Skip to content
Closed
Show file tree
Hide file tree
Changes from 2 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
56 changes: 56 additions & 0 deletions spec/FIX-1430/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# FIX-1430 · Business rules

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md)

The cases as rules: what someone does, what happens, and which check proves it. A human reviews this page; the plan turns it into work. *Contract gate* is the model-free check; *goal check* is the model-backed run of the same host.

## Declaring the team

| # | When | Then | Proved by |
|---|---|---|---|
| BR-1 | The lab's tree is read and hired | Exactly four seats — one coordinator, three workers — on the kinds their own files name, one channel, and one ledger minted from the channel at `org` scope. No id is written in any file | Contract gate |
| BR-2 | The coordinator's own file names the task tools | It can file and assign. A twin tree that omits them hires cleanly and cannot file: the names resolve, the grant does not | Contract gate · a refusal tree and its corrected twin |
| BR-3 | A seat's own folder holds a block that declares a board, or anything org-scoped | The whole roster is refused at hire, naming the block. The lab does not widen the seat-tool fence to get a board tool into a folder | Contract gate · refusal tree |

## Filing and assigning

| # | 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. 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, 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 |

## The queue the coordinator sees

| # | 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. **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 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). 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, **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 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

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

A team declared entirely in files — one channel holding one board, one coordinator seat and three worker seats — takes in more work than it has seats. The coordinator files every row through the tools its own file grants it, names who each is for, and the rows run on those seats and no others, each in its own session parented to the coordinator's. The row that could not start immediately runs when a seat frees, without being re-routed. Throughout, the coordinator can say what is queued, what is running, what is waiting on a person, and what is done — every one of those read off rows that already existed.

That is [ER-20](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) and [ER-21](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) together, and it is the epic's exit gate. Nothing else in the set makes this sentence true or false.
93 changes: 93 additions & 0 deletions spec/FIX-1430/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# FIX-1430 · Decisions

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

What was chosen, what lost, what each locks in. Three decisions are the sign-off surface. Calls this issue may not take — where a board lives, what an assignee is, which package format a capability arrives in — belong to [FIX-1385](https://github.com/fixpoint-labs/flow-state-dev/pull/1917), [FIX-1394](https://github.com/fixpoint-labs/flow-state-dev/pull/1915) and the epic.

## The tree

```mermaid
flowchart TD
I["FIX-1430"] --> D1["D1 · the lab ships no package code"]
D1 -.->|"rejected"| X1["export the queue view<br/>a surface designed from one consumer"]
I --> D2["D2 · a queue, not a hand-off"]
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.

<a name="d1"></a>
## D1 · The lab ships no package code; the queue columns stay lab-local

| | |
|---|---|
| **Instead of** | Exporting the columns from `orchestration` or `workforce` as the Layer 2 view surface |
| **Because** | This issue owns one epic rule and no surface. [ER-11](https://github.com/fixpoint-labs/flow-state-dev/pull/1905) calls a queue column a *view* rather than a status — a fence on where it may not live, not a commission to build a view package. One consumer is not a design input, and this lab is the only one. An export would also put the issue behind the W3 ship fence for no gain in evidence |
| **Locks in** | The next consumer that wants columns derives them again, and this lab's shape is a suggestion rather than a contract. If the view turns out to be the product we pay a second design pass — on two examples instead of one, which is the cheaper mistake |

<a name="d2"></a>
## D2 · The proof is a queue, not a hand-off: more rows than seats, and the coordinator assigns through the tools it declared

| | |
|---|---|
| **Instead of** | Re-running FIX-1385's own goal check with a third seat and calling it the exit gate |
| **Because** | That check already shows a row filed by one seat and claimed by another — [ER-20](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)'s first half, the half nobody doubted. Its second half is a coordinator *assigning* to named seats, and routing to the only seat on a board is indistinguishable from not routing. [ER-21](https://github.com/fixpoint-labs/flow-state-dev/pull/1905)'s columns say nothing until a row waits. Hence: several candidate seats, more rows than seats, and a coordinator filing through the model's door |
| **Locks in** | A slower check with more moving parts, and a flaky queue is a flaky exit gate. Worker seats therefore do small deterministic work and the model appears at one place only — how far that goes is [Q1](#q1) |

<a name="d3"></a>
## D3 · What a busy seat does is shown, not chosen

| | |
|---|---|
| **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)) |
| **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

- **No third `LabRoster`.** The lab reads its tree through whatever the package exports when it is built. FIX-1405 deletes the two copies that exist; a third while that is in flight is how a fourth appears.
- **Seat idle comes off the board's rows and the seats the lab hired**, not the live inventory — keeping blocking prerequisites at exactly one sibling.
- **No `defaultWorker`.** An unassigned row throws at the drain today. The lab shows that refusal rather than papering it, because "a row for nobody" is a case a queue meets.
- **The coordinator does not claim the rows it settles.** `taskTools` leaves an unclaimed settle unguarded on purpose; the lab records that rather than working around it.
- **Two checks over one host, differing by one block** — a model-free contract gate and a model-backed run. The devforce lab's shape, reused.
- **The channel's membership fence is consumed, not re-implemented.** A non-member filing is refused by the path a post already meets.

## Considered and dropped

| Alternative | Why not |
|---|---|
| **Grow `goals/devforce-lab` instead** | It is the epic's other evidence and carries a board shape labelled interim. Rewriting it mid-epic destroys the before/after that makes a one-line board legible |
| **A harness-backed coding run per row** | The devforce lab already owns row → supervised coding run. Re-proving it buys no new fact and buys a slow, flaky exit gate ([Q1](#q1)) |
| **Build the nested cascade here too** | Phase-2 inside W4, off the gate by the epic's D1. A gate has to be reachable on a schedule |
| **Read seat liveness from the live inventory** | A second blocking sibling for a fact the board already carries |
| **Let the coordinator dispatch seats directly, skipping the board** | That is today, and it is what the epic exists to replace |

<a name="q1"></a>
## Open · one

### Does the exit gate close on routing proved, or on routing proved all the way into real work?

**In plain terms.** Either the demo ends at *the right worker picked up the right job and reported done*, or it ends at *the right worker picked up the right job, and here is the file it changed.*

**The trade-off.** The narrow reading makes the gate fast, deterministic and rerunnable on every change — but an outsider reading *work reaches a seat that runs it* may reasonably hear the wider one. The wide reading is closer to the words and costs a check that takes minutes, needs a scratch repository and a live harness, and fails for reasons unrelated to routing. A gate that goes red for unrelated reasons stops being one.

**My recommendation: the narrow one**, with worker seats doing small real work — writing a file the check reads back — rather than nothing. The wide claim is evidenced next door: `goals/devforce-lab/` shows a board row becoming a supervised coding run. What has never been shown is a *queue* crossing from a declared coordinator to declared seats, and that is the gap this issue was adopted to close.

**What would change my mind.** If the promise will be read publicly as *declare a team in Markdown and it ships code*, the two halves have to meet in one run at least once, and this is the cheapest place to make them meet.

**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

- **Draft** — framed as evidence rather than surface: owns one rule, builds no export, consumes four. The delta against FIX-1385's goal check was made explicit early, because repeating a sibling's check is the obvious way this issue fails quietly.
Loading
Loading