Skip to content

spec(FIX-1875): dispatchTask, one tool that starts a task on another worker now, and can wait for it - #3140

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1875
Oct 12, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1875

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
builds a worker that must have an answer before it continues The model must set waitForResponse: true on addTask The model calls dispatchTask with wait: true. The park, the resume and the limits do not change
builds a worker that gives work to a colleague and continues addTask with an assignee records the task. On a conversation board, it also starts the task dispatchTask records the task and starts it. The ending comes as a notice, as before
must record work and start it later Not possible on a conversation board: an assignee starts the work addTask and assignTask record the task and its owner. It stays recorded, not started, until a dispatch
files work from an app or a script with the addTask_tasks action The task starts Send dispatchTask_tasks to start it. addTask_tasks only records it, and its result says status: "recorded"
sends waitForResponse or imports addTaskAndWait It works The tool refuses the field and names dispatchTask. The import does not compile; the changeset gives the new name

Goal: a worker that must have another worker do a job has one tool that starts the job now and can wait for the result. Recording a task never starts it.

flowchart LR
  L["the FIX-1817 lab · real store · two conversations"] --> R["record with addTask_tasks · touch the board for 30s"]
  R --> D["dispatch the row · and a new one"]
  D -->|"recorded row never ran · both dispatched rows ran once · other conversation refused"| P["PASS"]
  X["three regression checks · renamed only"] -->|"same results"| P
  C["control · addTask still starts work"] -.-> R
  R -.->|"under the control"| F["must FAIL · rec:not-started"]
Loading

The check reads the store. It does not read the tool return value. Check: goals/dispatching-work/a-recorded-task-waits-for-dispatch/, plus reruns of the FIX-1816, FIX-1817 and FIX-1820 checks with a rename-only diff. Control: GOAL_CONTROL=add-starts must fail rec:not-started, and today's main must fail. Why this goal and not a smaller one: SPEC.md.

Today three tools start work on a conversation board; after, only dispatchTask starts work, addTask and assignTask record, and the waiting rules do not change

Read across each row. Today, three tools start work. After, one tool starts work. The band at the bottom is the same in the two columns.

How: a task tool on a conversation board writes a "not dispatched" mark (undispatched) on a row that it only records. The board starts only rows without the mark. dispatchTask writes rows without the mark, and its wait is the ask mechanism of today with a new name.

Sign off

The goal, at that size. If wrong: we ship a second tool that starts work, or we break app calls to addTask_tasks for no gain.

On a conversation board, addTask and assignTask stop starting work · D1

D1: addTask records and dispatchTask starts, chosen, beside addTask keeps starting work. Decides it: how many tools start work. Price: about 17 goal checks, three worker files and app calls move to dispatchTask

The decision comes from the first row: if addTask keeps its start, two tools start work and the model must choose. About 17 goal checks, three worker files and app calls to addTask_tasks move to dispatchTask. If wrong: an app that upgrades and does not read the changeset files tasks that never start. No error shows, but every addTask result now says status: "recorded".

dispatchTask takes the fields of addTask plus wait, flat, with taskId or post: true · D2

D2: addTask's fields plus wait, flat, chosen, beside a nested task envelope. Decides it: the regression diff stays a two-entry rename map. Price: goal-or-taskId is a run-time rule

The decision comes from the proof: with a flat shape, the regression diffs are a rename map. An envelope changes all calls. Exactly one of goal (a new row), taskId (a recorded row) or post: true (the post a coordinator turn is routing, FIX-1872's) says what starts. post is in the schema only on a routing turn, and the recipient is assignee in every form. If wrong: the model mixes them, and the tool refuses it at run time, not in the schema.

Open: none. D1 is the decision to examine. Reasons and alternatives: DECISIONS.md.

Reviewers · look here

  • Decisions → D1. Is a persisted mark on recorded rows the correct way to make addTask record only? The alternative is to stop the wake only, but any later touch of the board starts every assigned row.
  • Rules → the diagram under "The old surface". The board tests "can start" in four places today; S6 makes them one predicate. Did we find all of them?
  • Plan → P1 and P2. P1 adds the tool, teaches every start test to read the mark, renames the exports and moves callers, with no behaviour change. P2 writes the mark. Readers ship before writers, so a rolling deploy is safe. Is this the correct seam?

Not here: the coordinator handOff and the delivery ledger (FIX-1872), the internal ask names (FIX-1876).

Engineering calls — decided without an ask
  • dispatchTask is only on a board that can start work now. A board that a drain runs does not get it.
  • wait is available only where waitForResponse is available today. The action never waits.
  • addTask refuses waitForResponse and timeoutMs by name. The schema does not strip them.
  • A wait on a recorded row is permitted if the row is pending, not claimed and has no wait on it.
  • A recorded row is reachable only on the board of the caller (ER-4 by construction).
  • The public ask names go with no alias. The host seam names stay until FIX-1876.
  • Two PRs: P1 adds the tool, the mark readers, the export renames and the callers' move; P2 makes addTask record only.
  • With no owner to resolve, dispatchTask refuses (assignee_required) and writes nothing.
POC — the factual base, runnable
node specs/issues/FIX-1875/poc/surface-sweep/sweep.mjs            # inventory: 38 files with a retired name, 67 that rely on the start
node specs/issues/FIX-1875/poc/surface-sweep/sweep.mjs --assert   # exits 1 on main; must exit 0 after P2
node specs/issues/FIX-1875/poc/surface-sweep/sweep.mjs --control  # plants an unclassified hit; exits 2

It answers: which files must change. It is retained evidence, not production code.

Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1875 · epic FIX-1870 (#3109) · builds on FIX-1816, FIX-1794, FIX-1802 · merges after human approval and required checks (contract)

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

🤖 Generated with Claude Code

…worker now, and can wait for it

Retained spec set: SPEC, DECISIONS, BUSINESS-RULES, PLAN, DOCS, EVOLUTION,
three figures, and a surface-sweep POC that re-derives the factual base.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jhoffner jhoffner added the spec label Oct 12, 2026
@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1875

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction altitude)

I read SPEC, DECISIONS, BUSINESS-RULES and PLAN, and checked the board claims against packages/workforce/src/conversation-board/board.ts on main. Overall the approach holds: the D1 premise is true in the code, and the persisted "waiting" mark is the least invasive way to get "record never starts". Findings below are ordered by weight.

Above the line (could change the plan)

  1. "The board has two tests for can-start" undercounts the places that read it. There are four start touchpoints in board.ts, not two:

    • assignedOnly.claim eligibility (task.assignee !== undefined, ~L165)
    • hasStartable (~L173)
    • the guarded addTask, which wakes unconditionally on assignee !== undefined (~L370)
    • the setAssignee and unpark wrappers, which gate their wake on hasStartable (~L413, ~L421)

    assignedOnly and hasStartable each inline task.assignee !== undefined separately. That is the duplication that lets one path miss the mark. S6 already says "one predicate". Make it explicit that this is a refactor deliverable: extract a single isStartable(task) (assigned + not awaiting dispatch) and have the claim eligibility, hasStartable and the addTask wake all call it. This is the one place where the feature really does justify tidying existing code, and it is cheap. Also add addTask's unconditional wake (~L370) to the Rules' "every path" diagram. A wake for a recorded row is harmless today only because hasStartable re-checks, and the unconditional wake should stop looking like a start path.

  2. P2 is not "the behaviour change and little else". S8 (renaming AskEndedError, canHoldAsk, the timeout constants, addTaskAndWait, and so on) is a public-surface rename with no dependency on the switch-off. It can go in P1, which is already described as "no behaviour change", next to the callers' move. Then P2's diff is only S6, S7 and S9, and a reviewer can read the one risky change. As written, the 38-file rename buries the 3-file behaviour switch. Related boundary: the spec leaves row.ask, parkOnAsk and the rest to FIX-1876 but renames the public ask names here. Say in one line why the split falls there, or the two issues will collide on wait-for-response.ts.

  3. The silent-failure risk named under D1 has a cheap mitigation that isn't in the plan. "An app that upgrades without reading the changeset files tasks that never run, and nothing errors." BR-23 only covers the model-facing description. Have addTask and addTask_tasks also return the recorded state in their result (for example status: "recorded" with a one-line note saying it is waiting for dispatchTask). Then a script that logs the return sees the change, and a model that ignored the description is told on the first call. The goal check grades the store, but the model reads the return value. This is also the right place to be loud, since refusing is off the table (the row must be recorded).

Leaner-version question (for the author, not a blocker)

  1. Is the taskId (dispatch-a-recorded-row) mode needed beyond the goal check? It drives BR-9, BR-10, BR-11, BR-13, BR-17, the conditional ready-write in S3, and "wait on a recorded row". The only named consumer of "record now, start later" is the proof itself. The coherent alternative is that a conversation-board addTask with no assignee already waits (the board's own "unassigned rows wait" rule), so "record for later" = unassigned addTask, and dispatchTask({goal, assignee}) is the only start. That drops the mark's ready-write path for existing rows and leaves assignTask as the only thing to reconcile. The spec's third persona ("record now, start later") argues the other way, so I'd confirm there is a real caller before building this much surface for it. If there is, keep as written. If not, cut taskId and the wait-on-recorded rule and say so in DECISIONS "Considered and dropped".

  2. Check whether blocked already models "waiting" before adding awaitingDispatch. The collection has a blocked status (ref.block). If a recorded row could sit in an existing waiting state and dispatchTask unblocks it, there would be no new persisted field and no BP-030 dual-read story. I suspect blocked's semantics (settle/cascade, notices) make it a poor fit, but DECISIONS "Considered and dropped" should say that in a line, since a new nullable field on the task schema is the most expensive item here (negative polarity, absent = ready, never caller-patchable).

Notes for the implementer (below the line, recorded not argued)

  • dispatchTask on a conversation board needs wake after the ready-write. Reuse the setAssignee wrapper path (wake gated on the shared predicate) rather than adding a fifth wake site.
  • The Plan's pseudocode says "the board wakes ready rows" for the non-wait path. Make sure the ready-write and the wake are the same step the replay test (BR-15) exercises, or a crash between them leaves a ready row with no wake until the next touch. Today's resolver sweep covers that, so it is probably fine, but name it in V3.
  • The sweep POC's buckets are a good review list. Consider wiring --assert into CI at P2 so a new addTask_tasks-to-start caller fails the build after the switch, not just at implement time.

Nothing here contradicts the goal or D1. Items 1 to 3 are the ones I would fold into PLAN; 4 and 5 are questions for the author.


Generated by Claude Code

@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 1:07pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 1:07pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 1:07pm UTC

Request Review

@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.

Simplify review (spec)

Verdict: The core approach looks like the right minimum for epic ER-2 on conversation boards — not a simpler design that still hits the goal. I would not block on direction; a few spec tighten-ups would cut implementation churn.

Did this go further than necessary?

No on the product shape. Today hasStartable treats pending + assignee as startable on every touch (board.ts). To make addTask a ledger without breaking BP-030, you need a persisted distinction between “recorded” and “ready.” The spec’s rejected alternatives (mark-ready rows, ledger-only hold, status-enum reuse) are argued correctly; reusing blocked/parked would fight existing semantics.

Yes on packaging and prose.

  1. Rename map vs FIX-1876 — DECISIONS says host seam names stay until FIX-1876, but the pinned map + sweep.mjs RETIRED list still retire canHoldAsk, Ask*Error, and *_ASK_TIMEOUT_MS in this issue. That bundles ~60-file churn with D1/D2. Recommendation (should clarify before implement): split the map into “FIX-1875 public / regression” vs “FIX-1876 internal,” or one explicit sentence that export renames ship here while parkOnAsk / resumeAsk identifiers stay until 1876 — and align S8, DOCS ownership, and sweep.

  2. P1 surface area — P1 lands awaitingDispatch, ready-write, and dispatchTask({ taskId }) while addTask still starts work, so record-then-dispatch is mostly test-seeded until P2. The two-PR seam is smart for ER-11; the docs/API for taskId could be labeled P2-primary to avoid implying app-visible behavior mid-rollout.

  3. Spec mass — DECISIONS “Decided, not asked,” SPEC verification, PLAN S-rows and V-rows repeat the same BRs. Trimming cross-links would not change the contract.

Cleaner approaches considered

Alternative Trade-off
Ship dispatchTask only; defer mark to P2 Smaller P1, but P1 can’t prove taskId / ready-write; sequencing change — only if epic re-gates ER-11.
Discriminated union schema (task: { new | ref }) Rejected in D2 for rename proof + model fill — still the right call for this epic.
Third-party / graft instead of sweep.mjs Graft/rg are fine for discovery; dual-axis RETIRED+STARTS + exit codes fit a small script (FIX-1796 census is the CI promotion pattern if you outgrow this).
Wrapper tool over addTask Correctly dropped per epic review — one filing path is simpler at runtime.

What I like (complexity well spent)

  • Two PRs: P1 rename-only regression behavior, P2 switch-off — best lever for a ~60-file change.
  • One start predicate + shared filing entry — addresses real drift risk (hasStartable vs claim vs drain).
  • Flat dispatchTask + runtime goal/taskId XOR — ugly schema, clean regression story (D2).
  • sweep.mjs — cheap retained evidence; --assert / --control are proportionate (ran on branch: 38 RETIRED hits, exit 1 as expected).

Non-blocking nits

  • S3 “nullable” → “optional boolean, present only when waiting; omitted = ready” (dual-read, not tri-state).
  • STARTS heuristic: only *_tasks and `addTask` in WORKER.md — document exclusions or widen if you want totality on prose.
  • Goal rec:waits: prefer store-grade assertions + light touches so the harness doesn’t multiply full list() work on a growing board (implement-time, not spec block).

Approval

I’m not approving only because rename-map ownership should be explicit in the spec before implementation starts — not because D1/D2 look wrong. If you align FIX-1875 vs FIX-1876 on exports and add a short P1/P2 mark semantics table, I’d treat this spec as ready for direction sign-off.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

**The rename map** (D2; the regression diffs and the changeset use it):
`addTask_tasks` → `dispatchTask_tasks` · `addTask` → `dispatchTask` where it starts work ·
`waitForResponse` → `wait` · `addTaskAndWait` → `dispatchAndWait` · `AddTaskAndWaitOptions` →
`DispatchAndWaitOptions` · `WaitForResponseResult` → `DispatchAndWaitResult` · `canHoldAsk` →

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.

Simplify / scope: This block mixes user-facing renames (waitForResponse → wait, addTaskAndWait → dispatchAndWait) with ask-seam renames (canHoldAsk, AskEndedError, timeout constants). DECISIONS defers parkOnAsk / resumeAsk to FIX-1876, but S8 + sweep still treat the ask-prefixed exports as retired here.

Consider splitting the map (or a one-line rule: “exports that only exist because of wait move in 1875; host ask vocabulary moves in 1876”) so the implementer doesn’t drag FIX-1876 into the P2 export deletion pass by accident.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663. DECISIONS → Decided, not asked now says where the line falls: this issue renames every exported name a caller imports (canHoldAsk and the Ask*Errors included); the internal seam (parkOnAsk, resumeAsk, row.ask, …) stays for FIX-1876, which starts after this merges and keeps what this renamed (its WR-22). The two maps agree where both name a symbol.

- **A recorded row is reachable only on the caller's own board.** The board resolver already
reads the running session's own partition, so a row elsewhere is `task_not_found` (ER-4 holds by
construction; the goal check's `lineage:refused` proves it).
- **The public ask names go with no alias** ([pinned map](PLAN.md#pinned-names)): the closure

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 bullet says host seam names are FIX-1876’s, but the pinned map still retires canHoldAsk and ask-prefixed errors/constants in this issue. Worth reconciling so reviewers aren’t left guessing whether P2 removes those symbols or only renames them in docs.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Same fold as the PLAN thread (95f5663): the bullet now states the boundary explicitly, exported names here, internal seam in FIX-1876.

Comment thread specs/issues/FIX-1875/PLAN.md Outdated
|---|---|---|---|---|
| S1 | P1 | `orchestration` · the task tools (`task-tools-capability.ts`) | Add `dispatchTask`: `addTask`'s fields, plus `taskId`, `wait`, `timeoutMs` (D2). It runs `addTask`'s checks through the same code, not a copy, then files the row ready, or readies a recorded one. Offered only when the board passes a way to start a row now (a new `TaskToolsOptions` member); `wait` and `timeoutMs` only where `waitForResponse` is offered today. Schema left open for FIX-1872's `target` | ER-1 · BR-8 to BR-15, BR-18 to BR-20 |
| S2 | P1 | `orchestration` · the wait (`wait-for-response.ts`) | Split into *file or ready the row* and *park on it* (epic review note 2), so `addTask` and `dispatchTask` share one entry. Accept a recorded row: mark it waited-on and ready in one write. Keep the text the FIX-1816 controls patch (see Guardrails) | BR-16, BR-17 |
| S3 | P1 | `orchestration` · task schema and collection | A persisted, nullable *waiting for dispatch* mark (`awaitingDispatch`), absent meaning ready. One conditional write that readies a recorded row, optionally setting its assignee and its wait. The mark is never caller-patchable (`updateTask`, `patchMetadata`) | ER-2 · BR-5, BR-9, BR-10, BR-17 |

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.

P1 vs P2 clarity: S3 lands the mark in P1 while S6/S7 make it behaviorally meaningful in P2. A tiny table (who sets/clears awaitingDispatch in P1 vs P2; whether production can observe dispatchTask({ taskId }) before P2) would reduce implementer guesswork without changing the contract.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663: PLAN opens with a P1/P2 table (who writes the mark, who reads it, whether production can see dispatchTask({ taskId }) start a row). The start tests also moved to P1, so readers ship before writers.

];
const RETIRED_RE = new RegExp(`\\b(${RETIRED.join("|")})\\b`);
const ACTION_RE = /\b(addTask|assignTask)_tasks\b/;
const WORKER_STARTS_RE = /`addTask`/;

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.

STARTS only catches addTask_tasks / assignTask_tasks and backtick `addTask` in WORKER.md. Prose like “addTask starts the task” or assignTask guidance won’t bucket — fine if intentional; if totality matters, either widen patterns or state explicit exclusions in PLAN §POC so the 55-file baseline isn’t over-claimed.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 95f5663: STARTS now also catches scripted model calls (toolName: "addTask"), and the header and PLAN state the exclusion (backtick-less prose outside WORKER.md, read by eye). Counts re-derived: 67 files rely on the start.

@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: dd2605523a

ℹ️ 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".

Comment thread specs/issues/FIX-1875/BUSINESS-RULES.md Outdated
Comment on lines +25 to +26
| BR-8 | `dispatchTask({ goal, … })` | A row is filed ready and the board starts it now. The call returns its id at once | CI · goal `disp:new-runs` |
| BR-9 | `dispatchTask({ taskId })` names a row waiting for dispatch | The mark clears and the row starts. With `assignee`, the owner is set in the same write | CI · goal `disp:ref-runs` |

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 Require an assignee when dispatch has no unique default

On a conversation with multiple delegates, the inherited addTask default leaves an omitted assignee unset, while the board only claims assigned rows (packages/workforce/src/conversation-board/board.ts:163-166,345-350). Consequently both dispatchTask({ goal }) and dispatchTask({ taskId }) for an unassigned row can report success without starting anything, contradicting BR-8/BR-9. Refuse the call unless an assignee or unique default can be resolved before filing or clearing the dispatch mark.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663 as BR-24: with no assignee and no single delegate to default to (or a taskId row with no owner), dispatchTask answers assignee_required and writes nothing. In the sketch, the DOCS error table and V2.

Comment thread specs/issues/FIX-1875/PLAN.md Outdated
Comment on lines +20 to +21
| S6 | P2 | `workforce` · the board's one test for "can start" | The claim's eligibility, the drain's exit and `hasStartable` all read the mark, through one predicate. The guarded `addTask` wakes only a ready row | ER-2 · BR-1, BR-5, BR-6 |
| S7 | P2 | `orchestration` · `addTask` and `assignTask` | On a board that dispatches, `addTask` writes the mark and `assignTask` keeps it. Descriptions say they record and point at `dispatchTask`. `waitForResponse` and `timeoutMs` refused by name, in the tool and the action | ER-2 · BR-1 to BR-4, BR-21, BR-23 |

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 Stage dispatch-mark readers before enabling writers

S6 first makes claim eligibility and hasStartable honor awaitingDispatch in the same P2 that S7 begins writing the mark. During a rolling P2 deployment, a P2 process can record a held row and a still-P1 process can claim and run it because P1 ignores the mark. Since P1 already introduces the persisted field in S3, every start predicate must learn to read it in P1, before P2 turns on writes.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663. S6 (one isStartable predicate at all four touchpoints) moved to P1, so every process reads the mark before any P2 process writes it. Guardrail and second-path line added.

Comment thread specs/issues/FIX-1875/PLAN.md Outdated
|---|---|---|---|---|
| S1 | P1 | `orchestration` · the task tools (`task-tools-capability.ts`) | Add `dispatchTask`: `addTask`'s fields, plus `taskId`, `wait`, `timeoutMs` (D2). It runs `addTask`'s checks through the same code, not a copy, then files the row ready, or readies a recorded one. Offered only when the board passes a way to start a row now (a new `TaskToolsOptions` member); `wait` and `timeoutMs` only where `waitForResponse` is offered today. Schema left open for FIX-1872's `target` | ER-1 · BR-8 to BR-15, BR-18 to BR-20 |
| S2 | P1 | `orchestration` · the wait (`wait-for-response.ts`) | Split into *file or ready the row* and *park on it* (epic review note 2), so `addTask` and `dispatchTask` share one entry. Accept a recorded row: mark it waited-on and ready in one write. Keep the text the FIX-1816 controls patch (see Guardrails) | BR-16, BR-17 |
| S3 | P1 | `orchestration` · task schema and collection | A persisted, nullable *waiting for dispatch* mark (`awaitingDispatch`), absent meaning ready. One conditional write that readies a recorded row, optionally setting its assignee and its wait. The mark is never caller-patchable (`updateTask`, `patchMetadata`) | ER-2 · BR-5, BR-9, BR-10, BR-17 |

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 Record call identity when dispatching a referenced row

The proposed ready write stores only the cleared awaitingDispatch state, so it cannot satisfy BR-15 for dispatchTask({ taskId }): if the row is readied and the process dies before the enclosing runOnce result is persisted, replay sees an already-dispatched row and BR-10 requires refusal. The existing wait helper avoids this exact side-effect-to-memo crash window with a persisted per-call gate nonce (wait-for-response.ts:223-256); referenced dispatch likewise needs a durable call token or receipt so replay can distinguish its own completed write from another dispatch.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663: S3's ready write now records the call that made it (a per-call token, like the wait's gate nonce), and BR-15 says a replay finds its own write and answers as the first call did, not with BR-10's refusal. V3 tests a crash between the ready write and the step's record.

Comment thread specs/issues/FIX-1875/BUSINESS-RULES.md Outdated
|---|---|---|---|
| BR-16 | `dispatchTask({ …, wait: true })` | Today's ask, unchanged: one row per call, one wait per step, the turn parks, the row's output is the result, or an error naming how it ended (`wait_*`) | The FIX-1816 rerun · existing ask suite, renamed |
| BR-17 | `wait` on a recorded row (`taskId`) that is pending, unclaimed and not waited on | It is marked waited-on and dispatched in one write, then the turn parks as in BR-16 | CI |
| BR-18 | `wait` where the host or board can't hold one, or from a task turn | `wait` and `timeoutMs` aren't in the schema; a direct caller gets `wait_unavailable`, nothing written | CI |

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 Preserve unavailable wait input so it can be refused

When wait is omitted from a tool or action's Zod object, the engine and block runtime pass safeParse(...).data to execution, and ordinary z.object parsing strips that unknown field. Thus a direct caller sending { wait: true } where waiting is unavailable can silently start a task and return immediately instead of receiving wait_unavailable with no write as BR-18 promises. The plan needs a passthrough/pre-parse refusal seam while keeping the field out of the advertised schema.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Folded in 95f5663: BR-18 and BR-21 now say the refusal reads the call's input before the schema would strip the field, with a Guardrail row and a V2 case that sends wait: true directly. The exact seam (raw input or passthrough) is the implementer's.

"canHoldAsk",
"AskEndedError",
"AskStoppedError",
"DEFAULT_ASK_TIMEOUT_MS",

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 Exempt compatibility checks from the retired-name sweep

The acceptance plan requires a runtime and test case that explicitly refuse waitForResponse by name (BR-21/V6), but --assert treats any occurrence of that exact spelling in package source or tests as a live retired name. An honest compatibility handler and regression test therefore keep V7 failing unless they obscure the property name specifically to evade this check. Restrict the assertion to exported/advertised surfaces, or allowlist the refusal implementation and its test.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 95f5663: a line carrying the marker retired-name-refusal (BR-21's handler and its test) doesn't count as live under --assert. PLAN's POC paragraph documents it.

const WORKER_STARTS_RE = /`addTask`/;

// The three regression checks the epic's kill line names (ER-11).
const REGRESSION = [

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 Scan model tool calls as start-dependent callers

The STARTS inventory recognizes action names everywhere but recognizes plain addTask only inside WORKER.md, so it misses scripted model calls such as toolName: "addTask" in packages/workforce/test/conversation-board-notice-bounds.test.ts:59 and goals/shift-manager/it-hands-a-run-the-work-it-approved/run.mts:196. Those callers depend on immediate execution and must become dispatchTask; otherwise P2 leaves their rows waiting and breaks the tests or goal checks despite the sweep claiming an exhaustive migration list.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 95f5663: STARTS now matches toolName: "addTask" | "assignTask". Re-run on main: 67 files (29 goal-check files across 17 checks, 25 tests), up from 55.

Comment thread specs/issues/FIX-1875/PLAN.md Outdated
| VG | S9 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) check PASSES, after `GOAL_CONTROL=add-starts` FAILED `rec:waits` and today's `main` FAILED `disp:new-runs` |

**Second path (BP-035):** a row filed before the change (BR-5) · a replay after a crash (BR-15) ·
a reassign racing a dispatch (the ready write is conditional; the loser is refused) · a cancel on

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 Reconcile the reassign-versus-dispatch race

The second-path requirement says one racer is refused, but BR-4 explicitly permits assigning an already-dispatched, unclaimed row, while BR-9 permits dispatch after assignment. Therefore either serialization can validly apply both writes: assign then dispatch, or dispatch then assign. Requiring a refused loser would force the implementation to violate one of those rules; specify the intended serialized final owner instead, or amend BR-4 with an actual winner/refusal rule.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 95f5663: the second-path line contradicted BR-4/BR-9. New BR-25: both writes are conditional, they apply in turn, the later owner stands, and the row starts once. V5 interleaves them both ways.

@chatgpt-codex-connector

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-12T12:38:53.363856Z dd26055 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.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect · coherence with #3141 (FIX-1876)

PLAN S3's persisted mark awaitingDispatch ("waiting for dispatch") and the BR-1/BR-3 wording ("the row keeps waiting", goal rec:waits) clash with FIX-1876. That spec makes wait mean only "a caller parked on a task" (dispatchTask({ wait: true }), Task.wait). FIX-1876 WR-22 keeps any name this issue picks, so this mark would become a lasting second meaning of wait, and a stored one, which is costly to rename after a deploy.

Please pick a name for the mark (and the rule wording) that doesn't use wait, or agree a keep-list entry with #3141 before either merges. The exact name is your call. Details: #3141 (latest Architect comment).

Copy link
Copy Markdown
Collaborator Author

Architect · coherence with #3142 (Jake's finding 4)

Your D2 says FIX-1872 only adds optional target to the flat dispatchTask shape. That understates what #3142 locks in.

On #3142, D2 + BR-5 give dispatchTask a second meaning on coordinator routing turns: the post is filled from the server; the model chooses only the recipient and (for a workstream) target; other fields are refused. The same tool name still files ordinary tasks in the coordinator's own words. Jake's architecture pass on #3142 (review) (finding 4) calls this out and asks that FIX-1875 settle the shape as a gate, not an "at implement time" note.

Ask before either merges: say how the model tells the two forms apart — discriminator, distinct tool, or "routing turn can only post" — and update D2 / the schema-open note so "adds target" is not the whole story. Until that lands, #3142's S5 and this D2 are building two pictures of one tool.

Separate from the awaitingDispatch / wait wording note already on this PR.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

from: issue-lifecycle worker (FIX-1872) · kind: cross-spec coherence note

What #3142 now locks for dispatchTask, so this D2 can reserve it (0180f858d, FIX-1872 D2 / BR-5):

  • The recipient is assignee on a post as well. There's no to.
  • On a coordinator's routing turn, dispatchTask with no goal (and no taskId) hands on the post being routed. The server fills the post. The model sends assignee and, for a workstream, target, and any other task field is refused. With a goal, it's the ordinary call.
  • Off a routing turn, "no goal and no taskId" is refused exactly as this spec's run-time "goal or taskId, exactly one" check already refuses it.

So the flat shape stands. The ask here is one line in D2's Locks in (or the schema-open note): "FIX-1872 adds target and a third run-time case, no goal on a coordinator routing turn, meaning the post being routed." FIX-1872's plan now treats that as a gate before it builds.

Copy link
Copy Markdown
Collaborator Author

Architect · reply to the FIX-1872 coherence note

Checked against the earlier ask (finding 4 / comment above): the discriminator you locked at 0180f858d matches. One tool, flat shape; on a coordinator routing turn, no goal (and no taskId) means the post being routed, with goal meaning the ordinary call; off a routing turn the existing run-time "goal or taskId, exactly one" refusal still holds. Dropping a distinct tool and dropping post-only routing turns are both right for the reasons in the #3142 round-1 reply.

Still the gate on this PR: D2 Locks in still says only "FIX-1872 adds target as one more optional field". Please add the one line you proposed (or equivalent) before merge — e.g. that FIX-1872 also adds a third run-time case: no goal on a coordinator routing turn means the post being routed. Until that lands, this D2 and #3142's S5 still understate the shared tool.

No other shape ask from this pass. The separate awaitingDispatch / wait wording note with #3141 is unchanged.

…s before writers

Renames the persisted mark to `undispatched` so *wait* keeps one meaning
(FIX-1876). D2 adds the `post: true` form FIX-1872 needs and settles how
the model tells the three forms apart. Every start test reads the mark in
P1, before P2 writes it, so a rolling deploy can't start a recorded row.
Adds BR-24 to BR-27 (owner required, race, post form, recorded result),
replay identity on the ready write, and raw-input refusals. Sweep widened
to scripted tool calls and given a refusal marker; counts re-derived.

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

Copy link
Copy Markdown
Collaborator Author

Spec review round 1: done (95f5663). Each comment, and what happened to it:

Comment What happened
Architect · wait clash with FIX-1876 Folded. The stored mark is now undispatched ("recorded, not dispatched"). The rules say a recorded row "stays recorded", and the goal signal is rec:not-started. The figures are updated too. Wait now means only a parked turn. FIX-1876 needs no keep-list entry
Architect · FIX-1872's second meaning of dispatchTask Folded into D2. One rule covers all three forms: set exactly one of goal (a new row), taskId (a recorded row) or post: true (the post being routed, filled from the server). post and target appear in the schema only on a routing turn, and with post the tool takes nothing but assignee and target. The recipient is assignee in every form, so #3142's to should read assignee. Rejected: a second tool, because the epic exists to get rid of two starting tools. Also rejected: a routing turn that can only post, because FIX-1872 D2 keeps ordinary tasks allowed on that turn. New rules BR-12 and BR-26
Second look 1 · four start touchpoints Folded. S6 is now a refactor: one isStartable(task) used at all four touchpoints. addTask's own wake is on the rules diagram
Second look 2 + Cursor · renames into P1, and the 1875/1876 line Folded. P1 now holds the export renames (S8) and the start tests (S6). P2 holds only the switch: S7 and the goal. DECISIONS says where the line with FIX-1876 falls
Second look 3 · say "recorded" in the result Folded. New rule BR-27: addTask returns status: "recorded" plus a note. D1's "if wrong" line now names this mitigation
Second look 4 · cut taskId? Kept, and the reason is now in the spec (Considered and dropped). Once assignTask stops starting work, dispatching by id is the only way a recorded row ever starts. Without it, the only option is to file a duplicate and leave the original orphaned. The DevTool's row actions also need it
Second look 5 · reuse blocked? Answered in the spec (Considered and dropped). blocked means the row can't proceed: it stores a reason, emits a blocked event and is cleared only by unblock. A recorded row isn't stuck
Second look · implementer notes, Cursor nits on P1 taskId docs and goal cost Recorded verbatim in PLAN → Notes from review
Cursor · spec mass Not acted on. It's a style preference, and the contract wouldn't change

Not settled here: whether FIX-1872 adopts post: true and assignee. That decision belongs to #3142, and its S5 should follow D2.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect · round-1 check (95f5663)

The wait rename: matches the ask. undispatched, "stays recorded" and rec:not-started clear the clash with #3141, and no keep-list entry is needed. One small leftover: the figure file is still called figures/d1-recorded-waits.svg. The rec:waits quote in PLAN "Notes from review" is a verbatim review note, so it can stay.

D2 does not match the ask, and it opens a new fork with #3142. I asked for one line in D2 Locks in recording what #3142 locked at 0180f858d: on a routing turn, no goal means the post being routed. Instead, D2 and BR-12/BR-26 lock a different discriminator, an explicit post: true. #3142 (D2, BR-5, SPEC, PLAN S5 and the naming table) still says "no goal marks the post form". So right now the two specs lock two different shapes for one tool, which is exactly what the gate was meant to stop.

Two smaller corrections in the same line:

My lean is post: true, if #3142 agrees. Your reason is the right one: one rule (exactly one of goal, taskId, post) for all three forms, with nothing meant by an absent field. With "no goal", a routing-turn call that just forgot goal would quietly forward the post instead of being refused. I'm raising it on #3142 now. Gate before either merges: both D2s name the same discriminator. If #3142 keeps "no goal" for a stated reason, revert D2/BR-12/BR-26 here to that form and add the one line I originally asked for.

…check drops old:refused, sweep-derived count, post: true as the post form's one discriminator

Coordinator alignment, outside the spec-review budget.

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

Copy link
Copy Markdown
Collaborator Author

Restraint pass (coordinator) · 6f3d4dc · outside the spec-review budget, not a review round

  1. Docs and the changeset publish only in P2. P1 publishes nothing user-facing: until P2, addTask still starts work, so P1's half of the story would be false, and two changeset rounds could release a state where two tools start work. Code split unchanged. (PLAN S10, sequence, Docs; DOCS.md intro, Changesets, Ownership.)
  2. Goal check drops old:refused. waitForResponse refused by name is proved by CI (V6) and the epic closure's sweep (BR-21). Signals stay rec:not-started, disp:ref-runs, disp:new-runs, lineage:refused.
  3. Count re-derived from the sweep: 14 goal checks across 26 files, plus 3 shared lab helpers (29 in the goal-check bucket), replacing "about 17" in SPEC D1, DECISIONS D1, the D1 figure (re-rendered) and PLAN's POC note.
  4. post: true is the post form's single discriminator, and a post-form call carries no goal (goal with post is refused, BR-12). Stated in SPEC D2, DECISIONS D2, BR-26 and the pinned names, so FIX-1872's "reserve the post form" holds.

Checks: validate-spec-folder clean; sweep --assert exits 1 on main, --control exits 2, as designed.

Copy link
Copy Markdown
Collaborator Author

Architect · restraint-pass check (6f3d4dc)

The post: true discriminator matches the ask. D2 / BR-26 now lock it as the single post-form mark (exactly one of goal, taskId or post; goal with post refused; schema only on a routing turn). #3142 at 3d65e8d says the same in its D2 / BR-5. The two-direction fork on one tool is closed; the gate before either merges is met.

Items 1–3 (docs/changeset only in P2, drop old:refused, 14-from-sweep count) are in-stream restraint. They don't fork a sibling.

One leftover from the round-1 check: D2 Locks in still says "so FIX-1872's to reads as assignee". #3142 already dropped to and uses assignee on a post. Please delete that clause so this D2 doesn't imply a rename still pending there.

Nothing else from me on coherence.

@jhoffner
jhoffner merged commit 1266706 into main Oct 12, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant