diff --git a/specs/epics/FIX-1815/BUSINESS-RULES.md b/specs/epics/FIX-1815/BUSINESS-RULES.md index 6016d83d61..01384045f6 100644 --- a/specs/epics/FIX-1815/BUSINESS-RULES.md +++ b/specs/epics/FIX-1815/BUSINESS-RULES.md @@ -12,8 +12,9 @@ checks them. Each names its owner and where it is checked. | ER-1 | An ask returns the asked worker's real answer inside the asker's turn, across a restart, and the asked worker runs once | FIX-1816 | FIX-1820's leg a and both controls | | ER-2 | An answered park resumes the same task session, which keeps what it did before it parked | FIX-1817 | FIX-1820's leg b | | ER-3 | A finished task's session answers a follow-up question from its history and accepts a follow-up task. It never locks. The finished row still declines writes (FIX-1794's leg e); a follow-up task is a new row bound to the same session | FIX-1817, with FIX-1765 on what a reply does | FIX-1820's leg b · FIX-1817's spec review | -| ER-4 | Every ask has a timeout and a depth cap, and a cancel of the asker reaches the asked worker ([D3](DECISIONS.md#d3)) | FIX-1816 | FIX-1816's tests · FIX-1820's gap sweep with a mutual ask | -| ER-5 | Dispatch stays fire-and-forget by default; ask is a separate, opt-in call ([D4](DECISIONS.md#d4)) | FIX-1816 decides · FIX-1817 consumes | Both specs' review | +| ER-4 | Every ask has a timeout and a depth cap, and a cancel of the asker reaches the asked worker ([D3](DECISIONS.md#d3)). The cap is depth 1, by construction; the timeout is fixed (L7) | FIX-1816 | FIX-1816's tests · FIX-1820's gap sweep with a stalled ask: it resumes with a timeout error, and a cancel of the asker reaches the asked task (L7) | +| ER-5 | Dispatch stays fire-and-forget by default; ask is an opt-in option, `addTask`'s `waitForResponse` (L5, [D4](DECISIONS.md#d4)) | FIX-1816 decides · FIX-1817 consumes | Both specs' review | +| ER-22 | An asked task gets no `parkOnQuestion` in v1. The colleague you asked answers with what it has, or fails; it cannot stop on a question back to the asker ([the cross-spec pass](DECISIONS.md#decided-in-the-cross-spec-pass)) | FIX-1817, with FIX-1816 mirroring it | FIX-1817's tests: an asked row's turn is offered no `parkOnQuestion` · FIX-1816's spec states it | ## What no child may do @@ -24,8 +25,8 @@ checks them. Each names its owner and where it is checked. | ER-8 | Hold a request open while it waits | [D1](DECISIONS.md#d1) | | ER-9 | Merge ask and assign into one kind | The product owner, 2026-10-08 | | ER-10 | Restore skill `agents:` in any form, including a skill's private team | FIX-1814 removed it; Not doing | -| ER-11 | Add a Layer 1 change outside [D5](DECISIONS.md#d5)'s nine, or any new public route | D5. It comes to this epic first | -| ER-12 | Change a FIX-1786 child's spec or code: FIX-1791, FIX-1792, FIX-1793, FIX-1794, FIX-1796, FIX-1797, FIX-1802, FIX-1814. A need goes to that epic as a comment. The one agreed exception: FIX-1816's lift re-points FIX-1794's S6 and S7 at the moved module ([Q2](DECISIONS.md#q2)) | Another session owns them | +| ER-11 | Add a Layer 1 change outside [D5](DECISIONS.md#d5)'s list, or any new public route | D5. It comes to this epic first | +| ER-12 | Change a FIX-1786 child's spec or code: FIX-1791, FIX-1792, FIX-1793, FIX-1794, FIX-1796, FIX-1797, FIX-1802, FIX-1814. A need goes to that epic as a comment. Two agreed exceptions: FIX-1816's lift re-points FIX-1794's S6 and S7 at the moved module ([Q2](DECISIONS.md#q2)); and FIX-1817's L9 rows change FIX-1794 code, its S5 `work` entry, S6 session key and S7 capability ([the cross-spec pass](DECISIONS.md#decided-in-the-cross-spec-pass)). Where both touch S6's task entry, FIX-1817 lands after FIX-1816 P3 and rebases onto it | Another session owns them. FIX-1786's coordinator is told of both before FIX-1794 P2 merges (ER-21) | | ER-13 | Build the Shift Manager composer for finished tasks | FIX-1764 and epic FIX-1765 own it | ## How the set is run @@ -33,11 +34,11 @@ checks them. Each names its owner and where it is checked. | # | Rule | Because | |---|---|---| | ER-14 | What a reply to a finished task does (a note, a follow-up task, or a reopen) is settled in FIX-1817's spec together with epic FIX-1765, not alone | Both epics answer the same question | -| ER-15 | The inputs land in this order, each on the product owner's merge, with no dates: FIX-1814, then FIX-1794 P2, then FIX-1802 P1. FIX-1817's build starts only after FIX-1802 merges on `main`. FIX-1816's lift of the child-finished signal (L4) starts only after FIX-1794 P2 merges; its other rows, L3 among them, do not wait | [Q2](DECISIONS.md#q2), decided 2026-10-08 | +| ER-15 | The inputs land in this order, each on the product owner's merge, with no dates: FIX-1814, then FIX-1794 P2, then FIX-1802 P1. FIX-1817's build starts only after FIX-1802 merges on `main`. FIX-1816's lift of the child-finished signal (L4) starts only after FIX-1794 P2 merges; its other rows, L3 among them, do not wait. Where FIX-1817 touches FIX-1794's S6 task entry, it lands after FIX-1816 P3 (ER-12) | [Q2](DECISIONS.md#q2), decided 2026-10-08 | | ER-16 | The epic finishes only when FIX-1820 closes: a clean run on one `main` commit, every bug an earlier run found fixed as a child of this epic and retested | The closure rule | | ER-17 | FIX-1816's spec, before its gate, names the caller the kill line asks for, or the set stops after it and ships assign alone | The kill line | | ER-18 | FIX-1816's spec decides FIX-1537's fate; one of the two closes as a duplicate. Nothing re-parents FIX-1537 out of FIX-1312 | FIX-1537 is FIX-1312's child | -| ER-21 | FIX-1816's spec sends `fix-1786-pm` the shape of the child-finished signal's seam before FIX-1794 P2 starts. If FIX-1817 changes what a park writes on the row, it tells `fix-1786-pm` before FIX-1794 P2 merges | [Q2](DECISIONS.md#q2): the module is built there and moved here, so both sides agree its shape first | +| ER-21 | FIX-1816's spec sends `fix-1786-pm` the shape of the child-finished signal's seam before FIX-1794 P2 starts. If FIX-1817 changes what a park writes on the row, or FIX-1794 code under L9 (ER-12), it tells `fix-1786-pm` before FIX-1794 P2 merges | [Q2](DECISIONS.md#q2): the module is built there and moved here, so both sides agree its shape first | ## The closure diff --git a/specs/epics/FIX-1815/DECISIONS.md b/specs/epics/FIX-1815/DECISIONS.md index f052c15058..8dcbe9f70b 100644 --- a/specs/epics/FIX-1815/DECISIONS.md +++ b/specs/epics/FIX-1815/DECISIONS.md @@ -5,7 +5,11 @@ The calls that sit above either child. None is open. Q1 was the product owner's, answered on 2026-10-08. Q2 was decided on 2026-10-08 by the two epics' coordinators, to whom the product owner delegated it. Q3 was an engineering call the coordinator absorbed on 2026-10-08. Five are engineering calls I made as EM (D1 to D5); they are recorded so no child -reopens them. +reopens them. The product owner's approval of the FIX-1816 and FIX-1817 specs on 2026-10-08 changed +D5's rows; they are recorded in [D5 amendments from the child specs](#d5-amendments-from-the-child-specs), +with the product owner's call on a FIX-1794 P2 slip. The cross-spec pass of the two specs, which +the product owner authorized on 2026-10-08, settled four more points, recorded +[below](#decided-in-the-cross-spec-pass). ## The tree @@ -19,7 +23,7 @@ flowchart TD D1 -.->|"rejected"| X3["hold the request open"] E --> D2["D2 · one of each shared part"] D2 -.->|"rejected"| X4["a copy per kind"] - E --> D5["D5 · nine Layer 1 changes, listed"] + E --> D5["D5 · Layer 1 changes, listed · L6 dropped"] ``` Q3, D3 and D4 have no rejected sibling worth a node: their cards name what lost. @@ -95,8 +99,8 @@ a note of the second kind (FIX-1802's settle-owed marker, its BR-17). Neither is **What it settles.** The gap the recommendation left open, that FIX-1794's `onTaskSettled` was a Workforce entry an ask below Workforce could not hear, closes by the lift, not by a second copy. FIX-1802's marker and FIX-1794 BR-25 stay as specified. FIX-1794 P2 builds S6 and S7 -layer-clean, as the coordinators agreed, and the lift's re-pointing of them is the one agreed touch -of FIX-1794's code ([ER-12](BUSINESS-RULES.md#what-no-child-may-do), [ER-21](BUSINESS-RULES.md#how-the-set-is-run)). +layer-clean, as the coordinators agreed, and the lift's re-pointing of them is one of two agreed +touches of FIX-1794's code; FIX-1817's L9 rows are the other ([ER-12](BUSINESS-RULES.md#what-no-child-may-do), [ER-21](BUSINESS-RULES.md#how-the-set-is-run)). **What it costs.** Two owed markers share one pattern, so a change to the pattern is made in both. FIX-1816 carries the lift, which lands only after FIX-1794 P2 merges. @@ -161,7 +165,7 @@ It comes down to ownership: a reopen or a new issue gives the signal two owners. |---|---| | **Instead of** | An ask that may wait without limit | | **Because** | A asks B while B asks A, and both wait forever. Nothing today carries a cancel from a parent to its child; `dispatch-and-execute.ts` combines only the request signal and lease loss | -| **Locks in** | A mandatory timeout and a depth cap on every ask, and a cancel of the asker that reaches the asked child. The values are FIX-1816's | +| **Locks in** | A mandatory timeout and a depth cap on every ask, and a cancel of the asker that reaches the asked child. As FIX-1816 settled them: the depth cap holds by construction at depth 1, since a turn working a task row cannot ask, and the timeout is fixed, fired by the durability sweeper's expiry step within 10 to 20 minutes (L7) | ## D4 · Dispatch stays fire-and-forget by default @@ -170,35 +174,36 @@ It comes down to ownership: a reopen or a new issue gives the signal two owners. |---|---| | **Instead of** | Making every dispatch wait | | **Because** | A dispatch on `main` returns before the dispatched work runs, and its callers are written for that. A default that waits changes all of them | -| **Locks in** | Ask is a separate, opt-in call | +| **Locks in** | Ask is an opt-in option on the call, `addTask`'s `waitForResponse` (L5); without it a hand-off is fire-and-forget | -## D5 · The set's Layer 1 changes are these nine +## D5 · The set's Layer 1 changes are these, L6 dropped | | | |---|---| | **Instead of** | Each child finding its Layer 1 changes during its build | | **Because** | This is framework work. A change to a persisted format or a public export outlives the epic, so each one is named, owned and proved before a child builds it | -| **Locks in** | A child that needs a tenth comes up to this epic first ([ER-11](BUSINESS-RULES.md#what-no-child-may-do)) | +| **Locks in** | A child that needs another comes up to this epic first ([ER-11](BUSINESS-RULES.md#what-no-child-may-do)). The rows keep their numbers; L6 is dropped, not renumbered | | # | Change | Area | Owner | Critical | Proved by · red state | |---|---|---|---|---|---| | L1 | Server-side resume of a turn parked on a task or internal source | `engine` · beside `routes/resume-routes.ts`; `public-reentry.ts` unchanged | FIX-1816 | New internal verb at an authorization boundary (BP-031); **no new public route** | Resumes a parked task-source turn; the public route still answers not-found. Red: nothing can resume it today | -| L2 | A wait binding: the parked turn names the request it waits on | `core` · `generator-resume.ts`; `engine` execution | FIX-1816 | **Persisted** in the item log | Leg a's restart. Red: after a restart the turn cannot find what it waited on | +| L2 | A wait binding: the parked turn names the task row it waits on (L5) | `core` · `generator-resume.ts`; `engine` execution | FIX-1816 | **Persisted** in the item log | Leg a's restart. Red: after a restart the turn cannot find what it waited on | | L3 | A durable resume-owed marker on FIX-1802's settle-owed pattern (BR-17): written in the write that ends the turn, cleared only by what it owes, replayed on any board touch. FIX-1802's own marker is unchanged | `orchestration` · board rows | FIX-1816 ([Q2](#q2)) | **Persisted** | Leg a's waker control must FAIL | | L4 | The child-finished signal FIX-1780 promised: FIX-1794 P2 builds it (S6, S7) as one layer-clean module; FIX-1816 lifts it into `orchestration` and re-points S6 and S7 at it | `orchestration` board gate, after the lift; `workforce` `onTaskSettled` | FIX-1794 P2 builds · FIX-1816 lifts ([Q2](#q2)) | **Public** entry name | FIX-1794's V5, before and after the lift; leg a consumes it | -| L5 | `awaitDispatch`: dispatch once under `ctx.runOnce`, then read `resultOf(requestId)` | `core` context; `engine` read | FIX-1816 | **Public export** and a new read verb | Leg a's `runOnce` control must FAIL: B runs twice | -| L6 | A board worker that asks parks its own row; its lease does not lapse into a second claim | `orchestration` · `dispatch-and-execute.ts`, lease renewal | FIX-1816 | **Persisted** row state | An asking worker past its lease is not re-claimed. Red: today a second worker claims it | -| L7 | A timeout and a depth cap on each ask; a cancel reaches the asked child (D3) | `core`, `engine`; `orchestration` cascade | FIX-1816 | **Persisted** deadline | A asks B, B asks A: both end at the timeout. Red: both wait forever | -| L8 | A test-harness dispatch seam with a durable in-memory runtime that survives a simulated restart | `@flow-state-dev/testing` | FIX-1816 | **Public export** | L1, L2 and L5 to L7's tests run on it. Red: today's harness drops the wait on restart | -| L9 | An answered park resumes the same task session; a finished session takes a follow-up question, and a follow-up task as a new row bound to it | `orchestration` park path; `workforce` task entry | FIX-1817 | **Persisted**: a row keeps its session after it ends | Leg b. Red: FIX-1794 BR-25's answer has no path back | +| L5 | An ask is a task on the asker's own board: `addTask` with a `waitForResponse` option. No new tool, no new core export, no `awaitDispatch` or `resultOf`. `waitForResponse` adds no tool | `orchestration` · `addTask` | FIX-1816 (its D1) | **Public**: one option on an existing tool | Leg a's `runOnce` control must FAIL: B runs twice | +| ~~L6~~ | **Dropped.** There are no nested asks: a turn that is itself working a task row cannot wait, so no asking worker parks its own row | — | — | — | — | +| L7 | A timeout and a depth cap on each ask; a cancel reaches the asked child (D3). The depth half holds by construction, at depth 1. The timeout is fixed and fires from the durability sweeper's expiry step, within 10 to 20 minutes | `engine` sweeper expiry; `orchestration` cascade | FIX-1816 | **Persisted** deadline | An ask past its deadline resumes with a timeout error. Red: it waits forever | +| L8 | A test-harness dispatch seam with a durable in-memory runtime that survives a simulated restart | `@flow-state-dev/testing` | FIX-1816 | **Public export** | L1, L2, L5 and L7's tests run on it. Red: today's harness drops the wait on restart | +| L9 | An answered park resumes the same task session; a finished session takes a follow-up question, and a follow-up task as a new row bound to it. `answerTask` joins the task tools, and `addTask.followUpOf` binds a follow-up to the root task's session; a follow-up is refused while that session has an unfinished task. `parkOnQuestion`, a new model-visible tool, parks an assigned task on its question; an asked task is not offered it (ER-22). A person's message keeps the shipped `allow` concurrency | `orchestration` park path and task tools; `workforce` task entry, which changes FIX-1794's S5 `work` entry, S6 session key and S7 capability (ER-12) | FIX-1817 | **Persisted**: a row keeps its session after it ends, and `turnReentries` now counts question re-entries as well as person turns. **Public**: two new tools, `answerTask` and `parkOnQuestion`, and one `addTask` option | Leg b. Red: FIX-1794 BR-25's answer has no path back | L9 keeps FIX-1794's rule that a finished task declines writes (its goal leg e): a follow-up task -is a new row, not a write to the old one. +is a new row, not a write to the old one. L5 adds no tool. L9's `answerTask` and `parkOnQuestion` +are the two the set adds, and a turn still carries one set of task tools. ## Who owns what -![Who owns what: eight cross-cutting rules by five columns, FIX-1816, FIX-1817, the closure, FIX-1786 and FIX-1765; each rule has one builder; FIX-1786 builds the child-finished signal and FIX-1816 lifts it, and FIX-1786 owns the owed-marker pattern that FIX-1816 reuses](figures/ownership.svg) +![Who owns what: nine cross-cutting rules by five columns, FIX-1816, FIX-1817, the closure, FIX-1786 and FIX-1765; each rule has one builder; FIX-1786 builds the child-finished signal and FIX-1816 lifts it, and FIX-1786 owns the owed-marker pattern that FIX-1816 reuses](figures/ownership.svg) Read a row: one cell builds or decides, the others consume, lift, reuse or prove. The two rows [Q2](#q2) settled each have FIX-1786 as builder: the signal, which FIX-1816 moves once, and the @@ -214,6 +219,50 @@ owed-marker pattern, which FIX-1816 reuses for its own resume-owed marker (L3). `sessionId` and `lineageId`, no request id. FIX-1659 is about a reassign that leaves a claim in place, not cancellation reaching children. +## D5 amendments from the child specs + +The product owner approved FIX-1816's spec at #2900 (head `964ecb69`) and FIX-1817's at #2899 +(head `163730d8`) in session on 2026-10-08. Each carried changes to this epic's rows, recorded +here as decided: + +- **L5, reshaped** (FIX-1816 D1). An ask is a task on the asker's own board, `addTask` with + `waitForResponse`. The product owner's reason: ask and add both add a task. +- **L6, dropped.** No nested asks; a turn working a task row cannot wait. +- **L7's depth half** holds by construction, at depth 1. The timeout is fixed and fires from the + durability sweeper's expiry step, within 10 to 20 minutes. +- **ER-5** reads "an opt-in option"; [D4](#d4)'s fire-and-forget default is unchanged. +- **L9** (FIX-1817) adds `answerTask`, a new task tool, and `addTask.followUpOf`. +- **If FIX-1794 P2 slips, ask waits with it. Decided by the product owner**, 2026-10-08. No + stop-gap waker is built: it would be the second child-finished signal + [ER-7](BUSINESS-RULES.md#what-no-child-may-do) forbids, and the lift would tear it out. The cost + is that ask's goal slips one for one with P2 ([PLAN](PLAN.md#what-unblocks-what-from-here)). + +## Decided in the cross-spec pass + +The product owner authorized a cross-spec pass of FIX-1816's and FIX-1817's approved specs on +2026-10-08. It found four points where the two specs, or this epic's rows, did not yet agree. +Recorded here as decided: + +1. **An asked task gets no `parkOnQuestion` in v1.** A coordinator decision, an engineering call + the product owner can overrule. A colleague you asked answers with what it has, or fails; it + cannot stop on a question back to the asker. *Rejected:* letting it park. A question parked + inside an ask would sit until the ask's timeout fired, silently, 10 to 20 minutes later (L7), + and the asker would see only a timeout. *Cost:* an asked worker that needs a fact it lacks + must fail and say so; the asker can assign the work instead. Epic rule + [ER-22](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt), owned by FIX-1817, mirrored by + FIX-1816. +2. **A second agreed touch of FIX-1794's code** ([ER-12](BUSINESS-RULES.md#what-no-child-may-do)). + FIX-1817's L9 rows change FIX-1794's S5 `work` entry, S6 session key and S7 capability. Where + FIX-1816's lift and FIX-1817 both touch S6's task entry, FIX-1817 lands after FIX-1816 P3 and + rebases onto it. `fix-1786-pm` is told before FIX-1794 P2 merges + ([ER-21](BUSINESS-RULES.md#how-the-set-is-run)). +3. **L9 adds `parkOnQuestion`**, a new model-visible tool, beside `answerTask`. The persisted + `turnReentries` now counts question re-entries as well as person turns ([D5](#d5)). +4. **One set of task tools per turn, not a count.** The intent is one set of task tools on each + turn. FIX-1816's check becomes "`waitForResponse` adds no tool", not a literal eight. + FIX-1786's ER-32 says "each of the eight task tools"; that literal is raised with + `fix-1786-pm` as an amendment request, since ER-12 keeps this epic out of FIX-1786's specs. + ## What the end-state POC showed None built. The spike was read-only, and the two kinds touch different callers, so a POC is the @@ -232,4 +281,14 @@ first move inside FIX-1816's spec, not here. - **Merged (Oct 8)**: #2891, by the product owner. - **Q1 and Q3 decided (Oct 8)**: Q1 by the product owner, in session: FIX-1818 and FIX-1819 cut. Q3 as an engineering call by the coordinator under epic-pm: FIX-1780 stays Done with a - correcting comment and a relation to FIX-1794. Recorded by a follow-up PR from `main`. + correcting comment and a relation to FIX-1794. Recorded by a follow-up PR from `main` (#2893). +- **Child specs approved (Oct 8)**: FIX-1816 (#2900) and FIX-1817 (#2899), by the product + owner, in session. Their changes to L5, L6, L7, L9 and ER-5, and the product owner's call that + ask waits on a FIX-1794 P2 slip, recorded in + [D5 amendments from the child specs](#d5-amendments-from-the-child-specs) by a second follow-up + PR from `main` (#2904). +- **Cross-spec pass (Oct 8)**: authorized by the product owner. An asked task gets no + `parkOnQuestion` (ER-22, a coordinator call the product owner can overrule); FIX-1817's L9 is a + second agreed touch of FIX-1794's code (ER-12); L9 adds `parkOnQuestion` and widens + `turnReentries`; the tool check is one set per turn, with FIX-1786's ER-32 raised as an + amendment request. Recorded in [Decided in the cross-spec pass](#decided-in-the-cross-spec-pass), same PR. diff --git a/specs/epics/FIX-1815/DOCS.md b/specs/epics/FIX-1815/DOCS.md index 291c226522..177edf2cdc 100644 --- a/specs/epics/FIX-1815/DOCS.md +++ b/specs/epics/FIX-1815/DOCS.md @@ -7,20 +7,24 @@ text; names in `code` are working names until FIX-1816's spec fixes them. ## UPDATE · `apps/docs/docs/server/background-work.md` · new section after "Starting a job on another flow" +Ask's limits and names are canonical in [FIX-1816's `DOCS.md`](https://github.com/fixpoint-labs/flow-state-dev/blob/main/specs/issues/FIX-1816/DOCS.md); +the timeout sentence below matches it, and any other number defers to it. + > ### Waiting for the answer > > A dispatch returns before the work it started has run. That is right for a job that outlives -> the turn, and wrong when the next step needs the result. For that case, ask instead of -> dispatching. +> the turn, and wrong when the next step needs the result. For that case, add the work as a task +> and wait for its answer: that is an ask. > -> An ask starts the work the same way, then parks the turn on it. When the answer arrives, the +> An ask files the task on the worker's own board, then parks the turn on it. When the answer arrives, the > turn picks up where it stopped, with the answer as the tool's result. Nothing holds the request > open in between, so a server restart while the turn waits loses nothing: the turn resumes after > the restart, and the asked work ran once. > -> Every ask has a time limit and a limit on how deep asks can nest. If two workers ask each -> other, both get a timeout error instead of waiting forever. Cancelling the turn that asked also -> cancels the work it is waiting on. +> Every ask has a time limit: a turn whose answer never came resumes with a timeout error within +> twenty minutes, instead of waiting forever. A turn that is itself working a task can't ask, so +> asks never nest. The worker you asked answers with what it has, or fails; it can't stop on a +> question back to you. Cancelling the turn that asked also cancels the work it is waiting on. > > Each wake replays the asking turn once, so an ask costs one extra replay. Use one when the > answer changes what this turn does next. When it doesn't, dispatch the work, or assign it as a diff --git a/specs/epics/FIX-1815/EVOLUTION.md b/specs/epics/FIX-1815/EVOLUTION.md index 51a0394d17..0ff4eb9adb 100644 --- a/specs/epics/FIX-1815/EVOLUTION.md +++ b/specs/epics/FIX-1815/EVOLUTION.md @@ -6,7 +6,7 @@ Only lineage that spans both children. Each child's own evolution record carries | Prior intent and precise source | Treatment | Reason / evidence | Replacement | Compatibility | |---|---|---|---|---| -| FIX-1537, a Backlog stub (2026-09-23) for `dispatchAndWait` under FIX-1312's reverse dispatch, gated on FIX-1312 and FIX-1171; Linear only, no retained spec | **Undecided**: FIX-1816's spec decides which framing stands (ER-18) | Ask reads the request id the dispatch returns (L5), so it may not need FIX-1312's reverse reply at all. FIX-1312's `from` stamp carries no request id (`engine/src/execution/dispatch-metadata.ts`) | FIX-1816, or FIX-1537 under it | One of the two closes as a duplicate. FIX-1537 stays FIX-1312's child | +| FIX-1537, a Backlog stub (2026-09-23) for `dispatchAndWait` under FIX-1312's reverse dispatch, gated on FIX-1312 and FIX-1171; Linear only, no retained spec | **Superseded**: closes as a duplicate of FIX-1816, decided in FIX-1816's approved spec (#2900, 2026-10-08) under ER-18 | Ask is a task on the asker's own board, woken by the board's notice (L5), so it needs no reverse reply carrying a request id. FIX-1312's `from` stamp carries none (`engine/src/execution/dispatch-metadata.ts`) | FIX-1816 | FIX-1537 is marked Duplicate in Linear and stays FIX-1312's child | | FIX-1230 and FIX-1231, earlier attempts at the same capability; Linear only, Canceled | **Superseded** | Cancelled before any design was retained | FIX-1816 | None | | FIX-1780's `onTaskSettled`, S1 to S5; its PRs #2758 and #2761 | **Retained** as the signal ask and assign wake on, built by FIX-1794 P2 and lifted into `orchestration` by FIX-1816 (Q2) | Only S5a shipped (#2761). [FIX-1794's evolution record](../../issues/FIX-1794/EVOLUTION.md) carries S1 to S5 to its S6 and S7. FIX-1780 stays Done in Linear, with a correcting comment and a relation to FIX-1794 ([Q3](DECISIONS.md#q3), decided 2026-10-08) | D2's one child-finished signal, L4 | None. The entry name is the one FIX-1780 pinned | | FIX-1794 BR-25, a parked task answered later gives a second `completed` notice; [source](../../issues/FIX-1794/BUSINESS-RULES.md) | **Amended** by FIX-1817 | BR-25 says the task completes, not which session the answer wakes. FIX-1794 BR-17 re-enters the same session only on a second attempt | ER-2: the answer wakes the same task session | FIX-1794's notices unchanged; ER-12 forbids editing its spec here | @@ -14,6 +14,10 @@ Only lineage that spans both children. Each child's own evolution record carries | FIX-1802 BR-15 to BR-17, a piece's notice wakes the task session and a settle-owed marker replays "run my board"; [source](../../issues/FIX-1802/BUSINESS-RULES.md) | **Retained**, its pattern reused | The settle-owed marker starts a new turn and stays as specified. Ask resumes a parked turn, so it reuses the pattern with its own marker. Spec-only on `main` | D2's one owed-marker pattern; FIX-1816's resume-owed marker, L3 | The pattern is shared, the marker is not (ER-7, Q2) | | FIX-1791's delivery ledger, a token the answer hands back, claimed once; `packages/workforce/src/delivery-ledger.ts` | **Retained** | One of the two existing answer-once checks ask may ride (ER-6) | — | Whether "ask the delegate" becomes an ask, and so the token goes, is FIX-1816's call | | FIX-1818, one answer-once fence, and FIX-1819, skill helpers; children as filed, Linear only | **Superseded** by Q1, the product owner, 2026-10-08 | Neither moves the goal. FIX-1818 is Canceled; FIX-1819 is in Backlog, unparented, still blocked by FIX-1816 | ER-6 for FIX-1818; FIX-1816's spec for its "ask the delegate" and ledger-token question | FIX-1819 is revisited after ask ships | +| This epic's D5 L5, `awaitDispatch` then `resultOf(requestId)`, as merged in #2891 | **Amended** by FIX-1816 D1, approved by the product owner 2026-10-08 (#2900 at `964ecb69`) | A request-level wait would add a second child-finished signal and a third answer-once check (ER-6, ER-7). The product owner: ask and add both add a task | L5: `addTask` with `waitForResponse`; no new tool or core export. The check is "`waitForResponse` adds no tool", not a count of eight (the cross-spec pass) | ER-5 now reads "an opt-in option"; D4's fire-and-forget default unchanged | +| This epic's D5 L6, an asking board worker parks its own row, as merged in #2891 | **Superseded**: dropped by FIX-1816, approved 2026-10-08 | A turn that is itself working a task row cannot wait, so asks never nest and no asker row needs lease rules | None; L6 keeps its number, marked dropped | None. Nothing was built | +| This epic's D5 L7, a timeout and a depth cap with values left to FIX-1816, as merged in #2891 | **Amended** by FIX-1816, approved 2026-10-08 | Depth 1 by construction once L6 is dropped. The timeout fires from the durability sweeper's expiry step, within 10 to 20 minutes | L7: depth 1, a fixed timeout; the cancel half unchanged | ER-4 and D3 restate it | +| This epic's D5 L9, as merged in #2891 | **Amended** by FIX-1817, approved by the product owner 2026-10-08 (#2899 at `163730d8`) | A follow-up needs a way into the root task's session, and the engine runs a session's turns concurrently by default (`allow`) | L9 adds `answerTask` and `addTask.followUpOf`; a follow-up is refused while the session has an unfinished task. The cross-spec pass adds `parkOnQuestion`, which an asked task is not offered (ER-22), widens `turnReentries` to count question re-entries, and records L9's changes to FIX-1794's S5 to S7 as an agreed exception (ER-12) | A person's message keeps the shipped `allow` concurrency | | FIX-1814, removing skill `agents:` | **Retained** | The product owner: half-built, no clear agent concept | ER-10 | No skill helper in this epic | Re-check each cited intention against current code before implementing: retained specs are diff --git a/specs/epics/FIX-1815/PLAN.md b/specs/epics/FIX-1815/PLAN.md index 3b64afa358..50efd8cbac 100644 --- a/specs/epics/FIX-1815/PLAN.md +++ b/specs/epics/FIX-1815/PLAN.md @@ -8,7 +8,7 @@ any piece; that is each issue's own plan. IDs cross-reference [DECISIONS.md](DEC ## The path -![The path in phases, not dates, as of 8 October 2026. Two input lanes from FIX-1786, landing in order: FIX-1794 P2 after FIX-1814, then FIX-1802 P1 after FIX-1794 P2. This spec is in review at the now line. After the gate, the ask and assign specs run at once, with the closure's QA plan. Ask builds its own pieces, its resume-owed marker among them, without waiting, and lifts the child-finished signal once FIX-1794 P2 merges; assign builds only after FIX-1802 merges. The closure run follows both. FIX-1818 and FIX-1819, cut by Q1, have no lane. The critical path runs through FIX-1814, FIX-1794 P2, FIX-1802 P1, assign's build and the closure run](figures/path.svg) +![The path in phases, not dates, as of 8 October 2026. Two input lanes from FIX-1786, landing in order: FIX-1794 P2 after FIX-1814, then FIX-1802 P1 after FIX-1794 P2. This spec is in review at the now line. After the gate, the ask and assign specs run at once, with the closure's QA plan. Ask builds its own pieces, its resume-owed marker among them, without waiting, and lifts the child-finished signal and goes live once FIX-1794 P2 merges, waiting with it if P2 slips; assign builds only after FIX-1802 merges. The closure run follows both. FIX-1818 and FIX-1819, cut by Q1, have no lane. The critical path runs through FIX-1814, FIX-1794 P2, FIX-1802 P1, assign's build and the closure run](figures/path.svg) The axis is order, not dates: nothing has started. Both specs run at once after the gate. The critical path goes through FIX-1786's inputs, landing FIX-1814, then FIX-1794 P2, then FIX-1802 @@ -18,8 +18,8 @@ P1, not through any work in this epic ([Q2](DECISIONS.md#q2), [ER-15](BUSINESS-R | Issue | Route | Consumes | Delivers | Releases | Size | |---|---|---|---|---|---| -| **FIX-1816** ask | spec → impl PRs | Generator suspend and resume (`generator-resume.ts`) · `ctx.runOnce` · FIX-1794 P2's notice module, to lift (L4) · FIX-1802's settle-owed pattern (L3) · an existing answer-once check (ER-6) | L1 to L3, L5 to L8; the lift of L4 into `orchestration`; the seam's shape to `fix-1786-pm` (ER-21); the answers to the kill line (ER-17), "ask the delegate", and FIX-1537 (ER-18) | FIX-1817's use of the resume verb · the closure's leg a | Large: a Layer 1 seam across four packages | -| **FIX-1817** assign stays open | spec → impl PR | FIX-1794 P2's `parked` notice and session binding · FIX-1802's "run my board" replay · FIX-1816's resume verb where it applies | L9 · the reply semantics with FIX-1765 (ER-14) · word to `fix-1786-pm` if a park's row write changes (ER-21) | The closure's leg b | Medium | +| **FIX-1816** ask | spec → impl PRs | Generator suspend and resume (`generator-resume.ts`) · `ctx.runOnce` · FIX-1794 P2's notice module, to lift (L4) · FIX-1802's settle-owed pattern (L3) · an existing answer-once check (ER-6) | L1 to L3, L5, L7, L8; the lift of L4 into `orchestration`; the seam's shape to `fix-1786-pm` (ER-21); the answers to the kill line (ER-17), "ask the delegate", and FIX-1537 (ER-18) | FIX-1817's use of the resume verb · the closure's leg a | Large: a Layer 1 seam across four packages | +| **FIX-1817** assign stays open | spec → impl PR | FIX-1794 P2's `parked` notice and session binding · FIX-1802's "run my board" replay · FIX-1816's resume verb where it applies | L9, with `answerTask`, `parkOnQuestion` and `addTask.followUpOf`, and its changes to FIX-1794's S5 to S7 (ER-12) · no `parkOnQuestion` for an asked task (ER-22) · the reply semantics with FIX-1765 (ER-14) · word to `fix-1786-pm` before FIX-1794 P2 merges if a park's row write or FIX-1794 code changes (ER-21) | The closure's leg b | Medium | | **FIX-1820** closure · required | spec (the QA plan) → runs until one is clean → PR | Every other child merged, on one `main` commit | The goal fixture under `goals/` on a durable store · a QA report · a bug child per failure | The wrap | Medium, and repeats per retest | ## Where it is @@ -40,11 +40,16 @@ carried out: FIX-1818 is Canceled and FIX-1819 is in Backlog, unparented, outsid 1. **This spec is approved and merged** → the FIX-1816 and FIX-1817 specs start together, and FIX-1820's QA plan beside them. 2. **FIX-1816's spec is approved** → if it names no caller, the kill line fires: FIX-1816 stops, - and the set is FIX-1817 and the closure. Otherwise FIX-1816 builds L1 to L3 and L5 to L8. Its + and the set is FIX-1817 and the closure. Otherwise FIX-1816 builds L1 to L3, L5, L7 and L8, + though ask is offered to models only once FIX-1794 P2 has merged. Its spec has already sent `fix-1786-pm` the signal seam's shape, before FIX-1794 P2 starts (ER-21). 3. **FIX-1794 P2 merges on `main`** → FIX-1816 lifts the child-finished signal into - `orchestration` and re-points S6 and S7 at it (L4, ER-15). FIX-1802 P1 starts. -4. **FIX-1802 merges on `main`** → FIX-1817's build starts (ER-15). + `orchestration` and re-points S6 and S7 at it (L4, ER-15), and ask goes live. FIX-1802 P1 + starts. **If P2 slips, ask waits with it**, the product owner's decision of 2026-10-08: no + stop-gap waker is built ([ER-7](BUSINESS-RULES.md#what-no-child-may-do), + [DECISIONS](DECISIONS.md#d5-amendments-from-the-child-specs)). +4. **FIX-1802 merges on `main`** → FIX-1817's build starts (ER-15). Where it touches FIX-1794's + S6 task entry, it lands after FIX-1816 P3 and rebases onto it (ER-12). 5. **FIX-1816 and FIX-1817 merge** → the closure's first run. 6. **A closure run finds bugs** → each one becomes a child of this epic that blocks FIX-1820, and the whole plan runs again on a fresh `main` commit. @@ -56,6 +61,8 @@ carried out: FIX-1818 is Canceled and FIX-1819 is in Backlog, unparented, outsid | The resume verb | FIX-1816 builds it · FIX-1817 may use it for an answered park | One verb. FIX-1817 does not add a second path into a parked session | | The board row's markers | FIX-1816 · FIX-1817 · FIX-1802 | One pattern (ER-7): FIX-1802's settle-owed starts a new turn and stays unchanged; FIX-1816's resume-owed resumes a parked one. A change to the pattern is made in both | | The child-finished signal module | FIX-1794 P2 builds it · FIX-1816 lifts it | Layer-clean as built; moved once, S6 and S7 re-pointed, no copy. Its shape is agreed with `fix-1786-pm` before P2 starts (ER-21) | +| FIX-1794's S6 task entry | FIX-1816's lift (its P3) · FIX-1817's L9 | FIX-1817 lands after FIX-1816 P3 and rebases onto it (ER-12). `fix-1786-pm` hears of both touches before FIX-1794 P2 merges (ER-21) | +| An asked task's question | FIX-1817 owns it · FIX-1816 mirrors it | No `parkOnQuestion` on an asked row's turn (ER-22): it answers with what it has, or fails | | The `parked` notice | FIX-1794 P2 produces it · FIX-1817 consumes it | FIX-1817 does not change the notice (BR-25's `parked` then `completed` stay); it changes what the answer wakes. A change to what a park writes on the row goes to `fix-1786-pm` before P2 merges (ER-21) | | The finished task's session | FIX-1817 · FIX-1764 and FIX-1765 | ER-14: the reply semantics are settled together | | `escalate.ts` | FIX-1816's kill line · FIX-1792's conversion of its board | FIX-1816's spec reads it after FIX-1792's conversion, not before | diff --git a/specs/epics/FIX-1815/SPEC.md b/specs/epics/FIX-1815/SPEC.md index 9bfc614364..23cfda8bdd 100644 --- a/specs/epics/FIX-1815/SPEC.md +++ b/specs/epics/FIX-1815/SPEC.md @@ -94,8 +94,8 @@ A dated snapshot. Live state is Linear and the implementation PRs. Nothing has s | Issue | What it delivers | Why the set needs it | Status | |---|---|---|---| -| [FIX-1816](https://linear.app/fixpoint-labs/issue/FIX-1816) · ask | Park and resume: a turn waits on a dispatched worker and resumes with its answer, bounded by a timeout and a depth cap ([D5](DECISIONS.md#d5) rows L1 to L3, L5 to L8); lifts the child-finished signal into `orchestration` (L4) | Leg a. Its spec also decides "ask the delegate" and FIX-1537 | Todo · spec route, first | -| [FIX-1817](https://linear.app/fixpoint-labs/issue/FIX-1817) · assign stays open | An answered park resumes the same task session; a finished session answers and takes a follow-up task (L9) | Leg b | Todo · spec route · build waits on FIX-1802, which follows FIX-1794 P2 ([ER-15](BUSINESS-RULES.md#how-the-set-is-run)) | +| [FIX-1816](https://linear.app/fixpoint-labs/issue/FIX-1816) · ask | Park and resume: an ask is a task on the asker's own board, with `waitForResponse`; the turn resumes with its answer, bounded by a fixed timeout, depth 1 by construction ([D5](DECISIONS.md#d5) rows L1 to L3, L5, L7, L8); lifts the child-finished signal into `orchestration` (L4) | Leg a. Its spec also decides "ask the delegate" and FIX-1537 | Todo · spec route, first | +| [FIX-1817](https://linear.app/fixpoint-labs/issue/FIX-1817) · assign stays open | An answered park resumes the same task session; a finished session answers and takes a follow-up task (L9); an asked task cannot park on a question ([ER-22](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | Leg b | Todo · spec route · build waits on FIX-1802, which follows FIX-1794 P2 ([ER-15](BUSINESS-RULES.md#how-the-set-is-run)) | | [FIX-1820](https://linear.app/fixpoint-labs/issue/FIX-1820) · closure · **required** | The QA plan and the goal fixture, run on one `main` commit | Proves the whole | Backlog · blocked by every other child | Two children and a closure, after [Q1](DECISIONS.md#q1)'s cuts; FIX-1818 and FIX-1819 are under @@ -123,12 +123,12 @@ both specs run at once and settle the shared pieces together. ## What stays as it is -- **Dispatch stays fire-and-forget by default.** Ask is opt-in ([D4](DECISIONS.md#d4)). +- **Dispatch stays fire-and-forget by default.** Ask is an opt-in option on `addTask` ([D4](DECISIONS.md#d4)). - **The public resume, retry and continue routes** still refuse task and internal sources (`engine/src/routes/public-reentry.ts`). The new resume is server-side only. - **FIX-1786's children**, their specs and code, consumed as they ship ([ER-12](BUSINESS-RULES.md#what-no-child-may-do)). -- **FIX-1312's `from` stamp**, which carries the sender's session and no request id. Ask reads - the request id the dispatch returns, not the stamp. +- **FIX-1312's `from` stamp**, which carries the sender's session and no request id. Ask waits + on a task row on its own board, not on the stamp (L5). ## Sign off @@ -139,7 +139,9 @@ the reverse. Decided, for the record: [Q1](DECISIONS.md#q1), two issues and a closure, the product owner's answer on 2026-10-08 ("cut both"). [Q2](DECISIONS.md#q2), who builds the shared waking parts, settled by the two coordinators on 2026-10-08. [Q3](DECISIONS.md#q3), FIX-1780 stays Done with a -correcting comment, an engineering call on 2026-10-08. Engineering calls I made as EM: [D1](DECISIONS.md#d1) to [D5](DECISIONS.md#d5). +correcting comment, an engineering call on 2026-10-08. [The cross-spec pass](DECISIONS.md#decided-in-the-cross-spec-pass), +authorized by the product owner on 2026-10-08: no `parkOnQuestion` for an asked task (ER-22, a +coordinator call the product owner can overrule), and three consistency fixes. Engineering calls I made as EM: [D1](DECISIONS.md#d1) to [D5](DECISIONS.md#d5). Rules: [BUSINESS-RULES.md](BUSINESS-RULES.md). Order: [PLAN.md](PLAN.md). Epic · two children and a closure · Workforce: Shift Manager · diff --git a/specs/epics/FIX-1815/figures/end-state.svg b/specs/epics/FIX-1815/figures/end-state.svg index e45bbe73cb..2a405eb984 100644 --- a/specs/epics/FIX-1815/figures/end-state.svg +++ b/specs/epics/FIX-1815/figures/end-state.svg @@ -1,5 +1,5 @@ + aria-label="What's in the box. In the box, two kinds of hand-off. Ask, FIX-1816: a task on the asker's own board, addTask with waitForResponse; the turn parks on it and resumes with its real answer, across a restart, the asked worker running once, bounded by a fixed timeout, depth 1 with no nested asks, and a cancel that reaches the child. Assign stays open, FIX-1817: an answered park resumes the same task session; a finished session answers follow-up questions and takes a follow-up task, through answerTask and addTask's followUpOf. Under both, the Layer 1 seam: a server-side resume, a wait binding, the waitForResponse option on addTask with no new tool, a resume-owed marker, answerTask and parkOnQuestion as two new tools, with addTask's followUpOf, and a durable test runtime. Built once elsewhere and lifted or reused here: the child-finished notices from FIX-1794 P2, which ask lifts into orchestration, the settle-owed marker's pattern from FIX-1802, which ask's own marker reuses, and the board's claim ticket or FIX-1791's delivery ledger as the one answer-once check; generator suspend and resume already ships. The app's: which kind to use per call, and the Shift Manager composer, FIX-1764 and FIX-1765. Not built, below a fence: an untrusted external inbox, skill agents in any form, one merged kind, a request held open, parallel fan-in beyond one-at-a-time resume, nested asks, a third answer-once check."> diff --git a/specs/epics/FIX-1815/figures/ownership.svg b/specs/epics/FIX-1815/figures/ownership.svg index 2f10ab1b87..2c51a15f55 100644 --- a/specs/epics/FIX-1815/figures/ownership.svg +++ b/specs/epics/FIX-1815/figures/ownership.svg @@ -1,5 +1,5 @@ - + - + RULE · ER @@ -68,9 +68,13 @@ DECIDES consumes + An asked task cannot park on a question · ER-22 + mirrors + DECIDES + - ONE OWNER PER ROW - MUST NOT RE-DECIDE - CLOSURE PROVES IT + ONE OWNER PER ROW + MUST NOT RE-DECIDE + CLOSURE PROVES IT diff --git a/specs/epics/FIX-1815/figures/path.svg b/specs/epics/FIX-1815/figures/path.svg index cbdd66212d..eccd6dfa80 100644 --- a/specs/epics/FIX-1815/figures/path.svg +++ b/specs/epics/FIX-1815/figures/path.svg @@ -1,5 +1,5 @@ + aria-label="The path as of 8 October 2026, in phases rather than dates. Two input lanes from FIX-1786, landing in the order Q2 fixed, each on the product owner's merge: FIX-1794 has P1 merged, then P2, the notices, waiting on FIX-1814, which removes skill sub-agents, then its build. FIX-1802 has its spec merged, then waits on FIX-1794 P2, then builds P1. This spec is in review at the now line. After the gate, the ask and assign specs run at once, beside the closure's QA plan. Ask builds its own Layer 1 pieces, L1 to L3, L5, L7 and L8, without waiting, then lifts the child-finished signal, L4, once FIX-1794 P2 merges. Ask is offered to models only once FIX-1794 P2 merges, and waits with it if P2 slips. Assign builds only after FIX-1802 merges. The closure runs on one main commit after both. FIX-1818 and FIX-1819 were cut by Q1 and have no lane. The critical path, dashed red, runs through FIX-1794 P2's wait on FIX-1814 and its build, FIX-1802 P1, assign's build and the closure run.">