Skip to content

spec(epic): fold Jake's answers to Q1–Q3 (FIX-1786) - #2806

Merged
jhoffner merged 1 commit into
mainfrom
epic/workforce-private-and-shared-answers
Oct 6, 2026
Merged

jhoffner merged 1 commit into
mainfrom
epic/workforce-private-and-shared-answers

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

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

  • Q1 · where an author says "this flow runs workers". 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. 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.
  • Q2 · private projects. Yes. FIX-1763's "projects stay org-level" fence is lifted, and FIX-1762's stack merged first. ER-7, leg b's private-project step, the docs draft and the plan no longer carry "if Q2 holds". If FIX-1793's spec finds private projects cost the MVP much more than a scope configuration, it raises that at its gate.
  • Q3 · FIX-1774 and FIX-1777. Yes. Both are closed (Canceled and Duplicate) and carried into FIX-1791 and FIX-1794.

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

  • DECISIONS.md → Q2, "Where it points." Jake expects org-level concepts may be a fast follow after the MVP. This PR records that and changes nothing because of it: the shared project, workstreams and library stay in the goal. Moving them past the MVP would be a separate change to the goal.
  • ER-2's wording, in BUSINESS-RULES.md. "A registered worker flow" has to hold under both shapes, because a wrapped flow is still registered with the installation.

What's asked of you

Approve and merge this head. Until it merges, the retained set on main still 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

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
@vercel

vercel Bot commented Oct 6, 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 6, 2026 6:41pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 6:41pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 6:41pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1786

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 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-06T18:44:31.753886Z 94db407 PR opened
ℹ️ 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.

@jhoffner
jhoffner merged commit 0f8064e into main Oct 6, 2026
15 checks passed
@jhoffner
jhoffner deleted the epic/workforce-private-and-shared-answers branch October 6, 2026 18:41

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass

Verdict: 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)

DECISIONS.md → Q2 "Where it points" says you expect org-level (shared) concepts may be a fast follow after the MVP. It also says the shared project, workstreams and library stay in the goal. Those two statements pull in different directions.

The following exist only for the shared half:

  • FIX-1795 (library)
  • the two-owner half of leg b
  • FIX-1793's "owner writes, org reads" engine rule (D3 change 2, the only new engine rule)

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)

BUSINESS-RULES.md:49 (ER-26) says a stacked PR "says DO NOT MERGE and retargets to main". docs/contributing/orchestration.md:170 now says "No DO NOT MERGE title" and uses GitHub stacks. ER-23 to ER-27 mostly restate that contract.

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 orchestration.md. Keep ER-23 and ER-27, which are epic-specific.

Checked and fine

  • ER-2 wording. "A registered worker flow" holds under both the list and defineWorkerFlow() shapes, because a wrapped flow is still registered. This is what the PR asks reviewers to check, and it holds.
  • Closing FIX-1774 and FIX-1777 into FIX-1791 and FIX-1794 is a net reduction.
  • The Q1 figure now shows the comparison the POC will run, which keeps the evidence and the decision aligned.

Generated by Claude Code

@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: 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".

Comment on lines +90 to +92
**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:

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 👍 / 👎.

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.

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

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

  1. 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.

  2. 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.

  3. concept/CONCEPT.md drift — 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.

  4. FIX-1789 should not reinvent workforce — Today you already have workerConfigSchema() as the authority (worker-config.ts explicitly rejects a marker wrapper), defineAgentWorkerFlow(), and hireWorkforce({ kinds }) as the installation map. Simpler FIX-1789 spec-poc: name those analogues and test whether a new defineWorkerFlow() adds a second authority or is mostly defineAgentWorkerFlow + registration — rather than a greenfield side-by-side in a vacuum.

  5. 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 + naive control; tuck record/R1 under “shape we rejected” (it motivated server-owned state, not a user row keyed by session id). C1 overlaps hand-off-cross-flow.test.ts — cite that test as sufficient for cross-flow lineage unless FIX-1794 needs more.

  6. 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.sh copy into orchestration — matches FIX-1549/1654 pattern; HTTP create legs can’t be replaced by testFlow without 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.

Open in Web View Automation 

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"]

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.

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.”

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.

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

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.

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).”

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.

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

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

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.

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

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.

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.

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.

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

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.

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.

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.

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

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Review of #2806, triaged (folded in #2807, head 78839b4, which needs approval and merge)

Second look:

  1. The shared half's fast follow: folded. FIX-1793's spec gate now asks it outright, beside Q2's cost check: does the shared project, "owner writes, org reads" and the library stay in the MVP? No is an amendment to the goal.
  2. ER-26: fixed as a correction. It points at orchestration.md's GitHub stacks. ER-24 and ER-25 stay: ER-24 now carries Q1's binding rule, and ER-25 is Jake's docs-with-code lock.

Simplify (Cursor): Q1's labels are fixed. The POC comparison and reusing defineAgentWorkerFlow() and hireWorkforce({ kinds }) as analogues go to FIX-1789 as notes. CONCEPT drift is already covered by its top note; the end-state POC's scope and the duplication points are not folded.

Codex P2: folded, as above.


Generated by Claude Code

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