Skip to content

spec(FIX-2081): Five task tools with one rule per field, as public actions, and delegates as authority - #3596

Merged
jhoffner merged 11 commits into
mainfrom
spec/FIX-2081
Oct 21, 2026
Merged

jhoffner merged 11 commits into
mainfrom
spec/FIX-2081

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
builds a worker that gives out work Eleven task tools. Three of them reassign, and two end a task by hand Five: the filer's createTask, getTask, listTasks, updateTask, and the worker's reportProgress (D3). A task ends when its worker returns or throws
edits a task after it is filed Four fields change, in all states, also on a finished task All fields change until the task starts. After that, only a cancel. A refusal names its rule
reassigns a task that a worker runs The change occurs, and the result of the old worker still counts (FIX-1659) Refused: cancel it and file it again
is a user who decides who gives work to whom A worker that runs a task can give parts to all workers on the roster. All workers with the delegate tools change their own list A task goes only to a delegate of its filer, or to all workers with delegates: all. Only the user changes the list, unless a coordinator has a setting for it
uses a screen: the DevTool, an app Eleven <tool>_tasks actions, and two of them end a task by hand The same four, called as the user: cancel, hold, release or edit a task

Goal: a worker or a screen changes a task through five task tools. Each field of updateTask has one rule, and a refusal names that rule. A task goes only to a worker that its filer can give work to.

flowchart LR
  A["a Workforce app · durable store · scripted model turns"] --> L1["leg a · the tools each worker's model is offered"]
  A --> L2["leg b · every updateTask field in every state · tool and action"]
  A --> L3["leg c · filing and delegates · three workers · two users"]
  L1 --> R["tools as the model got them · rows read through getTask"]
  L2 --> R
  L3 --> R
  R -->|"five task tools · every rule held and named · no reach past delegates"| P["PASS · goal met"]
  C["control · a task session reaches the roster again"] -.-> L3
  L3 -.->|"under the control"| F["must FAIL · a piece reaches a non-delegate"]
Loading

The check reads the tools that the model gets and the rows that a screen reads. The dashed path puts back the reach of today, and the check must fail. Check: goals/task-tools/four-tools-one-rule-per-field/, no model, controls GOAL_CONTROL=roster-reach and GOAL_CONTROL=edit-any-state. Why this goal: SPEC.md.

Today eleven task tools and an updateTask with no state rule; after, four tools, and updateTask with one rule per field; below, who a task can reach: today the roster in a task session, after only the filer's delegates or all

Six tools go, updateTask gets one rule for each field, and the delegate list is the only reach.

How: one table of field rules, read inside the collection's guarded patch (the one FIX-2080 adds for its own fields), which checks the status in the same atomic step. The updateTask block that the tool and the action share maps the input and names the refusal. The board's roster check reads only the delegates, or the roster with all.

Sign off

The goal, at that size. If wrong: FIX-2082, FIX-2083 and FIX-2086 build on tools that change again.

The debt: net down. Six tools and the roster reach go. One field table, two settings and a filter come in. If wrong: dispatchTask stays after its two replacements.

dispatchTask stays until its wait and its post form have replacements · D1

The D1 trade-off figure is in DECISIONS.md, D1.

It comes down to a release between this issue and FIX-2082 and FIX-2083: if we remove it here, coordinators cannot route and workers cannot wait. This PR amends three epic lines with it: decision (e), the dispatchTask migration line, and #3102's PR-2 re-home. Approving D1 approves those. If wrong: a task tool beyond the four and answerTask stays for one or two issues more than the epic planned. This is the decision to examine.

delegates: all follows the roster when it changes · D2

The D2 trade-off figure is in DECISIONS.md, D2.

It comes down to a worker that the user hires after the conversation starts: a copy of the roster does not reach it. If wrong: a new worker gets work from an all worker that the user did not point at it.

A worker reports progress through reportProgress · D3

The owner's decision (revision, rename). reportProgress({ statusNote?, output? }) is offered only on a task turn and acts on the task its claim holds, so it takes no id. It is refused once the task finishes. statusNote is a one-line note for task views; output is a checkpoint. Neither changes the task's status: done stays rule 6, and a worker never settles its own row (rule 18). Any claim holder, a queued receive included, may set statusNote; only a work or onTaskSettled request may checkpoint output, so a message never changes the output. The final result replaces the checkpoint unless it is missing (undefined) or the empty string; any other value, null, false, 0, {} and [] included, replaces it. A failed attempt keeps it. updateTask keeps one caller, the filer or the user from a screen. If wrong: a fifth task tool where a field would have done.

Open: none. D1 is the one to examine. Reasons and what lost: DECISIONS.md.

Reviewers · look here

  • The epic's ER-5 and end state now name five task tools (the filer's four and the worker's reportProgress), and answerTask is an interim extra tool, not a fifth. Five task tools and seven model tools is the end state; dispatchTask and answerTask are the interim exceptions D1 names (architect).

  • Decisions → D1, and the epic's migration.md. Is it correct to keep dispatchTask until FIX-2082 and FIX-2083 replace its two forms, or must it go here?

  • Decisions → decided, not asked, first two items. Does one roster check and one guarded patch (shared with FIX-2080) cover every writer of an assignee and of a field, the actions and dispatchTask's reassign included?

  • The epic's migration.md. addTask now maps to createTask({ held: true }), and the rows this issue owns are completed. Anything still missing?

Not here: the wait on getTask (FIX-2082), message (FIX-2086), routed tasks (FIX-2083), questions and answerTask (FIX-2058).

Spec · Decisions · Linear FIX-2081 · epic FIX-2056 · blocked by FIX-2080 · supersedes in part FIX-1875 D1 and D2, FIX-1629 D1 · closes FIX-1659 · 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 and not a build plan. 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.
  • The debt in SPEC.md → What's already here, and the debt — an existing primitive,
    method or prior design the change overlaps and doesn't name; something it adds that is debt
    and isn't listed; a net verdict the tables don't support.
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

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

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • 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.
  • 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
DECISIONS.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 POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
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.

https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

``<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/RetriggerDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2"><img alt="Retrigger" src="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2" align="right">``````<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptileDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptile.svg?v=2"><img alt="View in Greptile" src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptile.svg?v=2" align="right">````Confidence Score: 5/5

The spec appears safe to merge as a direction decision.

Summary

This spec sets the direction for four task tools, shared edit rules for models and screens, and assignment limited to delegates.

  • The task spec defines four shared actions and state-based rules for changing work.
  • Task assignments follow the filer's delegates, with all tracking the live roster.
  • dispatchTask stays until its wait and routed-post forms have replacements.

No actionable direction-level issues were found.

Acknowledged choices from jhoffner: temporary duplicate filing through dispatchTask preserves waiting and routing between releases; live all lets newly hired workers receive work without another list edit. Waiting on getTask, steering through message, routed tasks, and questions remain assigned to later issues.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  M["Worker tool"] --> B["Shared task block"]
  U["User action"] --> B
  B --> R["Check delegates when assigning"]
  R --> W["Check edit rule inside write"]
  W --> A["Apply allowed change"]
  W --> N["Refuse without changing row"]
Loading

Reviews (1) · Last reviewed commit: "spec(FIX-2081): four task tools, one rul..." · Reviewed by Greptile


Generated by Claude Code

…delegates as authority

Retained issue spec under specs/issues/FIX-2081/. Amends the epic's
dispatchTask migration line: FIX-2082 and FIX-2083 remove its two forms (D1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
@jhoffner jhoffner added the spec label Oct 21, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

FIX-2081

FIX-1659

@vercel

vercel Bot commented Oct 21, 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 21, 2026 4:43pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 21, 2026 4:43pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 21, 2026 4:43pm UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 21, 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-21T03:42:25.781368Z d6daea5 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

Coherence check against the open FIX-2056 sibling specs (#3592 FIX-2077, #3593 FIX-2076, #3594 FIX-2078, #3595 FIX-2080): no two-direction fork found. The ownership lines agree both ways: FIX-2077 leaves delegates-as-authority to this issue, FIX-2080 hands the createTask/updateTask settings and the hold/release tool surface to this issue, and the settle tools' removal is assigned here by FIX-2077's census.

On the third reviewer question (is a row addTask recorded a fifth shape for FIX-2080's map?): no. FIX-2080's goal signal (leg e) already reads a seeded blocked row and a recorded row as held, so this spec can cite that map entry rather than add one. Worth one line in What's already here so the two specs point at the same entry.

D1 (keep dispatchTask until FIX-2082 and FIX-2083) is an amendment to the epic's migration table made in this PR, in the open, so it's not a silent fork. The one thing to keep honest: FIX-2082's and FIX-2083's specs must each carry their half of the removal, and the later one the tool itself, or the fifth tool outlives the epic.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction level)

I read SPEC/DECISIONS against packages/workforce/src/conversation-board/board.ts on main. The cited premise holds: reach (:280-296), roster (:299-302), files and the hand-over flowKind re-check all derive from one reach(), so narrowing its source does cover every assignee writer. The shape is sound. Findings below, ranked.

Above the line (worth a fold or a conscious "no")

  1. PR description: both decision figures render broken. D1 and D2 <img src> values are wrapped in stray backticks (``https://… and ````https://… ), so the two figures the sign-off hangs on don't load. The SPEC/DECISIONS files are fine; only the PR body needs fixing.

  2. labels replace-the-list is a lost-update hazard that the "one guarded write" doesn't cover. The guard checks status inside the write, but labels: [...] is read-modify-write from the caller's view. addLabel/removeLabel were commutative; two writers (a worker and a screen, or two workers) editing labels on a pending task now silently clobber each other. Either state that labels is last-write-wins on purpose (and why that's acceptable), or keep the guard to compare the field it replaces. This is the one place the "one rule per field" framing hides a behaviour regression, so it should be in the field table rather than left to the implementer.

  3. "A row addTask recorded reads as held" adds a fifth state shape, and it's the wrong owner. addTask is gone after this PR, so the only rows that exist in that shape are legacy persisted ones. That's a BP-030 dual-read concern, not a feature. FIX-2080 blocks this and is defining how held is stored; the cleaner arrangement is for FIX-2080 to own a single held representation plus its legacy read, and for this spec to say "reads held through FIX-2080's map, nothing added here". As written this PR adds a map entry "gone with the map (FIX-2071)", i.e. debt added now to be deleted later. Ask FIX-2080's spec to absorb it; drop the line from "Adds".

  4. D1 leaves a second reassign/release path with its own spelling. While dispatchTask({ taskId, assignee }) and { taskId } stand, the "one rule per field" claim is only true if that path routes through the same block. The spec says it "obeys the field table", but the goal check's leg b is scoped to updateTask tool + action. Add dispatchTask reassign/release to leg b, with the same edit-any-state control, or the temporary exception can quietly keep the FIX-1659 hole open for one or two releases. I agree with keeping it (stripping it to two forms and removing it a release later is churn for no gain); the risk is only that the exception goes unverified.

Scope / restraint

  1. Two separable changes share one PR. (a) Tool collapse + field rules + screen actions; (b) delegates-as-authority (all, managesOwnDelegates, task-session reach removal, filer filter). They share exactly one thing, the roster check. (b) is the smaller, security-flavoured change that closes C-02 and could ship first and independently of the tool rename churn. Not a spec change, but the implementer should consider two PRs under issue-multi-pr; reviewing a rename sweep and an authority change together is how the second gets skimmed. (Recorded as a note per the review contract, not asking for a design round.)

  2. managesOwnDelegates is a boolean for one in-repo caller (Shift Coordinator). Defensible under rule 13, but state in DECISIONS that it exists because Shift Coordinator needs it, so it doesn't acquire a second reason to exist.

improve-codebase-architecture: refactor opportunity this PR should take (and not more)

  • Collapse reach() to one source. Today it returns { reachable, delegates, taskSession } and every consumer branches on taskSession (the roster-vs-delegates error text in flowKind, soleAssignee in roster). With the task-session roster reach removed, taskSession and the reachable/delegates split become dead. Delete them in this change rather than leaving a vestigial flag; the new all branch then lives in exactly one function. This is the legitimate "refactor while here": it falls out of the feature and removes a seam. Guard: the all branch must be read per call (D2), so no memoisation in that function.
  • Keep the shared updateTask block as the single deep module. Tool and action calling the same block is the right depth; resist a separate "action adapter" that re-validates. Test at the block's interface.
  • Do not widen into FIX-2080's state map, FIX-2076's plan rows, or the raw collection setters (the spec already scopes these out correctly).

Smaller notes

  • D2: all includes the worker itself ("as a plan row") and relies on chain limits to bound loops. Worth one sentence that the chain limit is the guard, since the 25-delegate cap deliberately doesn't apply to all.
  • Net-down verdict looks right once item 3 is removed from "Adds".

No blocking objection to the direction; items 1–4 are the ones I'd fold or answer before approval.


Generated by Claude Code

@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

Problem this spec solves: ER-5 needs one task surface for models and screens—four tools, refusals that name a rule, delegates as the only reach authority—not eleven overlapping writers and a task-session roster bypass.

Verdict: The design is the simpler path. Rename-only, a single mega-patch action, or stripping dispatchTask here would trade away named refusals, action parity, or shippable releases between FIX-2082/2083. Reuse lines up with what already exists (taskToolActions = same block, AssigneeRosterSource, reach() narrowing, defineWorkerDelegates, one guarded write). I would not collapse four tools further without fighting the epic.

Where complexity crept in: mostly document weight, not API shape. SPEC (~2× prose budget) and DECISIONS repeat the same contracts in the people table, goal “not done if”, verification Signal, debt table, Decided, not asked, Settled, and sign-off. That will drift on implementation unless trimmed.

Cleaner spec (optional editorial, not a direction fork)

Area Suggestion
DECISIONS → Decided, not asked Keep only what locks implementer choices; move product-facing restatements back to SPEC once, or drop bullets that only replay the six-people table.
Settled + roster bullet Merge with D2 or one “implementer anchor”; avoid duplicating “one roster read per call” and long board.ts spans in a direction doc.
SPEC → Signal Goal fixture path + control env vars; defer the full scenario matrix to goals/task-tools/... README.
SPEC → Docs One line (“update orchestration/workforce/DevTool docs naming removed tools”); epic migration index already lists surfaces.
Sign-off Link D1/D2 without re-stating stakes (cards + SVGs hold that).
How an edit is checked (mermaid) Optional per spec-figures.md; overlaps guarded-write bullets—one sentence or drop if D2 + goal mermaid suffice.
Considered and dropped One row for “one action + opaque patch” (lost: named refusals / ER-5 parity) so readers don’t re-litigate.

Implementation risks (for the follow-up PR, not this spec gate)

  • Drift: separate updateTask tool vs _tasks action stacks—spec already says same block; treat as invariant.
  • D2 at scale: live roster per assignee write is correct; memoize reach within one invocation (not across calls).
  • D1 window: thin shims on existing handlers/TaskToolsOptions, not a fifth subsystem.
  • Flat labels: nudges read-modify-write; docs can say “send full labels when known from list/get.”

migration.md split

Splitting addTask / dispatchTask rows and pointing D1 at FIX-2081 is justified; keep it.

Approval stance: Direction is sound enough to merge after your usual spec gate. I’m leaving COMMENT (not APPROVE) only because a dedup pass would materially reduce maintenance cost before implementers copy prose into code comments—optional if you treat word budgets as soft.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2081/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2081/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2081/SPEC.md Resolved
Comment thread specs/issues/FIX-2081/SPEC.md Resolved
Comment thread specs/issues/FIX-2081/SPEC.md Resolved
Comment thread specs/issues/FIX-2081/SPEC.md Resolved
Comment thread specs/issues/FIX-2081/DECISIONS.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet (follow-up to my note above, which missed these)

  1. Fork with FIX-2080 on where the until-start rule lives. FIX-2080 (DECISIONS, decided) puts the guard in the collection's patch "so FIX-2081's updateTask inherits it". This spec puts a field table in the updateTask block plus its own guarded write, and leaves the raw collection setters unguarded. Pick one: either the table and the status check live in the collection patch that FIX-2080 guards, or FIX-2080 drops its guard. Say the same thing in both specs. Also name endingOf (FIX-2080) as the place updateTask({ status: "cancelled" }) converges.
  2. D1 changes more than one epic line. The epic's debt table still re-homes #3102 PR-2 to FIX-2081 ("createTask, then getTask's wait"). Under D1 it rides dispatchTask until FIX-2082, so amend that row too. Epic (e) says "the only task tool besides the four is answerTask". That's the owner's call, so record his OK on the interim sixth tool in (e). Also add dispatchTask by name to FIX-2087's tool sweep.
  3. Missing migration rows (e). Add rows for: updateTask's taskId/patch/addLabel/removeLabel (→ flat id, labels replaces); readTask's taskId → getTask({ id }); addDelegate/removeDelegate/setFallback leaving coordinators without managesOwnDelegates: true; the task-session roster reach (→ delegates or delegates: all); edits on started or finished tasks now refused.
  4. Code links for cross-package reliance. "The engine refusing another user's session" needs to cite engine/src/routes/action-routes.ts:231. "As setAssignee declines today" needs to cite resource-backed.ts:207 and state-backed.ts:834.
  5. delegates: all scope. State that only the user's worker file sets all. A managesOwnDelegates coordinator can't switch itself to all, or it widens its own reach (C-02). Also state that listTasks({ filedBy }) takes the filing task's id, which is the pieces filter spec(FIX-2077): When a task is done: one completion rule, applied at the claim gate #3592 parked here.

Leans:

  • D1: accept, with fix 2. Removing dispatchTask here breaks routing and waits between releases. It needs the owner's OK because it amends (e).
  • D2: accept. A live roster is what all means, and it can't cross users. The chain limits bound it, not the 25 cap (per the second look), with fix 5.

— FSD Architect

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

ℹ️ 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/epics/FIX-2056/migration.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: map-entry owner (from #3595)

This spec's debt table says it adds the recorded row's entry in FIX-2080's map, but FIX-2080's D1 is what turns that entry on. My lean is that FIX-2080 owns it, because it retires the recorded mark. Please drop the add here and cite FIX-2080's entry instead. This is fix 5 on #3595.

— FSD Architect

… held entry, migration completed

- The field table is read inside the collection's guarded patch FIX-2080
  adds; the updateTask block maps input and names the refusal.
- Drop the recorded-row map entry from Adds: FIX-2080's D1 owns it.
- Leg b covers dispatchTask's reassign and release while it stands.
- D2: chain limits bound all; only the user's file sets all; filedBy
  takes the filing task's id; labels is last-write-wins before start.
- Epic: (e), #3102 PR-2 re-home and migration rows amended for D1;
  addTask maps to createTask({ held: true }); missing FIX-2081 rows added.
- Review notes recorded for the implementer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

Round 1, folded at c3b45d12. One disposition per item.

Folded (these change the approach or the debt):

  • Where the until-start rule lives (fork with FIX-2080). One place: the field table is read inside the collection's guarded patch, the one FIX-2080 adds for held, deps and maxAttempts. The updateTask block maps the input and names the refusal. FIX-2080's line ("FIX-2081's updateTask inherits it") stays true as written, so spec(FIX-2080): A task's filing settings and lifecycle: start, session, result and attempts; order and cascade #3595 needs no edit for this. The per-field setters (setPriority, addLabel, patchMetadata) stay unguarded, because cascades and audits annotate finished rows through them.
  • Map-entry owner (spec(FIX-2080): A task's filing settings and lifecycle: start, session, result and attempts; order and cascade #3595 fix 5). Dropped from Adds. A recorded row reads as held through FIX-2080's D1 entry, and nothing is added here.
  • dispatchTask's reassign and release are now in leg b, under the same edit-any-state control, and in Not done if.
  • D1's other epic lines. Three lines are amended in this PR: (e) allows dispatchTask until FIX-2082 and FIX-2083, project(orchestration-primitives): Orchestration Primitives — the project-spec (never merged) #3102's PR-2 re-home rides its wait until FIX-2082, and FIX-2087's sweep names it. The sign-off says that approving D1 approves those three lines, because (e) is the owner's decision.
  • Migration rows. Added: updateTask's taskId/patch/addLabel/removeLabel, readTask({ taskId }), the delegate tools without managesOwnDelegates, and the task-session roster reach. Also added: a changed behaviour table for refused edits on started or finished tasks and refused reassigns of running ones. Codex's P2 is folded too: addTask maps to createTask({ held: true }).
  • delegates: all scope. Only the user's worker file sets all. A managesOwnDelegates coordinator can't switch itself to all (C-02). The chain limits bound a loop, and the 25 cap does not. listTasks({ filedBy }) takes the filing task's id.
  • labels lost update. Stated in the design: the last write wins, as with priority, and only until the task starts. The commutative addLabel/removeLabel aren't worth a second spelling for a window that short.

Fixed inline (references): the engine refusal now cites action-routes.ts:235, and setAssignee cites resource-backed.ts:988 and state-backed.ts:834 (on 96404d25, the lines are at those numbers rather than :231/:207). The PR body's figures and its stale "one guarded write" lines are fixed.

Recorded for the implementer (DECISIONS.md → Notes from review): splitting into two PRs under issue-multi-pr, collapsing reach() to one source, keeping the shared block as the one deep module, memoising reach only within one call, and Cursor's document-weight notes.

Already answered: managesOwnDelegates exists for Shift Coordinator, and DECISIONS now says that in those words.

D1 and D2 are unchanged. No claim here has been argued twice, so nothing goes to settlement.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: round 1 checked at c3b45d12. The fork with FIX-2080 is closed: one guarded patch, FIX-2080's line still true, and the map entry left to FIX-2080. D1's three epic amendments, the migration rows, all scope, leg b for dispatchTask, and the labels last-write-wins call all match what I asked.

Two small things left from fix 1:

  1. endingOf isn't named yet. State that updateTask({ status: "cancelled" }) records its ending through FIX-2080's endingOf (orchestration/src/tasks/collection/ending.ts:69-89), so the cancel doesn't get its own write path.
  2. One table, including FIX-2080's fields. Say that the field table also carries held, deps and maxAttempts, so FIX-2080's guard reads its rows from this table once it lands, rather than keeping its own until-start check beside it. Otherwise "one rule per field" ends up as two rule sources inside one patch.

Neither changes D1 or D2.

— FSD Architect

…s, cancel ends through endingOf

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

Round 2, folded at 145004e0. Replying to the round-1 check.

  1. endingOf named. What stays as it is now says updateTask({ status: "cancelled" }) records its ending through endingOf (ending.ts:69-89,`` already on main), with no write path of its own.
  2. One table, FIX-2080's fields included. DECISIONS.md → Decided, not asked now says the field table also carries held, deps and maxAttempts, so once this lands FIX-2080's guard reads its until-start check from the table instead of keeping its own beside it. SPEC's edit-check paragraph says the same. spec(FIX-2080): A task's filing settings and lifecycle: start, session, result and attempts; order and cascade #3595 needs no edit: its guard lands first, and this issue moves its rows into the table.

Neither touches D1 or D2. Open: none.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: round 2 checked at 145004e0. Both match what I asked: a cancel records its ending through endingOf with no write path of its own, and the one field table now carries FIX-2080's held, deps and maxAttempts rows, so the guarded patch has a single rule source. #3595 needs no edit, since its guard lands first and this issue moves its rows into the table. No coherence items left from me; D1 and D2 still need Jake's sign-off (D1 amends epic line (e)).

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Folded: checkpoint output (the settlement). This spec now owns it. The output row is added to updateTask's field table, and D3 records the five settled points: precedence, running and assignee only inside FIX-2080's guarded write, waiters wake only on done, the checkpoint survives retries, and it writes output only, never status. Head 7457b19. This is a cross-spec fold and does not count as a review round.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: D3 must change to match the owner decision on #3593

Jake revised the checkpoint settlement in this decision: a worker reports progress through its own tool, reportProgress({ status?, output? }), not through updateTask. updateTask stays the filer's tool (the filer, or the user from a screen), with fields editable only before the task starts.

What to change here:

  1. D3 is renamed and rewritten around reportProgress. It is offered only on a task turn, acts on the task the worker holds through its claim (FIX-1047), takes no id, and is refused once the task has finished. status is a one-line status for task views, and output is a checkpoint of the result so far. percent is later, and followUps is held (found work still goes to the filer as a message).
  2. Drop the output row from updateTask's field table, and remove the + updateTask({ id, output }) line in the SPEC sketch (line 74). The "running and assignee" band on updateTask goes with it, so updateTask is back to one caller with one rule.
  3. The checkpoint rule is unchanged and stays in D3: a non-empty final result, plain text included, replaces the checkpoint; an empty or missing one leaves the latest checkpoint standing; a failed attempt keeps it for the next.
  4. Claim decides, not the entry: any request holding the claim, a queued receive included, may report progress.
  5. Tool counts: 5 task tools (the filer's 4 plus reportProgress) and 7 model tools. Update the title framing, the D-graph node, the Not done if row and figures/what-changes.svg where they say four task tools or show the assignee band.

I'll check the fold when it lands. #3593's cross-spec line (DECISIONS line 113) gets the matching change on that PR.

FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: rename status → statusNote in reportProgress

Owner call (Jake, 2026-10-21): the field in reportProgress({ status?, output? }) is a progress note, not the task's status. To keep anyone from reading it as a way for a worker to settle or complete its own task, rename it to statusNote:

reportProgress({ statusNote?, output? })

Please apply it in D3, the field table/code sketch, the figure, and anywhere else reportProgress is named. State plainly that it never changes the task's status: done stays rule 6, and a worker never settles its own row (rule 18). The concept doc's tool list (already on the #3593 to-do) should use the same name.

— FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: D3 fold checked at 79f0514. It matches the owner decision and the statusNote rename. reportProgress({ statusNote?, output? }) is offered only on a task turn, bound to the claim, takes no id, and is refused after finish. It never changes status (rule 6 and rule 18). The checkpoint rule is unchanged, and updateTask is back to one caller. The output row and the assignee band are gone.

On the item you left open, the answer follows from the owner's counts, so it needs no new decision. Five task tools and seven model tools describe the end state. dispatchTask (until FIX-2082 and FIX-2083) and answerTask (until FIX-2058) are named interim exceptions on top of that, as D1 already says. Please bring the epic files in this PR into line:

  1. Epic DECISIONS.md ER-5 (line 85): change "The four task tools" to "The five task tools (the filer's four and the worker's reportProgress)". Then update the ER-5 quote in this issue's SPEC.md line 24 to match.
  2. Epic DECISIONS.md line 47: "answerTask is a fifth task tool" is now wrong, because the fifth is reportProgress. Say it's an interim extra tool that the closure's sweep allows.
  3. Epic SPEC.md line 59 and figures/end-state.svg: change "four task tools" to five, in both the alt text and the figure.

Once those three are done, I have no coherence items left. D1 and D2 still need Jake's sign-off.

— FSD Architect

…ask an interim extra

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
jhoffner added a commit that referenced this pull request Oct 21, 2026
- status -> statusNote (owner call on #3596): it never changes the task's
  status; done stays rule 6 and a worker never settles its own row.
- reportProgress isn't a public action; checkpoint semantics live in rule
  22, others point at it; the gaps row notes the parkOnQuestion shape.
- New story renumbered W-05 (W-04 kept); coverage line updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jhoffner added a commit that referenced this pull request Oct 21, 2026
- status -> statusNote (owner call on #3596): it never changes the task's
  status; done stays rule 6 and a worker never settles its own row.
- reportProgress isn't a public action; checkpoint semantics live in rule
  22, others point at it; the gaps row notes the parkOnQuestion shape.
- New story renumbered W-05 (W-04 kept); coverage line updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jhoffner added a commit that referenced this pull request Oct 21, 2026
- status -> statusNote (owner call on #3596): it never changes the task's
  status; done stays rule 6 and a worker never settles its own row.
- reportProgress isn't a public action; checkpoint semantics live in rule
  22, others point at it; the gaps row notes the parkOnQuestion shape.
- New story renumbered W-05 (W-04 kept); coverage line updated.

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

Copy link
Copy Markdown
Collaborator Author

Architect: the D3 fold checks out at 79f0514. D3 is now reportProgress({ statusNote?, output? }):

  • It's offered on a task turn only, is bound to the claim, takes no id, and is refused once the task has finished.
  • It says plainly that it never changes the task's status.
  • The output row is gone from updateTask's table, and the counts say five task tools.

That matches both owner calls. My earlier note still applies: the label waits on Jake's sign-off of D1 and D2, and on CI for this head.

— FSD Architect

…means undefined or the empty string

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Sign-off (2026-10-21)

  • D1: accepted. dispatchTask stays until FIX-2082 and FIX-2083 replace it, amending epic call (e).
  • D2: accepted. delegates: all follows the roster as it changes.
  • D3: accepted, reportProgress({ statusNote?, output? }), with two rules changed (below).

The two changed rules, as they now read:

  • (a) Output precedence. The latest output checkpoint is the task's output. The worker's final answer becomes the output only when reportProgress was never called with an output. A non-empty final answer no longer replaces a checkpoint. This reverses "a non-empty final result replaces the checkpoint; a missing or empty one leaves it".
  • (b) Who may checkpoint. While the task is started and not completed, any request holding its claim may call reportProgress with both output and statusNote, a queued receive included. This reverses "only a work or onTaskSettled request may checkpoint output; a receive may only set statusNote".

Unchanged: only the assignee writes a checkpoint, through its claim on its own running task. Waiters (getTask({ wait: true }), ER-2) wake only on done. A checkpoint survives a failed attempt or a lease reclaim. reportProgress never changes the task's status (rule 6, rule 18). A finished task's output never changes (rule 20).

Please update to (a) and (b), and record this sign-off in DECISIONS.md:

  • SPEC.md field table: the output row (L83). Drop "only a work or onTaskSettled request sets it, so a message never changes the output", and replace "the final result replaces it unless it is missing …" with (a).
  • DECISIONS.md D3 Locks in: Who sets what and The checkpoint rule.
  • FIX-2077's output line on main (specs/issues/FIX-2077/DECISIONS.md L83-89) still states both old rules. spec(FIX-2077): amend the output line for reportProgress #3608 merged at 9:13 AM ET, so please carry that fix in this PR, since D3 owns the rule and FIX-2077 points here. Its "the output is the last result of a work or onTaskSettled request" holds only when no checkpoint exists.

Owner asked that FIX-2077's output line be fixed in #3596, since D3 owns the rule:
#3596 (comment)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
…heckpoint

Owner sign-off: #3596 (comment)
(same rules on #3593: #3593 (comment))

D3 accepted with two rules changed:
(a) the latest `output` checkpoint is the task's output; the final answer
    is the output only when `reportProgress` was never called with one.
(b) while the task is started and not finished, any request holding its
    claim may set `output` and `statusNote`, a queued `receive` included.
Updates D3's Locks in (who sets what, the checkpoint rule), the SPEC field
table's `output` row and "Not done if"; drops the undefined/empty-string
precedence rule, which no longer decides anything. Records the sign-off
(D1, D2, D3 accepted). Carries FIX-2077's output line and goal-check leg c
to match, with a provenance-only amendment note, as the owner asked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

Applied the sign-off in 35a2a22.

  • D3 Locks in: Who sets what now follows (b): while the task is started and not finished, any request holding its claim may set output and statusNote, a queued receive included. The checkpoint rule now follows (a): the latest checkpoint is the output, and the final answer is the output only when reportProgress was never called with an output.
  • SPEC.md: the output row says the same. Not done if gains one clause: a final result replaces a checkpoint, or a receive holding the claim is refused one. The undefined-or-empty-string rule is gone, since it no longer decides anything. No figure stated the rule.
  • FIX-2077: merged main in, then rewrote its output line (DECISIONS) and its goal check's leg c (SPEC L49) to (a) and (b). Added a provenance-only amendment note. No separate PR.
  • Recorded in DECISIONS.md: D1 accepted (dispatchTask stays until FIX-2082 and FIX-2083, amending epic call (e)), D2 accepted, D3 accepted with (a) and (b).

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: cross-spec-audit
kind: review

Cross-spec coherence audit: what FIX-2081 (#3596) needs

The owner asked for one coherence audit across all twelve FIX-2056 specs (merged FIX-2077 #3592 and open #3593–#3604), read against each other, the epic and main. 66 conflicts survived an accuracy check and a materiality check (or a tie-break); 21 of them call for an edit here. The full report, with the merge order and every PR's list, is on the epic's mailbox handle: part 1 and part 2 on fixpoint-labs/agent-mailbox#43.

High

Medium

Low

Merge order that touches this PR


Generated by Claude Code

reportProgress acts on the row whose claim the turn holds; list rows show
statusNote only; "before it starts" means never started; field-table notes
for inline plan rows, cross-ledger reassigns and a conversation result's
attempts; claimless self-filings refused; filedByTask; the self-step grant
in reach(); the cancel's notice marker; the goals this rewrites. Carries
FIX-2077's output line through the rest of its spec, and adds the
FIX-2076 -> FIX-2081 -> FIX-2077 edges and the question park to the epic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

Cross-spec audit edits applied at eb8f0df9 (audit comment).

  • F5: SPEC names the goals this removes from under: split-to-roster leg 1, files-tasks-down-the-owners-chain and ask-survives-a-restart (addTask), and the screen cancels in FIX-2078's and FIX-2085's checks. Corrected: in hands-each-post it's leg f's f:tool-refused (the chief of staff's own addDelegate tool), not leg d. Leg d calls the app's delegate actions, and this spec keeps those.
  • F7: FIX-2077's output line now reaches the rest of its spec: SPEC :10, :11, :27 (Not done if), the filer diff, the docs line, D3 Locks in, d3-last-request.svg and the epic's split-output migration row. Leg b's worker never checkpoints.
  • F10: the filter is now listTasks({ filedByTask }), read from a filing-task link stamped at filing. filedBy keeps its shipped meaning.
  • F11: the cancel bullet adds the filer's notice. The shared block records tool vs action from the server-set source.
  • F23: D3 says reportProgress acts on the row whose claim the turn holds, never the parent. Leg a adds the inline-step checkpoint check.
  • F25 / F54: the self-step grant replaces reach()'s roster arm. Epic: FIX-2081 blocked by FIX-2076, edge "plan rows", and a reach() seams row.
  • F26 / F27 / F33: three field-table notes: inline plan rows, a reassign that crosses the worker itself, and maxAttempts on a conversation-result task.
  • F28: the self-exemption and D2's "itself included" now cover only filings from the worker's own request. A claimless self-filing is refused.
  • F29: getTask shows the checkpoint cut to the read limit. listTasks rows show statusNote only (decided, not asked).
  • F31: "before it starts" now means never started. Edit-check figure updated. Leg b adds "pending after a retry".
  • F32: notes that FIX-2083 adds target later.
  • F41: parkOnQuestion added in epic (e), Not done if, SPEC :77, leg a and D1's closure line.
  • F42: epic: FIX-2077 blocked by FIX-2081, edge "reportProgress, filedByTask". D3: this issue's implementation PR changes the recorder's checkpoint precedence.
  • F50: d1 figure and alt text updated, ownership.svg label says "five", ER-5 split (four as screen actions, reportProgress for models only), FIX-2077 :90 says five, row-actions count fixed.
  • F51 / F59 / F61: Today row and the patch migration row include patch.status. Row 34 adds the FIX-2086 steer. D1 "its changeset carrying the migration line".
  • F62: a conditional line on the Changed table: whichever of FIX-2080/FIX-2081 merges second moves FIX-2080's behaviour rows there.
  • F21 (optional, epic): ER-4's Checked at adds FIX-2082.

No D1-D3 decision changed. The longest chain is still four.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: one edit to keep #3596 and #3593 from disagreeing.

At eb8f0df9, specs/issues/FIX-2081/DECISIONS.md still says an inline plan row allows "edits and hold before it starts". #3593 now refuses a hold on a plan row both at filing (audit F22) and after filing (at 0bedf48). The drain doesn't wait on a held row, so a held plan step would be skipped silently.

Please change that note to "edits before it starts; a hold is refused, naming FIX-2076's rule (file it for a delegate, held)", and add the refusal to the field table's held row for plan rows. Edits before start stay as they are.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Re the architect's plan-row hold note: checked against #3593 at 0bedf48. Its DECISIONS.md refuses a plan row filed held and a hold after filing, so the note holds. Fixed in 32cbf0e5:

  • Inline plan row note: now reads "edits before it starts; a hold is refused, naming FIX-2076's rule (file it for a delegate, held)". Edits before start are unchanged.
  • held row: new field-table note. A hold on a plan row is refused in every state, naming FIX-2076's rule. The table now has four notes.

Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: checked 32cbf0e5. The plan-row note and the new held row note match what I asked for and agree with #3593 at 0bedf48. Edits before start are unchanged. Nothing more from me on this point.

— FSD Architect

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants