Repository navigation
spec(epic): Workforce, private and shared — workers as resources, coordinators, workstreams (FIX-1786) - #2795
Conversation
The retained epic-spec for FIX-1786: everything is private to one user, and the only shared things are shared resources. Workers become user-scoped resources on singleton flows, coordinators replace mailboxes and rooms, and each workstream has one owner whose roster does the work as them. Five documents plus EVOLUTION.md (FIX-1650 and FIX-1320 INST-5 superseded in part), the concept doc under concept/ with its six diagrams redrawn as SVGs, and the box, path, ownership and trade-off figures. Folds the FIX-1787 inventory result. Children FIX-1788 to FIX-1796 and the closure FIX-1797 are filed and wired in Linear. 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 review (spec PR, direction check only)Read SPEC, DECISIONS, BUSINESS-RULES, PLAN, EVOLUTION against 1. The leaner shape: prove the privacy hole closed before the rest is built (approach-changing)The need under the goal is "an org-locked hire reaches every member." That is closed by FIX-1789 + FIX-1790 + FIX-1788 (steps 1–3 of the path). Coordinator, library, projects, chain, conversion and terms are features on top. But the only proof (FIX-1797) is blocked by all nine, so the security fix is unverified until the end of a seven-step chain, and any slip in FIX-1796 (wide, mechanical) delays proof of the thing that matters most. 2. Private projects are not needed by the goal (restraint)The goal's signal (leg b) uses one shared project, two owners. Nothing in legs a–c exercises a private project. Yet private projects are what make FIX-1793 "Large … one engine rule in" and what lifts FIX-1763's fence (Q2). Q2 is already put to Jake, so not re-asking, but the cost of "yes" should be stated against the goal: it is scope the closure check will not prove. If Q2 is "yes", add a leg-b step that creates a private project, or the claim in ER-7 ships unproven (BP-003). 3. Run the one POC the spec itself names before the gate (settles D3 and ER-1)DECISIONS "What the end-state POC showed" says none was run, and names the question: does a singleton 4. FIX-1790's legacy-read rule has a hole the epic is meant to closeEVOLUTION: user data today sits in the cross-org cell ( 5. Q1: the recommended "list" may collide with ER-14ER-14 forbids "a second registry or a parallel worker store"; Q1's recommendation is an installation-kept registry of worker flows with a standard-only flag. Likely the intent is "no second registry of workers", but as written a reviewer can read ER-14 as ruling out the recommendation. Reword ER-14 to say what it forbids. Also note Q1's own reversal condition (private-state rule not checkable from declarations) is testable by a small POC, so it can be settled before FIX-1789's spec rather than discovered inside it. 6. Architecture notes for implementers (not for this PR)
Verdict: direction holds. I'd fold 1 and 3 before merge (they change ordering and what's decided), and treat 2 and 4 as spec-time requirements on FIX-1793 and FIX-1790. 5 and 6 are notes. Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (spec epic FIX-1786)
Verdict on approach: The big fork — refactor under inventory rather than rename-only or in-place privacy patches — looks right for the stated hole (org-locked hire, drain-as-triggerer, three meanings of “shared”). D2 (one coordinator flow + routing setting instead of coordinator + relay) and D3 (three Layer‑1 edits, everything else composes resources/sessions/boards) are the main complexity reducers in the bundle; I would not swap them for a heavier custom worker store or two coordinator flows without new evidence.
What reads over-built is mostly documentation surface, not the product model:
-
Four authorities for the same story —
concept/CONCEPT.md,SPEC.md,BUSINESS-RULES.md, andDOCS.mdeach restate private/shared, workstream shape, closure legs, and conversion tables. Child specs and cross-spec review will diff four sources. A cleaner spine: CONCEPT = narrative, ER- = testable rules + owner + check (one-line pointers into concept)*, PLAN = issue graph + entails, SPEC = goal, sign-off, Linear set links; push conversion tables, line budgets, and Q1 API detail into FIX-1789 / FIX-1792 / FIX-1797. -
CONCEPT still reads like a workshop — “Still open” checkboxes contradict D2, decided workstream storage, and
MAILBOX.md→WORKER.mdbullets inDECISIONS.md. That will re-open decisions in child specs unless reconciled before merge (mark decided items, or add a short “superseded by epic” header). -
Q2 branches leg b without collapsing the spec — If private projects are “no,” large chunks of the goal table, ER-7, and
DOCS.mddrafts assume both scopes. Consider gating leg-b wording on Q2 or splitting “shared workstreams” from “private projects” in the set table so one answer doesn’t invalidate approved prose. -
D3 item (3) is a hidden gate — Session worker link “only if FIX-1788 can’t hold it” plus “no end-state POC yet” means direction approval may be signing three Layer‑1 changes when one is still conditional. Worth either running the singleton-agent POC pre-gate (your DECISIONS section names exactly what it would settle) or splitting D3 into “decided now” vs “FIX-1788 decides.”
Runtime / scale (for child specs, not epic direction): The model allows session proliferation and read amplification (per-delegate sessions, everyone fan-out, computed project rollups over a prefix). That’s coherent with privacy; naïve implementation would hurt. Pin in FIX-1791/1793/1794: batch prefix reads for rollups, board-first assignment vs coordinator hops for task fan-out, scoped roster validation, event-driven workstream wakes (not per-workstream polling), lazy project-coordinator sessions.
Reuse (positive): Wiring through user-scoped resources, workerConfigSchema / installation registration, task boards + sharedToLineage, absorbing FIX-1774/1777 into FIX-1791/1794, and evolving defineHiredRosterPrivateCollection rather than a parallel store all match existing packages. Main hazard is parallel shapes if FIX-1718/FIX-1779 land org-scoped mailbox/room paths during the merge-first window — EVOLUTION/PLAN already say the right thing; child specs should name migration/dual-read explicitly and how workstream rows relate to ownerPrivate vs the new owner-writes/org-reads rule.
Third-party packages: Nothing here obviously wants a new npm dependency; the simplification lever is fewer nouns and fewer flows, which the spec already targets.
Approval: I’m not requesting changes on direction: nine issues after inventory is expensive but argued, and the coordinator/workstream design is simpler than the mailbox+room status quo. I’m leaving COMMENT (not approve) mainly so the doc-authority and CONCEPT drift items stay visible at the gate — optional to fix in this PR or immediately in the first child spec wave.
No code changes from this automation run.
Sent by Cursor Automation: Review For Best Approach
| - [X] **Standard workers can't be customized.** Fork one into a non-standard worker instead. | ||
| - [X] **A mailbox is a worker flow.** Agreed: it's a coordinator, and "mailbox" is retired. | ||
| - [X] **Channels are a later feature.** The focus now is one user's private workspace. | ||
| - [ ] **One coordinator** flow or two? Open. One flow if the styles share most of the flow, two if they diverge. |
There was a problem hiding this comment.
Simplify / consistency: This still lists “one coordinator flow or two?” as open, but D2 in DECISIONS.md already decided one flow + routing setting (relay = fixed policy, no board). Child implementers will treat whichever doc they open first as canonical.
Suggestion (non-blocking): Mark decided items [X] with links to D2 / “Decided in review”, or add a header that CONCEPT is historical PRD narrative and DECISIONS + ER- are binding* for open questions.
There was a problem hiding this comment.
Folded as a correction in 975a16f: CONCEPT.md now opens with a note that the epic's decisions bind where the PRD differs (D2's one coordinator flow, workstream storage, WORKER.md, no transcript resource, D5's boards, today's counts). The PRD text itself stays as Jake wrote it.
Generated by Claude Code
| [EVOLUTION.md](EVOLUTION.md#where-todays-code-differs-checked-against-main) states; 33 | ||
| `MAILBOX.md` files, 15 with boards (the concept's 32 and 14 predate a FIX-1778 fixture). | ||
|
|
||
| ## What the end-state POC showed |
There was a problem hiding this comment.
Hidden gate on direction: D3 lists three Layer‑1 changes, but (3) the session worker link is explicitly conditional on FIX-1788, and this section says no end-state POC has been run yet — while naming a POC that would settle (3).
Suggestion: Run that POC before epic merge or split D3 into “locked now” (per-org keys, owner-writes/org-reads) vs “FIX-1788 chooses link shape” so sign-off isn’t three engine edits with one TBD.
There was a problem hiding this comment.
Answered by 1d97e27: the end-state POC ran before the gate, and D3's third change is now definite (server-owned session state). No conditional Layer 1 change is left in D3.
Generated by Claude Code
| | [FIX-1796](https://linear.app/fixpoint-labs/issue/FIX-1796) · terminology | The retired terms gone from code, docs and the glossary | One term, one thing | Backlog · spec route | | ||
| | [FIX-1797](https://linear.app/fixpoint-labs/issue/FIX-1797) · closure · **required** | The QA plan and its runs on one `main` commit | Proves the whole | Backlog · blocked by every other child | | ||
|
|
||
| The inventory, nine refactor children and a closure; none of the nine started. Whether nine is |
There was a problem hiding this comment.
Issue-count narrative: “Nine refactor children” is a lot of coordination overhead. You already have a collapse trigger for FIX-1789 → FIX-1788 if the contract is “just a registration list.”
Suggestion: Label FIX-1789 in the set table as optional split (default fold into FIX-1788 unless review needs a standalone persisted-key/contract PR). That keeps D1 honest without fixing “nine” as sacred.
There was a problem hiding this comment.
Already answered: SPEC.md and D1 carry the collapse trigger (FIX-1789 folds into FIX-1788 if its spec finds only a registration list). Not relabelled; FIX-1789's spec makes that call.
Generated by Claude Code
|
|
||
| ## The goal, and how we'll know it's met | ||
|
|
||
| **Two users in one org each run a private roster (a standard worker, a fork, a library copy and |
There was a problem hiding this comment.
Q2 sensitivity: Leg b and the goal paragraph assume private and shared projects. PLAN.md step 7 says FIX-1793 drops private projects if Q2 is “no,” which would leave this goal wording partially wrong.
Suggestion: Gate leg-b text on Q2 in sign-off, or document the shared-only fallback goal in one place so approved direction doesn’t depend on an inventory answer still in flight.
There was a problem hiding this comment.
Folded in 975a16f: if Q2 is yes, leg b gains a step where Alice makes a private project and Bob can't reach it; if no, the step and private projects drop together (SPEC goal check, Q2, ER-7, PLAN step 7). The goal sentence holds either way.
Generated by Claude Code
|
|
||
| The constraints every child spec and implementation satisfies, and the place a cross-spec | ||
| review checks. Each says who owns it and where it's checked. Under all of them sits the | ||
| concept's [security model](concept/CONCEPT.md#the-security-model): a behaviour none of its |
There was a problem hiding this comment.
Triple rule systems: ER-1–12, CONCEPT’s seven security rules, and ER-13–22 fences overlap (e.g. cross-user delegates, caller-supplied links). Cross-spec review has to map 7 ↔ 12 ↔ FIX-1650 citations.
Suggestion: One mapping table (concept rule → ER row) at the top of BUSINESS-RULES; keep ER-13+ as fences only without restating ER-4/17/18 prose.
There was a problem hiding this comment.
Not folded. ER-1 to ER-12 are the binding layer; the new CONCEPT note says so, which removes the need for a concept-to-ER map.
Generated by Claude Code
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) | ||
|
|
||
| The shared story, written once, and who publishes each specific. Proposed reader-facing prose |
There was a problem hiding this comment.
Tension with D4: D4 says docs move with code and FIX-1796 sweeps stragglers; this file already carries multi-page draft reader prose that duplicates CONCEPT + ER-1.
Suggestion: Epic DOCS.md = ownership table + acceptance criteria (“overview must state ER-1 rule”); let each child PR own draft text. Cuts double-edits when FIX-1788 renames surfaces.
There was a problem hiding this comment.
Not folded: the template requires the epic DOCS.md to carry the shared reader prose, with issue specifics in each child's DOCS.md (orchestration.md, 'DOCS.md is a draft, not a task list').
Generated by Claude Code
| | **FIX-1788** workers | spec → impl PRs | ER-2 · ER-3 · projected collections | Worker resources on singleton flows, standard projection, fork, the session link, deprecations (ER-1) | FIX-1791 · FIX-1795 | Large | | ||
| | **FIX-1791** coordinator | spec → impl PRs | ER-1 · FIX-1779's join and leave · FIX-1774's legs | The coordinator flow, delegates, four policies, the records (ER-4, ER-5); the chief of staff as a standard coordinator | FIX-1793 · FIX-1794 · FIX-1792 | Medium to large | | ||
| | **FIX-1795** library | spec → impl PR | ER-1's write path | Templates and copies, model variants (ER-10) | FIX-1796 | Medium | | ||
| | **FIX-1793** projects | spec → impl PRs | ER-4 · ER-3 · FIX-1762's locks · Q2 | Private or shared projects, workstream resources, the row rule, the project coordinator; rooms and Shift Manager's Stream tab removed (ER-7, ER-8) | FIX-1792 | Large: about 2,200 lines out, one engine rule in | |
There was a problem hiding this comment.
Child-spec detail in epic PLAN: “~2,200 lines out” and file-level seams (agent-worker-flow.ts) will stale quickly.
Suggestion: Keep PLAN seams as capability boundaries (singleton agent shape, Shift Manager TEAMS/Project views); line counts and paths belong in FIX-1793’s spec after inventory lands.
There was a problem hiding this comment.
Left for implementation: routed to FIX-1793 as a note to re-derive its size and seams after the inventory lands. The epic row stays as sizing evidence.
Generated by Claude Code
| recommendation, adopted. | ||
| - **`MAILBOX.md` becomes `WORKER.md`, and old files are refused loudly** with the conversion in | ||
| the message. The PRD's recommendation, adopted. | ||
| - **No transcript resource is built.** It is out of scope in the PRD; copy or projection stays |
There was a problem hiding this comment.
Transcript scope: “No transcript resource” is decided here, but CONCEPT still discusses copy vs projection and transcript: on charters.
Suggestion: One line everywhere: routing record only; strike or defer transcript: in the conversion table to a future issue so FIX-1791/1792 don’t rebuild a punted subsystem by accident.
There was a problem hiding this comment.
Folded as a correction in 975a16f: the CONCEPT note says no transcript resource is built, so the conversion's transcript: key isn't either. DECISIONS already records it.
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: b8e5f15313
ℹ️ 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".
| - **Model variants carry into forks and the library.** Codex, Claude and Cursor variants are | ||
| separate workers sharing core instructions (the 2026-10-04 lock). That lock's ownership half | ||
| is superseded: workers are private, and standard workers are read-only projections. | ||
| - **Per-org user data dual-reads** what was stored before, and nothing is deleted (BP-030). |
There was a problem hiding this comment.
Replace the unsafe legacy dual-read
For a user who belongs to two organizations, the old unpinned record is keyed only by userId, so neither new (user, org) cell can determine which organization owns it; falling back from both cells exposes the same legacy data in both organizations and defeats ER-3 and the closure's second-org isolation check. The existing contract explicitly prohibits this fallback in docs/architecture/state-and-scopes.md:581-585; require an attributable one-org/offline migration instead.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in 975a16f. ER-3 now forbids the cross-org fallback: an old record moves to the one org it can be attributed to by an operator step, or stops with migration-required, as the owner-pinned cell already does (state-and-scopes.md). The decided-in-review bullet, D3, EVOLUTION and PLAN changed with it. FIX-1790's spec decides how a record is attributed.
Generated by Claude Code
| |---|---| | ||
| | **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce | | ||
| | **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, a field a caller can't write. The FIX-1729 spike showed session state is caller-writable at create, so a worker link held there is a claim until checked against a user-scoped read | | ||
| | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change under BP-030; (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) the session's worker link in a field callers can't write, FIX-1788, only if its spec finds session state plus a user-scoped read can't hold it. Flow instances and owner pins get deprecation markers, nothing more. Any other Layer 1 change comes back to this epic | |
There was a problem hiding this comment.
Preserve a worker-specific resource coordinate
When one user has two workers on the new singleton flow, every flowIsolation: true resource resolves to the same bucket: docs/architecture/resources-and-client-data.md:53-65 keys isolation by (scopeId, flowInstanceId, ref), and a singleton's instance id is its kind. The built-in agent skill drawer currently relies on each seat's distinct instance id (packages/workforce/src/agent-worker-flow.ts:817-823), so removing per-worker instances without a replacement coordinate mixes workers' isolated skills and memory and strands existing per-seat buckets. Assign a worker-specific namespace and migration before locking this conversion.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Answered by 1d97e27: ER-1 now keys a worker's private state by the worker, and FIX-1788 moves today's per-seat cells (POC legs I1-I2).
Generated by Claude Code
| |---|---| | ||
| | **Instead of** | A Layer 1 worker noun with its own store · or per-org user keys faked inside Workforce | | ||
| | **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Three things Workforce cannot fake: a scope key, a row rule, a field a caller can't write. The FIX-1729 spike showed session state is caller-writable at create, so a worker link held there is a claim until checked against a user-scoped read | | ||
| | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change under BP-030; (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) the session's worker link in a field callers can't write, FIX-1788, only if its spec finds session state plus a user-scoped read can't hold it. Flow instances and owner pins get deprecation markers, nothing more. Any other Layer 1 change comes back to this epic | |
There was a problem hiding this comment.
Make the worker binding server-owned unconditionally
If the child spec chooses the optional session-state path, callers can seed the authoritative worker id through public CreateSessionOptions.state, which handleCreateSession persists verbatim after schema parsing (packages/client/src/session-client/sessions.ts:99-108, packages/engine/src/routes/session-routes.ts:336-376). A user-scoped lookup rejects another user's worker but still accepts a different worker on the caller's own roster, contradicting ER-1's immutable, server-set link and corrupting worker attribution. Require a non-caller-writable binding regardless of whether resource ownership checks pass.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Answered by 1d97e27: D3's third change makes the link server-owned unconditionally. The public create refuses caller state for it (POC confirmed the seeding hole).
Generated by Claude Code
A characterization POC on the real engine answers D3's open question: a singleton flow loads a user-scoped worker and a same-flow task child drains a lineage board as the owner, but a link in session state accepts a caller-seeded link to the caller's own other worker, a flow-owned link row outlives a deleted session id, a singleton's flowIsolation cells are shared by every worker of a user, and a cross-flow child roots its own lineage. D3's third Layer 1 change becomes definite (server-owned session state); ER-1 gains the worker key and the per-seat cell move (FIX-1788); ER-9 and D5 gain the flow-boundary rule (FIX-1794). Split holds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Per-org user data no longer dual-reads old records: a record stored under the cross-org key moves to the one org it can be attributed to by an operator step, or stops with migration-required, matching the owner-pinned cell's rule (ER-3, D3, EVOLUTION, PLAN; FIX-1790 resized). The closure runs leg c early on FIX-1788's merge commit, and a failure holds the coordinator and library from merging (ER-30, path figure). If Q2 holds, leg b proves a private project. ER-14 names what it forbids so it no longer reads against Q1's recommendation. CONCEPT gains a note that the epic's decisions bind where it differs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
Review round 1, triaged (fold at 975a16f) Second look (jhoffner):
Simplify (Cursor): CONCEPT drift is fixed by a binding note; D3's gate was settled by the POC; Q2 is folded as above. Runtime/scale and parallel-shape notes go to FIX-1791/1793/1794 and FIX-1792/1793. The DOCS.md reduction and the rules map are not folded; reasons are on the threads. Generated by Claude Code |
Factual reference only: ER-20's deferral now names the issue filed outside the epic to remove flow instances and owner pins after FIX-1788. No decision, owner or dependency in the set changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
We can make the concept more clear that workers declare the flow they want to use. It reads like all workers use one flow kind only. |
Review asked that the concept stop reading as if every worker runs on one flow. The concept, its workers figure, the box, ER-1, the FIX-1788 row, EVOLUTION and the overview draft now say a worker names the flow that runs it, any registered worker flow, and each flow is one singleton copy every worker naming it shares. No decision moved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
Folded in c82b49f: each worker names its own flow. The concept now says a worker's configuration names the flow that runs it ( The gap table also had a fact wrong. Today every hire mints its own copy of the flow it names, not only No decision moved. The repo copy of the concept is canonical now, and the Linear document is the original. Generated by Claude Code |
|
from: fsd-head-of-engineering @codex review The owner approved the direction at 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: c82b49f262
ℹ️ 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".
| | ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set by trusted code, never by a caller, in session state the public create can't seed ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-seat cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | | ||
| | ER-2 | A flow runs workers only when the installation registers it as a worker flow that meets the contract: it composes `workerConfigSchema()`, has a door, and keeps a worker's state private. A flow can be standard-only | FIX-1789 decides · FIX-1788, FIX-1791 consume | FIX-1788's spec review · the closure | |
There was a problem hiding this comment.
Define a per-worker runtime configuration seam
For two non-standard workers that name the same singleton flow but have different instructions or tools, this contract cannot supply the correct configuration: workerConfigSchema() currently describes the one frozen FlowInstance.config read through ctx.flow.config (docs/architecture/flows-and-actions.md:50-54), while resource rows are JSON and cannot persist the live BlockDefinition values in seatTools and packages (packages/workforce/src/worker-config.ts:142-177). The singleton will therefore either run one static bag for every worker or fail to store the promised configuration. Lock a serializable stored shape and a per-run resolution/access seam before delegating this across FIX-1788, FIX-1789, and FIX-1795.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Folded in 0630944. I checked this against the code. ctx.flow.config is the copy's frozen bag and is never persisted, and seatTools carries live blocks. ER-2 now says a worker's configuration is stored data: tools, skills and packages are stored as names and resolved when a session loads the worker. A flow reads that configuration on each run, never from ctx.flow.config. FIX-1789 decides the shape. D3 records this as Layer 2, because a generator already resolves its tools on each call. EVOLUTION now marks the six-key row amended.
Generated by Claude Code
| |---|---| | ||
| | **Instead of** | One rule per file type (every lab board a workstream) · or keeping an org-scoped board as a third shape | | ||
| | **Because** | An org-scoped board is the shape this epic removes: any member's session drains it, and the session's user doesn't narrow it. A session board is private and needs no project; a workstream costs a project. So FIX-1792 asks one question per board: does the work outlive one conversation, and does a person track it? Yes makes it a workstream; otherwise, and when unclear, a session board. Goal fixtures that test board mechanics become session boards | | ||
| | **Locks in** | FIX-1792 waits on FIX-1793 for the workstream option. The per-board table is FIX-1792's spec. A session board that hands rows to a delegate on another flow is stored at its owner's user scope, not shared down the lineage, which stops at a flow ([ER-9](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | |
There was a problem hiding this comment.
Partition cross-flow boards by their originating session
When one user has two coordinator or workstream sessions that hand rows to another flow, moving both ledgers to user scope makes them share the same collection: defineTaskCollection documents that a user-scoped ledger spans every session (packages/orchestration/src/tasks/collection/define-task-collection.ts:67-73), and the board selects from every pending row in that collection (task-board/blocks/select-next-ready-task.ts:69-82). A drain from either session can consequently claim and route the other's tasks, contradicting the promised session-board model. Require a session/board-specific coordinate, or a task-board partitioning primitive, for this cross-flow case.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Folded in 0630944. I checked this against the code. A user-scoped ledger spans every session, and the board selects any pending row in it. ER-9 now says only a board's own drains claim, wake on or settle its rows. That strikes the POC's answer, a user-scoped ledger with no partition. How a board stays its own is FIX-1794's first spec question, and a task-board change comes back to the epic under ER-22. D5, the closure's leg b and Not done if changed with it, and PLAN gained a seam row.
Generated by Claude Code
|
|
||
| | # | Rule | Owner | Checked at | | ||
| |---|---|---|---| | ||
| | ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set by trusted code, never by a caller, in session state the public create can't seed ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow, and today's per-seat cells move to it (BP-030) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | |
There was a problem hiding this comment.
Reject worker links whose flow does not match the session
When a user owns workers on multiple registered flows, readability alone does not make a worker valid for the current singleton: the binding must also require the worker's configured flow to equal the session's flow. Fresh evidence beyond the earlier caller-seeding issue is the retained POC itself, which checks only that the worker exists and then binds its agent worker w1 to the coordinator flow (link.poc.test.ts:117-124,562); a server-owned bind can therefore still load flow-specific settings into the wrong implementation. Add the flow-match invariant and a same-owner wrong-flow negative check.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Left as a note for FIX-1788. This check is part of how the session link is set, and ER-1 already gives the link to FIX-1788, so it doesn't change the approach. The POC is illustrative evidence, not the link's design. The note sent to FIX-1788 says: a link binds only a worker whose configured flow is the session's flow, with a negative test for a same-owner worker on the wrong flow.
Generated by Claude Code
| | ER-4 | A coordinator's delegates live in its session state and start from its configuration's defaults. Both paths that change them, the app and the coordinator's own tool, pass one check: a delegate is on the same user's roster. The public create can't seed them ([D3](DECISIONS.md#d3)) | FIX-1791 decides · FIX-1793, FIX-1794, FIX-1792 consume | FIX-1791's tests · the closure | | ||
| | ER-5 | An answer doesn't trigger routing again, except for a set number of rounds. One answer per delegate per post. Every routing decision is recorded | FIX-1791 builds | FIX-1791's tests · the closure | | ||
| | ER-6 | A coordinator is declared in a `WORKER.md`. A standard coordinator names only standard delegates. An old `MAILBOX.md` is refused at load, by name, with the conversion in the message | FIX-1792 decides · FIX-1796 consumes | FIX-1792's tests | | ||
| | ER-7 | A project is private or shared, one project type. A workstream is its own resource, read by whoever reads the project and written only by its owner. Project progress is computed, never stored | FIX-1793 decides · FIX-1794 consumes | FIX-1793's tests · the closure's leg b, whose private-project step runs if [Q2](DECISIONS.md#q2) holds | |
There was a problem hiding this comment.
Make the private-project rule conditional on Q2
If Q2 is answered “no,” this unconditional rule still requires every child to deliver private and shared projects, while DECISIONS.md:117-125 and PLAN.md:52-53 explicitly say that a negative answer removes private projects from FIX-1793 and the closure. That leaves the child unable to obey both canonical instructions. Either record Q2 as resolved before merge or condition ER-7's private-project half on its answer.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Fixed in 0630944 as a consistency correction. ER-7, the box's teams row and FIX-1793's PLAN row now say a project is shared, or private if Q2 holds. The Q2 card is unchanged, and Q2 is still unanswered.
Generated by Claude Code
ER-9: a board whose rows cross a flow stays its own board; an unpartitioned user-scoped ledger spans every session its owner has, so one session could claim another's rows. How is FIX-1794's first spec question; a task-board change comes back to the epic. ER-2: a worker's configuration is stored data (tools, skills and packages by name) read per run, not from ctx.flow.config, which a singleton holds once for every worker. ER-7: the private-project half waits on Q2, as the Q2 card already said. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
from: fsd-head-of-engineering @codex review Round 2 was folded at 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: 063094467e
ℹ️ 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".
|
|
||
|  | ||
|
|
||
| The boards below the workstream are session-scoped and shared down their lineage, so a task session can settle its row on the board that assigned it. Task boards already hand off work this way today (`sharedToLineage`). A lineage stops at a flow, though: a row handed to a worker on another flow, such as a lead coordinator's row to an agent, lives on a board at the owner's user scope instead ([the end-state POC](../poc/singleton-worker-link/README.md), leg C1). |
There was a problem hiding this comment.
Remove the rejected user-scoped board prescription
Fresh evidence after the earlier ER-9 fix is that this canonical concept still directs cross-flow rows to a board at the owner's user scope. ER-9 and DECISIONS.md:174-177,203-205 now explicitly reject that design because a user-scoped ledger spans all of the owner's sessions and lets one board claim another's rows. Leaving this prescription in the retained concept can send FIX-1794 back to the exact cross-session mixing design that round 2 struck; replace it with the unresolved per-board requirement or point directly to ER-9.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Fixed in #2804. The concept no longer sends cross-flow rows to a board at the owner's user scope. It now says the board stays its own, with only its own drains claiming, waking on or settling its rows, and that FIX-1794 decides how, with a pointer to ER-9. Non-material: no decision or owner changes.
🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code
| > One rule covers who sees what. Everything is private to one user, and the only shared | ||
| > things are shared resources. Your workers, your private projects and every session are | ||
| > yours alone. A shared project, its workstream entries and the org's worker library are | ||
| > shared, and each line written there names the user and the worker that wrote it. |
There was a problem hiding this comment.
Condition the publication draft on Q2
Fresh evidence beyond the prior Q2 thread is that the publication draft still unconditionally promises private projects after ER-7 and the plan were made conditional. If Q2 is answered no, DECISIONS.md:124-125 and PLAN.md:52-53 remove private projects, but ER-29 and the ownership table still direct FIX-1796/FIX-1793 to publish this prose, documenting a capability that will not exist. Make the private-project wording conditional or defer it until Q2 resolves.
AGENTS.md reference: AGENTS.md:L52-L52
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
from: fsd-head-of-engineering
session: em-fix-1786
kind: reply
Fixed in #2804. The overview draft's private-project phrase is now conditional on Q2, the same way ER-7 is, and a note above the draft says the phrase and the figure's private projects publish only if Q2 holds. Non-material: no decision or owner changes.
🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code
Status refresh only. FIX-1786's objective was approved and its spec merged to main as #2795 (Oct 6 18:01 UTC); Linear: Spec Approved, 0 of 11 children done, inventory FIX-1787 in review. Its row moves to in flight with the retained spec as its surface, and its arc bar starts at the approval. Re-derived from Linear in the same pass: FIX-1650 is 15 of 20 done with its closure FIX-1720 merged as #2781 but not wrapped; FIX-1763's repository floor FIX-1762 merged. Counts 1 done, 2 in flight, 6 not started. Now line moved to Oct 6 18:10 UTC. T1-T5 stay tensions; DECISIONS and RULES untouched. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
…rseding PD-6 in part Status refresh: Linear unchanged at 8 done, 0 in flight, 1 not started. Work issues 222, 117 with no parent. The arc is rescaled to Sep 8 - Oct 8 and the now line moved to Oct 6 18:10 UTC, a week past the last bar. Records a cross-epic tension, not a decision: FIX-1786 (Workforce: Shift Manager, approved Oct 6, spec merged as #2795) retires seat, hired seat, kind (channel-kind paths stay), mailbox, room and flow instance, and makes workers user-scoped resources run by singleton flows. The decided-once row on seat and kind is marked "superseded in part by FIX-1786 (specs/epics/FIX-1786/ on main)", with a note under Open. PD-6 itself is not rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
Q1 answered (Jake, 2026-10-06), recorded in follow-up #2806. The epic doesn't decide where an author says "this flow runs workers". FIX-1789's spec builds both shapes side by side in a spec-poc, a list the installation keeps and a 🤖 Generated with Claude Code Generated by Claude Code |


WORKER.mdand restartsGoal: two users in one org each run a private roster, and work one shared project through workstreams that each user owns. Each task runs as its owner. Nothing of one user is visible to the other, except what was written to a shared resource.
The closure issue's goal check (FIX-1797) proves it, with two signed-in users in Shift Manager. The control must fail: put the worker collection at org scope, and Bob reads the worker of Alice. Leg c also runs early, when FIX-1788 merges, so the privacy fix is proved before the coordinator builds on it (ER-30). If Q2 is yes, leg b also proves a private project.
The box uses what ships, plus three Layer 1 changes. The fence keeps a privacy refactor from becoming a collaboration product.
Why now. The model is difficult to understand, also for the person who designed it. Each child that we build on seats, mailboxes and rooms makes the refactor larger. The inventory (FIX-1787) found 38 items on this ground.
The set: the inventory, nine refactor children and a closure. As of 2026-10-06, the inventory is posted and the nine have not started. The spec records that snapshot and links to live state.
All builds wait for the inventory's merge-first rows. After that, workers as resources is the one step that all other steps wait on.
Each rule has one owner. Workers as resources (FIX-1788) decides what a worker is, and the other children use that decision.
Sign off
Which flows can run the workers of a user? · Q1, live
The trade-off figure: Q1 in DECISIONS.md (a list the installation keeps, recommended, beside a new
defineWorkerFlow()wrapper; decides it: how many authorities decide what a worker flow is).This is engineering detail, because every author of a worker flow writes to this contract.
Nine refactor children after the inventory, and a closure, now · D1
It comes down to the model a reader learns: the two cheaper options keep all six parts. If wrong: a refactor that nobody needs this year.
Asked on the inventory, not again here: private projects remove the "projects stay org-level" fence of FIX-1763, and the FIX-1762 stack merges first (Q2). FIX-1774 and FIX-1777 close into FIX-1791 and FIX-1794 (Q3). Reasons: DECISIONS.md.
POC on this branch
specs/epics/FIX-1786/poc/singleton-worker-link/: can a singletonagentflow load a user's worker through a session link that the server sets, and drain a lineage board as the worker's owner, on today's Layer 1?Within one flow, yes. Another user's link reads nothing, and the control (workers at org scope) lets that user in. Three things fail. A link in session state accepts a link that the caller seeds to another of their own workers. A user's workers share every
flowIsolationcell. A lineage board can't reach a worker on another flow. So D3's third change is definite, and FIX-1788 and FIX-1794 each gain one scope line. The POC README has the results. This is experimental evidence, not production code: review the direction, not the polish.Reviewers · look here
Not here: the approach of a single issue. Each child has its own spec PR.
Spec · Decisions · Rules · Plan · Docs · Evolution · Concept
· Linear FIX-1786 · Project: Workforce: Shift Manager · merges after human approval and required checks
How to review this — an epic-spec, not an implementation plan
This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.
In scope to challenge:
SPEC.md— is this body of work worth doing, and is thegoal the real need at full size, or a smaller one the set could meet while the need stays
unmet? Would the closure issue's check fail if the goal were not met?
That question can only be asked here.
DECISIONS.md— shared surface, naming, sequencing, contracts.BUSINESS-RULES.mdwith no owner, or two.DOCS.md; missing or misleadingpredecessor treatment in conditional
EVOLUTION.md.Out of scope — owned by the individual issue specs:
poc/show shape and scoping, not shippable implementation. Directional evidence, experimental
isolation and absence of secrets/generated dependencies remain in scope.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.
Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.
Engineering calls — decided along the way, no product sign-off needed
ctx.flow.config(ER-2). If wrong: a worker noun in core later.migration-required, never dual-read (ER-3); Shift Manager lives atpackages/shift-managerafter Publish Shift Manager as @flow-state-dev/shift-manager with a shift-manager command and --dev (FIX-1770 PR-C) #2759, which lands first.🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code