Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
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
Prev Previous commit
Next Next commit
spec(FIX-1430): round 1 — routing claim gets an oracle, BR-6 goes obs…
…ervational

Folds spec-level findings from Cursor, Greptile and Codex.

- BR-4's negative control could not fail: it mutated the caller-supplied
  assignee-to-seat map, which PLAN declared the sole authority, so repointing
  it moved the correct destination along with the routing. The expected
  association is now held out in the tree (each worker seat's file names the
  assignee it answers for) while the host's map stays the implementation
  under test, and VG states the red state it produces.

- BR-6 required a busy seat's second row to read `pending`. A hand-off claims
  a row before its child starts and leaves it `in_progress`
  (docs/architecture/dispatched-work.md, "The claim gate and the fence
  ticket"), so that reading is not guaranteed — and requiring it also settled
  the busy-seat policy D3 says this lab must only show. BR-6 now requires what
  holds at every drain width (nothing re-routes, nothing drops, the assignee
  is held) and records the status instead.

- D3 dissolved: "shown, not chosen" means the lab is wired to run at either
  width from one switch, not that this issue's CI runs the queue twice. S8/V5
  come off the merge bar; the two-width comparison lands when the epic asks.

- PLAN pins assignee `eligibility` on every drain's claim. ClaimOptions
  narrows candidates before the CAS flip; omit it and a drain claims a row
  addressed to another seat, keyedRouter misses, and recordError settles the
  row `errored`.

- Queued is the substrate's admission predicate, not `pending` alone, so an
  in_progress row with a lapsed lease is no longer in no column at all. The
  claim gate refuses adoption past the lease, so queued is where it belongs.
  Figure and alt text redrawn to match.

- A missing tool grant is not hire-fatal: `tools:` grants use, so a seat that
  omits it hires cleanly and fails at filing. Taxonomy corrected, BR-2 kept.

- The diff gate now rejects goals/devforce-lab/ — a behavioural suite cannot
  prove a tree unchanged.

Q1 stays open and stays the owner's. The narrow shape it would pick is now a
hard requirement of the plan so the gate cannot widen while it is open.

Two SPEC-layout findings refuted and left open: spec-template.md governs a
spec document's headings, and writing-for-humans.md exempts structural
navigation from "nothing precedes the problem".

Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
  • Loading branch information
claude committed Sep 19, 2026
commit 50af21c04d8da495cbbae535a474cafcdf3deea8
29 changes: 10 additions & 19 deletions spec/FIX-1430/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ The cases as rules: what someone does, what happens, and which check proves it.

| # | When | Then | Proved by |
|---|---|---|---|
| BR-4 | The coordinator files four rows across three named assignees | Each row runs on the seat that assignee addresses, and on no other. **Negative control:** re-point one assignee at a different declared seat and watch this go red | Goal check |
| BR-4 | The coordinator files four rows across three named assignees | Each row runs on the seat that assignee addresses, and on no other. The expected assignee-to-seat association is held out **in the tree** — each worker seat's own file names the assignee it answers for — and never read from the host's map, which is the routing implementation under test. **Negative control:** re-point one assignee in the host's map at a different declared seat. The tree still says where the row should have gone, the run says where it went, and the two now disagree: the row is observed on a seat whose own file claims a different assignee, and BR-4 goes red | Goal check |
| BR-5 | A row runs | It runs in its own session, whose parent is the session the row was filed from. Nothing carries the coordinator's transcript with it | Goal check · read off the session record |
| BR-6 | Two rows name the same assignee | The second stays `pending`, still holding that assignee, and runs when the seat frees. Nothing re-routes it to a free seat and nothing drops it | Goal check |
| BR-6 | Two rows name the same assignee, and there is no free seat for the second | Neither row is re-routed and neither is dropped: both are observed reaching the seat their assignee names, and the second runs once that seat frees. **What the waiting row's status reads is recorded, not required** — a hand-off claims a row before its child starts and leaves it `in_progress` (`docs/architecture/dispatched-work.md` -> "The claim gate and the fence ticket"), so `pending` is not the only honest reading of a row that is waiting. Which reading each drain width produces is [D3](DECISIONS.md#d3)'s comparison, not this issue's assertion | Goal check · the status recorded per run |
| BR-7 | A row is filed naming no assignee | Refused by name where it would have run. The lab declares no default worker, so a row for nobody is loud rather than quiet | Goal check · asserted on the refusal |
| BR-8 | Someone who is not a member of the channel files a row | Refused with the channel's own author-not-a-member reason, in the same words a refused post gets | Contract gate |
| BR-9 | The coordinator settles a row it never claimed | Allowed, exactly as the task tools allow it today. Recorded as observed behaviour rather than defended as a design | Contract gate |
Expand All @@ -27,36 +27,27 @@ The cases as rules: what someone does, what happens, and which check proves it.

| # | When | Then | Proved by |
|---|---|---|---|
| BR-10 | The queue is read | Four columns — queued, running, waiting on you, done — each a grouping of rows that already exist. No field is written to produce one | Contract gate · the ledger compared before and after a read |
| BR-11 | A seat holds a live claim | It reads busy; a seat holding none reads idle. Idle is the absence of a claim, never a stamp somebody writes | Contract gate |
| BR-10 | The queue is read | Four columns — queued, running, waiting on you, done — each a grouping of rows that already exist. No field is written to produce one. **Queued is the substrate's own admission predicate, not `pending` alone:** a row whose worker died — `in_progress` with a lapsed lease — is claimable, so it reads queued, because the next drain is what takes it back (`isClaimable`, `packages/orchestration/src/tasks/collection/internal.ts`). Every row lands in exactly one column; a row in none of them is a bug in the view | Contract gate · the ledger compared before and after a read, and a lapsed-lease row asserted into queued |
| BR-11 | A seat holds a live claim | It reads busy; a seat holding none reads idle. Idle is the absence of a claim, never a stamp somebody writes. **A seat whose claimed row has a lapsed lease reads idle, and that row reads queued** — nobody is on it, and nobody can quietly resume it either: the claim gate refuses an adoption once the lease has lapsed (`StaleTaskClaimError`), so the row is genuinely back in the queue rather than in flight | Contract gate |
| BR-12 | A row is parked or blocked | It appears under *waiting on you*, carrying the reason already on the row | Contract gate |
| BR-13 | The queue is read at any moment | The task status set has exactly the members it had before this issue | CI · asserted on the enum, not on a reading of it |

![A matrix of four queue columns against the row facts each is computed from. Queued reads status pending and the assignee. Running reads status in progress and a live claim. Waiting on you reads status parked or blocked and the reason already on the row. Done reads the terminal statuses. A fifth strip beneath shows seat idle derived from the absence of a live claim against the seats the lab hired. A heavy fence runs under the whole matrix, labelled nothing below this line is written, with the task status enum and the row fields drawn underneath it untouched.](figures/the-view.svg)
![A matrix of four queue columns against the row facts each is computed from. Queued reads the rows the claim path would admit — status pending, or in progress with a lapsed lease, which is a row whose worker died — grouped by assignee. Running reads status in progress and a live claim. Waiting on you reads status parked or blocked and the reason already on the row. Done reads the terminal statuses. A fifth strip beneath shows seat idle derived from the absence of a live claim against the seats the lab hired. A heavy fence runs under the whole matrix, labelled nothing below this line is written, with the task status enum and the row fields drawn underneath it untouched.](figures/the-view.svg)

Read down a column to see every fact it is allowed to touch. Everything below the fence is read and never written, which is the whole content of BR-10 and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). The mermaid below names the same four paths.

```mermaid
flowchart LR
R["the board's rows"] -->|"pending, with an assignee"| Q["queued"]
R -->|"in progress, live claim"| N["running"]
R -->|"parked or blocked, with its reason"| W["waiting on you"]
R -->|"terminal"| D["done"]
S["the seats the lab hired"] -.->|"no live claim"| I["idle"]
```
Read down a column to see every fact it is allowed to touch. Everything below the fence is read and never written, which is the whole content of BR-10 and [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905). This figure is the one picture of the columns; the rules above are their text.

## What does not move

| # | When | Then | Proved by |
|---|---|---|---|
| BR-14 | This issue's diff is inspected | It touches `goals/` and nothing else. No published package gains a file, an export or a changeset ([D1](DECISIONS.md#d1)) | CI · a check over the diff, run rather than read |
| BR-15 | `goals/devforce-lab/` is run after this lands | Byte for byte as before. Its interim board shape and its two ledger declarations are untouched | Existing suite |
| BR-14 | This issue's diff is inspected | It touches `goals/` and nothing else, **and nothing under `goals/devforce-lab/`** — the one subtree inside the fence this issue must also leave alone. No published package gains a file, an export or a changeset ([D1](DECISIONS.md#d1)) | CI · a check over the diff, run rather than read |
| BR-15 | `goals/devforce-lab/` is run after this lands | Byte for byte as before. Its interim board shape and its two ledger declarations are untouched | BR-14's diff gate, which rejects that subtree — a behavioural suite cannot prove a tree unchanged · its existing suite still green |
| BR-16 | Someone looks here for the nested cascade | It is not here. One hop: the channel's board, then the seat | Documented, not checked |
| BR-17 | The lab is run twice at two drain widths | Both runs are recorded, and neither is presented as the recommended setting ([D3](DECISIONS.md#d3)) | The comparison the lab writes out |
| BR-17 | The epic asks what a busy seat does | The lab runs at either drain width from one documented switch, with no edit to the tree and none to the checks. Running both and writing out the comparison is [ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) evidence the epic calls for, and neither width is presented as the recommended setting ([D3](DECISIONS.md#d3)) | Contract gate · the switch exercised at both values · the comparison when the epic asks |

## Failure taxonomy

Everything about the **tree** is fatal at hire and collected: a bad seat folder, a missing tool grant or an undeclared board refuses the whole roster and names every problem, because a lab that boots short proves something other than what it claims. Everything about a **row** is a per-row outcome that leaves the ledger readable — an unroutable row refuses at the drain, a non-member's filing refuses at the channel, a failed row settles `errored` and stays visible in the queue. Nothing retries, because a retry would hide the thing the queue exists to show.
A malformed or forbidden **declaration** is fatal at hire and collected: a bad seat folder, a `seatTools:` key in a worker file, a block declaring a board or anything org-scoped — each refuses the whole roster and names every problem, because a lab that boots short proves something other than what it claims. **A missing tool grant is not in that class.** `tools:` is what grants a registered name's use, so a seat that omits it has nothing to refuse at hire: it hires cleanly and the tool is simply absent from its catalog. That is why BR-2's twin fails where it does — at filing, not at hire. Everything about a **row** is a per-row outcome that leaves the ledger readable — an unroutable row refuses at the drain, a non-member's filing refuses at the channel, a failed row settles `errored` and stays visible in the queue. Nothing retries, because a retry would hide the thing the queue exists to show.

## Acceptance criteria this issue owns

Expand Down
9 changes: 8 additions & 1 deletion spec/FIX-1430/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ flowchart TD
D2 -.->|"rejected"| X2["FIX-1385's check with a third seat<br/>proves the half nobody doubted"]
I --> D3["D3 · a busy seat's behaviour is shown"]
D3 -.->|"rejected"| X3["pick a drain width and move on<br/>settles an epic wall in a goals folder"]
D3 -.->|"rejected"| X4["run both widths in this issue's CI<br/>a second deliverable on the exit gate"]
```

Solid edges are what you're signing. Dashed edges lost, and the label says why.
Expand Down Expand Up @@ -43,7 +44,9 @@ Solid edges are what you're signing. Dashed edges lost, and the label says why.
|---|---|
| **Instead of** | Picking a drain width for the lab and letting that choice read as the recommended shape |
| **Because** | Whether a busy seat gets a second copy or work queues behind it is one of four session-policy walls the epic took back from FIX-1408 — and the epic named *this lab, running a queue deep enough to matter*, as what would settle it. Deciding it inside `goals/` settles an epic wall where nobody reads decisions ([ER-15](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)) |
| **Locks in** | Two runs of one queue where one would do, and a reader looking for the recommended setting gets a comparison instead. When the epic rules, the lab is revisited to keep the ruled shape — the evidence costs a second visit, on purpose |
| **What "shown" means, exactly** | The lab is **wired so either width runs from one documented switch** — no edit to the tree, none to the checks. It does **not** mean this issue's CI runs the whole queue twice. Running both and writing out the comparison is evidence the epic asks for when it wants to rule, and it is off this issue's merge bar (BR-17). The decision is unchanged; only the work it implies moved |
| **And what the lab may therefore not assert** | If the lab must not choose the busy-seat policy, it cannot require the waiting row to read `pending` either — that reading *is* one of the two candidate policies. BR-6 keeps what holds at every width (nothing re-routes, nothing drops, the assignee is held) and records the status rather than requiring it. A hand-off leaves a claimed row `in_progress` while its child is still queued (`docs/architecture/dispatched-work.md` -> "The claim gate and the fence ticket"), so requiring `pending` would have pinned the gate to a state the landed path need not produce |
| **Locks in** | A reader looking for the recommended setting gets a comparison instead, and the epic owes a ruling before anyone can copy this lab as a shape. When it rules, the lab is revisited to keep the ruled width — the evidence costs a second visit, on purpose |

## Decided, not asked

Expand Down Expand Up @@ -79,6 +82,10 @@ Solid edges are what you're signing. Dashed edges lost, and the label says why.

**What being wrong costs.** Narrow when it was wide: the epic wraps on a claim narrower than it reads, and someone builds the wide check afterwards — a few days, nothing already built thrown away. Wide when it was narrow: the gate is slow and intermittently red from the day it lands, which is worse because it is permanent.

**Still open, and not settled here.** This is the product owner's call and it is with them.

**What is fenced while they decide.** Both reviewers asked for the same thing underneath the question, and it costs nothing to give: the *narrow* shape is now a hard requirement of the plan rather than a recommendation waiting on an answer — stub worker handlers doing small deterministic work, one model surface (the coordinator, and nothing else), and pentest-style poll and timeout fixtures ([PLAN](PLAN.md) -> Guardrails, and V-G). So the gate cannot widen toward devforce economics while the question is open. If the answer comes back wide, that is a change to make then, with the cost visible — not a door left open now.

**Settled: none.** No claim here has been argued twice.

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.

Spec gate · Q1. Recommendation is already narrow; “Settled: none” leaves the exit gate one implementation choice away from devforce economics (×4 harness). I’d close this at spec review as narrow + small worker artifacts and reflect that in SPEC sign-off so VG can’t widen silently.

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.

Half accepted, and the half I am declining is the one that is not mine to take.

Not closing Q1 here. It is the product owner's call and it is with him now. Closing it at spec review would be an agent settling a scope question about what the epic's exit gate means, which is the kind of decision the gate exists to put in front of a person. Settled: none stays accurate — no claim here has been argued twice, which is the bar for a settlement.

Accepting the thing underneath it. Your actual worry is that the exit gate sits one implementation choice away from devforce economics while the question is open, and that is fair — an open question is not a licence to widen. So the narrow shape is now a hard requirement of the plan rather than a recommendation waiting on an answer: stub worker handlers doing small deterministic work, one model surface (the coordinator only), pentest-style poll and timeout fixtures. It is a guardrail with a because, not a note.

DECISIONS.md records this under Q1 explicitly — what is fenced while the owner decides, and that if the answer comes back wide, that is a change to make then, deliberately and with the cost visible. Not a door left open now.

So VG cannot widen silently, which is what you were protecting. It just does not cost the owner his question. Leaving this open since it tracks a live gate.


Generated by Claude Code


## How it got here
Expand Down
Loading
Loading