Skip to content

spec(FIX-1786): align the child specs after the cross-spec review - #2843

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-1786-cross-spec-align
Oct 7, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-1786-cross-spec-align

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator

The problem

The epic's child specs were reviewed and merged one by one. Checking them against each other found 9 places where two specs disagree, so an implementer reading one would build something its sibling doesn't expect. All nine are engineering alignments under decisions already made.

What this does

One amendment per touched spec, each recorded as Amended after merge (cross-spec alignment, 2026-10-07) in its EVOLUTION.md (or in DECISIONS → How it got here where the spec has no EVOLUTION.md).

  1. Closure b5. Before: b5 used the seeded feature workstream, which FIX-1792 opens as the lab's member (Bob). Alice's coordinator only hands work to her own workstreams (FIX-1793 BR-25), and the closure forbids seeding. Now: Alice opens feature herself with the EM as lead. "Comes back up" is graded at the EM's workstream session and the EM's entry update (FIX-1793 BR-16), not at the coordinator conversation (FIX-1802 BR-12). FIX-1792 BR-15/S7 now names the seed's user (LAB_USERS.member) and says the closure doesn't rely on it.
  2. One live delegate list. Before: FIX-1802 read the grant from the file's delegates:, while the assignee check reads the session's delegates per call (FIX-1794 T1). Now: the grant reads that same list per call. Adding a delegate mid-conversation shows the tools, and removing the last one hides them. Changed in FIX-1802 S2, BR-1/2/5, D1 Locks in, decided, not asked, the sketch and the docs draft, and in FIX-1792's sketch.
  3. No record of what a turn wrote. Before: specs said "a turn names the collections it wrote". FIX-1761 ended at 503c9790e, which has no durable record of a request's writes, so views refresh after every turn. Now: FIX-1788 BR-8/S9, FIX-1795 BR-8/BR-12/BR-30, both docs drafts and epic ER-19 say the view reloads after the turn and no tool name is treated specially.
  4. D3's count. Before: "five mechanism changes and two public renames". Now: six mechanism changes, two public renames and one public removal. The sixth mechanism change is FIX-1788 S7, the skills library taking its key per run, reshaped as a function the composing layer supplies. The removal is FIX-1792 S9's mailboxes domain. Updated in D1 (Locks in, alt text, tree), D3, D7, ER-22, SPEC, PLAN, both figures, FIX-1788's guardrail (orchestration named as Layer 1) and FIX-1794 T1.
  5. Guards on delegates:. Before: FIX-1802 said nothing is refused at load, and that a delegate list on create is "ignored, or refused". Now: FIX-1802 S3 carries FIX-1791 BR-11's load refusal to every standard worker (new BR-10a), and delegate state is server-only on every flow (FIX-1788 S1). BR-6 now refuses with a 400 naming the field. Epic ER-6 is widened to match.
  6. FIX-1793 build order. Before: the epic released FIX-1793's board slice after FIX-1794's first PR. Now: FIX-1793 P3 carries the Board view and V6's walk-up leg, and waits on FIX-1794 P2 and FIX-1802 P1. Epic PLAN step 4 matches.
  7. Assignee. Before: "a named entry in a board's workers map". Now: "who a task goes to: an entry in the board's workers map, or a name the board's assignee check accepts (in Workforce, a delegate)". Changed in FIX-1796 BR-18, D1, the glossary row and epic D7. The word stays assignee.
  8. Library path. Before: workforce/library/* with an owner field. Now: workforce/library/[owner]/[template] with ownerWrites: { param: "owner" } (FIX-1795 PLAN, pinned names, docs).
  9. Bookkeeping.
    • The epic's workstream path gains [owner].
    • The set table's "13 files" is now FIX-1792's count: 11 session boards, plus 1 workstream, 1 removed with its feature and 2 removed trees.
    • The epic DOCS table gains a row for FIX-1802's filing-work.md.
    • FIX-1794's reassign and cancel text everywhere now says: the task tools' contract, a cancel that lands and cascades (FIX-1802 BR-19), the late result declined, no three-move limit.
    • FIX-1791 now points at FIX-1792 S9, not FIX-1796.
    • T1's "D3 four" now reads "the fifth of six".
    • The changeset policy is stated once in D9. FIX-1792's changeset that only named removed exports is dropped.
    • The BP-030 citations in FIX-1788, 1789, 1794 and 1795 (and FIX-1790's) now stand on their own reasons.

What's asked of you

Nothing. These are engineering alignments under decisions already made.

Reviewers · look here

  • Item 4's count. (a) FIX-1788 S7 really is a Layer 1 mechanism change: packages/orchestration/src/skills/collection.ts keys an isolated catalog on the flow instance id, and the library has to take a per-run key. (b) is a removal from an exported contracts constant and from core's discover description, not a rename. So I wrote "two renames and one removal" rather than "three renames". The D1 figure's row now reads "6 mechanisms, 2 renames, 1 removal". It was checked in Chromium, light and dark, and is narrower than the old text.
  • Item 2. FIX-1802 BR-5 now also says that a change to the file reaches only sessions whose list is copied after it (FIX-1791 BR-1). That is the consequence of one live list. The old BR-5 said "the next run reads it".
  • Item 1. Naming the seed's user as LAB_USERS.member means the DevTeam owner has no seeded workstream of their own. I kept FIX-1792's existing wording and made it explicit. If the seed is meant to be the owner's, b5 would collide on feature.
  • Item 6. Instead of putting both of FIX-1793's P2 and P3 behind FIX-1802 P1 (which itself waits on all of FIX-1794), only V6's walk-up leg moves into P3. P2 still delivers S6.
  • Beyond the brief (same rule, applied consistently):
    • FIX-1790's BP-030 citation is removed.
    • FIX-1792's removal-only changeset is dropped.
    • FIX-1791's mailbox exports now point at FIX-1792 S9.
    • Epic ER-6 is widened.
    • Left as is: epic D8's "its delegates:" (the product owner's text; the file is still where each session starts), the concept doc's old workstream path, and FIX-1793's "fourth Layer 1 change" phrases (hypothetical, historical).

Spec amendment · epic FIX-1786 · children FIX-1788 to FIX-1797 and FIX-1802 · draft, not for agent merge

Verification
  • node scripts/validate-spec-folder.mjs: exit 0.
  • Code fences are balanced in every edited .md, and every edited file ends with a newline.
  • xmllint --noout passes on both edited SVGs. Both were rendered in light and dark mode with no text overflow.
  • A relative-link and anchor check over the edited files found no new dangling anchors. The only misses are docs-draft links to apps/docs pages that don't exist yet, and they were there before this PR.
  • A final grep for each item's old wording ("collections it wrote", "five mechanism", "D3 four", "13 files", "named entry in a", library/*, the file-based grant) finds only historical or amendment-record lines.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


Generated by Claude Code

Reading the epic's merged child specs against each other found nine places
they disagreed. Each is an engineering call under decisions already made:

- FIX-1797 b5: Alice opens `feature` herself; graded at the EM's workstream
  session and entry update. FIX-1792 names the seed's user.
- FIX-1802: the grant reads the session's delegates per call, the list the
  assignee check reads; FIX-1792's sketch follows.
- ER-19, FIX-1788 BR-8, FIX-1795 BR-8/BR-30: views reload after every turn.
- D3 counts six mechanism changes (FIX-1788's per-run skills key), two
  renames and one public removal (FIX-1792's `mailboxes` domain).
- FIX-1802: BR-11's load refusal reaches every standard worker; a create
  seeding delegates gets a 400.
- FIX-1793 P3 and epic PLAN step 4 wait on FIX-1794 P2 and FIX-1802 P1.
- Assignee: an entry in the board's `workers` map or a name its assignee
  check accepts (epic D7, FIX-1796).
- FIX-1795: `workforce/library/[owner]/[template]` with `ownerWrites`.
- Bookkeeping: workstream path, board count, DOCS row, FIX-1794 reassign and
  cancel, FIX-1791's FIX-1792 pointer, T1's count, changeset policy in D9,
  BP-030 citations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@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 12:33pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 7, 2026 12:33pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 7, 2026 12:33pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 7, 2026

Copy link
Copy Markdown

FIX-1786

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@jhoffner
jhoffner marked this pull request as ready for review October 7, 2026 12:25
@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-07T12:31:59.941790Z b8a1105 Draft marked ready
ℹ️ 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.

@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 / cross-spec alignment review

Verdict: Approve direction. The nine conflicts this PR resolves were real (D3 counts, assignee vs delegate, ER-19 vs FIX-1761 aspiration, FIX-1793 P3 merge gates, session-scoped filing grant, board inventory, closure b5 grading). Folding them in one amendment PR after child spec merge is consistent with how this epic already handled the D9 sweep (#2841) and matches cross-spec-review → single amendment PR from main.

Did the approach go too far?

Substance: No — most edits are normative (PLAN/BR/DECISIONS Locks in) where implementers actually look.

Process / documentation surface: Partially. Nine near-copy EVOLUTION.md#amendment-cross-spec blocks (~same four-line intro each) plus epic “How it got here” plus per-issue DECISIONS bullets triple-tracks the same event. FIX-1650 already shows a lighter pattern: one epic EVOLUTION.md amendment table + child deltas only where local lineage changes. For the next cross-spec pass on this epic (or others), I’d prefer epic-first manifest (D9 Reaches-style row or FIX-1650-style epic EVOLUTION table) + inline normative fixes + optional child EVOLUTION rows only when a predecessor claim flips — not mandatory #amendment-cross-spec everywhere.

BP-030 citation-only child EVOLUTION sections (FIX-1789, FIX-1790, FIX-1794, …) are probably more ceremony than value given epic D9 already wins; fine to ship, but skippable next time.

Inconsistency in this PR: FIX-1795 (library key workforce/library/[owner]/[template], ownerWrites) and FIX-1797 (b5) got DECISIONS chronology bullets but no #amendment-cross-spec / EVOLUTION table — same alignment event, harder to grep. Either add matching EVOLUTION rows or drop boilerplate elsewhere for parity.

Cleaner alternative (future, not a merge blocker)

  1. Record the nine calls once in specs/epics/FIX-1786/EVOLUTION.md (FIX-1650 Oct-2 shape) with a “child touch” column.
  2. Patch child PLAN/BR/SPEC in the same PR.
  3. Child EVOLUTION only when superseding a row in the predecessor table (e.g. FIX-1788 BR-8, FIX-1795 S1 key).

That would cut ~300+ duplicated words without losing BP-037 retention.

Implementation-cost notes (not spec bugs)

The alignment hardens costs that were already implicit: T1 roster per call, skills-library key per run (D3 #6), ER-19 full view reload per turn. Worth planning request-scoped roster reads on coordinator paths where the spec allows one read per post.

Should fix (small)

FIX-1802 D1 Because still says “Nothing is refused at load” while Locks in / BR-10a refuse a standard worker naming a non-standard delegate at load. Left inline — easy one-sentence narrow in Because (failure taxonomy already says the right thing).


No changeset needed (spec-only). Tests N/A.

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

ℹ️ 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/BUSINESS-RULES.md Outdated
|---|---|---|---|
| BR-1 | A worker's file lists a delegate that takes a task, and its flow carries the task tools | Its turn has Orchestration's eight task tools over its session's board, and the app's actions of those names (`<tool>_<board>`) work on its sessions | CI · VG legs a, b |
| BR-2 | A worker's file lists no delegate that takes a task: none at all, or only ones that take posts (a routing coordinator) | Its turn has none of the eight. Its session keeps no board, so the app's `addTask` action on it answers `no_delegation_board`. Nothing stored | CI · VG leg c |
| BR-1 | A session's delegate list holds a delegate that takes a task, from the file or added since, and its flow carries the task tools | Its turn has Orchestration's eight task tools over its session's board, and the app's actions of those names (`<tool>_<board>`) work on that session | CI · VG legs a, b |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Keep the filing grant out of session state

When a worker starts without task-taking delegates, this rule and BR-5 let the public addDelegate action make all eight task tools available on the next call. That makes mutable session state the filing grant, contradicting epic ER-17 (specs/epics/FIX-1786/BUSINESS-RULES.md:35), which forbids granting access from session state or a delegate, and FIX-1791's guardrail (specs/issues/FIX-1791/PLAN.md:98), which says the delegate list grants nothing. Retain the server-recorded/file grant or explicitly amend the higher-level security invariant before implementation.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

The live list doesn't grant access, so ER-17 holds. ER-17 is about access: what a caller can read or write is decided by the engine-recorded owner, checked against the resource. Here is the path I traced:

  • addDelegate adds only a worker already on the user's own roster (FIX-1791 BR-2), in their own conversation.
  • The list then decides which task tools that turn carries.
  • Every task's assignee is checked against the roster and FIX-1788's links when it's filed, and again when it's delivered.

So adding a delegate lets the user hand their own work to their own worker, which they could already do through a post. It opens nothing they couldn't reach before. Keeping the grant on the file would bring back the mismatch this alignment removed: tools with no assignee to accept them, or an assignee with no tools.

The wording did invite the misreading, so cf01840 says it outright. FIX-1802 BR-1 now says "the list grants no access (ER-17): it decides which tools a turn carries", plus the two checks. FIX-1791's guardrail now says "grants no access (it decides only which task tools a turn carries)".


Generated by Claude Code

Comment thread specs/issues/FIX-1794/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1792/PLAN.md Resolved
- Changeset policy (epic D9): a rename or removal of a published export
  carries a minor changeset so the version moves with the break; none
  carries upgrade steps. FIX-1789, FIX-1792 and FIX-1796 restore theirs.
- FIX-1794 leg e and goal: a finished task is filed again with addTask;
  it can't be reassigned or cancelled.
- FIX-1802 BR-1 and FIX-1791's guardrail: the delegate list grants no
  access (ER-17); it decides only which task tools a turn carries.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants