diff --git a/spec/_epics/work-routing-package-cohesion/BUSINESS-RULES.md b/spec/_epics/work-routing-package-cohesion/BUSINESS-RULES.md new file mode 100644 index 0000000000..1c32398ddc --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/BUSINESS-RULES.md @@ -0,0 +1,123 @@ +# FIX-1407 · Rules every issue in the set obeys + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) + + + +What every child spec and implementation must satisfy, and what a cross-spec review checks. Numbers +are stable ids, not an order. ER-1 to ER-5 and ER-19 are the rows of the ownership matrix in +[DECISIONS.md](DECISIONS.md#who-owns-what). + +## What a team gets, and what it doesn't + +| # | Rule | Owner | Checked at | +|---|---|---|---| +| ER-1 | Work for a team lives as a row on a **channel or org board** — `0..N` TaskCollections on a channel — and a seat claims it or is assigned it. Channel actions and `taskTools` are **two doors on one mutation surface** | FIX-1385 | FIX-1385's spec · the proof | +| ER-2 | **A seat's package format is whatever FIX-1394's ratify records**, and no child may pre-name what is still open. **Recorded 2026-09-19 — the collapse is the answer:** one format, **authored in Markdown**, scoped to **instructions and tools**, two attachment modes — seat **always-on**, library **opt-in**. *Don't collapse* is no longer a live result. **The format may not be disk-only:** the owner's direction is that packages will eventually be LLM-authored and stored as a **resource**, never saved to disk — binding on the design, though v1 ships the file. **Documents settled 2026-09-19 — all org-scoped for now:** a seat's document is a resource under that seat on the org, and v1 carries no per-seat document slot. Per-resource configurability is deferred to **resource templates** ("used to define the resource, but isn't the resource itself"), which do not exist yet — so a child that builds one now is building against nothing. **Nothing in ER-2 is open any more**, and the ratify is unblocked | FIX-1394, at the ratify | FIX-1394's POC matrix · the proof, which may not invent a shape outside the recorded one · every ship ticket's review, on the not-disk-only and org-scoped halves | +| ER-3 | Inventory is **two layers**: a **declared roster** composed at read time from the existing readers, and the **live org resource** ChannelFlow updates. The live layer answers membership, author check, fan-out and DM find-or-create **at inventory level** — who exists and is open. It **does not own or mirror a channel's session-local `members`, nor its post-refusal fence**; that stays ChannelFlow-on-channel. The declared layer answers what the tree says exists, and never substitutes for the live one | FIX-1405 | FIX-1405's two prove-pressure callers — the **devforce and pentest labs**, both off their private copies · FIX-817's and FIX-1415's spec review, from outside the set. **Not FIX-1385**, which reads through the roster only if it has landed | +| ER-4 | Dispatch always passes `parentSessionId`; the child binds its parent **for life at mint**. Parent history reaches a child only by **opt-in tools**; the default payload is the brief — `goal` / `constraints` / `acceptance` / `links`. **Linked is not nested** | FIX-1408 (D4) — **shipped as a decision**, so the first child over the wire is where it first gets tested | Every child's spec review. **First read on the wire, 2026-09-19:** the parent a child binds is the **draining seat's** session, not the filer's ([the corrected mechanisms](DECISIONS.md#refuted-mechanisms)) | +| ER-5 | A board `assignee` is a **board-worker key**, not a Workforce seat; the two map by composition. `assignee` stays optional, and a registry board's "must be assigned" is discipline, not schema | FIX-1385 | FIX-1385's spec · FIX-1430's wiring | + +## What no child may do + +| # | Rule | Because | +|---|---|---| +| ER-6 | No **Agent, Channel, Team, MessageBoard, TeamFlow, ChannelAdmin or SessionBoard as an L1 package type**; no revived `materializeAgent` or `AgentRegistry` | D3. Agent is an opinionated default *kind*; the rest are L2 opinion or nothing | +| ER-7 | No `team.*` (or other) wildcards before the inventory lands, and none blocking the channels convention | D5. Wildcards call the live layer later | +| ER-8 | No shipping the package collapse from FIX-1394's exploration alone, without a ratify. **Discharged 2026-09-19:** the ratify is recorded ([both forks](DECISIONS.md#authorship-answer)) and the ship ticket is cut — **FIX-1459**, which is [related, not a child](SPEC.md#related-not-children). Nothing is held behind this row any more; ER-14 still fences FIX-1459 when it is picked up, on its own terms | That ticket's posture: matrix → ratify → then ship tickets | +| ER-9 | No dumping a parent's full transcript, or its private seat history, into a child by default | D4. Channel transcript passes only when both are on that channel | +| ER-10 | Boards are not the mint door for sessions, DMs, posts or sub-agents. No assignable-channel routing, no Project-as-required | D1, D3. Conversation stays off the board | +| ER-11 | No expanding the L1 `TaskStatus` enum. Queue columns — idle, ready-for-review, waiting-on-you — are **L2 views** over status plus claim, assignee, park reason and seat idle | A second hold status was already refused | +| ER-12 | No second `WorkerRegistry`, mega-loader, mega-bus or parallel index of truth; no Graft rebuild for membership or DM lookup. **Compose is not a registry.** No relocating ChannelFlow's post fence onto the org resource, and no second authoritative copy of membership | D5. Two authoritative copies of membership is the incoherence, not the fix | +| ER-13 | No closing an item on the Architect's **Still open** list without the owner: exact package schema · reuse-vs-create · nested cascade timing · how many POCs before a ship cut. Exploration may lean; leaning is not closing | Inventory helper-vs-resource left this list in round 1 — closed as **both layers** ([D5](DECISIONS.md#d5)), by the owner himself | +| ER-14 | **No W4 *ship* PR merges until every W3 ([FIX-1351](https://linear.app/fixpoint-labs/issue/FIX-1351)) child that carries an implementation is merged to main.** Children completed by decision, duplicated or cancelled do not hold the fence | D2. The risk is W4 shipping onto unlanded W3 *code*, so the condition is merge, not closure | + +**Where the fence stands · 2026-09-19.** Both W3 inputs are merged — FIX-1377 +([#1911](https://github.com/fixpoint-labs/flow-state-dev/pull/1911)), FIX-1416 +([#1909](https://github.com/fixpoint-labs/flow-state-dev/pull/1909)) — on main at `d8e4c99`. Of +FIX-1351's 22 children, exactly two are non-terminal: **FIX-1435** (`Todo`) and **FIX-1449** +(`Backlog`), neither with a PR, branch or commit. On the question the fence turns on, **FIX-1435 +carries an implementation** — it collapses two copies of the slot-descent walk in the resources +loaders, framework code W4 children read. FIX-1449 is Atlas HTML staleness and carries none. + +**So the fence has not lifted, and four W4 ship PRs have merged under it** — FIX-1385's +[#1922](https://github.com/fixpoint-labs/flow-state-dev/pull/1922), FIX-1405's +[#1920](https://github.com/fixpoint-labs/flow-state-dev/pull/1920), +[#1923](https://github.com/fixpoint-labs/flow-state-dev/pull/1923) and +[#1928](https://github.com/fixpoint-labs/flow-state-dev/pull/1928), all shipping +`packages/workforce` with changesets. **The owner merged the last of them himself**, on 2026-09-19. +That settles #1928; it is not a change to this rule, and he has said nothing about one. + +**What is still fenced.** **FIX-1459**, the ratified format's ship ticket — outside the set, but it +edits `packages/workforce`, so the fence reaches it when it is picked up; **FIX-1381's eventual implementation**, which edits `packages/workforce` and so will be a +ship PR when it exists; and **the +[wrap term](PLAN.md#wrap)**, which cannot complete while a W4 ship PR is parked. + +**[FIX-1451](SPEC.md#the-seventh-child)'s fix resolved out of the conditional, and it is the first +real test of [the operating default](DECISIONS.md#fence-default).** The changeset call was made: +[#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) carries one +(`@flow-state-dev/orchestration`, patch), and **it stays** — the fix changes prompt text a +consumer's generator receives and adds a public export, so dropping it to escape the fence would be +gaming the rule. **On ER-14 as written it is fenced. On the default — per-PR file overlap — it is +clear:** FIX-1435's scope is the workforce **resources loader** (`walkResourceSlots`) plus a +TypeScript-extension dedupe in Door B's two codegen files, and its Out excludes widening the walk; +#1936 touches `packages/orchestration/src/skills/*`, a `packages/core` doc comment, `apps/docs`, +two tests and the changeset, with `packages/workforce` appearing **only** as a test file. **No +overlap, not one file.** This is the first time the default has decided a PR the owner did not merge +himself — the rule and the default disagree here, which is what makes it a test of the default +rather than a restatement. **It narrows nothing:** [the re-gate](DECISIONS.md#er-14-re-gate) is +still pending and unanswered, and if the owner countermands the default this fix goes back behind +the fence with everything else. **No merge is authorised by it** — the epic has no objection to +#1936 merging when it is otherwise ready; the merge is the owner's. + +**How the epic behaves meanwhile.** ER-14 derives from [D2](DECISIONS.md#d2), which the owner +ratified, so the epic cannot narrow the rule — and it has not. What it has adopted is an +[operating default](DECISIONS.md#fence-default): treat the fence as narrowed to per-PR file +overlap, read from the owner's action rather than his words, and **countermandable by him at any +time**. Whether the rule itself narrows is still **[a pending re-gate](DECISIONS.md#er-14-re-gate)** +with the owner, where the recommendation is the epic's and unanswered. + +## How the set is run + +| # | Rule | Because | +|---|---|---| +| ER-15 | A cross-cutting question is commented **up** on the epic PR, never decided locally. FIX-1408's unclosed walls are **epic-owned**, and their current standing is in [Open](DECISIONS.md#open) | A local answer is a second authority. A wall closes on evidence a child produced and folded up here — never on a child's own say-so | +| ER-16 | A child's Linear state is mirrored the moment it changes. **Holding as of 2026-09-19**, the egress outage over and the queued backlog written | The epic wake derives blocked-by from Linear, so stale state silently mis-orders the set. The wrap term is **not** re-coupled to Linear by this — it stays [derived from GitHub](PLAN.md#terminal), because what makes code shipped is a merge. What Linear *does* decide is which children exist, and it decided it twice on 2026-09-19: the set is **seven** — FIX-1381 pulled in by the owner ([D6](DECISIONS.md#d6-extended)), and [FIX-1451](SPEC.md#the-seventh-child) confirmed as having been parented all along ([the correction](DECISIONS.md#d6-seventh)). **No unconfirmed remainder.** The second of those is the rule earning its place: the tracker was right and this spec was wrong | +| ER-17 | Every child routes to *spec* by default; only a `Bug` label re-routes | Fail-closed. The original five carry `Design` + `Feature`, and **FIX-1381 is routing to spec** like any other child — its spec is in review on #1935. **[FIX-1451](SPEC.md#the-seventh-child) is the first child to take the other branch:** labelled `Bug`, so it skips the spec and enters at implementation with its PR as the review surface. There is no spec gate to wait for on it, and its absence is not a gap | +| ER-18 | A child depending on FIX-1377 or FIX-1416 writes against the **landed code** at `d8e4c99` and names it. Where a W3 spec and that code disagree, **the code wins** | **FIX-1416 shipped stricter than its spec**, which said a seat's own `blocks/` folder is callable without being listed anywhere. `resolveDeclaredTools` (`packages/workforce/src/hire.ts`) promotes only names declared in `tools:`, so a child carrying the spec's sentence forward builds against behaviour that does not exist | +| ER-19 | The project's **PR-5** — a new surface uses the settled Layer 2 name, never the superseded one — is met here as **a check over this set's own diff**, owned by **FIX-1385**. It is **not** a repo-wide rename | The repo-wide pass waits on the project's vocabulary lock (**PD-4** — running it early pays the rename twice), so it stays the project's and has **no owner inside W4**: named out here rather than dropped, so nobody wraps this epic believing it ran | +| ER-23 | **A shared contract's spec is approved before the next child specs against it.** FIX-1405's reader contract — **`readDeclaredRoster(root)`** on `@flow-state-dev/workforce/loader`, collecting rather than throwing, joining the layers on **`id` alone** — closes before FIX-817 starts; the `tools:` fence settles across FIX-1416 → FIX-1394 → FIX-1415 in that order | Two issues designing one discovery API at once is how you ship two of them. It outlives FIX-817 leaving the set: the dependency is on the contract, not the parent | + +## The proof + +| # | The epic's first cut is done when | Proved by | +|---|---|---| +| ER-20 | Work filed on a **channel or org board** wakes a seat that runs it, and a coordinator seat assigns work to **team** seats — on the real path, seats and channels declared in files. **PASS, 2026-09-19** ([the run](SPEC.md#er-20-passed)) | **FIX-1430 owns it**, adopted as the proof at the objective gate ([D6](DECISIONS.md#d6)). **FIX-1385 provides the surface it stands on and does not own it** — one row filed and claimed on a board is not ER-20; ER-20 is a coordinator assigning a queue across several seats. **Proved by `goals/manager-queue-lab/it-routes-a-queue-to-the-seats-their-files-name`** at `GOAL_FILER=model` on `vercel/openai/gpt-5.4-mini`, commit `e6ccb22` of `main` — **three consecutive PASS runs** | +| ER-21 | The queue a coordinator sees is a **view** over existing task state and seat idle — no new status, no new L1 type | FIX-1430's goal check · ER-11 | +| ER-22 | The docs teach routing as something a team gets by attaching a board to a channel, **not something it builds** — and teach `assignee` and *seat* as two different things | The epic's docs pass · ER-5 | + +**ER-20 is the rule to read twice.** It is the only rule that makes the epic's claim falsifiable. +Wrapping on ER-1, ER-2 and ER-3 shipping, without ER-20 run on the real path, would be claiming +routing works rather than having seen it. **On 2026-09-19 it ran, and it passed** — three +consecutive times, on the model path, and the verdict log's row moved from `NOT RUN` to +[PASS](SPEC.md#er-20-passed). A coordinator seat whose own file declares `tools: []` chose the desks +and filed four rows through the eight task tools its kind composes; every row ran on the seat whose +**own file** answers for that desk. + +**And this is the first check in the epic whose negative control was demonstrated on the same path +as the pass** — which is the fact that makes the row mean anything. This set's recurring defect has +been the check that could only pass: BR-6 asserted a type and a field rather than arrival, FIX-1394's +compiler never opened the file it claimed to compare, and its grant-gate probe watched a worker the +package was never given to. ER-20 is the rule written to stop that happening to the epic's own claim, +so a `PASS` whose red state was only ever shown on a scripted filer would have been the same defect +wearing the rule's clothes. It was not: **`repointed-map` produced exactly three leg-(c) identity +failures with every row still running and completing — only the association moved — and +`duplicate-filing` produced exactly the two leg-(b) arms and nothing else.** Both on the model path, +which is stronger than the scripted control logged on +[#1929](https://github.com/fixpoint-labs/flow-state-dev/pull/1929): the authoring environment could +not reach the model path and this one could. The [wrap](PLAN.md#wrap) is still enforced against this +rule as written — it is now met, and **the wrap's remaining terms are the open children, not this +row**. diff --git a/spec/_epics/work-routing-package-cohesion/DECISIONS.md b/spec/_epics/work-routing-package-cohesion/DECISIONS.md new file mode 100644 index 0000000000..517cbb37dc --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/DECISIONS.md @@ -0,0 +1,274 @@ +# FIX-1407 · Decisions + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + + + +The calls above any single issue: what was chosen, what lost, what each locks in. D1 to D5 are +**Architect locks carried into this document**; [D6](#d6) is the one call taken here, the owner's +at the objective gate. + +## The tree + +```mermaid +flowchart TD + E["FIX-1407"] -->|"kills the full cascade as the gate"| D1["D1 · the exit gate is one hop"] + E -->|"kills W4 as a W3 floor child"| D2["D2 · soft-after for ship only"] + E -->|"kills one noun for two registries"| D3["D3 · workers do, channels hold"] + E -->|"kills the ambient transcript dump"| D4["D4 · the wire and the payload"] + E -->|"kills a second index, and the fork between the layers"| D5["D5 · inventory is two layers"] + E -->|"kills an epic that outlives its own gate"| D6["D6 · the set is seven, grown from five"] +``` + +Each edge names what the decision killed. The alternative that lost is in the card. + + +## D1 · The W4 first cut is one hop: channel/org board → seat runs, and assign team seats + +| | | +|---|---| +| **Instead of** | Making the full nested cascade — channel/org board → personal board → request board → seat — the exit gate | +| **Because** | The routing claim needs one hop to be true or false. A cascade proves the same thing three times and cannot be finished on a schedule, which is how an epic with a behavioural gate never closes | +| **Locks in** | Nested personal / request decomposition is **phase-2 inside W4**, promoted by a POC that proves need. What sits off the gate is FIX-1430's nested half. Conversation, DM and transcript stay off the board | + + +## D2 · W4 *ship* tickets are soft-after W3; W4 is not a child of W3 + +| | | +|---|---| +| **Instead of** | Nesting W4 under W3 · or letting a W4 ship PR merge onto a floor still being edited | +| **Because** | Every W4 child reads the file surface W3 is still closing. Nesting makes one epic that cannot wrap; ignoring the order lands a package format against a `tools:` fence and a `TEAM.md` layer that are still specs | +| **Locks in** | Filing, specs and **parallel POCs run now**. The fence lifts when **every W3 child that carries an implementation is merged to main**; children completed by decision, duplicated or cancelled do not hold it ([ER-14](BUSINESS-RULES.md)). Soft-after in Linear, never parent | + +Whether that condition is the right *unit* — the package, or the files a PR actually touches — is +now [a pending re-gate](#er-14-re-gate) with the owner. The card stands until he moves it. + + +## D3 · Workers and seats *do*; channels *hold*. A board assignee key is not a Workforce seat + +| | | +|---|---| +| **Instead of** | One noun for both — merging the board's assignee registry with the Workforce roster · or an assignable channel that claims work as an executor | +| **Because** | Different lifetimes, different identity rules. A board assignee is a key on a ledger; a seat is a roster slot that mints a flow instance. Collapsing them means every board row implies a hired seat, and every seat implies a board | +| **Locks in** | The two map **by composition**, per child. No assignable-channel routing, no channel-as-claim-worker, no second `WorkerRegistry`. `defaultWorker` and `assignTask` are composition, not new primitives. **Agent is an opinionated default kind**, not a Layer-1 substrate type, and there are no thin/fat seat labels | + + +## D4 · Dispatch is the wire; handoff content is the payload policy — not competing forks + +| | | +|---|---| +| **Instead of** | Choosing between "pass the parent session" and "pass a brief" · or a silent full parent transcript as the default | +| **Because** | One is mechanism, one is policy, and reading them as a fork produces both an ambient dump *and* a second runtime. A sub-agent is same-session background work with a different prompt; a worker assign is a roster seat in a **linked** session. Both need the link; only the second needs a payload rule | +| **Locks in** | Dispatch always passes `parentSessionId`; the child binds its parent **for life at mint**. Parent history reaches a child by **opt-in tools**, never an ambient dump. The default payload is the brief — `goal` / `constraints` / `acceptance` / `links` — plus channel transcript **only if both are on that channel**. **Shipped on FIX-1408**, as a decision rather than code | + +**Linked is not nested.** A linked session is a sibling that names its parent; +[FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440) removed the nested-session substrate and +no child reads `parentSessionId` as a session tree. **Which** session a child names was first read +on the wire by FIX-1430 and is not the one its spec assumed — [below](#refuted-mechanisms). + + +## D5 · Runtime inventory is **two layers**, and choosing between them is not a fork + +| | | +|---|---| +| **Instead of** | A second `WorkerRegistry`, a mega-loader that re-walks the tree differently, or a Graft rebuild for membership and DM lookup — **and** treating read-time compose versus an org-scoped resource as a fork to pick one of | +| **Because** | They answer different questions. The declared tree is what the files say; the live set is what is actually open. A compose helper goes stale the moment a channel mints; a live resource cannot tell you about a seat nobody has opened. Picking one produces the other by accident, badly | +| **Locks in** | **Layer 1 — declared roster, composed at read time.** The duplicated private `LabRoster` in `goals/devforce-lab/lab/host.mts` and `goals/pentest-lab/lab/host.mts` becomes one package-level export over the three existing readers (`readWorkforce`, `readResourcesDirectory`, `readChannelsDirectory`) — derived per read, no state, registers nothing. Both lab copies deleted. **Layer 2 — runtime inventory** (Jake's lock, 2026-09-16): ChannelFlow updates an org-scoped resource as seats and channels open. It stays FIX-1405's **primary** runtime shape for DM find-or-create, membership and fan-out **as inventory questions — who exists and is open**, and layer 1 does not replace it. It does **not** take over a channel's session-local `members` or its post-refusal fence ([ER-3](BUSINESS-RULES.md), [ER-12](BUSINESS-RULES.md)). `team.*` wildcards call layer 2 later, not at first ship | + +Layer 1's **public export is approved** (objective gate), and FIX-1405 specified it as +`readDeclaredRoster(root)` — the contract [ER-23](BUSINESS-RULES.md) blocks FIX-817 on. + + +## D6 · The set is seven children; two related issues are re-homed rather than parented + +| | | +|---|---| +| **Instead of** | Keeping FIX-817 and FIX-1415 parented as well — an epic that meets its own exit gate and then stays open, indefinitely, on two children it does not need | +| **Because** | **The exit gate and the wrap are different moments.** The wrap term requires every child to be [terminal](PLAN.md#terminal), and a phase-2 child that has never been built is not. An epic that cannot close after proving what it set out to prove has the wrong boundary | +| **Locks in** | **Originally five:** FIX-1394, FIX-1405, FIX-1385, FIX-1408 (done), and **FIX-1430 adopted as the proof**, which gives [ER-20](BUSINESS-RULES.md) its owner. **Now seven** — FIX-1381 pulled in and FIX-1451 confirmed, both below. FIX-817 and FIX-1415 are **related-not-child**, keeping their FIX-1405 dependency and this set's rules — FIX-817 still waits for FIX-1405's approved spec ([ER-23](BUSINESS-RULES.md)), and neither may re-decide [ER-3](BUSINESS-RULES.md) | + +**Re-homed is not descoped.** Both stay filed and keep their dependency edges; what changed is which +epic's wrap they hold: none. + + +**Amended 2026-09-19, 16:01 — the set is six.** The owner said **"pull it in"** of +[FIX-1381](https://linear.app/fixpoint-labs/issue/FIX-1381), answering a direct question about +whether to take it into the epic's tail or leave it in backlog. **His own word, not a reading of an +action** — the distinction matters here, because [the fence default](#fence-default) on this same +page is the other kind and must not be confused with this one. + +**What the amendment costs, stated before the call and restated here.** D6 existed to stop the epic +outliving its own gate, and this extension knowingly spends some of that: FIX-1381 has no spec and +no implementation, so the [wrap](PLAN.md#wrap) waited on it **as well as** on ER-20 passing, and +W4's finish moved further out. That was the owner's call to make and he made it with the consequence +in front of him. **It is a cheaper child than a cold one:** its direction is already decided by +**D-11 ([FIX-1380](https://linear.app/fixpoint-labs/issue/FIX-1380)), which is Done** — Ask 1 the +thin allowlist, Ask 3 org `ro` automatic and `rw` by permission — so what is outstanding is its +spec, not its shape. + + +**Corrected 2026-09-19 — the set is seven, and FIX-1451 was always the seventh.** The ticket was +read directly instead of from memory, and it contradicts what this document said: `parentId: +FIX-1407`, a `## Parent` section naming this epic — *"soft encounter under package cohesion, not a +ship-gate on FIX-1394"* — and Architect guidance reading *"ship-able honesty fix under FIX-1407; do +not nest under FIX-1359"*, filed by the owner at 12:58. **This is not a new call and not a re-gate.** +Nobody changed their mind; a documented parenting was correctly described by the tracker and +incorrectly described here. The standing note said to clear it, the note was wrong, and the write +was never made — which is the whole of why it cost nothing. + +**It is a `Bug`, so no spec.** It enters at implementation with its PR as the review surface +([ER-17](BUSINESS-RULES.md)), and it **holds the wrap** like any child. Counting FIX-1381, the +wrap's tail was then three open children plus ER-20; with ER-20 since +[passed](SPEC.md#er-20-passed) and FIX-1394's ratify recorded, it is this bug and FIX-1381. + +**The defect is worth more than the correction.** Twice on 2026-09-19 a remembered decision about +set membership disagreed with the ticket — [FIX-817](SPEC.md#related-not-children) out of a set the +memory had it in, FIX-1451 into one the memory had it out of. Both were caught by reading the ticket +before acting on the memory, and only one of the two had a write pending. The habit is the control, +not the outcome. + + +## Who owns what + +![A matrix of six cross-cutting rules against the five original issues in the set, each rule with exactly one builds-or-decides cell and any number of consumes cells. The figure's aria-label carries every cell.](figures/ownership.svg) + +A *consumes* cell is a place a child must not re-decide. **It is not a sequencing edge** — ER-3 is +FIX-1385's to obey, not to wait on. FIX-1430 consumes four rows and owns none, which is what makes +it a proof rather than a surface; what it owns is [ER-20](BUSINESS-RULES.md), a done-condition +rather than a matrix row, and **FIX-1385 provides the surface ER-20 stands on without owning it**. +[FIX-817 and FIX-1415](SPEC.md#related-not-children) consume ER-3 from outside the set. + +**The matrix is drawn against the original five and has deliberately not been redrawn.** Both later +children — [FIX-1381](#d6-extended) and [FIX-1451](#d6-seven) — **own no cross-cutting rule here**. +FIX-1381's spec is in review and unapproved, so which ER rows it consumes is not yet settled; +FIX-1451 is a bug and will never have a spec, so its column would be read off its PR rather than a scope document. +Inventing cells for either is a worse defect than a missing column. FIX-1381 gets its column when +its approved spec says what it touches; FIX-1451 gets one only if its fix turns out to touch a rule. + + +## Decided in review, recorded so no child reopens them + +| Decided | Because | Now lives in | +|---|---|---| +| Inventory is **two layers**; the helper-vs-resource fork is dismissed | The declared tree and the live set answer different questions | [D5](#d5) · ER-3 | +| The W3 ship fence has **one** release condition | Three documents stated it three ways — *merges*, *no open children*, *close* — which diverge the moment a child closes by decision | [D2](#d2) · ER-14 | +| The proof consumes **no package work** — not the implementation, and not the contract either | Binding it to either hangs the exit gate on work the lab does not need. ER-2 still binds it as a **fence** | [the spec](SPEC.md#what-the-proof-consumes) | +| **FIX-1385 owns ER-19**, the project's PR-5, **narrowed** to a check over this set's own diff | Running the repo-wide pass before the vocabulary lock pays the rename twice (project **PD-4**) | ER-19 | +| **The objective gate**: the exit gate is one hop · **the set is five**, FIX-1430 the proof · the compose helper's public export approved · **the ship fence as written** | The owner, 2026-09-19, ratifying the three-item ask as recommended | [D1](#d1) · [D6](#d6) · [D5](#d5) · [D2](#d2) | +| FIX-1394's POC keeps **one** of FIX-1408's walls — *which opt-in history packs are v1*; the other four returned to the epic, of which **three are still open** | A history pack **is** a library package with opt-in attachment, so the matrix already probes it. The four are session policy with no package content | ER-15 · [Open](#open) | +| The **inventory → boards** sequencing edge the epic asserted does not exist; dropped. **The set's one blocking edge is FIX-1385's implementation before FIX-1430** | FIX-1385's spec names inventory only as an optional read, and its BR-7 carries the caller's `assignee` with no seat resolution | [the graph](SPEC.md#how-the-issues-flow-into-each-other) · [the seams table](PLAN.md#coordination-seams-to-watch) | +| **A package is authored in Markdown**, as the new file, scoped to **instructions and tools** — and the format **may not be designed disk-only** | The owner, 2026-09-19 13:22, answering the numbered authorship fork directly: *"eventually we will allow anyone to write their own through an LLM creating it for them, but those won't be saved to disk, but as a resource. I think for now (if I understand correctly) **your recommendation is fine**."* **Both halves bind:** the recommendation is approved, and the direction — *anyone*, LLM-authored, stored as a resource — is a constraint on the design, so a format readable only off the filesystem is wrong on arrival. v1 still ships the file; *eventually* is not a deliverable. *Don't collapse* is no longer a live result | [ER-2](BUSINESS-RULES.md) · FIX-1394's [RATIFY.md](https://github.com/fixpoint-labs/flow-state-dev/blob/spec/FIX-1394-matrix/spec/FIX-1394/RATIFY.md) | +| ER-3 means **(a)** a contrast with the declared tree — **not (b)** relocating ChannelFlow's post fence onto an org resource | A channel's `members` is already live, read on the refusal path in the session the post lands in; (b) would put one fact in two places and tax every post | ER-3 · ER-12 | +| **Drain width is 1.** Work queues behind a busy seat; a busy seat never takes a second row concurrently | Closes FIX-1408's *auto-scale / busy-copy* wall on FIX-1430's evidence, the way [ER-15](BUSINESS-RULES.md) says such a wall closes: the lab ran at **both** widths and wrote the comparison out, rather than a number being picked. **Reversible** — the `MANAGER_QUEUE_DRAIN_WIDTH` knob stays, which is how the other case remains reachable | FIX-1430's `lab/README.md` · [Open](#open), one wall lighter | +| **Documents are org-scoped for now** — a seat's document is simply a resource under that seat on the org, and there is no per-seat document slot in v1 | The owner, 2026-09-19, answering FIX-1394's second ratify fork **in his own words rather than by taking the recommendation**. Per-resource configurability is not refused, it is *deferred to a mechanism that does not exist yet*: **resource templates** — "used to define the resource, but isn't the resource itself". Until those exist there is nothing to configure against, which is why v1 gets the org scope and no slot. **The exclusion is structural, not provisional:** a package attaches to **one seat** and a document installs at **org** scope, so a format declaring one would be a seat-level unit minting an org-level resource — true whichever format wins, so it is not a tiebreak. **This closes the second of the two forks**, and with it the ship tickets ER-8 gates | [ER-2](BUSINESS-RULES.md) · FIX-1394's ratify | +| **The set grew to six.** [FIX-1381](https://linear.app/fixpoint-labs/issue/FIX-1381) — the seat resource allowlist — is pulled in as a child | The owner, 2026-09-19 16:01, **"pull it in"**, answering whether to take it into the epic's tail or leave it in backlog. **His word, not an inference from an action.** It exists because he asked whether resource access inside workers and skills could be controlled yet and it cannot — `resourcesFromDocs` hard-codes `scope: "org"`, `workerConfigSchema` admits only `instructions` / `teamInstructions` / `seatSkills`, and no access gate exists in `workforce/src` or `orchestration/src`. No new ticket was needed: FIX-1381 already covers it as D-11 Ask 1's ship ticket. **It moves the wrap out**, knowingly | [D6](#d6-extended) · [the wrap](PLAN.md#wrap) | +| **The epic treats the W3 ship fence as narrowed to per-PR file overlap**, from 2026-09-19 | **An operating default, not a ruling, and not the owner's.** He merged #1928 through the live fence; the epic reads that action — not any statement, because there was none — as licence to stop parking W4 ship PRs whose diffs do not touch an unlanded W3 child's files. Recorded so the epic's behaviour is predictable and attributable rather than improvised per PR. **[The re-gate](#er-14-re-gate) is still open and still the owner's**, and **he can countermand this in a sentence**, at which point the default reverts to the rule as written | [ER-14](BUSINESS-RULES.md)'s note · [the re-gate](#er-14-re-gate) | +| **Two of FIX-1430's approved rules had their stated mechanism refuted by the code.** Both texts are corrected; both rules stand and are graded | **BR-5:** a row does run in its own session, with a parent bound at mint and none of the coordinator's transcript — but the parent is the **draining seat's** session, not the filer's, because the dispatch that mints the child happens at the seat, after the filing. **BR-11:** `adoptLapsedLease` (`packages/orchestration/src/task-board/task-entry.ts`) **renews** a lapsed lease so a successor *can* take the row back; `StaleTaskClaimError` fires only when a reclaim genuinely won. The substance — a lapsed row is really back in the queue — now grades the stronger true claim: the next drain takes it and runs it on the seat whose own file answers for the desk it was filed for | ER-4 · FIX-1430's `BUSINESS-RULES.md` and `lab/README.md` | +| **The set is seven — FIX-1451 was a child all along.** Not a new call; a correction to what this document said | The ticket, read directly rather than recalled: `parentId: FIX-1407`, a `## Parent` section naming this epic (*"soft encounter under package cohesion, not a ship-gate on FIX-1394"*), and Architect guidance reading *"ship-able honesty fix under FIX-1407; do not nest under FIX-1359"* — filed by the owner at 12:58 on 2026-09-19. The epic held a standing note to clear the parenting; **the note was wrong and the write was never made**. It is a `Bug`, so it [skips the spec](SPEC.md#the-seventh-child) and holds the wrap like any child | [D6](#d6-seventh) · [the wrap](PLAN.md#wrap) · ER-16 · ER-17 | + +The first four rows are round 1 (2026-09-18, five reviewers on +[#1905](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)); the rest are 2026-09-19, raised +up from a child rather than decided locally ([ER-15](BUSINESS-RULES.md) working). **The drain-width +and refuted-mechanism rows are a child's PR correcting the epic** — the same mechanism as the +cross-spec pass above them, pointed at a fact rather than a scope. **Two rows are neither.** [The +fence default](#fence-default) is how the epic behaves while a question with the owner stays open, +and it decides nothing that question will decide. [The seventh child](#d6-seven) is not a decision +at all — it is the tracker correcting this document. None of these rows reopens an approved +decision. + +**Two stay falsifiable.** ER-3's reading flips on evidence that a channel's `members` is *not* +current on the refusal path; the ER-15 split flips if those walls turn out to carry package content +after all. + +## What the end-state POC showed + +**None built.** The division came from the Architect's ownership carve, three of the original five +are themselves POC-first, and the gate approved it without one. The question a POC would still +answer: are the package format and the board's assign surface really two issues? + + +## Open + +**Both of FIX-1394's ratify forks are now closed** — [authorship](#authorship-answer) at 13:22 and +[documents](#documents-answer) later the same day — so nothing here blocks a child any more. The +set +question is closed twice over: [extended](#d6-extended) to six, then [corrected](#d6-seventh) to +seven. The compose helper's public export closed with D5's card ([D5](#d5)). What remains open is +**a re-gate on ER-14** and three of FIX-1408's walls. **Neither blocks work today.** + + +### Does the W3 ship fence narrow to per-PR overlap? — a pending re-gate + +*(Decides: the owner, and only the owner — this document records him ratifying **the ship fence as +written** at the objective gate, so narrowing it is a re-gate, not an epic call. Blocks: now +**FIX-1394's eventual ship PR**, **FIX-1381's eventual implementation** and the +[wrap term](PLAN.md#wrap); no longer #1928, and **no longer FIX-1451's fix**, whose conditional has +since resolved — [#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) does carry a +changeset, and the default clears it on zero file overlap ([the derivation](BUSINESS-RULES.md)). The bite **grew** with the set +rather than shrinking as the merges landed. The recommendation below is **the epic's**, and +**unanswered**.)* + +**The facts.** #1928 publishes `@flow-state-dev/workforce` and carries a changeset, so it is a +**ship PR** by [ER-14](BUSINESS-RULES.md)'s letter. FIX-1435 — a W3 child carrying an +implementation, hoisting the duplicated slot-descent walk in the resources loaders — is `Todo` with +**no branch and no PR at all**, so the fence was live. **By substance the overlap is empty:** +#1928's 13 paths sit under `packages/workforce/src/channel/`, `src/inventory/`, `test/`, the README, +`apps/docs/` and a changeset — **none** under `packages/workforce/src/loader/`, where FIX-1435 +lands. Same package, disjoint files. + +**The owner merged #1928 through the fence** on 2026-09-19 (`merged_by: jhoffner`, merge commit +`8428614`). That is his act and it **settles #1928** — nothing about that PR is outstanding and +nothing here asks for it to be undone. **It is not an answer to this question.** He has said +nothing about the rule, and a merge is not a rewrite: reading one as the other is how a fence gets +narrowed by accident and nobody can say when. + +**The recommendation stands, and stays the epic's: narrow ER-14 to per-PR overlap** — a W4 ship PR +is fenced only when its diff touches files an unlanded W3 child will edit. ER-14's own stated risk +is W4 shipping onto unlanded W3 *code*, and a fence that parks on package identity rather than file +overlap costs merges it was never aimed at. **What would change my mind:** evidence that FIX-1435's +hoist changes the *behaviour* of a loader a W4 child's code calls — then the package is the right +unit. **What being wrong costs:** a W4 change merged onto a floor still moving under it, so a +conflict or a silent behavioural change surfaces on `main` rather than in a rebase. **Nothing is +narrowed here:** ER-14's row stands exactly as written. + +**What the epic does in the meantime** is [its own operating default](#fence-default), not a +decision on this question — and the owner can countermand it in a sentence. + +**Why the two above are here and the three below are not.** Those are business calls the owner +owns and nothing else can settle; the three below are engineering walls that *building* answers +([ER-15](BUSINESS-RULES.md)). + +### Three of FIX-1408's walls, still with the epic + +*(Decides: the epic, as EM calls, on evidence. Blocks: nothing today. The fourth — +auto-scale / busy-copy — closed on 2026-09-19 as [drain width is 1](#drain-width).)* + +| Wall | What it decides | What would settle it | +|---|---|---| +| **Reuse-vs-create session policy** | Whether assigning a seat that is already running reuses its session or mints a second | **FIX-1430** — its lab reports which dispatcher `session` knob it ran. Also on the Architect's Still-open list ([ER-13](BUSINESS-RULES.md)) | +| **Hire-or-dispatch-with-parent naming** | What the call that mints a linked child is *called*, given [D4](#d4) fixed what it does | **FIX-1430's** board → seat call site — the first one read by anybody who did not write the name | +| **A sub-agent's background work on a board row** | Whether same-session background work is visible on the row at all, and as what | **Unowned, and orphaned.** It was FIX-1385's as the owner of the row; FIX-1385 closed without building a coordinator assign, so nothing left in the set will force it. [ER-11](BUSINESS-RULES.md) binds whoever takes it — a view, never a new status. **Named out at [the wrap](PLAN.md#wrap)**, so the epic cannot close by confirming a pass nobody ran | + +**What being wrong costs.** The bet was that FIX-1385 would force three of these; it did not. The +two still settleable ride on FIX-1430 — **which has now merged**, so the evidence is on `main` to be +read rather than waited for, and **this is the last cheap moment**: no child is left to force them, +and once the epic wraps nobody is looking. The third has no owner at all. + + +**A second unowned residue, from FIX-1385.** A seat naming a board id **no channel minted** is not +refused; it silently resolves a second, empty ledger, with only `warnUnattendedBoards` as a signal +(FIX-1385's BR-15: *there is no registry of legal board ids and this issue doesn't add one*). The +cross-flow half **did** ship — a board's id is derived from its channel, never written, so two flows +reach one logical board by naming the same channel and board name. The unrefused half has **no owner +and no filed ticket**, and FIX-1385 being Done does not give it one. + +Not this epic's to close: the Architect's **Still open** list ([ER-13](BUSINESS-RULES.md)) — exact +package schema, reuse-vs-create, nested cascade timing, how many POCs before a ship cut. Those close +with the owner, on the evidence FIX-1394's matrix produces. diff --git a/spec/_epics/work-routing-package-cohesion/PLAN.md b/spec/_epics/work-routing-package-cohesion/PLAN.md new file mode 100644 index 0000000000..3b7059978f --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/PLAN.md @@ -0,0 +1,193 @@ +# FIX-1407 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** + +An epic plan sequences the work and says what each piece entails — not how to build any piece, +which is each issue's own plan. IDs cross-reference [DECISIONS.md](DECISIONS.md) (D-n) and +[BUSINESS-RULES.md](BUSINESS-RULES.md) (ER-n). + +## The path + +![The path: a ship-fence band, two W3 input lanes, the seven lanes of the set against time with a now line at September 19, and two related lanes under a divider. The figure's aria-label carries every lane and bar.](figures/path.svg) + +Eleven lanes: two W3 inputs, the **seven** children of the set, and — under the divider — the two +[related issues](SPEC.md#related-not-children) that still consume FIX-1405. Four lanes are merged; +FIX-1394 sits at its **recorded** ratify, and the last two each open at the now line with a PR-open +bar and nothing merged behind it — **FIX-1381**, pulled in at 16:01, and +**[FIX-1451](SPEC.md#the-seventh-child)**, which was a child all along. Three lanes with nothing +merged is what the wrap's tail looks like. + +**The critical path ran boards → the proof, and all of it is behind us.** FIX-1385 merged on +2026-09-19 and FIX-1430's build followed it onto `main` the same day +([#1929](https://github.com/fixpoint-labs/flow-state-dev/pull/1929)). **The gate has since been met**: +[ER-20 passed](SPEC.md#er-20-passed) on 2026-09-19, three runs on the model path with both controls +red, once the project was pointed at an environment that could reach a model. The proof's lane ends +in a passed gate rather than an unrun one. **Behind the gate, the wrap has a tail of two:** +FIX-1381's spec and FIX-1451's fix. Neither is on the critical path — they came *after* it — but +both are terms of the wrap. + +## What each issue entails + +| Issue | Route | Consumes | Delivers | Releases | Size | +|---|---|---|---|---|---| +| **FIX-1408** dispatch policy | design → **closed as decided** | D4's two leans | Sub-agent vs seat-assign, `parentSessionId` at mint, opt-in history, the brief | Every other child | — | +| **FIX-1405** runtime inventory | spec → POC → **impl, merged** | The three existing readers · hire · `channelInstances` · open sessions (D5) | Two layers: a declared roster composed at read time (replacing both labs' private `LabRoster`), and the live org resource | FIX-817, on its approved reader contract (ER-23) · FIX-1415 · `team.*` wildcards, later. **Not FIX-1385** | Medium · all three PRs on `main` — PR-A [#1920](https://github.com/fixpoint-labs/flow-state-dev/pull/1920), S4 [#1923](https://github.com/fixpoint-labs/flow-state-dev/pull/1923), S5–S7 [#1928](https://github.com/fixpoint-labs/flow-state-dev/pull/1928) | +| **FIX-1385** channel boards | spec → POC → **impl, merged** | The ChannelFlow floor · ER-5 · ER-3, which it may not re-decide and reads only **if** the roster has landed | A channel holding `0..N` TaskCollections; two doors, one surface. Plus the PR-5 name check over its own diff (ER-19) | The proof · FIX-1430 — **released 2026-09-19** | Large · shipped in one PR, not four | +| **FIX-1394** package cohesion | **POC matrix → ratify, recorded** → ship tickets | FIX-1377's team layer · FIX-1416's `tools:` fence — **both landed** at `d8e4c99`, and the code wins over either spec (ER-18) · D4 | One format as a Markdown file, instructions and tools, two attachment modes, **not disk-only**, **documents org-scoped** (ER-2). Its POC also carries the evidence for **one** of FIX-1408's walls (ER-15) | Ship tickets, once the ratify completes (ER-8) — **not** the proof | Large | +| **FIX-1381** seat resource allowlist | spec → impl · **spec PR [#1935](https://github.com/fixpoint-labs/flow-state-dev/pull/1935) open**, in review, gate unanswered | **D-11's settled direction** (FIX-1380, Done): Ask 1 the thin allowlist, Ask 3 org `ro` automatic / `rw` by permission · today's `resourcesFromDocs` org hard-code and the `WorkerConfig` gap its invent-kill names | Thin seat/kind resource refs by `ro`/`rw` — the first control over which resources a worker or skill reaches | **The wrap** — it is now a term of it | Not sized · direction settled, spec in review | +| **FIX-1451** allowed-tools honesty · *a bug* | **no spec** → impl · fix PR [#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) open on `fix/FIX-1451-allowed-tools-honesty` | FIX-1416's landed `tools:` fence at `d8e4c99` — the promise the bug is about (ER-18) | A seat's skill no longer promising a tool grant the loader does not make | **The wrap** — a term of it like any child. Explicitly **not** a ship-gate on FIX-1394 | Not sized · a bug, scoped by its PR rather than a spec | +| **FIX-1430** manager-queue lab · *the proof* | spec → **impl, merged** → **goal check PASS**, three runs | ER-1 · **ER-2 as a fence, not an input** · ER-4 · ER-5 — consumes four, owns none | A coordinator seat assigning over a channel board to linked seats, queue columns as views. Plus the drain-width comparison ER-15 called for ([width 1](DECISIONS.md#drain-width)) | The epic's wrap, **once ER-20 runs** — merging did not release it | Medium · [#1929](https://github.com/fixpoint-labs/flow-state-dev/pull/1929) merged | + +**Size is a read, not an estimate.** Three of the original five are exploration tickets whose own +scope is the thing being explored — FIX-1394 most of all, whose ship tickets are not in this set +yet. **The two newest children are deliberately unsized, for opposite reasons:** FIX-1381's +direction is settled by D-11 but its spec is still in review, and a number before that spec is +approved would be a guess wearing an estimate's clothes; FIX-1451 is a bug and will never have a +spec, so its scope is whatever its PR turns out to be. + +## Where it is + +Status lives in one place: [the set table](SPEC.md#the-set--as-of-2026-09-19). The lanes above are +the same state as a picture of time, and Linear mirrors both ([ER-16](BUSINESS-RULES.md)). + +**Both W3 inputs have landed** — FIX-1377 and FIX-1416, merged 2026-09-19 +([#1911](https://github.com/fixpoint-labs/flow-state-dev/pull/1911), +[#1909](https://github.com/fixpoint-labs/flow-state-dev/pull/1909)), on main at `d8e4c99`. Write +against **that code** and name the commit ([ER-18](BUSINESS-RULES.md)). They stay dashed edges in +the graph because they do not block, not because the code is missing. + +## What unblocks what, from here + +1. **The objective is approved** — 2026-09-19. Nothing waited on anything else to *start*. +2. **FIX-1405's reader contract is approved** → FIX-817 may specify against it (ER-23). Leaving the + set did not change this edge. +3. **Nothing inside the set sequences a *start*.** In particular there is **no inventory → boards + edge**: FIX-1385 reads the declared roster only *if it has landed*, and its BR-7 carries the + caller's `assignee` verbatim rather than resolving a seat ([ER-5](BUSINESS-RULES.md)). +4. **FIX-1385's implementation landed** ([#1922](https://github.com/fixpoint-labs/flow-state-dev/pull/1922)) + → the proof's build ran, and has since merged too. The set's only true blocking edge is + discharged, and **four of the seven children are on `main`**. +5. **ER-20 ran on the real path and passed** → the epic's *claim* is proved, 2026-09-19. It was + blocked on an **environment** rather than on work, and that blocker is gone — the project was + pointed at the FSD environment and a thread ran the gate there, three consecutive passes with + both controls red ([the run](SPEC.md#er-20-passed)). It was the one term nobody could work + around; **[two open children](#wrap) are the rest of the wrap**, and those are work. +6. **W3's last implementing child merges** → the ship fence lifts (ER-14). That is **FIX-1435**, + still `Todo` with no branch and no PR. Four W4 ship PRs have merged under the live fence, the + last of them **#1928, by the owner himself** — which settles that PR without answering the rule. + What is still fenced is **FIX-1394's eventual ship PR**, **FIX-1381's eventual implementation**, + **FIX-1451's fix if it ships a package** (that changeset call has not been made) and the + [wrap](#wrap) — the fence's bite **grew** when the set did. Whether the rule + narrows is [a re-gate with the owner](DECISIONS.md#er-14-re-gate), not an epic call; how the + epic behaves until he answers is [an operating default](DECISIONS.md#fence-default). +7. **FIX-1394's ratify completes** → ship tickets are cut (ER-8). **Both forks are now answered** — + [authorship](DECISIONS.md#authorship-answer), and [documents as + org-scoped](DECISIONS.md#documents-answer) — so nothing external holds it. Those tickets are new + children and will need this path redrawn. It does **not** unblock the proof ([the spec](SPEC.md#what-the-proof-consumes)). +8. **FIX-1381's spec lands, then its implementation** → one of the three remaining wrap terms + clears. It starts with its direction already decided by D-11 (FIX-1380, Done), so the spec is + describing a settled shape rather than choosing one. Its implementation will be a **ship PR** and + therefore sits under [ER-14](BUSINESS-RULES.md). +9. **FIX-1451's fix merges** → the last of the three clears. **No spec gate on this one** — it is a + `Bug`, so its PR is the review surface ([ER-17](BUSINESS-RULES.md)) and it goes straight to + implementation on `fix/FIX-1451-allowed-tools-honesty`. It is fenced by ER-14 only **if** it + ships a package; that call has not been made. + +## Coordination seams to watch + +| Seam | Between | Rule | +|---|---|---| +| The inventory surface | FIX-1405 and FIX-817 *(related, not a child)* | 1405 owns both layers; 817 reads them, and specs only after 1405's reader contract is approved (ER-23) | +| The seat's `tools:` fence | FIX-1394 · FIX-1415, outside the set · FIX-1416, **landed** | Three edits on one fence, in that order (ER-23). None widens past seat `tools:`, and FIX-1416's merged code is the fence's actual shape, not its spec | +| The skill's tool promise | **FIX-1451** and FIX-1394 · FIX-1416, **landed** | The bug is that a skill's `allowed-tools` promises a grant the loader does not make, on the same surface FIX-1394's format scopes to *instructions and tools*. **Explicitly not a ship-gate on FIX-1394** — the owner filed it as a soft encounter, so 1394's ratify never waits on it. Both write against FIX-1416's merged fence at `d8e4c99`, not its spec (ER-18) | +| The seat's prompt compose | FIX-1394 and FIX-1377 | Composes framework default → team → seat. No fourth layer; the team's text does not merge into the seat's | +| The board's claim / assign surface | FIX-1385 (**merged**) and FIX-1430 (**#1929, merged**) | 1385 owned it and shipped it; the lab consumes what landed. Two of 1385's rules about that surface were read back by the lab and [corrected](DECISIONS.md#refuted-mechanisms) rather than worked around. What 1385 did **not** settle is named in [DECISIONS](DECISIONS.md#the-cross-flow-board-residue) and has no owner | +| The same surface, again | FIX-1385 and FIX-1415 *(related, not a child)* | 1415's invite verbs land on the channel 1385 hangs a board on. Re-homing moved the wrap, not the collision | +| One channel flow factory, two PRs | FIX-1385 (**merged**) and FIX-1405's **S5–S7 ([#1928](https://github.com/fixpoint-labs/flow-state-dev/pull/1928), merged)** | Both edit `defineChannelFlow` and the binder. **Closed:** FIX-1385 shipped whole first and #1928 landed on top of it rather than racing it, its own deviations noting where the landed code won. Board *declaration* stays built-in-kind-only; channel *inventory* is every kind's | +| The Workforce docs section | FIX-1385, FIX-1405, FIX-1430 | All three teach boards. Whichever lands second links rather than repeats | +| What a seat's file may declare | FIX-1394 and **FIX-1381** | Both extend `WorkerConfig` — 1394 with the package format's instructions and tools, 1381 with `ro`/`rw` resource refs. Neither widens into the other's half, and the seat `tools:` fence stays ER-23's. **Confirm this seam once FIX-1381's spec exists**; it is named now because the collision is foreseeable, not because it has been checked | + +## Not children, deliberately + +**Re-homed at the objective gate** ([D6](DECISIONS.md#d6)), FIX-1405 dependency preserved and still +bound by ER-3 and ER-23: [FIX-817](https://linear.app/fixpoint-labs/issue/FIX-817) (catalog +manifests) and [FIX-1415](https://linear.app/fixpoint-labs/issue/FIX-1415) (channel-admin verbs). +Neither holds this epic's wrap; both remain filed. + +**Re-homed 2026-09-19:** [FIX-1459](https://linear.app/fixpoint-labs/issue/FIX-1459), the ship +ticket for the ratified package format, for the same reason — the build is downstream of W4's +objective, not inside it ([the spec](SPEC.md#related-not-children)). ER-8's hold is discharged by +it being cut; ER-14 fences it when it starts. + +**Related to FIX-1381, and not absorbed by it:** +[FIX-1454](https://linear.app/fixpoint-labs/issue/FIX-1454) is the scope-*existence* half — that a +resource cannot be scoped to a single seat at all — which is a different question from which +resources a seat may reach. [FIX-1442](https://linear.app/fixpoint-labs/issue/FIX-1442), the +org-identity security pass, is adjacent. Neither is a child. + +Soft-after for ship, never re-parented: [FIX-1351](https://linear.app/fixpoint-labs/issue/FIX-1351) +(**W3**, D2). Parked: [FIX-1341](https://linear.app/fixpoint-labs/issue/FIX-1341) (**Collab RC**). +Shipped and not reopened inside W4: [FIX-1359](https://linear.app/fixpoint-labs/issue/FIX-1359) +(OOTB agent kind), [FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440) (nested-session +removal — cited as a fence, never a ship child). Consumed, not owned: FIX-1388, FIX-1393, FIX-1426, +FIX-1410, FIX-1373, FIX-957. + +## Wrap + +When **[ER-20](BUSINESS-RULES.md) holds** and every remaining child is terminal — **now seven +children, not five** ([amended](DECISIONS.md#d6-extended), then [corrected](DECISIONS.md#d6-seventh)). + + +**Terminal is read from GitHub, not from Linear.** A child is terminal when its **implementation PR +is merged or closed**, or when this epic-spec records its work as **done by decision rather than as +code** — which is FIX-1408, and the set table is where that is recorded. Linear is the mirror; a +merge is what makes code shipped. **Five children are terminal: FIX-1408 and FIX-1394 by +decision, FIX-1385, FIX-1405 and FIX-1430 by merge.** FIX-1394 counts here because its deliverable +was the ratify and the ratify is recorded — its matrix PR never merges and its build left the set as +[FIX-1459](SPEC.md#related-not-children). Two are not terminal: **FIX-1381, whose spec PR +[#1935](https://github.com/fixpoint-labs/flow-state-dev/pull/1935) is open and unapproved**, and +**FIX-1451, whose fix PR +[#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) is open and unmerged**. Note +that FIX-1451 needs no spec to become terminal — a bug's route runs straight to its implementation PR +([ER-17](BUSINESS-RULES.md)) — so a missing spec there is not a missing step. + +**ER-20 ran and passed, so the gate is met.** [The row reads PASS](SPEC.md#er-20-passed) — three +consecutive runs of +`goals/manager-queue-lab/it-routes-a-queue-to-the-seats-their-files-name` at `GOAL_FILER=model` on +`vercel/openai/gpt-5.4-mini`, against `e6ccb22` of `main`, with both negative controls red at their +own legs on the same path. **Terminal children were never a met gate**, and for a week this set was +the clearest case of that difference: everything built was on `main` and nobody had watched it work. +Somebody has now watched it work. **One caveat on where that is written down:** the `NOT RUN` row +inside `goal.md` on `main` is still stale and needs its own PR — that is not this branch's to fix, +and until it lands, `main` does not yet say what this page says. + +**And meeting the gate is no longer the same moment as wrapping.** [D6](DECISIONS.md#d6) bought +exactly that alignment at the objective gate, and the set has since grown twice — the owner +deliberately pulled **FIX-1381** in at 16:01 with the cost stated to him, and **FIX-1451** turned +out to have been a child since 12:58, which no call made and no call can undo. So the wrap needed +**ER-20 passing *and* every child terminal**. **ER-20 is now met, and the second term is not:** +FIX-1381 and FIX-1451 are both open. Only one of those two growths was a choice, and they are what +is left. + +**Which children count is no longer open.** The tracker and this document agree on seven +([ER-16](BUSINESS-RULES.md)), and there is no unconfirmed remainder. That agreement was reached by +reading the tickets rather than trusting this document, which is the only reason it is worth +stating — [the epic had FIX-1451 wrong](DECISIONS.md#d6-seventh), and a wrap computed from the +wrong membership is a wrap that closes over unbuilt work. + +**Three things must be named out at the wrap, not confirmed.** None has an owner inside W4, and each +would otherwise close as a pass nobody ran: + +- **ER-19's repo-wide PR-5 rename.** What FIX-1385 owed was a check **over its own diff**; the + repo-wide pass is the project's and waits on its vocabulary lock ([ER-19](BUSINESS-RULES.md)). +- **How a sub-agent's background work surfaces on a board row.** Orphaned when FIX-1385 closed + without building a coordinator assign; [unowned](DECISIONS.md#open), and nothing left in the set + will force it. +- **A board id no channel minted.** Not refused — it silently resolves a second, empty ledger + ([the residue](DECISIONS.md#the-cross-flow-board-residue)). No owner, no filed ticket. + +Then: run the lessons pass over the set's review rounds, and dispatch the docs polish over the +Workforce pages the children each edited in isolation. It owes the sentence nobody else will write — +a board **assignee** and a Workforce **seat** are two different things that map by composition +(ER-5, [ER-22](BUSINESS-RULES.md)). Refresh the set table and the path one last time, and close the +epic PR unmerged. diff --git a/spec/_epics/work-routing-package-cohesion/SPEC.md b/spec/_epics/work-routing-package-cohesion/SPEC.md new file mode 100644 index 0000000000..5ece996fe0 --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/SPEC.md @@ -0,0 +1,263 @@ +# FIX-1407 · W4: work reaches a seat + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +Epic · 7 issues · Workforce: Layer 2 Abstraction · Goal 1 — Workforce multi-seat real usage / +architecture cohesion + +## Four teams, before and after + +| A team that… | Today | After this epic's first cut | +|---|---|---| +| **has work for a team of seats** | Nowhere shared to put it. Dispatched by hand, from code, one seat at a time | It goes on the channel's board. A seat claims it or is assigned it, and runs it | +| **writes one package for a seat** | Two overlapping systems — the seat's prompt file and skills — and no answer to which one a tool belongs in | One answer: **one package format, written in Markdown**, scoped to instructions and tools, with two attachment modes. A team writes one without an engineer | +| **asks what seats and channels exist** | Opaque strings. `engineering.*` cannot expand, and a seat cannot find another seat's DM | A declared roster read from the tree, plus a live org resource for what is actually open | +| **hands work from one seat to another** | Invents an ambient transcript dump, or a second runtime | A brief, a linked session bound to its parent for life, and parent history only by opt-in tools | + +**Why now.** W3 made a Workforce *describable*. Nothing yet says how **work reaches** one of those +declared seats: no shared place to file it, no runtime answer to "which seats exist", and three +unreconciled meanings of *assign*. W3 proved a seat is described; W4 proves a seat is given work. + +## What's in the box + +![The W4 first cut in three bands: what this epic builds, what the app composes in, and — below a fence — what the set refuses to build. The figure's aria-label carries every item.](figures/end-state.svg) + +The **exit gate is the top row and only the top row** ([D1](DECISIONS.md#d1)). The strip under it is +phase-2 *inside* W4 — named so nobody reads it as refused, and nothing on it holds the wrap +([D6](DECISIONS.md#d6)). The bottom strip is what the set refuses to build, named out rather than +forgotten. + +## The set · as of 2026-09-19 + +The live table. Refreshed on the epic PR as issues move; the plan and the figures point here, and +Linear mirrors it ([ER-16](BUSINESS-RULES.md)). **A closed spec PR is review history, not the +document:** read the spec branch's head, or the Linear document on the issue. + +| Issue | What it delivers | Why the set needs it | Status | +|---|---|---|---| +| FIX-1408 | Dispatch / session policy: sub-agent is same-session background, worker assign is a roster seat in a **linked** session, `parentSessionId` at mint, history by opt-in tools | The wire everything else routes over | **Done** · 2026-09-18 · no impl PR ([below](#a-note-on-fix-1408)) | +| FIX-1394 | **One package format as a Markdown file**, scoped to instructions and tools, two attachment modes, and **not disk-only** ([ER-2](BUSINESS-RULES.md)). POC-first | Half the epic's title. Two overlapping surfaces grow board and tool sugar twice until this settles | **Done by decision** · 2026-09-19 · the **ratify is the deliverable** and it is recorded — both forks [decided](DECISIONS.md#decided-in-review), [authorship](DECISIONS.md#authorship-answer) and [documents](DECISIONS.md#documents-answer). Matrix [#1921](https://github.com/fixpoint-labs/flow-state-dev/pull/1921) stays open and never merges; the **build is [FIX-1459](#related-not-children), outside the set** | +| FIX-1405 | Inventory in two layers: a declared roster composed from the existing readers, and the live org resource ChannelFlow updates | The epic's third promise in its own right — *which seats and channels exist* — and what `team.*` addressing calls later ([ER-7](BUSINESS-RULES.md)). It does **not** gate the boards | **Done** · 2026-09-19 · PR-A [#1920](https://github.com/fixpoint-labs/flow-state-dev/pull/1920), S4 [#1923](https://github.com/fixpoint-labs/flow-state-dev/pull/1923) and S5–S7 [#1928](https://github.com/fixpoint-labs/flow-state-dev/pull/1928) all **merged** — terminal by merge | +| FIX-1385 | A channel holding `0..N` TaskCollections; channel actions and `taskTools` as two doors on one surface. Plus the PR-5 name check over its own diff ([ER-19](BUSINESS-RULES.md)) | **The exit gate's surface** — the board in "channel/org board → seat runs" | **Done** · 2026-09-19 · [#1922](https://github.com/fixpoint-labs/flow-state-dev/pull/1922) **merged** — one full-scope PR, not the spec's four ([the seam it discharged](PLAN.md#coordination-seams-to-watch)) | +| FIX-1430 | Manager-queue lab: a coordinator seat owns a channel board, assigns to linked seats, shows queue state as **views** over existing task status | The **proof** of the exit gate, and the owner of [ER-20](BUSINESS-RULES.md) | **Done** · 2026-09-19 · [#1929](https://github.com/fixpoint-labs/flow-state-dev/pull/1929) **merged**, and **the gate it exists to run [has passed](#er-20-passed)** — three runs, controls red | +| [FIX-1381](https://linear.app/fixpoint-labs/issue/FIX-1381) | **Seat resource allowlist** — thin seat/kind refs by `ro`/`rw`. The ship ticket for D-11 Ask 1 | Nothing today can control which resources a worker or skill reaches: `resourcesFromDocs` hard-codes `scope: "org"` and `workerConfigSchema` admits only `instructions`, `teamInstructions`, `seatSkills`. **Pulled in by the owner** ([below](#the-sixth-child-pulled-in)) | **In spec review** · spec PR [#1935](https://github.com/fixpoint-labs/flow-state-dev/pull/1935) open on `spec/FIX-1381` · **the spec gate is with the owner and unanswered — nothing here is approved** | +| [FIX-1451](https://linear.app/fixpoint-labs/issue/FIX-1451) | **Skill `allowed-tools` promises a grant it does not make** — the honesty fix on the seat's tool surface | A seat's package is half of this epic's title, and a promise the loader does not keep is the package lying about what a seat can reach. Parented by the owner as a *soft encounter under package cohesion*, explicitly **not a ship-gate on FIX-1394** ([below](#the-seventh-child)) | **In PR review** · a `Bug`, so [**no spec**](#the-seventh-child) — the PR is the review surface · fix PR [#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) open on `fix/FIX-1451-allowed-tools-honesty`, 10 files | + +**Five of seven children are complete; two are open.** FIX-1385, FIX-1405 and FIX-1430 merged to +`main` on 2026-09-19, and two are done by decision rather than as code — FIX-1408, whose deliverable +was the dispatch policy, and **FIX-1394, whose deliverable was the ratify** ([the build is downstream](#related-not-children)). +Open: **FIX-1381** at its spec and **FIX-1451** at its fix. Both joined the set today — one pulled +in, one confirmed as having been a child all along. + +**The thing this set exists to prove has now been observed** — [ER-20 passed](#er-20-passed), three +runs, with both controls red on the same path. That was the one term no amount of work could +substitute for, and it is met. **It is still not a wrap:** the other term is every child terminal, +and two are not. What is left is two pull requests, which is a different kind of obstacle from the +one that stood here this morning. + + + +**[ER-20](BUSINESS-RULES.md) PASSED on 2026-09-19 — the row that read `NOT RUN` all week now reads +PASS.** The gate is +`goals/manager-queue-lab/it-routes-a-queue-to-the-seats-their-files-name`, run at the default +`GOAL_FILER=model` on `vercel/openai/gpt-5.4-mini`, against commit `e6ccb22` of `main`. **Three +consecutive runs passed.** A coordinator seat whose own file declares `tools: []` chose the desks +and filed four rows through the eight task tools its kind composes; **every row ran on the seat +whose own file answers for that desk**, proved by the outbox rather than by the board's own report. +The waiting row was neither re-routed nor dropped, and a row filed for nobody settled `errored`, +named, and ran nowhere. + +**Both controls went red, each at its own leg and nowhere else** — `repointed-map` produced exactly +three leg-(c) identity failures with every row still running and completing, so only the +association moved; `duplicate-filing` produced exactly the two leg-(b) arms and nothing else. **Both +ran on the model path**, which is what makes this row worth more than the scripted control logged on +[#1929](https://github.com/fixpoint-labs/flow-state-dev/pull/1929) — and it is the first check in +this epic whose negative control was demonstrated on the same path as its pass +([why that matters](BUSINESS-RULES.md)). The environment blocker is gone: the project was pointed at +the FSD environment and a thread ran it there. + +**This does not wrap the epic, and nothing here should be read as it doing so.** ER-20 was one of +two wrap terms; the other is every child terminal, and **two children are still open** — +[FIX-1381](#the-sixth-child-pulled-in)'s spec, with you on +[#1935](https://github.com/fixpoint-labs/flow-state-dev/pull/1935), and +[FIX-1451](#the-seventh-child)'s fix on +[#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936). Neither is merged. What changed +is the *kind* of thing standing in the way: for a week it was a fact nobody had observed, and now it +is two pull requests. + + +**The sixth child, and what it cost.** [FIX-1381](https://linear.app/fixpoint-labs/issue/FIX-1381) +joined the set at the owner's own word — *"pull it in"*, 2026-09-19 16:01, answering whether to take +it into the epic's tail or leave it in backlog. It arrived from his own question earlier that day, +whether resource access inside workers and skills could be controlled yet. It cannot: `resourcesFromDocs` +hard-codes `scope: "org"` (`packages/workforce/src/resources-from-docs.ts:80`), `workerConfigSchema` +admits only `instructions`, `teamInstructions` and `seatSkills` +(`packages/workforce/src/worker-config.ts:89`), and no access gate exists anywhere in `workforce/src` +or `orchestration/src`. It needed no new ticket: **FIX-1381 already covered it exactly**, as the ship +ticket for D-11 Ask 1, its own invent-kill naming that `WorkerConfig` gap. + +**It moved the wrap out, and that was said before the call was made.** The [wrap](PLAN.md#wrap) now +needed FIX-1381 terminal **as well as** ER-20 passing; ER-20 has since passed, and FIX-1381's spec +is only now in review with no implementation — so it is now one of the two things W4's finish waits +on. The owner made that call with the consequence in +front of him. **It enters cheaper than a cold child:** [D-11 (FIX-1380)](https://linear.app/fixpoint-labs/issue/FIX-1380) +is **Done** and already decides its direction — Ask 1 the thin allowlist, Ask 3 org `ro` automatic +and `rw` by permission — so only its spec is outstanding, not its shape. + +**On its Architect fence.** FIX-1381's body fences it against being nested under **W3**. That fence +is about W3 and it still stands; the owner pulled it into **W4**, which the fence does not speak to. +Not a fence broken — a different parent. + +**Related, not absorbed.** [FIX-1454](https://linear.app/fixpoint-labs/issue/FIX-1454) is the +scope-*existence* half — resources cannot be scoped to a single seat at all — which is a different +question from which resources a seat may reach. +[FIX-1442](https://linear.app/fixpoint-labs/issue/FIX-1442), the org-identity security pass, is +adjacent. Neither is folded in here. + + + + +**The seventh child: FIX-1451 was never unconfirmed — the epic's note was wrong.** +[FIX-1451](https://linear.app/fixpoint-labs/issue/FIX-1451) (*skill `allowed-tools` promises a grant +it does not make*) carries `parentId: FIX-1407`, a `## Parent` section naming this epic — *"soft +encounter under package cohesion, not a ship-gate on FIX-1394"* — and Architect guidance reading +*"ship-able honesty fix under FIX-1407; do not nest under FIX-1359"*. Filed by the owner at 12:58 on +2026-09-19. **The parenting is deliberate and documented.** The epic carried a standing note saying +to clear it; that note was wrong and the write was never made, which is the only reason the mistake +cost nothing. + +**It is a `Bug`, so it skips the spec** and enters at implementation with its PR as the review +surface ([ER-17](BUSINESS-RULES.md)) — there is no spec gate to wait for. That surface now exists: +[#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936) on +`fix/FIX-1451-allowed-tools-honesty`. **It holds the wrap like any child**, and with +[ER-20 met](#er-20-passed) the wrap's tail is now just it and FIX-1381. + +**Worth naming, because it is this epic's own recurring defect in miniature:** a remembered decision +about set membership, contradicted by the ticket, caught only by reading the ticket before acting on +the memory. That is twice in one day — [FIX-817](#related-not-children) went the other way, out of a +set the memory had it in. + + +**Related, not children.** [FIX-817](https://linear.app/fixpoint-labs/issue/FIX-817) (catalog +manifests) and [FIX-1415](https://linear.app/fixpoint-labs/issue/FIX-1415) (channel-admin verbs) are +real work in the same area the epic's promise does not need. Both **keep their FIX-1405 dependency** +and still obey this set's rules: FIX-817 waits on FIX-1405's **approved** spec +([ER-23](BUSINESS-RULES.md)), and neither may re-decide [ER-3](BUSINESS-RULES.md). + +**And the format's build is downstream, not inside.** +[FIX-1459](https://linear.app/fixpoint-labs/issue/FIX-1459) — *ship `PACKAGE.md`, the ratified +worker-package format* — is FIX-1394's ship ticket, **re-homed to related-not-child** on +2026-09-19. W4's objective is the exploration and the decisions it produced; building the ratified +format is downstream of that objective, and parenting it would stop this epic wrapping until a +fresh multi-week feature landed. **So the format is ratified inside W4 and shipped outside it** — +said plainly here because a later reader could otherwise conclude it shipped in this epic. It holds +no wrap; [ER-14](BUSINESS-RULES.md) still fences it when it is picked up. + + +**A note on FIX-1408.** Done with no implementation PR: what shipped is the **decision** +([D4](DECISIONS.md#d4)). Of its five open walls, **one** is evidenced by FIX-1394's POC, **one** +closed on FIX-1430's evidence ([drain width is 1](DECISIONS.md#drain-width)), and **three** are +parked in [Open](DECISIONS.md#open) ([ER-15](BUSINESS-RULES.md)). + +## How the issues flow into each other + +```mermaid +flowchart LR + T377["FIX-1377 · TEAM.md · W3, landed"] -.->|"the team layer a package composes onto"| PK + T416["FIX-1416 · tools fence + blocks scan · W3, landed"] -.->|"what a seat may call"| PK + DP["FIX-1408 · dispatch / session policy"] -->|"the wire: parentSessionId, opt-in history"| BD + DP --> PK["FIX-1394 · package cohesion"] + INV["FIX-1405 · runtime inventory"] -.->|"read if it has landed — not a wait"| BD["FIX-1385 · channel boards"] + BD -->|"the exit gate's surface"| LAB["FIX-1430 · manager-queue lab · the proof"] + PK -.->|"a fence on what the lab may author — not an input"| LAB + D11["FIX-1380 · D-11 · done"] -.->|"the settled direction: thin allowlist, org ro/rw"| ACL["FIX-1381 · seat resource allowlist"] + T416 -.->|"the fence whose promise the bug breaks — not a wait"| HON["FIX-1451 · allowed-tools honesty · bug"] + HON -.->|"soft encounter — explicitly not a ship-gate"| PK + subgraph REL ["related, not in the set — consume it, do not hold its wrap"] + CAT["FIX-817 · catalog manifests"] + ADM["FIX-1415 · channel-admin"] + end + INV -->|"approved reader contract first, ER-23"| CAT + INV -.->|"invite and find"| ADM + T416 -.-> ADM + classDef done stroke-width:2px + class DP,BD,INV,LAB,D11 done +``` + +A **solid** edge blocks; a **dashed** edge does not, and its label says why — **landed code** to +write against ([ER-18](BUSINESS-RULES.md)), a **fence** the child holds itself to +([the proof](#what-the-proof-consumes)), or a surface read **if it has landed**. A heavy border is +done. The two in the box are [related, not children](#related-not-children). + +**Exactly one edge inside the set blocks, and it is discharged** — FIX-1385's implementation before +FIX-1430. FIX-1385 merged, so the proof's one prerequisite exists and its build ran. The inventory +does **not** gate the boards: FIX-1385's spec names the declared roster only as an optional read, +and its BR-7 carries the caller's `assignee` verbatim rather than resolving a seat +([ER-5](BUSINESS-RULES.md)). + + +**The proof consumes no package work — not the implementation, and not the contract either.** +FIX-1430's seats run on surfaces already on `main` at `d8e4c99` that FIX-1394 does not change, and +the lab authors no package shape at all, so it stayed compatible with every answer FIX-1394 could +reach — including the one it reached. [ER-2](BUSINESS-RULES.md) still binds it as a **fence**: no +shape the ratified format would contradict. Binding the proof to a shipped package, or to a ratify, +would hang the exit gate on work it does not need — the unreachable gate [D1](DECISIONS.md#d1) +exists to prevent. + +## What stays as it is + +- **Collab RC ([FIX-1341](https://linear.app/fixpoint-labs/issue/FIX-1341))** — parked. FIX-1415 + shapes a capability surface; it does not reopen Collab. +- **The W3 floor ([FIX-1351](https://linear.app/fixpoint-labs/issue/FIX-1351))** — soft-*after* for + ship, never a parent ([D2](DECISIONS.md#d2)). +- **Session substrate ([FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440))** — linked + dispatch does not re-legitimize nested sessions as a work hierarchy ([D4](DECISIONS.md#d4)). +- **The OOTB agent kind ([FIX-1359](https://linear.app/fixpoint-labs/issue/FIX-1359))** — shipped. + Package cohesion flags drift against it; it is not redesigned from zero. +- **The board's claim system** — `assignee` stays optional, `TaskStatus` does not grow + ([ER-11](BUSINESS-RULES.md)). +- **`goals/devforce-lab/` ([FIX-1426](https://linear.app/fixpoint-labs/issue/FIX-1426))** — the + coding seam only; it does not grow into FIX-1430's showcase. + +## Signed off · 2026-09-19 + +The owner ratified all three items of this section's ask, each with the recommendation it carried. +What each one killed is in the card behind it. + +1. **[D1](DECISIONS.md#d1) · The exit gate is channel/org board → seat runs / assign team seats.** + The nested cascade is phase-2 inside W4. +2. **[D6](DECISIONS.md#d6) · The set was five**, FIX-1430 adopted as the proof, which gives + [ER-20](BUSINESS-RULES.md) its owner; FIX-817 / FIX-1415 re-homed as + [related-not-child](#related-not-children), dependency preserved. **[Extended to six on + 2026-09-19](DECISIONS.md#d6)** by the owner, pulling in FIX-1381. +3. **[D2](DECISIONS.md#d2) · W4 *ship* PRs are soft-after W3**, as written: the fence lifts when + every W3 child that carries an implementation is merged to main. + +Also approved: **the public export of the compose helper on `@flow-state-dev/workforce`** +([D5](DECISIONS.md#d5)). **Since the gate, both of FIX-1394's ratify forks are answered.** *[Who +authors a package](DECISIONS.md#authorship-answer)* — the Markdown file, on your *"your +recommendation is fine"* at 13:22 — and **not disk-only**, because the direction you gave with it is +that packages will eventually be LLM-authored and stored as a resource rather than saved to disk. +And *[are documents in v1](DECISIONS.md#documents-answer)* — **all documents org-scoped for now**, a +seat's document being simply a resource under that seat on the org, with per-resource +configurability arriving later on **resource templates**, which do not exist yet. Both bind through +[ER-2](BUSINESS-RULES.md), and the ratify is unblocked. + +**The gate is met.** [ER-20 passed](#er-20-passed) on 2026-09-19 — three runs on the model path, +both controls red at their own legs. The inference key that was the whole of what it waited for +arrived when the project was pointed at the FSD environment. **Behind the gate, the wrap now waits +on two open children** — [FIX-1381](#the-sixth-child-pulled-in)'s spec, which is with you on +[#1935](https://github.com/fixpoint-labs/flow-state-dev/pull/1935), and +[FIX-1451](#the-seventh-child)'s fix on +[#1936](https://github.com/fixpoint-labs/flow-state-dev/pull/1936). Both are open, neither is +merged, and **W4 does not wrap until they are**. + +**Settled since the last refresh, and it was the epic that had it wrong:** **FIX-1451 is a child**, +parented deliberately and documented as such on the ticket ([above](#the-seventh-child)) — the +epic's standing note to clear it was mistaken, and no write was ever made on it. + +**Open with you, blocking nothing today:** a **[pending re-gate on +ER-14](DECISIONS.md#er-14-re-gate)** — you merged #1928 through the fence, which settles that PR but +says nothing about the rule; narrowing it reopens what you ratified as item 3 above, so only you can +do it. **With the epic:** FIX-1408's three remaining session-policy walls +([Open](DECISIONS.md#open)). diff --git a/spec/_epics/work-routing-package-cohesion/figures/end-state.svg b/spec/_epics/work-routing-package-cohesion/figures/end-state.svg new file mode 100644 index 0000000000..d1f6f1425f --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/figures/end-state.svg @@ -0,0 +1,78 @@ + + + + + + IN THE BOX — THE W4 FIRST CUT + + + THE EXIT GATE + channel / org board → seat runs · assign team seats + + + package format — one Markdown file, two modes + instructions + tools · not disk-only · documents org-scoped — ratify recorded + + + runtime inventory — two layers + declared roster, composed at read time · live org resource: membership · fan-out · DM + + + dispatch + session policy + parentSessionId at mint · history by opt-in tools — shipped, FIX-1408 + + A sub-agent is same-session background; a worker assign is a seat in a linked session. + + + + + COMPOSED IN BY THE APP + + custom kinds + flow factories under workforce/flows/ + + defaultWorker triage + who to assignTask to — composition + + + + + PHASE-2 — OFF THE GATE, HOLDS NO WRAP + + nested personal / request boards + the manager-queue lab's nested half + + + + + NOT BUILT + no Agent / Channel / Team / MessageBoard / TeamFlow / SessionBoard as an L1 type · no Collab RC as this epic + no silent parent transcript · no nested / child / shadow sessions as a work hierarchy + no merged board-assignee + seat registry · no team.* wildcards as first ship · no second WorkerRegistry + no mega-loader · no assignable-channel · no BoardFlow-as-only-mint · no Graft rebuild + + diff --git a/spec/_epics/work-routing-package-cohesion/figures/ownership.svg b/spec/_epics/work-routing-package-cohesion/figures/ownership.svg new file mode 100644 index 0000000000..b55f91f0d0 --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/figures/ownership.svg @@ -0,0 +1,95 @@ + + + + WHO OWNS WHAT — EVERY RULE HAS EXACTLY ONE OWNER + + + FIX-1385 + FIX-1394 + FIX-1405 + FIX-1408 + FIX-1430 + + + + ER-1 · the board is the work plane + BUILDS + + + + consumes + + + + ER-2 · the package format + + BUILDS + + + consumes + + + + ER-3 · inventory in two layers + consumes + + BUILDS + + + + + + ER-4 · the wire and the payload + consumes + consumes + + DECIDES + consumes + + + + ER-5 · assignee is not a seat + DECIDES + consumes + + + consumes + + + + ER-19 · the PR-5 name check + BUILDS + + + + + + + + + the one owner — decides or builds it + + consumes it, and must not re-decide it — not a wait + FIX-1430 consumes four rows and owns none of them — what makes it the proof. It owns ER-20, the done-condition. + Related, not in the set: FIX-817 and FIX-1415 also consume ER-3 from outside, and may not re-decide it. + + diff --git a/spec/_epics/work-routing-package-cohesion/figures/path.svg b/spec/_epics/work-routing-package-cohesion/figures/path.svg new file mode 100644 index 0000000000..402bada91c --- /dev/null +++ b/spec/_epics/work-routing-package-cohesion/figures/path.svg @@ -0,0 +1,127 @@ + + + + THE PATH — ONE LANE PER ISSUE, AGAINST TIME + + + + Sep 16 + now · Sep 19 + ahead · no dates set + + + + SHIP FENCE + + W3: FIX-1435 has no PR and is still Todo — four W4 ship PRs merged under the live fence, #1928 by the owner himself + + + + + + + + + + + + FIX-1377 TEAM.md · W3 + + landed on main · Sep 19 · #1911 + FIX-1416 tools fence · W3 + + landed on main · Sep 19 · #1909 + + + + FIX-1408 dispatch policy + + done by decision — no impl PR + FIX-1405 inventory + + + Done · #1920, #1923, #1928 all merged + FIX-1385 channel boards + + + Done · #1922 merged Sep 19 — one full-scope PR + FIX-1394 package cohesion + + + matrix #1921 — both forks decided, ratify recorded + FIX-1430 manager-queue lab + + + + ER-20 PASS ×3 + #1929 merged · gate passed · controls red + FIX-1381 seat resource ACL + + + spec PR #1935 open · in review · not approved + FIX-1451 allowed-tools · bug + + + fix PR #1936 open · a bug, so no spec + + + + + RELATED — NOT IN THE SET + FIX-817 catalog manifests + + consumes FIX-1405 · after its approved spec (ER-23) + FIX-1415 channel-admin + + consumes FIX-1405 · holds no wrap here + + + + + done / merged + + spec approved + + PR open + + W3 input + + not started + + gate passed + + + critical path to the proof + +