Repository navigation
spec(epic): fold Jake's answers to Q1–Q3 (FIX-1786) - #2806
Conversation
Follow-up to #2795 (merged at 0630944) and #2804. Records the owner's answers of 2026-10-06 as decided, so no child reopens them. - Q1: not decided at epic level. FIX-1789's spec builds both shapes (an installation-kept list and a defineWorkerFlow() wrapper) in a spec-poc and settles it at its gate; Jake leans to the wrapper for contract integrity. The epic's recommendation of the list is withdrawn. ER-2 and ER-14 now hold for either shape; the Q1 figure is redrawn. - Q2: yes. Private projects are in, FIX-1763's org-level fence lifted, FIX-1762's stack merged first. ER-7, leg b's private step, the docs draft and PLAN lose their condition; FIX-1793 raises at its gate if private projects cost the MVP more than a scope configuration. - Q3: yes. FIX-1774 and FIX-1777 closed into FIX-1791 and FIX-1794. 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
|
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 passVerdict: The change itself is well-scoped: it records Q1–Q3 and moves no other decision. Deferring Q1 to FIX-1789's POC is the leaner call, because it gets the evidence before the decision instead of choosing now. Neither finding below blocks this PR. The first is the one worth reading. The architecture pass found nothing to refactor. This is a spec-only PR with no code, so there is no opportunity to deepen anything. 1. Q2's "fast follow" is recorded but not reconciled with the goal (Med · low confidence)
The following exist only for the shared half:
If shared work really is the follow-up, the MVP goal shrinks to "private roster + private projects", and the epic loses one issue and half a proof leg. The cost is the "two users work one shared project" proof, which is the epic's headline. That may be deliberate. Recommendation: Keep this PR as is. Make the goal call explicitly at the FIX-1793 or FIX-1795 spec gate, so it isn't left as an open implication. This PR's note that moving them "would be a separate change to the goal" is correct, but nothing currently owns making that change. 2. ER-26 contradicts the orchestration contract (Low · high confidence, pre-existing)
This PR doesn't touch ER-26, so don't fix it here. In a follow-up, delete ER-26 and replace ER-24 to ER-26 with a link to Checked and fine
Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 94db4073ed
ℹ️ 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".
| **Jake, 2026-10-06:** not decided at epic level. FIX-1789's spec builds both shapes side by side | ||
| in a spec-poc, a list the installation keeps and a `defineWorkerFlow()` wrapper, and the call is | ||
| made on that evidence at FIX-1789's spec gate. Jake leans to the wrapper for contract integrity: |
There was a problem hiding this comment.
Return Q1's choice to the epic gate
When FIX-1789 chooses between the registration list and defineWorkerFlow(), that choice also changes FIX-1788's agent flow and the contract consumed by FIX-1788/FIX-1791, so making the child spec gate authoritative contradicts ER-24 in BUSINESS-RULES.md, which says cross-cutting questions are never decided in one child. Have the POC produce evidence, then record and approve the winner through a follow-up epic amendment; otherwise dependent children can commit to one shape while the canonical epic still permits both.
AGENTS.md reference: AGENTS.md:L52-L56
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in #2807 (head 78839b4, needs approval). FIX-1789's gate still chooses on its POC, as Jake answered, but the winner binds the set only once a follow-up epic PR records it in Q1, and FIX-1788's and FIX-1791's specs name no shape until then. ER-2, ER-24 and PLAN say the same. Their builds already wait on FIX-1789, so nothing re-sequences.
Generated by Claude Code
There was a problem hiding this comment.
Simplify review (FIX-1786 / Jake Q1–Q3 fold)
Verdict: The epic’s overall approach looks like the right trade for the privacy hole and the six-part model — a rename-only path is correctly rejected in D1, and the retained end-state POC earned its keep for D3 (caller-seeded session state is the load-bearing finding). This follow-up commit is a real simplification where Q2 landed: dropping the conditional wording on ER-7, leg b, and the docs draft is the right move.
I don’t think a materially smaller epic is available without shrinking the goal (e.g. FIX-1796-only or in-place mailbox narrowing). What is available is less documentation and decision surface up front, and a sharper FIX-1789 POC that reuses workforce patterns instead of re-deriving them.
Where complexity crept in (and cleaner alternatives)
-
Q1 labeling vs substance — Jake answered how to decide (FIX-1789 spec-poc of both shapes), not which shape wins. The mermaid node and H2 say “decided” while the body says “not decided at epic level” and Jake still leans wrapper. That will read as “wrapper is locked” to implementers. Simpler: split labels (“epic: deferred to FIX-1789” vs “shape: TBD at gate”) everywhere, including the tree diagram.
-
Epic carries FIX-1789’s comparison matrix — The “What the POC compares” bullets (authorities, migration, private-state locus) are FIX-1789 scope; the epic already has a 600-line engine POC for D3. Simpler: epic Q1 = Jake quote + ER-2/ER-14 invariants + pointer; move the matrix to FIX-1789’s spec when written.
-
concept/CONCEPT.mddrift — Still frames coordinator vs relay as an open one-flow/two-flow question after D2 locked one flow + routing setting. Simpler: strike or mark superseded with a link to D2; trim “Still open” items that the epic already decided. -
FIX-1789 should not reinvent workforce — Today you already have
workerConfigSchema()as the authority (worker-config.tsexplicitly rejects a marker wrapper),defineAgentWorkerFlow(), andhireWorkforce({ kinds })as the installation map. Simpler FIX-1789 spec-poc: name those analogues and test whether a newdefineWorkerFlow()adds a second authority or is mostlydefineAgentWorkerFlow+ registration — rather than a greenfield side-by-side in a vacuum. -
End-state POC scope — Legs B/I/C/R are valuable but broader than “can we avoid a third Layer 1 change?” Simpler narrative: core story = P/X/O +
naivecontrol; tuckrecord/R1 under “shape we rejected” (it motivated server-owned state, not a user row keyed by session id). C1 overlapshand-off-cross-flow.test.ts— cite that test as sufficient for cross-flow lineage unless FIX-1794 needs more. -
Duplication across spec pack — Sign-off, “Decided in review,” and ER tables restate the same rules; Q2’s MVP escape hatch appears in DECISIONS + PLAN. Simpler: one canonical home per fact (ER-n for rules, DECISIONS for owner calls, EVOLUTION for chronology); elsewhere link.
What I would not simplify away
- Nine children + closure — heavy but matches blast radius; collapse triggers (FIX-1789 → FIX-1788, optional FIX-1790 fold) are already documented.
- spec-poc
run.shcopy into orchestration — matches FIX-1549/1654 pattern; HTTP create legs can’t be replaced bytestFlowwithout losing O1/O2 evidence. - Three Layer 1 changes — POC + ER-9 review round look like honest outputs, not over-engineering.
This PR’s delta
The eight-file Jake fold is directionally good (especially unconditional Q2). Main follow-up before child specs ship: fix Q1 vocabulary and sync the concept doc with D2/D3/Q2.
No blocking concerns for the epic direction from a simplify lens; items above are tighten-ups and FIX-1789 scoping.
Sent by Cursor Automation: Review For Best Approach
| E --> D5["D5 · a board is a session board unless people track it"] | ||
| E --> Q1["Q1 · open · which flows run workers"] | ||
| E --> Q["Q2 and Q3 · asked on the inventory"] | ||
| E --> Q1["Q1 · decided · FIX-1789's spec settles it on a POC of both"] |
There was a problem hiding this comment.
Nit / simplify: this node says Q1 · decided, but the section body correctly says not decided at epic level (only the process is decided: FIX-1789 builds both shapes). Consider renaming the node to something like Q1 · gate at FIX-1789 so implementers don’t read “decided” as “wrapper wins.”
There was a problem hiding this comment.
Fixed in #2807. The node now reads Q1 · answered · chosen at FIX-1789's gate, recorded here.
Generated by Claude Code
| It comes down to authorities: the wrapper makes a second one over the schema's rule. | ||
| ## Q1 · decided · Where an author says "this flow runs workers" is settled in FIX-1789's spec, on a POC of both | ||
|
|
||
| **Jake, 2026-10-06:** not decided at epic level. FIX-1789's spec builds both shapes side by side |
There was a problem hiding this comment.
Same labeling point: the H2 says “decided” while this paragraph defers the shape. If intentional, one explicit sentence up front helps: “Decided: FIX-1789 owns the shape; not decided: list vs wrapper (Jake leans wrapper).”
There was a problem hiding this comment.
Fixed in #2807. The heading reads "answered, shape open", and the card opens with "Decided: who chooses and on what evidence. Not yet decided: list or wrapper."
Generated by Claude Code
| contract: the flow composes `workerConfigSchema()`, has a door, keeps a worker's state private, | ||
| and can be kept for standard workers only. [ER-14](BUSINESS-RULES.md#what-no-child-may-do): | ||
| whichever shape wins registers flows, not workers. | ||
| - **What the POC compares.** The figure's rows. Contract integrity: is every requirement checked |
There was a problem hiding this comment.
Simplify suggestion (optional): this comparison matrix is FIX-1789’s job; the epic already carries a large D3 engine POC. Consider moving bullets 101–106 to FIX-1789’s spec and leaving ER-2/ER-14 invariants + Jake’s lean here — less duplicate maintenance when FIX-1789’s POC evolves.
There was a problem hiding this comment.
Left for FIX-1789. The bullets stay as the card's trade-off, which the figure carries; FIX-1789's spec owns the full comparison and can extend it. Sent to FIX-1789 as a note.
Generated by Claude Code
| > declares a worker flow is [Q1](../DECISIONS.md#q1), which FIX-1789's spec settles on a POC of both shapes. A workstream is a project entry plus its | ||
| > lead's session; `MAILBOX.md` becomes `WORKER.md`; no transcript resource is built, so the | ||
| > `transcript:` key below isn't either ([decided in review](../DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them)). | ||
| > The boards are per [D5](../DECISIONS.md#d5) and [ER-9](../BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt). A worker's |
There was a problem hiding this comment.
Drift vs D2 (one coordinator flow + routing setting): this still reads as an open one-flow/two-flow fork. Striking or a short “superseded by D2” note would keep the concept doc from fighting the epic decisions pack.
There was a problem hiding this comment.
Already answered. CONCEPT.md's top note says the epic binds where the PRD differs and names D2's one coordinator flow; the PRD text stays as Jake wrote it (round 1, 975a16f).
Generated by Claude Code
| here: [Q2](DECISIONS.md#q2) · private projects lift FIX-1763's "projects stay org-level", and | ||
| FIX-1762's stack merges first; [Q3](DECISIONS.md#q3) · close FIX-1774 and FIX-1777 into | ||
| FIX-1791 and FIX-1794. Engineering calls I | ||
| **Answered by Jake, 2026-10-06.** [Q1](DECISIONS.md#q1) · where an author says a flow runs |
There was a problem hiding this comment.
Duplication simplify: Jake’s Q1–Q3 answers are spelled out again in DECISIONS.md. Sign-off could be one line each pointing at #q1–#q3 plus D1, so owner answers have a single canonical paragraph.
There was a problem hiding this comment.
Not folded. The sign-off carries each answered ask in one line by design (the PR-body template); the card is the canonical paragraph. #2807 keeps that line consistent with Q1's new wording.
Generated by Claude Code
|
Review of #2806, triaged (folded in #2807, head Second look:
Simplify (Cursor): Q1's labels are fixed. The POC comparison and reusing Codex P2: folded, as above. Generated by Claude Code |


Follow-up to #2795 (the FIX-1786 epic spec, merged at
0630944) and #2804. It records Jake's answers of 2026-10-06 to the three questions the epic asked, so no child reopens them. No other decision, owner or objective moves.What changes
defineWorkerFlow()wrapper. The call is made on that evidence at FIX-1789's spec gate. Jake leans to the wrapper for contract integrity. The epic no longer recommends the list. ER-2 and ER-14 now hold for either shape.The Q1 figure: DECISIONS.md → Q1 (rendered there; the pinned image line is with the coordinator to paste).
The figure now shows the comparison FIX-1789's POC runs, with Jake's reason as its first row.
Reviewers · look here
What's asked of you
Approve and merge this head. Until it merges, the retained set on
mainstill shows Q1 to Q3 as open.Links: FIX-1786 · original review #2795 · inventory asks on FIX-1786 · set at
specs/epics/FIX-1786/🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code