Skip to content
Closed
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
50 changes: 50 additions & 0 deletions spec/FIX-1438/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# FIX-1438 · Business rules

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.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. A human reviews this page; the plan turns it into work.

**Stop report** throughout means the run's three-way word for how it ended (`finished`, `stopped-at-limit`, `failed`), defined in [SPEC.md](SPEC.md). Where a rule means the run record's own `outcome` bookkeeping instead, it says so.

## What the completion check is handed

| # | When | Then | Proved by |
|---|---|---|---|
| BR-1 | A run ends cleanly and reports `finished` | The check is asked, exactly as today, and sees `finished` | CI |
| BR-2 | A run ends cleanly and reports `stopped-at-limit` | The check is asked, and sees `stopped-at-limit` | CI |
| BR-3 | A run ends cleanly and reports no stop report at all | The check is asked, and sees the absent case — distinguishable from every reported word | CI |
| BR-4 | A run reports a stop-report word this framework version does not define | The check sees that word as reported. Never mapped to `finished`, never dropped | CI |
| BR-5 | A run did not end cleanly | The check is not asked, as today. The attempt failed | CI, unchanged suite |
| BR-6 | A prompt builder reads its context | No stop report is on it. The previous attempt's reason still arrives as feedback, as today | CI |

## What a phase does with it, and what the row does

| # | When | Then | Proved by |
|---|---|---|---|
| BR-7 | A phase's check ignores the stop report entirely | Its rows settle exactly as they do today, byte for byte | CI · the cost of [D1](DECISIONS.md#d1), asserted rather than assumed |
| BR-8 | A phase refuses because the run stopped at its limit | The row does not settle. The attempt is failed, the row re-opens, and the reason written on it names the budget stop rather than only "still not done" | CI |
| BR-9 | That row is picked up again | The next attempt resumes the previous attempt's confirmed coding session, so it continues rather than restarting | Existing suite, unchanged |
| BR-10 | A phase refuses on a budget stop for every attempt it is given | The row errors once the retry budget is spent. No new status, no second hold | CI · the path a run that produces nothing already takes |
| BR-11 | A phase's check passes despite a budget stop, because that phase judges the job done | The row settles done. The framework imposes nothing | CI |
| BR-12 | A run asked a question *and* stopped at its limit | The row parks on the question. The ask arm is decided before the completion check, unchanged | CI, unchanged suite |

## Conductor and the lab

| # | When | Then | Proved by |
|---|---|---|---|
| BR-13 | Conductor's implement phase sees a budget stop, and a pull request exists on the branch | It refuses. A pull request is a deliverable, not a finished job ([D3](DECISIONS.md#d3)) | CI |
| BR-14 | The DevForce lab's phase sees a budget stop, and a commit the base ref lacks exists | It refuses | Goal check |
| BR-15 | The lab runs with the `stopped-at-limit` control | The control goes red because the row did not settle done — caught by the same assertion that catches every other control, with no clause of its own | Goal check |
| BR-16 | The lab runs with no control | It passes, unchanged: a clean finish that commits still settles the row done | Goal check |

## Failure taxonomy

Nothing here is fatal. A budget stop is a failed attempt, which is a retry — the same class as a clean run that produced nothing.

**The run record's own `outcome` field is untouched by this change**, and it is a different thing from the stop report: it is the manager's bookkeeping on the run row, holding `running`, `succeeded` or `failed`, and the board row stays the authority on the job's state. The stop report is never written to it. Two fields, two enums, and an implementer who wires the wrong one produces exactly the silent wrong answer this issue is about — which is why the plan pins the field's name apart from `outcome`.

The only way this change makes a row worse off than today is the extra attempt a wrongly-refused budget stop costs, which is named in [D3](DECISIONS.md#d3).

## Acceptance criteria this issue owns

`GOAL_CONTROL=stopped-at-limit pnpm tsx goals/devforce-lab/it-wakes-the-seat-a-file-declared/run.mts` goes red, and its red names the row failing to settle done rather than a framework observation the lab cannot fix. The same goal with no control still passes. Both are run today: the control is red on the finding, the plain gate is green.
80 changes: 80 additions & 0 deletions spec/FIX-1438/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# FIX-1438 · Decisions

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

What was considered, what was chosen, why, and what each choice locks in. Three decisions are the sign-off surface. Everything else here is context for them.

**Stop report** is the run's three-way word for how it ended (`finished`, `stopped-at-limit`, `failed`), defined in [SPEC.md](SPEC.md). It is not the run record's own `outcome` bookkeeping, which this spec does not touch.

## The tree

```mermaid
flowchart TD
I["FIX-1438"] --> D1["D1 · the phase's check receives the stop report<br/>the manager rules on nothing"]
D1 -.->|"rejected"| X1["the manager refuses to settle a budget stop<br/>the run's narration vetoes the phase's judgement"]
D1 -.->|"rejected"| X2["document it as designed<br/>the hazard the epic exists to kill, written down and kept"]
I --> D2["D2 · a refused budget stop re-opens the row,<br/>and errors once retries are spent"]
D2 -.->|"rejected"| X3["park it for a person<br/>new manager machinery, and a human waits on work a retry continues"]
I --> D3["D3 · both shipped phases refuse a budget stop"]
D3 -.->|"rejected"| X4["let the pull-request check keep closing<br/>a half-written pull request is the case this is about"]
```

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

<a name="d1"></a>
## D1 · The phase's completion check receives the run's stop report; the manager still decides nothing on it

| | |
|---|---|
| **Instead of** | The manager comparing the stop report itself and refusing to settle a row whose run stopped at a limit |
| **Because** | What "done" means genuinely differs by phase, and only the phase knows it. A rule in the manager would let the run's own narration overrule the phase's judgement, so a pessimistic report would block work that really was finished. That inversion is the one thing the current design is built to avoid, and the issue locks it as out of bounds |
| **Locks in** | Every phase author now owns one more call, and the framework cannot make them take it. A phase that ignores the new fact closes rows on partial work exactly as today, silently. The contract, the two shipped phases, and the lab control are the whole of the teaching |

**What would change my mind:** a third and fourth phase shipping and both forgetting. At that point the evidence says the fact should be enforced rather than offered, and the right move is a manager-level default with an explicit opt-out — which is a different decision, taken with data rather than ahead of it. It is flagged in [PLAN.md](PLAN.md) → Follow-ups rather than built now.

The honest cost of this decision is that it does not, by itself, fix anything. It hands the fact down; [D3](#d3) is where the rows actually stop closing. Weighed against a central rule, that is the trade: the central rule fixes every phase at once and is wrong for the phase where a budget stop really did leave the job done.

<a name="d2"></a>
## D2 · A refused budget stop re-opens the row with its reason attached, and errors once the retry budget is spent

| | |
|---|---|
| **Instead of** | Parking the row for a person to decide whether to continue, or minting a board word that means "partial" |
| **Because** | That path already exists, is already proved (a clean run that leaves no commit takes it today), and needs no new board vocabulary — which the issue locks. It is also the cheaper answer: a retry resumes the *same* coding session with a fresh budget, so the next attempt carries on rather than starting over. Waiting for a person is the expensive way to get a continuation the system can do unattended |
| **Locks in** | A budget stop spends a retry. An operator sees a row that came back, not a row waiting on them, and a run that keeps hitting its limit ends `errored` rather than as a question. If someone later wants a human in that loop, it is a new hold on an existing status, not a new status |

**What would change my mind:** evidence that a budget-stopped retry usually stops at the same place rather than continuing. Then the retries are pure spend and parking is worth its machinery. Today the resume path hands the previous attempt's confirmed session to the next one, which is what makes continuation the expected case.

<a name="d3"></a>
## D3 · Both shipped phases refuse a budget stop — including the one whose completion check is "a pull request exists"

| | |
|---|---|
| **Instead of** | Refusing only in the lab's phase, where the check is weak ("any commit the base ref lacks"), and letting the pull-request check keep closing because a pull request is a real deliverable |
| **Because** | A run that opens the pull request early and then exhausts its budget is precisely the case this issue is about, and the pull request's existence says nothing about whether the branch under it is finished. The cost of refusing wrongly is one extra run that resumes the session, finds the work done, and closes the row; the cost of closing wrongly is a half-finished branch marked done, found by a person downstream |
| **Locks in** | Anyone running conductor on a tight budget pays one extra attempt per budget stop, including the ones that had genuinely finished. Reversing it later is a one-line change in the phase, not in the framework |

## Decided, not asked

- **The stop report travels as the word the run reported, never narrowed to a boolean or defaulted.** A word this framework version does not define must reach the check as itself; silently mapping an unknown word to `finished` is the same silent partial success in a new place.
- **Reporting nothing stays distinguishable from reporting `finished`.** The absent case is its own value, because a check that cannot tell them apart is the sometimes-absent field the manager's own contract already refuses.
- **The stop report is absent from the prompt builder's context, deliberately and always.** It is the mirror of the rule that keeps the previous attempt's reason off the completion check: a value that means "this attempt" in one place and "the last attempt" in another is a field that lies by position.
- **The manager reads the stop report for one thing only — to say which kind of stop a failure was, in the reason it writes on the re-opened row.** That is what it already does today, and it stays phrasing rather than a decision.
- **The lab's `stopped-at-limit` control stops being special-cased.** It becomes an ordinary control, caught by the same assertion that catches the others.

## Considered and dropped

| Alternative | Why not |
|---|---|
| **Leave it as designed and document it** (the issue's option 1) | Defensible, and it is what the current contract implies. But it writes down the exact hazard this epic exists to remove, and it costs the only reproduction we have: the lab control would have to be rewritten to *expect* a row closing on partial work |
| **Distinguish "finished cleanly" from "finished the work" on the run record** (the issue's option 3) | The row still settles through the done-condition, so nothing about what an operator sees changes. It is option 1 with extra bookkeeping |
| **A manager-level rule: never settle a row whose run reported a limit** | Fixes every phase at once, and is wrong for the phase where the budget stop genuinely left the job complete. Rejected by the issue as an authority inversion, and by the reasoning in [D1](#d1) independently |
| **A new board status for a partial stop** | Locked out by the issue, and it would be a second answer to a question the existing statuses already answer |
| **Scope the completion check to this attempt instead** | A different fix for a different defect (a probe reporting on a branch an earlier attempt wrote), already considered and rejected in the manager's own contract as a clock-skew race |

**Open: none.**

## How it got here

- **Draft** — framed as *two facts are reported and one is read*; chose to hand the second fact to the phase's completion check rather than rule on it in the manager; both shipped phases refuse, and a refusal settles through the re-pend path that already exists.
- **Review** — the stop report and the run record's `outcome` are now named apart everywhere, because the draft repeated the issue's claim that the stop report is written to the run record. It is not: it reaches no store and is read only by the text of a failure message. No decision moved; three reviewers hit the same collision.
Loading
Loading