Skip to content

spec(FIX-1793): amend after merge · each Shift Manager workstream gets its own coordinator - #2861

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-1793-amend-default-coordinator
Oct 7, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-1793-amend-default-coordinator

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator

The problem

FIX-1793's spec, merged in #2823, lets Shift Manager open a workstream from a project, but never says who leads it. openWorkstream needs 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.

  • Opening a workstream in Shift Manager creates its lead. The view forks a new standard workstream coordinator onto the owner's roster, through the fork action FIX-1788 ships. It then sends openWorkstream with that coordinator as the lead. Each workstream gets its own.
  • The framework doesn't change. openWorkstream still 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 through ensureWorkerSession with a workstreamId criterion, and the one delegate record on the owner's project coordinator (which FIX-1791's roster check accepts).
  • It is an ordinary worker of the owner's. It never appears on another user's roster. If Bob names it as his lead, the open is refused as if the worker didn't exist (BR-10).
  • It stays when the workstream is done. This is the smaller rule: it is what happens to any worker. Firing it would break moving the workstream back out of done, because restoring the delegate record runs the roster check on the lead, and a fired worker's session takes no new turn.
  • Each workstream forks once. The coordinator's id comes from the workstream's address. A repeated or simultaneous open finds that coordinator and reuses it. A refused open fires the coordinator it forked.

D2: what leads a workstream opened in Shift Manager. Its own new coordinator, chosen, beside no default and one coordinator for all of an owner's workstreams. Decides it: a lead of its own with no step first. Price: one worker per workstream on the roster, kept after done. Tie: the framework is unchanged under all three

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

  • The worker it forks from is new. The brief said "the installation's standard coordinator", but neither standard coordinator in the DevTeam setup fits. The chief of staff hires, fires and opens projects. The project coordinator hands posts to workstreams, so a copy of it would hand posts to itself. S9 therefore adds a standard workstream coordinator on the coordinator flow, whose default delegates are standard DevTeam workers, at least one of which takes a task. If you meant one of the existing two, say which.
  • Two facts to check before P3 builds this (PLAN → At implement time). FIX-1791's coordinator flow must accept a delegated post, or the project coordinator's posts to this lead are skipped and leg c of the goal fails. Also, the DevTeam setup must not reserve the coordinator flow for standard workers, or the fork is refused. If either doesn't hold, it goes back to that issue rather than being built here.
  • Out of scope, listed as follow-ups: choosing an existing worker in the open (S8 never offered one), and the same default for the chief of staff's openWorkstream tool.
  • Implementation has started. P1 (#2827, the owner rule) is merged. Nothing in it changes. This amendment touches S8 and S9 in P3, which hasn't started.

Links: original spec review #2823 · P1 #2827 · FIX-1793 · epic FIX-1786. This merges into main when the product owner merges it.

Sections changed
  1. 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.
  2. PLAN.md → S9. Adds the standard workstream coordinator WORKER.md, which the project setup names as the worker S8 forks.
  3. 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.
  4. PLAN.md → header, At implement time, Follow-ups.
  5. 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.
  6. DECISIONS.md. Adds D2 as the product owner's call, with Instead of naming no default and one shared coordinator, plus its trade-off figure figures/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.
  7. SPEC.md → Sign off. Adds decided item 5.
  8. DOCS.md. Adds an "Opening a workstream" paragraph to Shift Manager's overview, plus the matching README line.
  9. 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-rename and validate-changeset-refs all 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

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

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

Request Review

@linear-code

linear-code Bot commented Oct 7, 2026

Copy link
Copy Markdown

FIX-1793

@jhoffner jhoffner added the spec label Oct 7, 2026
@jhoffner
jhoffner marked this pull request as ready for review October 7, 2026 22:51
@jhoffner
jhoffner merged commit 0653809 into main Oct 7, 2026
18 checks passed

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

  1. 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.
  2. Stable refusal reason for "wrong worker at derived coordinator id" — taxonomy names BR-36 but not a reason string like other refusals.
  3. DECISIONS.md opener still says "two questions and one decision" while D2 is a fourth decided surface post-merge — small hygiene fix.
  4. 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 /simplify without 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.

Open in Web View Automation 

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 |

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.

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

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.

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 |

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

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.

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 |

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.

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.


![D2, decided: what leads a workstream opened in Shift Manager. Its own new coordinator, chosen, beside no default and one coordinator for all of an owner's workstreams. Decides it: whether each workstream has a lead of its own with no step first; no default needs a hire or a pick on every open, and a shared coordinator carries one edit into every workstream. Price: one worker per workstream on the roster, kept after done. A tie: the framework is unchanged under all three. Flips if owners' rosters become hard to read for workstream coordinators](figures/d2-own-coordinator.svg)

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.

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.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants