Repository navigation
spec(FIX-1786): align the child specs after the cross-spec review - #2843
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
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. |
There was a problem hiding this comment.
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)
- Record the nine calls once in
specs/epics/FIX-1786/EVOLUTION.md(FIX-1650 Oct-2 shape) with a “child touch” column. - Patch child PLAN/BR/SPEC in the same PR.
- Child
EVOLUTIONonly 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.
Sent by Cursor Automation: Review For Best Approach
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
There was a problem hiding this comment.
💡 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".
| |---|---|---|---| | ||
| | 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 | |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
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:
addDelegateadds 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
- 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


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).
featureworkstream, 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 opensfeatureherself 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.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.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.mailboxesdomain. 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.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.workersmap". Now: "who a task goes to: an entry in the board'sworkersmap, 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.workforce/library/*with an owner field. Now:workforce/library/[owner]/[template]withownerWrites: { param: "owner" }(FIX-1795 PLAN, pinned names, docs).[owner].filing-work.md.What's asked of you
Nothing. These are engineering alignments under decisions already made.
Reviewers · look here
packages/orchestration/src/skills/collection.tskeys an isolated catalog on the flow instance id, and the library has to take a per-run key. (b) is a removal from an exportedcontractsconstant and from core'sdiscoverdescription, 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.LAB_USERS.membermeans 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 onfeature.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..md, and every edited file ends with a newline.xmllint --nooutpasses on both edited SVGs. Both were rendered in light and dark mode with no text overflow.apps/docspages that don't exist yet, and they were there before this PR.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