Skip to content
Merged
26 changes: 17 additions & 9 deletions specs/epics/FIX-2152/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,17 +56,18 @@ recorded here.*
> stays as the row below says.
>
> **What decides FIX-2159:** whether a public `exports` entry (ER-2) lets a flow take and acknowledge
> a settled notice, and answer again in the same request. On `main` none does: the take record
> (FIX-2123) and Workforce's handling are internal, and the agent flow's `afterAnswer` can't answer
> again. So FIX-2159 is narrowed to those two public pieces, a take-and-acknowledge for a settled
> notice and an answer-again hook. The take keeps the guarantees in the row below. The loop itself
> stays in the lab.
> a settled notice. On `main` none does: the take record (FIX-2123) and Workforce's handling are
> internal. So FIX-2159 adds the take, and it keeps the guarantees in the row below. It also
> extracts the answer-once-more step `Planning.planned` (FIX-2076) already runs into one shared
> step with one exported cap, and adds an `answerAgain` source slot on `defineAgentWorkerFlow`
> with no loop or cap of its own, so there is one way to answer again (#3799 review). The shared
> step runs the loop; the lab passes only the source block that calls the take.

| | |
|---|---|
| **Instead of** | The main session hearing the result only after its turn ends, which is what happens on `main` today: a settled notice waits for the reply (`AFTER_REPLY_CONCURRENCY`, `workforce/src/conversation-board/task-settled.ts`) |
| **Because** | Claude Code shows a background result inside the running turn, and the brief's script asks for it. A flow can already loop back to its generator within one request, so a small lab flow can take the result in at turn end |
| **Locks in** | *As amended above: FIX-2153's lab flow runs the loop; this row is the guarantee FIX-2159's public take keeps.* [ER-6](#who-owns-what), built by [FIX-2159](https://linear.app/fixpoint-labs/issue/FIX-2159): a delivery mode on FIX-2078's one ending path, not a second path, with one durable "taken in request R" mark like `steersTakenIn`; the deferred notice skips once R has completed. The take, the notice's handling and its acknowledgement move as one transaction from the queued `onTaskSettled` request to the running one, so the ending is never handled twice or skipped. Only a conversation request in a session that is not backed by a task takes it, never a `receive`. In a task-backed session the notice stays on the queued `onTaskSettled`, because that handler also does the task's own work at an ending (`admitOwnTask`, `workforce/src/conversation-board/task-settled.ts`) and acknowledging a taken notice would skip it (`orchestration/src/tasks/notice/task-settled-entry.ts` refuses a cleared notice). The lab flow takes the notice through FIX-2159's public take at its turn end; the steer entry (`steer-context.ts`) doesn't change and stays task-only. A request waiting on the task with `getTask` resumes with the result instead. Rules 5 and 6 (FIX-2077) are untouched: a take records no ending. No change in core or engine |
| **Locks in** | *As amended above: FIX-2159's shared answer-again step runs the loop under its cap, and FIX-2153's lab supplies only the `answerAgain` source block that calls the take; this row is the guarantee that take keeps.* [ER-6](#who-owns-what), built by [FIX-2159](https://linear.app/fixpoint-labs/issue/FIX-2159): a delivery mode on FIX-2078's one ending path, not a second path, with one durable "taken in request R" mark like `steersTakenIn`; the deferred notice skips once R has completed. The take, the notice's handling and its acknowledgement move as one transaction from the queued `onTaskSettled` request to the running one, so the ending is never handled twice or skipped. Only a conversation request in a session that is not backed by a task takes it, never a `receive`. In a task-backed session the notice stays on the queued `onTaskSettled`, because that handler also does the task's own work at an ending (`admitOwnTask`, `workforce/src/conversation-board/task-settled.ts`) and acknowledging a taken notice would skip it (`orchestration/src/tasks/notice/task-settled-entry.ts` refuses a cleared notice). The lab's `answerAgain` source block takes the notice through FIX-2159's public take (`takeFinishedTasks`) at its turn end; the steer entry (`steer-context.ts`) doesn't change and stays task-only. A request waiting on the task with `getTask` resumes with the result instead. Rules 5 and 6 (FIX-2077) are untouched: a take records no ending. No change in core or engine |
| **Amends** | Rule 7 of [`workforce-coordination-concept.md`](../../../docs/internal/design/workforce-coordination-concept.md) gains a third destination for an ending's notice: the filer's running request. It stays consistent with FIX-2103's call that an ending is not a message and changes no open work |

**What would change my mind:** a take that can't be made crash-safe the way `steersTakenIn` is.
Expand Down Expand Up @@ -115,7 +116,12 @@ It comes down to finishing the UI first: the adapter is the only file that chang

## Who owns what

![Who owns what: seven rules by FIX-2153, FIX-2157, FIX-2154, two gaps and the closure FIX-2156, each rule with one owner](figures/ownership.svg)
> **Amended 2026-10-23, after the merge of #3783.** ER-8 and ER-9 come from the owner, relayed by
Comment thread
jhoffner marked this conversation as resolved.
Resolved
> fsd-product-lead (agent-mailbox #46): a lab works where you point it, never in its own repository,
> and only delegated workers run on a coding harness. The rows are canonical. The lead measure grew
> to 18 with the steps the labs added for them.

![Who owns what: nine rules by FIX-2153, FIX-2157, FIX-2154, three gaps and the closure FIX-2156, each rule with one owner](figures/ownership.svg)

A *uses* cell is a place a child must not decide again. FIX-2153 owns the lab rules because it
goes first; the gap issues own their mechanisms.
Expand All @@ -127,15 +133,17 @@ goes first; the gap issues own their mechanisms.
| ER-3 | One way to set up a lab: under `labs/`, private, launched with `fsdev dev --app` as Shift Manager is; the theme from `@flow-state-dev/design-system` and components from the `packages/ui` registry (`fsdev ui add`). A lab defines no color tokens of its own. The two labs share no code: a piece both need that isn't UI is a package gap ([ER-4](#who-owns-what)), and a piece of UI both need is copied, so each inventory shows what that app adds. FIX-2157 is a mode of FIX-2153's app, not a third lab, so it shares that app's code | FIX-2153 | Every lab's spec review |
| ER-4 | Any need beyond ER-1's three kinds goes to the package: filed against workforce or orchestration (or react, for a hook), named in the lab's spec, and never worked around in the lab, not even for a while. A gap that blocks a script is a child of this epic ([D1](#d1)) | FIX-2153 | Every lab's spec review; the closure |
| ER-5 | Until wiring, a lab reads and writes through one adapter whose functions each name the package call they stand for, by post-refactor names ([D4](#d4)); a fixture carries a plain `fixture:` marker, and the README maps each to its gap (BP-006); at wiring the fixtures are deleted. FIX-2153's spec sets the adapter's layout (file names, one function per package call), and FIX-2154 copies the layout, not the code | FIX-2153 | Each lab's wiring PR; the closure |
| ER-6 | A settled notice reaches a filer's running request once, as [D2](#d2) locks in. FIX-2153's lab flow runs the loop and consumes the notice through FIX-2159's public take, so the queued `onTaskSettled` skips it | FIX-2153 (the loop), FIX-2159 (the public take and the answer-again hook) | FIX-2153's wiring; the closure's leg a |
| ER-6 | A settled notice reaches a filer's running request once, as [D2](#d2) locks in. FIX-2159's shared answer-again step runs the loop; FIX-2153's lab supplies the `answerAgain` source block, which consumes the notice through FIX-2159's public take, so the queued `onTaskSettled` skips it | FIX-2153 (the source block), FIX-2159 (the take and the shared step) | FIX-2153's wiring; the closure's leg a |
| ER-7 | A lab session is an ordinary session of the worker on its flow; a person lists only their own, through the workforce client; the derived session stays the default conversation, where messages and routed tasks land ([D3](#d3)) | FIX-2158 | FIX-2153's wiring; the closure's legs a and c |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
| ER-8 | Every run a lab starts works in a **project's** checkout, never the lab's own and never a scratch directory. A session or worker holds its project, and tasks it files inherit it through `filingProjectId`, which `projectWorkspace()` reads. When a job needs a project and none is set, the lab's screen asks before anything runs; `projectWorkspace()`'s `no-project` refusal is only the backstop. Each lab's spec says when it asks: FIX-2153 and FIX-2157 at New session, FIX-2154 (talk-first) at the first job that touches files. A raw path outside any project is not offered. [FIX-2161](https://linear.app/fixpoint-labs/issue/FIX-2161) lets an ordinary session, or a worker's default conversation, carry a project, set from the screen and stored on the server, never read from lab config | FIX-2153 | Every lab's spec review; each lab's wiring; the closure |
| ER-9 | Only delegated workers run on a coding harness (Claude Code or Codex); a main session stays on the lab's generator, because its loop owns the turn ([D2](#d2)). The harness path is the one `harness-manager` already gives, as DevTeam's `coder` flow uses it, and no new mechanism. A lab has **one** coding worker flow, whatever the number of harnesses: it builds one `harnessManager` per harness (the slot is fixed when a manager is built) and routes each task by the worker's own `harness` setting, a key in its `WORKER.md` that the hire passes to the flow as settings, as DevTeam's `coder` routes by task and reads its worker's settings. So a harness is chosen in config and the flow count stays flat as harnesses are added. If that flow can't stay under ER-1's 200 lines, FIX-2153's spec raises the cap once and says why; a harness flow is never left out of the count. A harness run shows as an ordinary task row, tagged from the worker's `harness` setting; the task row gains no field | FIX-2153 | Every lab's spec review; the closure |

## Coordination seams

| Seam | Owner, then who else touches it |
|---|---|
| The workforce client (`workforce/src/workers/client.ts`) | FIX-2158 adds the list of a person's sessions of one worker; FIX-2153 and FIX-2157 call it through their adapters |
| The settled notice (`workforce/src/conversation-board/task-settled.ts`, its deferred entry) and the agent flow's turn (`defineAgentWorkerFlow`) | FIX-2159 adds a public take-and-acknowledge for a settled notice and an answer-again hook; FIX-2153's lab flow runs the loop at turn end and shows the result in the main thread |
| The settled notice (`workforce/src/conversation-board/task-settled.ts`, its deferred entry) and the answer-once-more step `Planning.planned` runs (FIX-2076) | FIX-2159 adds a public take-and-acknowledge for a settled notice and shares that step under one cap; FIX-2153's lab passes the `answerAgain` source block and shows the result in the main thread |
| Messages (`workforce/src/messages/`, the user-scoped `workerMessagesCollection`) | FIX-2070 owns the rename to `sendMessage` and `receive`, where a message lands, and the row it ships (call ids, `{ task }` addresses). FIX-2154 is blocked by FIX-2070 and keys its worker-talk view to that row; a pair filter is UI, and a gap is filed only if paging by pair needs a server index |
| Routed tasks, task statuses and the hold on questions (`workforce/src/coordinator/`, FIX-2058's hold and `waitForUser`) | FIX-2083 and FIX-2058 own them. FIX-2157's status board reads them and adds no status of its own; a column the statuses can't fill is a gap |
| The app's mode switch (FIX-2153's host and UI) | FIX-2153 plans for it in its spec; FIX-2157 adds threads mode behind it |
Expand Down
26 changes: 16 additions & 10 deletions specs/epics/FIX-2152/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ flowchart LR
| **Anti-game** | Assert on what a person sees in the browser, and on task rows read through public task actions. Never on a lab's own state. Leg a also asserts each ending is heard once: no second notice turn answers a result the running turn already took |
| **Control that must fail** | Leg a with the lab flow's loop-back off ([D2](DECISIONS.md#d2)): step 4 lands after the turn. Leg b with B's `sendMessage` dropped from its tools: A never hears B. Leg c with the main worker's delegates removed: no thread starts |

**Lead measure:** scripted steps that pass on `main` with a real model, of 14 (5, 5 and 4). **0 today.**
**Lead measure:** scripted steps that pass on `main` with a real model, of 18 (7, 6 and 5). **0 today.**

## What's in the box

Expand All @@ -70,11 +70,13 @@ The reviewed snapshot; live state is in Linear.
| [FIX-2157](https://linear.app/fixpoint-labs/issue/FIX-2157) · Claude Code-style lab, threads mode | A second mode of FIX-2153's app: the main session hands everything to background threads, and the right pane is a status board. Spec after FIX-2153's | FIX-2153; FIX-2056 and FIX-2058 (wiring only) |
| [FIX-2154](https://linear.app/fixpoint-labs/issue/FIX-2154) · Grok Bot-style lab | The same, second. Rides worker messaging (FIX-1989), written against FIX-2070's names | FIX-2056 (wiring only); FIX-2070, whose message row its worker-talk view reads; the gaps it files |
| [FIX-2158](https://linear.app/fixpoint-labs/issue/FIX-2158) · list a person's sessions of one worker | A list on the workforce client, and the concept line that the derived conversation is the default, not the only one ([D3](DECISIONS.md#d3)) | — |
| [FIX-2159](https://linear.app/fixpoint-labs/issue/FIX-2159) · a result reaches a running turn | Two public pieces for FIX-2153's lab flow: a take-and-acknowledge for a settled notice on the one ending path, and an answer-again hook. The loop itself stays in the lab ([D2](DECISIONS.md#d2), amended) | — |
| [FIX-2159](https://linear.app/fixpoint-labs/issue/FIX-2159) · a result reaches a running turn | A take-and-acknowledge for a settled notice on the one ending path, and an `answerAgain` source slot on `defineAgentWorkerFlow`. The answer-once-more step `Planning.planned` already runs becomes one shared step with one exported cap, and it runs the loop; FIX-2153's lab passes only the source block that calls the take ([D2](DECISIONS.md#d2), amended; [ER-6](DECISIONS.md#who-owns-what)) | — |
| [FIX-2161](https://linear.app/fixpoint-labs/issue/FIX-2161) · a session opens on a project | An ordinary session of any worker can open on a project the person may work in (a member of a shared project or the owner of a private one; reading isn't enough, since `projectWorkspace()` refuses a reader), and a worker's default conversation can carry a project, a server-written field the screen sets through a client call and never lab config (BP-031), checked as the roster owner, the person whose worker it is, so a lab's runs work in that project's checkout ([ER-8](DECISIONS.md#who-owns-what)). Today only the project coordinator's session can | — |
| [FIX-2156](https://linear.app/fixpoint-labs/issue/FIX-2156) · closure · **required** | The QA plan, run on one `main` commit | every other child |

Two labs, one with two modes, two gaps known before review, and a closure. fsd-architect checked
both gaps against `main` and agreed their shape; each lab's spec may add more.
Two labs, one with two modes, three gaps, and a closure. fsd-architect checked the first two
Comment thread
jhoffner marked this conversation as resolved.
Resolved
against `main` and agreed their shape. FIX-2161 came from FIX-2153's spec, when the working directory
was added ([ER-8](DECISIONS.md#who-owns-what)). Each lab's spec may add more.

## How the issues flow into each other

Expand All @@ -85,7 +87,10 @@ flowchart LR
N["FIX-2070 · Messages · consumed"] -.-> B
G1["FIX-2158 · list a person's sessions of one worker"] -->|"the session list"| A["FIX-2153 · Claude Code-style lab"]
G1 -->|"the session list"| T
G2["FIX-2159 · a flow can take a settled notice and answer again"] -->|"the public take for step 4's lab flow"| A
G2["FIX-2159 · a flow can take a settled notice"] -->|"the public take for step 4's lab flow"| A
G3["FIX-2161 · a session opens on a project"] -->|"the session's project"| A
G3 -->|"the session's project"| T
G3 -->|"each worker's project"| B
I["FIX-2058 · one Inbox · consumed"] -.-> T
A -->|"the app, its mode switch and its task reads"| T["FIX-2157 · threads mode"]
A -->|"the inventory check and the setup pattern"| B["FIX-2154 · Grok Bot-style lab"]
Expand Down Expand Up @@ -124,21 +129,22 @@ code.
| `messageWorker` and `onWorkerMessage` (FIX-1989); `sendMessage` and `receive` (FIX-2070, planned) | **Builds on.** FIX-2154 is written against FIX-2070's names |
| The agent flow's planned turn (`board.planned`), where one worker does work and files work | **Builds on.** The main session that works and delegates |
| A worker's sessions: the derived default conversation, and any other session on its flow, which the create check already accepts (`workforce/src/workers/installation.ts`) | **Extended** by FIX-2158's list. Workstreams (FIX-1883, opened by `openWorkstream` or a coordinator) are not used: they need a project and a lead ([D3](DECISIONS.md#d3)) |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
| `@flow-state-dev/harness-manager`'s `harnessManager`, with a harness slot, and `projectWorkspace()`, which runs a task in its session's project (DevTeam's `coder` flow) | **Builds on.** Delegated workers on Claude Code or Codex, one lab flow that routes to a manager per harness, working in the session's project ([ER-8, ER-9](DECISIONS.md#who-owns-what)) |
| `@flow-state-dev/design-system` and the `packages/ui` registry | **Builds on.** The labs' only theme and components |

| The debt | |
|---|---|
| **Adds** | Two private labs under `labs/` · one list call on the workforce client · a public take and an answer-again hook on the ending path (D2) |
| **Adds** | Two private labs under `labs/` · one list call on the workforce client · a public take on the ending path and an `answerAgain` source slot on `defineAgentWorkerFlow`, with `Planning.planned`'s answer-once-more step extracted as one shared step under one exported cap (D2) · an ordinary session that opens on a project (FIX-2161) |
| **Removes** | Nothing |

**Net: up, by two labs and two package entries.** The labs are the evidence the epic exists to
**Net: up, by two labs and four package entries.** The labs are the evidence the epic exists to
produce. Each package entry is a gap the labs proved, and the next app gets it for nothing.

## Sign off

**[The goal](#the-goal-and-how-well-know-its-met):** three scripts, 14 steps, with a real model,
**[The goal](#the-goal-and-how-well-know-its-met):** three scripts, 18 steps, with a real model,
and an inventory with no *other* row. **[The debt](#whats-already-here-and-the-debt):** up, by
two labs and two package entries.
two labs and four package entries.

1. **[D1](DECISIONS.md#d1) · A gap that blocks a lab's script is a child of this epic and is
built here.** If wrong: the epic grows by package work that another epic should own.
Expand All @@ -153,5 +159,5 @@ two labs and two package entries.
and the merge of this PR approves it. Session-to-session messaging (FIX-2160) is filed outside
this epic for the owner to place.

Epic · 2 labs (one in two modes), 2 known gaps and a closure · Workforce: Shift Manager · Goal 1, validate through
Epic · 2 labs (one in two modes), 3 known gaps and a closure · Workforce: Shift Manager · Goal 1, validate through
real usage · Goal 4, keep the foundation honest
Loading
Loading