Repository navigation
spec(FIX-1786): amend after merge · record the Layer 1 exports the set shipped (FIX-1896) - #3125
Conversation
…t shipped (FIX-1896) The closure's layer fence found public Layer 1 exports D3 didn't name. A walk of every Layer 1 entry point's exports, merge by merge from the pre-epic baseline to main, attributes each to a D3 item. Two are new mechanisms (the hold/defer concurrency policies, FIX-1834 and FIX-1836; a task ledger's ending recorder, FIX-1794 P2) and four are additions to existing surfaces (FIX-1789, FIX-1788 P1, FIX-1828, FIX-1866). None names a Workforce concept. D3 now counts nine mechanisms and four additions; ER-22, D1, the box, the kill line and their figures match. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second look + architecture pass (spec-only PR)I checked the diff and spot-checked the exports against the checkout. 1. This is the third time the same hole has been patched by hand. A mechanical check would stop a fourth.
2. The
3. A stale "seven" is left, and the figure and
4. Wording: "the other four" now reads two ways. 5. The counting rule (mechanism vs addition) is only implicit. 6. Minor.
No correctness blockers found in the numbers I could verify. I didn't re-run the full per-merge TS-checker walk. Generated by Claude Code |
|
Architect · Layer 1 lens Checked against
|
…-1896 review) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx
|
Both fixed in 8b8d432.
Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (spec amendment FIX-1896)
Verdict: The export walk and D3 re-count are the right fix for the gap FIX-1797 P4 surfaced. I would not collapse this back to “trust the closure grep” — that gate only scans new core/engine files for worker nouns and “as recorded on the commit,” so it cannot catch hold/defer, TaskEndingRecorder, or additive export surface. Recording after merge matches the binding/visibility/handoff pattern and is appropriate.
Where the approach is heavier than necessary
-
Forensic table in epic
EVOLUTION.md— The 14-row merge × symbol inventory is auditor-grade and will go stale on the next Layer 1 merge unless someone repeats the walk. Prior amendments kept epic sections narrative + a small “what changed” table and pushed detail to issue evolution (e.g. FIX-1788). FIX-1896 has nospecs/issues/FIX-1896/home, so everything landed in the epic. Simpler follow-up (optional, not blocking): keep this PR’s D3/ER-22/SPEC/figure count sync, but trim#amendment-exportsto problem + methodology + delta ((8), (9), four additions) + “recorded after the fact,” and move the full table to a generated JSON artifact or a one-off issue spec — same idea as FIX-1639’snames.mtsdisclaimer (“evidence, not a gate”). -
Nine surfaces for one count — D3, D1, tree, SPEC box + kill line, ER-22, two SVGs, How it got here, and EVOLUTION duplicate the same taxonomy (9 mechanisms + 2 + 2 + 4 additions). That duplication is intentional for “one count across the set,” but it is the main maintenance cost on the next surprise export. A small
ts-morph/checker script walkingpackage.jsonexportsfor the four Layer 1 packages would make re-runs cheap; prose would still own mechanism vs addition judgment. -
Taxonomy — Splitting “four additions to existing surfaces” from mechanisms (8)–(9) avoids inflating D3 to 13 mechanisms for
SessionItem.roleandnoRetry; that split looks correct. Clarity nit: D3 Because says “The other four are names and surfaces” (renames + removals) while the title also advertises “four additions” — easy to misread; one bridging sentence would help (inline).
What I would not change
- Promoting hold/defer and
recordEndingto mechanisms (8)–(9) rather than burying them in child specs — aligns with “what Workforce cannot fake.” - Leaving historical amendment sections at “seven” — correct lineage.
TaskStateTargetas an addition building (3), not mechanism 10.
Nit before merge (trivial fix)
figures/d1-the-set.svg visible cost row still says 9 mechanisms, 2 renames, 2 removals while end-state.svg, ER-22, D1 alt text, and SPEC include four additions. That breaks the PR’s own “one count” goal for figure-only readers (inline).
Skipped (needs product call): folding additions into mechanism narratives to shrink ER-22 buckets; re-opening kill-line wording for additions vs nine mechanisms.
Approving directionally — please sync the D1 figure subtitle with the rest of the set.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 09ee21f00d
ℹ️ 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".
…ger (FIX-1896 review) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx


Requested by Jake · project thread
Before: FIX-1797's layer fence (ER-22) failed because Layer 1 gained public exports during FIX-1786 that the epic's D3 doesn't record (FIX-1896).
After: D3 records every Layer 1 public export the set added, renamed or removed. None breaks the layer rule: no export names a worker, coordinator, workstream, project, hire or roster of workers.
This is a post-merge amendment to the retained epic spec (original review #2795), shaped like the earlier binding, visibility and hand-off amendments.
What changed in D3
holdanddeferconcurrency policies (FIX-1834 feat(engine): a reply holds its conversation, so a task's notice waits for it (FIX-1834) #2970, FIX-1836 fix(bullmq): queue workers honour hold and defer (FIX-1836) #2990)TaskEnding/TaskEndingRecorder(FIX-1794 P2 FIX-1794 P2: a conversation files tasks for its delegates and hears each one end #2935)FlowConfigRefusalError,FlowConfigIssue,FlowConfigPath(FIX-1789 feat(workforce): workers run only on registered worker flows (FIX-1789) #2847)TaskStateTarget,resolveTaskState(FIX-1788 P1 FIX-1788 P1: check every session at create; server-owned session data #2850)SessionItem.role(FIX-1828 fix(workforce): a best-fit follow-up keeps its conversation's context (FIX-1828) #2955)FailOptionswithnoRetry(FIX-1866 P1 feat(harness-manager): a run reads its board from the task's claim (FIX-1866 P1) #3050)WorkerRoster→AssigneeRoster, which landed early in FIX-1794 P2: a conversation files tasks for its delegates and hears each one end #2935), and the removals (FIX-1814 removed core'sAgent*types and orchestration'smaterializeWorkerfamily).EVOLUTION.md→ "Amended after merge: the Layer 1 exports the set shipped" has one row per merge, naming each public name and its D3 item.Evidence
exportsentry point ofcontracts,core,engineandorchestrationwas read with the TypeScript checker. This was done at the baselinecad4e278and after each first-parent merge up tof1ae3521that touched Layer 1 source, and each merge's added and removed names were diffed.endingOfandapplyEndingRecorder, which the fence's grep flagged, are on no entry point, so they aren't public.node scripts/validate-spec-folder.mjspasses, and so doesnode scripts/check-retired-terms.mjs.What's asked of you
One judgment for you to confirm or overrule. I counted
hold/deferand the ending recorder as mechanisms, because Workforce can't build either one outside Layer 1. I counted the other four as additions to surfaces that already shipped, so they don't add to the mechanism count. If you'd rather countnoRetryas a mechanism too, that's a one-line change.No changeset: this PR changes only the spec.
🤖 Generated with Claude Code
https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx
Generated by Claude Code