Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions specs/issues/FIX-1875/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# FIX-1875 · Business rules

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md)

The cases, written as rules. Each says what a person or the system does and what happens. The
*proved by* column is the check the plan runs. "The board" means a conversation's board unless a
row says otherwise. Epic rules this issue owns are ER-1 to ER-4; every row below serves one.

## Recording work

| # | When | Then | Proved by |
|---|---|---|---|
| BR-1 | `addTask` (tool or action) records a row with an assignee | The row is pending and not dispatched. No run, no task session, however often the board is touched | CI · goal `rec:not-started` |
| BR-2 | `addTask` records a row with no assignee, in a conversation with one delegate | It is given that delegate, as today, and is still not dispatched | CI |
| BR-3 | `assignTask` names a new owner for a recorded row | The owner changes; the row stays recorded | CI |
| BR-4 | `assignTask` moves a row that was already dispatched and not yet claimed | It moves and starts, as today: the dispatch already happened | CI |
| BR-5 | A row filed before this change has an assignee and no mark | It starts as it does today (BP-030) | CI, a row written in the old shape |
| BR-6 | Flow code writes the board directly | Today's behaviour: an assigned row starts | Existing suite |
| BR-7 | `addTask` runs on a board a drain runs (`taskBoard()`, a pattern) | Exactly as today. No mark, no `dispatchTask` in the tool list | Existing suite |

## Dispatching work

| # | When | Then | Proved by |
|---|---|---|---|
| BR-8 | `dispatchTask({ goal, … })` | A row is filed ready and the board starts it now. The call returns its id at once | CI · goal `disp:new-runs` |
| BR-9 | `dispatchTask({ taskId })` names a recorded row | The mark clears and the row starts. With `assignee`, the owner is set in the same write | CI · goal `disp:ref-runs` |
| BR-10 | `dispatchTask({ taskId })` names a row that is claimed, running, ended, or already dispatched | Refused, naming its state. Nothing changes | CI |
| BR-11 | `dispatchTask({ taskId })` names a row not on the caller's own board | `task_not_found`. Nothing changes | CI · goal `lineage:refused` |
| BR-12 | More than one of `goal`, `taskId` and `post`, or none | Refused before anything is written | CI |
| BR-13 | `taskId` with a field that only a new row takes (`deps`, `input`, `followUpOf`, …) | Refused before anything is written. To change a recorded row, `updateTask` first | CI |
| BR-14 | Every check `addTask` runs (assignee on the roster, follow-up rules, chain depth and breadth, caps) | `dispatchTask` runs the same checks, in the same order, with the same errors | CI, one test per check |
| BR-15 | The same `dispatchTask` call replays after a crash or a resume | One row, one start. For `taskId` too: the ready write records the call that made it, so a replay finds its own write and answers as the first call did, not with BR-10's refusal | CI, a crash between the ready write and the step's record · the FIX-1820 rerun |
| BR-24 | `dispatchTask` with no `assignee`, where the conversation has no single delegate to default to (or a `taskId` row that has no owner) | Refused, `assignee_required`, nothing written. It never reports a start the board can't make | CI |
| BR-25 | `assignTask` and a `dispatchTask({ taskId })` race on the same recorded row | Both writes are conditional, so they apply one after the other: the later write's owner stands, and the row starts once | CI, the two writes interleaved both ways |
| BR-26 | `post: true`, on a coordinator turn that is routing a post | The routed post is the task, filled from the server; only `assignee` and `target` are taken. `post: true` is the only discriminator; the call carries no `goal` (with one, BR-12 refuses it). Off such a turn, `post` isn't in the schema. FIX-1872 builds it; this issue keeps the schema open to it | FIX-1872's checks |

## Waiting for the result

| # | When | Then | Proved by |
|---|---|---|---|
| BR-16 | `dispatchTask({ …, wait: true })` | Today's ask, unchanged: one row per call, one wait per step, the turn parks, the row's output is the result, or an error naming how it ended (`wait_*`) | The FIX-1816 rerun · existing ask suite, renamed |
| BR-17 | `wait` on a recorded row (`taskId`) that is pending, unclaimed and not waited on | It is marked waited-on and dispatched in one write, then the turn parks as in BR-16 | CI |
| BR-18 | `wait` where the host or board can't hold one, or from a task turn | `wait` and `timeoutMs` aren't in the schema; a direct caller that sends them anyway gets `wait_unavailable`, nothing written. The refusal reads the call's input before the schema would strip an unknown field | CI, a direct call with `wait: true` |
| BR-19 | `timeoutMs` without `wait`, or outside 30 seconds to an hour | Refused, nothing written, never clamped | CI |
| BR-20 | The `dispatchTask_<board>` action | Never waits; it has no `wait` field | CI |

## The old surface

| # | When | Then | Proved by |
|---|---|---|---|
| BR-21 | `addTask` gets `waitForResponse` or `timeoutMs` | Refused by name, the message points at `dispatchTask`, nothing filed. Read before the schema would strip it, as in BR-18 | CI (V6) · the epic closure's sweep |
| BR-22 | Code imports a retired name | It fails to compile. The changeset gives each new name | Typecheck · the sweep's `--assert` |
| BR-23 | The model reads `addTask`'s description | It says `addTask` records and doesn't start, and points at `dispatchTask` | CI on the description · the FIX-1816 rerun |
| BR-27 | `addTask` (tool or action) records a row on a board that dispatches | Its result carries `status: "recorded"` and a one-line note that the task starts on `dispatchTask`. A model that skipped the description, or a script that logs the result, sees it | CI on the result |

```mermaid
flowchart LR
A["addTask · assignTask"] -->|"recorded · not dispatched"| R["the row"]
D["dispatchTask"] -->|"ready"| R
O["a row filed before this"] -->|"no mark · ready"| R
R -->|"the board's one test · ready rows only"| S["start"]
```

Every path into a row ends at one test for "can start". A second test anywhere (a claim's
eligibility, the drain's exit, `addTask`'s own wake, the `setAssignee` and `unpark` wakes) that
doesn't read the mark starts a recorded row.

## Failure taxonomy

Every refusal is a soft `{ ok: false, error }` the model can act on, written before anything is
stored. A failed wake leaves a ready row ready, for the next touch, as today. Nothing retries
inside the tool. A wait that ends without an answer is today's `wait_*` set, unchanged.

## Acceptance criteria this issue owns

[The goal](SPEC.md#the-goal-and-how-well-know-its-met): its check passes on the FIX-1817 lab
after `GOAL_CONTROL=add-starts` and today's `main` fail it; the three regression checks pass with
diffs the rename map explains; and the sweep's `--assert` exits 0.
126 changes: 126 additions & 0 deletions specs/issues/FIX-1875/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# FIX-1875 · Decisions

[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md)

What was considered, what was chosen, why, and what each choice locks in. Two decisions are the
sign-off surface. The epic already decided the tool exists, that waiting moves onto it, and that
the board tools only record ([FIX-1870 D1](../../epics/FIX-1870/DECISIONS.md#d1), ER-1 to ER-4);
these two are what that costs on the real code.

## The tree

```mermaid
flowchart TD
I["FIX-1875"] --> D1["D1 · a recorded task doesn't start until dispatched"]
D1 -.->|"rejected · two tools still start work"| X1["addTask keeps starting work on a conversation's board"]
I --> D2["D2 · addTask's fields plus wait, flat · goal, taskId or post"]
D2 -.->|"rejected · every changed call stops being a rename"| X2["a nested task new-or-ref envelope"]
```

Solid edges are what you're signing. Dashed edges lost, and the label says why.

<a name="d1"></a>
## D1 · On a conversation's board, `addTask` and `assignTask` stop starting work; a recorded task doesn't start until `dispatchTask`

| | |
|---|---|
| **Instead of** | Keeping today's start: on a conversation's board, a row with an assignee starts at once, so `dispatchTask` without `wait` is a second name for `addTask` with an assignee |
| **Because** | A conversation's board starts every row that is pending and assigned, on any touch ([`board.ts`](../../../packages/workforce/src/conversation-board/board.ts), the guarded `addTask` and the resolver's wake). So "the board decides when it runs" is false there unless a row can be recorded *without* being ready. Without that, two tools start work, and the model still has to pick: the problem the epic exists to remove (tenet 2: one primitive per job). Every other board is drained by its owner and already only records |
| **Locks in** | A recorded row carries a persisted mark, *not dispatched* (`undispatched`, never "waiting": FIX-1876 keeps *wait* for a turn parked on a task), written only by the task tools and actions on a board that dispatches. A row without the mark (every row filed before this) still starts as today. Code that writes the board directly is untouched. `addTask`'s result says `status: "recorded"`, so the change is visible on the first call, not only in the changeset. Every caller that relied on `addTask` or `assignTask` starting work moves to `dispatchTask` in this issue: the [sweep](PLAN.md#the-sketch-and-the-poc) lists 14 goal checks (26 files, plus 3 shared lab helpers), 3 worker files, 2 published pages and the workforce README. An app that sends `addTask_tasks` to start work must switch, and the changeset says so |

![D1: what addTask does on a conversation's board. Chosen: record only, and dispatchTask starts. Instead of: addTask keeps starting work. It comes down to the first row: with start-on-assign kept, two tools start work and the model still picks. Second row, the price: 14 goal checks, three worker files and an app's addTask_tasks calls move to dispatchTask, where keeping it costs nothing. Third row, a tie: what a started task does is the same either way. Locks in a persisted not-dispatched mark that old rows don't carry. Flips if a regression check can't stay a rename](figures/d1-recorded-waits.svg)

It comes down to the tool choice: keep start-on-assign and the model still picks between two tools.

**What would change my mind:** one of the three regression checks can't pass with a rename-only
diff once `addTask` stops starting work. That is the epic's kill line, and it goes back to the
epic (ER-14).

<a name="d2"></a>
## D2 · `dispatchTask` takes `addTask`'s fields plus `wait` and `timeoutMs`, flat, with `taskId` for a recorded row and `post: true` for a routed post

| | |
|---|---|
| **Instead of** | The issue's sketch: `dispatchTask({ task: { new } \| { ref }, to, wait: true \| { timeoutMs } })`. For FIX-1872's post form, also instead of a second tool, or a routing turn that can only post |
| **Because** | The epic's proof is that the three regression checks change only by a rename map ([ER-11](../../epics/FIX-1870/BUSINESS-RULES.md#what-no-child-may-do)). With a flat shape, `addTask_tasks` → `dispatchTask_tasks` and `waitForResponse` → `wait` are the whole map. A nested envelope rewrites every call, so no changed line is a rename, and a reviewer can't tell a reshaped call from a changed assertion. A flat object is also what a model fills most reliably, and what OpenAI strict mode accepts without a union (BP-016) |
| **Locks in** | A public tool and action shape. Exactly one of three says what starts, checked when the call runs, not by the schema: `goal` (a new row, in the caller's words), `taskId` (a recorded row), or `post: true` (the post a coordinator turn is routing, filled from the server). The model tells the forms apart by which one it sets, the same rule for all three. `post: true` is the single discriminator for the post form, never a missing `goal`: the routed post is the task, so a post-form call carries no `goal`, and `goal` with `post` is refused (BR-12). That reserves the post form for FIX-1872 without overloading `goal`'s absence, which `taskId` already uses. `post` and `target` are in the schema only on a coordinator turn that is routing a post; with `post`, only `assignee` and `target` are taken. The recipient is `assignee` in every form, with its default (the conversation's only delegate), so FIX-1872's `to` reads as `assignee`. FIX-1872 builds the post form; this issue leaves the schema open to it. A second tool was rejected because two starting tools is what the epic removes; a post-only routing turn because FIX-1872 D2 keeps a coordinator able to file an ordinary task on that turn |

![D2: the shape of dispatchTask's input. Chosen: addTask's fields plus wait, flat. Instead of: a nested task envelope with new or ref. It comes down to the first row: with the flat shape the regression checks change only by a rename map, while the envelope rewrites every call. Second row, the price: goal, taskId or post is a run-time rule, not a schema rule. Third row, a tie: both can carry FIX-1872's post form, with post and target. Locks in a public shape. Flips if a second kind of reference needs fields of its own](figures/d2-flat-shape.svg)

It comes down to the proof: a flat shape keeps the regression diffs a rename map; the envelope
rewrites every call.

## Decided, not asked

- **`dispatchTask` is offered only on a board that can start work now** (a conversation's board
today). A drained board has nothing to start a row with, so the tool would lie there.
- **`wait` is offered exactly where `waitForResponse` was:** a board that resumes waits, on a host
that can hold and bound one. Elsewhere the fields are absent from the schema, as today.
- **The action form never waits**, as the `addTask_<board>` action never did.
- **`waitForResponse` and `timeoutMs` on `addTask` are refused by name**, with a message naming
`dispatchTask`, never stripped by the schema (BP-030). A silent strip would file the task and
return at once to a model that thinks it waited.
- **Waiting on a recorded row is allowed** when the row is pending, unclaimed and not already
waited on. The mark and the wait are written in one write.
- **A recorded row is reachable only on the caller's own board.** The board resolver already
reads the running session's own partition, so a row elsewhere is `task_not_found` (ER-4 holds by
construction; the goal check's `lineage:refused` proves it).
- **The public ask names go with no alias** ([pinned map](PLAN.md#pinned-names)): the closure

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This bullet says host seam names are FIX-1876’s, but the pinned map still retires canHoldAsk and ask-prefixed errors/constants in this issue. Worth reconciling so reviewers aren’t left guessing whether P2 removes those symbols or only renames them in docs.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Same fold as the PLAN thread (95f5663): the bullet now states the boundary explicitly, exported names here, internal seam in FIX-1876.

fails while a retired name is exported, and the packages are pre-1.0. **Where the line falls
with FIX-1876:** this issue renames every exported name a caller of the waiting surface imports
(the map, `canHoldAsk` and the `Ask*Error`s included). The host seam's names (`resumeAsk`,
`hasAskSweeper`, `parkOnAsk`, `resumesAsks`, `row.ask`) are not imported by callers and stay for
FIX-1876, which starts after this merges and keeps what this renamed (its WR-22). Where both
maps name a symbol they agree (`AskEndedError` → `WaitEndedError`).
- **`assignTask` on a recorded row keeps it recorded.** `answerTask` still re-queues a row that
was already started, as today: that row was dispatched once.
- **`dispatchTask` refuses a row with no owner.** With no `assignee` and no single delegate to
default to, it answers `assignee_required` and writes nothing, so it never reports a start the
board can't make (BR-24).
- **`onTimeout: "continue"` is not built** (the epic dropped it: new behaviour no rerun proves).
- **The coordinator's `handOff` is left alone.** FIX-1872 retires it with the ledger
([EM call](https://linear.app/fixpoint-labs/issue/FIX-1875), 2026-10-12).
- **The issue's open questions** — rows per delegate on the everyone policy, and whether `to` may
be a coordinator — are FIX-1872's ([epic D2](../../epics/FIX-1870/DECISIONS.md#d2)) and the
roster's: `assignee` is checked against the board's roster, unchanged.

## Which methods already do this job

The job: *start work on another worker now, optionally waiting for it.* Searched `packages/` for
`addTask`, `assignTask`, `handOff`, `createHandOff`, `dispatcher`, `waitForResponse`, `park`,
`resume`, `wake`:

| Entry | Does the job how | After this issue |
|---|---|---|
| `addTask` with an assignee, on a conversation's board | Records, and the board's wake starts it | Records only (D1) |
| `assignTask`, on a conversation's board | Moves, and the wake starts it | Records only (D1) |
| `addTask({ waitForResponse })` / `addTaskAndWait` | Records, starts, parks the turn | **Closest entry.** Becomes `dispatchTask({ wait })`; differs only by a flag, so it is that parameter (D2) |
| The coordinator's `handOff` tool | Delivers a post through the delivery ledger | FIX-1872 |
| `createHandOff` (a `taskBoard()` worker) | A drain hands a claimed row to another session | Unchanged: the drain's own start, not a model tool |
| `dispatcher()` | Flow-code transport, no row | Unchanged ([ER-12](../../epics/FIX-1870/BUSINESS-RULES.md#what-no-child-may-do)) |

## Considered and dropped

| Alternative | Why not |
|---|---|
| A new conversation-board scheduler that starts recorded rows later by itself | Nothing needs it. "Later" today means a person or a worker deciding, which is a dispatch |
| Mark ready rows instead of waiting ones | Every row filed before this lacks the mark and would stop starting on upgrade. Marking the waiting ones leaves old rows as they are (BP-030) |
| Hold rows in `addTask` at the ledger, not in the tools | Flow code that writes the ledger directly (DevTeam's EM row filing) would stop starting work, a change ER-2 doesn't ask for |
| A wrapper tool over `addTask` | The implementer note from the epic review: build dispatch into the task tools and the board, so there is one filing path |
| Alias the old names for a release | The closure's sweep fails while one is exported; pre-1.0 patch notes carry the map instead |
| Use the existing `blocked` status for a recorded row, so no new field | `blocked` means a row can't proceed: its reason is stored in `error`, it emits a `blocked` change event, and it returns to pending only through `unblock`. A recorded row is healthy and ready to go on request, so an app reading `blocked` would show it as stuck |
| Drop `taskId`: "record for later" is an unassigned `addTask`, and `dispatchTask({ goal })` is the only start | Once `assignTask` stops starting work, a recorded row has no way to start except by id; the only other move files a duplicate and orphans the original. The DevTool's row actions also work on an existing row (`works-a-task-from-its-row`) |

## How it got here

- **Draft** — framed as the epic's substance: one starting tool, and board tools that only
record. Found that a conversation's board starts any assigned row, so ER-2 needs a persisted
waiting-for-dispatch mark (D1), and that the regression proof needs a flat input shape (D2).
Built as two PRs: the tool and the callers' move, then the switch-off.
- **Review round 1** — the mark is `undispatched`, not `awaitingDispatch`, because FIX-1876
makes *wait* mean only a parked turn and a stored name is costly to change later. D2 gained
the post form, because FIX-1872 gives `dispatchTask` a second meaning on routing turns and the
two specs drew it differently. Every start test now reads the mark in P1, before anything writes
it in P2, because a rolling deploy would otherwise run P1 processes that start a P2 recorded row.

**Open: none.**
Loading
Loading