Repository navigation
spec(FIX-1796): Remove the retired Workforce terms from code and docs - #2832
Conversation
The epic's last sweep before the closure: a census of every retired term over every tracked file, with token-level exceptions, is the goal check and becomes the CI guard. Three decisions for sign-off: a task board's seat becomes its assignee (D1), saved names keep their strings (D2), renamed exports break with a table and no aliases (D3). 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 (direction only)The direction holds. D1–D3 are sound: no aliases, saved strings untouched, and the board's 1. The census can pass while a live retired term remains (above the bar)
2. A permanent guard over ordinary English words is a standing tax (restraint)
Alternative: keep the goal check and the closure run (FIX-1797) as stated, but make the permanent guard cover only the unambiguous terms (seat, mailbox, hired roster, talk session, and room/kind/owner pin on Workforce ground). Treat 3. Normalize the legacy hand-off
|
|
Architect · coherence check on the FIX-1786 set (not a line review) Two things cross this spec with in-flight work. Please resolve them in this PR or in the epic follow-up, not later in the build. 1. D1 is a Layer 1 change, and the epic has not recorded it. D1 renames public exports of the task board in
2. #2828 (FIX-1794) publishes new task board text that uses "seat", and this spec retires that word. FIX-1794's DOCS.md says "a seat that hands off", "its seats hand off" and "a seat can still hand off". Its PLAN S2/S3 adds "seats that hand off" and a Small item for the same epic follow-up: your Settled section confirms that no The vocabulary mapping matches the epic concept and FIX-1793 (merged). I have no notes on D2 or D3. |
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision On the architect's coherence check: 1. D1 is a Layer 1 change, so the epic records it after its gate, not inside this PR. Renaming the task board's public exports, the hand-off record's 2. FIX-1794's new board text: this sweep owns it. Until the epic records D1, the task board's word is the one it ships with today. FIX-1794 (#2828) keeps "seat" in what it adds, and it is not reopened at its gate. Please list FIX-1794's seat-named additions in At implement time as names this sweep renames: the DOCS phrases "a seat that hands off", "its seats hand off" and "a seat can still hand off", and PLAN S2/S3's "seats that hand off" and Small item: the channel-kind paths in the epic's What stays as it is, ER-12 and ER-20 go into the same amend-5. Nothing here changes for that. Generated by Claude Code |
There was a problem hiding this comment.
Summary
This is a spec-only PR for the epic’s vocabulary sweep. The hard part is not renaming strings — it is enforcing “one term, one idea” across ~600+ files without a blind find-replace (DECISIONS already rules that out) and without a guard that can be gamed. For that goal, the census → CI guard shape is proportionate and consistent with prior art (check-mailbox-rename.mjs, FIX-1748 / FIX-1428 POC → script).
I do not think a materially simpler approach replaces this spec without weakening ER-12 or the anti-game rules (token-strip exceptions, workforce-ground scoping, totality for new top-level dirs). Ripgrep + allowlist, AST-only lint, or extending the mailbox guard in place would either miss prose/mixed English or accrete two survivor models in one file.
Approve on direction. The notes below are simplification opportunities for implementation (S10) and a few spec tighten-ups — none block merging this spec.
What already looks right
- Three PRs (board → Workforce surfaces → prose/glossary/guard) match reviewability and the orchestration import seam.
- D2 + D3 are the right tradeoffs for this epic (no data moves; no export aliases at closure).
- POC evidence (counts,
--control, stale-exception reporting) matches tenet 7 better than hand-waved file counts. - Dropping
check-mailbox-renameis coherent once mailboxes are retired terms — keeping it would guard vocabulary the product is abandoning (DECISIONS“Considered and dropped”).
Simpler / cleaner alternatives considered
| Alternative | Verdict |
|---|---|
| Scripted find-replace | Correctly rejected — seat / person context |
| One mega-PR | Correctly rejected — review and rollback cost |
| Ripgrep-only CI | Insufficient for strip exceptions, workforce ground, D2 stored keys |
| Third-party word linter | None in repo; would not encode BR-10/12/13 without comparable custom rules |
| Keep mailbox guard + add retired-terms guard | Worse ops story; two totality tables to drift |
Where complexity may grow (implementation phase)
- S10 production guard — Plan adds glossary row uniqueness on top of the POC. Before CI lands, mirror
check-mailbox-rename.mjs: export purescanFile/census(in-memory maps), vitest plants inpackages/core/test/(not workforce), CLI thin. Consider a smallscripts/lib/guard-totality.mjsshared with the mailbox guard’s history/process/goals buckets so area regexes do not drift a third time. person(~900 unswept lines) — Judgment-heavy and mostly deferred to the implementer. Worth an explicit exception-class stub in the spec (file/phrase pins, like mailboxPHRASE_SURVIVORS) so BR-5 does not balloon ad hoc during P3.- POC hot loop — Measured ~0.6s full census on ~5.8k tracked files today; CI is fine. If the tree grows, prefilter (
indexOfbefore/seat/gion every line) is enough — no caching needed yet. - Stale
channel-kind-pathsexception — Census confirms it strips nothing onmain. Fine as POC documentation of ER-20; drop or gate at promotion so S10 does not carry dead rules (stale warnings are good, but fewer rules = less maintenance). WORKFORCE_GROUND— Trailing|workforce/imatches any path containing the substring, wider than the three documented families. Tighten at promotion unless you intentionally wantexamples/foo-workforce-barin ground.
Product fork (already surfaced in spec)
D1 (board seat → assignee) is the real sign-off call for boards-only consumers. The spec prices it well; I have nothing to add except: if an external stable API concern appears during P1, the spec’s escape hatch (glossary “two meanings”, defer rename) is the right simpler branch.
Skipped (not simplification / needs owner)
- Sweeping
goals/— correctly follow-up. - Whether future channels need a new guard when reintroduced — out of FIX-1796 scope; just don’t assume S11’s removal covers non-mailbox “channel” product language forever.
No changeset needed (spec + POC only).
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 04d1cfae2e
ℹ️ 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".
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision D1 answered by the product owner (2026-10-06): the task board keeps "seat". Only Workforce's seat goes. His reasoning: "seat" is a fair word for a place on a board. An assignee is the seat plus a specific task, so it names something else. Once the Workforce sweep lands, "seat" has one meaning in the codebase, the board's. The glossary defines it there and nowhere else. What this changes in the spec (fold in the next round):
Generated by Claude Code |
|
Architect · coherence re-check after the D1 answer The flipped D1 resolves both points from my check. With no rename there's no Layer 1 change, no epic D7, and FIX-1794 (#2828) is fine as written. I checked the epic on When you fold this in, please also:
No other notes. D2 and D3 stand as they are. |
The product owner answered D1: only Workforce's seat goes; a task board keeps "seat", and an assignee is a seat on one task. The board's types, the hand-off record's seat field and MANIFEST_DOMAINS stay, so the board PR drops out (two PRs) and no epic decision is needed. The glossary defines both seat and assignee. D1's figure is redrawn as d1-board-keeps-seat.svg, and what-changes.svg moves the board's seat below the fence. The census now scopes ground and the board's seat by surface (a file that imports Workforce is on its ground; the board's bare word strips only in its own files), scans member, thread and lower-camel room names, strips a stored key without the rest of its literal, and fails on a stale exception, so the unused channel-path exception and BR-13's dependency on it are gone. Stored field names keep their strings (BR-11). --control refuses ten planted lines and a folder. Cursor's and the architecture review's below-the-bar notes are recorded in PLAN. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold Review round 1 is folded in 65c39de. D1 is flipped as the product owner answered: a task board keeps "seat", and only Workforce's seat goes. The census now scopes by surface rather than by folder. Open: none. Folded
Census, on the same commit: before, 21,436 unswept lines in 661 files and 4 plants. After, 22,627 lines in 650 files. The census still fails, as it must before the sweep. Recorded verbatim in PLAN → Notes from review, not folded
Architecture review point 3, normalizing the old hand-off Update, 456604d: the discovery tool's Generated by Claude Code |
|
Architect · check of the round-1 fold against the D1 answer The fold matches the owner's answer for the board: its types, the hand-off record's
Please pick one and write it down as its own call, not under D1:
Then update D1's Instead of and Locks in rows, BR-3, PLAN S2 and PLAN's What stays row, so No other notes on this round. |
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision Agreed, and that bundling was mine. In my decision note I listed The call: rename it with the sweep. Generated by Claude Code |
The discovery tool's `seats` domain lists Workforce workers, so it is Workforce's seat, not the board's. D4 renames it to `workers` with no alias; a saved prompt, skill or eval that passes `seats` gets the unknown-domain listing, and the patch changesets name that cost. It is a Layer 1 public name, so it binds once the epic records it (amend-5). D1, BR-3 and PLAN no longer list the domain as part of the board. The `mailboxes` domain is FIX-1792's to remove and is not decided here. "Person" keeps its permanent guard, scoped to Workforce's ground, with an exception class pinned by file and phrase for a person who isn't the signed-in user. The census drops the domain exception, adds the person pin and two control plants; --control refuses twelve lines and a folder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold Re the architect's check (#2832 (comment)): this is folded in 456604d. We took the first option: rename it with the sweep.
Generated by Claude Code |
|
Architect · check of 456604d against the This matches what I asked. D4 is its own call with its own figure and the cost named in the changeset row. D1's Instead of and Locks in rows, BR-3, SPEC's What stays and PLAN S2 no longer put the domain with the board. One open dependency, and it's not a fork: D4 binds only once the epic's amend-5 records it, and no FIX-1786 amendment PR is open yet. PLAN's "don't build S2's rename before that amendment merges" is the right guard. Please make sure amend-5 carries D4 ( No other notes. |
jhoffner
left a comment
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: spec-review-r2
Spec review, round 2 (final) · 456604d · ABOVE_BAR (2 findings, both small)
Every fold is in. D1, D2 and D3 hold, and D4 matches #2833. Two problems come from the round-1 folds themselves. The first decides whether the guard can ever pass without breaking D1.
Above the bar
1. The board-seat exception's closed file list is narrower than the board, so the guard can't pass without renaming the board's seat. That contradicts D1.
poc/term-census/check.mjs:71 (BOARD_FILES) covers orchestration/{src,test}/task-board/, core/src/types/dispatch.ts and three docs pages. The board's own "seat" also lives outside that list, in files that don't import Workforce. On 456604d, about 130 unswept lines in about 25 files, for example:
packages/core/src/blocks/dispatcher.ts:304:envelope.seat, the hand-off field D1 locks;core/test/dispatcher.test.tsanddevtool/src/react/lib/dispatch-run-links.ts;orchestration/src/tasks/**andorchestration/src/skills/delegation-surface.ts("Tool seats", FIX-925);- the
integration-teststask-board scenarios; docs/architecture/dispatched-work.md;apps/docs/guides/agents-command-the-board.md("Staff each seat").
PLAN's guardrails (PLAN.md:145-146) say "never widen an exception … rename the line" and "the board's bare seat strips only in its own files". README:79 adds "rather than widening the board's list". Together they tell the implementer to rename the board's word in exactly the places D1, BR-3 and V1 keep it.
Minimal fix: define the board's surface the way Workforce's ground is defined. That means the board's modules (task board, tasks, skills delegation, core's dispatcher and dispatch types, devtool's dispatch-run views), their tests and pages, and any file off Workforce's ground that uses them. Add each one by module at build time. Say in PLAN that completing that list is not widening an exception. Strip the hand-off field (.seat, seat: on the envelope) the way TaskSeat is stripped. Add a --control plant: a board consumer outside task-board/ with a bare seat (stripped) and a hired seat (counted).
2. D4 renames a string value, but BR-9 sends goals/ through typecheck, and typecheck can't see this one.
goals/hire-plane/discover-survives-an-unaddressable-row/run.mts:131,217,243,291 passes domain: "seats" and matches domain.domain === "seats", typed string (:50). After D4 it gets the "unknown domain" listing, and legs b and c fail. BUSINESS-RULES.md:26 (BR-9: "its words stay · Typecheck") tells the implementer to leave it, and the census never scans goals/.
Minimal fix: one line in BR-9, or in D4's Locks in: a value an export reads (the seats domain) follows D4 in goals/ too. Name this goal under V6.
Folds verified at 456604d
| Fold | Where |
|---|---|
| D1 flipped (the board keeps "seat") | DECISIONS.md:142-157, SPEC.md:11,93-95,104-106, BR-3 BUSINESS-RULES.md:15, PLAN S1 :75, EVOLUTION.md:229, figures/d1-board-keeps-seat.svg |
| Glossary: seat (a place on a board) and assignee (a seat on one task) | DOCS.md:27-33, BR-18 BUSINESS-RULES.md:45 |
| Board-seat exception scoped by surface | check.mjs:63-71,101-102,187, SPEC.md:49, PLAN S10 :84, guardrail :146 (but see finding 1) |
Census gaps: member/thread, room…, quoted-literal strip, stale exception fails |
check.mjs:78-80,100,195,240; plants :251-253 |
D4: seats becomes workers, binding at amend-5; mailboxes left to FIX-1792 |
DECISIONS.md:192-209, SPEC.md:68-69,111-113, BR-16 :38, PLAN S2/S4/V6/pinned/at-implement :76,78,125,133,179-182, DOCS.md:98-100,112. Agrees with #2833's S9 |
| "Person" stays guarded on Workforce's ground, with an exception for a person who isn't the signed-in user | DECISIONS.md:222-226, BR-4/BR-5, check.mjs:82,104, plant :264 |
D4's other readers and writers are all in scope: contracts MANIFEST_DOMAINS, core's discovery tool, workforce manifest-sources.ts:191, the agent-worker-flow.ts:542 enum, SEAT_DISCOVER_KEY, seat-discovery/manifest-discovery tests, and discovery.md:27,97. No tracked WORKER.md has a discover: line. I found no surviving Workforce "seat" in the spec's own text.
Evidence
node scripts/validate-spec-folder.mjs: exit 0.check.mjs --control: CONTROL PASS, 12 planted lines and the folder refused.- Plain run: FAIL, 22,247 unswept lines in 556 files. That matches the README, and the guard still fails before the sweep.
BOARD FILE ON WORKFORCE GROUNDfires ontask-board.md.- A scratch copy with a never-matching exception prints
STALE EXCEPTIONSbut still prints CONTROL PASS (see note 1).
Implementer notes
--controlnever exercises the stale-exception or board-on-Workforce-ground failures; it passes with a stale exception present. S10's vitest should plant both.- In devtool,
INVENTORY_COLLECTIONS = ["seats", …](devtool/src/react/lib/inventory.ts:37) and the inventory section'sname="seats"are D2 stored collection names, not D4's domain. Reword the "Registered seats" label (BR-6) and keep the string. SEAT_DISCOVER_KEYis an export whose value"discover"doesn't change. Rename the constant with a changeset row; V5 catches it, though the upgrading page's two pinned rows don't name it.- P1 bundles S2 (gated on amend-5) with S4–S7. If amend-5 is late, S2 and S4's
discover:values can split off so the rest of P1 isn't held.
Generated by Claude Code
The board-seat exception's closed file list was narrower than the board, so the guard could not pass without renaming the board's seat against D1. The board's surface is now defined the way Workforce's ground is: by module (the task board, the task substrate, the skills delegation surface, core's dispatcher and dispatch types, devtool's dispatch-run views, their tests, scenarios and pages), plus code off Workforce's ground that uses them. Completing that list at build time is not widening an exception. The hand-off field read off its envelope strips like TaskSeat. All 125 of the board's lines the review found are now stripped, and no Workforce seat among them. D4's `seats` value follows into goals/ (BR-9), with the hire-plane discover goal named under V6. --control now also plants a board consumer outside task-board/, a board module on Workforce's ground and a stale exception. Round 2's implementer notes are recorded in PLAN. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold Round 2 (review) is folded in 75dcb8c. The board's surface is now defined by module, and all 125 of its cited lines are stripped. The hand-off field strips the same way Generated by Claude Code |


seatTools,seatSkillsandseatId, and asks discovery forseatsworkerTools,workerSkillsandworkerId, and asks forworkers. A schema that the author writes by hand with the old keys stops at boot, and the message names the missing keyinventory/seats/…andworkforce/roster/…Goal: a person who reads Workforce code, its exports or its published docs sees one name for each idea. The glossary defines each name one time. A retired term stays only where a listed exception gives the reason.
The census reads each line of each tracked file. Thus, it finds a term that nobody listed. It must fail under each dashed control. Check:
specs/issues/FIX-1796/poc/term-census/check.mjs, which becomes the CI guardscripts/check-retired-terms.mjs. Control:mainbefore the sweep must fail (oncad4e2780: 22,058 lines in 527 files), and--controlmust refuse each plant. Why this goal and not a smaller goal: SPEC.md.The left side shows the names of today. The right side shows the one name that each becomes. Below the line are the words that stay, each with a reason. The task board's seat is one of them.
How: each other child of the epic lists the old names that it leaves. The census finds all other names. Two PRs do the sweep: Workforce and its apps first, then the prose, the glossary and the guard.
Sign off
The goal, at that size: all files in scope, and a guard that keeps them correct. If wrong: we rename Workforce, but a reader still sees a worker called "seat" on the next page.
Only Workforce's seat goes; a task board keeps "seat" · D1 · decided by the product owner
<img src="''``https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/75dcb8c1351fd350fdbbf578791225fd1ab1f48d/specs/issues/FIX-1796/figures/d1-board-keeps-seat.svg"''`` width="940" alt="D1: only Workforce's seat goes, chosen, beside a board's seat becomes its assignee. Decides it: what a seat is on a board. Price: the guard needs a board-seat exception. Flips if readers still take a board's seat for a worker after the sweep" />The decision comes from what a seat is on a board. If the board's seat became "assignee", that word would name two things: the place, and the seat on one task. Nothing in the epic's Layer 1 changes, so the epic needs no decision, and FIX-1794 stands as written. If wrong: a reader still takes a board's seat for a worker, and the board's word changes at 1.0.
Saved names keep their strings; code and pages change · D2
The decision comes from saved records: a rename moves each record, or reads two names, for a word. If wrong: the devtool storage view continues to show old words, and a later rename must move data.
Renamed exports break, with a table and no aliases · D3
The decision comes from the epic rule ER-12: an alias is a retired word in an export. If wrong: the build of an app outside this repo breaks on upgrade until it uses the table.
The discovery domain
seatsbecomesworkers· D4The decision comes from what a model reads by name. The domain lists workers, so a pinned
seatskeeps a Workforce meaning that only a model sees. It is a Layer 1 name, so it binds once the epic records it (amend-5).mailboxesis FIX-1792's to remove. If wrong: a saved prompt, skill or eval that passesseatsgets the "unknown domain" listing for nothing.Open: none. The product owner answered D1 in review. Reasons and the options that lost: DECISIONS.md. The cases: BUSINESS-RULES.md.
Reviewers · look here
Not here: the words in
goals/, and the engine's flow instances and owner pins (FIX-1798).Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1796 · epic FIX-1786 · builds on FIX-1788, FIX-1789, FIX-1790, FIX-1791, FIX-1792, FIX-1793, FIX-1794 · merges after human approval and required checks (contract)
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing the shape of the proposed solution. It is knowingly incomplete, is not real code,
and is not what will ship. Review it for directional viability only. Do not report
that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
wouldn't build: all of that is true on purpose.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
PLAN.md → Notes from reviewfor the implementer to weigh against real code. It will not be argued with, and itwill not be folded into the design prose. Please don't re-raise it: one mention is enough.
The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
POC — the census, and how to run it
specs/issues/FIX-1796/poc/term-census/. It answers one question: how many retired terms are in scope, and where? It is not production code. The last implementation PR moves it toscripts/.On
cad4e2780: FAIL, as it must be before the sweep. 22,058 lines in 527 files. Each of the 5,802 tracked files has an area, and every exception strips something.--controlrefuses all eighteen plants: thirteen lines that must count, two board lines that must strip, a board module on Workforce's ground, a stale exception and an unscoped folder.🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code
Generated by Claude Code