Skip to content

spec(epic): dispatchTask, one tool for handing work to another worker (FIX-1870) - #3109

Merged
jhoffner merged 2 commits into
mainfrom
epic/dispatch-task
Oct 12, 2026
Merged

jhoffner merged 2 commits into
mainfrom
epic/dispatch-task

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator
A team that… Today After this epic
needs a colleague's result before it continues Calls addTask({ waitForResponse: true }). A flag turns a board tool into a delivery tool Calls dispatchTask({ …, wait: true }). The park, the resume and the limits do not change
hands work over and moves on Picks from four tools that overlap Calls dispatchTask without wait. addTask and assignTask only record work
runs a coordinator A delivery ledger fences its deliveries, apart from the board Each delivery is a task row. The claim ticket fences it, if Open 1 holds
reads the docs "Ask" and "hand-off" each name two things Each word names one thing

Goal: a worker that needs another worker to do something has one tool that starts the work now and can wait for the result. Today it has to pick from four tools that overlap.

flowchart LR
  F["one main commit · every child merged"] --> R["rerun FIX-1816, FIX-1817 and FIX-1820 checks · dispatchTask only"]
  F --> K["rerun the three coordinator checks · no ledger"]
  F --> S["public surface sweep"]
  R -->|"same results · diff is the rename map"| P["PASS · the epic's goal is met"]
  K -->|"same outcome lines · map plus fence lines"| P
  S -->|"retired tools and ledger absent"| P
  C["control · main before FIX-1875"] -.-> S
  S -.->|"under the control"| X["must FAIL · waitForResponse, handOff, ledger present"]
Loading

The reruns show that the behaviour did not change, for a waiter or a coordinator. The sweep (exports, tool lists, docs, package READMEs) shows that the old tools are gone. The closure issue FIX-1887 runs this check. Today's main must fail the sweep: SPEC.md.

In the box: dispatchTask, the claim ticket as the only fence, one meaning per word. Unchanged: the task tools as board CRUD, dispatcher() as transport. Replaced in one line: waitForResponse, handOff, the delivery ledger. Not built: multi-wait, a row-less question tool, channels, any behaviour change

The box holds one tool and one fence. The names change. The behaviour does not.

Why now. FIX-1815 closed on 2026-10-11. Three passing goal checks now pin ask and assign, so a behaviour change shows as a failing check. FIX-1637's docs and FIX-1796's term cleanup wait for this vocabulary.

The set: FIX-1875 adds dispatchTask. FIX-1872 moves coordinator delivery to rows and removes handOff and the delivery ledger in one change. FIX-1876 does the docs and the names. FIX-1887 is the closure. As of 2026-10-11: all four are in Backlog. The spec has the snapshot and the links to live state.

The path: a straight chain. This spec in review, then FIX-1875, FIX-1872 and FIX-1876 implemented in order, specs side by side, the closure run last

The specs can run in parallel. The implementations cannot, because each one gives the next a surface that must stop changing.

Who owns what: seven rules by four issues, each rule with exactly one owner

Each rule has one owner.

Sign off

One tool, dispatchTask, with an optional wait · D1

D1: dispatchTask with optional wait, chosen, beside ask, assign and handOff. Decides it: the recipient does the same work in both. Price: the tool description must say when to wait

The decision comes from the recipient: it does the same work for an ask and an assign. If wrong: the model waits when it should not, and turns park for no reason.

Every coordinator delivery is a row; the claim ticket is the only fence · D2

D2: every delivery is a row, chosen, beside the ledger kept beside the ticket. Decides it: two fences disagree at the edges. Price: one row per delegate per post on the everyone policy

The decision comes from two fences that disagree. It amends a merged decision, FIX-1816 D3, and waits on Open 1. If wrong: a coordinator post answered twice, or each delegate's own line folded into one.

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

FIX-1816 (merged) kept a post a post, so each delegate's answer shows as its own line. Recommendation: make it a task, if FIX-1872's spec first shows each delegate's own line, rounds and routing survive as rows. If not: D2 narrows to task endings and the ledger stays for posts. The project-spec's Open 2 (#3102) is the same question. This PR should not merge until it is answered: DECISIONS.md → Open.

D3, the vocabulary, is the owner's decision from 2026-10-11. What would change my mind on D1: one regression check that cannot stay the same. That is the kill line. Reasoning: DECISIONS.md.

Reviewers · look here

  • Open 1 gates the merge. D2 amends FIX-1816 D3; EVOLUTION.md records it as amended, pending the answer.
  • handOff now retires in FIX-1872, with the ledger, so no build ships two fences. The closure now reruns the three coordinator checks (FIX-1791, FIX-1794, FIX-1610) as well.
  • Wait depth stays one and a timeout cancels, as shipped. onTimeout: "continue" was dropped as new behaviour.
  • post-to-mailbox is already gone (FIX-1792, 617aeabb5). FIX-1875 has nothing to remove there. The sweep still checks it.

Not here: the approach of one issue. Those are the spec PRs.

Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1870 · Project: Orchestration Primitives · merges after human approval and required checks

How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.

In scope to challenge:

  • The objective and the goal in SPEC.md — is this body of work worth doing, and is the
    goal the real need at full size, or a smaller one the set could meet while the need stays
    unmet? Would the closure issue's check fail if the goal were not met?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

🤖 Generated with Claude Code

… (FIX-1870)

Five documents, an evolution record and six figures under specs/epics/FIX-1870/.
Closure issue FIX-1887 filed and blocked by every child.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 12, 2026 2:40am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 2:40am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 2:40am UTC

Request Review

@linear-code

linear-code Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

FIX-1870

FIX-1887

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T02:33:53.217707Z 2f0d80e Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec PR, read-only review)

I checked the spec's premises against main. The direction holds: one tool over the existing board, and the three unchanged goal checks as the kill line. Findings below, most important first. None need a change to D1 or D3.

1. The FIX-1875 → FIX-1872 gap leaves two fences, and ER-10 forbids that (PLAN "Coordination seams")

PLAN says FIX-1875 retires the coordinator's handOff tool. The judgment turn then delivers through dispatchTask rows while policy routing still runs on the ledger. That is the "second answer-once fence" ER-10 prohibits, and the spec only promises that FIX-1791's check stays green across it.

Simpler shape: move the coordinator handOff retirement from FIX-1875 into FIX-1872. FIX-1875 then adds dispatchTask and retires only the addTask ask options. FIX-1872 swaps the coordinator's delivery path and removes the ledger in one PR, so there is no interim state. The cost is that handOff and dispatchTask coexist for one release. That is cheaper than a seam both specs must keep green, and it fits the epic's own "rename, don't redesign" fence.

2. D2 says the ledger is "just a fence". On main it also does other work.

packages/workforce/src/delivery-ledger.ts also provides:

  • a pending → delivered | failed settlement, with the target session recorded
  • missed marking, where a delegate with no answer says so once
  • closeOverdue, which the coordinator's round sweep uses (coordinator-flow.ts, around lines 1353–1410)

D2 and ER-5 only argue the answer-once part. Round deadlines and "delegate failed or timed out" need an owner in the row model, probably onTimeout plus onTaskSettled. If they have none, FIX-1872 will rebuild the ledger on rows.

Ask: add to ER-5/ER-6, or to FIX-1872's brief, that round-deadline and missed-answer behaviour is carried by rows. The coordinator-rounds and coordinator-followup-context tests already pin it.

3. The sweep control may be weaker than it reads

The closure sweep "must FAIL on main before FIX-1875". Say what it greps: exported symbols, tool names in tool lists, and published pages. A sweep that only greps text can pass while a renamed internal (createHandOff) lives on. The "names-only diff" anti-game is also hand-judged. A scripted rename-map check would make it executable: the diff of the three goal dirs must be fully explained by the map, or the check fails.

4. Small points

  • ER-6 cites a "FIX-1840 coordinator check". The only reference I found in-repo is goals/coordinators/files-tasks-down-the-owners-chain/goal.md. Confirm that is the check meant, and name its path in the spec.
  • "waitForResponse and timeoutMs are refused by name (BP-030)" is good. Also say whether handOff is refused by name in persisted coordinator tool configs.
  • FIX-1876 as its own issue is defensible for review size. If finding 1 is taken, FIX-1872 touches the same files, which strengthens the case for keeping it last.

Architecture opportunity (in scope only because it is already being touched)

wait-for-response.ts (501 lines) holds the ask park/resume. dispatchTask is the natural point to make "start now" and "wait" two small functions: one starts the row, one parks on it. The current file mixes both. FIX-1875's spec should say so, so the tool does not become a third entry point beside addTask internals. I would not open any other refactor from this PR.

Verdict

Approve the direction. Fold finding 1 into PLAN/DECISIONS, and note finding 2 for FIX-1872's spec as an implementer note, not an epic decision. Findings 3 and 4 are optional.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: Layer-1 coherence on #3109. D1 holds. D2 forks from a merged decision and the spec never says so.

1. D2 reverses FIX-1816 D3 (merged in #2900) without naming it. specs/issues/FIX-1816/DECISIONS.md D3, "Ask the delegate stays a post", says a coordinator's post stays a post. It keeps two checks, the ledger token and the claim ticket, one per kind, and adds no third. It rejects "making a coordinator's hand-off of a post an ask". The reason: a post shows each delegate's own line, and a row folds them into one reply. FIX-1794 and FIX-1802 say the same: "a post is answered, a task is worked".

2. ER-8 and ER-6 can't both hold under D2. ER-8 ("nothing changed but names") and the kill line only cover the three reruns (FIX-1816/1817/1820). D2 changes coordinator delivery from post to row, so each delegate now runs a task session. The named controls are FIX-1791 and FIX-1840, but the closure's "names-only" proof doesn't apply to them. Say what a legitimate diff there is.

3. Smaller issues.

  • PLAN.md seam row: FIX-1875 retires handOff while routing still runs on the ledger. That is a window where deliveries are rows and the ledger still claims them. Name which fence wins in that window.
  • Say that openWorkstream (FIX-1793, a project-coordinator action, project-coordinator.ts) is not a hand-off tool and is outside the ER-2/ER-10 freeze. The project coordinator's own handOff use (project-coordinator.ts:267) migrates in FIX-1875.

Checked and fine.

  • D1 matches FIX-1815's shipped ask and assign semantics (wait-for-response.ts, askGateId, resumeOwed, followUpOf) and the FIX-1794 lineage check (ER-4).
  • The closure sweep would FAIL on today's main. waitForResponse and timeoutMs are on addTask (task-tools-capability.ts 46, 775, 901), the coordinator handOff tool exists (coordinator-flow.ts ~808), and delivery-ledger.ts plus delegateAnswer and delegateMissed exist (coordinator-keys.ts 32, 39).
  • post-to-mailbox is already gone from src, so that sweep item only guards a regression.
  • Vocabulary is clean (no seat, role or room).
  • Overbuild: the set is not overbuilt, since FIX-1871 and FIX-1874 were dropped. FIX-1876 could fold into the other two, but the spec already says why it stays separate.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect · coherence check on the epic-spec

The direction matches the Orchestration Primitives project-spec (#3102). Two things in it still read as building in two directions, and both are about D2 / ER-5.

1. D2 reverses a merged decision that EVOLUTION.md doesn't list. FIX-1816 D3 (merged in #2900, aligned in #2905) kept a coordinator's post as a post. Its "Locks in" line says: "Two answer-once checks stay: the post's ledger token and the row's claim ticket. Each serves one kind, and no third is added." D2 and ER-5 remove that ledger token. D2's "Because" cites FIX-1815 D2 (one fence, never built), but FIX-1816 D3 is the later and more specific call, and it chose two.

D2 may still be right. D3 kept the post because of what the person sees, which is each delegate's own line rather than one folded reply. ER-6 ("one answer per delegate per post per round") looks like it keeps that. If so, D2 changes only the fence and not what the person sees. That's an amendment, and it should be written down as one:

  • Add a row to EVOLUTION.md for FIX-1816 D3, treated as Amended: the behaviour is kept (each delegate's own line), the fence is changed (ledger token goes, the row's claim ticket replaces it). Give the evidence that the person-visible result doesn't change.
  • Cite it in D2's "Instead of" or "Because", so FIX-1872 isn't built against a decision that's still on main saying the opposite.
  • If keeping each delegate's line does not survive the move to rows, that's D3's flip condition. It then needs an owner decision through FSD Decision Manager before this merges, not a change made inside FIX-1872.

2. A third delivery marker isn't counted. FIX-1794 (#2935, merged Oct 9) shipped the conversation board's notice markers (workforce/src/conversation-board/ledger.ts, notice-delivery.ts, with recordEnding in orchestration/src/tasks/collection/ending.ts). A marker lands with the ending and only delivering the notice clears it. ER-5 says the claim ticket is the only answer-once fence, and the closure sweep checks for "no delivery ledger". So please either:

  • state that the notice marker tracks a delivery owed, not an answer-once fence, and say why ER-5 and the sweep still hold with it in place, or
  • give it to FIX-1872 to fold in, and add it to the sweep.

Otherwise FIX-1887 could pass while two fences still ship, or fail on something no child owns.

Small point: FIX-1786 (where the task envelope, assignee and the filing API were settled, D7/D9 in #2841) and FIX-1794 belong in "Not children, deliberately" or the inputs, next to FIX-1815, since the regression gate depends on both.


FSD Architect (coherence watch).

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The redraft is the right simplification: canceling the envelope draft (FIX-1871/1874) and building on wait-for-response.ts plus row endings is cleaner than inventing reply/settle modes. D1 (one dispatchTask + wait), D2 (claim ticket only), and D3 (vocabulary) hang together, and the kill line (regression goals change beyond names) is a strong falsifier.

Where the approach is about as simple as it gets

  • Keeping dispatcher() / FIX-1312 as flow transport (ER-12) avoids a second public hand-off path.
  • wait: true should be a thin façade over existing ask machinery; wait: false should reuse notice/onTaskSettled paths rather than new transport.
  • The FIX-1815 pivot is documented honestly in EVOLUTION.md; the five-team table is high-signal.

Where complexity is mostly process, not product

  • Three implementation children plus closure is defensible for reviewability, but PLAN’s FIX-1875 → FIX-1872 seam intentionally runs two fences until 1872 lands. That’s the main “went further than one PR” cost; consider merging 1872 into 1875 if FIX-1791 green can be held without the interim ledger (optional, not required).
  • FIX-1876 as a separate issue is reasonable; the spec already names the collapse trigger if renames land early.

Nits to tighten before or in child specs (see inline)

  1. onTimeout: "continue" is called out as the only new behaviour, which sits awkwardly next to ER-8 / “names only” and closure anti-game. Either elevate it in SPEC + ER-3 + DOCS, or drop it from this epic.
  2. D2 row cost is named as the D2 flip condition but FIX-1887 is behavioral-only; child specs should add a concrete everyone×rounds×delegates scenario with storage/latency thresholds (ER-14), since the ledger’s bounded post window does not automatically transfer to partitioned conversation rows.
  3. ER-2 (addTask never starts work now) requires removing conversation-board wake on assignee present in board.ts today — worth one explicit acceptance line in FIX-1875’s issue spec so implementers don’t ship the tool without the CRUD split.

No changes requested on direction; approving the epic spec.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1870/DECISIONS.md Outdated
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`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This reads as scope beyond a rename epic: ER-8 and the closure anti-game both stress parity, yet this bullet is the only place that admits net-new caller behavior. onTimeout does not appear in packages/orchestration on main today.

Suggestion (pick one): (a) promote continue into SPEC goal / ER-3 and the DOCS draft with an explicit regression or goal leg; (b) defer it to a follow-up issue; or (c) drop it here so FIX-1870 stays strictly “names + fence consolidation.”

Comment thread specs/epics/FIX-1870/DECISIONS.md Outdated
|---|---|
| **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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Good that row cost is the D2 flip. Closure (FIX-1887) as written only reruns behavioral goals + export sweep — it won’t catch everyone-policy storage blow-up.

Worth requiring FIX-1875 or FIX-1872’s issue spec to carry one bounded scenario (delegates × rounds × posts) and pass/fail thresholds, so ER-14 isn’t only a human escalation.

|---|---|
| **Instead of** | Ask (`addTask({ waitForResponse })`) and assign as two kinds of hand-off, with the coordinator's `handOff` beside them · or the first draft: a dispatch envelope carrying a reply mode and a settle mode (FIX-1871, FIX-1874) |
| **Because** | An ask is an ordinary task row the caller waits on (`packages/orchestration/src/tasks/helpers/wait-for-response.ts`). Every way a result comes back (ask resume, `onTaskSettled`, the split wake) already comes from a row ending and runs through the board's notice code. The recipient does the same work either way; only the caller differs. So no new transport is needed |
| **Locks in** | `addTask`, `assignTask` and the other task tools are board CRUD and never start work now. `dispatcher()` stays transport for flow code; a fire-and-forget with no row is a `dispatcher()` call, not a model tool. Every rule ask carries today moves to `wait` unchanged ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Implementers will need a deliberate step: on conversation boards, guarded addTask still wakes when an assignee is present (packages/workforce/src/conversation-board/board.ts). ER-2 is false until that wake moves behind dispatchTask.

Suggest FIX-1875’s issue spec lists “strip start-now from addTask/assignTask on boards where ER-2 applies” as an explicit deliverable beside adding the tool.

Comment thread specs/epics/FIX-1870/PLAN.md Outdated

| Seam | Between | Rule |
|---|---|---|
| The coordinator's delivery | FIX-1875 and FIX-1872 | FIX-1875 retires the `handOff` tool, so the judgment turn delivers through `dispatchTask` rows while policy routing still runs on the ledger. FIX-1791's check must stay green across that gap; FIX-1872 closes it |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This seam is the epic’s main complexity tax: retiring coordinator handOff while the ledger may still fence routing until FIX-1872 merges.

The PLAN already says FIX-1791 must stay green — consider one hard rule in FIX-1875’s spec: either (1) don’t merge 1875 until 1872 is ready, or (2) judgment turn uses dispatchTask rows and a documented interim ledger bridge. Without that, two-fence drift is easy during implementation.

| [FIX-1887](https://linear.app/fixpoint-labs/issue/FIX-1887) · closure · **required** | The QA plan and its run on one `main` commit: the three reruns, the surface sweep, every child's own check | Proves the whole ([ER-15](BUSINESS-RULES.md#the-closure)) | Backlog · blocked by FIX-1875, FIX-1872, FIX-1876 |

Three issues and a closure. [FIX-1871](https://linear.app/fixpoint-labs/issue/FIX-1871) and
[FIX-1874](https://linear.app/fixpoint-labs/issue/FIX-1874), the first draft's envelope and

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The “whether three is really two” paragraph is useful honesty. If reviewability is the only reason for FIX-1876, the collapse trigger could be stated as a default preference (fold vocabulary into whichever PR last touches task-tools-capability.ts / coordinator docs) rather than a third mandatory child — optional simplification, not a blocker.

Comment thread specs/epics/FIX-1870/DOCS.md Outdated
> 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

“Unless you asked to keep it running” implies onTimeout: "continue" from DECISIONS. Published docs will teach behavior the FIX-1816/1820 reruns won’t exercise if closure stays names-only.

Align this sentence with whatever you decide on the DECISIONS bullet (promote to tested behavior vs defer).

Comment thread specs/epics/FIX-1870/BUSINESS-RULES.md Outdated
|---|---|---|---|
| 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 |
| 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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

ER-3 documents onTimeout: "cancel" as default but not continue. If continue ships in FIX-1875, ER-3 should list it here (and in FIX-1875’s goal check) so ER-8’s “unchanged” claim stays coherent.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f0d80e460

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".


| # | Rule | Owner | Checked at |
|---|---|---|---|
| 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 👍 / 👎.

Comment thread specs/epics/FIX-1870/BUSINESS-RULES.md Outdated
|---|---|---|---|
| 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 |
| 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 |

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 Resolve the contradictory wait-depth contract

For a worker already executing a task, the shipped addTaskAndWait path refuses before filing (packages/orchestration/src/tasks/helpers/wait-for-response.ts:159-190), and the predecessor contract deliberately fixes wait depth at one (specs/epics/FIX-1815/DECISIONS.md:162-168). Saying both that this rule remains unchanged and that depth is MAX_TASK_DEPTH instead permits nested waits through the task-chain limit. Either retain the task-turn prohibition or treat nested waits as a behavior change with explicit safety and regression coverage.

Useful? React with 👍 / 👎.

Comment thread specs/epics/FIX-1870/SPEC.md Outdated
| How we verify | |
|---|---|
| **Goal check** | The closure issue, [FIX-1887](https://linear.app/fixpoint-labs/issue/FIX-1887), on one `main` commit after every other child merges ([ER-15](BUSINESS-RULES.md#the-closure)) |
| **Signal** | `goals/hand-offs/ask-survives-a-restart/` (FIX-1816), `goals/coordinators/task-session-stays-open/` (FIX-1817) and `goals/hand-offs/survives-a-restart-and-runs-once/` (FIX-1820) each get the result they got before, with workers that use only `dispatchTask`. The public exports, tool lists and docs carry no `waitForResponse` or `timeoutMs` on `addTask`, no coordinator `handOff` tool, no `post-to-mailbox`, and no delivery ledger |

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 Add coordinator regressions to the closure signal

The closure signal runs only the FIX-1816, FIX-1817, and FIX-1820 checks plus a surface sweep, none of which proves D2's migrated coordinator behavior: one answer per delegate/post/round, round closure, and onward routing. Although BUSINESS-RULES.md:18 names the FIX-1791 and FIX-1840 coordinator checks, they are not required by this pass criterion, so removing the ledger could duplicate or drop coordinator answers while the stated epic goal still passes. Require those coordinator checks in FIX-1887's assembled-set run.

Useful? React with 👍 / 👎.

Comment thread specs/epics/FIX-1870/DECISIONS.md Outdated
Comment on lines +82 to +83
- **`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`.

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 Prove the new continue-on-timeout behavior

When a wait times out, the shipped contract always cancels its row (specs/issues/FIX-1816/BUSINESS-RULES.md:54), whereas this option lets the work continue and later sends an onTaskSettled notice. That is observable new behavior despite the spec's names-only/no-behavior-change success condition, and no listed closure control exercises it. Either remove the mode or widen the goal and add explicit proof for timeout, later settlement, and restart behavior.

Useful? React with 👍 / 👎.

Comment on lines +45 to +49
| "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`: 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` |

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 👍 / 👎.

…, 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>
@jhoffner
jhoffner merged commit f1ae352 into main Oct 12, 2026
19 checks passed
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Open 1, raised from the architect's D2-vs-FIX-1816-D3 comment, is answered by the owner (2026-10-11): anything that needs a confirmed answer is a task through dispatchTask; a tell that expects no reply is a plain message with no row. D2 amends FIX-1816 D3 to match; a question kind of task is deferred. Folded in the follow-up amendment #3110 (this PR stays as merged).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant