tldr-experts 0.26.1 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # Changelog
 
+## 0.28.0 — 2026-09-15
+
+### Added
+
+- **A story whose merge-up to its epic conflicts in a few of its own files gets one conflict
+  turn instead of a person (#286).** MEASURED on a field run: a story with a green DoD conflicted
+  bringing itself up to the epic (#268) in one counted test list both stories bumped, blocked
+  correctly — and nothing in the framework could resolve it: the developer holds no merge verb, a
+  plain reopen had no work, and a person did it in a scratch worktree; 1.5 h later the same story
+  conflicted again in four files. Now, when the conflict is in at most three files, every one in
+  the story's declared `touches` (the boundary matcher, `inSurface`), with no conflict turn since
+  its last `story.reopened` and an attempt left, the story is requeued the way #313 requeues a
+  red DoD — prior status, worktree kept, one attempt spent — and one new `story.conflict_turn`
+  event is written. Its next attempt is dispatched with the CURRENT epic tip merged into the
+  worktree and the merge left open (markers, `MERGE_HEAD`); the prompt names the files, the
+  story's intent and the stories that landed on the epic, and `git add` + `git commit` — verbs the
+  developer already holds — close it, with the DoD as judge. A marker guard in `git.ts`
+  (each conflicted file handed, any path it was renamed to, and every added or untracked path a
+  commit could sweep in, read for any `<<<<<<<`, `|||||||`
+  or `>>>>>>>` line — a lone `=======` heading underline is not a marker — plus `MERGE_HEAD`)
+  blocks, never requeues, a turn that left a marker in one of those files or never closed the
+  merge, naming the files — without it, measured
+  by mutation, markers were committed and merged onto the epic as `done`. Anything else still
+  blocks exactly as before, with the reason it got no turn appended. The bound is counted from
+  `events.jsonl`, so it holds across invocations, and `tldrx replay` says an agent, not a person,
+  resolved the merge. Headless only: the host's `--commit` half and an as-is settlement block as
+  they did.
+
+### Fixed
+
+- **`tldrx story reopen` on a `blocked` story also releases the dependents it alone was holding
+  (#312).** Reopening a blocked dependency left every dependent `blocked` with a
+  `dependency S<n> blocked` reason that had just gone stale, so each needed its own reopen —
+  measured three times in one day on a live run. Every `blocked` story whose recorded hold names
+  the reopened story (or a story released this way, transitively) now goes back to `todo` in the
+  same command when no other dependency still holds it. Each release is its own signed
+  `story.reopened` naming the dependency that caused it (additive `released_by` and `dependency`),
+  consuming no attempt. A dependent still held by another dependency, or blocked by a verdict
+  rather than a hold, stays `blocked`, and the output says which and why.
+- **`Recommended: A [src: …]` is a recommendation, and `seed check` reads the line the way the
+  loop does (#323).** On a live run the loop answered Q8's `Recommended: A — <why> [src: …]`
+  and left Q7's `Recommended: A [src: …]` for a person, parking an unattended run: the question
+  parser demanded a dash reason before any citation, while `seed check` tested only the
+  substring `Recommended:` and had passed the same shape clean — two derivations of "has a
+  recommendation" that disagreed. There is now one grammar and one reader
+  (`parseRecommendedLine`): the letter first, then any of its `)`, a `— <why>` and trailing
+  `[src: …]` tokens. `seed check` calls it and names, as exit-1 findings, a `Recommended:` line
+  it cannot read (`question-recommended-unreadable`, with the line and the shape expected) and
+  a letter naming none of the options the question lists (`question-recommended-option`). A
+  seed question that lists no options is not judged on its letter — the options are the What
+  stage's to write. A §2.7 block's unreadable line is still ignored rather than refused.
+- **An unattended run is no longer stranded by its own provenance, or by a refused check it could
+  fix itself (#231).** Measured 2026-09-14 on a `run auto` validation run (0.27.0): a What stage
+  wrote `[src: absent:.tldrx/memory/facts.yml#tenant-credits]`, true when written; the loop then
+  auto-answered that stage's questions, the new facts' `source:` maps read
+  `run: 260914-tenant-credits`, and `claim-sources` refused the absence on the run id. The refused
+  `auto` gate then waited for a person, who typed `reject --and-continue` with the finding —
+  intervention #2 of that run. Two fixes. An `absent:…#<needle>` over the workspace's
+  `facts.yml` no longer searches a fact's `source: {who, when, run, q, decided_by}` map — that is
+  who recorded it, not what it says; a map with any other key is searched in full, and a needle in
+  a fact's content still refuses, even on a fact this run just wrote. And under `--wait-gates`,
+  an `auto` gate refused by failed checks ALONE (a declared check, or `claim-sources` failing)
+  re-runs its stage once through the same `reject --and-continue` path, signed `run auto` with the
+  findings as the note; past that bound, or on a `human`/`agent` gate, or when questions, budget,
+  stories, boundary or status also hold it, the loop waits for a person as before and prints why.
+
+## 0.27.0 — 2026-09-14
+
+### Added
+
+- **The Plan gate holds a plan to its shape, not only to whether it can execute (#316, #317,
+  #318, #319).** A planning audit of 9 runs (relayed, not re-run) found 25 of 54 build-gate
+  rejections were dependency reopens and every multi-story plan in one workspace a
+  one-story-per-wave chain; a 4-wave plan left 2 stories never attempted, while the 2-wave cap
+  lived only as skill prose and a `seed check` advisory nothing enforced. The `plan` check now
+  refuses more waves than the framework carries per run unless `waves.yml` records the new
+  optional `wave_cap_reason` (an additive root key — `version: 1` only grows), refuses a story
+  scheduled later than its `depends_on` requires, and names in its detail a dod command some
+  stories of one epic and repo carry and a sibling does not — an advisory, because which
+  stories share a shape is not machine-readable and the evidence is one epic. Vertical slices,
+  inventory files in `touches:` and end-to-end placement are Plan-prompt rules rather than
+  checks, because no stack-independent name marks a route file and no changed-file set exists
+  at Plan time to compare against. Every rule, number and sentence comes from one file,
+  `src/core/plan/planShape.ts`, which the gate, the rendered "Plan shape" section
+  (`tldrx plan schema`) and `seed check` all read; the gate's pass is its own, not
+  `validatePlan`'s, so a plan approved before it still loads at Build.
+
+- **`tldrx run auto --rebalance-finished` moves a blocked phase's shortfall out of money a
+  finished phase can no longer spend (#314).** MEASURED on a field run: `04-build` was refused
+  $11.07 short while `01-what` had finished $16.25 under its ceiling and the run total had $141
+  of room; `run auto` stopped and a person typed `budget raise 04-build 12 --take-from 01-what`
+  and relaunched. The move was already sanctioned — nothing looked for it. With the flag, the
+  budget gate moves EXACTLY the shortfall before refusing, out of phases whose every stage is
+  `done`/`skipped`, none stale, priced in `metered-usd` and with no unmetered turn (a lower-bound
+  spend proves nothing about what is left) — so `05-watch` with a stage still to run never gives.
+  It goes through `budget raise --take-from`'s own code, so the run ceiling never grows; it never
+  passes a recorded grant, not even under `on_grant_exceed: warn`; it never makes a partial move.
+  Each move is one `budget.raised` with both phases' before/after, `source` and the launcher as
+  actor. OPT-IN, not a default or a `budget.yml` key, because a phase ceiling is a person's
+  decision about money — the reason `--retry-failed` and `--until-done` never touch exit 2.
+  Without the flag every money refusal now names the finished phases' unspent money and the exact
+  `--take-from` move, and `budget.blocked` records `short_usd`, `finished_unspent_usd` and
+  `uncovered_usd`. An agent gate on the stage a move unblocked still falls to a person, and its
+  reason now names the flag, the launcher and the donor phase instead of "a person moved" it.
+
+### Fixed
+
+- **`tldrx ship` no longer opens a PR over a stale or red epic (#315).** Four PRs it opened in
+  one audit window came back red and needed a person, because between choosing the base and
+  `gh pr create` nothing fetched the base or ran a workspace command. Ship now fetches the base,
+  merges it into the epic in a throwaway worktree when behind, and runs the `done` stories'
+  Definition of Done on that tree; a conflict or a red command refuses (exit 2) naming the
+  paths or the command. Under `ship.push` the base is merged into the epic (forward, never
+  rebased or forced) and pushed with it; without it the branch is untouched. `--dry-run` runs
+  the same checks and exits the same way.
+
+- **A reviewer is given at least $2.00, not $1.00 — the old floor sat below the reviews that
+  finish (#307, owner decision: "A: piso $2").** MEASURED in the issue across 44 reviewer task
+  rows in two workspaces: the 37 that returned a verdict cost $0.17–$1.02 (median $0.50), so the
+  most expensive COMPLETED review already spent more than the $1.00 floor allowed; and a 3-story
+  run whose Plan priced every story at $8–$9 put every reviewer on that floor — at the shipped
+  defaults an $8 story derives `8 × 0.25 / (2 × 1.25)` = $0.80 — and one died with
+  `Reached maximum budget ($1)` before reading the diff, parking its story at `review`. $1.00
+  was never measured; it was chosen because it looked reasonable. `REVIEWER_FLOOR_USD` is now
+  $2.00, a fixed constant — no new key, event or schema. The consequence the owner accepted:
+  #289's refuse-before-spawn now fires when a stage has less than $2.00 left, and the refusal
+  already says so with the figure (`a review costs at least $2.00`). The budget brake's copy of
+  the floor in `budget/remainingWork.ts` is now IMPORTED from `build/caps.ts` rather than
+  restated, so the brake's estimate and the executor's cap read one definition (`caps.ts`
+  imports only two schema leaves, so the budget-gate hook stays cheap). The Build golden moves
+  by exactly that figure: the four reviewer `agent.spawned` lines carry `max_budget_usd: 2`.
+  `test/build-parallel.test.ts`'s three-story wave moves from a $9 to a $12 stage, because at $9
+  three $2.00 floors plus three developers sum past the ceiling the test proves the wave fits
+  inside. The seed-check / plan-gate warning (part 3 of #307) is not in this change.
+
+- **A developer whose DoD goes red gets the story's next attempt, instead of blocking it on the
+  first miss (#313).** Reported in #313's audit of 12 run folders (relayed, not re-measured
+  here): 17 human `tldrx story reopen`s were a red DoD — a snapshot not regenerated, a pinned
+  inventory the story's own change moved, a lint rule — that the developer never got a second
+  look at, each one waiting on a person to read the kept output and type the reopen. MEASURED on
+  `70da3d1` with the fake agent: a story at `attempts: 2` whose attempt 1 left a red DoD ended
+  `blocked` with ONE `task.started`. Mechanism: `settleHalf` blocked on any half-A failure,
+  while the reviewer's `changes` verdict already requeued while `attempt < attempts` — two
+  failures on the merits, one retry budget honoured for only one of them. A red DoD now takes
+  the same bound: the attempt settles back at the status it started from (not `blocked` — it is
+  about to run again) with `the DoD was red on attempt 1 of 2`, keeps its worktree, and the next developer prompt carries the kept output under `## Previous
+  attempt` with the DoD header (#211); the last attempt blocks, saying `the DoD stayed red on 2
+  of 2 attempts` when both were red. Narrow on purpose — a refused developer (#271), a cap death
+  (#277), a REFUSED or absent-binary dod command (#165, #209), no dod commands and a reopen that
+  changed nothing (#308) still block on the first attempt, because a second one buys the same
+  outcome. The attempts a red DoD spent are counted off `events.jsonl`, not memory: review of
+  the first cut MEASURED three red DoDs under `attempts: 2` when a spawn fault ended an
+  invocation between attempts and the next process started counting from zero. No new event,
+  no new field; the host door (`--prepare`/`--commit`) is unchanged. `tldrx learn`'s chapter 5
+  now narrates — and asserts — the two red attempts before the reopen.
+
 ## 0.26.1 — 2026-09-14
 
 ### Changed

package/README.md

@@ -335,6 +335,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.28.0 | 2026-09-15 | `beta` | Four changes that keep an unattended run moving instead of stranding on a person. A story whose merge-up to its epic conflicts in at most three of its own touched files gets one automated conflict turn instead of a person, guarded against committing conflict markers (#286). `story reopen` on a blocked story now releases every dependent it alone was holding, in the same command (#312). Seed's `Recommended:` line and the loop's question parser now share one grammar, so a citation-only recommendation no longer parks a run that `seed check` had already passed (#323). And an `absent:` needle over `facts.yml` no longer trips on a fact's own recording metadata, while an `auto` gate refused only by failed checks gets one automatic re-run before waiting for a person (#231). |
+| 0.27.0 | 2026-09-14 | `beta` | Five changes for unattended runs, from a planning audit and live field measurement. The `plan` check now refuses a plan with more waves than the framework carries per run (unless `waves.yml` names a `wave_cap_reason`), refuses a story scheduled before its `depends_on` allows, and flags a dod command siblings carry that one story doesn't (#316–#319). `tldrx run auto --rebalance-finished` moves a blocked phase's exact shortfall out of a finished phase's unspent ceiling before refusing, through `budget raise --take-from` itself, so the run ceiling never grows and no grant is ever assumed; every money refusal now names the unspent total and the exact command to fix it (#314). `tldrx ship` fetches and merges the base into the epic and re-runs the `done` stories' DoD before opening a PR, so a stale or red epic refuses instead of shipping a PR that comes back red (#315). A reviewer's budget floor rises from $1.00 to $2.00, matching what completed reviews actually cost, so a review no longer dies mid-diff on a floor that was never measured (#307). And a developer whose DoD goes red gets the story's next attempt instead of blocking on the first miss, with the kept output handed to the next attempt and the bound counted from `events.jsonl` so it holds across process restarts; a refused developer, a cap death, or a broken dod command still blocks immediately (#313). |
 | 0.26.1 | 2026-09-14 | `beta` | Three refusals that stop a bad state from settling quietly. A Build fix round whose developer lands no diff is refused before the DoD instead of closing `done` on an unmoved tree, because `commitIfDirty` hands back the old head sha on a clean commit and the existing "no commit to review" gate never fires for it — `workSince` is now asked on the success path too, for any story a person put back with a note. `tldrx ship` refuses an epic carrying a story the reviewer marked `changes`: it asks the ledger's `lastMerge` for every story not `done` and exits 2 naming the story, the merge and the handoff's reason, instead of opening a PR whose "Not done" list hid rejected code already merged into the diff. And a stage-failure line keeps the branch it names when the worktree path is wider than the line: the refusal puts the branches before the path, and `oneLine` keeps a line's head and tail instead of dropping the identifiers that sat at the end. |
 | 0.26.0 | 2026-09-14 | `beta` | Two field defects from the same class — a reader of an event payload trusting a field its writer never set — plus the ceiling that killed the turn that earned it. A wide story's measured `touches_widened` no longer throws after the turn has settled: the cap knows the three lists by name and drops them whole by count, every reader derives before/after through one function, and an executor that throws after paid turns leaves their rows and money in `run.yml` and saves before it emits. The cost surfaces then agree with each other: a turn whose result was lost to that fault reads as UNMETERED, LOWER BOUND on `tldrx cost` and in the Build handoff through the door other unmeasured turns already use, a turn still in flight reads as nothing, and a late result retires the lost mark instead of counting twice. Replay reads the reason a failed stage recorded instead of printing "no reason recorded" for every one. |
 | 0.25.0 | 2026-09-14 | `beta` | The other half of the two-session protocol and four holes measured on live runs. `scripts/release.sh` now waits on a running wave's lock before touching the tree and never hands back the marker it wrote — release has precedence, the wave yields, exit 14 when it gives up; the heading gate also refuses an unreleased version at or below `package.json`; the marker carries its phase and `--status` reports a release queued behind a wave (#304). In-session `tldrx next --prepare` and `--commit` ask the same dependency frontier the headless loop asks: a terminal hold records the dependent `blocked`, a pending hold refuses without writing, a held `--commit` keeps the work it sits on and says where it is (#300). A Watch card refused for an unsourced `## Where` item comes back to its writer marked, the refusal names the cure, and the brief shows one non-file example, so a retry edits the card instead of regenerating it blind (#301). And `run.yml` no longer loses an external write to a live loop: a save carries only the fields the store changed over a fresh read, ownership is declared, `cancelled` is terminal and wins in the file and in the process, a file that cannot be merged is kept beside as `.bak` and said so, and a file recording another run is refused (#305). Minor release: a new exit code on a public script, a stricter merge gate, and `--prepare`/`--commit` refuse where they used to proceed. |

package/dist/hooks/answer-capture.js

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-d0jhr5wh.js";
+} from "./chunk-c62y35wh.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-jpp137mb.js";
+} from "./chunk-48ctk154.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-qzsxhsyj.js";
+} from "./chunk-khjm356r.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   PHASE_IDS
-} from "./chunk-m1s8a6s0.js";
-import"./chunk-bznt6jb2.js";
-import"./chunk-ezfvp5kx.js";
+} from "./chunk-veffvzw5.js";
+import"./chunk-g7wz339n.js";
+import"./chunk-zvxgdssb.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,7 +28,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -38,7 +38,7 @@ import {
   isScopedTemplate,
   parseYaml,
   scopedSlotOf
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-ka7768vx.js";
+} from "./chunk-q3d4xdhb.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-t44983nq.js";
-import"./chunk-qzsxhsyj.js";
+} from "./chunk-tna1bz8r.js";
+import"./chunk-khjm356r.js";
 import {
   asRunBudget,
   currentActor,
@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-bbrhs055.js";
+} from "./chunk-xhd77h0p.js";
 import {
   EventLog
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -34,18 +34,18 @@ import {
   newestActiveRun,
   renderRunEconomies,
   runSpend
-} from "./chunk-yre2scxn.js";
-import"./chunk-bznt6jb2.js";
+} from "./chunk-hws2gnxj.js";
+import"./chunk-g7wz339n.js";
 import {
   noteDeprecations
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-jpp137mb.js → chunk-48ctk154.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-ezfvp5kx.js";
+} from "./chunk-zvxgdssb.js";
 import {
   FACT_CONFIDENCES,
   FACT_DECIDERS,
@@ -15,7 +15,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -28,7 +28,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-41k19q8t.js → chunk-abswp1vt.js}

@@ -2,7 +2,7 @@ import {
   GATE_POLICIES,
   validateGatesPolicy,
   validateStagePolicy
-} from "./chunk-bznt6jb2.js";
+} from "./chunk-g7wz339n.js";
 import {
   asDocument,
   isRecord,
@@ -15,7 +15,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -50,6 +50,7 @@ var EVENT_TYPES = [
   "story.reopened",
   "story.base_fastforwarded",
   "story.base_updated",
+  "story.conflict_turn",
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",

package/dist/hooks/{chunk-d0jhr5wh.js → chunk-c62y35wh.js}

@@ -1,15 +1,15 @@
 import {
   findDuplicate
-} from "./chunk-jpp137mb.js";
+} from "./chunk-48ctk154.js";
 import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 
 // src/core/distill/distill.ts
 var CONFLICT_THRESHOLD = 0.6;

package/dist/hooks/{chunk-0sy3tmfg.js → chunk-f6t1xc3f.js}

@@ -8240,7 +8240,7 @@ function resolveAbsent(ref, ctx, section, claim) {
   if (found === null)
     return OK;
   if (needle !== null)
-    return searchForNeedle(found, needle, path);
+    return searchForNeedle(found, needle, path, isWorkspaceFacts(found, ctx));
   const held = whatIsThere(found);
   if (held === null)
     return OK;
@@ -8248,7 +8248,7 @@ function resolveAbsent(ref, ctx, section, claim) {
 }
 var NEEDLE_MAX_BYTES = 512 * 1024;
 var EMPTY_PROBE_MAX_BYTES = 64 * 1024;
-function searchForNeedle(abs, needle, path) {
+function searchForNeedle(abs, needle, path, factsFile) {
   let stat;
   try {
     stat = statSync2(abs);
@@ -8271,12 +8271,35 @@ function searchForNeedle(abs, needle, path) {
   const lines = text.split(`
 `);
   for (let i = 0;i < lines.length; i++) {
-    if ((lines[i] ?? "").toLowerCase().includes(wanted)) {
+    const line = factsFile ? withoutFactProvenance(lines[i] ?? "") : lines[i] ?? "";
+    if (line.toLowerCase().includes(wanted)) {
       return refused(`\`${needle}\` IS at ${path}:${String(i + 1)} — that is a presence, not an absence`, abs);
     }
   }
   return OK;
 }
+function isWorkspaceFacts(abs, ctx) {
+  return normalize(abs) === normalize(join2(ctx.root, PROJECT_FRAMEWORK_DIR, "memory", "facts.yml"));
+}
+var PROVENANCE_KEYS = new Set(["who", "when", "run", "q", "decided_by"]);
+var SOURCE_OPEN_RE = /(^|[\s,{])source:\s*\{/;
+var PROVENANCE_ENTRY_RE = /^\s*([a-z_]+):\s*("(?:[^"\\]|\\.)*"|[^,{}"]*?)\s*([,}])/;
+function withoutFactProvenance(line) {
+  const open = SOURCE_OPEN_RE.exec(line);
+  if (open === null)
+    return line;
+  const start = open.index + (open[1] ?? "").length;
+  let at = open.index + open[0].length;
+  for (;; ) {
+    const entry = PROVENANCE_ENTRY_RE.exec(line.slice(at));
+    if (entry === null || !PROVENANCE_KEYS.has(entry[1] ?? ""))
+      return line;
+    at += entry[0].length;
+    if (entry[3] === "}")
+      break;
+  }
+  return line.slice(0, start) + " ".repeat(at - start) + line.slice(at);
+}
 function whatIsThere(abs) {
   let stat;
   try {

package/dist/hooks/{chunk-bznt6jb2.js → chunk-g7wz339n.js}

@@ -1,6 +1,6 @@
 import {
   isRecord
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/run/stagePolicy.ts
 function validateStagePolicy(value, stageIds, issues, spec) {

package/dist/hooks/{chunk-yre2scxn.js → chunk-hws2gnxj.js}

@@ -1,7 +1,7 @@
 import {
   listRunDirs,
   parseYaml
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-qzsxhsyj.js → chunk-khjm356r.js}

@@ -1,6 +1,6 @@
 import {
   runtime
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/hooks/passthrough.ts
 async function readStdin() {

package/dist/hooks/{chunk-5stgwp3g.js → chunk-khy21x6e.js}

@@ -3,7 +3,7 @@ import {
   parseSrcToken,
   srcToken,
   withoutSrcToken
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
@@ -11,7 +11,9 @@ var HEADING_RE = /^##\s+(Q\d{1,6})\s+·\s+(.+?)\s*$/;
 var METADATA_RE = /^<!--\s*(.*?)\s*-->$/;
 var WHY_RE = /^Why asked:\s*(.*)$/;
 var OPTION_RE = /^-\s+([A-E])\)\s*(.*)$/;
-var RECOMMENDED_RE = /^Recommended:[ \t]+([A-E])\)?[ \t]*(?:[—–-][ \t]+(.*))?$/;
+var RECOMMENDED_PREFIX_RE = /^Recommended:/;
+var RECOMMENDED_RE = /^Recommended:[ \t]+([A-E])\)?(?![^ \t])[ \t]*(.*)$/;
+var RECOMMENDED_REASON_RE = /^[—–-](?:[ \t]+(.*))?$/;
 var ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
 var ANSWER_SLOT_RE = /^\[Answer\]:/;
 var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
@@ -55,6 +57,7 @@ function buildBlock(startLine, lines) {
   let whySrc = null;
   const options = [];
   let recommended = null;
+  let sawRecommendedLine = false;
   let answer = "";
   let answerIndex = -1;
   let footer = null;
@@ -82,9 +85,10 @@ function buildBlock(startLine, lines) {
       options.push({ letter: option[1], text: option[2] });
       continue;
     }
-    const recommendation = RECOMMENDED_RE.exec(line);
-    if (recommendation !== null && recommendation[1] !== undefined && recommended === null) {
-      recommended = toRecommendation(recommendation[1], recommendation[2] ?? "");
+    if (RECOMMENDED_PREFIX_RE.test(line) && !sawRecommendedLine) {
+      sawRecommendedLine = true;
+      const reading = parseRecommendedLine(line);
+      recommended = reading.kind === "ok" ? reading.recommendation : null;
       continue;
     }
     if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
@@ -109,13 +113,27 @@ function buildBlock(startLine, lines) {
     lines: [...lines]
   };
 }
-function toRecommendation(option, rest) {
-  const token = parseSrcToken(rest);
-  return {
-    option,
-    why: withoutSrcToken(rest).trim(),
-    src: token === null ? "" : token.refs.map((ref) => ref.raw).join(SRC_SEPARATOR)
-  };
+function parseRecommendedLine(line) {
+  if (!RECOMMENDED_PREFIX_RE.test(line))
+    return { kind: "absent" };
+  const match = RECOMMENDED_RE.exec(line.replace(/\s+$/, ""));
+  const option = match?.[1];
+  if (match === null || option === undefined)
+    return { kind: "unreadable", line };
+  let rest = (match[2] ?? "").trim();
+  const tokens = [];
+  for (let token = parseSrcToken(rest);token !== null; token = parseSrcToken(rest)) {
+    tokens.unshift(token.refs.map((ref) => ref.raw));
+    rest = withoutSrcToken(rest).replace(/[\s.,;:!?]+$/, "").trim();
+  }
+  let why = "";
+  if (rest !== "") {
+    const reason = RECOMMENDED_REASON_RE.exec(rest);
+    if (reason === null)
+      return { kind: "unreadable", line };
+    why = (reason[1] ?? "").trim();
+  }
+  return { kind: "ok", line, recommendation: { option, why, src: tokens.flat().join(SRC_SEPARATOR) } };
 }
 function parsePipeComment(inner) {
   const pairs = [];

package/dist/hooks/{chunk-pwzy19er.js → chunk-kx45kt9n.js}

@@ -3,12 +3,13 @@ import {
   DEFAULT_ECONOMY,
   DEFAULT_ON_GRANT_EXCEED,
   DEFAULT_ON_HOST_TOKENS_EXCEED,
+  WAVES_FILE,
   asRunBudget,
   nowRfc3339,
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-bbrhs055.js";
+} from "./chunk-xhd77h0p.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -21,12 +22,12 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   cursorStage,
   isAttendedByHostView,
   openRunViews
-} from "./chunk-yre2scxn.js";
+} from "./chunk-hws2gnxj.js";
 import {
   backupPathFor,
   isAlive,
@@ -35,20 +36,20 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-ezfvp5kx.js";
+} from "./chunk-zvxgdssb.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   FRAMEWORK_ROOT,
   PLAN_STATUSES,
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
@@ -421,6 +422,11 @@ class RunStore {
     this.currentBudget = fn(structuredClone(this.currentBudget));
     this.budgetMutated = true;
   }
+  refreshCeilings() {
+    if (this.budgetMutated)
+      return;
+    this.currentBudget = this.ceilingsToWrite();
+  }
   append(event) {
     this.events.append(event);
   }
@@ -621,6 +627,33 @@ var MIN_SLICE_BYTES = 2 * 1024;
 // src/core/facilitator/contextLedger.ts
 var DEFAULT_PROMPT_MAX_BYTES = 400 * 1024;
 
+// src/core/plan/planShape.ts
+var MAX_WAVES_PER_RUN = 2;
+var RUN_SIZE_ISSUES = "#286/#244/#280";
+var WAVE_CAP_REASON_KEY = "wave_cap_reason";
+var PLAN_SHAPE_RULES = [
+  {
+    issue: "#316",
+    text: `**At most ${String(MAX_WAVES_PER_RUN)} waves** (patch for ${RUN_SIZE_ISSUES} — the framework's measured ` + "carry today, not a design preference). A later wave waits on every earlier merge, so each extra wave is " + "a stall: a 4-wave plan left 2 stories never attempted. The `plan` check refuses more unless the root of " + `\`${WAVES_FILE}\` records \`${WAVE_CAP_REASON_KEY}: "<why these stories cannot share a wave>"\`.`
+  },
+  {
+    issue: "#316",
+    text: "**Every story runs in the EARLIEST wave its `depends_on` allows.** `depends_on: []` runs in W1; a story " + "whose dependencies all finish in W1 runs in W2. The `plan` check refuses a story held later with nothing " + "making it wait. If something does — two stories editing one file — that is a `depends_on` edge: write it."
+  },
+  {
+    issue: "#317",
+    text: "**Each story is a vertical slice.** When its own dod goes green, what it adds is reachable from a route, " + "endpoint, command or job that a user or caller actually hits — not only from its own tests. A component " + "no route renders, or a handler nothing registers, is refused at Build review as unreachable: put the wiring " + "in the same story, and the wiring's file in its `touches`. No check reads this; the review does."
+  },
+  {
+    issue: "#318",
+    text: "**Inventory files go in `touches` up front.** Grep for the tests, snapshots and generated files that " + "ENUMERATE what the story adds — route trees, guard tables, allow-lists, architecture or coverage " + "inventories, approved snapshots — and declare them. They change because the story's change forces them " + "to, not because anyone meant to edit them, and each one left out is a `touches` widening at Build."
+  },
+  {
+    issue: "#319",
+    text: "**End-to-end coverage is not the last story.** Either a test-harness story runs in W1 and later stories " + "depend on it and run against it, or each UI or feature story carries the e2e command in its own dod. A " + "final e2e story that depends on everything is the story never reached. The `plan` check names a command " + "some stories of one epic and repo carry and a sibling does not — an advisory: say in that story why not."
+  }
+];
+
 // src/core/run/runOutcome.ts
 import { join as join3 } from "node:path";
 
@@ -651,6 +684,7 @@ function statusWithOutcome(status, outcome) {
 
 // src/core/run/autoGate.ts
 var AUTO_GATE_ACTOR = "auto";
+var RETRYABLE_CONDITIONS = new Set(["checks", "claim-sources"]);
 var AUTO_GATE_REFUSED_PREFIX = "auto-gate refused — held by: ";
 var HELD_SEPARATOR = " · ";
 function heldByNote(note) {

package/dist/hooks/{chunk-ka7768vx.js → chunk-q3d4xdhb.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";

package/dist/hooks/{chunk-t44983nq.js → chunk-tna1bz8r.js}

@@ -1,7 +1,7 @@
 import {
   parseHookInput,
   readStdin
-} from "./chunk-qzsxhsyj.js";
+} from "./chunk-khjm356r.js";
 
 // src/hooks/lib/decide.ts
 function deny(reason) {