Skip to content

spec(FIX-1786): amend after merge · record the Layer 1 exports the set shipped (FIX-1896) - #3125

Merged
jhoffner merged 3 commits into
mainfrom
claude/project-thread-mggc2n
Oct 12, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/project-thread-mggc2n

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

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

Evidence

  • Every exports entry point of contracts, core, engine and orchestration was read with the TypeScript checker. This was done at the baseline cad4e278 and after each first-parent merge up to f1ae3521 that touched Layer 1 source, and each merge's added and removed names were diffed.
  • The fence missed three children. Its own PR list left out FIX-1828, FIX-1834 and FIX-1836, which all changed Layer 1. The walk caught them. The other merges in the window that changed an entry point belong to other epics (FIX-1815's children, FIX-1772, FIX-1846, FIX-1128, FIX-1608) and aren't counted.
  • endingOf and applyEndingRecorder, which the fence's grep flagged, are on no entry point, so they aren't public.
  • node scripts/validate-spec-folder.mjs passes, and so does node scripts/check-retired-terms.mjs.

What's asked of you

One judgment for you to confirm or overrule. I counted hold/defer and 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 count noRetry as 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

…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
@jhoffner jhoffner self-assigned this Oct 12, 2026
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

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

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

Request Review

@linear-code

linear-code Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

FIX-1896

FIX-1786

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

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

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T05:35:31.826622Z 09ee21f Manual request
ℹ️ About Codex in GitHub

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

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

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

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec-only PR)

I checked the diff and spot-checked the exports against the checkout. TaskEnding, TaskEndingRecorder, FailOptions, TaskStateTarget and ConcurrencyPolicyName are all on public entry points, so the ledger's central claims look right. The notes below are for the next agent to weigh, roughly most to least important.

1. This is the third time the same hole has been patched by hand. A mechanical check would stop a fourth.
ER-22 relies on each child noticing it is changing Layer 1 and escalating. FIX-1834, FIX-1836 and FIX-1794 P2 didn't. The fence missed three children because it started from a PR list and a grep. The amendment's own method (read every exports entry point with the TS checker and diff names per merge) is the real control, but it only lives as prose in EVOLUTION.md.

  • Suggestion: commit a small script that snapshots the public names of contracts, core, engine and orchestration, and fails when a name appears that isn't in an allowlist tied to D3. Hook it into validate-spec-folder.mjs or the fence.
  • Why it matters: otherwise this PR fixes the count and the next child that ships a Layer 1 export without escalating re-opens FIX-1896.
  • Scope: probably a follow-up issue, not this PR. Worth filing so ER-22 has teeth.

2. The D3 table cell keeps growing.
The Because and Locks in cells were already very long, and this PR adds more. (8) and (9) and the four additions are now prose inside one cell, and EVOLUTION.md repeats them in a table. That is the fold problem BP-039 and writing-for-humans.md describe.

  • Suggestion: keep (8) and (9) to one sentence each in D3 and let the EVOLUTION ledger carry the detail. It already has one row per merge.

3. A stale "seven" is left, and the figure and aria-label disagree.

  • SPEC.md line ~201, the how it got here entry, says "beyond D3's seven". This may be fine if the "kept as written" rule covers decision-log entries, but that entry restates the kill line itself. A reader who lands there sees a different threshold than the table at the top. Either amend it or add a pointer to the exports section.
  • figures/d1-the-set.svg: the visible text now says "9 mechanisms, 2 renames, 2 removals" and drops "4 additions". The aria-label and end-state.svg include the additions. The three should agree, and the SVG text has room to say it.

4. Wording: "the other four" now reads two ways.
D3's Because still says "The other four are names and surfaces, not mechanisms. Two are renames... Two are removals." After this PR there are also four additions, which are described as "none a mechanism". Readers can reasonably ask which "four" is meant. Reword it, for example "the rest are names and surfaces".

5. The counting rule (mechanism vs addition) is only implicit.
The test is "Workforce can't build it outside Layer 1". It's applied in the PR description and the EVOLUTION "Why" cell, but not written next to the count. FailOptions.noRetry changes settlement semantics (an errored task with attempts left), which a reader could call a mechanism. One sentence in D3 stating the test would make the ruling checkable. It would also answer the PR's open question in the spec itself instead of only in the PR body.

6. Minor.

  • "Nine issues" and "nine mechanisms" sit side by side in D1's Cost now. They are unrelated numbers that happen to match, so a reader may assume a mapping. The existing "nine children" wording was already like this, so I'd leave it unless you're touching the line anyway.

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

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect · Layer 1 lens

Checked against main (f1ae352). Every claimed export is public from its entry point, the hold/defer and ending-recorder mechanism calls hold, noRetry is an addition (an option on the existing fail, applied inside the same ledger write; it adds no new state or arbitration), and no name this set added or renamed breaks the layer rule. Two count fixes are left:

  1. specs/epics/FIX-1786/figures/d1-the-set.svg:86: the visible cost line reads "9 mechanisms, 2 renames, 2 removals". It should add ", 4 additions" to match D3 and end-state.svg. The aria-label on line 2 also leaves out the four additions, while the D1 alt text in DECISIONS.md includes them.
  2. specs/epics/FIX-1786/DECISIONS.md:82 (D3 Because): "The other four are names and surfaces, not mechanisms" means the renames and removals, but it now sits next to "four additions". Please reword it, e.g. "The two renames and two removals are names, not mechanisms; the four additions extend existing surfaces."

…-1896 review)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx

Copy link
Copy Markdown
Collaborator Author

Both fixed in 8b8d432.

  1. In d1-the-set.svg, the cost cell now reads "Nine issues · 9 mechanisms" on the bold line and "2 renames, 2 removals, 4 additions" underneath. Adding ", 4 additions" to the single line would have run into the next column, so I split it across two lines. I rendered the figure to check: both lines end before the next column at x=468, at x=412 and x=430. The aria-label now names the four additions too.
  2. D3 Because now reads: "The two renames and two removals are names, not mechanisms, and the four additions extend existing surfaces."

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 (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

  1. 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 no specs/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-exports to 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’s names.mts disclaimer (“evidence, not a gate”).

  2. 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 walking package.json exports for the four Layer 1 packages would make re-runs cheap; prose would still own mechanism vs addition judgment.

  3. Taxonomy — Splitting “four additions to existing surfaces” from mechanisms (8)–(9) avoids inflating D3 to 13 mechanisms for SessionItem.role and noRetry; 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 recordEnding to mechanisms (8)–(9) rather than burying them in child specs — aligns with “what Workforce cannot fake.”
  • Leaving historical amendment sections at “seven” — correct lineage.
  • TaskStateTarget as 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1786/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1786/EVOLUTION.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: 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".

Comment thread specs/epics/FIX-1786/EVOLUTION.md Resolved
…ger (FIX-1896 review)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013v7bUqBT2FVDVGjWHji2zx
@jhoffner
jhoffner merged commit 725241b into main Oct 12, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants