Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
spec(epic): fold review on FIX-1870 — FIX-1816 D3 amendment as Open 1…
…, handOff retires with the ledger, coordinator checks in the closure

- D2 names the FIX-1816 D3 amendment; Open 1 asks the owner whether a coordinator post becomes rows
- coordinator handOff retirement moves from FIX-1875 into FIX-1872, one change with the ledger (ER-10)
- closure adds the three coordinator checks, a scripted rename-map diff, package READMEs in the sweep
- wait depth stays one and a timeout cancels, as shipped; onTimeout continue dropped
- notice marker and openWorkstream clarified; FIX-1840 check reference corrected

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
  • Loading branch information
jhoffner and claude committed Oct 12, 2026
commit 8527a8eb3ad0ea900fb6c5dcbbd9bd654eb3ac5f
12 changes: 6 additions & 6 deletions specs/epics/FIX-1870/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ it and where it's checked.
|---|---|---|---|
| ER-1 | A worker starts work on another worker now with one tool, `dispatchTask`: a new row or a reference, a worker, and an optional `wait`. With `wait`, its turn parks until the row ends and resumes with the row's output, or an error naming how it ended. Without it, the ending arrives through `onTaskSettled` | FIX-1875 ([D1](DECISIONS.md#d1)) | The closure's reruns |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve target-session routing in dispatchTask

When one lead owns multiple project workstreams, the existing coordinator must call handOff({ worker, target }) to select the correct existing session (packages/workforce/test/project-coordinator.test.ts:507-525); targeted workstream delegates are explicitly rejected by the ordinary task path as “takes posts, not tasks” (packages/workforce/src/delegates/worker-delegates.ts:270-287). ER-1 defines the replacement using only a row/reference and worker, while PLAN.md:20 retires handOff, so the specified API cannot express this production route. Preserve target/existing-session addressing in dispatchTask, or retain handOff until parity exists.

Useful? React with 👍 / 👎.

| ER-2 | `addTask`, `assignTask` and the other task tools record work and an owner; the board decides when it runs. Only `dispatchTask` starts work now | FIX-1875 | FIX-1875's goal check |
| ER-3 | Every rule ask carries today holds under `wait`, unchanged: a waited-on row can't park on a question · the waiting turn owns the row's lifetime, and only its filer hears a cancel · `onTimeout: "cancel"` is the default · bounds 30 seconds to an hour, default 5 minutes · one row per call, one wait per step · `wait` only where the host can resume a parked turn and a sweeper bounds every wait · depth is `MAX_TASK_DEPTH` · the description says to wait only when the next step needs the result | FIX-1875 | The FIX-1816 and FIX-1820 reruns |
| ER-3 | Every rule ask carries today holds under `wait`, unchanged: a waited-on row can't park on a question · the waiting turn owns the row's lifetime, and only its filer hears a cancel · a timeout cancels the row · bounds 30 seconds to an hour, default 5 minutes · one row per call, one wait per step · `wait` only where the host can resume a parked turn and a sweeper bounds every wait · a turn working a task can't wait (depth one) · the description says to wait only when the next step needs the result | FIX-1875 | The FIX-1816 and FIX-1820 reruns |
| ER-4 | A referenced row must sit on the caller's own board lineage ([FIX-1794](https://linear.app/fixpoint-labs/issue/FIX-1794)) | FIX-1875 | FIX-1875's goal check |
| ER-5 | The board claim ticket is the only answer-once fence. Every coordinator delivery is a row; the delivery ledger and its `delegateAnswer` / `delegateMissed` entries are gone | FIX-1872 ([D2](DECISIONS.md#d2)) | FIX-1872's goal check · the closure sweep |
| ER-6 | One answer per delegate per post per round, and the routing record, keep working | FIX-1872 | The FIX-1791 and FIX-1840 coordinator checks |
| ER-5 | The board claim ticket is the only answer-once fence. Every coordinator delivery is a row, a delivery to a workstream's existing session included; the coordinator's `handOff` tool, the delivery ledger and its `delegateAnswer` / `delegateMissed` entries go in one change. A notice marker, which records a notice owed, is not a fence | FIX-1872 ([D2](DECISIONS.md#d2)) | FIX-1872's goal check · the closure sweep |
| ER-6 | One answer per delegate per post per round, each delegate's own line, the round deadline, the missed answer, and the routing record keep working, carried by rows ([Open 1](DECISIONS.md#open)) | FIX-1872 | `goals/coordinators/hands-each-post-to-its-delegates/`, `goals/coordinators/files-tasks-down-the-owners-chain/`, `goals/workforce-mailboxes/a-routed-post-gets-one-answer/` · the closure |
| ER-7 | Ask is a question to a person; hand-off is mid-work only; new work is dispatched; a caller waits. Every new public name in the set follows it | FIX-1876 defines in docs and code · FIX-1875, FIX-1872 consume | Each child's spec review · the closure's docs walk |

## What no child may do
Expand All @@ -24,7 +24,7 @@ it and where it's checked.
|---|---|---|
| ER-8 | Change what a waited-on or dispatched task does | Not doing. The proof is that nothing changed but names |
| ER-9 | Add waiting on several tasks at once, a row-less question tool for workers, or channels | Not doing |
| ER-10 | Add a second answer-once fence, or a delivery path that isn't a row | D2. A row-less path needs its own fence |
| ER-10 | Add a second answer-once fence, or a delivery path that isn't a row, including between two children's merges | D2. A row-less path needs its own fence |
| ER-11 | Edit the FIX-1816, FIX-1817 or FIX-1820 goal checks beyond names | The kill line. A check that had to change is the finding, not a fix |
| ER-12 | Retire `dispatcher()` or FIX-1312's `session: { from: true }` | They are flow-code transport, not a model tool |

Expand All @@ -40,5 +40,5 @@ it and where it's checked.

| # | The epic is done when | Proved by |
|---|---|---|
| ER-16 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) is met: the three reruns match with a names-only diff, the sweep passes, and both controls fail | FIX-1887's goal check |
| ER-17 | The published docs teach one path for giving another worker work | FIX-1876's docs PR · the closure follows the docs as written |
| ER-16 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) is met: the three reruns match with a rename-map diff, the three coordinator checks keep every outcome line, the sweep passes, and both controls fail | FIX-1887's goal check |
| ER-17 | The published docs and the package READMEs teach one path for giving another worker work | FIX-1876's docs PR · the closure follows the docs as written |
58 changes: 51 additions & 7 deletions specs/epics/FIX-1870/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,9 @@ describe one mechanism.

| | |
|---|---|
| **Instead of** | Keeping FIX-1791's delivery ledger (`packages/workforce/src/delivery-ledger.ts`) beside the claim ticket, or a lighter row-less path for group threads |
| **Because** | Two mechanisms that both decide "answered once" disagree at the edges. FIX-1815 decided on one fence ([its D2](../FIX-1815/DECISIONS.md#d2)) and never built it. A row-less path keeps a second fence alive, because something still has to refuse the duplicate answer |
| **Locks in** | A coordinator on the everyone policy, with rounds, files one row per delegate per post. One answer per delegate per post per round, and the routing record, keep working. FIX-1875's spec measures the row cost; if it's unacceptable, that comes up here, not to a local fix |
| **Instead of** | [FIX-1816 D3](../../issues/FIX-1816/DECISIONS.md#d3), merged: a coordinator's post stays a post, fenced by FIX-1791's delivery ledger (`packages/workforce/src/delivery-ledger.ts`) beside the claim ticket · or a lighter row-less path for group threads |
| **Because** | Two mechanisms that both decide "answered once" disagree at the edges. FIX-1815 decided on one fence ([its D2](../FIX-1815/DECISIONS.md#d2)) and never built it. A row-less path keeps a second fence alive, because something still has to refuse the duplicate answer. FIX-1816 D3 kept two for what the person sees: each delegate's own line, a routing policy, rounds. D2 keeps that and changes only the fence, so it amends D3 rather than reversing it, on the condition [Open 1](#open) asks the owner to accept |
| **Locks in** | A coordinator on the everyone policy, with rounds, files one row per delegate per post. One answer per delegate per post per round, each delegate's own line, the round deadline, the missed answer and the routing record keep working ([ER-6](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). The coordinator's `handOff` tool and the ledger go in one change, FIX-1872, so no build ships two fences. FIX-1872's spec measures the row cost; if it's unacceptable, that comes up here, not to a local fix |

![D2: one fence or two. Chosen: every coordinator delivery is a task row, fenced by the board claim ticket. Instead of: the delivery ledger kept beside it. It comes down to the first row: two fences that both decide answered once disagree at the edges. Second row, the price: the everyone policy files one row per delegate per post. Third row, a tie: one answer per delegate per post holds either way. Locks in the ledger and its delegateAnswer and delegateMissed entries removed. Flips if the row cost of the everyone policy is too high to carry](figures/d2-one-fence.svg)

Expand Down Expand Up @@ -78,9 +78,50 @@ Every rule has one owner. Read a row to see where it is built and where it is on
- **Why FIX-1818 was canceled.** [FIX-1815 Q1](../FIX-1815/DECISIONS.md#q1), the product owner,
2026-10-08: it did not move that epic's goal, and ask could ride an existing fence. FIX-1872
carries its intent; FIX-1872 closes it in favour of itself.
- **No separate wait depth.** Depth is the task chain limit, `MAX_TASK_DEPTH`.
- **`onTimeout: "continue"` is the only new behaviour, and it is a caller choice.** The row runs on,
as an unwaited dispatch would; its ending reaches the filer through `onTaskSettled`.
- **Wait depth stays one.** A turn that is itself working a task can't wait, as `addTaskAndWait`
refuses today ([FIX-1816's cut](../../issues/FIX-1816/DECISIONS.md#cut-before-the-gate)).
`MAX_TASK_DEPTH` bounds the task chain, not waits. Nested waits would be a behaviour change (ER-8).
- **A timeout cancels the row, as it ships.** Keeping a timed-out row running is not built here;
it would be new behaviour that no rerun proves (ER-8).
- **The coordinator's `handOff` tool retires in FIX-1872, with the ledger.** Retiring it in
FIX-1875 left a window where deliveries were rows and the ledger still fenced routing: two fences
(ER-10). `handOff` and `dispatchTask` coexist until FIX-1872 merges.
- **The conversation board's notice marker is not a fence.** FIX-1794's marker
(`conversation-board/ledger.ts`, `recordEnding`) records a notice owed; only delivering the
notice clears it. It never refuses a duplicate answer, so ER-5 and the sweep hold with it in place.
- **`openWorkstream` is not a hand-off tool.** FIX-1793's project-coordinator action starts a
workstream; ER-2 and ER-10 don't touch it. A delivery *to* a workstream's session is a coordinator
delivery, and moves to a row under ER-5.
- **The coordinator checks are FIX-1791's, FIX-1794's and FIX-1610's goals.** The earlier
"FIX-1840 check" was FIX-1794's `files-tasks-down-the-owners-chain`; FIX-1840 only appears in a
verdict row there.

<a name="open"></a>
## Open

### 1 · When a coordinator passes your message on to its delegates, does that become a task, or stay a message?

**In plain terms.** Today a coordinator hands a person's message to its delegates as a post, and a
ledger makes sure each delegate answers once. Board tasks have their own check. FIX-1816 (merged)
kept both on purpose, because a post shows each delegate's answer as its own line. D2 makes each
delegate's share a task, with one check for everything. The question is whether the person still
sees each delegate's own line, in rounds, routed the same way. The project-spec asks the same
(#3102, Open 2), so one answer settles both.

**The trade-off.** One check is one thing to keep right, and it is the epic's goal. Two checks
protect what FIX-1816 protected for certain, at the cost of the two disagreeing at the edges.

**My recommendation.** Make it a task, on one condition: FIX-1872's spec shows, before any code,
that a post sent as rows still lands each delegate's answer as its own line, keeps rounds and
routing, and passes the three coordinator checks with only fence lines changed. FIX-1816 D3 is then
amended (fence changed, what the person sees kept), as [EVOLUTION.md](EVOLUTION.md) records.

**What would change my mind.** A post's own lines, rounds or routing can't run as rows. Then D2
narrows to task endings: the ledger stays for posts, FIX-1872 shrinks to the hand-off route, and the
goal and sweep drop "no delivery ledger".

**What being wrong costs.** Decided now, a spec edit. Decided after FIX-1872 starts, a coordinator
post answered twice, or FIX-1872 redone. This spec should not merge until it is answered.

## What the end-state POC showed

Expand All @@ -95,5 +136,8 @@ None built. The premise, that every result path already comes from a row ending,
over the board; the owner fixed the vocabulary (D3).
- **Spec written (2026-10-11)** — closure FIX-1887 filed; D2 settles the everyone policy's row cost
at epic level, since a row-less path keeps a second fence.
- **Review folded (2026-10-12)** — D2 names the FIX-1816 D3 amendment and waits on Open 1; the
`handOff` retirement moved into FIX-1872; the coordinator checks and package READMEs joined the
closure; wait depth and timeout restated as they ship, with `onTimeout: "continue"` dropped.

**Open: none.**
**Open: 1.**
6 changes: 4 additions & 2 deletions specs/epics/FIX-1870/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The shared story once, and who publishes each specific. The prose is proposed re
> Your turn pauses until the task ends, then carries on with the task's output as the tool's
> result. Nothing holds a request open while it waits, so a server restart loses nothing. A wait
> has a time limit, five minutes unless you set one between 30 seconds and an hour. When it runs
> out, the task is cancelled, unless you asked to keep it running. A worker you're waiting on
> out, the task is cancelled. A worker you're waiting on
> can't stop to ask you a question; it answers with what it has, or fails.
>
> Only wait when the result changes what you do next. Otherwise let the task run and carry on.
Expand All @@ -44,7 +44,9 @@ The shared story once, and who publishes each specific. The prose is proposed re
|---|---|---|
| "Giving another worker work" above, replacing the ask section and the `waitForResponse` / `timeoutMs` table rows | FIX-1875, with the tool | This document; option table in FIX-1875's `DOCS.md` |
| `background-work.md` "Waiting for the answer" rewritten to point at the section above | FIX-1875 | Its `DOCS.md` |
| `coordinators.md` and `chief-of-staff.md`: the `handOff` tool replaced by `dispatchTask` | FIX-1875 | Its `DOCS.md` |
| `coordinators.md` and `chief-of-staff.md`: the `handOff` tool replaced by `dispatchTask` | FIX-1872 | Its `DOCS.md` |
| `packages/orchestration/README.md`: the `waitForResponse` / `timeoutMs` section replaced by `dispatchTask` | FIX-1875 | Its `DOCS.md` |
| `packages/workforce/README.md`: the coordinator `handOff` section and the delivery ledger replaced by rows | FIX-1872 | Its `DOCS.md` |
| `coordinators.md`: one answer per delegate per post, fenced by the task row | FIX-1872 | Its `DOCS.md` |
| The glossary rows above; every remaining use of "ask" or "hand-off" for delivering work, across `apps/docs` | FIX-1876 | This document, then its `DOCS.md` |
Comment on lines +45 to +51

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include package READMEs in documentation ownership

The ownership table covers only docs-site pages, but packages/orchestration/README.md:721-749 still teaches waitForResponse/timeoutMs, while packages/workforce/README.md:1595-1690 teaches coordinator handOff. Following this plan would leave installed-package readers with removed APIs, so assign both README migrations and include them in the closure sweep.

AGENTS.md reference: AGENTS.md:L210-L211

Useful? React with 👍 / 👎.


Expand Down
2 changes: 2 additions & 0 deletions specs/epics/FIX-1870/EVOLUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
| FIX-1815: ask and assign are two kinds of hand-off, both stay; source [`../FIX-1815/DECISIONS.md`](../FIX-1815/DECISIONS.md) → "Decided before review" | **Superseded** as naming; behaviour **retained** | The recipient does the same work in both; only the caller differs (`wait-for-response.ts`) | This epic D1 and D3 | Both behaviours stay, pinned by the FIX-1816, FIX-1817 and FIX-1820 reruns |
| FIX-1815 D4: ask is an opt-in option on `addTask`, `waitForResponse`; source [`../FIX-1815/DECISIONS.md#d4`](../FIX-1815/DECISIONS.md#d4) | **Amended**: fire-and-forget by default is retained, the option moves | `waitForResponse` makes a board CRUD tool a delivery tool | `dispatchTask`'s `wait` (FIX-1875, ER-1, ER-2) | `waitForResponse` and `timeoutMs` are refused by name, not ignored (BP-030) |
| FIX-1815 D2: one answer-once fence, never built; source [`../FIX-1815/DECISIONS.md#d2`](../FIX-1815/DECISIONS.md#d2), with ER-6 allowing either the claim ticket or the ledger | **Amended**: the intent retained, the choice made | Two fences still ship; FIX-1818 was cut by [FIX-1815 Q1](../FIX-1815/DECISIONS.md#q1) | This epic D2, ER-5, ER-10; FIX-1872 | The delivery ledger's server-written `deliveries` state is dropped; a session holding an open round needs FIX-1872's migration answer |
| [FIX-1816 D3](../../issues/FIX-1816/DECISIONS.md#d3): a coordinator's post stays a post; two answer-once checks, one per kind | **Amended**, pending [Open 1](DECISIONS.md#open): what the person sees is kept (each delegate's own line, routing, rounds), the fence changes (ledger token goes, the claim ticket replaces it) | D2. Evidence owed by FIX-1872's spec: the three coordinator checks pass with only fence lines changed | This epic D2, ER-5, ER-6; FIX-1872 | If the lines don't survive, D3 stands and D2 narrows to task endings |
| FIX-1816's cut: no ask from a task turn (depth one); [`../../issues/FIX-1816/DECISIONS.md`](../../issues/FIX-1816/DECISIONS.md#cut-before-the-gate) | **Retained** | Nested waits would be a behaviour change (ER-8) | — | `wait` refuses on a task turn, as `addTaskAndWait` does |
| FIX-1791: the delivery ledger, a token the answer hands back, claimed once; `packages/workforce/src/delivery-ledger.ts`; [`../../issues/FIX-1791/DECISIONS.md`](../../issues/FIX-1791/DECISIONS.md) → "Decided, not asked" | **Superseded** | Same as above | The board claim ticket (FIX-1872) | One answer per delegate per post per round holds (ER-6) |
| FIX-1312: reply-to-sender, `session: { from: true }`; Linear only | **Retained** | Flow-code transport, not a model tool | — | Unchanged (ER-12) |
| The glossary's *Hand-off*: work leaving the request for another session; `apps/docs/docs/glossary.md` | **Superseded** | D3 | The rows in [DOCS.md](DOCS.md) (FIX-1876) | Docs only |
Expand Down
Loading
Loading