Repository navigation
spec(FIX-1793): amend after merge · each Shift Manager workstream gets its own coordinator - #2861
Conversation
…s its own coordinator The product owner decided on 2026-10-07 that every workstream in Shift Manager comes with its own coordinator by default. S8's open forks the standard workstream coordinator (new in S9) onto the owner's roster and names it as the lead; openWorkstream and the framework are unchanged. Adds D2 with its trade-off figure, BR-35 to BR-37, V8a, the docs lines and the EVOLUTION entry. A workstream's coordinator is kept when it is done. 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
|
There was a problem hiding this comment.
/simplify review · spec amendment (D2)
This PR is spec-only: it records the product call that Shift Manager forks a standard workstream coordinator per open (deterministic roster id) and passes it as openWorkstream's lead, leaving S3/framework unchanged. I ran parallel read-only passes (quality, performance, reuse against current main).
Is the approach too heavy?
The product choice (one coordinator per workstream) is coherent with the epic model and the stated UX goal (lead with no picker, edits scoped to one workstream). The rejected alternatives in D2 are fairly traded off.
Mechanical complexity is real, and mostly comes from the boundary you chose, not from D2 itself:
| Layer | What the spec does | Simpler mechanical option (same product intent?) |
|---|---|---|
| Shift Manager (S8) | Fork before openWorkstream; BR-36 fire on refused open; id + forkedFrom checks |
Run member/visibility gates first, fork only when open will succeed; or a Shift Manager–scoped helper ensureWorkstreamLead(...) so BR-35/36 aren't prose duplicated in S8 + BR + V8a |
| Workforce (S3) | openWorkstream always requires lead |
Optional/default lead in workforce (install-scoped) — rejected explicitly to keep framework neutral; fair, but it concentrates orchestration in the view |
| Install (S9) | Second standard coordinator WORKER.md |
Worth validating whether project-coordinator + different session criteria could suffice; spec argues neither standard worker fits as fork seed — I'd keep S9 unless implement-time diff is trivial |
Reuse check on main: FIX-1788 fork today refuses duplicate ids (not idempotent); BR-36's find-or-fork + forkedFrom validation is new view logic, analogous in shape to ensureWorkerSession + derived session ids, not an existing helper. That's expected, but implementers should use point reads on the derived worker id (not full roster listAll on every open) — worth a one-line guardrail under S8 if you want to head off perf footguns.
What I'd tighten before implementation (not re-litigating D2)
- Ordering when the entry already exists — BR-14 (one entry), BR-21a (reopen restores delegate), and BR-36 (idempotent coordinator) don't yet say whether Shift Manager still forks when the entry is already there. One sentence in S8 or a BR-36 sub-clause would prevent two P3 implementations that both claim to pass V8a.
- Stable refusal reason for "wrong worker at derived coordinator id" — taxonomy names BR-36 but not a
reasonstring like other refusals. - DECISIONS.md opener still says "two questions and one decision" while D2 is a fourth decided surface post-merge — small hygiene fix.
- Prose duplication — D2 + EVOLUTION + S8 cell + BR-35–37 + DOCS repeat the same story; BR-35–37 + D2 "Locks in" could be canonical with S8 shortened to pointers (fits
/simplifywithout changing behavior).
Performance note (for implementer, not spec-blocking)
D2 grows roster rows without cap (BR-37 keeps coordinators after done; BR-21b only caps open delegates). That's an accepted product price in D2; the main runtime risk is amplified roster listing in ensureWorkerSession if opens don't use get-by-id — optional implementer note only.
Verdict
Directionally approve the amendment — framework-neutral default via Shift Manager is consistent with FIX-1793's split, and the extra rules are the cost of fork-first + deterministic ids. I'm not approving merge yet; I'd like the BR-14 / BR-21a / BR-36 ordering and named refusal reason clarified (inline). The rest is simplification / dedup I'd treat as nice-to-have before or during P3.
No code changes from this automation run — review only.
Sent by Cursor Automation: Review For Best Approach
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-35 | Alice opens a workstream from a project in Shift Manager | Its lead is a new coordinator of its own: Shift Manager forks the standard workstream coordinator onto her roster, then opens the workstream with it as the lead, as BR-7 and BR-9 have it. One entry, its workstream session on that coordinator, and one delegate record on her project coordinator. Her next workstream gets another. It is an ordinary worker of hers: Bob's roster never lists it, and naming it as Bob's lead is refused like a missing worker (BR-10) | CI · V8a | | ||
| | BR-36 | The same open is sent twice, at once or after a failure, or the open is refused | One coordinator. Its id comes from the workstream's address, so a second open finds it on her roster, forked from the standard workstream coordinator, and uses it. Any other worker of hers at that id refuses the open, naming the id, and nothing is written. A refused open, such as `not-a-member`, fires the coordinator that open forked, so her roster is as it was | CI · V8a | |
There was a problem hiding this comment.
BR-36 bundles a lot (idempotent fork, collision at derived id, compensating fire on refused open). Consider splitting into two rules or a numbered "Then" list inside the cell so V8a maps 1:1 — behavior unchanged, easier to test.
Also: when the entry already exists (BR-14 / BR-21a), should Shift Manager still run fork-first, or skip straight to openWorkstream? That ordering isn't spelled out and two implementers could diverge while both citing this rule.
| owner-rule error. A lost compare-and-swap is retried, as the row writes are | ||
| today. Nothing is ignored silently, and nothing stored is deleted. | ||
| `not-a-member`, `no-such-project`, a missing worker, FIX-1791's delegate cap, `not-the-owner`, the engine's | ||
| owner-rule error, and, in Shift Manager, a worker of the owner's already at a workstream |
There was a problem hiding this comment.
Other refusals in this taxonomy use stable reason strings (not-a-member, etc.). For the BR-36 collision case ("worker already at workstream coordinator id" / wrong forkedFrom), consider pinning the exact code here so CI, docs, and Shift Manager stay aligned.
| | S7 | `workforce` · **removals** | Rooms: `talk.ts`, `room-store.ts`, `room-answer.ts`, `talk-template.ts`; the mailbox kind's `bind`, `onTalkPosted`, `join`, and the talk branches of `post`, `read`, `answer`, with no entry kept to refuse them. No room collection is read or written, and the room collections stop being declared; their rows are dropped ([epic D9](../../epics/FIX-1786/DECISIONS.md#d9)). `mintFor` and the `talk` option go with them, not refused by name. Claims, `setWorkstreams` and a row's mailbox list stay, with no markers, until FIX-1792 | BR-32 | | ||
| | S8 | `shift-manager` · views | PROJECTS lists shared and the viewer's private projects. A project's Workstreams tab lists entries with S4; its Stream tab is the viewer's project coordinator session; its Board draws the viewer's own workstream sessions' boards only, never through the Lab-wide inventory walk. An entry's view: its owner sees the lead's workstream session, others the entry. Open a workstream from the project. A project view opens on the row plus one entry prefix, not a Lab read; the whole Lab is read again only after a coordinator turn. `lib/talk.ts`, `talkFor` and the room session **removed** | BR-12 BR-18 BR-28 | | ||
| | S9 | `shift-manager` · DevTeam install | A standard `project-coordinator` `WORKER.md` (`flow: coordinator`, `routing: judgment`), named in the project setup; the chief of staff's project tools gain `visibility` and `openWorkstream`. Default projects stay shared. The room parts out: `resources/projects.ts`'s `talk:` template (the option goes, S7), the EM's room-answer action, and the room door in `notify.mts` ([inventory](poc/removal-inventory/README.md#what-was-observed)) | BR-21 | | ||
| | S8 | `shift-manager` · views | PROJECTS lists shared and the viewer's private projects. A project's Workstreams tab lists entries with S4; its Stream tab is the viewer's project coordinator session; its Board draws the viewer's own workstream sessions' boards only, never through the Lab-wide inventory walk. An entry's view: its owner sees the lead's workstream session, others the entry. Open a workstream from the project, with a coordinator of its own as the lead ([D2](DECISIONS.md#d2)): the view forks the standard workstream coordinator (S9) onto the viewer's roster through FIX-1788's fork action, under an id derived from the workstream's address, then sends `openWorkstream` naming it as the lead. S3 is unchanged, and so is every rule it runs: the roster check on the lead, the workstream session, the delegate record. The view offers no choice of an existing worker. A worker already at that id, forked from the standard workstream coordinator, is used, not forked again; any other worker at that id refuses the open, naming it. A refused open fires the coordinator that open forked. A project view opens on the row plus one entry prefix, not a Lab read; the whole Lab is read again only after a coordinator turn. `lib/talk.ts`, `talkFor` and the room session **removed** | BR-12 BR-18 BR-28 BR-35–BR-37 | |
There was a problem hiding this comment.
/simplify: this S8 cell largely duplicates BR-35–BR-37. Consider shortening to "Open per D2; mechanics BR-35–BR-37; proved V8a" and keeping the fork/idempotency/fire story only in BUSINESS-RULES — same behavior, less drift risk when one copy edits.
| @@ -5,8 +5,10 @@ | |||
| Two questions and one decision are the sign-off surface, all decided: Jake answered Q1 and Q2 on | |||
There was a problem hiding this comment.
Opening line still says "Two questions and one decision are the sign-off surface" but D2 is a separate post-merge product decision (paragraph below already says so). Worth updating the count so readers don't treat D2 as re-openable scope at the original gate.
| | | | | ||
| |---|---| | ||
| | **Instead of** | No default: the owner names a lead from their roster on every open · one coordinator for all of an owner's workstreams, made on their first open and named on every later one | | ||
| | **Because** | The product owner's call. It buys a lead of its own with no step first, even on a roster with nothing fit to lead, and an edit to one coordinator changes one workstream. With no default, every open waits on a hire or a pick; with one shared coordinator, an edit reaches every workstream. Shift Manager forks the standard workstream coordinator through FIX-1788's fork action, then sends `openWorkstream` naming it, so S3's roster check (BR-10), the workstream session (`ensureWorkerSession` with a `workstreamId` criterion) and the delegate record (BR-21a) run as written. The framework doesn't change | |
There was a problem hiding this comment.
For implementers comparing alternatives: the rejected path "workforce default lead / optional lead on openWorkstream" isn't named in the decision tree (only "no default" picker UX and "one coordinator for all"). A short Considered and dropped bullet here would document why complexity landed in S8 — without reopening the product call.
|
|
||
|  | ||
|
|
||
| It comes down to a lead of its own: no default makes every open wait on a pick, and a shared one carries each edit everywhere. |
There was a problem hiding this comment.
This sentence restates the SVG and the Because row above it — safe to drop for word budget if you want a tighter fold (per writing-for-humans).


The problem
FIX-1793's spec, merged in #2823, lets Shift Manager open a workstream from a project, but never says who leads it.
openWorkstreamneeds a lead from the owner's roster, and a new user's roster has nothing suited to lead a workstream. On 2026-10-07 the product owner decided that every workstream in Shift Manager comes with its own coordinator by default. This PR records that decision in the retained spec.What this does
It changes only
specs/issues/FIX-1793/. No code changes.openWorkstreamwith that coordinator as the lead. Each workstream gets its own.openWorkstreamstill takes a lead, and other apps choose their own. Because the coordinator is on the roster before the open, everything S3 already runs works as written: the roster check on the lead, the lead's session throughensureWorkerSessionwith aworkstreamIdcriterion, and the one delegate record on the owner's project coordinator (which FIX-1791's roster check accepts).The deciding row is having a lead of its own. With no default, every open waits on a hire or a pick. With one shared coordinator, every edit to it reaches every workstream.
What's asked of you
The product owner has already made this call, so this PR records it. Check that the record says what you meant, then merge it. No question is open.
Parts worth reviewing closely
openWorkstreamtool.Links: original spec review #2823 · P1 #2827 · FIX-1793 · epic FIX-1786. This merges into
mainwhen the product owner merges it.Sections changed
PLAN.md→ S8. Opening a workstream forks its own coordinator and names it as the lead. It covers reuse on a repeated open, the refusal when a different worker already holds that id, and the fire after a refused open. The rules column adds BR-35 to BR-37.PLAN.md→ S9. Adds the standard workstream coordinatorWORKER.md, which the project setup names as the worker S8 forks.PLAN.md→ Checks. Adds V8a, which runs in Shift Manager's tests with two users. An open with no lead chosen creates exactly one coordinator on the owner's roster and makes it the lead, the worker on its workstream session, and the target of the delegate record. A second workstream gets its own, and Bob's roster is unchanged. A repeated open, or two at once, forks once. A refused open leaves the roster as it was. Marking the workstream done keeps the coordinator. "One check per decision" now includes D2.PLAN.md→ header, At implement time, Follow-ups.BUSINESS-RULES.md. Adds a section, Opening a workstream in Shift Manager, with BR-35 (the default lead), BR-36 (one coordinator per workstream, and a refused open leaves nothing behind) and BR-37 (kept when done). The failure taxonomy also changes.DECISIONS.md. Adds D2 as the product owner's call, with Instead of naming no default and one shared coordinator, plus its trade-off figurefigures/d2-own-coordinator.svg. The tree, the intro, two lines in Decided, not asked (kept when done, and the derived id), the chief of staff's tool line, and a How it got here entry also change.SPEC.md→ Sign off. Adds decided item 5.DOCS.md. Adds an "Opening a workstream" paragraph to Shift Manager's overview, plus the matching README line.EVOLUTION.md. Adds a new section, Amended after merge: each workstream's own coordinator.Checks run:
validate-spec-folder,validate-publish-set,validate-no-nul-bytes,validate-model-strings,validate-reserved-names,check-isolation-coordinate,check-mailbox-renameandvalidate-changeset-refsall pass. The spec-figure checks 1 to 7 pass: fences balanced, no risky mermaid labels, each SVG self-contained with both themes and an aria-label, nav lines present, and every card paired with its figure. The new figure was rendered in light and dark and checked by eye.🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code