Skip to content

spec(FIX-1796): Remove the retired Workforce terms from code and docs - #2832

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-1796
Oct 6, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-1796

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
learns Workforce from its docs Sees seat, hired roster, mailbox, member, thread, room, talk session, kind, flow instance and owner pin. Some of these names are for one idea Sees one name for each idea: worker, worker flow, coordinator, delegate, roster, workstream, project coordinator. The glossary defines each name one time
writes a custom worker flow Reads seatTools, seatSkills and seatId, and asks discovery for seats Reads workerTools, workerSkills and workerId, and asks for workers. A schema that the author writes by hand with the old keys stops at boot, and the message names the missing key
builds a task board Sees "seat" for a place on the board, and in the Workforce docs for a worker Sees "seat" only for a place on the board, and "assignee" for a seat on one task. The glossary defines both. No board name changes
upgrades an app n/a Gets a table of old and new names in each changeset and on the upgrading page. There are no aliases
keeps data from an earlier release Has records under inventory/seats/… and workforce/roster/… Reads them as before. No data moves

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.

flowchart LR
  A["the last PR's head · rebased on main"] --> C["the census · every tracked file · every line"]
  C -->|"zero unswept · every file has an area"| P["PASS · one name per idea"]
  A --> B["typecheck · tests · docs build"]
  B -->|"green · no broken anchor"| P
  K["control · main before the sweep"] -.-> C
  C -.->|"under the control"| F["must FAIL · each unswept line named"]
  X["control · planted lines and a folder"] -.-> C
Loading

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 guard scripts/check-retired-terms.mjs. Control: main before the sweep must fail (on cad4e2780: 22,058 lines in 527 files), and --control must refuse each plant. Why this goal and not a smaller goal: SPEC.md.

Six rows map old names to one new name each: seat, hired seat, flow instance and owner pin to worker; kind to worker flow; hired roster to roster; mailbox, its member and its thread to coordinator, delegate and the delegate's session; room and talk session to project coordinator; person, for the signed-in user, to user. Below a dashed line, what stays by design, a task board's seat first

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

D2: saved names keep their strings, chosen, beside rename saved names too. Decides it: records saved before. Price: raw storage views still show old words. Flips if app builders read those keys as product names

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

D3: rename outright with a table, chosen, beside deprecated aliases for a release. Decides it: the epic's ER-12 at the closure. Price: an app on the old names breaks on upgrade. Release type is a tie

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 seats becomes workers · D4

D4: seats becomes workers, chosen, beside pin seats as a model-facing name. Decides it: what a model reads by name. Price: saved prompts that pass seats get the unknown-domain listing. Flips if the epic declines the rename

The decision comes from what a model reads by name. The domain lists workers, so a pinned seats keeps a Workforce meaning that only a model sees. It is a Layer 1 name, so it binds once the epic records it (amend-5). mailboxes is FIX-1792's to remove. If wrong: a saved prompt, skill or eval that passes seats gets 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

  • Decisions → D4. Should a model-facing domain name follow the sweep, at the cost of saved prompts that name it?
  • Rules → BR-3 and BR-11. Can the board's seat exception hide a Workforce seat? Do we read all saved data after the sweep, field names included?
  • POC → the exceptions and the ground. Can one exception hide a live use of a different term? Does a Workforce file outside Workforce's folders still count?

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:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing 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 implementation polish. Experiments under the owning spec's 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 review for the implementer to weigh against real code. It will not be argued with, and it
will 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 to scripts/.

node specs/issues/FIX-1796/poc/term-census/check.mjs              # the census; exits 1 while a line is unswept
node specs/issues/FIX-1796/poc/term-census/check.mjs --list seat  # each unswept line of one term
node specs/issues/FIX-1796/poc/term-census/check.mjs --control    # must print CONTROL PASS

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

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
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1796

@vercel

vercel Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 6, 2026 11:05pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 11:05pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 11:05pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-06T22:26:29.731634Z 04d1cfa PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture review (direction only)

The direction holds. D1–D3 are sound: no aliases, saved strings untouched, and the board's seat is already the assignee in hand-off.ts. The findings below are about the guard's shape and the seams, not the vocabulary. Ordered by weight.

1. The census can pass while a live retired term remains (above the bar)

  • Ground-limited terms are scoped by path, not by meaning. WORKFORCE_GROUND is a path regex. kind, owner pin and flow instance are scanned only inside it. But S5/S6 rename Workforce consumers that sit outside it: apps/kitchen-sink/components/seat-pane.tsx, apps/kitchen-sink/fsdev.config.ts, apps/kitchen-sink/flows/workforce-admin/flow.ts (ownerPin, owner pin in test asserts), the packages/react panels and apps/devtool. A "kind" or "owner pin" left in a Workforce panel there is invisible to the guard. That is the "an exception hides a live use" failure the spec's Not done if names. Suggest defining ground by an explicit file list or by imports from @flow-state-dev/workforce, and recording the choice in BR-2.
  • stored-key-names strips more than a token. Its pattern ends in [^"']*\1, so it removes everything up to the closing quote. "inventory/seats/ … the seat is a worker"is stripped whole, which contradicts "an exception strips a token, never a line". The--control` plants don't cover this case. Bound it to the key's own character class, and add a plant that puts a second retired word inside the same quotes.

2. A permanent guard over ordinary English words is a standing tax (restraint)

person (~900 lines, "many meaning the user, some any human"), kind and room are everyday words. Making them CI-fatal forever means:

  • BR-5's keeps are "pinned by file and phrase", so any later edit to a pinned phrase breaks CI;
  • every contributor writing "a person" or "a room for…" in docs hits an exception ledger.

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 person as a one-time census plus a glossary rule. This keeps what the goal needs and drops the part that will rot. If you keep person permanent, say so as a decision, with the cost named. It's a product-owner call: a guard that blocks ordinary writing.

3. Normalize the legacy hand-off seat once, at ingress (refactor opportunity)

core/src/types/dispatch.ts has the envelope schema (seat: z.string().min(1)) and the dedupe key worker|board|seat. Do the BR-16/17 dual-read with one preprocess on that schema: seat becomes assignee, with assignee winning when both are present. Then nothing downstream ever sees seat, and the dedupe key is built only from assignee. That also makes the key's equivalence testable: an old queued record and a new one for the same row must still dedupe. As written, S1 (orchestration) and S2 (core) could each grow their own seat ?? assignee read. Pin "one read site" in PLAN S2.

4. D2 covers key strings but not field names inside saved records

BR-11 keeps collection patterns and ids. If saved hired-roster or room rows carry fields like seatId, and the renamed TS types now say workerId, the code's read path and its stored shape part ways. V3's "store written by main reads the same" would catch it, but the rule should say it: stored field names also keep their strings, behind a read mapper. FIX-1788's workerId pin makes this the likeliest place to miss.

5. Smaller notes (recorded for the implementer, no design round needed)

  • P2 bundles S4–S7 (workforce exports, panels, apps/labs, docs: ~290+ files). Splitting the library rename from the consumers lets the typecheck fail narrowly. Optional.
  • The discovery tool's MANIFEST_DOMAINS values (seats, mailboxes) are model-facing input. Saved prompts, skills or evals that pass them will get the "unknown domain" listing after the rename. Fine with D3, but the changeset row should name it.
  • The census counts a lot of code that FIX-1788/1791/1792/1793 rewrite. The plan already says re-run on main, so just don't size P2 off 21,436.

Not raised: the figures at pixel level, and the POC's line-level polish.


Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 orchestration (TaskSeat… and HandOffSeat). It also renames the hand-off record's seat field in core, and the seats and mailboxes names in MANIFEST_DOMAINS in contracts. Under ER-22 a Layer 1 change outside D3's list goes to the epic, and under ER-24 it binds only after an epic PR records it. That is how #2831 records FIX-1794's D1 as D6. The epic's SPEC also says under What stays as it is: "Task boards and sharedToLineage, consumed as they ship". D1 contradicts that line. ER-12 does not settle the question, because D1 itself treats "only Workforce's seat goes" as a real choice. So the epic has not decided it. Please do one of these:

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 defaultWorker seat to the board it changes. Under ER-25 each child writes in the new terms. If D1 holds, FIX-1794 should write assignee now, so its docs are not published one way and then reversed in P1 here. If D1 waits for the epic, list FIX-1794's seat-named additions in At implement time as names this sweep owns (the PLAN still says "FIX-1794's lists come with their specs"). Choose one and state it in both PRs.

Small item for the same epic follow-up: your Settled section confirms that no workforce/flows/channels/ path is tracked on main. The epic SPEC's What stays as it is still names "their kinds at workforce/flows/channels/<kind>.ts and CHANNEL.md's flow:" as kept, and ER-12/ER-20 keep "channel-kind paths". Those lines protect paths that do not exist. Please reword them so they do not tell a later reader that the paths are there.

The vocabulary mapping matches the epic concept and FIX-1793 (merged). I have no notes on D2 or D3.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 seat field and the MANIFEST_DOMAINS names is exactly what ER-22 sends to the epic. It also contradicts the epic's line "Task boards … consumed as they ship". So DECISIONS here should say that D1 binds only once the epic records it, and that it goes to the product owner at this spec's gate. If D1 is approved, an epic amendment (amend-5) records it as D7 and updates the What stays line and D3's count. I'm keeping it out of #2831: that PR is already at its gate for D6, and a second decision would hold it up. If D1 is rejected, D1 here becomes "only Workforce's seat goes" before merge.

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 defaultWorker seat. Then the "FIX-1794's lists come with their specs" line can go. That page changes at most once more, inside this epic, and only if D1 holds.

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

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

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-rename is 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)

  1. S10 production guard — Plan adds glossary row uniqueness on top of the POC. Before CI lands, mirror check-mailbox-rename.mjs: export pure scanFile / census (in-memory maps), vitest plants in packages/core/test/ (not workforce), CLI thin. Consider a small scripts/lib/guard-totality.mjs shared with the mailbox guard’s history/process/goals buckets so area regexes do not drift a third time.
  2. 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 mailbox PHRASE_SURVIVORS) so BR-5 does not balloon ad hoc during P3.
  3. POC hot loop — Measured ~0.6s full census on ~5.8k tracked files today; CI is fine. If the tree grows, prefilter (indexOf before /seat/gi on every line) is enough — no caching needed yet.
  4. Stale channel-kind-paths exception — Census confirms it strips nothing on main. 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).
  5. WORKFORCE_GROUND — Trailing |workforce/i matches any path containing the substring, wider than the three documented families. Tighten at promotion unless you intentionally want examples/foo-workforce-bar in 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).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1796/PLAN.md Resolved
Comment thread specs/issues/FIX-1796/PLAN.md Resolved
Comment thread specs/issues/FIX-1796/DECISIONS.md Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 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".

Comment thread specs/issues/FIX-1796/SPEC.md Resolved

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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

  • D1 flips to "only Workforce's seat goes". The hand-off record's seat field, TaskSeat…, HandOffSeat and MANIFEST_DOMAINS stay. The task-board PR (P1) drops out or shrinks to the Workforce-side callers only.
  • No Layer 1 change, so no epic D7. This replaces my earlier note: the architect's point 1 is resolved by not renaming. The epic's "Task boards … consumed as they ship" line stays true.
  • FIX-1794's board text is fine as written. Drop the At implement time list of its seat-named additions I asked for. They are the board's word now.
  • The census needs an exception class for the board's seat. Scope it to the task board's surface, so it can't hide a Workforce "seat" on the same line (the token-strip rule).
  • The channel-kind path wording in the epic is still a small epic follow-up. It's independent of this change.

Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 main against the owner's split (seat = the place on a board, assignee = that seat on one task). It already agrees: CONCEPT says "each task still has one assignee, picked from the delegates", the SPEC graph says FIX-1794 "delegates as assignees", and end-state.svg says "a task's named assignee". So the epic needs no edit for D1. Only the channel-kind path wording goes in the follow-up.

When you fold this in, please also:

  • Flip what readers see first. The PR body's "builds a task board" row, the what-changes.svg row "a task board's seat to assignee" and d1-board-assignee.svg all still show the rename.
  • Define both words in the glossary, not only seat. Seat is the board's place. Assignee is a seat on one task. If assignee isn't defined, FIX-1794's "delegates as assignees" reads like a third meaning.
  • Scope the board-seat exception by surface, not by path. It's the same risk as point 1 of the architecture review: kitchen-sink's seat-pane.tsx and the packages/react panels are Workforce seat, not board seat. Add a --control plant that puts a Workforce seat on a line that also has a board seat.

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

jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator Author

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

  • D1 flipped. The board's TaskSeat… and HandOffSeat types, the hand-off record's seat field and MANIFEST_DOMAINS keep their names. The board PR drops out, so the plan is two PRs: Workforce and its apps, then the prose, the glossary and the guard. No epic D7 is needed, and FIX-1794's board text stands. BR-16 and BR-17 (reading the old hand-off field) are gone, and BR-3 now says the board keeps its word.
  • Readers see the flip first. The people table row, what-changes.svg (the board's seat now sits below the fence) and the D1 figure, redrawn and renamed d1-board-keeps-seat.svg, all show it. The PR body matches.
  • Glossary. The task-board table defines Seat (a place on a board) and Assignee (a seat on one task). This is new rule BR-17.
  • Surface, not path (architect re-check, and architecture review point 1). Workforce's ground now also includes any file that imports Workforce or Shift Manager, such as kitchen-sink's seat pane and the React panels. The board's type names strip anywhere. Its bare "seat" strips only in its own files, a closed list, and a listed file on Workforce's ground fails the run. "Hired seat" counts everywhere.
  • Codex P1. member and thread are census terms on Workforce's ground. room also matches lower-camel identifiers like roomLineSchema.
  • Codex P2.
    • A stored key strips alone, never the rest of its quoted literal.
    • The channel-kind-paths exception is gone. BR-13 is now proved by git ls-files.
    • The guard fails on an exception that strips nothing, so the signal and the checker agree.
  • Stored field names keep their strings (architecture review point 4, into BR-11). A renamed type reads its stored field through one mapper.

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. --control refuses all 10 planted lines and the unscoped folder, including two terms in one quote, roomLineSchema, and a Workforce seat beside a board's. The run also names one board file on Workforce's ground: the task-board page's "A board a mailbox holds" section. It leaves with the mailbox (FIX-1792), or it moves to the Workforce pages.

Recorded verbatim in PLAN → Notes from review, not folded

  • Cursor's notes:
    • the WORKFORCE_GROUND substring
    • shared totality with the mailbox guard
    • a "person" exception class
    • identifier-targeted renames
    • the S10 guard's structure
    • the hot loop
    • the future channels guard
  • Architecture review:
    • point 2 (a permanent guard over "person")
    • point 5's notes

Architecture review point 3, normalizing the old hand-off seat at ingress, is moot now that the field isn't renamed.

Update, 456604d: the discovery tool's seats domain lists Workforce workers, so it is not the board's seat. It is now its own call, D4, and becomes workers. MANIFEST_DOMAINS is out of D1. "Person" keeps its permanent guard, scoped to Workforce's ground.


Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 seat field, the glossary pair and the surface-scoped exception all look right. One item goes further than the answer, so it needs a fix before the gate.

MANIFEST_DOMAINS is not board seat, so D1 doesn't cover it. Your own fold says the discovery tool's seats domain "lists Workforce workers today". mailboxes is the Workforce mailbox that FIX-1792 retires and has nothing to do with the board. The owner's answer was that only Workforce's seat goes, and that after the sweep "seat" has one meaning, the board's. A model-facing seats domain that returns workers is a Workforce seat that survives, and it's the one surface a model reads by name. The board-keeps-seat reasoning can't justify keeping it. That bundling started in the decision note (comment 6026602320), not in the owner's answer.

Please pick one and write it down as its own call, not under D1:

  • Rename it with the sweep (for example workers, and whatever FIX-1792 settles for the mailbox domain). This follows D3's no-aliases rule and names the cost the architecture review flagged: saved prompts, skills or evals that pass seats or mailboxes will get the "unknown domain" listing. That cost goes in the changeset row.
  • Or pin both strings as model-facing names with a separate decision (a D4) that names the cost: the word "seat" keeps a second, Workforce meaning that a model can see, which goes against the stated end state. This one goes to the product owner at the gate because it reverses part of his answer.

Then update D1's Instead of and Locks in rows, BR-3, PLAN S2 and PLAN's What stays row, so MANIFEST_DOMAINS no longer reads as part of the board. Also check with FIX-1792 so the mailboxes domain isn't decided in two places.

No other notes on this round.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision

Agreed, and that bundling was mine. In my decision note I listed MANIFEST_DOMAINS with the board, and the product owner's answer doesn't cover it.

The call: rename it with the sweep. seats becomes workers as its own decision, D4, with no alias, and its cost is named in the changeset row. mailboxes is FIX-1792's, because its spec removes the domain, and it is decided only there. This is a Layer 1 public name, so the epic records it in its next amendment. The fold now in progress makes these changes, including D1's Instead of and Locks in rows, BR-3, PLAN S2 and What stays.


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

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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.

  • D4 · the discovery domain seats becomes workers. It is its own call, separate from D1, and has its own figure. The changeset row names the cost: a saved prompt, skill or eval that passes seats gets the "unknown domain" listing. It is a Layer 1 public name, so it binds once the epic records it in amend-5.
  • MANIFEST_DOMAINS is out of D1. D1's Instead of and Locks in rows, BR-3, PLAN S2, PLAN's What stays row and both figures no longer list the domain as part of the board. New BR-16 covers the domain, and the census counts it.
  • mailboxes is not decided here. FIX-1792's PLAN S9 removes it (spec(FIX-1792): MAILBOX.md becomes WORKER.md on the coordinator flow, and the mailbox is removed #2833), and this spec cites that.

Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Architect · check of 456604d against the MANIFEST_DOMAINS ask

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. mailboxes is decided only in FIX-1792. I checked #2833 as well: its S9 leaves the pinned list as seats, skills, resources and says FIX-1796 renames seats, so the two specs agree and neither decides the other's domain.

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 (seats becomes workers as a Layer 1 public name, ER-22) before P1 starts.

No other notes.

@jhoffner jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.ts and devtool/src/react/lib/dispatch-run-links.ts;
  • orchestration/src/tasks/** and orchestration/src/skills/delegation-surface.ts ("Tool seats", FIX-925);
  • the integration-tests task-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 GROUND fires on task-board.md.
  • A scratch copy with a never-matching exception prints STALE EXCEPTIONS but still prints CONTROL PASS (see note 1).

Implementer notes

  1. --control never exercises the stale-exception or board-on-Workforce-ground failures; it passes with a stale exception present. S10's vitest should plant both.
  2. In devtool, INVENTORY_COLLECTIONS = ["seats", …] (devtool/src/react/lib/inventory.ts:37) and the inventory section's name="seats" are D2 stored collection names, not D4's domain. Reword the "Registered seats" label (BR-6) and keep the string.
  3. SEAT_DISCOVER_KEY is 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.
  4. 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

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 TaskSeat does. BR-9 and V6 now carry seats into goals/. The four implementer notes are recorded in PLAN, and the stale-exception and board-on-Workforce-ground plants are added to --control.


Generated by Claude Code

@jhoffner
jhoffner merged commit a959b64 into main Oct 6, 2026
17 checks passed
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