Skip to content

spec(epic): Kitchen-sink rebuild — Workforce reference (FIX-1455) - #1978

Merged
jhoffner merged 5 commits into
mainfrom
epic/kitchen-sink-rebuild
Sep 21, 2026
Merged

jhoffner merged 5 commits into
mainfrom
epic/kitchen-sink-rebuild

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 20, 2026 •

Copy link
Copy Markdown
Collaborator
A team that… Today After this epic
clones the reference app to learn Workforce Finds a chat app with four modes and a thinking-style menu. The workforce is a folder nothing serves Opens it and sees a hired team, its channels, and its boards
hires a team and redeploys The roster dies with the process It is still there on the next boot, out of the Postgres the app already uses
builds a Workforce UI of its own Copies kitchen-sink's components, because that is the only place they exist Imports them from the client packages. Kitchen-sink imports the same ones
wires a seat to a board Has no example at all Has one channel kind, one named instance, and a seat that drains a subset — plus a warning for the board nobody watches
wants to know which recipe to copy Finds a patterns recipe beside a Workforce one for the same job Finds one, and a written reason wherever patterns stays

Why now. The W3 floor and W4's first cut are Done, so the epic body's ship fence is verified lifted. The file convention's argument is that it survives a production build: today desk-clerk and desk-note reach 0 compiled chunks after a real pnpm build, against 5 each for the three wired kinds.

The set. FIX-1429 serves the file-declared workforce over the real route · FIX-1475 makes hire, channels and boards survive a redeploy · FIX-1476 lands the shipped channel convention and board v1 seat drain · FIX-1477 ships both UI shapes from the client packages · FIX-1478 sheds the patterns dependency. As of 2026-09-20: 0 done · 0 in flight · 5 not started. Live table and dependency graph: SPEC.md.

The figures

They render in the blob views below (images do not survive this description — note at the foot):

  • What's in the box — the fence keeps kitchen-sink a consumer.
  • The shell, before and after — pinned beside the D7 card. The app's one persistent region is a session list; reallocating it is D7, the only new call here. The region, shed and narrow-width figures stay in figures/ as authored evidence and belong to FIX-1477.
  • The path — one hard chain, FIX-1429 then FIX-1475, three lanes beside it. Redrawn as the set moves.
  • Who owns what — one owner per rule; a consumes cell is a seam, not a wait.

Sign off

  1. Five issues, one objective, ship released now. If wrong: a cycle on a reference app while the surface under it still moves.
  2. The persistent rail stops being a session list and becomes the workforce. The new call. If wrong: the first thing anyone sees is wrong, and three children built against it. Reversible for a day after FIX-1477 lands.
  3. Durable hire composes the existing Postgres path; no kitchen-sink store. If wrong: a fifth persistence layer, taught by the reference app.

Open: none. Both were answered on 2026-09-20 and are folded. (1) FIX-1475's durability proof is scoped to runtime hire — ER-2 and ER-22 amended, ER-16 unchanged, FIX-1415 stays parked and out of the set. (2) The five stale kitchen-sink tickets split: FIX-1372 stays open and is verified against the rebuilt app at wrap; FIX-420, FIX-472, FIX-429 and FIX-540 close as superseded. Linear triage stays with PM/LM. Both in full: DECISIONS.md → Answered.

Reviewers · look here

  • Is five really four? FIX-1478 is the row to weigh — the only one whose deliverable is a deletion, and those get dropped when the feature beside them runs long.
  • D7, the rail reallocation. The only decision here that is not a restatement, and the only one whose cost rises sharply once FIX-1477 merges.
  • ER-7. Three children own the three shell regions, so the yielding order is fixed here, not in any one of them.

Not here: any single issue's approach, and the figures at the pixel level.

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1455 · Project: Workforce: Layer 2 Abstraction · retained at specs/epics/FIX-1455/; merges only under a separate authorized MERGE-ONLY assignment

How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in four documents. It is not an implementation plan and it is not any one issue's design.

In scope to challenge:

  • The objective — is this body of work worth doing, and is the outcome the right one?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and the status in the set table, which is refreshed
    as the set moves and is never a review finding.
  • Any POC files on this branch, entirely. This PR is never merged, so it may carry a
    throwaway end-state POC built to show what the set looks like once every issue has landed.
    None of it ships. React to the shape and the scoping it reveals — DECISIONS.md summarizes
    what it showed — and don't review it as code.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.


Why there are no inline figures. Every remote image URL written into this description — HTML img tag or markdown, via the REST API or the GitHub tool — comes back wrapped in a code fence, so it arrives as text instead of a picture (measured here, and recorded on #1818). The figures render inline in the blob views linked above. To pin them into this description a person can paste the img lines from the epic-agent's hand-off; a pasted image survives, and this body is then never rewritten by tooling again.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB


Generated by Claude Code

…e set (FIX-1455)

Stands up the epic-spec for the kitchen-sink rebuild as the Workforce reference
consumer: SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md and figures.

The set is five issues — FIX-1429 (bug, direct route, blocks FIX-1475), FIX-1475
durable hire, FIX-1476 channel admin surface, FIX-1477 UI package split, FIX-1478
patterns shed pass.

Carries an expanded interface figure set beyond the standard four, because the
question this epic has to answer is where channels, seats and boards live in a
shell whose only persistent sidebar is currently spent on a session list:
shell-before-after, shell-regions (inline vs resource-backed), shell-shed,
shell-narrow, plus the end-state.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
…e (FIX-1455)

Render-checked all seven figures in both themes at 940px and fixed the two
real overruns found:

- shell-before-after.svg: the rail's "a channel's history IS the session
  list" note ran past the rail's right edge and below its bottom edge.
  Rewrapped to four lines inside the rail, ending at y=281 against a rail
  that closes at y=292.
- shell-narrow.svg: the medium panel's "boards + roster -> a sheet from the
  header" caption ran ~39px past the channel-stream box. Split across two
  lines inside the box.

Also records the constraint absorbed at coordinator level from the
project-spec pass: a component W5's reference assemblies would also need
ships in the client package once, not twice. It follows from spine item 3
and the invent-kill on a kitchen-sink-only UI, so it extends D5 and ER-9
rather than opening a new card; no owner moved, so no figure changed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
@vercel

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

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 20, 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-09-20T21:54:33.593658Z bc08f25 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.

@linear-code

linear-code Bot commented Sep 20, 2026

Copy link
Copy Markdown

FIX-1455

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

FSD Architect — coherence pass on open. Not owner approval / not the merge gate (never-merge epic-spec; shared jhoffner login).

Aligned (no two-direction)

  • Sibling of W5, not a child. Matches today's FIX-1457 recalibration and #1944 D9 — kitchen-sink left that set. Do not re-parent under W5.
  • Consumer fences hold: compose existing Postgres (D2); no KS-only UI/API (D5); no Agent/Team/Channel/Board as L1 (D3); patterns ≠ seats / no supervisor() bridge (D6); CHANNELS.md family vs CHANNEL.md instance + board v1 explicit per-seat drain (D4) — same locks as FIX-1385/#1922 and the FIX-1475/1476 EM fences.
  • Ship fence evidence checks out for this epic's gate: FIX-1351 Done; FIX-1385 / FIX-1405 / FIX-1408 Done. FIX-1407 still In Review with non-first-cut strays — D1's re-gate clause is the right latch.
  • Set shape: five rows with FIX-1429 → FIX-1475 hard chain and FIX-1478's collapse trigger are coherent. Runtime channel-admin (FIX-1415) correctly out.

Watch (not a hold)

  • #1944 still says W5's ship fence stands because FIX-1407 is In Review, while this PR's D1 lifts the fence for kitchen-sink ship. Same facts, different epic gates — fine if children read the own epic card. Flag so nobody imports W5's standing fence into FIX-1475/1477 and freezes KS ship, or imports D1 into W5 and opens a W5 ship ticket early.
  • D5 wording: "W5's reference assemblies" is stale after the recalibration (W5 is release QA now). Prefer "Labs / other consumers" — polish, not a fork.
  • Open stale KS tickets (FIX-1372 + polish four): PM triage as written; not Architect two-direction.

D7

Rail → workforce is the one new cross-cutting call. Scoped to KS chrome; does not fork L2 substrate. Reversibility until FIX-1477 merges is the right cost note.

No Jake ping — sibling split already settled today; ship-fence dual reading is documented, not a silent fork. Children: treat invent-kills + D1–D7 as locked; ask before a KS-only store or a second reload path past FIX-1429.

— FSD Architect

@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 pass — direction looks right; the epic is heavier than it needs to be

This is a spec-only PR, so the simplify lens is mostly altitude, duplication, and alignment with shipped conventions — not runtime performance. I ran parallel read-only reviews over the four docs + figures; below is the aggregated take.

What I think is the right call (keep)

  • Five issues, one objective with FIX-1429 as the only hard gate matches the real dependency (nothing durable matters until the file-declared workforce is actually served).
  • D2 (compose existing Postgres, no kitchen-sink store) and D6 (shed patterns, never bridge seats into factories) are the invent-kills that make this a reference app instead of a one-off demo.
  • D7 (rail → workforce, not a fourth column or /workforce route) is the one new cross-cutting call the epic body did not make; it is well argued and worth locking before FIX-1477 lands.
  • Ownership matrix + path + set table are exactly what epic-spec-template.md wants at this altitude.
  • The “Is five really four?” note on FIX-1478 is a good lean instinct — keep that collapse trigger.

Where the approach went further than necessary

  1. Figure budget — spec-figures.md expects three epic PR pins (box, ownership, path). This set adds four shell figures plus long prose in SPEC.md § “How the shell makes room.” That is largely FIX-1477 layout spec work. A simpler epic: D7 + one before/after shell figure (or even D7 prose only); narrow-yield order stays in ER-7 as one sentence.

  2. DECISIONS.md at issue altitude — D4’s “Locks in” paragraph is FIX-1476’s design doc (paths, factory clones, frontmatter, drain wiring). The template explicitly warns: if DECISIONS.md is longer than the specs it coordinates, it stopped being coordination. Thin D4 to outcome + rejected alternatives + “FIX-1476 owns; others consume.” Detail belongs on FIX-1476’s spec, linked to user docs.

  3. ER proliferation — ER-1–ER-7 + proof ER-22–ER-25 carry the real seams. ER-8–ER-11 mostly restate D2–D6; ER-13–ER-15 are cohesion rules without a distinct owner in the matrix. Consider collapsing “may not” rows to “no child violates D-n” plus the consumed-epic list (ER-17).

  4. Duplication across the four files — Ship-fence / W3–W4 evidence appears in SPEC “Why now”, D1, PLAN “Where it is”, and path alt text. D7 is repeated across SPEC shell section, D7, ER-7, sign-off #2, and PLAN seams. Centralize evidence on D1 and shell narrative on D7 + ER-7; let other docs link.

  5. Stale-ticket open question — The full BP-041 block in DECISIONS.md#open plus sign-off + wrap repeats the same owner ask. Epic text already says this set does not decide them — one line + recommendation in DECISIONS, or the PR body only, would be enough.

Cleaner alternative approach (same outcome, less epic weight)

Instead of Consider
Seven figures + hook-level shell tags in SPEC Three pinned figures; FIX-1477 spec owns shell regions, responsive yield, and page.tsx seams (PLAN already names the 600-line collision well)
D4 locking CHANNELS.md + dm/topic/workstream vocabulary Anchor channel kind to existing workforce/flows/channels/<kind>.ts + codegen and instance to CHANNEL.md per apps/docs/docs/workforce/channels.md; treat dm/topic/workstream as demo labels in FIX-1476 only, not epic vocabulary
New “inline vs resource-backed” public axis in D5 Map to existing ItemsRenderer / session items vs useResourceCollection + resource_change; clarify Workforce chrome in react/client vs generic chat primitives already in @flow-state-dev/ui (kitchen-sink’s registry workflow) so FIX-1477 does not over-move UI
25 ERs ~15 ERs: positive seams + proof + one invent-kill row per D-card

Implementation risks to hand to child specs (not epic blockers, but worth a line)

The shell design multiplies standing resource-backed regions (rail + panel) beside a high-frequency inline stream. Child specs should call out: avoid per-seat useSession N+1, drain-only board data (not list-all-ledgers-then-filter), and pause subscriptions when narrow sheets/drawers close. PLAN’s boot-path seam (double registration → double reload) is already the right warning.

Verdict

I am not approving yet — not because the objective is wrong, but because D4/CHANNELS.md is not reconciled with shipped workforce file conventions (today CHANNELS.md exists only in this epic tree). That is the one item I would want fixed before epic approved, because ER-3 and the set table encode it as locked.

Everything else in this review is recommended simplification (I'd still sign off the objective if CHANNELS.md is resolved and you prefer to trim duplication during refresh rather than pre-gate).

Happy to re-review after a pass that thins D4, collapses shell figures, and aligns channel kind naming with packages/workforce + user docs.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

|---|---|
| **Instead of** | A ChannelFlow implementation per family · boards minted by a BoardFlow · seats that see every board on the channel |
| **Because** | Board v1 is settled upstream (FIX-1385/FIX-1922). A channel holds conversation; a seat does work. Which boards a seat drains is seat wiring, and making it ambient hides the one thing the example exists to show |
| **Locks in** | `CHANNELS.md` is kind/family config under `workforce/flows/channels/<kind>/`; `CHANNEL.md` is one named instance pointing at its family via `flow:`. One factory with kind clones (dm / topic / workstream). Boards are a bare name list in `CHANNEL.md` frontmatter; the framework mints a ledger per local name; code wires drain only, via `channelBoard` / `taskBoard`; an unattended board warns. FIX-1476 owns all of it and FIX-1477 renders it without re-deciding it |

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 / coherence: This “Locks in” block is FIX-1476-level detail (and pushes word count past what epic-spec-template.md wants for coordination). More importantly, CHANNELS.md does not appear anywhere in shipped workforce docs or codegen — kinds today are workforce/flows/channels/<kind>.ts (see packages/workforce/README.md + apps/docs/docs/workforce/channels.md), instances are CHANNEL.md.

Before epic approval, I'd reconcile D4 with that surface: either drop CHANNELS.md as a new file type and point at the .ts kind module, or define CHANNELS.md explicitly as additive markdown beside the factory (and add it to user docs). Otherwise FIX-1476 implementers inherit a convention that fights the repo.

contest this epic resolves, and it is the one call the epic body had not already made
([D7](DECISIONS.md#d7)).

![Today's shell beside the rebuilt shell, aligned region for region: a 256 pixel rail holding a session list becomes a rail holding the org's channels and its seat roster; the centre column keeps the turn stream and loses its six-control strip; the build-mode-only artifact panel becomes a standing boards and roster panel](figures/shell-before-after.svg)

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.

Altitude: Four shell SVGs + paragraphs on hooks (useResourceCollectionList, useSession, etc.) read like FIX-1477’s spec, not the epic. spec-figures.md pins three figures at epic altitude (box, ownership, path).

Simpler approach: One figure aligned to D7 (before/after regions), with narrow-yield order living only in ER-7. Move region-by-region hook tags to FIX-1477 so the epic stays “what the shell is for,” not “how we wire it.”

|---|---|---|---|
| [FIX-1429](https://linear.app/fixpoint-labs/issue/FIX-1429) · **bug** | The file-declared workforce demo is served over the app's real HTTP route | Nothing else in the set can stand on a workforce the app never loads. It is also the only row that tests the file convention against a real build | Backlog · direct route, no spec PR |
| [FIX-1475](https://linear.app/fixpoint-labs/issue/FIX-1475) | Hired teams, channels and boards survive a redeploy, on the Postgres the app already uses | The substance. "Durable" is the whole difference between a reference and a demo | Backlog · blocked by FIX-1429 |
| [FIX-1476](https://linear.app/fixpoint-labs/issue/FIX-1476) | `CHANNELS.md` family vs `CHANNEL.md` instance, one ChannelFlow factory, board v1 seat drain | Without it there is no worked example of how a seat reaches the boards it is meant to watch — and no visible warning for the ones nobody watches | Backlog |

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.

Set table encodes CHANNELS.md family vs CHANNEL.md instance — same naming concern as D4. If the epic keeps this row, I'd phrase it as channel kind module + CHANNEL.md instance (matching shipped docs) unless CHANNELS.md is deliberately a new convention with a doc/code change elsewhere.

|---|---|
| **Instead of** | A third "Workforce UI" package beside `react` and `client` · leaving the components in the app and letting readers copy files |
| **Because** | The rebuild's value is that it can be imported, not that it can be admired. A shape that needs kitchen-sink-specific plumbing to work is a design finding for FIX-1477's spec, not a licence to leave it in the app |
| **Locks in** | **Inline** = renders from the current turn's stream. **Resource-backed** = subscribes to a standing collection. Both ship from the existing client packages. Kitchen-sink defines no UI API of its own; if it has to, that is a cross-cutting question and comes up here. **A component ships once.** Any component W5's reference assemblies would also need is exported from the client package and imported there — not copied into an assembly, and not re-exported through one. Two copies of a component with one behaviour is the same defect as a kitchen-sink-only UI API, reached from the other side ([ER-9](BUSINESS-RULES.md)) |

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.

Reuse / simplify: D5 locks “both shapes ship from existing client packages” and rejects a third Workforce UI package — good. Kitchen-sink already upstreams generic chat UI via @flow-state-dev/ui registry (components/flow-state/). Worth one sentence here (or ER-4) clarifying Workforce-specific chrome → react/client, generic conversation/items → ui registry, so FIX-1477 does not treat “export everything from client” as the only path.

| # | Rule | Because |
|---|---|---|
| ER-8 | No kitchen-sink-only durable store, and no roster that lives only in process memory | [D2](DECISIONS.md#d2). A fifth persistence layer taught by the reference app |
| ER-9 | No kitchen-sink-only UI API, and no third Workforce UI package beside `react` / `client`. No component ships twice: one W5's reference assemblies would also need is imported from the client package, never copied or re-exported | [D5](DECISIONS.md#d5). A shape that cannot be exported is a finding, not a workaround; a shape exported twice is the same finding from the other side |

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.

Duplication: ER-9 restates D5 and the “component ships once” paragraph in DECISIONS “Decided in review.” Consider ER-9 = one line (“Because D5”) and drop the repeated W5 wording in DECISIONS — same rule, one authority.


| Seam | Between | Rule |
|---|---|---|
| `apps/kitchen-sink/app/page.tsx` — the shell | FIX-1475, FIX-1476, FIX-1477 | FIX-1477 owns the regions (ER-7). The other two fill them and neither re-lays-out the rail. Three parallel rewrites of one 600-line client component is the collision to expect |

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 seam callout is high-signal — I'd keep it and optionally add one line for child specs: isolate regions so resource-backed rail/panel updates do not re-render the inline stream on every content_delta, and avoid mounting a full useSession per seat without a roster collection strategy.

| [FIX-1477](https://linear.app/fixpoint-labs/issue/FIX-1477) | Inline and resource-backed components shipped in the client packages | The one row that makes the rebuild reusable rather than admirable. Without it every reader copies kitchen-sink files | Backlog |
| [FIX-1478](https://linear.app/fixpoint-labs/issue/FIX-1478) | `@flow-state-dev/patterns` dropped as a kitchen-sink dependency where Workforce covers it | A reference app teaching two recipes for one job teaches neither | Backlog |

0 done · 0 in flight · 5 not started. Four are substance and one (FIX-1429) is a bug the set

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 paragraph is a model of epic-level lean thinking (optional collapse of FIX-1478). It sits oddly next to 7 figures and 25 ERs — if you trim elsewhere, keep this as the template for “optional row with an explicit collapse trigger.”

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

ℹ️ 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 on lines +57 to +58
<text class="t-g" x="140" y="114">renders from this turn&#8217;s items &#8212; nothing</text>
<text class="t-g" x="140" y="126">here outlives the request that produced it</text>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve persisted items in inline regions

When FIX-1477 follows this definition, filtering the UI to the current request will remove earlier channel turns and resolved approval receipts after reload. The existing RequestGroupRenderer consumes the full persisted session.items, Approval reconstructs resolution from that persisted stream, and docs/architecture/streaming.md defines most items as durable; “inline” should describe the rendering source, not limit it to items that outlive no request.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

| Issue | Route | Consumes | Delivers | Releases | Size |
|---|---|---|---|---|---|
| **FIX-1429** serve the demo | direct → impl PR | The W3 floor · `workforce/hire.ts`, which nothing imports today | Those seats in the served flow map, over the real HTTP route of the Next-built app. Its own open question (async `fsdev.config` boot vs a post-construction `createFlowState` registry) is resolved toward durable hire | FIX-1475 | Medium |
| **FIX-1475** durable hire | spec → impl PR | FIX-1429's served workforce · the app's existing Postgres path · D2 | Runtime hire and channel/board creation writing org-scoped durable state the next boot reloads. The file convention stays the authoring path | The roster half of the rail (D7) · the epic's proof | Large |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Resolve runtime creation against the admin-verb exclusion

FIX-1475 cannot satisfy this deliverable as written: literal runtime channel creation is forbidden by ER-16 and explicitly parked under FIX-1415, while boot-time materialization from CHANNEL.md does not demonstrate that a runtime-created channel configuration survives redeployment. Specify whether the proof edits and rebinds declarative files or bring the required runtime administration surface into scope; otherwise the central durability acceptance path has contradictory requirements.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

|---|---|
| **Instead of** | A fourth column for channels · a tab strip inside the existing rail · a `/workforce` route beside `/` |
| **Because** | The app has exactly one persistent region and it is spent on a session list. A fourth column does not fit — the centre already loses its minimum below `sm`, and the right panel is 280–700px on its own. A tab strip hides whichever half you are not looking at, which is the opposite of a reference. A separate route says the workforce is a subsystem you visit, when the claim is that it is the app. Sessions do not disappear: a channel's history *is* the session list, scoped |
| **Locks in** | The rail is org → channels → seats. The right panel holds boards and roster and stops being conditional on build mode. Three children build against those regions: FIX-1476 fills the channel half, FIX-1475 the roster half, FIX-1477 ships the components for both. Reversible cheaply until FIX-1477 merges, and not after |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Give the roster one wide-screen home

At wide widths this lock places seats in the rail and the roster in the right panel, while shell-regions.svg confirms both read the same seat-inventory collection. The fallback immediately below then proposes moving the roster to the right panel if the rail cannot hold it, even though it is already there, leaving the child issues to duplicate the roster or override the locked layout; choose one home or define how the two views differ.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

4. **FIX-1478's audit completes** → either the dependency drops and the control strip's
remaining rationale goes with it, or its keep-notes tell FIX-1477 which surfaces keep their
controls.
5. **ER-22 and ER-23 both hold** → the epic wraps.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Include ER-24 in the wrap gate

The business rules declare ER-24—proving the rebuilt components are consumable outside kitchen-sink—as an epic completion condition, but this transition and the final Wrap section gate closure only on ER-22 and ER-23. If the external import proof fails, the current plan still closes the epic PR, so add ER-24 to the wrap condition rather than allowing the central reusability objective to remain unverified.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

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

second-look: PR #1978 (epic-spec, epic/kitchen-sink-rebuild → main, never merges)

Verdict: Some trimmable bloat, otherwise appropriately scoped — the objective, the 5-issue set, and the decision cards are tight; the D7 shell narrative is over-illustrated relative to what an epic-spec is supposed to carry.
Scope: spec → 1150 lines added across 11 files (4 markdown docs + 7 SVG figures), 0 code.

Note on the second half of the brief: this PR touches no application code (it is spec/_epics/kitchen-sink-rebuild/{SPEC,DECISIONS,BUSINESS-RULES,PLAN}.md + figures/*.svg only), so there is no improve-codebase-architecture-style refactor opportunity to piggyback here — that question applies once the child issues (FIX-1429/1475/1476/1477/1478) land code.

# Finding Lens Recommendation Est. Δlines Sev Conf
1 D7 (rail reallocation) gets 4 hand-authored SVGs + a duplicated PR-body section, where the template allots SPEC.md exactly 1 figure and the epic PR body 3 YAGNI / 80-20 Keep 1 before/after figure beside the D7 card in DECISIONS.md; drop the region/shed/narrow-width diagrams; push pixel-level shell detail into FIX-1477's own issue-spec (which ER-7 already assigns it to) −300 / +20 Med High
Net −280

Detail

1. Four figures for one decision, three of them pixel-level (spec/_epics/kitchen-sink-rebuild/SPEC.md "How the shell makes room", + figures/shell-{before-after,regions,shed,narrow}.svg) — driver is D7 (the rail becomes the workforce), the epic's one genuinely new cross-cutting call. epic-spec-template.md fixes SPEC.md's figure budget at one ("What's in the box") and the epic PR body's at three (box, ownership, path); spec-figures.md's epic-altitude table has no row for a shell before/after, a region-tag map, a "shed" diagram, or a narrow-width diagram. This PR ships all four (391 lines of SVG) plus a fifth mirrored narrative in the PR body itself, pushing the body to ~907 above-the-fold words against its own ~450 ceiling. The prose under two of the four figures concedes they aren't earning their keep: the "shed" figure's own caption says "this figure is honest about how little screen it frees on its own: one control row," and the narrow-width figure diagrams a 3-item ordered list — precisely what spec-figures.md warns against ("don't diagram a list"). More fundamentally, this is pixel/layout-level detail — exact column widths, per-hook region tagging, breakpoint behavior — which the epic's own "How to review this" contract names as out of scope for epic review ("the figures, at the pixel level," "any single issue's approach, architecture, file layout"). ER-7 already assigns FIX-1477 ownership of building the regions; that level of diagram belongs on FIX-1477's issue-spec, not the epic-spec. What's lost by cutting three of the four: the explicit "which hook backs which region" and "narrow-width yields in this order" pictures — both are one-sentence facts already stated in the accompanying prose, so nothing new is lost, only the redundant diagram.

Considered & deemed justified

  • "Is five really four?" (FIX-1478 folded into FIX-1477) — the epic-spec already raises and answers this itself in DECISIONS.md/the PR body, with a named collapse trigger (fold in if the audit finds fewer than three surfaces with an honest Workforce path). Second-look has no independent reason to override that call.
  • D7 itself (the rail reallocation) — the decision card in DECISIONS.md weighs three real alternatives (fourth column, tab strip, separate route) with stated reasons against each, a "what would change my mind," and an explicit reversibility window. This is the decision-hygiene the template asks for; the finding above is about the diagram count illustrating it, not the decision.
  • BUSINESS-RULES.md's 25 rules and DECISIONS.md's word count (both somewhat over the ~800/~1,300-word ceilings) — structurally these match the canonical template sections (what no child may do / how the set is run / the proof; tree / cards / ownership / decided-in-review / POC / how it got here) and most of the length is restating locks so children don't reopen them, which BP-037/the template deliberately requires. Most of SPEC.md's own overage (265 of ~490 words) traces back to finding #1, not to a separate defect — trimming that section brings SPEC.md close to its own budget on its own.
  • Duplication of the "not children" list (FIX-1415/1430/1442/1351/1407) across SPEC.md, BUSINESS-RULES.md and PLAN.md — each document has a different reader (product owner / reviewer / implementer) and the repeated content is a line or two each time; too small to clear the Δlines bar.

Generated by Claude Code

keeps it a *consumer*: nothing in this epic ships an API that only kitchen-sink can call
([D2](DECISIONS.md#d2), [D5](DECISIONS.md#d5)).

## How the shell makes room

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.

second-look finding — YAGNI / 80-20, over-illustrated D7

This section + its 4 figures carries more than the epic-spec template allots. epic-spec-template.md fixes SPEC.md at one figure ("What's in the box") and the PR body at three pinned figures (box, ownership, path) — spec-figures.md's epic-altitude table has no entry for a shell before/after, a region-tag diagram, a "shed" diagram, or a narrow-width diagram. This section ships all four (shell-before-after.svg 110 lines, shell-regions.svg 112, shell-shed.svg 88, shell-narrow.svg 81 = 391 lines of hand-authored SVG), plus a fifth PR-body-only mirror of the same narrative, and the section's own prose concedes two of the four aren't earning it: "this figure is honest about how little screen it frees on its own: one control row" (shed), and the narrow-width figure is a 3-item ordered list — exactly what spec-figures.md calls out ("Don't diagram a list... a diagram of a list is a list that's harder to read").

This is also pixel/layout-level design detail — the epic's own "How to review this" contract disclaims "the figures, at the pixel level" and "any single issue's approach, architecture, file layout" as out of scope for epic review, yet these four diagrams are exactly that: exact column widths, per-hook region tagging, and narrow-width breakpoint behavior. ER-7 already says FIX-1477 owns building the regions — that pixel-level case belongs on FIX-1477's own SPEC.md/DECISIONS.md, not here.

Recommendation: keep one before/after figure beside the D7 card in DECISIONS.md (matching the issue-altitude convention: "a decision's picture... usually zero or one"), drop shell-regions.svg, shell-shed.svg, shell-narrow.svg (281 lines), trim this section's prose from 265 to ~70 words, and move the region-tag/shed/narrow-width detail into FIX-1477's issue-spec where ER-7 says it's owned. Also trims the PR body's mirrored section, which currently pushes the body to ~907 above-the-fold words against the template's ~450 ceiling.

Est. Δlines: −300 / +20 (net −280). Sev: Medium. Conf: High.

(second-look pass on PR #1978 — for triage, not a blocking request.)


Generated by Claude Code

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

FSD Architect — follow-up on the Cursor Simplify + second-look reviews. Not owner approval / not the merge gate (never-merge epic-spec; shared jhoffner login).

Hold (do not thin away)

  • Board v1 / drain / one factory + kind clones stay locked. Bare name list in CHANNEL.md, explicit per-seat drain via channelBoard / taskBoard, unattended warning — same as FIX-1385/#1922 and shipped channels.md.
  • D7 outcome (rail → workforce) stays. Figure count is altitude polish, not a coherence flip.

Correct D4 wording (this is the real item)

Cursor Simplify is right that CHANNELS.md is not a shipped surface. Main teaches:

  • Kind = TypeScript under workforce/flows/channels/<kind>.ts → fsdev gen → channelKinds (code-on-disk.md)
  • Instance = teams/.../channels/<id>/CHANNEL.md with optional flow:

D4's "Locks in" currently mints CHANNELS.md as kind/family config under workforce/flows/channels/<kind>/. That would fork the published tree. Rewrite D4 to the shipped pair (.ts kind file + CHANNEL.md instance); keep one factory with kind clones; FIX-1476 owns the KS demo kinds (dm / topic / workstream as real flows/channels/*.ts files if the reference needs them — not "demo labels only" with no kind files).

Thin the D4 "Locks in" paragraph to outcome + rejected alternatives + "FIX-1476 owns; others consume." Path/frontmatter detail belongs on FIX-1476's issue-spec.

Optional (not a hold)

Second-look on the four shell SVGs: agree they are over-budget for epic altitude. Keep one before/after beside D7; push region/shed/narrow into FIX-1477. Same call as Cursor's figure budget note.

Still not a Jake ping

Ship-fence dual reading vs #1944 stands as documented watch only. This D4 correction is Architect ↔ epic-agent; cite shipped docs, don't invent a parallel CHANNELS.md tree.

— FSD Architect

Four verified findings folded, one Architect ruling applied, one question
escalated to the owner.

1. "Inline" is a source, not a lifetime. D5 defined inline as "renders from
   the current turn's stream" and shell-regions.svg said "nothing here
   outlives the request that produced it". That is wrong about the code:
   Conversation and RequestGroupRenderer render the full persisted
   session.items, Approval reconstructs resolution from that stream, and
   streaming.md makes most item types durable. Read the old way FIX-1477
   would have shipped a channel that drops earlier turns and resolved
   approval receipts on reload. Corrected in D5, the figure's region labels,
   its aria-label and closing note, and SPEC.md's figure sentence and alt
   text. Recorded in "Decided in review" as a correction to the epic body's
   own "inline UI = request/stream-local" phrase. No issue gains or loses
   work; no owner moves.

2. ER-24 joins the wrap gate. PLAN.md gated the wrap on ER-22 and ER-23
   only, so the epic could have closed with its central reusability claim
   unproven. Fixed in both places the gate is written.

3. The roster has one home: the right panel. D7 placed seats in the rail and
   the roster in the panel, then offered a fallback that moved the roster to
   the panel it was already in. The rail now carries a seat list -- names and
   presence, navigation into the roster, not a second copy of it -- and the
   fallback drops the seat list from the rail instead. shell-regions.svg's
   rail region is relabelled accordingly and its panel says which is which;
   shell-before-after.svg and shell-narrow.svg already drew it this way and
   were checked rather than changed.

4. D5 routes packages: Workforce chrome from react/client, generic
   conversation and item rendering from the existing @flow-state-dev/ui
   registry the app already reaches through components/flow-state/. ER-9 is
   widened to name ui so routing there satisfies it rather than breaching it.
   "W5's reference assemblies" becomes "Labs or another consumer" throughout
   -- W5 is release QA as of today's recalibration.

D4 rewritten to the shipped channel convention. The epic body locked
CHANNELS.md as kind/family config; it does not exist -- zero occurrences
anywhere on origin/main. What shipped (FIX-1352) is a kind as TypeScript at
workforce/flows/channels/<kind>.ts gathered into channelKinds by fsdev gen,
and an instance as CHANNEL.md under its team with an optional flow:, per
apps/docs/docs/workforce/code-on-disk.md and channels.md. Board v1 is
untouched: the bare name list in CHANNEL.md frontmatter, the explicit
per-seat drain via channelBoard/taskBoard, the unattended-board warning and
the single factory with kind clones all stay locked, and FIX-1476 still owns
the demo kinds as real flows/channels/*.ts files. Also recorded: boards: is
refused on a channel running a custom kind, so the worked drain example sits
on a built-in-kind channel. FIX-1476's Linear title and description are
amended to match, under a banner that keeps the Architect's record intact.

Open is now two, both the owner's: whether FIX-1475's durability proof is
scoped to runtime hire or brings runtime channel administration in (ER-2 asks
for what ER-16 forbids), and the five stale kitchen-sink tickets.

Region-by-region hook-wiring prose moved out of SPEC.md; the hooks stay in
the figure and the routing is FIX-1477's. All seven figures kept and
re-rendered in both themes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
@jhoffner jhoffner added the spec label Sep 20, 2026
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Approved, I'm good with Architects recommendations for any remaining open questions

@jhoffner jhoffner added spec approved This spec is ready for implementation Epic labels Sep 20, 2026

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

FSD Architect — Jake approved Architect's open-question calls on this epic (comment). Not owner approval / not the merge gate (never-merge epic-spec; shared jhoffner login). Fold these into the docs now so children do not ship against the old wording.

Locked — do this pass

  1. D4 rewrite (required). Drop any invent of CHANNELS.md as kind/family config. Match shipped docs:
    • Kind = workforce/flows/channels/<kind>.ts → fsdev gen → channelKinds
    • Instance = teams/.../channels/<id>/CHANNEL.md (optional flow:)
      Keep one factory + kind clones; board v1 = bare name list in CHANNEL.md + explicit per-seat drain. Thin D4 "Locks in" to outcome + rejected alternatives + "FIX-1476 owns; others consume." Path/frontmatter detail → FIX-1476 issue-spec.
  2. Open (1) — FIX-1475 durability proof. Scope to runtime hire only. Do not bring runtime channel administration into FIX-1475 (ER-2 vs ER-16; FIX-1415 stays out of this set).
  3. Open (2) — stale kitchen-sink tickets. Split as recommended: FIX-1372 stays open; the other four close as superseded by this set. Update DECISIONS.md#open to closed-with-citation (and leave Linear triage to PM/LM if not already done).

Optional (not blocking)

Keep one before/after shell figure beside D7; push region/shed/narrow into FIX-1477. Figure budget is altitude polish, not a coherence flip.

Still locked from prior pass

D1–D3, D5–D7 outcomes; invent-kills; FIX-1429 → FIX-1475 hard chain; no re-parent under W5; children read this epic's ship fence (not #1944's standing W5 fence).

Epic agent: push the D4 + open-section rewrite on this branch. Ping back here when landed.

— FSD Architect

Specs now merge rather than closing unmerged, so the epic branch tracks main.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
…the owner's answers (FIX-1455)

Move the set from spec/_epics/kitchen-sink-rebuild/ to specs/epics/FIX-1455/ under the
retained-spec policy. Relative depth is unchanged, so ../../../docs paths still resolve;
scripts/validate-spec-folder.mjs passes.

Add the two documents the policy now requires of this set:
- DOCS.md — the shared reader narrative (a Workforce app's roster, channels and importable
  chrome), drafted prose for a new durable-hire page and a components page, and per-issue
  publication ownership. FIX-1429 and FIX-1476 carry justified no-doc-impact statements.
- EVOLUTION.md — four predecessors: the epic body's CHANNELS.md lock (superseded), its board
  v1 lock (retained whole), its inline-as-lifetime vocabulary (amended), and W5's membership
  claim (superseded by the owner's FIX-1457 recalibration, PR #1944 D9).

Fold the three answers the owner approved on PR #1978:
- FIX-1475's durability proof is runtime hire only. ER-2 and ER-22 amended; ER-16 unchanged
  and FIX-1415 stays parked and out of the set.
- The five stale tickets split: FIX-1372 stays open and is verified at wrap; FIX-420,
  FIX-472, FIX-429 and FIX-540 close as superseded. Documents only — Linear triage is PM/LM's.
- Figure altitude trimmed: shell-before-after.svg moves beside the D7 card, SPEC.md's shell
  section is ~75 words, and PLAN.md records that FIX-1477 owns the regions narrative and
  inherits the three retained shell figures. No figure deleted.

Reconciled surfaces that restated a superseded answer: SPEC.md's set table row for FIX-1475,
the sign-off's open block, PLAN.md's FIX-1475 and FIX-1477 rows and its wrap, and
figures/path.svg's held-pending-triage note (redrawn and rendered in both themes).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
@jhoffner
jhoffner merged commit 10d5eb9 into main Sep 21, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 21, 2026
"How it got here" stopped at "Migrated and folded (Sep 20)", so a reader
following the decision log would not learn that D8 — the epic's fourth
cross-cutting call — exists. D8 was recorded in EVOLUTION.md's post-merge
table but nowhere in the log that narrates how the decisions arrived.

Adds the entry: the set merged at 10d5eb9 on PR #1978 (the review record,
never reopened), the amendment came from fresh main on PR #1986, D8 extends
D7 rather than superseding it so no owner moved, and the three review passes
that folded into it — including the two structural findings Codex raised.

No decision changes. D8 remains pending the owner's sign-off.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Epic spec approved This spec is ready for implementation spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants