tldr-experts 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.21.0 — 2026-09-13
+
+### Fixed
+
+- **The raise an operator is told to make now moves a ceiling, and a stage that cannot fund a
+  review stops buying one (#244, #289).** One function, one question — how much money is there,
+  and who decides when there is not enough — so the two were done together. The model, measured
+  case by case by the session running two live unattended runs (their measurement, not this
+  file's): the three money figures are three knobs with three different jobs, not three copies of
+  one number. The STAGE's `budget_usd` decides the price scale and therefore every per-story
+  developer ceiling and the reviewer's; the PHASE ceiling only takes part in the economy refusal
+  ("remaining work > what is left") and caps no spawn at all; `per_agent_max_usd` only trims a
+  ceiling from above. Their two controls: raising only the stage figure, 16.20 → 60, moved a
+  developer ceiling 5.97 → 22.11 on the next spawn, and raising `per_agent_max_usd` and the phase
+  ceiling *without* touching the stage moved the ceiling by nothing. So `tldrx budget raise
+  <phase> <usd>` — the command every refusal names — moved the one knob that caps nothing a
+  sub-agent is dispatched under: the operator raised, re-ran, died on the identical cap, and each
+  `reject --and-continue` bought exactly one more turn. It now takes `--stage <id>`, which adds
+  the same amount to that stage's own `budget_usd` in `run.yml` (additively, like the phase
+  ceiling; recorded on `budget.raised` as `stage`/`stage_budget_before`/`stage_budget_after`, and
+  an unknown stage id is a usage refusal that writes neither file), and a raise that names no
+  stage now SAYS in its own output that no spawn ceiling moved and names the flag that would
+  move one.
+- **A reviewer the stage cannot fund is not spawned, and the refusal is not recorded as a verdict
+  (#289).** Measured on a live unattended run (`--budget 60`, `--gates none --questions none
+  --ship merge`): story S1's developer went DoD 3/3 green at $10.64, the reviewer right after it
+  was handed **$0.43**, died with `Reached maximum budget ($0.43)` before reading a line of the
+  diff, and the `verdict: error` that recorded its death parked S1 at `review` with both
+  dependent stories blocked behind it — the loop stopped after $17.23 of a $60 run.
+  `REVIEWER_FLOOR_USD` ($1.00) already existed and did not save it, because the floor YIELDS to
+  the stage remainder (`min(REVIEWER_FLOOR_USD, budget − spent)`): a nearly-exhausted stage buys a
+  turn that provably cannot finish. The fix is not a bigger floor. When the stage has less left
+  than a review costs the executor refuses BEFORE the spawn — no `agent.spawned`, no task row, not
+  a cent — and the story parks at `review` exactly where an unjudged story parks, with its diff
+  merged and its one attempt unspent. What it writes down is **not a verdict**: `verdict: "n-a"`
+  ("no reviewer ran for this story") beside a `reviewer_unfunded:` reason on the story's
+  `task.done`, its review log and the retro — the reviewer-side sibling of the `developerError`
+  and `budget_death:` records #271 and #277 shipped, and for the same reason. An agent that never
+  started formed no opinion, and `error` already means "it died mid-read"; writing a death nobody
+  chose as a review outcome is an audit record lying in the dangerous direction. The reason names
+  the lever that actually moves the ceiling — `tldrx budget raise <phase> <usd> --stage <id>`,
+  sized to the shortfall — rather than the phase ceiling that caps no spawn. The review stays
+  owed, so the next invocation's review-only path picks it up instead of re-running the developer,
+  and under an unchanged remainder it refuses again for free. `reviewerCap`'s arithmetic is
+  deliberately untouched: it is mirrored on the budget gate's hot path, and the brake's estimate
+  must keep reading the schedule the executor would have spent under. A HOST review is never
+  refused this way — it costs the stage nothing.
+
 ## 0.20.0 — 2026-09-13
 
 ### Added

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.21.0 | 2026-09-13 | `beta` | `tldrx budget raise <phase> <usd> --stage <id>` now moves the stage's own `budget_usd` — the figure that actually sets a developer's and a reviewer's spawn ceiling — instead of the phase figure, which caps no spawn at all: measured on a live unattended run where raising the plan's per-story price and the phase ceiling moved a developer's cap by nothing, and only raising the stage figure moved it; a raise naming no `--stage` now says outright that it moved no spawn ceiling. And a reviewer a nearly-exhausted stage cannot fund is refused before it is spawned — the run that surfaced this handed a reviewer **$0.43**, which died before reading a line of diff and recorded `verdict: error`, parking the story with its dependents blocked; the refusal now costs $0 and records `verdict: n-a`, not an error the reviewer never formed (#244, #289). Minor release: a new flag, `--stage`, on `budget raise`. |
 | 0.20.0 | 2026-09-13 | `beta` | `tldrx seed check <file\|dir>` runs a hand-written seed through the same importer chain `run new --seed` runs, plus the authoring rules four unattended runs paid to learn — bullets under 200 characters, `[src:]` citations that resolve, `dod` lines byte-equal to a declared command with no shell separator, `depends_on` wherever two stories touch one file, a `Recommended:` on every open question — and prints the budget split and per-story caps a run would set, creating no run and spending nothing; `tldrx install --claude` now writes a second managed skill, `tldrx-plan`, that reads `workspace.yml` and the repo tree and turns "I want X" into seeds that pass the same check, naming only declared tools (#291). And a permission refusal over a command the workspace's `commands:` could have granted now names the operator's cure on the first dead developer instead of the fourth, measured on a live unattended run where four developers died and two review rounds ran before the missing command turned out to be one `workspace.yml` line away (#285). Minor release: a new CLI verb, `tldrx seed check`. |
 | 0.19.0 | 2026-09-13 | `beta` | `tldrx story reopen <id> --as-is --note "…"` settles a story a person finished by hand from its branch as it stands, spawning no developer — measured on a live unattended run where a hand-rebased branch had a green DoD and a clean merge-tree but no way to land, blocked by #271's since-the-spawn rule from a developer with nothing to do (#279). Everything after the missing developer is the ordinary path: the epic merges in first if it moved, the same DoD and reviewer judge the diff, the same merge lands it. The record never lies about who did the work — `story.reopened` carries `reason: as_is` with the actor and note, `task.done` carries `as_is`/`as_is_by`/`as_is_note`, and the review log names the branch and the signer. Two refusals are structural with no flag to skip either: a branch with no commit ahead of its epic, and a red DoD. The signature clears the moment a real developer attempt starts, so a requeued story after a `changes` verdict records a developer, not an as-is. Minor release: a new flag, `--as-is`, on `story reopen`. |
 | 0.18.3 | 2026-09-13 | `beta` | four fixes to the unattended build path, all measured on live runs: a headless permission refusal is now classified — a chained shell command, a git verb outside the developer's allowance, or neither — so a chained line gets one retry with the cure stated first, an ungranted verb names its granted equivalent, and the developer prompt now lists the git verbs it holds from the one constant the grant is built from, after six refusals in one day left a ledger that recorded the symptom and not the cause; a wave no longer merges a story into its epic from the base it was cut from once a sibling has moved that epic — the story is measured against the epic tip immediately before merge, the epic is merged into the story and its Definition of Done re-run only when the epic actually moved, and a conflict blocks the story naming the files rather than merging half of one; a seed bullet over the claim cap no longer has its citation cut in half, with the clip moving back to the citation's start instead; and a failed commit count is no longer read as zero, so `--discard-pending` can no longer delete a plan just because git could not answer. |

package/dist/hooks/budget-gate.js

@@ -22,7 +22,7 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-j5d0nard.js";
+} from "./chunk-f5wkn522.js";
 import {
   EventLog
 } from "./chunk-6z5rmj0b.js";

package/dist/hooks/{chunk-53wgfn01.js → chunk-6qnsx1tz.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-j5d0nard.js";
+} from "./chunk-f5wkn522.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,

package/dist/hooks/session-start.js

@@ -20,14 +20,14 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-53wgfn01.js";
+} from "./chunk-6qnsx1tz.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-j5d0nard.js";
+} from "./chunk-f5wkn522.js";
 import {
   isFinished
 } from "./chunk-6z5rmj0b.js";

package/dist/hooks/statusline.js

@@ -2,8 +2,8 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-53wgfn01.js";
-import"./chunk-j5d0nard.js";
+} from "./chunk-6qnsx1tz.js";
+import"./chunk-f5wkn522.js";
 import"./chunk-6z5rmj0b.js";
 import"./chunk-m1s8a6s0.js";
 import"./chunk-yre2scxn.js";

package/dist/tldrx.js

@@ -16639,6 +16639,12 @@ var ENTRIES = [
       runFlag(),
       json("the budget view", "show"),
       { name: "take-from", arg: "<phase>", meaning: "Move the money out of this phase instead of raising the run's total.", sub: "raise" },
+      {
+        name: "stage",
+        arg: "<id>",
+        meaning: "ALSO add the same amount to that stage's own budget_usd in run.yml — the one knob a sub-agent's ceiling is derived from (#244). Without it a raise moves the phase ceiling, which decides only whether a stage may START, and every per-story and reviewer cap stays exactly where it was.",
+        sub: "raise"
+      },
       { name: "note", arg: "<text>", meaning: "Why the ceiling moved. Recorded on the budget.raised event beside the before/after and the actor.", sub: "raise" },
       { name: "note", arg: "<text>", meaning: "Why the grant was recorded. Kept on the budget.granted event beside the amount, the fact and the actor.", sub: "grant" },
       {
@@ -16665,10 +16671,12 @@ var ENTRIES = [
     examples: [
       "tldrx budget show",
       "tldrx budget raise 04-build 25 --take-from 02-how",
+      "tldrx budget raise 04-build 25 --stage build",
       "tldrx budget grant 20 --fact F031 --on-exceed block"
     ],
     exits: [EXIT_OK, EXIT_USAGE, EXIT_GATE_REFUSED, EXIT_NOT_FOUND],
     notes: [
+      "Three knobs, three jobs, and only one of them caps a spawn. The STAGE's `budget_usd` (run.yml) decides the price scale, every per-story developer ceiling and the reviewer's — `--stage` is the sanctioned way to move it (#244). The PHASE ceiling (budget.yml) decides only the economy refusal, `remaining work > what is left`. `per_agent_max_usd` only caps a ceiling from above. Measured on two live unattended runs: the stage figure alone, 16.20 to 60, moved a developer ceiling 5.97 to 22.11 on the next spawn; raising the other two without it moved nothing.",
       "`raise` ADDS. `raise 04-build 25` on a phase already ceilinged at $10 leaves it at $35, not $25 — the amount is a delta, and the run ceiling grows with it unless --take-from moves the money. `budget show` prints the exact command, already sized to the shortfall, when a stage is blocked; pasting that is the way to raise without doing the arithmetic.",
       "`grant` RECORDS, it does not spend: it writes authorized_usd, authorized_by, authorized_at and on_grant_exceed into budget.yml and appends a budget.granted event. No ceiling moves, and a grant the current ceiling already exceeds is still recorded — the money is committed, there is nothing left to refuse. `raise` then measures the ceiling it is about to write against it: a PHASE grant against the phase ceiling, the RUN grant against the run ceiling.",
       "Two exit families, two conditions. A bad amount, an unknown phase, an unknown --on-exceed value, or a --fact naming no live fact is a USAGE error: exit 1, nothing written. A ceiling above the recorded grant under on_grant_exceed: block is a GATE refusal: exit 2, budget.yml byte-identical. Under the default warn the ceiling is written and one sentence names the grant, the fact and the figure."
@@ -26439,6 +26447,9 @@ function dodRefused(result2) {
 }
 var DOD_REFUSAL_FALLBACK = "the gate declined to run it";
 var DEVELOPER_FAILED = "the developer sub-agent failed";
+function reviewStillOwed(outcome) {
+  return outcome.verdict === "error" || (outcome.reviewerUnfunded ?? null) !== null;
+}
 var AS_IS_MARK = "the branch was taken AS IT STANDS — no developer was spawned for it";
 var AS_IS_NOT_AHEAD_MARK = "nothing to take as it stands";
 function asIsNotAheadReason(branch, epicBranch, ahead) {
@@ -28893,6 +28904,21 @@ function text2(value) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
 }
 var REVIEWER_FAILED = "the reviewer sub-agent failed";
+var REVIEWER_UNFUNDED_MARK = "no reviewer was spawned: the stage cannot fund one";
+function reviewerUnfundedReason(parts) {
+  return `${REVIEWER_UNFUNDED_MARK} — $${parts.remainingUsd.toFixed(2)} left, and a review ` + `costs at least $${parts.floorUsd.toFixed(2)}. Nothing was spent on a turn that could not ` + `read the diff. Raise the stage's own budget_usd — the phase ceiling caps no spawn: ${parts.fix}`;
+}
+function reviewerUnfunded(reason) {
+  return {
+    verdict: "n-a",
+    summary: reason,
+    findings: [],
+    fixlist: [],
+    fixlistProblems: [],
+    formatProblems: [],
+    verdictProblem: null
+  };
+}
 function reviewerFailed(error) {
   const said2 = (error ?? "").trim();
   return {
@@ -29011,6 +29037,14 @@ function summaryLines(outcome) {
       `> ${outcome.developerError}`
     ];
   }
+  if ((outcome.reviewerUnfunded ?? null) !== null) {
+    return [
+      "**No reviewer was spawned: the stage could not fund one.** This is not a verdict and not",
+      "a failure of the diff — nothing read it, and nothing was spent trying. Why:",
+      "",
+      `> ${outcome.reviewerUnfunded ?? ""}`
+    ];
+  }
   if (outcome.verdict === "error") {
     return [
       "**The reviewer FAILED and returned no verdict.** This is not a request for changes:",
@@ -29374,6 +29408,9 @@ function unmeteredNote(count) {
 function raiseCommand(runId, phaseId, amountUsd) {
   return `tldrx budget raise ${phaseId} ${amountUsd.toFixed(2)} --run ${runId}`;
 }
+function stageRaiseCommand(runId, phaseId, stageId, amountUsd) {
+  return `${raiseCommand(runId, phaseId, amountUsd)} --stage ${stageId}`;
+}
 function shortBy(estimate, remaining2) {
   return Math.max(0.01, Math.ceil((estimate - remaining2) * 100) / 100);
 }
@@ -36486,6 +36523,15 @@ function reviewerCap(parts, spentUsd, storyId) {
   const floor = Math.min(REVIEWER_FLOOR_USD2, Math.max(parts.budgetUsd - spentUsd, 0));
   return round25(Math.min(Math.max(derived, floor), parts.maxBudgetUsd));
 }
+function stageRemainderUsd(parts, spentUsd) {
+  if (!(parts.budgetUsd > 0))
+    return null;
+  return Math.max(round25(parts.budgetUsd - spentUsd), 0);
+}
+function reviewerUnderfunded(parts, spentUsd) {
+  const left = stageRemainderUsd(parts, spentUsd);
+  return left !== null && left < REVIEWER_FLOOR_USD2;
+}
 function priceOf(parts, storyId) {
   if (storyId === undefined)
     return null;
@@ -36686,6 +36732,8 @@ function readReviewLedger(runDir, storyId) {
   };
 }
 function reviewEventErrored2(payload) {
+  if (typeof payload.unfunded_usd === "number")
+    return true;
   if (payload.verdict === "error")
     return true;
   if (payload.verdict !== "changes")
@@ -36821,7 +36869,7 @@ function awaitingReview(runDir, stageId, pending) {
 function resumableReview(runDir, storyId, status, fresh) {
   if (status !== "review" && status !== "in_progress")
     return null;
-  if (fresh !== undefined && fresh.verdict !== "error")
+  if (fresh !== undefined && !reviewStillOwed(fresh))
     return null;
   const ledger4 = readReviewLedger(runDir, storyId);
   if (ledger4.erroredWith === null || ledger4.commit === null)
@@ -37194,6 +37242,9 @@ function storyRetroLines(outcome, runId) {
   if (outcome.developerError !== null) {
     lines.push(`- \`${outcome.id}\` — the developer FAILED and produced no work on attempt ` + `${String(outcome.attempts)}: ${oneLine5(outcome.developerError)} ${src}`);
   }
+  if ((outcome.reviewerUnfunded ?? null) !== null) {
+    lines.push(`- \`${outcome.id}\` — no reviewer was spawned on attempt ` + `${String(outcome.attempts)}: ${oneLine5(outcome.reviewerUnfunded ?? "")} ${src}`);
+  }
   if (outcome.verdict === "error") {
     lines.push(`- \`${outcome.id}\` — the reviewer FAILED and returned no verdict on attempt ` + `${String(outcome.attempts)}: ${oneLine5(outcome.reviewSummary)} ${src}`);
   }
@@ -38910,6 +38961,7 @@ class BuildSession {
   outcomes = new Map;
   refusals = new Map;
   capDeaths = new Map;
+  unfundedReviews = new Map;
   asIsSettlements = new Map;
   epics = new EpicState;
   lines = [];
@@ -39253,7 +39305,7 @@ class BuildSession {
         return;
       if (outcome?.status !== "review")
         return;
-      if (outcome.verdict === "error")
+      if (reviewStillOwed(outcome))
         return;
       if (outcome.verdict === "fixlist")
         return;
@@ -39313,6 +39365,7 @@ class BuildSession {
     const before = this.statusOf(planned);
     this.refusals.delete(id);
     this.capDeaths.delete(id);
+    this.unfundedReviews.delete(id);
     this.asIsSettlements.set(id, asIs);
     const story = await this.writes.run(() => this.openStory(planned));
     await this.writes.run(() => {
@@ -39386,6 +39439,7 @@ class BuildSession {
     const before = this.statusOf(planned);
     this.refusals.delete(planned.story.id);
     this.capDeaths.delete(planned.story.id);
+    this.unfundedReviews.delete(planned.story.id);
     this.asIsSettlements.delete(planned.story.id);
     const story = await this.writes.run(() => this.openStory(planned, true));
     await this.writes.run(() => {
@@ -39565,6 +39619,21 @@ class BuildSession {
       await this.handOffReview(story, dod, commit2, priorCost, carried, epicBase);
       return "handed-off";
     }
+    if (supplied === undefined && reviewerUnderfunded(this.capParts, this.spent())) {
+      const review2 = this.refuseUnfundedReview(story);
+      await this.settle(story, "review", {
+        dod,
+        commit: commit2,
+        merged: true,
+        carried,
+        epicBase,
+        verdict: "n-a",
+        review: review2,
+        cost: round25(priorCost),
+        reason: review2.summary
+      });
+      return "settled";
+    }
     const outcome = supplied === undefined ? await this.spawnReviewer(story, dod, epicBase) : { review: supplied, cost: 0 };
     const review = outcome.review;
     const cost = round25(priorCost + outcome.cost);
@@ -39769,7 +39838,8 @@ class BuildSession {
       });
     });
     this.noteMerged(story, null);
-    this.lines.push(`  · ${planned.story.id}: the previous reviewer FAILED (${resume.error}) — ` + `re-running the REVIEW only; \`${resume.commit}\` is already merged into \`${story.epicBranch}\``);
+    const failed3 = resume.error.includes(REVIEWER_UNFUNDED_MARK) ? `the previous review was refused for want of money (${resume.error})` : `the previous reviewer FAILED (${resume.error})`;
+    this.lines.push(`  · ${planned.story.id}: ${failed3} — ` + `re-running the REVIEW only; \`${resume.commit}\` is already merged into \`${story.epicBranch}\``);
     this.noteUnrecordedBase(planned.story.id, story.epicBranch, resume.epicBase);
     await this.reviewAndSettle(story, resume.dod, resume.commit, 0, null, resume.epicBase ?? null);
   }
@@ -40107,6 +40177,28 @@ class BuildSession {
       storyTitle: story.planned.story.title
     });
   }
+  refuseUnfundedReview(story) {
+    const id = story.planned.story.id;
+    const left = stageRemainderUsd(this.capParts, this.spent()) ?? 0;
+    const review = reviewerUnfunded(reviewerUnfundedReason({
+      remainingUsd: left,
+      floorUsd: REVIEWER_FLOOR_USD2,
+      fix: `\`${stageRaiseCommand(this.ctx.runId, this.ctx.phaseId, this.ctx.stageId, shortBy(REVIEWER_FLOOR_USD2, left))}\``
+    }));
+    this.unfundedReviews.set(id, review.summary);
+    this.ctx.emit("check.failed", {
+      phase: this.ctx.phaseId,
+      check: "review",
+      story: id,
+      verdict: review.verdict,
+      attempt: story.attempt,
+      unfunded_usd: left,
+      floor_usd: REVIEWER_FLOOR_USD2,
+      detail: review.summary
+    });
+    this.reviewers.set(id, null);
+    return review;
+  }
   async spawnReviewer(story, dod, epicBase) {
     const id = story.planned.story.id;
     let refusal = null;
@@ -40330,6 +40422,7 @@ class BuildSession {
       permissionRefused: this.refusals.get(id) ?? null,
       declaredCommands: this.repoCommands(story.planned.story.repo),
       budgetDeath: this.capDeaths.get(id) ?? null,
+      reviewerUnfunded: this.unfundedReviews.get(id) ?? null,
       asIs: this.asIsSettlements.get(id) ?? null,
       rescued,
       cost_usd: parts.cost
@@ -40362,6 +40455,7 @@ class BuildSession {
       ...parts.epicBase === null || parts.epicBase === undefined || parts.epicBase === "" ? {} : { epic_base: parts.epicBase },
       ...outcome.permissionRefused == null ? {} : { permission_refused: outcome.permissionRefused },
       ...outcome.budgetDeath == null ? {} : { budget_death: outcome.budgetDeath },
+      ...outcome.reviewerUnfunded == null ? {} : { reviewer_unfunded: outcome.reviewerUnfunded },
       ...outcome.asIs == null ? {} : { as_is: true, as_is_by: outcome.asIs.actor, as_is_note: outcome.asIs.note }
     });
     if (pruning && (rescued === null || rescued.worktree === null)) {
@@ -48520,12 +48614,12 @@ function wouldExceedGrant(budget, phaseId, resultingCeilingUsd) {
 }
 
 // src/cli/commands/budget.ts
-var VALUE_FLAGS3 = ["run", "root", "take-from", "note", "fact", "phase", "on-exceed"];
+var VALUE_FLAGS3 = ["run", "root", "take-from", "note", "fact", "phase", "on-exceed", "stage"];
 var budgetCommand = {
   name: "budget",
   summary: "Show what the run may still spend, raise a phase ceiling, or record what the owner authorized",
   usage: `tldrx budget show [<run>] [--run <id>] [--json] [--root <path>]
-` + `       tldrx budget raise <phase> <usd> [--run <id>] [--take-from <phase>] [--note <text>] [--root <path>]
+` + `       tldrx budget raise <phase> <usd> [--stage <id>] [--run <id>] [--take-from <phase>] [--note <text>] [--root <path>]
 ` + "       tldrx budget grant <usd> --fact <F> [--phase <p>] [--on-exceed <warn|block>] [--note <text>] [--run <id>] [--root <path>]",
   implemented: true,
   async run(argv) {
@@ -48546,6 +48640,14 @@ ${budgetCommand.usage}
   }
 };
 var GRANT_ONLY_FLAGS = ["fact", "phase", "on-exceed"];
+var RAISE_ONLY_FLAGS = ["stage"];
+function refuseRaiseFlags(args, verb) {
+  for (const flag of RAISE_ONLY_FLAGS) {
+    if (!boolFlag(args, flag))
+      continue;
+    throw new UsageError(`--${flag} is \`budget raise\`'s flag, not \`budget ${verb}\`'s — ` + "raise a stage's own ceiling with `tldrx budget raise <phase> <usd> --stage <id>`");
+  }
+}
 function refuseGrantFlags(args, verb) {
   for (const flag of GRANT_ONLY_FLAGS) {
     if (!boolFlag(args, flag))
@@ -48557,6 +48659,7 @@ function budgetShow(argv) {
   try {
     const args = parseArgs(argv, VALUE_FLAGS3);
     refuseGrantFlags(args, "show");
+    refuseRaiseFlags(args, "show");
     const resolved = openRun(args.positionals[0] ?? stringFlag(args, "run"), workspaceRootFrom(args));
     if (!isResolved(resolved))
       return resolved.exit;
@@ -48587,6 +48690,9 @@ function budgetRaise(argv) {
     if (!isResolved(resolved))
       return resolved.exit;
     const store = resolved.store;
+    const stageId = stringFlag(args, "stage") ?? null;
+    if (stageId !== null)
+      requireStageBudget(store.run, phaseId, stageId);
     const outcome = raiseBudget(store.budget, {
       phaseId,
       amountUsd,
@@ -48600,6 +48706,19 @@ function budgetRaise(argv) {
       return EXIT_GATE_REFUSED;
     }
     store.mutateBudget(() => outcome.budget);
+    const stageBefore = stageId === null ? null : requireStageBudget(store.run, phaseId, stageId);
+    if (stageId !== null) {
+      store.mutate((run2) => ({
+        ...run2,
+        phases: run2.phases.map((phase) => phase.id !== phaseId ? phase : {
+          ...phase,
+          stages: phase.stages.map((stage2) => stage2.id !== stageId ? stage2 : {
+            ...stage2,
+            budget_usd: round25(stage2.budget_usd + amountUsd)
+          })
+        })
+      }));
+    }
     store.append({
       ts: nowRfc3339(),
       run: store.runId,
@@ -48615,12 +48734,17 @@ function budgetRaise(argv) {
         phase_ceiling_after: outcome.phaseCeilingAfter,
         run_ceiling_before: outcome.runCeilingBefore,
         run_ceiling_after: outcome.runCeilingAfter,
+        ...stageId === null || stageBefore === null ? {} : {
+          stage: stageId,
+          stage_budget_before: stageBefore,
+          stage_budget_after: round25(stageBefore + amountUsd)
+        },
         note: stringFlag(args, "note") ?? ""
       }
     });
     store.save();
     const view = buildBudgetView(store.run, store.budget, store.runDir);
-    const lines = [describeRaise(outcome)];
+    const lines = [describeRaise(outcome), ...stageRaiseLines(phaseId, stageId, stageBefore, amountUsd)];
     if (verdict2.sentence !== null)
       lines.push(verdict2.sentence);
     lines.push(view.blocked === null ? "`tldrx next` is now affordable in every phase that still has a stage to run." : `still BLOCKED in ${view.blocked.id} — ${view.fix_command ?? ""}`);
@@ -48635,6 +48759,7 @@ function budgetRaise(argv) {
 function budgetGrant(argv) {
   try {
     const args = parseArgs(argv, VALUE_FLAGS3);
+    refuseRaiseFlags(args, "grant");
     const amountText = args.positionals[0];
     if (amountText === undefined) {
       throw new UsageError("budget grant needs an amount: `tldrx budget grant 20 --fact F031`");
@@ -48720,6 +48845,27 @@ function money4(amount) {
 function openRun(wanted, root2) {
   return resolveRunOrExplain("tldrx budget", root2, wanted);
 }
+function requireStageBudget(run2, phaseId, stageId) {
+  const phase = run2.phases.find((entry) => entry.id === phaseId);
+  if (phase === undefined)
+    throw new UsageError(`no phase \`${phaseId}\` in this run`);
+  const stage2 = phase.stages.find((entry) => entry.id === stageId);
+  if (stage2 === undefined) {
+    const known = phase.stages.map((entry) => entry.id).join(", ");
+    throw new UsageError(`no stage \`${stageId}\` in ${phaseId} — this phase has: ${known === "" ? "none" : known}`);
+  }
+  return stage2.budget_usd;
+}
+function stageRaiseLines(phaseId, stageId, before, amountUsd) {
+  if (stageId === null || before === null) {
+    return [
+      "No spawn ceiling moved: per-story and reviewer caps come from the STAGE's own " + `budget_usd, not from this phase ceiling. Move that too with \`--stage <id>\` ` + `(\`tldrx budget show\` names the stage ${phaseId} would run next).`
+    ];
+  }
+  return [
+    `${phaseId}/${stageId} budget_usd $${before.toFixed(2)} → $${round25(before + amountUsd).toFixed(2)} ` + `(+$${amountUsd.toFixed(2)}) — every per-story and reviewer cap is derived from this figure.`
+  ];
+}
 
 // src/cli/commands/cost.ts
 var VALUE_FLAGS4 = ["run", "root"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "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.20.0",
+  "version": "0.21.0",
   "author": {
     "name": "Alan Martinez"
   }