Skip to content

spec(FIX-1802): Any worker can file work, and a filed task can be split down the chain - #2839

Merged
jhoffner merged 11 commits into
mainfrom
spec/FIX-1802
Oct 7, 2026
Merged

jhoffner merged 11 commits into
mainfrom
spec/FIX-1802

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
wants one of their workers, not a coordinator, to hand out work Only a coordinator's conversation files tasks They list the workers it hands work to in its file's delegates:. When one of them takes a task, the worker gets the task tools and files onto its own conversation's board, for those delegates, on any flow
gives a worker a big task The worker does all of it. A task session that tries to file is refused The worker splits the task. It files the pieces on its own board, waits, and its task finishes with what the pieces returned. Up to five boards deep
gives a worker no delegate that takes a task (a routing coordinator, or a worker with no delegates) n/a The worker gets no task tools, and the app cannot add tasks on its conversations. Nothing is refused at load
runs a worker on their own app flow (the DevTeam's EM, flow: em) Filing is in the coordinator flow only The flow puts Orchestration's existing task tools on its model's block and their actions on the flow, wired to Workforce's session board. The worker keeps its flow
builds a worker that keeps splitting n/a It stops at five boards deep, or at 100 tasks under one top task, a cap the app can raise. A filing past either is refused as a full board is

Goal: any worker whose file lists a delegate that takes a task, on any worker flow, files work for those delegates onto its own session's board. A worker that gets a task can split it the same way. Every session in the chain is the owner's, the chain has limits, and each result comes back up, board by board, to the session that filed the top task.

flowchart LR
  A["Shift Manager · two users · goal-local workers"] --> L1["a · an agent worker files · its delegate splits"]
  A --> L2["b · an app flow's worker files"]
  A --> L3["c · no task-taking delegate · nothing files"]
  A --> L4["d · the limits"]
  A --> L5["e · a real model splits"]
  L1 & L2 & L3 & L4 & L5 -->|"boards, sessions and notices match"| P["PASS · the goal is met"]
  C["control · delegates aren't checked"] -.-> L3
  L3 -.->|"under the control"| F["must FAIL · a worker with no task-taking delegate files"]
Loading

The check files through the app and the tools. Then it only reads boards, sessions and notices. Check: goals/workers/files-and-splits-down-the-chain/. Controls: GOAL_CONTROL=no-delegate-check must fail leg c, and GOAL_CONTROL=no-parent-settle must fail leg a. Why this goal and not a smaller one: SPEC.md.

Two panels. Today only a coordinator conversation files, and a task session that tries to file is refused. After, any worker whose file lists a delegate that takes a task keeps a board in each session, on any flow; a split task waits parked above and settles from its pieces, up to five boards deep and 100 tasks under one top task

On the left, filing is a kind of worker. On the right, it follows from who the worker's file lists as delegates.

How: Orchestration's existing eight task tools (createTaskToolsCapability on the model's block, taskToolActions on the flow), wired by FIX-1794 with the session's own board as the resolver and its task-taking delegates as the roster. FIX-1794's split, parent binding and settle-owed marker are used as written. The task board does not change.

Sign off

The goal, at that size. If wrong: the EM must move to another flow to file, or a split spends without a limit before a person looks.

D1 · answered (product owner, 2026-10-07) · a worker files for its delegates that take a task; no filing flag

D1, answered: who files, and for whom. Chosen: a worker files for its delegates that take a task, with no flag. Instead of: an explicit filing flag, or a second list of who it files for. Decides it: one answer to who works for this worker and whether it files. The price: FIX-1791's check widens to a delegate that takes posts or tasks. A tie: Bob's worker is refused either way. Locks in: a worker that lists task-taking delegates files; a later no-filing mark covers an exception

It comes down to one list: a flag or a second list beside it can disagree. Locks in: a worker can't list task-taking delegates and be barred from filing; a later "no filing" mark would cover that if a case ever appears.

D2 · answered (product owner, 2026-10-07) · five boards deep, fixed; 100 tasks under one top task by default, which the app can raise

D2, answered: how big one chain can get. Five deep, fixed, and 100 tasks per chain by default, which the app can raise, chosen, beside five deep with each board capped alone. Decides it: a worker that splits at every level stops at 100 tasks instead of 11,110. The price: a job that needs a 101st piece is refused unless the app raises the cap

It comes down to a worker that splits at every level: with only a cap on each board, it can reach 11,110 tasks. The trade-off: a job needing a 101st piece is refused unless the app raises the cap (an option on hireWorkforce).

Open: none. Reasoning and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Also on this PR (news): post-merge amendments to four merged specs, each noted in its EVOLUTION.md.

  • FIX-1794 ships the final shape: the board per session, worked through Orchestration's existing eight task tools, not new ones (fileTask, reassignTask and createTaskFilingCapability() are gone). Its one interim part is the answer to "may this session file?": a coordinator conversation, never a task session, until FIX-1802's delegate rule replaces it. Its split acceptance (leg b, BR-30 to BR-32, S8, S10, V6) points to FIX-1802.
  • One Layer 1 change for the epic to record (ER-22), in FIX-1794 as T1: the task tools' roster may be read per call, and taskToolActions takes a roster. Without it, an app's addTask would go unchecked against the session's delegates until hand-over. Everything else rides Workforce's resolver.
  • FIX-1789: workerConfigSchema() gains delegates; no filing key. FIX-1791: BR-1a and BR-4 are marked as amended, pointing at D1, and the task session's lookup key is filingSessionId. FIX-1788: V4 reads that key.
  • No backwards support anywhere while there are no consumers; rename provenance lives only in EVOLUTION.

Depends on #2837 (epic D8). Merge after it. #2837 also amends FIX-1791, so merge this PR from a fresh main.

Reviewers · look here

  • Decisions → D1. The delegate list is the grant: a routing flow posts to them, and a delegate that takes a task is filed for.
  • Plan → S1 and S2, and FIX-1794 Plan → S4 and T1. The wiring of the existing task tools, and the one task-tool extension.
  • Plan → S5, Rules → BR-20 to BR-22. The chain count and the app-set cap; both limits refuse as the board's existing lifetime cap.
  • Rules → BR-12 and BR-19. A delegate's session that files keeps the results. A change from above that lands cascades to the open pieces.

Not here: converting the lab files that file (FIX-1792), the coordinator's routing policies (FIX-1791, amended on the epic).

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1802 · epic FIX-1786, its D8 on #2837 · builds on FIX-1794 (#2828), FIX-1791 · merges after human approval and required checks

Engineering calls — decided, not asked
  • The tools are Orchestration's eight; the app's actions are named <tool>_<board> by taskToolActions' rule (addTask_tasks for FIX-1794's draft board id).
  • With no task-taking delegate, the model's block gets no task tools and the resolver gives no board, so the app's actions answer the existing no_delegation_board.
  • Depth and the chain cap refuse in Workforce's board ref with the existing TaskCapExceededError (total_task_cap_exceeded): no task-tool change.
  • FIX-1780's reassignTask rules are not carried: assignTask moves a task no attempt holds, a failed task is filed again, and a cancel of a running task lands while its late result is declined.
  • The task-session refusal lifts in P2, with the split, so no task completes before its pieces.
  • The board is the session the worker runs in: a talk session, a delegate's session, or a task session. One board per session, in that session's D6 partition.
  • A delegate session that files does not hold its answer to the post. The results go to that session.
  • Depth and the chain's top task are written by the server at each task session's birth.
POC — the split on one worker flow, on today's task board (throwaway)

bash specs/issues/FIX-1802/poc/split-on-one-flow/run.sh — does one flow keep a board and work its own rows, and can a parked row settle later, from another session, through a stored claim ticket? Passed on main at ce06cb5c7, and again on head a8a7a4b63: settle recorded; replay and forged ticket declined; genuine ticket recorded. README. Throwaway evidence, outside default discovery.

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

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV

claude added 2 commits October 7, 2026 00:06
…it down the chain

The retained spec for FIX-1802 under epic FIX-1786's D8: filing is a
capability a worker's file grants (`filing: true`), on any worker flow;
the worker files for its own delegates (FIX-1791's list) onto its own
session's board; FIX-1794's split, parent binding and settle-owed marker
are carried as written; a chain stops at five boards deep and 50 tasks
under one top task. No Layer 1 change, on a POC run against main.

Also the post-merge amendment to FIX-1794's spec: the places that said
only a coordinator files, that a task session refuses to file, or that
the split waits for a later issue now point at FIX-1802 and epic D8.

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

linear-code Bot commented Oct 7, 2026

Copy link
Copy Markdown

FIX-1802

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 7, 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-07T00:13:02.782496Z 95c34cf PR opened
ℹ️ 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.

@vercel

vercel Bot commented Oct 7, 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 7, 2026 11:40am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 7, 2026 11:40am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 7, 2026 11:40am UTC

Request Review

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Second-look + architecture review (direction altitude)

Read SPEC, DECISIONS, PLAN, BUSINESS-RULES and EVOLUTION. The direction holds. A grant in the worker file plus a capability for app flows is the leaner shape. A second delegate list and a tools:-line grant were both correctly rejected. Findings are ordered by weight.

Above the line

1. The chain counter is a second store written alongside the board, with no stated lifecycle (D2 / S5 / BR-21–22).

  • The count is one versioned row per top task at user scope. The task row lives in a session partition.
  • The add and the count raise are two writes to two stores. "A failed add gives it back" does not cover a crash between them. A leaked count then permanently shrinks a chain's 50, and nothing reconciles it.
  • BR-22 covers two filings at 49. It does not cover a crash between raise and add.
  • Every fan-out piece contends on that one row. Versioned-write retry under 50 concurrent adds is not mentioned.
  • Rows keyed by top task are never deleted. A long-lived owner accumulates one per top task, and no cleanup is named.
  • Suggest the spec says one of:
    • the count is derived (a count of rows by topTaskId, so there is nothing to give back), or
    • there is an explicit reconcile-on-touch rule and a retention rule.
  • Deriving it looks more in keeping with tenet 5 and avoids the leak class entirely. The catch is that rows sit in different session partitions, so a derived count needs a cross-partition read. That is probably why the counter was chosen, so the decision should say so.

2. delegates: now means two things, and the spec doesn't say which applies where (D1 / BR-4 / BR-9).

  • D1's claim is one list for posts and tasks. But only coordinators route posts (FIX-1791).
  • For a non-coordinator with filing: true, delegates: is effectively a "files-for" list. For a coordinator it is both.
  • BR-4 refuses delegates: without the grant "off the coordinator". So a coordinator with delegates: and no filing: is valid, while a non-coordinator is not. "Coordinator" is therefore still a load-bearing kind.
  • That is the distinction D8 set out to remove. State it plainly: either a granted non-coordinator can also receive posts-to-delegates (then say so), or "coordinator" survives as "can post". Without that, BR-9 ("skipped by a post") reads oddly for a worker that never posts.
  • Related: the D1 "flips if" clause already names a tasks-only mark. Confirm that is deferred and not a hole.

3. FIX-1794 builds an interim that this issue deletes (S6 / EVOLUTION).

  • FIX-1794 ships "only a coordinator conversation keeps a board" and a task-session refusal. FIX-1802 P1 then removes both.
  • Both specs are unshipped, so the cheaper move is to amend FIX-1794 now to ship the board per session and the capability shape. Only the grant check would be coordinator-flavoured, and the removal PR disappears.
  • If FIX-1794's stack is already too far along, keep S6. The PR should say that explicitly, because the throwaway is real churn on a stack of six PRs.

4. An owed parent settle waits for "the next touch", and the chain is now up to five deep (S4 / Follow-ups).

  • The sweeper was a nice-to-have at one level. Here a stuck mid-chain board stalls every board above it, up to the top task.
  • The goal's 120 s completion holds only on the happy path.
  • Suggest at minimum a bound on how long a parent can sit settle-owed before the top task surfaces an error to the filing session. Alternatively, say plainly that the sweeper becomes a P3 dependency, not a follow-up.

Refactor opportunity this PR should take (not just note)

5. coordinatorSessionId (plan "At implement time").

  • This PR makes the name wrong for every granted-worker session: the lookup key is now the filing session's incarnation.
  • The plan defers the rename to FIX-1796. P1 touches every reader of it anyway (S1, S3).
  • Renaming it once, in P1, is cheaper than leaving a misleading persisted key through two more issues. If it is persisted, BP-030 applies: dual-read the old key.
  • Same for the "coordinator" wording in the delegate module and actions. S3 widens them to any granted worker, but the names stay as they are.

Smaller, for the implementer

  • BR-21 says a cancelled or completed piece still counts toward 50. Say so, because "50 tasks under one top task" can be read as 50 open.
  • Depth is "the parent's plus one" at birth. A delegate session that files starts a fresh chain (D1 / decided-not-asked), so a coordinator can post repeatedly and each round can start a new 5×50 chain. The board caps still bound it, but the spec should state that the chain limit is per top task and not per owner.

Not raised: the sketch, the POC polish, and naming. The POC's isolation and lack of secrets look fine.


Generated by Claude Code

@jhoffner jhoffner left a comment

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: spec-review-r1

Direction: sound. This reviews it against epic D8: filing is opt-in per worker, it ships as a capability any flow can take, the split is in the MVP, and the task board doesn't change (the POC backs that). D1's one delegate list is the right call: a second list would drift. D2 is a real product limit, and it belongs on the sign-off surface.

Above the bar (2):

  1. FIX-1789's and FIX-1791's merged specs aren't amended. S2 adds filing and delegates to workerConfigSchema(), which is FIX-1789's contract. S3 widens FIX-1791's BR-1a and BR-4. Both of those specs are merged, so each change binds only once that spec records it. Today only this spec's EVOLUTION records it.
    • Fix: add an "Amended after merge (FIX-1802's spec PR)" note to each spec's EVOLUTION.md.
    • Mark FIX-1791's BR-1a and BR-4 rows and FIX-1789's contract row as amended, pointing at D1.
    • Keep it the same smallest coherent change as FIX-1794's.
    • Merge order: #2837 also amends FIX-1791 (D2). It merges first, so take a fresh main before merging this PR.
  2. Coordinators now need the grant, and FIX-1792 says otherwise. FIX-1792 at 4592f94 (PLAN guardrail, around line 127) still says "A coordinator files with FIX-1794's actions; any other worker only with FIX-1802's filing tools".
    • Under D1, every coordinator that keeps a board needs filing: true, and so does the chief of staff.
    • FIX-1792 is the right place to fix it, and I'll fold it on #2833.
    • On this PR: name that consequence in D1's Locks in as a cross-spec edit, so it doesn't get lost.

Implementer notes (record, don't fold):

  • FIX-1793's run placement must walk up through as many as five task sessions. It may be simpler to read the chain's top task, which is written at birth, and then that task's filing session. Leave the choice to the implementer.
  • coordinatorSessionId now reads narrow. The rename is FIX-1796's call, as the PLAN says.

Round 2 follows once Codex's and Cursor's round 1 is folded.


Generated by Claude Code

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · coherence with #2833 (FIX-1792): one fork, on D1

D1 Locks in says each converted board file in FIX-1792 gains filing: true, coordinators included, and V5 removes any "is this a coordinator" check from the filing path. #2833 currently says the opposite: "A coordinator files with FIX-1794's actions; any other worker only when its WORKER.md grants FIX-1802's filing tools" (its D1, Settled, BR-13a and the PLAN guardrail). Epic D8 (#2837) backs this spec's reading. I've asked #2833 to align, conditional on D1 here being approved as written: comment.

Ask here: add FIX-1792 to Reviewers · look here next to the FIX-1789 and FIX-1791 changes, since D1 rewrites its coordinator conversions too. If D1 changes in review so that coordinators file by flow, say so in D1, DOCS and V5, and #2833 stays as it is.

No other fork found against #2837 (D7, D8), #2835 (FIX-1797) or the board's "seat" (FIX-1796).

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · coherence note on the second look (findings 3 and 5)

Two facts from outside this PR that bear on how to answer them:

  • Finding 3 (FIX-1794 builds an interim that this issue deletes). FIX-1794's spec merged in spec(FIX-1794): tasks go down the owner's chain and run as the owner #2828, but I find no FIX-1794 implementation PR open yet. So the "stack is already too far along" branch doesn't apply today. Prefer amending FIX-1794 now so it ships the board per session and the capability shape, with only the grant check coordinator-flavoured, and drop S6's removal step. If a FIX-1794 impl run has already started off-PR, say so here and keep S6, but name the throwaway explicitly as the reviewer asked.
  • Finding 5 (coordinatorSessionId). FIX-1796's spec (spec(FIX-1796): Remove the retired Workforce terms from code and docs #2832) is the retired-terms sweep and already merged. If P1 here takes the rename, FIX-1796 has to drop that key from its list in the same breath, so exactly one issue owns the rename and the dual-read (BP-030). Don't leave it in both.

No owner decision changes here. Findings 1, 2 and 4 are this spec's own to answer.

FSD Architect

@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 (FIX-1802 spec)

Problem: Epic D8 needs filing as an opt-in grant on any worker flow, plus the split in the MVP. This PR adds the FIX-1802 spec package (with a retained POC) and amends FIX-1794 so the post-merge story matches D8.

Verdict: approve the direction. The expensive part of the problem (park, ticket-fenced parent settle, per-session boards) is correctly inherited from FIX-1794 rather than redesigned. D1 (one delegates: list + filing: true in the worker contract, capability on flows) is the right trade for “EM keeps flow: em” and “one roster for posts and tasks.” The POC is honestly scoped and answers the Layer-1 question the epic cares about.

What follows is simplify feedback: places where the spec surface is wider than D8 strictly requires, or where two issues now carry the same story. None of this blocks merge for me; treat as optional tightening before implementation gates.


What already looks lean

  • Split mechanism: Carrying FIX-1794 S8/S10 verbatim (binding + settle-owed) avoids a second split design.
  • POC: One flow, two partition stand-ins, README calls out grant/chain count/settle-owed as out of scope.
  • Implementation reuse (when you build): PLAN aligns with existing workforce patterns (defineCapability like mailbox boards, workerConfigSchema, worker-lookup filing check) rather than inventing parallel modules.

Complexity that may be wider than necessary

  1. Two specs still own the split story. FIX-1794 keeps full goal leg b / BR-30–32 / conditional S8 language while FIX-1802 re-proves the same chain in VG leg a. Cleaner: In FIX-1794, replace split acceptance with pointer-only stubs (“owned by FIX-1802; not exercised in FIX-1794 VG”) and keep a single interim rule: task-session filing refused until FIX-1802 lands.

  2. Three limits for one chain (depth 5, per-board caps, user-scoped 50-task counter). D2’s fan-out math justifies something beyond per-board caps; the separate CAS row is coherent. If you want a smaller MVP: depth-only + aggressive per-partition caps ships faster; add the 50-task ledger when a goal leg proves fan-out in the wild. I would not reopen D2 without product sign-off — just flag that this is the main new persistence/concurrency surface beyond FIX-1794.

  3. Grant + capability + delegates: — three knobs that must stay aligned (BR-3, BR-4, load vs runtime). Cleaner docs/spec: one “filing kit” checklist in PLAN (or bootstrap that treats filing: true as implying required capability) so app authors see one failure mode, not three.

  4. S3 widens FIX-1791 delegate session machinery to every granted worker (mutable list + four actions on talk/task sessions). That follows D1 literally; alternative if product allows: file-static delegates for non-coordinator filers (edit in WORKER.md or on coordinator only) and keep versioned delegate writes coordinator-scoped — smaller session state, same EM/lab behavior if files are the source of truth.

  5. POC settle path uses full list() + heard scan (settledStep). Fine for throwaway evidence; implementers should not copy this for “last open piece” — use settle-owed + bounded counts per PLAN/BR-17.


Alternative approach (only if re-scoping were on the table)

Fold “grant + session boards” into FIX-1794 as a follow-on PR stack without a separate issue doc set; defer the 50-task counter; narrow delegate mutations on non-coordinator sessions. That reduces spec duplication and implementation surface, at the cost of a larger FIX-1794 narrative and less clear FIX-1802 tracking in Linear.

Given D8 and the FIX-1794/Q split already merged, the current issue boundary is reasonable — the wins above are polish, not a rewrite.


What's asked of you: No required changes from this review. Optional: trim FIX-1794 split duplication, add a one-line implementer guardrail against POC list() settle logic, and note expected chain-count contention near the 50-task cap in PLAN (operational, not correctness).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1802/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1794/SPEC.md Resolved
Comment thread specs/issues/FIX-1802/BUSINESS-RULES.md Resolved

@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: 95c34cfed4

ℹ️ 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-1802/SPEC.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1802/SPEC.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1802/PLAN.md Resolved
Comment thread specs/issues/FIX-1802/BUSINESS-RULES.md Resolved
- The capability's two halves: a capability for the worker's model block
  and the entries a flow spreads into its own maps; no flow-level `uses`.
- FIX-1794 amended to ship the board per session and
  createTaskFilingCapability(); its only interim part is the answer to
  "may this session file". Split acceptance there is pointer-only.
- The task-session refusal lifts in P2 with the split (S4, S6).
- The chain count: one versioned record per chain, keyed by the top
  board's partition and top task; idempotent reservation by task id,
  reconciled at the limit, deleted with the top task. BR-22 made exact.
- `delegates:` gets its use by capability (a routing flow or the grant).
- A touch of any board replays owed settles down the chain (BR-17).
- coordinatorSessionId and the delegate module's wording renamed in P1.
- FIX-1789's contract and FIX-1791's BR-1a and BR-4 marked as amended.
- Filing kit checklist, POC guardrail and contention note in PLAN.

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Round 1 is folded in 455ff61. Here is what happened to the review comments that aren't in line threads.

Head of engineering (spec-review-r1)

Second look

  • 1: D2 says why the count is stored and not derived. PLAN S5 and BR-21, BR-22 and BR-22a now say: one record per chain, keyed by the top board's partition plus the top task; reserving is idempotent by task id; ids with no row are dropped at the limit; the record is deleted when the top task ends. Finished pieces count, and the limit is per chain.
  • 2: BR-4 and D1 now say delegates: needs a use, decided by capability (a routing flow or the grant). The tasks-only mark stays deferred (D1, Follow-ups).
  • 3: FIX-1794 is amended to ship the board per session and createTaskFilingCapability(). S6 shrinks to "the grant replaces FIX-1794's interim answer".
  • 4: A touch of any board replays owed settles down the chain (BR-17, S4, V3). The sweeper stays a follow-up.
  • 5: coordinatorSessionId and the delegate module's wording are renamed in P1, and a stored key still resolves (S3, V2).

Architect

  • FIX-1792 is now in Reviewers · look here.
  • FIX-1796's merged spec doesn't list coordinatorSessionId, so no amendment was needed there. FIX-1802 owns the rename alone.

Generated by Claude Code

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · 455ff61: both asks folded; no open fork

Checked against my FIX-1792 ask and my note on findings 3 and 5:

  • FIX-1792 is in Reviewers · look here, and spec(FIX-1792): MAILBOX.md becomes WORKER.md on the coordinator flow, and the mailbox is removed #2833 already folded the matching change in 2617d4b. Both specs now say every worker that files, coordinators included, carries filing: true and files through createTaskFilingCapability(). There's one answer on both sides.
  • Finding 3: FIX-1794's spec files are amended on this PR to ship the board per session and the capability shape. The only interim part left is the coordinator-only answer to "may this session file?", and S6 now just swaps that for the grant. No FIX-1794 implementation PR is open, so nothing gets built and then thrown away.
  • Finding 5: FIX-1796's merged spec has no coordinatorSessionId, so this issue owns the rename and the stored-key dual-read alone. That's right.

Nothing more from the coherence side. If D1 changes in review, #2833 follows it.

FSD Architect

@jhoffner jhoffner left a comment

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: spec-review-r2

Verdict: one above-bar finding. It's a one-line fold, and then this goes to the gate. All 11 round-1 folds are in at 455ff61. Their locations: SPEC 79-90 and DECISIONS "Decided, not asked" (the capability's two halves), PLAN S5 and BR-21/22/22a (the chain record), BR-4 and D1 Locks in (delegates: needs a use), FIX-1794 S3/S4/S8/S10 and BR-7/30-32 (the amendment), PLAN S6 and V5 (task sessions refused until P2), BR-17 and S4 (the replay), S3 and V2 (the rename), FIX-1789's and FIX-1791's EVOLUTION notes, the PR body (the #2837 dependency), D1 (the FIX-1792 cross-edit), and PLAN At implement time (Cursor's notes). validate-spec-folder passes, and the POC passes (recorded, lost-claim replay, forged declined).

Above the bar

  1. The reconcile at 50 needs the cross-partition read that D2 rejected (PLAN.md:17, :96; BR-21 at BUSINESS-RULES.md:56).
    • "At 50, drop ids with no row" reads rows on other sessions' boards. FIX-1794 S1 says a ref reaches only its own partition. S2 opens another partition only through the hand-off gate.
    • So the check needs either a task-board change (ER-22) or a breach of the "every board operation through the partitioned ref" guardrail.
    • That is the same reason DECISIONS.md:88 gives for dropping a derived count.
    • Minimal fix: drop the row read.
      • The record marks each id reserved, and the filer marks it added once its add commits, in its own request.
      • At 50, drop reserved ids older than a lease.
      • Change S5, the sketch line and V4 to match.

Checked, no change needed: the replay-on-touch works without a Layer 1 change (see note 1), and so do the BR-3 grants in FIX-1792. Every coordinator FIX-1792 grants a board has members:, which becomes delegates:. FIX-1791 S10 seeds the chief of staff's delegates. BR-13a and the EM list theirs. FIX-1797's P3.10 (no-parent-settle, leg a), b5 (no-follow-up) and b6 (no-grant-check, leg c) all match.

Cross-spec (FIX-1792, #2833). These lines need "and actions" for the app's fileTask: BUSINESS-RULES.md:40, DECISIONS.md:48-49, DOCS.md:78-79, PLAN.md:23, :128 and :172-173.

Implementer notes

  • Replay the chain down by dispatching "run my board" into each parked row's task session. Each session then reads only its own partition. Never read a child's board from above (S4, BR-17).
  • Birth data has to carry the top board's partition as well as the top task, because S5 keys the record by both. DECISIONS.md:73 names only the top task.
  • FIX-1794 still has split leftovers, which are inline corrections: SPEC.md:36 (leg b in the diagram), PLAN.md:21 ("depth under the limit"), :25 ("If Q moves the split…"), and :72/:75 (V7 on S10/D2).
  • coordinatorSessionId is also a public findWorkerSession criterion (FIX-1794 SPEC.md:14, :78). Decide whether callers can still pass the old name, not only whether stored keys still resolve.

Generated by Claude Code

The chain record reads no other board: each id is reserved, then marked
added by its filer, and a reservation lapses after a lease (S5, BR-21,
V4, D2). FIX-1791 names the task session's lookup key for the filing
session, so FIX-1802 renames nothing (S3, V2, DOCS; FIX-1791 and
FIX-1794 amendments). Replay dispatches "run my board" down the chain;
birth data carries the top board's partition. FIX-1794's split
leftovers removed.

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold-r2

Round 2 (review) is folded at e894a81.

Above the bar: the chain record reads no other partition.

  • Each piece id is reserved first, and the filer marks it added in its own request once its add commits. At 50, reserved ids older than a lease are dropped, then the count is checked again. No rows on other boards are read.
  • The lease is the implementer's choice: at least one minute, and comfortably longer than one add (a few minutes).
  • If a crash lands between the add and its mark, the run that clears the row's pending-wake marker marks the id again, so the lease never drops a landed id (PLAN At implement time).
  • Changed: PLAN S5, the sketch, V4, BR-21, and D2's Because. D2 now says that checking the count against the rows would also cross partitions, so it no longer contradicts S5.

Your note on coordinatorSessionId: there is no rename, so no dual-read.

  • The key isn't in shipped code. The only hits on main are an unrelated docs example (packages/core/README.md, background-work.md), so no keys are stored and no callers pass the old name.
  • FIX-1791 introduces the key under its final name. Its post-merge amendment (FIX-1791 EVOLUTION) now says the task session's lookup key, the findWorkerSession criterion FIX-1788 S5a carries, is named for the filing session in the new terms, not coordinatorSessionId. The name is the implementer's.
  • Removed from FIX-1802: the P1 rename and its BP-030 dual-read (S3), V2's old-key case, and DOCS' "the name P1 gives it", which now reads "the name FIX-1791 ships". EVOLUTION's compatibility cell and PLAN At implement time are updated to match.
  • FIX-1794 SPEC.md:14 and :78 now use the filing session's key, marked as amended.

Implementer notes, folded inline.

  • Replay: a touch dispatches "run my board" into each parked row's task session, and each session reads only its own partition (PLAN S4, the sketch, BR-17).
  • Birth data carries the top board's partition as well as the top task (DECISIONS Decided, not asked, PLAN S5, the sketch).
  • FIX-1794's split leftovers are gone:
    • SPEC.md: leg b removed from the diagram.
    • PLAN S4: "depth under the limit" removed.
    • PLAN S8: "If Q moves the split…" removed.
    • V7: now runs after S9 only.
    • "D2 by V7" now reads "D2 is FIX-1802's (its V4)".

Not folded here: the cross-spec "and actions" edits belong to FIX-1792's PR (#2833).

DECISIONS How it got here has a round-2 line. The PR body is updated and its figure URLs are pinned to e894a81.

Checks: node scripts/validate-spec-folder.mjs → ✓ legacy spec folders are clear and no dangling legacy spec paths are cited (exit 0). The POC passes: settle recorded, replay declined (lost-claim), forged declined, genuine recorded.


Generated by Claude Code

…9 as amended

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · e894a81: the task session's lookup key now has two names

The round-2 fold moves the key's name to FIX-1791 and says "the name is the implementer's". That's fine as an owner, but only FIX-1791's EVOLUTION says it. At e894a81, FIX-1791's own spec still pins the old name in five places, unmarked:

  • PLAN.md:84 (the pinned on purpose table): "The criteria key · coordinatorSessionId, on FIX-1788's ensureWorkerSession and findWorkerSession criteria. FIX-1788 S5a reserved it for this spec to name."
  • PLAN.md:20 (S5) and :115 (the sketch): ensureWorkerSession({ worker, coordinatorSessionId: inc }).
  • SPEC.md:117 and BUSINESS-RULES.md BR-20a: ensureWorkerSession({ worker, coordinatorSessionId }).

So a FIX-1791 implementer who reads the pinned row builds coordinatorSessionId, while FIX-1794 (amended SPEC.md:14, :78) and FIX-1802 use the filing session's key. One criterion that FIX-1788, FIX-1791, FIX-1794 and FIX-1802 all pass would ship under two names. No FIX-1791 implementation PR is open, so this is still only a spec edit.

Ask:

  1. Mark those five FIX-1791 spots as amended, pointing at the EVOLUTION note, the same way BR-1a and BR-4 are marked.
  2. Pin one name in FIX-1791 PLAN.md:84 instead of leaving it to the implementer. Four issues share this key and will be built by different runs, so "the implementer's choice" is how it splits. Any name for the filing session works. It only has to be written down once.

No owner decision is involved. Everything else in round 2 holds against #2833: both specs say actions, internal and task maps (#2833 BR-13a, S7, the PLAN guardrail and DOCS already carry actions), so the "not folded here" item is already done there.

FSD Architect

…across FIX-1791, FIX-1794 and FIX-1802

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold

The architect's ask on the lookup key is folded in 275acea: one name, pinned.

  • The name is pinned as filingSessionId. It's written once in FIX-1791 PLAN's pinned table, marked as amended by this PR and renamed from coordinatorSessionId.
  • No other name remains in FIX-1791, FIX-1794 or FIX-1802. I updated every use: FIX-1791 SPEC:117, BR-20a, PLAN S5 and the sketch, DECISIONS, and EVOLUTION; FIX-1794 BR-19, SPEC:14 and :77, DECISIONS, DOCS and PLAN; and FIX-1802 DOCS and EVOLUTION.
  • Nothing needs to stay readable under the old name. It never shipped, so there are no stored values or callers.

validate-spec-folder passes.


Generated by Claude Code

@jhoffner

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · 275acea: one name now, one leftover in FIX-1788

Checked at 275acea. FIX-1791 (PLAN.md:84 pinned and marked amended, :20, :115, SPEC.md:117, BR-20a, DECISIONS), FIX-1794 and FIX-1802 all read filingSessionId, and the only coordinatorSessionId left in them is the "renamed from" note. That's the ask, done.

One spot outside those three still uses the old name. FIX-1788 is where S5a reserved the key, and it isn't touched by this PR:

  • specs/issues/FIX-1788/PLAN.md:75 (V4, the strict-subset case): "a coordinator's { worker, coordinatorSessionId } never lands in a task session".
  • specs/issues/FIX-1788/PLAN.md:182 calls it the "coordinator-conversation key" (wording only, not a name).

A FIX-1788 implementer writing the V4 test from that row would use the retired name. Ask: change :75 to { worker, filingSessionId }, marked as amended by #2839 the same way FIX-1791's row is, and optionally reword :182 to "the filing session's key". No owner decision is involved.

FSD Architect

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold

Folded in 60660dd.


Generated by Claude Code

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · 60660dd: FIX-1788 ask folded; no open fork

Checked specs/issues/FIX-1788/PLAN.md at 60660dd. V4 now reads { worker, filingSessionId } with the "renamed from coordinatorSessionId by #2839" note, and Follow-ups names filingSessionId as FIX-1791's key. That's the ask, done. The lookup key now has one name across FIX-1788, FIX-1791, FIX-1794 and FIX-1802.

Not blocking: S5a still describes the key in words ("FIX-1791's key for the coordinator conversation…", { worker, <coordinator key> }). It doesn't pin a name, so it can't fork. Reword it to the filing session if you're in the file anyway.

Nothing more from the coherence side.

FSD Architect

D1: no filing flag. A worker files for its delegates that take a task; the
flag's load errors go. Build on Orchestration's existing eight task tools
(createTaskToolsCapability, taskToolActions) instead of a new filing
capability; FIX-1794's amendment wires them, with one task-tool extension
(a roster read per call, and on taskToolActions) named as a Layer 1 change.
D2: depth fixed at five; the chain cap 100 by default, raised by the app.
No backwards support anywhere; rename provenance kept in EVOLUTION only.
Figures re-rendered.

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: sign-off-fold

Folded the product owner's answers (2026-10-07) in a8a7a4b.

D1 · no filing flag. A worker gets the task tools when at least one of its delegates: takes a task; that is the whole grant. A routing coordinator whose delegates only take posts, and a worker with no delegates, get none. The filing key is gone from D1, BR-1 to BR-6, S2, V1, the controls' wording, goal leg c, DOCS, the figures, and the FIX-1789 and FIX-1791 amendments. Dropped the load errors that existed only for the flag; kept the refusals for a worker not on the list and a delegate that takes no task (BR-8, BR-10). D1 is rewritten as the product owner's call: Instead of lists the explicit flag and the second list; Locks in says a worker can't list task-taking delegates and be barred from filing, and a later "no filing" mark would cover that.

Existing task tools, not new ones. createTaskFilingCapability() and fileTask / reassignTask are gone. The tools are Orchestration's eight (addTask, assignTask, completeTask, failTask, blockTask, cancelTask, updateTask, listTasks) through createTaskToolsCapability(resolver, roster), with the actions from taskToolActions, named <tool>_<board> (addTask_tasks for the draft board id). The resolver is the session's own D6 board, and the roster is its delegates that take a task. FIX-1794's S4, S11, pinned row, sketch, SPEC sample, DOCS and EVOLUTION are amended to match.

  • One Layer 1 change, T1, in FIX-1794's plan (ER-22, for the epic to record): the roster may be read per call, and taskToolActions takes a roster. Without T1, the app's actions check no assignee.
  • Everything else rides Workforce's resolver ref: the start on add or reassign, both limits (thrown as the existing TaskCapExceededError, so the tools answer total_task_cap_exceeded), and BR-19's cascade. Notices come from the board's gate.
  • FIX-1780's reassignTask rules are not carried. A failed task is filed again, and a cancel of a running task lands while the worker's late result is declined.

D2 · limits. Depth is fixed at 5. The chain cap is 100 by default, set by an app option on hireWorkforce (the implementer names it). Updated D2, BR-21, new BR-21a, BR-22, V4, goal leg d (101st task, and the 4th under an app cap of 3), DOCS and the figure text.

No backwards support. Removed the "read as before" compatibility entries and the inline "renamed from" notes. Provenance stays in EVOLUTION only ("renamed from coordinatorSessionId; never shipped"), with a note added to FIX-1788's.

Checks. node scripts/validate-spec-folder.mjs passes. The POC passes on this head (settle recorded; replay and forged ticket declined; genuine ticket recorded). Figures re-rendered and checked in light and dark. The PR body shows D1 and D2 as answered, with the figures re-pinned to a8a7a4b.


Generated by Claude Code

…g FIX-1797

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: FSD Architect / kind: fold-check

Checked a8a7a4b's sign-off fold against the epic's D8 and D9 (#2837 at 814b90d) and #2833 at 9f14e23. They agree: there's no filing key, the grant is a delegate that takes a task, the tools are Orchestration's existing eight through createTaskToolsCapability(resolver, roster), a chain goes five deep with 100 tasks by default and an app-set cap, and there's no backwards support. The hold I put on this PR from #2837 is lifted on the D8 and D9 side.

There are two epic-side follow-ups, and I've asked for both on #2837. Nothing changes here.

  • The epic has to record T1 as a counted Layer 1 change in D3 and D8 before this PR merges (ER-22).
  • The epic's D8 still says the D9 sweep amends FIX-1794's S4, but this PR already carries that amendment. It should point here, so S4 is rewritten once.

FSD Architect

jhoffner pushed a commit that referenced this pull request Oct 7, 2026
…ifth mechanism change

D8 records T1 from FIX-1794's amended PLAN (#2839): createTaskToolsCapability's
roster may be read per call, and taskToolActions(<board id>, resolver, roster)
takes one too, so an app's addTask is checked against the session's current
delegates. Generic orchestration change; names no worker or delegate. #2839
carries FIX-1794's D8 amendment, so the D9 sweep leaves FIX-1794 alone.

D3, D1, ER-22, SPEC, PLAN and the d1-the-set and end-state figures now count
five mechanism changes and one public rename. PLAN mirrors FIX-1792's
four-PR plan on #2833 (P4 · remove, no refusal PR).

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

jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: ci-note

Packed release installs and imports failed at cc594d6, and the failure isn't this PR's. This PR changes only files under specs/. The job's npm install got a 404 on ai-7.0.130.tgz. The registry lists ai@7.0.130 as published at 01:47:26Z, and the job asked for it about 30 seconds later, before the tarball was being served. The same check passed on #2837 at 1f5c627 fifteen minutes earlier. No fix to port; I'll re-run the failed job once when the rest of the run finishes.


Generated by Claude Code

@jhoffner
jhoffner merged commit bdb14e9 into main Oct 7, 2026
17 checks passed
jhoffner pushed a commit that referenced this pull request Oct 7, 2026
Conflicts in FIX-1788 EVOLUTION/PLAN and FIX-1789 EVOLUTION: both
amendments kept (#2839's filingSessionId and delegates notes, and the
D9 sweep's sections); FIX-1788 V2/V3 stay as D9 left them, V4 takes
#2839's filingSessionId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
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.

2 participants