From 06b0f0d791d77eacf05258d9c5dd721326bcf271 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 01:52:13 +0000 Subject: [PATCH 1/4] spec(FIX-1438): a run that stopped at its budget still closes its row as done The phase's completion check receives the run's outcome word; the manager still decides nothing on it. Both shipped phases refuse a budget stop, and a refusal settles through the re-pend path that already exists. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_018VJZRfkY7gBbiYZhr1eanR --- spec/FIX-1438/BUSINESS-RULES.md | 44 +++++++++++ spec/FIX-1438/DECISIONS.md | 77 ++++++++++++++++++ spec/FIX-1438/PLAN.md | 103 +++++++++++++++++++++++++ spec/FIX-1438/SPEC.md | 64 +++++++++++++++ spec/FIX-1438/figures/what-changes.svg | 94 ++++++++++++++++++++++ 5 files changed, 382 insertions(+) create mode 100644 spec/FIX-1438/BUSINESS-RULES.md create mode 100644 spec/FIX-1438/DECISIONS.md create mode 100644 spec/FIX-1438/PLAN.md create mode 100644 spec/FIX-1438/SPEC.md create mode 100644 spec/FIX-1438/figures/what-changes.svg diff --git a/spec/FIX-1438/BUSINESS-RULES.md b/spec/FIX-1438/BUSINESS-RULES.md new file mode 100644 index 0000000000..e21120c955 --- /dev/null +++ b/spec/FIX-1438/BUSINESS-RULES.md @@ -0,0 +1,44 @@ +# 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. + +## 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 outcome at all | The check is asked, and sees the absent case — distinguishable from every reported word | CI | +| BR-4 | A run reports an outcome 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 outcome 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 outcome 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 keeps its three values (`running`, `succeeded`, `failed`) and gains nothing; it is bookkeeping, and the board row stays the authority on the job's state. 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. diff --git a/spec/FIX-1438/DECISIONS.md b/spec/FIX-1438/DECISIONS.md new file mode 100644 index 0000000000..d944b4d01c --- /dev/null +++ b/spec/FIX-1438/DECISIONS.md @@ -0,0 +1,77 @@ +# 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. + +## The tree + +```mermaid +flowchart TD + I["FIX-1438"] --> D1["D1 · the phase's check receives the outcome word
the manager rules on nothing"] + D1 -.->|"rejected"| X1["the manager refuses to settle a budget stop
the run's narration vetoes the phase's judgement"] + D1 -.->|"rejected"| X2["document it as designed
the hazard the epic exists to kill, written down and kept"] + I --> D2["D2 · a refused budget stop re-opens the row,
and errors once retries are spent"] + D2 -.->|"rejected"| X3["park it for a person
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
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. + + +## D1 · The phase's completion check receives the run's outcome word; the manager still decides nothing on it + +| | | +|---|---| +| **Instead of** | The manager comparing the outcome 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. + + +## 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. + + +## 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 outcome 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 outcome 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 outcome 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 phrasing, not 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. diff --git a/spec/FIX-1438/PLAN.md b/spec/FIX-1438/PLAN.md new file mode 100644 index 0000000000..aec66ae69b --- /dev/null +++ b/spec/FIX-1438/PLAN.md @@ -0,0 +1,103 @@ +# FIX-1438 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** + +Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md) (BR-n) and [DECISIONS.md](DECISIONS.md) (D-n). `tdd`. One PR. + +## Surfaces + +| ID | Package · role | Change | Rules | +|---|---|---|---| +| S1 | `harness-manager` · the phase contract | A completion-check context that carries the run's outcome, sitting beside the prompt context that carries the ask. The shared base keeps what both need; the outcome goes on the completion side only, mirroring how the carry-forward reason sits on the prompt side only (D1) | BR-1 BR-2 BR-3 BR-4 BR-6 | +| S2 | `harness-manager` · the verdict handler's completion arm | Hand the reported outcome word to the check. Compare nothing on it. The value crosses as reported — not narrowed to a boolean, not defaulted when unrecognised (D1) | BR-1 BR-2 BR-3 BR-4 BR-5 BR-7 BR-11 | +| S3 | `harness-manager` · the failure text the refusal writes | When a clean run's check refuses, name how the run stopped, so the reason carried onto the re-opened row says *stopped at its limit* and not only *still not done* | BR-8 | +| S4 | `labs/conductor` · the implement phase's check | Refuse a budget stop before the pull-request probe runs (D3) | BR-13 | +| S5 | `goals/devforce-lab/lab` · the lab phase's check | Refuse a budget stop before the commit probe runs (D3) | BR-14 | +| S6 | `goals/devforce-lab/it-wakes-the-seat-a-file-declared/run.mts` | **Remove** the `stopped-at-limit` clause and the exclusion that keeps the ordinary settle assertion from applying to that control. The control then goes red through the same assertion as the others (tenet 3) | BR-15 BR-16 | +| S7 | `goals/devforce-lab/it-wakes-the-seat-a-file-declared/goal.md` | **Remove** the Findings section recording this as an unfixed framework observation, and give the control's table row an ordinary *goes red on*. The verdict log gains a line | BR-15 | +| S8 | Docs | `packages/harness-manager/README.md` EXTEND · `apps/docs/docs/orchestration/harness-manager.md` EXTEND · one `minor` changeset for `@flow-state-dev/harness-manager` | — | + +## Sequence + +```mermaid +flowchart TD + S1["S1 · the completion-check context"] --> S2["S2 · hand the outcome down"] + S2 --> S3["S3 · name the stop in the reason"] + S2 --> S4["S4 · conductor's phase refuses"] + S2 --> S5["S5 · the lab's phase refuses"] + S5 --> S6["S6 · remove the control's special case"] + S6 --> S7["S7 · remove the finding from goal.md"] + S4 --> S8["S8 · docs and changeset"] +``` + +## Checks + +| ID | Runs after | Passes when | +|---|---|---| +| V1 | S1 S2 | A stubbed run reporting each of `finished`, `stopped-at-limit`, a word the framework does not define, and nothing at all reaches the check as four distinguishable values (BR-1 BR-2 BR-3 BR-4). The unrecognised word is not mapped to anything | +| V2 | S2 | A check that never reads the outcome settles its rows exactly as before, on every one of those four (BR-7). This is [D1](DECISIONS.md#d1)'s cost asserted, not assumed — it is the check that must go red if S2 ever grows a rule of its own | +| V3 | S2 | A run that did not end cleanly never reaches the check (BR-5); a run that asked a question parks before it (BR-12). Both unchanged | +| V4 | S1 | No outcome is reachable from a prompt builder's context (BR-6) | +| V5 | S3 | A refusal after a budget stop writes a reason naming the stop; a refusal after a clean finish writes today's text (BR-8) | +| V6 | S4 | Conductor's implement phase refuses a budget stop with a pull request present on the branch, and still closes on a clean finish with one (BR-13) | +| V7 | S2 S4 S5 | A phase that refuses every attempt re-pends the row and errors it once the retry budget is spent (BR-10) | +| VG | S5 S6 | Goal: `GOAL_CONTROL=stopped-at-limit pnpm tsx goals/devforce-lab/it-wakes-the-seat-a-file-declared/run.mts` goes red, and the red is the ordinary settle assertion. The same goal with no control passes (BR-15 BR-16) | +| V8 | S6 S7 | No `stopped-at-limit` special case survives in the lab runner, and `goal.md` carries no Findings section for it. Grep | + +**The red state to produce first.** The finding reproduces today on `main`: the control is red with *the run reported outcome "stopped-at-limit" and the row settled done anyway*, and the plain gate is green (both run 2026-09-18 on `a34a3ab`, this branch's base). VG is that same pair after the change, with the control's red coming from a different assertion. If VG's control is *green* at any point, the change is wrong — a control that stopped going red has stopped being a control. + +## Pinned names · the only two + +| Where | Name | Why pinned | +|---|---|---| +| The outcome word | `stopped-at-limit` | The framework's own vocabulary, already public on the harness contract. A phase author types it | +| What crosses into the check | the **word**, not a boolean | A boolean would fold the unrecognised and absent cases into one, which is BR-3 and BR-4's whole point | + +Everything else is yours to name, including what the completion-check context type is called. + +## Guardrails + +| Rule | Because | +|---|---| +| The outcome reaches the check as reported — never narrowed, never defaulted when unrecognised (BP-030) | A vendor word this version does not know, silently becoming `finished`, is the same silent partial success in a new place | +| "Reported nothing" stays a distinct value from "reported `finished`" | A field where one value means two things is the sometimes-absent shape the manager's own contract refuses, and the reason the prompt context was split from the base in the first place | +| The outcome is absent from the prompt builder's context, always | Its mirror is already a rule: the carry-forward reason is kept off the completion check because it describes the *previous* attempt. A value that means "this attempt" in one place and "the last one" in another lies by position | +| The manager compares nothing on the outcome except to phrase a failure reason | A comparison there makes the run's narration an authority over the done-condition — the inversion this issue locks out | +| No new `TaskStatus` member, no second hold, no `needs_input` | Locked on the issue. A refused budget stop settles through terminals that already exist | +| Every phase that ships in this repo is updated, not just the one the lab exercises (tenet 5) | The fact is offered rather than enforced, so the shipped phases *are* the teaching. One updated and one forgotten teaches that it is optional | + +## Docs + +- **EXTEND** `apps/docs/docs/orchestration/harness-manager.md` — the paragraph on what `isDone` answers and when it is consulted. Add the second fact the check is handed and say plainly that a check which ignores it will close a row on a run that stopped at its budget. *Voice risk:* this is a correctness caveat, and the temptation is to soften it into "you may also consider". Don't — the docs' job here is to make the cost of ignoring it visible. +- **EXTEND** `packages/harness-manager/README.md` — the one line describing the done-condition, plus the outcome in the phase example. +- **One `minor` changeset** for `@flow-state-dev/harness-manager`. It is published and the phase contract is what a consumer writes against, so a downstream author needs to know the check gained an input (BP-022). `labs/conductor` and `goals/devforce-lab` are private and get none. +- **No new page.** This is one paragraph under an existing concept. + +## Sketch · pseudocode, illustrative, react to the shape + +``` +the phase contract: + shared base → where the run is, which attempt, the branch + the prompt side → + the ask marker, the answers, last attempt's reason + the completion side → + how this run stopped ← the whole change + +the manager, after a clean verdict: + ask the phase: done?, handing it the run's outcome word as reported + if done → settle, as today + if not → fail the attempt; the reason names the stop when there was one (S3) + +a phase that cares: + if the run says it stopped at its limit → not done + otherwise → whatever the probe says +``` + +**POC:** none built, and none needed. The claim this rests on is reproducible from the shipped lab, and both directions were run before this was written — see the red-state note under Checks. + +## At implement time + +- Check whether the verdict handler still widens the outcome to a plain string on its input schema. It does today, deliberately; whether the value is narrowed on the way to the check is yours, subject to the guardrail that an unrecognised word must survive. +- [FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440) is removing the child/nested session substrate in parallel. It does not touch the completion path, but the manager runs its verdict step inside a dispatched session and reads that session's id onto the run record. If that work has landed, re-read the verdict handler before editing it. Neither issue blocks the other. + +## Follow-ups + +- **The framework cannot enforce that a phase consults the outcome**, which is [D1](DECISIONS.md#d1)'s named cost. If a third phase ships and forgets, that is the evidence for reversing it: a manager-level default with an explicit per-phase opt-out. Flagged, not filed — filing it now would pre-commit to a design the data has not asked for yet. diff --git a/spec/FIX-1438/SPEC.md b/spec/FIX-1438/SPEC.md new file mode 100644 index 0000000000..3fd6205a16 --- /dev/null +++ b/spec/FIX-1438/SPEC.md @@ -0,0 +1,64 @@ +# FIX-1438 · A run that stopped at its budget still closes its row as done + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +Feature · `harness-manager` + `conductor` + `devforce-lab` · small · 1 PR · under [FIX-1408](https://linear.app/fixpoint-labs/issue/FIX-1408) (W4 dispatch / session policy) + +## Five people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **watches a board to see what got finished** | A row reads `completed` for a run that ran out of turns half-way and committed the half it managed. Nothing says so | The row comes back open with the reason on it, and the work carries on from where the run stopped | +| **writes a phase's completion check** | Gets one fact — is the job done on the branch. The run's own report that it ran out of road never reaches them | Gets both facts: the state of the branch, and the word the run used for how it stopped. The call stays theirs | +| **runs a coding agent on a tight turn or spend budget** | Budget stops are indistinguishable from clean finishes once a row settles, so the cost of a budget that is too small is invisible | A budget stop is visible on the row, every time it happens | +| **has a run that stopped at its budget but had genuinely finished** | The row closes, correctly, by luck | The row re-opens once. The next attempt resumes the same coding session, finds the work done, and closes it. One extra cheap run | +| **reads the harness-manager contract to build a phase** | The contract says a clean end plus a passing check is completion, and never says that "clean" includes a run that hit its limit | The contract says which two facts decide completion, and that ignoring the second one closes rows on partial work | + +A supervised run reports two things when it ends: whether it ended cleanly, and *how* it stopped. Only the first is read. The second — the framework's own three-way word, one of `finished`, `stopped-at-limit`, `failed` — is written to the run record and never consulted by anything that decides. + +## What changes + +![Two columns. Today, a finished run reports both a status and an outcome word, only the status reaches the completion check, the outcome word goes nowhere, and the row settles completed. After, both reach the check, the check answers not done, and the row re-opens with the reason attached.](figures/what-changes.svg) + +Follow the second line out of each box. Today it dead-ends: `stopped-at-limit` is recorded and no decision reads it, so the phase's check answers from the branch alone and a half-finished commit closes the row. After, the same word reaches the check, and the phase — still the only thing that decides — has what it needs to say *not done*. + +**A phase's completion check, as its author writes it:** + +```diff + isDone: async (run) => { ++ // The run itself says it ran out of road. A commit is not the job. ++ if (run.outcome === "stopped-at-limit") return false + return await aCommitExistsTheBaseRefLacks(run) + }, +``` + +Nothing else about a phase changes. A check that ignores the new fact behaves exactly as it does today, byte for byte, which is [D1](DECISIONS.md#d1)'s cost and is named there. + +## How the two facts reach the decision + +```mermaid +flowchart LR + H["the coding run's report"] -->|"status · did it end cleanly"| M["the manager"] + H -->|"outcome · how it stopped"| M + M -->|"not clean"| F["the attempt failed"] + M -->|"clean · both facts"| P["the phase's completion check"] + P -->|"done"| C["the row settles"] + P -->|"not done"| F +``` + +The manager still reads `status` alone to decide whether the attempt failed, and still asks the phase whether the job is done. The only new edge is the second one into the check. The manager compares nothing on the outcome word. + +## What stays as it is + +- **The done-condition is the sole authority on completion.** The manager gains no rule of its own, and the run record never becomes a judge. +- **The board's vocabulary.** No new `TaskStatus`, no second hold status, no word for "partial". A refused budget stop takes the path a run that produced nothing already takes. +- **A run that asks a question still parks first.** The ask arm is decided before the completion check, exactly as today. +- **The prompt builder's context.** The outcome is not on it; a prompt still learns about the last attempt through `feedback`. + +## Sign off + +1. **[D1](DECISIONS.md#d1) · The phase's completion check receives the run's outcome word; the manager still decides nothing on it.** If wrong: every phase carries one more call the framework cannot enforce, so a phase that forgets closes rows on partial work exactly as today, silently. +2. **[D3](DECISIONS.md#d3) · Both shipped phases refuse a budget stop — including the one whose check is "a pull request exists".** If wrong: a run that opened a reviewable pull request and then hit its limit costs one extra run before it closes. +3. **[D2](DECISIONS.md#d2) · A refused budget stop re-opens the row with its reason attached, and errors once the retry budget is spent.** If wrong: a run that keeps stopping at its budget burns its whole retry budget before anyone is asked about it. + +**Open: none.** Number 1 is the one to weigh: it is the choice to hand the fact down rather than rule on it centrally. The reasoning, what was rejected, and what each locks in is in [DECISIONS.md](DECISIONS.md). The cases the code must satisfy are in [BUSINESS-RULES.md](BUSINESS-RULES.md). diff --git a/spec/FIX-1438/figures/what-changes.svg b/spec/FIX-1438/figures/what-changes.svg new file mode 100644 index 0000000000..d35f41f602 --- /dev/null +++ b/spec/FIX-1438/figures/what-changes.svg @@ -0,0 +1,94 @@ + + + + + + + + + + + + + + TODAY + AFTER + + + + + + + THE RUN ENDED + status: completed + outcome: stopped-at-limit + + + + status + + + outcome is recorded, + never consulted + + + + THE PHASE'S CHECK + a commit exists → done + + + + THE BOARD ROW + completed + + half the job, closed + + + + + THE RUN ENDED + status: completed + outcome: stopped-at-limit + + + + status + + outcome + + + + THE PHASE'S CHECK + a commit, and how it + stopped → not done + + + + THE BOARD ROW + open again + + reason attached; the next + attempt resumes the session + + From 3eb7ef948ba9ca921408db9def0a8dc14e23f0a7 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 02:00:40 +0000 Subject: [PATCH 2/4] spec(FIX-1438): name the run's stop report apart from the run record's outcome MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-draft: the draft repeated the issue's claim that the harness's 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. The two three-value fields are now named apart in all four documents and the figure, and the plan pins the phase-side field away from `outcome`. No decision moved. Re-draft: review round 1 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_018VJZRfkY7gBbiYZhr1eanR --- spec/FIX-1438/BUSINESS-RULES.md | 16 ++++++--- spec/FIX-1438/DECISIONS.md | 15 ++++---- spec/FIX-1438/PLAN.md | 47 +++++++++++++++++--------- spec/FIX-1438/SPEC.md | 21 +++++++----- spec/FIX-1438/figures/what-changes.svg | 28 +++++++-------- 5 files changed, 78 insertions(+), 49 deletions(-) diff --git a/spec/FIX-1438/BUSINESS-RULES.md b/spec/FIX-1438/BUSINESS-RULES.md index e21120c955..7d3b8ba0a6 100644 --- a/spec/FIX-1438/BUSINESS-RULES.md +++ b/spec/FIX-1438/BUSINESS-RULES.md @@ -4,22 +4,24 @@ 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 outcome at all | The check is asked, and sees the absent case — distinguishable from every reported word | CI | -| BR-4 | A run reports an outcome word this framework version does not define | The check sees that word as reported. Never mapped to `finished`, never dropped | 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 outcome is on it. The previous attempt's reason still arrives as feedback, as today | CI | +| 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 outcome 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-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 | @@ -37,7 +39,11 @@ The cases, written as rules. Each says what a person or the system does and what ## 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 keeps its three values (`running`, `succeeded`, `failed`) and gains nothing; it is bookkeeping, and the board row stays the authority on the job's state. 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). +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 diff --git a/spec/FIX-1438/DECISIONS.md b/spec/FIX-1438/DECISIONS.md index d944b4d01c..a97833323d 100644 --- a/spec/FIX-1438/DECISIONS.md +++ b/spec/FIX-1438/DECISIONS.md @@ -4,11 +4,13 @@ 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 outcome word
the manager rules on nothing"] + I["FIX-1438"] --> D1["D1 · the phase's check receives the stop report
the manager rules on nothing"] D1 -.->|"rejected"| X1["the manager refuses to settle a budget stop
the run's narration vetoes the phase's judgement"] D1 -.->|"rejected"| X2["document it as designed
the hazard the epic exists to kill, written down and kept"] I --> D2["D2 · a refused budget stop re-opens the row,
and errors once retries are spent"] @@ -20,11 +22,11 @@ flowchart TD Solid edges are what you're signing. Dashed edges lost, and the label says why. -## D1 · The phase's completion check receives the run's outcome word; the manager still decides nothing on it +## 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 outcome itself and refusing to settle a row whose run stopped at a limit | +| **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 | @@ -54,10 +56,10 @@ The honest cost of this decision is that it does not, by itself, fix anything. I ## Decided, not asked -- **The outcome 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. +- **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 outcome 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 outcome 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 phrasing, not a decision. +- **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 @@ -75,3 +77,4 @@ The honest cost of this decision is that it does not, by itself, fix anything. I ## 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. diff --git a/spec/FIX-1438/PLAN.md b/spec/FIX-1438/PLAN.md index aec66ae69b..49ef1060a9 100644 --- a/spec/FIX-1438/PLAN.md +++ b/spec/FIX-1438/PLAN.md @@ -4,12 +4,14 @@ Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md) (BR-n) and [DECISIONS.md](DECISIONS.md) (D-n). `tdd`. One PR. +**Stop report** is the run's three-way word for how it ended (`finished`, `stopped-at-limit`, `failed`), on the run's handle — *not* the run record's own `outcome` bookkeeping, which this change does not touch. See [SPEC.md](SPEC.md). + ## Surfaces | ID | Package · role | Change | Rules | |---|---|---|---| -| S1 | `harness-manager` · the phase contract | A completion-check context that carries the run's outcome, sitting beside the prompt context that carries the ask. The shared base keeps what both need; the outcome goes on the completion side only, mirroring how the carry-forward reason sits on the prompt side only (D1) | BR-1 BR-2 BR-3 BR-4 BR-6 | -| S2 | `harness-manager` · the verdict handler's completion arm | Hand the reported outcome word to the check. Compare nothing on it. The value crosses as reported — not narrowed to a boolean, not defaulted when unrecognised (D1) | BR-1 BR-2 BR-3 BR-4 BR-5 BR-7 BR-11 | +| S1 | `harness-manager` · the phase contract | A completion-check context carrying the stop report, added the same way the prompt context already adds its ask fields — one sibling of the existing shared base, not a new hierarchy. The stop report is on the completion side only, mirroring how the carry-forward reason sits on the prompt side only (D1) | BR-1 BR-2 BR-3 BR-4 BR-6 | +| S2 | `harness-manager` · the verdict handler's completion arm | Hand the reported stop report to the check. Compare nothing on it. The value crosses as reported — not narrowed to a boolean, not defaulted when unrecognised (D1) | BR-1 BR-2 BR-3 BR-4 BR-5 BR-7 BR-11 | | S3 | `harness-manager` · the failure text the refusal writes | When a clean run's check refuses, name how the run stopped, so the reason carried onto the re-opened row says *stopped at its limit* and not only *still not done* | BR-8 | | S4 | `labs/conductor` · the implement phase's check | Refuse a budget stop before the pull-request probe runs (D3) | BR-13 | | S5 | `goals/devforce-lab/lab` · the lab phase's check | Refuse a budget stop before the commit probe runs (D3) | BR-14 | @@ -21,7 +23,7 @@ Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSI ```mermaid flowchart TD - S1["S1 · the completion-check context"] --> S2["S2 · hand the outcome down"] + S1["S1 · the completion-check context"] --> S2["S2 · hand the stop report down"] S2 --> S3["S3 · name the stop in the reason"] S2 --> S4["S4 · conductor's phase refuses"] S2 --> S5["S5 · the lab's phase refuses"] @@ -34,10 +36,10 @@ flowchart TD | ID | Runs after | Passes when | |---|---|---| -| V1 | S1 S2 | A stubbed run reporting each of `finished`, `stopped-at-limit`, a word the framework does not define, and nothing at all reaches the check as four distinguishable values (BR-1 BR-2 BR-3 BR-4). The unrecognised word is not mapped to anything | -| V2 | S2 | A check that never reads the outcome settles its rows exactly as before, on every one of those four (BR-7). This is [D1](DECISIONS.md#d1)'s cost asserted, not assumed — it is the check that must go red if S2 ever grows a rule of its own | +| V1 | S1 S2 | A stubbed run reporting each of `finished`, `stopped-at-limit`, a word the framework does not define, and nothing at all reaches the check as four distinguishable values (BR-1 BR-2 BR-3 BR-4). The unrecognised word is not mapped to anything. One table over the four values covers this and V2 | +| V2 | S2 | A check that never reads the stop report settles its rows exactly as before, on every one of those four (BR-7). This is [D1](DECISIONS.md#d1)'s cost asserted, not assumed — it is the check that must go red if S2 ever grows a rule of its own | | V3 | S2 | A run that did not end cleanly never reaches the check (BR-5); a run that asked a question parks before it (BR-12). Both unchanged | -| V4 | S1 | No outcome is reachable from a prompt builder's context (BR-6) | +| V4 | S1 | No stop report is reachable from a prompt builder's context (BR-6) | | V5 | S3 | A refusal after a budget stop writes a reason naming the stop; a refusal after a clean finish writes today's text (BR-8) | | V6 | S4 | Conductor's implement phase refuses a budget stop with a pull request present on the branch, and still closes on a clean finish with one (BR-13) | | V7 | S2 S4 S5 | A phase that refuses every attempt re-pends the row and errors it once the retry budget is spent (BR-10) | @@ -50,25 +52,27 @@ flowchart TD | Where | Name | Why pinned | |---|---|---| -| The outcome word | `stopped-at-limit` | The framework's own vocabulary, already public on the harness contract. A phase author types it | +| The stop-report value | `stopped-at-limit` | The framework's own vocabulary, already public on the harness contract. A phase author types it | | What crosses into the check | the **word**, not a boolean | A boolean would fold the unrecognised and absent cases into one, which is BR-3 and BR-4's whole point | +| The field a phase reads it from | **not** plainly `outcome` | The run record already has an `outcome` holding a different enum. Two fields one word apart is how an implementer wires the wrong one, and three reviewers hit it reading the first draft | -Everything else is yours to name, including what the completion-check context type is called. +Everything else is yours to name, including what the completion-check context type is called and the exact spelling of that field. ## Guardrails | Rule | Because | |---|---| -| The outcome reaches the check as reported — never narrowed, never defaulted when unrecognised (BP-030) | A vendor word this version does not know, silently becoming `finished`, is the same silent partial success in a new place | +| The stop report reaches the check as reported — never narrowed, never defaulted when unrecognised (BP-030) | A vendor word this version does not know, silently becoming `finished`, is the same silent partial success in a new place | | "Reported nothing" stays a distinct value from "reported `finished`" | A field where one value means two things is the sometimes-absent shape the manager's own contract refuses, and the reason the prompt context was split from the base in the first place | -| The outcome is absent from the prompt builder's context, always | Its mirror is already a rule: the carry-forward reason is kept off the completion check because it describes the *previous* attempt. A value that means "this attempt" in one place and "the last one" in another lies by position | -| The manager compares nothing on the outcome except to phrase a failure reason | A comparison there makes the run's narration an authority over the done-condition — the inversion this issue locks out | +| The stop report is absent from the prompt builder's context, always | Its mirror is already a rule: the carry-forward reason is kept off the completion check because it describes the *previous* attempt. A value that means "this attempt" in one place and "the last one" in another lies by position | +| The manager compares nothing on the stop report except to phrase a failure reason | A comparison there makes the run's narration an authority over the done-condition — the inversion this issue locks out | | No new `TaskStatus` member, no second hold, no `needs_input` | Locked on the issue. A refused budget stop settles through terminals that already exist | | Every phase that ships in this repo is updated, not just the one the lab exercises (tenet 5) | The fact is offered rather than enforced, so the shipped phases *are* the teaching. One updated and one forgotten teaches that it is optional | +| The run record's `outcome` is not touched, and nothing writes the stop report to it | They are different enums. Merging them makes the run record the judge, which is the inversion the issue locks out | ## Docs -- **EXTEND** `apps/docs/docs/orchestration/harness-manager.md` — the paragraph on what `isDone` answers and when it is consulted. Add the second fact the check is handed and say plainly that a check which ignores it will close a row on a run that stopped at its budget. *Voice risk:* this is a correctness caveat, and the temptation is to soften it into "you may also consider". Don't — the docs' job here is to make the cost of ignoring it visible. +- **EXTEND** `apps/docs/docs/orchestration/harness-manager.md` — the paragraph on what `isDone` answers and when it is consulted. Add the second fact the check is handed and say plainly that a check which ignores it will close a row on a run that stopped at its budget. *Voice risk:* this is a correctness caveat, and the temptation is to soften it into "you may also consider". Don't — the docs' job here is to make the cost of ignoring it visible. Teach the Lab as **DevForce**; `labs/conductor` is the package path, not the product name. - **EXTEND** `packages/harness-manager/README.md` — the one line describing the done-condition, plus the outcome in the phase example. - **One `minor` changeset** for `@flow-state-dev/harness-manager`. It is published and the phase contract is what a consumer writes against, so a downstream author needs to know the check gained an input (BP-022). `labs/conductor` and `goals/devforce-lab` are private and get none. - **No new page.** This is one paragraph under an existing concept. @@ -76,13 +80,13 @@ Everything else is yours to name, including what the completion-check context ty ## Sketch · pseudocode, illustrative, react to the shape ``` -the phase contract: +the phase contract, as it already is plus one sibling: shared base → where the run is, which attempt, the branch the prompt side → + the ask marker, the answers, last attempt's reason - the completion side → + how this run stopped ← the whole change + the completion side → + this run's stop report ← the whole change the manager, after a clean verdict: - ask the phase: done?, handing it the run's outcome word as reported + ask the phase: done?, handing it the stop report as reported if done → settle, as today if not → fail the attempt; the reason names the stop when there was one (S3) @@ -95,9 +99,20 @@ a phase that cares: ## At implement time -- Check whether the verdict handler still widens the outcome to a plain string on its input schema. It does today, deliberately; whether the value is narrowed on the way to the check is yours, subject to the guardrail that an unrecognised word must survive. +- Check whether the verdict handler still widens the stop report to a plain string on its input schema. It does today, deliberately; whether the value is narrowed on the way to the check is yours, subject to the guardrail that an unrecognised word must survive. - [FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440) is removing the child/nested session substrate in parallel. It does not touch the completion path, but the manager runs its verdict step inside a dispatched session and reads that session's id onto the run record. If that work has landed, re-read the verdict handler before editing it. Neither issue blocks the other. +## Notes from review + +Below-the-bar feedback from the spec PR, verbatim. Inputs, not instructions — adopt, adapt, or discard; you owe no justification for discarding one. + +- "S1 is really 'add a `CompletionRunContext` (or equivalent) with the harness stop word on **`isDone` only**' — same mirror as `answers` / `feedback`. That keeps implementers from inventing a third exported base type." — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#discussion_r4043102044)) +- "V1 and V2 both require the same four-way matrix … at implement time one table-driven stub phase + shared fixture is enough. Calling that out here would avoid eight near-duplicate harness-manager scenarios in CI." — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#discussion_r4043102045)) +- "Thin PLAN surfaces: … merge S4+S5 into one row with two paths, merge S6+S7, fold S3 into S2; drop or fold V8 into VG." — cursor ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#pullrequestreview-5243422272)) +- "Keep V7 on injected probes — avoid duplicating eight manager scenarios or live `gh` in V6." — cursor ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#pullrequestreview-5243422272)) +- "Single owner per invariant: prompt/completion split → BR-6 once; pass-through word → one BR + one PLAN guardrail; D1's 'silent if ignored' cost → DECISIONS D1 only." — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#discussion_r4043102052)) +- "Early refuse **before** PR/git probes saves I/O on the failure path but does not offset retries." — cursor ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/1887#pullrequestreview-5243422272)). The plan already sequences the refusal first in S4 and S5. + ## Follow-ups - **The framework cannot enforce that a phase consults the outcome**, which is [D1](DECISIONS.md#d1)'s named cost. If a third phase ships and forgets, that is the evidence for reversing it: a manager-level default with an explicit per-phase opt-out. Flagged, not filed — filing it now would pre-commit to a design the data has not asked for yet. diff --git a/spec/FIX-1438/SPEC.md b/spec/FIX-1438/SPEC.md index 3fd6205a16..10882a01f4 100644 --- a/spec/FIX-1438/SPEC.md +++ b/spec/FIX-1438/SPEC.md @@ -14,20 +14,24 @@ Feature · `harness-manager` + `conductor` + `devforce-lab` · small · 1 PR · | **has a run that stopped at its budget but had genuinely finished** | The row closes, correctly, by luck | The row re-opens once. The next attempt resumes the same coding session, finds the work done, and closes it. One extra cheap run | | **reads the harness-manager contract to build a phase** | The contract says a clean end plus a passing check is completion, and never says that "clean" includes a run that hit its limit | The contract says which two facts decide completion, and that ignoring the second one closes rows on partial work | -A supervised run reports two things when it ends: whether it ended cleanly, and *how* it stopped. Only the first is read. The second — the framework's own three-way word, one of `finished`, `stopped-at-limit`, `failed` — is written to the run record and never consulted by anything that decides. +A supervised run reports two things when it ends: whether it ended cleanly, and *how* it stopped. Only the first is read. + +**Two different things are called "outcome" today, and this spec keeps them apart.** The **stop report** is the framework's three-way word for how a run ended — `finished`, `stopped-at-limit`, `failed` — and it lives on the run's handle. The **row outcome** is the manager's own bookkeeping on the run record, an unrelated three values (`running`, `succeeded`, `failed`). This spec is about the stop report. The row outcome does not change and is never what a phase reads. + +The stop report is not recorded anywhere and is read by exactly one thing: the text of the failure message written when an attempt fails. On a run that ends cleanly it reaches no decision at all. ## What changes -![Two columns. Today, a finished run reports both a status and an outcome word, only the status reaches the completion check, the outcome word goes nowhere, and the row settles completed. After, both reach the check, the check answers not done, and the row re-opens with the reason attached.](figures/what-changes.svg) +![Two columns. Today, a finished run reports both a status and a stop report, only the status reaches the completion check, the stop report goes nowhere, and the row settles completed. After, both reach the check, the check answers not done, and the row re-opens with the reason attached.](figures/what-changes.svg) -Follow the second line out of each box. Today it dead-ends: `stopped-at-limit` is recorded and no decision reads it, so the phase's check answers from the branch alone and a half-finished commit closes the row. After, the same word reaches the check, and the phase — still the only thing that decides — has what it needs to say *not done*. +Follow the second line out of each box. Today it dead-ends: `stopped-at-limit` reaches no decision, so the phase's check answers from the branch alone and a half-finished commit closes the row. After, the same word reaches the check, and the phase — still the only thing that decides — has what it needs to say *not done*. **A phase's completion check, as its author writes it:** ```diff isDone: async (run) => { + // The run itself says it ran out of road. A commit is not the job. -+ if (run.outcome === "stopped-at-limit") return false ++ if (run.stopReport === "stopped-at-limit") return false return await aCommitExistsTheBaseRefLacks(run) }, ``` @@ -39,25 +43,26 @@ Nothing else about a phase changes. A check that ignores the new fact behaves ex ```mermaid flowchart LR H["the coding run's report"] -->|"status · did it end cleanly"| M["the manager"] - H -->|"outcome · how it stopped"| M + H -->|"stop report · how it stopped"| M M -->|"not clean"| F["the attempt failed"] M -->|"clean · both facts"| P["the phase's completion check"] P -->|"done"| C["the row settles"] P -->|"not done"| F ``` -The manager still reads `status` alone to decide whether the attempt failed, and still asks the phase whether the job is done. The only new edge is the second one into the check. The manager compares nothing on the outcome word. +The manager still reads `status` alone to decide whether the attempt failed, and still asks the phase whether the job is done. The only new edge is the second one into the check. The manager compares nothing on the stop report. ## What stays as it is - **The done-condition is the sole authority on completion.** The manager gains no rule of its own, and the run record never becomes a judge. +- **The run record's own `outcome` field.** It keeps its three bookkeeping values and gains nothing; the stop report is not written to it. - **The board's vocabulary.** No new `TaskStatus`, no second hold status, no word for "partial". A refused budget stop takes the path a run that produced nothing already takes. - **A run that asks a question still parks first.** The ask arm is decided before the completion check, exactly as today. -- **The prompt builder's context.** The outcome is not on it; a prompt still learns about the last attempt through `feedback`. +- **The prompt builder's context.** The stop report is not on it; a prompt still learns about the last attempt through `feedback`. ## Sign off -1. **[D1](DECISIONS.md#d1) · The phase's completion check receives the run's outcome word; the manager still decides nothing on it.** If wrong: every phase carries one more call the framework cannot enforce, so a phase that forgets closes rows on partial work exactly as today, silently. +1. **[D1](DECISIONS.md#d1) · The phase's completion check receives the run's stop report; the manager still decides nothing on it.** If wrong: every phase carries one more call the framework cannot enforce, so a phase that forgets closes rows on partial work exactly as today, silently. 2. **[D3](DECISIONS.md#d3) · Both shipped phases refuse a budget stop — including the one whose check is "a pull request exists".** If wrong: a run that opened a reviewable pull request and then hit its limit costs one extra run before it closes. 3. **[D2](DECISIONS.md#d2) · A refused budget stop re-opens the row with its reason attached, and errors once the retry budget is spent.** If wrong: a run that keeps stopping at its budget burns its whole retry budget before anyone is asked about it. diff --git a/spec/FIX-1438/figures/what-changes.svg b/spec/FIX-1438/figures/what-changes.svg index d35f41f602..c759de3eee 100644 --- a/spec/FIX-1438/figures/what-changes.svg +++ b/spec/FIX-1438/figures/what-changes.svg @@ -1,5 +1,5 @@ + aria-label="Two columns. Today, a finished run reports both a status and a stop report, only the status reaches the completion check, the stop report reaches no decision, and the row settles completed. After, both reach the check, the check answers not done, and the row re-opens with the reason attached.">