tldr-experts 0.18.1 → 0.18.2

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## 0.18.2 — 2026-09-13
+
+### Added
+
+- **The zero-touch recipe is written down, on the pages a person opens to run one (#276).**
+  Measured on origin/main at 0.18.1, after the first fully unattended run had ended in a merged
+  pull request: `--questions`, `--ship`, `--until-done`, `--gates none` and `run cancel` were
+  each documented, and no page chained them into the thing that had just worked — seed file →
+  `run new … --gates none --questions none --ship pr --budget` → a backgrounded
+  `run auto --run <id> --until-done`. `nohup`, `2>&1 &`, the log to `tail -f` and "how do I
+  check on it later" had zero hits repo-wide; `--ui plain`, the flag that keeps a backgrounded
+  log readable, lived in the spec and the changelog only. Three seeds written the same day had
+  failed `run new` on the 240-character claim clip (#275), and the rules a seed must follow to
+  survive the importer and the `[src:]` grammar existed only in the source. So: a "Zero-touch
+  run, start to finish" section at the top of the site's unattended-operation guide (EN + ES)
+  with the copyable block, one line per flag — including that `--ship merge` over a base
+  branch seen to require no check arms nothing and leaves the PR open for a person (#274) —
+  how to check on the run, how to stop
+  it (`run cancel` after the process, never before), and the honest boundary: this is the
+  happy path without a person, and a run a person signs is a different configuration. The
+  same block, six lines, in the README quick start and both quickstarts; `docs/guide/10` has
+  its switches, its flags and its cheat sheet brought up to `--until-done`, `--questions`,
+  `--ship`, `--gates none` and `_scoped`, and drops a sentence that predated the engine's own
+  gate signer; the seed authoring rules — one claim per bullet, ~200 characters with the
+  citation, token last, `path:line` that exists, `"; "` between sources, the four What
+  headings, a `Recommended:` line per question, `.tldrx/seeds/<nn>-<slug>.md` — are in
+  `docs/guide/05` and in the site section, measured against `markdownClaims.ts` and
+  `srcToken.ts` rather than remembered. `run auto` examples in the guides now say `--run <id>` (the generated flag reference keeps its positional form), the
+  spelling under which a bare `--until-done` cannot mistake the id for its count. The ES
+  landing page links the release notes, which stay English and generated (a translated copy
+  would be the second copy `gen-changelog.ts` exists to prevent); the untranslated `TLDRX_UI`
+  row on the ES flags page is generated from `gen-cli.ts`'s English-by-design env table and
+  was left alone.
+### Fixed
+
+- **The dependency frontier is the sequential path's too — nothing fans out over a story a dead
+  developer parked (#263).** Measured on a field run (2026-09-12, `run auto --yolo`): S3's
+  developer died on its own cap, `parkDeveloperFailure` put the story back at `todo` — deliberate,
+  a transport failure settles nothing about the work — and one second later the next wave started
+  S4, whose front matter says `depends_on: [S3]`. S4 reached `done` on an epic branch S3 had put
+  no line of code on, which is an audit record lying in the dangerous direction: a gate signer
+  reads `done` over work that was never delivered. #260 had already built the check that answers
+  this (`blockingDependency`: any dependency that is not `done` holds a story, and the story is
+  written `blocked` with the reason rather than left quietly at `todo`) and switched it on for
+  `--parallel N` only, on the grounds that the sequential loop had no defect of its own. It had
+  this one, and `lanes === 1` is the default and what `run auto` runs. Re-measured at 017dda8
+  before the change, one fixture, one field moved: at `--parallel 2` the dependent is held with
+  the reason `dependency S1 is not done` on `gate.requested`; at the default it is built and
+  reported `done`. Now the same one derivation is asked on every N — no second copy of the rule,
+  and #260's own direction is kept: a story that depends on nothing still runs after a parked one.
+  The park itself, the cap arithmetic and the DoD-decides half of #277 are all untouched.
+
+- **The plan's per-story price is a ceiling now, not a wall — and a story that dies on it with
+  work in its tree lets the DoD decide (#277).** We shipped this one ourselves, hours earlier:
+  #264 landed in 0.18.1 and made the Build executor actually read `03-plan/budget.yml`'s
+  per-story prices. Before it nothing did, so the number was decorative and every story got the
+  uniform stage share; from #264 on it became the hard ceiling of the developer's turn, at
+  `price ÷ (1 + reviewer_share)` = **0.8 × price** — a figure a planner writes before it has
+  read a line of the repo. The session running two live unattended runs on 0.18.1 measured the
+  consequence (their measurement, not this repo's suite): stories died mid-change on caps a
+  dollar or three wide, were left `todo` having spent real money, their dependants went
+  `blocked`, and both runs stalled with nothing delivered — the real cost of a story spanning
+  roughly an order of magnitude above what the planner had estimated. Two changes, one issue.
+  **The cap is now `max(price × story_cap_multiplier, story_cap_floor_usd)`** — defaults 3 and
+  $4.00, both new optional `stage.yml` keys alongside `attempts:` and `reviewer_share:`
+  (`schemas/stageTuning.ts`), refused by name out of range rather than clamped. 3 NARROWS
+  that gap for the low and middle of the range and does not close it: over the prices the
+  planner writes today ($1.20-$4.00) the ceiling lands at $4.00-$12.00, so a story at the
+  top of the observed spread still dies on it — **a story still dies on its cap whenever
+  its real cost exceeds `max(price x 3, $4.00)`**, which is the figure to check before
+  recalibrating. The expensive end is carried by the OTHER half below, not by the
+  multiplier: the work is committed and measured instead of lost. What neither half covers
+  — a stage still reporting `done` over a story that died — is #263, out of scope here. 3
+  is chosen against that division of labour and against keeping one story's worst case
+  legible in its stage; the floor is the developer-side sibling of
+  `REVIEWER_FLOOR_USD` ($1.00) and is a small multiple of it, because the developer reads the
+  repo, edits it, runs the story's whole DoD suite and commits where the reviewer reads one
+  diff. The error here is not symmetric — a price set too low costs a dead story plus
+  everything already paid for it, one set too high costs only the difference on work that lands
+  — so the arithmetic is deliberately allowed to over-run a single estimate and the STAGE's own
+  budget gate, metered against real spend, is what stops a stage that runs out.
+  **Derived at DISPATCH, off the price as it sits on disk, with no migration of `budget.yml`:**
+  that is load-bearing rather than tidy, because runs already in flight carry prices written by
+  an older planner and only a dispatch-time derivation covers them the moment this is installed.
+  `gh #91`'s property survives intact — attempt 1 is the pass the plan priced and gets the whole
+  ceiling, the contingency attempt after it gets an `attempts`-th — and the reviewer's share,
+  which never came out of the developer's ceiling in the first place, is untouched and now
+  visibly additive. The brake's mirror in `budget/remainingWork.ts` moves in step, pinned as
+  ever by `test/remaining-work.test.ts`. **And a developer killed by that ceiling with work in
+  its tree no longer parks the story `todo`:** it is a story with a diff and no verdict, so the
+  facilitator's own Definition of Done decides it — #271's rule over a second cause, the same
+  `workSince` tree comparison (committed or not, `tldrx-work/` and `.tldrx/` excluded), the same
+  "the cause is recorded either way". The death is named in words with its figure on the story's
+  review log, on its `task.done` (`budget_death:`, additive) and in the handoff's `## Unknowns`;
+  a red DoD blocks with both reasons on the row; a cap death that left no work still parks the
+  story exactly where it was, unchanged since 2026-08-30. The narrowing to a CAP death is
+  deliberate: a spawn that never started or a transport fault says nothing about a tree, while
+  `Reached maximum budget` says precisely that the turn was working when it stopped. The Plan
+  schema contract now tells the planner the price is a ceiling and to budget the expensive case
+  rather than the expected one — it is pricing before reading the code, which is exactly when an
+  estimate is least worth trusting. What this does NOT fix: a stage that still reports `done`
+  while a story died on its cap is #263, measured and filed separately, and is left untouched
+  here.
+
+- **`--ship merge` no longer arms an auto-merge over a base that requires nothing (#274).**
+  Measured on the zero-touch proof run (a field workspace, `--gates none --ship merge`, no human
+  in the loop): the PR merged at `06:20:14Z` while all four of its check runs were still pending
+  — they had started at 06:20:12/06:20:16/06:20:28 and completed between 06:21:38 and 06:24:56,
+  every one of them AFTER the merge — and the ship record said `queued — GitHub merges when its
+  checks pass`. The mechanism is a gap between two different sets: the guard counted the checks
+  the PR REPORTED (`gh pr view --json statusCheckRollup`), while `gh pr merge --auto` hands the
+  wait to GitHub's auto-merge, which waits on the base branch's REQUIREMENTS. That workspace's
+  `main` had none (`gh api …/branches/main/protection` → 404 `Branch not protected`), so `--auto`
+  did not mean "merge when green", it meant "merge now", and the ledger recorded a red-eligible
+  suite as merged on green — a record lying in the dangerous direction (§7). `ship` now asks the
+  BASE what it requires before arming anything: `repos/{owner}/{repo}/rules/branches/<base>` for
+  rulesets (repository and organization level) and, when that finds none,
+  `repos/{owner}/{repo}/branches/<base>/protection` for classic branch protection. Nothing is
+  armed without a requirement actually SEEN — `merge: absent — the base branch requires no check
+  before merge` when both were read and hold nothing back, and `absent — could not tell what the
+  base branch requires` when a probe could not be read, because for a merge "I could not tell" has
+  to behave like "there is nothing to wait on". A requirement imposed by a mechanism neither probe
+  can see (a merge queue, an org policy this token cannot read) reads as "requires nothing" and so
+  arms NOTHING: the residual gap can only ever cost a merge that was not armed, never a merge that
+  should not have happened. The `queued` sentence now says what `--auto` actually waits on — the
+  base's REQUIRED checks. Two edges of the probe are closed on the same side: a rule that arrives
+  carrying an `enforcement` other than `active` is a dry run and is not counted as a requirement
+  (GitHub already filters `evaluate`/`disabled` server-side and the response carries no such field
+  — measured against the official REST description — so this is belt-and-braces, and its absence is
+  read as that documented filter rather than as "unknown", which would refuse to arm on every real
+  repo); and only a 404 whose body reads `Branch not protected` means "no classic protection" — a
+  branch or a repo that is not there answers 404 too, and reading that as "requires nothing" would
+  arm a merge against a base nobody identified.
+
 ## 0.18.1 — 2026-09-13
 
 ### Added

package/README.md

@@ -41,6 +41,21 @@ tldrx run new payments --scope feature --seed docs/payments/ --budget 25
 tldrx run auto            # `next`, over and over, until something actually needs you
 ```
 
+Or hand a small, well-seeded change to the engine with nobody watching — measured once: a one-story
+bugfix went from seed to merged PR in 45 minutes with no human input:
+
+```bash
+tldrx run new login-timeout --scope bugfix --seed .tldrx/seeds/01-login-timeout.md \
+  --gates none --questions none --ship pr --budget 40
+nohup tldrx run auto --run <id> --until-done --max-usd 40 \
+  --wait-answers 8h --wait-gates 8h --notify-every 30m --ui plain > /tmp/<id>.log 2>&1 &
+```
+
+`--gates none` lets every gate sign itself, `--questions none` lets the loop take each question's own
+`Recommended:` pick, `--ship pr` opens the PR when the run is done. What each flag means, how to write
+the seed, how to check on it and how to stop it:
+[Zero-touch run, start to finish](https://ederwii.github.io/tldr-experts/guides/unattended-operation#zero-touch-run-start-to-finish).
+
 **To run it: Node ≥ 20, and nothing else** — the published package is a pre-built bundle with
 zero runtime dependencies, and `dist/` is a Node bundle (Bun runs it too, if you have it).
 **To build or contribute: Bun ≥ 1.3**, which compiles that bundle and runs the test suite.
@@ -316,6 +331,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.18.2 | 2026-09-13 | `beta` | three things measured on the first fully unattended run and on the live runs that followed it, one of them a regression 0.18.1 shipped hours earlier: `--ship merge` armed GitHub's auto-merge over a base that required nothing — the guard counted the checks the PR REPORTED while `--auto` waits on the base's REQUIREMENTS, so a proof run's pull request merged at 06:20:14 while all four of its checks finished between 06:21:38 and 06:24:56, and the record said `queued — GitHub merges when its checks pass`; ship now asks the base what it requires through rulesets and classic protection, names its three absences apart, and every unreadable answer arms nothing; the plan's per-story price had become a hard wall at 0.8x the planner's guess once 0.18.1 made those fields actually read, killing stories mid-flight at $1.28 and $3.25 against real costs an order of magnitude higher, so the ceiling is now `max(price x 3, $4.00)` derived at DISPATCH from the budget as it sits on disk — a run already in flight is covered without migrating anything — and, the half that carries the expensive end, a developer that dies on its cap with work in its tree commits it and lets the Definition of Done decide instead of parking the story, the same authority #271 gave a refused one; and the zero-touch recipe is written down where a person looks for it, seed file to backgrounded loop, on the README quick start and both documentation sites, with the honest boundary that this is the happy path without a person |
 | 0.18.1 | 2026-09-13 | `beta` | five things a run could not survive on its own, every one measured on the unattended proof runs that followed 0.18.0 rather than reasoned about: a priced plan was never priced — the planner wrote `stories[].estimate_usd` and Build read only `per_phase_usd` + `spent_usd`, so every story got the same $5.40 cap while the plan said $28, and the contract now names the shape and the plan check refuses a budget.yml that does not carry it; a headless refusal under a host-tokens ceiling wrote nothing to the ledger, so `--until-done` relaunched over a refusal it could not see, and now writes its `budget.blocked` first; a developer that had committed its work and was then refused a compound verification command was blocked BEFORE the facilitator ran the Definition of Done, so the DoD now decides when there is work and the refusal is recorded either way, with the prompt saying to run each DoD command verbatim and alone because shell separators split a line into subcommands that each need their own grant; a workspace can declare `<slot>_scoped` DoD commands that run per story on the paths it touched with the full suite once per epic head, after the full suite was measured running three times per story attempt; and a cancelled run no longer leaves an epic branch that refuses the ordinary retry — `run cancel` releases it and Build renames aside an epic whose owner run is closed, while an open or unknown owner still refuses verbatim and an uncounted branch is never deleted |
 | 0.18.0 | 2026-09-13 | `beta` | the release that lets an unattended run survive its own accidents and end somewhere, every item measured on live runs at 0.16.1 rather than reasoned about: a turn that wrote a lot of files could not be RECORDED — an `agent.result` whose `outputs` field held 3924 bytes of run-relative paths blew the 4096-byte event cap through a RAW append that never reached the capped seam, the throw landed one line after the try/catch built for exactly this and came out as exit 1, which `--retry-failed` does not retry since its branch keys on exit 5, so a loop told to survive two failures survived zero, and the epic branch had been cut on disk one line before the throw with the save after it, leaving the relaunch to read its own epic as a stranger's; `outputs` is now named by COUNT with the full list written beside the event rather than truncated, all four raw appends route through the capped seam at module scope, a throw while recording fails the STAGE with exit 5 saying how many of how many rows landed, the claim is saved the moment it is earned, and `capPayload` still knows its two fields BY NAME — a third growable field has to be taught to it deliberately or it is refused whole; Build entry now proves the Definition of Done can run IN A WORKTREE before a developer is paid, after 18 h from `run auto` to the first story that could run on one workspace, five relaunches, because the repo's `install:` named a file that existed in the human's checkout and was never committed and `git worktree` carries TRACKED FILES ONLY, so every story failed identically after the story was opened and immediately before the paid turn while the base pre-flight was green and right to be, measuring in the checkout where the file is — one throwaway worktree at the base sha, the install run inside it, each DoD command's first token resolved there, NEVER the suite, refusal exit 2 naming the exact path or binary, cached under an additive `worktree:` key narrowed by base sha, declaration hash and AGE (six hours for a green, because the row is a claim about an ENVIRONMENT that no sha contains; the base red's 30 minutes for a red), and costing zero where it could learn nothing; where the two readings could not be told apart it deliberately refuses LESS — a path named by a `dod` command after the first may be an artefact an earlier one builds, so that is an advisory and not a verdict; one blocked story no longer stops every later wave, after a loop told to build 8 stories built 5, never started 3, and reported the stage `done`, twice on the same run, because the parallel path asked only "did any story block" and `depends_on` appeared ZERO times in the Build executor — a story now runs when every one of its `depends_on` is `done`, one held back is `blocked` WITH the reason `dependency S7 blocked` (transitive for free) which is what the gate's `blocked_reason` and the continue note read, the stage line counts every story `waves.yml` scheduled rather than the rows the executor happened to hold, and a scheduled story with no outcome at all is named in `## Unknowns` instead of dropped, while `--parallel 1` is untouched on purpose — a story whose dependency blocked is still attempted there, and changing that would be a second change in the opposite direction; the spawned developer can now delete and rename paths in its own tree, after a story that was simply "delete an unused file" proved undoable — nothing in the allowance could unlink a path or take it out of the index, so every `git rm` came back needing approval nobody was there to give, the refused turn exited 0 with an envelope, the DoD ran green on an untouched tree and the reviewer faulted a diff that was never written, twice — the file-lifecycle git verbs are granted as index operations on the story's OWN tree (never a bare `rm`, `git push` still asserted absent), and a tool call refused for approval now BLOCKS the story at once with the command and why, reaching the story file, the handoff and the gate, so the next missing verb costs one attempt instead of two and nothing; that detector reads a structural field first and the English refusal sentence only as a fenced fallback, because pre-merge review measured the unfenced version reading a plain file-read of a document CONTAINING the phrase as a refusal — this very CHANGELOG is one of them — and a refusal carrying neither signal is a miss taken on purpose, with the sentence half depending on prose the host can change without notice; a fix-list finding now declares what it IS, after three stories with a green definition of done, a merged commit and an APPROVING reviewer settled `blocked`, each on a `fix-now` finding whose whole content was a stale docstring or a citation that did not resolve — the reviewer was not wrong and `severity` was never the vehicle (a free string NO consumer read, one render site under `src`), so a required `kind` splits behaviour from text: `correctness` and `security` hold the story exactly as before, a `docs`/`style` finding submitted `fix-now` is routed to `defer-with-log` with a `Normalised-from:` line, and because this makes a gate WEAKER on purpose the unblocking is priced — declaring a finding `docs` costs the SAME `[src: …]` citation that refuting one already costs, a `kind` that is absent or outside the enum is refused for free and indexed as a fault so it costs the story no attempt, a fix list already on disk with no `Kind:` line reads as not stated and not stated blocks, and the four reviewer-prompt goldens MOVED because the schema alone would have left a reviewer nobody told about the field; `run.yml` can finally explain its own `cost_usd` — a row read `input_tokens: 84, output_tokens: 37150, cost_usd: 1.98` for a 124 KB prompt while the provider reported 4,911,750 cache reads for that same turn, and across 101 transcripts in one workspace cache reads were 97.3% of the input side against a column that saw 0.002% of it — the counters were parsed on every turn and thrown away one function later, and the half the issue did not know about is that the executor path's `agent.result` emitted NO `usage` at all, so every Build and Watch turn lost all four counters and the whole Build was priced off zeroes (measured: zero `usage` lines across the four frozen goldens with ten `agent.result` among them); they are recorded additively and gated one at a time rather than both-or-nothing, `turnTokens` names them while deliberately reading neither so the exclusion is a decision on the record, nothing displayed changed — the dashboard and `tldrx cost` are byte-identical — and a row from before this reads absent, since nothing reconstructs a counter nobody wrote down; a gate about to sign itself is no longer sent as a Yes/No the owner cannot answer, after 3 of 3 questioned stages on two live workspaces sent the prompt 600 ms after the last answer and self-signed on the very next poll, so the one tap it invited ran `approve` on an already-approved gate and, because the in-wait approval fell between two notify windows, the bridge kept the prompt open and re-mentioned its owner every escalate tick for two hours — the release now asks the gate's CONDITIONS through the same re-evaluation the poll uses, extracted so neither can form a second opinion, sends nothing when there is no decision to take and says which stage and why on stdout instead of going quiet, and words a genuinely held gate from that one reading so a payload can no longer name four open questions beside `holding: "none"`; and three things a run could not do before: it can end in a pull request toward main on purpose, frozen at `run new --ship` with `push`, `pr` or `merge` into an additive `run.yml` block and not a sixth phase, pushed through the ONE push wrapper in the codebase with a PR that reports NO check left open and recorded as `merge: absent — no checks to wait on` because auto-merge over nothing to wait on is a merge now rather than a merge when green — pre-merge review caught the first version erasing a recorded merge failure with an empty string and exit 0, and the emitter dropped the whole block until it was taught the key; `questions_policy: recommended` answers a blocking question that carries its own `Recommended:` line and escalates the ones that do not, after 10 owner questions across two headless runs ($89.82 over 28 h and $26.38 over 5.6 h, the agents busy 4.9 h and 56 min of it) parked the loop on 9 that already held the pick in a parsed field, writing `decided_by: agent-default` as a THIRD value beside owner and driver because `owner` there would be an audit record lying in the dangerous direction, and never inventing a pick — no line, a letter naming no option, or a block marked irreversible or money escalates exactly as before; and `run auto --until-done [<n>]` relaunches the loop in-process after an exit it can do nothing else with, at most `n` times (default 5), after five hand relaunches and 18 h before a story ran — never over a person's exit 4, never over a budget block since nothing in-process moves a ceiling, never twice over the same last line, with the run id and the spend baseline pinned across relaunches so `--max-usd` still describes the one command a person typed; the epic-claim-at-cut half of that issue lives in the Build executor and is NOT fixed here |
 | 0.17.0 | 2026-09-12 | `beta` | three things the framework knew and recorded wrongly, each found by reading its own records rather than by using it: a gate notification now carries the condition HOLDING the gate as data instead of leaving it to be guessed from the text of the command it suggests — `holding` says questions, stories or nothing-mechanical, and when a story is blocked with a recorded reason the payload also hands over a ready-made rejection that lets the loop carry on, with the note DERIVED from the blocked story rather than canned, because a rejection's note is fed to the next turn's prompt and a generic one would hand that turn an empty instruction, so when no reason can be derived the offer is absent rather than invented; the emitted command keeps a literal placeholder and never interpolates the reason, which keeps the quoting hazard out of the record and puts it where a substituting client can see it; `run status` stopped printing more money left than it had ceiling — the run ceiling now has ONE live copy, read from `budget.yml` by every live screen, and `run.yml`'s mirror is documented as the creation value and no longer written by a raise, since the break was never that a raise failed to write the mirror but that an ordinary concurrent save carried a stale copy over it, and the fix was to delete the half-sync rather than to build a better one — pre-merge review caught the first version pairing a LIVE spend with that now-frozen ceiling inside `tldrx replay`, which would have reproduced the same impossible line in a different command on every run whose budget had been raised, measured on the real CLI as `$12.00 spent of $10.00 ceiling` with no concurrency required; and a task row now records the ROLE its turn actually ran under, where every Build turn had been filed as the developer including the reviewer's — the role was known at spawn and written to the event stream, and was dropped on the way to the ledger, so the audit record named the wrong actor for work it had itself measured; the new key is additive and written on EVERY row including the developer's, because a role present only on reviewers would make its absence mean developer-or-not-recorded and send a reader back to inferring the role from an absence, which is the guess the change exists to remove |

package/dist/hooks/answer-capture.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-1tynpxvm.js";
+} from "./chunk-nf2j945p.js";
 import {
   FactsStore,
   formatJaccard
@@ -13,11 +13,11 @@ import {
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-x64paqbg.js";
+} from "./chunk-gx6qa496.js";
 import {
   PHASE_IDS
-} from "./chunk-bgxj40rr.js";
-import"./chunk-zg7q0q4y.js";
+} from "./chunk-x00a2vaz.js";
+import"./chunk-4y3pk4n2.js";
 import"./chunk-vf992pfw.js";
 import {
   ADVISORY_KEY,

package/dist/hooks/budget-gate.js

@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-ct7kazfy.js";
+} from "./chunk-wx1jce1t.js";
 import {
   EventLog
-} from "./chunk-x64paqbg.js";
+} from "./chunk-gx6qa496.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -35,7 +35,7 @@ import {
   renderRunEconomies,
   runSpend
 } from "./chunk-hwsng0xq.js";
-import"./chunk-zg7q0q4y.js";
+import"./chunk-4y3pk4n2.js";
 import {
   noteDeprecations
 } from "./chunk-8ak5kwd5.js";

package/dist/hooks/{chunk-zg7q0q4y.js → chunk-4y3pk4n2.js}

@@ -66,13 +66,17 @@ var STAGE_TUNING_DEFAULTS = {
   attempts: 2,
   fixlistRounds: 1,
   reviewerShare: 0.25,
-  gateSignerShare: 0.25
+  gateSignerShare: 0.25,
+  storyCapMultiplier: 3,
+  storyCapFloorUsd: 4
 };
 var STAGE_TUNING_RANGES = {
   attempts: { key: "attempts", min: 1, max: 5, integer: true },
   fixlistRounds: { key: "fixlist_rounds", min: 0, max: 3, integer: true },
   reviewerShare: { key: "reviewer_share", min: 0, max: 1, integer: false },
-  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false }
+  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false },
+  storyCapMultiplier: { key: "story_cap_multiplier", min: 1, max: 20, integer: false },
+  storyCapFloorUsd: { key: "story_cap_floor_usd", min: 0, max: 200, integer: false }
 };
 var FIELDS = Object.keys(STAGE_TUNING_RANGES);
 function inTuningRange(range, value) {

package/dist/hooks/{chunk-rmpcrt4c.js → chunk-afttzftj.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-ct7kazfy.js";
+} from "./chunk-wx1jce1t.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -21,7 +21,7 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-x64paqbg.js";
+} from "./chunk-gx6qa496.js";
 import {
   cursorStage,
   isAttendedByHostView,

package/dist/hooks/{chunk-x64paqbg.js → chunk-gx6qa496.js}

@@ -2,7 +2,7 @@ import {
   GATE_POLICIES,
   validateGatesPolicy,
   validateStagePolicy
-} from "./chunk-zg7q0q4y.js";
+} from "./chunk-4y3pk4n2.js";
 import {
   asDocument,
   isRecord,

package/dist/hooks/{chunk-1tynpxvm.js → chunk-nf2j945p.js}

@@ -5,7 +5,7 @@ import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-x64paqbg.js";
+} from "./chunk-gx6qa496.js";
 import {
   openBlocks,
   parseQuestions

package/dist/hooks/{chunk-ct7kazfy.js → chunk-wx1jce1t.js}

@@ -1,6 +1,6 @@
 import {
   STAGE_TUNING_DEFAULTS
-} from "./chunk-zg7q0q4y.js";
+} from "./chunk-4y3pk4n2.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
@@ -968,8 +968,10 @@ function looksLikeSpawnError(detail) {
 var MAX_ATTEMPTS = STAGE_TUNING_DEFAULTS.attempts;
 var REVIEWER_SHARE = STAGE_TUNING_DEFAULTS.reviewerShare;
 var REVIEWER_FLOOR_USD = 1;
-function developerPriceDivisor(attempt, attempts = MAX_ATTEMPTS, reviewerShare = REVIEWER_SHARE) {
-  return attempt <= 1 ? 1 + reviewerShare : attempts * (1 + reviewerShare);
+var STORY_CAP_MULTIPLIER = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function developerAttemptDivisor(attempt, attempts = MAX_ATTEMPTS) {
+  return attempt <= 1 ? 1 : attempts;
 }
 function remainingWork(input) {
   try {
@@ -1094,7 +1096,7 @@ class CapMath {
     const price = this.priceOf(storyId);
     if (price === null)
       return this.agentCap(1 / this.worstCaseShares());
-    return this.agentCap(this.shareOf(price / developerPriceDivisor(attempt, this.attempts(), this.reviewerShare())));
+    return this.agentCap(this.shareOf(this.storyCeiling(price) / developerAttemptDivisor(attempt, this.attempts())));
   }
   reviewer(storyId) {
     const price = this.priceOf(storyId);
@@ -1103,6 +1105,11 @@ class CapMath {
     const floor = Math.min(REVIEWER_FLOOR_USD, Math.max(this.input.stageBudgetUsd - this.input.stageSpentUsd, 0));
     return round2(Math.min(Math.max(derived, floor), this.maxBudgetUsd));
   }
+  storyCeiling(price) {
+    const declared = this.input.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD;
+    const floor = this.input.stageBudgetUsd > 0 ? Math.min(declared, this.input.stageBudgetUsd) : declared;
+    return Math.max(price * (this.input.storyCapMultiplier ?? STORY_CAP_MULTIPLIER), floor);
+  }
   priceOf(storyId) {
     const price = this.prices.get(storyId);
     if (price === undefined || !Number.isFinite(price) || price <= 0)

package/dist/hooks/{chunk-bgxj40rr.js → chunk-x00a2vaz.js}

@@ -3,7 +3,7 @@ import {
   STAGE_TUNING_DEFAULTS,
   parseWorkflowGates,
   readStageTuning
-} from "./chunk-zg7q0q4y.js";
+} from "./chunk-4y3pk4n2.js";
 import {
   PROJECT_FRAMEWORK_DIR,
   STAGES_DIR,

package/dist/hooks/dod-gate.js

@@ -20,11 +20,11 @@ import"./chunk-pday823f.js";
 import {
   DEFAULT_TIMEOUT_S,
   buildStageDefaults
-} from "./chunk-bgxj40rr.js";
+} from "./chunk-x00a2vaz.js";
 import {
   loadRunView
 } from "./chunk-hwsng0xq.js";
-import"./chunk-zg7q0q4y.js";
+import"./chunk-4y3pk4n2.js";
 import {
   DodCommandRefused,
   loadWorkspace,

package/dist/hooks/session-start.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-1tynpxvm.js";
+} from "./chunk-nf2j945p.js";
 import"./chunk-kwaqdq9w.js";
 import {
   allow,
@@ -20,22 +20,22 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-rmpcrt4c.js";
+} from "./chunk-afttzftj.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-ct7kazfy.js";
+} from "./chunk-wx1jce1t.js";
 import {
   isFinished
-} from "./chunk-x64paqbg.js";
-import"./chunk-bgxj40rr.js";
+} from "./chunk-gx6qa496.js";
+import"./chunk-x00a2vaz.js";
 import {
   openRunViews
 } from "./chunk-hwsng0xq.js";
-import"./chunk-zg7q0q4y.js";
+import"./chunk-4y3pk4n2.js";
 import"./chunk-vf992pfw.js";
 import {
   openBlocks,

package/dist/hooks/statusline.js

@@ -2,12 +2,12 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-rmpcrt4c.js";
-import"./chunk-ct7kazfy.js";
-import"./chunk-x64paqbg.js";
-import"./chunk-bgxj40rr.js";
+} from "./chunk-afttzftj.js";
+import"./chunk-wx1jce1t.js";
+import"./chunk-gx6qa496.js";
+import"./chunk-x00a2vaz.js";
 import"./chunk-hwsng0xq.js";
-import"./chunk-zg7q0q4y.js";
+import"./chunk-4y3pk4n2.js";
 import"./chunk-vf992pfw.js";
 import"./chunk-8ak5kwd5.js";
 import {

package/dist/tldrx.js

@@ -11893,6 +11893,8 @@ function renderSeedHandoff(input) {
 var SHIP_LEVELS = ["push", "pr", "merge"];
 var AUTO_MERGE_POLICIES = ["never", "checks"];
 var NO_CHECKS_TO_WAIT_ON = "absent — no checks to wait on";
+var NO_REQUIRED_CHECKS = "absent — the base branch requires no check before merge";
+var REQUIREMENTS_UNREADABLE = "absent — could not tell what the base branch requires";
 var MERGE_QUEUED = "queued";
 
 class ShipPolicyError extends Error {
@@ -12404,13 +12406,17 @@ var STAGE_TUNING_DEFAULTS = {
   attempts: 2,
   fixlistRounds: 1,
   reviewerShare: 0.25,
-  gateSignerShare: 0.25
+  gateSignerShare: 0.25,
+  storyCapMultiplier: 3,
+  storyCapFloorUsd: 4
 };
 var STAGE_TUNING_RANGES = {
   attempts: { key: "attempts", min: 1, max: 5, integer: true },
   fixlistRounds: { key: "fixlist_rounds", min: 0, max: 3, integer: true },
   reviewerShare: { key: "reviewer_share", min: 0, max: 1, integer: false },
-  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false }
+  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false },
+  storyCapMultiplier: { key: "story_cap_multiplier", min: 1, max: 20, integer: false },
+  storyCapFloorUsd: { key: "story_cap_floor_usd", min: 0, max: 200, integer: false }
 };
 var FIELDS = Object.keys(STAGE_TUNING_RANGES);
 function inTuningRange(range, value) {
@@ -15895,7 +15901,7 @@ var ENTRIES = [
       {
         name: "ship",
         arg: "<push|pr|merge>",
-        meaning: "How far past the LAST gate the framework may carry the epic branch, frozen into run.yml as `ship:` (#253). `push` publishes `epic/<slug>` to origin; `pr` also opens the pull request `tldrx ship` opens; `merge` also arms `gh pr merge --auto --merge`, so the remote's own checks decide — and a PR that reports NO check is left open with `merge: absent — no checks to wait on`, never merged over silence. It runs when `run auto` sees the run close, or when a person types `tldrx ship`. Absent (the default) nothing is pushed and nothing is opened, exactly as before. Every gate is still signed by whoever `--gates` says: an unattended ship is `--gates none --ship merge`, on purpose, and run.yml records both.",
+        meaning: "How far past the LAST gate the framework may carry the epic branch, frozen into run.yml as `ship:` (#253). `push` publishes `epic/<slug>` to origin; `pr` also opens the pull request `tldrx ship` opens; `merge` also arms `gh pr merge --auto --merge`, so the base branch's own REQUIRED checks decide — and it is armed only over a base SEEN to require one (#274): a PR reporting no check, a base requiring none, and a base whose rulesets and branch protection could not be read all leave the PR open with an `absent — …` reason on the record, never merged over silence. It runs when `run auto` sees the run close, or when a person types `tldrx ship`. Absent (the default) nothing is pushed and nothing is opened, exactly as before. Every gate is still signed by whoever `--gates` says: an unattended ship is `--gates none --ship merge`, on purpose, and run.yml records both.",
         values: ["push", "pr", "merge"],
         sub: "new"
       },
@@ -16480,7 +16486,7 @@ var ENTRIES = [
     ],
     exits: [EXIT_OK, EXIT_USAGE, EXIT_GATE_REFUSED, EXIT_NOT_FOUND],
     notes: [
-      "It pushes ONLY when the run says so. Publishing a branch is a decision, so by default a branch the remote has not seen is a refusal that names the `git push` command rather than running it. The decision is taken once, at `tldrx run new --ship <push|pr|merge>` (#253): then this verb pushes the epic first, through the one push wrapper in the codebase (the Build phase itself still has none, spec §5), and under `merge` arms `gh pr merge --auto --merge` after the PR opens — unless the PR reports NO check at all, in which case it is left open and run.yml says `merge: absent — no checks to wait on`. `run auto` calls this verb when it sees the run close and skips a run whose record already carries `shipped_at`; typing `tldrx ship` again is the recovery after a partial failure — a repo whose merge is recorded `failed` is armed again, one recorded `queued` is left alone, and the record is the union, so a recorded failure is never erased. A run without the block is never written.",
+      "It pushes ONLY when the run says so. Publishing a branch is a decision, so by default a branch the remote has not seen is a refusal that names the `git push` command rather than running it. The decision is taken once, at `tldrx run new --ship <push|pr|merge>` (#253): then this verb pushes the epic first, through the one push wrapper in the codebase (the Build phase itself still has none, spec §5), and under `merge` arms `gh pr merge --auto --merge` after the PR opens — unless the PR reports NO check at all, or the BASE branch was not seen to require one (#274: `--auto` waits on the base's requirements, not on the PR's reported checks, so over a base that requires nothing it merges at once), in which case the PR is left open and run.yml says which absence it was. `run auto` calls this verb when it sees the run close and skips a run whose record already carries `shipped_at`; typing `tldrx ship` again is the recovery after a partial failure — a repo whose merge is recorded `failed` is armed again, one recorded `queued` is left alone, and the record is the union, so a recorded failure is never erased. A run without the block is never written.",
       "The body is WRITTEN for a PR (#167): an **Outcome** line saying how much of the plan landed (`partial: 1 of 3 stories delivered; S2 — …`); what shipped and what did not, from the handoff's own done/not-done split; the reviewer findings still open, read from the run's fix lists; and the LAST phase handoff the run has on disk — `04-build/handoff.md` on a run that built something — verbatim and complete, inside a `<details>` block. It goes to `gh` as a file, never as an argument, so a long body cannot overflow an argv limit.",
       "It REFUSES a run that delivered no story (exit 1 — nothing behind it, #210). `ship` already knew: the body it renders keeps only the handoff bullets that say `done`, and with none it wrote `(nothing settled `done` in this run)` into a PR it opened anyway. The refusal names the counts and the first blocked story's own reason, and `--dry-run` is refused in the same words. A run that delivered at least one story ships exactly as it did before.",
       "It moves no gate and no cursor and appends no event. On a run with no `ship:` block it never writes to the run at all; on a run with one it writes exactly that block's record (`pr_urls`, `merge`, `merges`, `shipped_at`) and nothing else. To mirror the plan's epics and stories to a ticket tool, `tldrx tickets sync` is the verb that does that, and it stays separate.",
@@ -28747,6 +28753,7 @@ function renderReviewLog(outcome) {
     `- Commit: ${outcome.commit ?? "(none)"}`,
     ...outcome.developerError === null ? [] : [`- Developer: **FAILED** — ${outcome.developerError}`],
     ...outcome.permissionRefused == null ? [] : [`- Developer: \`${outcome.permissionRefused}\` was refused for approval by the agent's own ` + "permission layer; the tree held committed work, so the Definition of Done below decided"],
+    ...outcome.budgetDeath == null ? [] : [`- Developer: died on its per-story cap — ${outcome.budgetDeath}; the tree held work, ` + "so the Definition of Done below decided"],
     "",
     "## Definition of done",
     "",
@@ -28833,8 +28840,10 @@ function renderPreviousAttempt(review) {
 var MAX_ATTEMPTS = STAGE_TUNING_DEFAULTS.attempts;
 var REVIEWER_SHARE = STAGE_TUNING_DEFAULTS.reviewerShare;
 var REVIEWER_FLOOR_USD = 1;
-function developerPriceDivisor(attempt, attempts = MAX_ATTEMPTS, reviewerShare = REVIEWER_SHARE) {
-  return attempt <= 1 ? 1 + reviewerShare : attempts * (1 + reviewerShare);
+var STORY_CAP_MULTIPLIER = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function developerAttemptDivisor(attempt, attempts = MAX_ATTEMPTS) {
+  return attempt <= 1 ? 1 : attempts;
 }
 var NAMED_STORIES = 6;
 function remainingWork(input) {
@@ -29004,7 +29013,7 @@ class CapMath {
     const price = this.priceOf(storyId);
     if (price === null)
       return this.agentCap(1 / this.worstCaseShares());
-    return this.agentCap(this.shareOf(price / developerPriceDivisor(attempt, this.attempts(), this.reviewerShare())));
+    return this.agentCap(this.shareOf(this.storyCeiling(price) / developerAttemptDivisor(attempt, this.attempts())));
   }
   reviewer(storyId) {
     const price = this.priceOf(storyId);
@@ -29013,6 +29022,11 @@ class CapMath {
     const floor = Math.min(REVIEWER_FLOOR_USD, Math.max(this.input.stageBudgetUsd - this.input.stageSpentUsd, 0));
     return round22(Math.min(Math.max(derived, floor), this.maxBudgetUsd));
   }
+  storyCeiling(price) {
+    const declared = this.input.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD;
+    const floor = this.input.stageBudgetUsd > 0 ? Math.min(declared, this.input.stageBudgetUsd) : declared;
+    return Math.max(price * (this.input.storyCapMultiplier ?? STORY_CAP_MULTIPLIER), floor);
+  }
   priceOf(storyId) {
     const price = this.prices.get(storyId);
     if (price === undefined || !Number.isFinite(price) || price <= 0)
@@ -29319,6 +29333,7 @@ function renderBuildHandoff(parts) {
   const done = parts.outcomes.filter((o) => o.status === "done");
   const notDone = parts.outcomes.filter((o) => o.status !== "done");
   const refusedButMeasured = done.filter((o) => o.permissionRefused != null);
+  const diedButMeasured = done.filter((o) => o.budgetDeath != null);
   const lines = [
     `# Handoff — 04-build / ${parts.stageId} — run ${parts.runId}`,
     `Stage: ${parts.stageId} · Expert: developer + reviewer · Model: ${parts.model ?? "default"} · ` + `Cost: ${spentFigure({
@@ -29337,9 +29352,10 @@ function renderBuildHandoff(parts) {
     "",
     "## Unknowns",
     "",
-    ...notDone.length === 0 && (parts.carried ?? []).length === 0 && (parts.unreadableStories ?? []).length === 0 && (parts.foreignWork ?? []).length === 0 && (parts.notStarted ?? []).length === 0 && refusedButMeasured.length === 0 ? [`- none — every scheduled story reached \`done\` and no carried finding is unowned ` + `[src: absent:04-build/log]`] : [],
+    ...notDone.length === 0 && (parts.carried ?? []).length === 0 && (parts.unreadableStories ?? []).length === 0 && (parts.foreignWork ?? []).length === 0 && (parts.notStarted ?? []).length === 0 && refusedButMeasured.length === 0 && diedButMeasured.length === 0 ? [`- none — every scheduled story reached \`done\` and no carried finding is unowned ` + `[src: absent:04-build/log]`] : [],
     ...notDone.map((o) => `- ${o.id} is \`${o.status}\` and needs a human: ${o.reason ?? "see the review"} ` + `[src: ${o.reviewRel}:1]`),
     ...refusedButMeasured.map((o) => `- ${o.id}'s developer had \`${o.permissionRefused ?? ""}\` refused for approval by the agent's own ` + `permission layer; its tree held committed work, so the Definition of Done decided and the story is ` + `\`${o.status}\` — a person may still want to know the command it could not run [src: ${o.reviewRel}:1]`),
+    ...diedButMeasured.map((o) => `- ${o.id}'s developer died on its per-story cap (${o.budgetDeath ?? ""}) with work in its tree, ` + `so the Definition of Done decided and the story is \`${o.status}\` — the plan priced this story ` + `below what it cost, which is worth knowing before the next one [src: ${o.reviewRel}:1]`),
     ...(parts.notStarted ?? []).map((row2) => `- ${row2.id} was scheduled and never started, and is still \`${row2.status}\` — ` + `${row2.reason} [src: ${row2.rel}:1]`),
     ...carriedBullets(parts.carried ?? []),
     ...(parts.unreadableStories ?? []).map((row2) => `- a story file could not be read, so its carried findings were not checked: ` + `\`${row2.rel}\` — ${row2.reason} [src: absent:${row2.rel}]`),
@@ -33072,7 +33088,7 @@ var BUDGET_FIELDS = {
   spent_usd: { value: "0", rule: "`0` — nothing priced here has been spent yet" },
   per_phase_usd: {
     value: "{S1: 4.75}",
-    rule: "`<story id>: <usd>`, one entry per scheduled story, every value a number. Keyed by STORY " + "despite the name (the run's own budget.yml keys the same map by phase), and it is the ONLY key " + "anything prices from: a `stories:` list or an `estimate_usd` field validates nothing and prices nothing"
+    rule: "`<story id>: <usd>`, one entry per scheduled story, every value a number. Keyed by STORY " + "despite the name (the run's own budget.yml keys the same map by phase), and it is the ONLY key " + "anything prices from: a `stories:` list or an `estimate_usd` field validates nothing and prices nothing. " + "Each number is a CEILING the story's developer is dispatched under, not a forecast of what it will " + "spend: budget the expensive case, not the expected one. A story that has to read unfamiliar code, " + "run a real test suite and come back from one red is worth several times what a quick edit looks like " + "from here, and stories priced at a couple of dollars are almost always priced too low"
   }
 };
 var EXAMPLE_DOD_COMMAND = "npm run test";
@@ -33222,6 +33238,13 @@ function renderPlanSchemaContract() {
     "",
     ...ruleTable(["version", ...BUDGET_REQUIRED_KEYS], BUDGET_FIELDS),
     "",
+    "Price the EXPENSIVE case. These numbers are read as ceilings, not as estimates: the Build executor",
+    "derives each story's developer ceiling from its price here, so a story priced below what it costs",
+    "dies mid-change having spent the money and delivered nothing, while one priced above it simply",
+    "costs what it costs. The error is not symmetric, so do not write the expected cost — write a high",
+    "percentile of it. You are pricing this before reading the code, which is exactly when an estimate",
+    "is least worth trusting.",
+    "",
     "An optional `economy: host-tokens` at the root says the numbers are tokens, not dollars — it",
     "validates and it prices nothing, because a token figure must never become a dollar cap. Leave",
     "it out when pricing in dollars.",
@@ -36202,8 +36225,10 @@ import { join as join91, relative as relative15 } from "node:path";
 var MAX_ATTEMPTS2 = STAGE_TUNING_DEFAULTS.attempts;
 var REVIEWER_SHARE2 = STAGE_TUNING_DEFAULTS.reviewerShare;
 var REVIEWER_FLOOR_USD2 = 1;
-function developerPriceDivisor2(attempt, attempts = MAX_ATTEMPTS2, reviewerShare = REVIEWER_SHARE2) {
-  return attempt <= 1 ? 1 + reviewerShare : attempts * (1 + reviewerShare);
+var STORY_CAP_MULTIPLIER2 = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD2 = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function developerAttemptDivisor2(attempt, attempts = MAX_ATTEMPTS2) {
+  return attempt <= 1 ? 1 : attempts;
 }
 var DEFAULT_PARALLEL = 1;
 function clampParallel(requested) {
@@ -36214,6 +36239,12 @@ function clampParallel(requested) {
 function attemptsOf(parts) {
   return parts.attempts ?? MAX_ATTEMPTS2;
 }
+function storyCapMultiplierOf(parts) {
+  return parts.storyCapMultiplier ?? STORY_CAP_MULTIPLIER2;
+}
+function storyCapFloorOf(parts) {
+  return parts.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD2;
+}
 function reviewerShareOf(parts) {
   return parts.reviewerShare ?? REVIEWER_SHARE2;
 }
@@ -36224,7 +36255,11 @@ function developerCap(parts, storyId, attempt = 1) {
   const price = priceOf(parts, storyId);
   if (price === null)
     return parts.agentCap(1 / worstCaseShares(parts));
-  return parts.agentCap(shareOf(parts, price / developerPriceDivisor2(attempt, attemptsOf(parts), reviewerShareOf(parts))));
+  return parts.agentCap(shareOf(parts, storyCeilingUsd(parts, price) / developerAttemptDivisor2(attempt, attemptsOf(parts))));
+}
+function storyCeilingUsd(parts, price) {
+  const floor = parts.budgetUsd > 0 ? Math.min(storyCapFloorOf(parts), parts.budgetUsd) : storyCapFloorOf(parts);
+  return Math.max(price * storyCapMultiplierOf(parts), floor);
 }
 function reviewerCap(parts, spentUsd, storyId) {
   const price = priceOf(parts, storyId);
@@ -38647,6 +38682,7 @@ class BuildSession {
   tasks = [];
   outcomes = new Map;
   refusals = new Map;
+  capDeaths = new Map;
   epics = new EpicState;
   lines = [];
   counters = new ReviewCounters;
@@ -38696,7 +38732,7 @@ class BuildSession {
           this.lines.push(`  · ${planned.story.id} is already \`${status}\` — left alone`);
           continue;
         }
-        const held2 = this.lanes === 1 ? null : this.blockingDependency(planned);
+        const held2 = this.blockingDependency(planned);
         if (held2 !== null) {
           this.blockOnDependency(planned, held2);
           continue;
@@ -39040,6 +39076,7 @@ class BuildSession {
   async buildHalf(planned) {
     const before = this.statusOf(planned);
     this.refusals.delete(planned.story.id);
+    this.capDeaths.delete(planned.story.id);
     const story = await this.writes.run(() => this.openStory(planned, true));
     await this.writes.run(() => {
       this.ctx.emit("task.started", {
@@ -39066,16 +39103,28 @@ class BuildSession {
     }
     const handed = await headSha(story.worktree);
     const developer = await this.spawnDeveloper(story);
+    const capDeath = developer.error !== null && diedOnCap(developer.error);
+    let budgetDeath = null;
     if (developer.error !== null) {
-      return {
-        story,
-        cost: developer.cost,
-        dod: [],
-        commit: null,
-        failure: null,
-        developerError: developer.error,
-        before
-      };
+      const proven = capDeath && await workSince({
+        workspaceRoot: this.workspace.root,
+        repoDir: story.repoDir,
+        worktree: story.worktree,
+        since: handed
+      });
+      if (!proven) {
+        return {
+          story,
+          cost: developer.cost,
+          dod: [],
+          commit: null,
+          failure: null,
+          developerError: developer.error,
+          before
+        };
+      }
+      budgetDeath = developer.error;
+      this.capDeaths.set(story.planned.story.id, developer.error);
     }
     const spent = developer.cost;
     if (developer.refused !== null) {
@@ -39108,7 +39157,11 @@ class BuildSession {
         cost: spent,
         dod,
         commit: null,
-        failure: developer.refused === null ? why : `${why}; and ${permissionBlockReason(developer.refused)}`,
+        failure: [
+          why,
+          ...developer.refused === null ? [] : [permissionBlockReason(developer.refused)],
+          ...budgetDeath === null ? [] : [capDeathReason(budgetDeath)]
+        ].join("; and "),
         developerError: null,
         before
       };
@@ -39919,6 +39972,7 @@ class BuildSession {
       reviewRel,
       reason: parts.reason,
       permissionRefused: this.refusals.get(id) ?? null,
+      budgetDeath: this.capDeaths.get(id) ?? null,
       rescued,
       cost_usd: parts.cost
     };
@@ -39948,7 +40002,8 @@ class BuildSession {
       commit: parts.commit,
       attempt: story.attempt,
       ...parts.epicBase === null || parts.epicBase === undefined || parts.epicBase === "" ? {} : { epic_base: parts.epicBase },
-      ...outcome.permissionRefused == null ? {} : { permission_refused: outcome.permissionRefused }
+      ...outcome.permissionRefused == null ? {} : { permission_refused: outcome.permissionRefused },
+      ...outcome.budgetDeath == null ? {} : { budget_death: outcome.budgetDeath }
     });
     if (pruning && (rescued === null || rescued.worktree === null)) {
       await removeWorktree(story.repoDir, story.worktree);
@@ -40472,7 +40527,9 @@ class BuildSession {
       maxBudgetUsd: this.ctx.maxBudgetUsd,
       agentCap: this.ctx.agentCap,
       attempts: this.attempts,
-      reviewerShare: this.ctx.spec.tuning.reviewerShare
+      reviewerShare: this.ctx.spec.tuning.reviewerShare,
+      storyCapMultiplier: this.ctx.spec.tuning.storyCapMultiplier,
+      storyCapFloorUsd: this.ctx.spec.tuning.storyCapFloorUsd
     };
   }
   get attempts() {
@@ -40644,6 +40701,12 @@ function developerTools(repoCommands, options = {}) {
 function permissionBlockReason(command2) {
   return `permission — \`${command2}\` was refused for approval by the agent's own permission layer, ` + "and a headless turn has nobody to approve it: the same allowance would refuse it again, " + "so this attempt was not repeated";
 }
+function diedOnCap(error) {
+  return error.includes("Reached maximum budget");
+}
+function capDeathReason(error) {
+  return `the developer died on its per-story cap — ${error}: the ceiling is derived from ` + "`03-plan/budget.yml`'s price for this story, so a story that really costs more than the " + "plan guessed wants a higher price there or a higher `story_cap_multiplier:` on the stage";
+}
 var REVIEWER_TOOLS = ["Read", "Grep", "Glob", "Bash(git diff *)"];
 function summaryOf(envelope) {
   return typeof envelope.summary === "string" ? envelope.summary : "";
@@ -41337,7 +41400,9 @@ function stageRemainingWork(store, options, phaseId, stage2, spec) {
     economy: economyFor(store.budget, phaseId),
     attended: isAttendedByHost(store.run),
     attempts: spec.tuning.attempts,
-    reviewerShare: spec.tuning.reviewerShare
+    reviewerShare: spec.tuning.reviewerShare,
+    storyCapMultiplier: spec.tuning.storyCapMultiplier,
+    storyCapFloorUsd: spec.tuning.storyCapFloorUsd
   });
 }
 async function runExecutor(store, options, phaseId, stageId, spec, notes, executor) {
@@ -42558,7 +42623,7 @@ async function shipOne(options, store, branch, repo, body, excuses, policy) {
   }
   const existing = policy === null ? null : await openPrFor(options, repo, branch);
   if (existing !== null && policy !== null) {
-    const merge2 = await armOrKeep(options, repo, existing, policy, previousMerges(store));
+    const merge2 = await armOrKeep(options, repo, existing, policy, previousMerges(store), base2);
     const record4 = writeShipRecord(store, policy, [existing], { [repo.name]: merge2 }, options.at);
     return {
       code: merge2.startsWith("failed") ? EXIT_GATE_REFUSED : EXIT_OK,
@@ -42587,7 +42652,7 @@ async function shipOne(options, store, branch, repo, body, excuses, policy) {
   ];
   if (policy === null)
     return { code: EXIT_OK, lines };
-  const merge = await armMerge(options, repo, url, policy);
+  const merge = await armMerge(options, repo, url, policy, base2);
   const record3 = writeShipRecord(store, policy, url === null ? [] : [url], { [repo.name]: merge }, options.at);
   return {
     code: merge.startsWith("failed") ? EXIT_GATE_REFUSED : EXIT_OK,
@@ -42602,15 +42667,22 @@ function policyLines(prepared, branch, merge) {
   ];
 }
 function describeMerge(merge) {
-  if (merge === MERGE_QUEUED)
-    return `${MERGE_QUEUED} — \`gh pr merge --auto --merge\`; GitHub merges when its checks pass`;
+  if (merge === MERGE_QUEUED) {
+    return `${MERGE_QUEUED} — \`gh pr merge --auto --merge\`; GitHub merges when the base's REQUIRED checks pass`;
+  }
   if (merge === NO_CHECKS_TO_WAIT_ON)
     return `${NO_CHECKS_TO_WAIT_ON} — the PR stays open for a person`;
+  if (merge === NO_REQUIRED_CHECKS) {
+    return `${NO_REQUIRED_CHECKS} — \`--auto\` would merge at once; the PR stays open for a person`;
+  }
+  if (merge === REQUIREMENTS_UNREADABLE) {
+    return `${REQUIREMENTS_UNREADABLE} — nothing was armed; the PR stays open for a person`;
+  }
   if (merge === "never")
     return "never (ship.auto_merge)";
   return merge;
 }
-async function armMerge(options, repo, url, policy) {
+async function armMerge(options, repo, url, policy, base2) {
   if (policy.auto_merge !== "checks")
     return "never";
   if (url === null)
@@ -42620,16 +42692,21 @@ async function armMerge(options, repo, url, policy) {
     return `failed — could not read the PR's checks: ${checks.detail}`;
   if (checks.count === 0)
     return NO_CHECKS_TO_WAIT_ON;
+  const required = await requiredChecks(options, repo, base2);
+  if (required.kind === "unreadable")
+    return REQUIREMENTS_UNREADABLE;
+  if (!required.required)
+    return NO_REQUIRED_CHECKS;
   const armed = await options.transport.run(GH_BIN, ["pr", "merge", url, "--auto", "--merge"], repo.dir);
   if (armed.exitCode !== 0) {
     return `failed — \`gh pr merge --auto\` exited ${String(armed.exitCode)}` + `${firstLine10(armed.stderr) === "" ? "" : `: ${firstLine10(armed.stderr)}`}`;
   }
   return MERGE_QUEUED;
 }
-async function armOrKeep(options, repo, url, policy, previous) {
+async function armOrKeep(options, repo, url, policy, previous, base2) {
   if (policy.auto_merge === "checks" && previous[repo.name] === MERGE_QUEUED)
     return MERGE_QUEUED;
-  return await armMerge(options, repo, url, policy);
+  return await armMerge(options, repo, url, policy, base2);
 }
 function previousMerges(store) {
   return store.run.ship?.merges ?? {};
@@ -42655,6 +42732,63 @@ async function checksReported(options, repo, url) {
     await new Promise((resolve12) => setTimeout(resolve12, Math.min(SHIP_CHECKS_POLL_MS, grace)));
   }
 }
+var ENFORCEMENT_ACTIVE = "active";
+var BRANCH_NOT_PROTECTED = "Branch not protected";
+var RULES_ENDPOINT = (base2) => `repos/{owner}/{repo}/rules/branches/${base2}`;
+var PROTECTION_ENDPOINT = (base2) => `repos/{owner}/{repo}/branches/${base2}/protection`;
+async function requiredChecks(options, repo, base2) {
+  const rules = await rulesRequireChecks(options, repo, base2);
+  if (rules.kind === "unreadable" || rules.required)
+    return rules;
+  return await protectionRequiresChecks(options, repo, base2);
+}
+async function rulesRequireChecks(options, repo, base2) {
+  const seen = await options.transport.run(GH_BIN, ["api", RULES_ENDPOINT(base2)], repo.dir);
+  if (seen.exitCode !== 0) {
+    return { kind: "unreadable", detail: firstLine10(seen.stderr) || `gh exited ${String(seen.exitCode)}` };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(seen.stdout);
+  } catch {
+    return { kind: "unreadable", detail: "`gh api …/rules/branches` printed something that is not JSON" };
+  }
+  if (!Array.isArray(doc))
+    return { kind: "unreadable", detail: "`gh api …/rules/branches` did not print an array" };
+  const required = doc.some((rule) => {
+    const row2 = rule;
+    if (row2?.type !== "required_status_checks")
+      return false;
+    if (row2.enforcement !== undefined && row2.enforcement !== ENFORCEMENT_ACTIVE)
+      return false;
+    const contexts = row2.parameters?.required_status_checks;
+    return Array.isArray(contexts) && contexts.length > 0;
+  });
+  return { kind: "read", required };
+}
+async function protectionRequiresChecks(options, repo, base2) {
+  const seen = await options.transport.run(GH_BIN, ["api", PROTECTION_ENDPOINT(base2)], repo.dir);
+  let doc;
+  try {
+    doc = JSON.parse(seen.stdout);
+  } catch {
+    doc = null;
+  }
+  if (seen.exitCode !== 0) {
+    const body = doc;
+    const notProtected = String(body?.status ?? "") === "404" && body?.message === BRANCH_NOT_PROTECTED;
+    if (notProtected)
+      return { kind: "read", required: false };
+    return { kind: "unreadable", detail: firstLine10(seen.stderr) || `gh exited ${String(seen.exitCode)}` };
+  }
+  if (doc === null) {
+    return { kind: "unreadable", detail: "`gh api …/branches/…/protection` printed something that is not JSON" };
+  }
+  const rule = doc.required_status_checks;
+  const contexts = Array.isArray(rule?.contexts) ? rule.contexts.length : 0;
+  const checks = Array.isArray(rule?.checks) ? rule.checks.length : 0;
+  return { kind: "read", required: contexts + checks > 0 };
+}
 function writeShipRecord(store, policy, prUrls, merges, at) {
   const all = { ...previousMerges(store), ...merges };
   const distinct = [...new Set(Object.values(all))];
@@ -42694,7 +42828,7 @@ async function shipMany(options, store, branch, repos, body, excuses, policy) {
         kind: "existing",
         url: already,
         base: prepared.base,
-        ...policy === null ? {} : { merge: await armOrKeep(options, repo, already, policy, previousMerges(store)) }
+        ...policy === null ? {} : { merge: await armOrKeep(options, repo, already, policy, previousMerges(store), prepared.base) }
       });
       continue;
     }
@@ -42718,7 +42852,7 @@ async function shipMany(options, store, branch, repos, body, excuses, policy) {
       kind: "opened",
       base: prepared.base,
       url,
-      ...policy === null ? {} : { merge: await armMerge(options, repo, url ?? null, policy) }
+      ...policy === null ? {} : { merge: await armMerge(options, repo, url ?? null, policy, prepared.base) }
     });
   }
   const rendered = renderMany(store, branch, body, results, options.dryRun === true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "tldr-experts: an evidence-first, file-based AI development framework - five stages, a gate on every one, and every claim cited or refused. Installs the `tldrx` (and `tldr-experts`) command. Beta.",
   "license": "MIT",
   "author": "Alan Martinez",

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
   "name": "tldrx",
   "description": "tldr-experts: an evidence-first, file-based AI development framework. Five stages, a gate on every one, every claim cited or refused. Beta.",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "author": {
     "name": "Alan Martinez"
   }