tldr-experts 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.22.0 — 2026-09-14
+
+### Fixed
+
+- **A developer may now READ its own tree, `git -C` is refused on purpose, and every cure says
+  WHY it is a cure (#287, #294).** Two issues, one edit, because they are the same defect seen
+  twice. The developer's git allowance held `add`, `commit`, `rm`, `mv`, `restore` and **no read
+  verb at all** — it could write its worktree and never look at it. Measured on a live
+  unattended run: a developer ran `git -C <worktree> log --oneline -5`, was refused, was
+  re-spawned with the cure, was refused again, and the story died — ~$5 for a command that
+  changes nothing. `status`, `log`, `diff` and `show` join the ONE constant the grant, the
+  prompt's list and the refusal classifier all read (`build/developerGrants.ts`), so all three
+  gained them in the same edit. **`-C <path>` (and `--git-dir`, `--work-tree`) stays ungranted
+  as a decision, and the code now says so**: `-C` points git at ANY directory — the epic
+  worktree, another story's worktree, the shared checkout — so granting it would turn a read
+  verb into a read of trees the story does not own, and a mutating verb into a write there. It
+  is its own refusal kind (`elsewhere`) whose cure is "drop `-C <path>` and run git from your
+  own worktree", never "ask for `-C`". The second half is the reason these shipped together:
+  the three cures we had — "run each command alone" (#278), "run `git log` from your own
+  worktree" (#287), "don't append `echo`" (#294) — all said WHAT and none said WHY, and an agent
+  that does not know why finds another way to do the same thing. #294 is the proof: three
+  consecutive developers on ONE story appended `; echo "EXIT:$?"` to a DoD command, each was
+  refused, and the cure kept telling them to separate the commands — but from their side the
+  `echo` was not an extra command, it was HOW you read an exit code, so they re-added it. A
+  `separator` classification now carries `capturing` (the chain exists only to capture the
+  outcome: an `echo` naming `$?`, or a redirect of the command's own output), and that cure, the
+  retry prefix and the developer prompt all append the same one clause, from one constant: the
+  facilitator re-runs the Definition of Done after you and records each command's exit code, so
+  the number the `echo` would print is written down whether you capture it or not. That
+  clause says only what this repo measures (`build/dodRunner.ts`) and only what holds for every
+  provider: whether an agent's own execution tool hands the exit code back to the model is a
+  property of the provider's CLI — measured for Claude Code's `Bash` tool, established nowhere
+  for `codex exec` — and the sentence goes into the prompt BOTH providers read, so asserting it
+  would have been this very bug one level up, a plausible explanation instead of a true one. The
+  developer prompt goldens moved for exactly those two paragraphs.
+
+## 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,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.22.0 | 2026-09-14 | `beta` | A developer may now READ its own tree — `git status`, `log`, `diff` and `show` join the one constant the grant, the developer prompt and the refusal classifier all read; measured on a live unattended run where a developer was refused `git -C <worktree> log` twice and the story died, ~$5 for a command that changes nothing. `-C <path>` (and `--git-dir`, `--work-tree`) stays ungranted as a decision with its own refusal kind, `elsewhere`, because it points git at trees the story does not own. And every refusal cure now says WHY it is a cure: three consecutive developers on one story re-appended `; echo "EXIT:$?"` to a DoD command because the cure said what to drop and never that the facilitator re-runs the Definition of Done itself and records each exit code (#287, #294). Minor release: the developer's git allowance grew and a new refusal kind was added. |
+| 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-1p5027fn.js";
 import {
   EventLog
 } from "./chunk-6z5rmj0b.js";

package/dist/hooks/{chunk-j5d0nard.js → chunk-1p5027fn.js}

@@ -728,6 +728,9 @@ var KINDS = {
 var MAX_FIXLIST_ROUNDS = STAGE_TUNING_DEFAULTS.fixlistRounds;
 var FINDING_KINDS = ["correctness", "security", "docs", "style"];
 
+// src/core/build/refusalKind.ts
+var OUTCOME_ALREADY_REPORTED = "the facilitator re-runs the Definition of Done after you and records each command's exit " + "code, so the number the `echo` would print is measured and written down whether you " + "capture it or not";
+
 // src/core/build/prompts.ts
 var MAX_TOUCHED_BYTES = 64 * 1024;
 var REVIEW_SCHEMA = {

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

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-j5d0nard.js";
+} from "./chunk-1p5027fn.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-ah1pdax3.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-j5d0nard.js";
+} from "./chunk-1p5027fn.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-ah1pdax3.js";
+import"./chunk-1p5027fn.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) {
@@ -26466,7 +26477,23 @@ function dodFailureReason(result2, repo) {
 }
 
 // src/core/build/developerGrants.ts
-var DEVELOPER_GIT_VERBS = ["add", "commit", "rm", "mv", "restore"];
+var DEVELOPER_GIT_VERBS = [
+  "add",
+  "commit",
+  "rm",
+  "mv",
+  "restore",
+  "status",
+  "log",
+  "diff",
+  "show"
+];
+var GIT_ELSEWHERE_OPTIONS = ["-C", "--git-dir", "--work-tree"];
+function gitElsewhereOption(argv) {
+  const word = argv[1] ?? "";
+  const flag = word.includes("=") ? word.slice(0, word.indexOf("=")) : word;
+  return GIT_ELSEWHERE_OPTIONS.includes(flag) ? flag : null;
+}
 function developerGitGrants() {
   return DEVELOPER_GIT_VERBS.map((verb) => `Bash(git ${verb} *)`);
 }
@@ -26491,6 +26518,94 @@ function slotForCommand(line) {
   return SUBCOMMAND_RE.test(second) ? `${head} ${second}` : head;
 }
 
+// src/core/build/refusalKind.ts
+var MAX_SEPARATOR_RETRIES = 1;
+function classifyRefusal(command2, declared) {
+  const separator = unquotedShellSeparator(command2);
+  if (separator !== null) {
+    return { kind: "separator", separator, capturing: capturesOutcome(command2, separator) };
+  }
+  const argv = command2.trim().split(/\s+/);
+  if (argv[0] !== "git")
+    return undeclaredKind(command2, declared);
+  const verb = argv[1] ?? "";
+  const elsewhere = gitElsewhereOption(argv);
+  if (elsewhere !== null)
+    return { kind: "elsewhere", option: elsewhere };
+  if (verb === "" || verb.startsWith("-"))
+    return { kind: "unknown" };
+  if (isDeveloperGitVerb(verb))
+    return { kind: "unknown" };
+  return { kind: "verb", verb, equivalent: grantedEquivalent(verb, argv.slice(2)) };
+}
+function undeclaredKind(command2, declared) {
+  if (declared === undefined)
+    return { kind: "unknown" };
+  if (grantsCommand(declared, command2))
+    return { kind: "unknown" };
+  const slot = slotForCommand(command2);
+  return slot === "" ? { kind: "unknown" } : { kind: "undeclared", slot };
+}
+function grantedEquivalent(verb, args) {
+  if (verb === "checkout") {
+    const switching = args.some((a) => a === "-b" || a === "-B" || a === "--orphan" || a === "-t" || a === "--track");
+    if (switching)
+      return null;
+    const hasTarget = args.some((a) => !a.startsWith("-")) || args.includes("--");
+    return hasTarget ? "git restore <path>" : null;
+  }
+  if (verb === "reset") {
+    const mode = args.some((a) => /^--(hard|soft|mixed|merge|keep)$/.test(a));
+    if (mode)
+      return null;
+    if (args.includes("--"))
+      return "git restore --staged <path>";
+    const [first, second] = args.filter((a) => !a.startsWith("-"));
+    if (first === "HEAD" && second !== undefined)
+      return "git restore --staged <path>";
+    return null;
+  }
+  return null;
+}
+var EXIT_CODE_ECHO_RE = /(^|[;&|])\s*echo\b[^;&|]*\$\?/;
+function capturesOutcome(command2, separator) {
+  if (EXIT_CODE_ECHO_RE.test(command2))
+    return true;
+  return separator === ">" || separator === ">>" || separator === "2>&1";
+}
+var OUTCOME_ALREADY_REPORTED = "the facilitator re-runs the Definition of Done after you and records each command's exit " + "code, so the number the `echo` would print is measured and written down whether you " + "capture it or not";
+function refusalCure(kind) {
+  switch (kind.kind) {
+    case "separator":
+      return "run each command alone — shell separators split a line into subcommands that each need their own grant" + (kind.capturing ? `. The exit code is not lost by dropping it: ${OUTCOME_ALREADY_REPORTED}` : "");
+    case "elsewhere":
+      return `drop \`${kind.option} <path>\` and run git from your own worktree — \`${kind.option}\` ` + "points git at another directory, so it is refused on purpose rather than missing from the " + "allowance: it would reach trees this story does not own. Your working directory already is " + "the worktree, and the read verbs run there";
+    case "verb":
+      return kind.equivalent === null ? `\`git ${kind.verb}\` is not granted` : `\`git ${kind.verb}\` is not granted; use \`${kind.equivalent}\``;
+    case "undeclared":
+      return `nothing in .tldrx/workspace.yml's \`commands:\` grants \`${kind.slot}\` — a developer's ` + "grant is built from the declared commands, so no re-run and no reopen note can make this " + `line runnable. The operator's cure: add a \`commands:\` slot whose value is exactly ` + `\`${kind.slot}\` (a slot grants that string plus any arguments), or a longer prefix of the ` + "refused line if less should be granted";
+    case "unknown":
+      return "";
+  }
+}
+function withCure(sentence, command2, declared) {
+  const cure = refusalCure(classifyRefusal(command2, declared));
+  return cure === "" ? sentence : `${sentence}. The cure: ${cure}`;
+}
+function separatorCurePrefix(command2) {
+  const separator = unquotedShellSeparator(command2);
+  const capturing = separator !== null && capturesOutcome(command2, separator);
+  return [
+    `Your previous command \`${command2}\` was refused because it chains commands. Run each command alone.`,
+    "The permission layer splits a line at every shell separator (`&&`, `;`, `|`, `>`, `2>&1`, `$()`)",
+    "and each fragment must match its own grant, so a compound line is refused even when every",
+    "command in it is allowed on its own. This is the one retry: a second refusal blocks the story.",
+    ...capturing ? [`The exit code is not lost by dropping it: ${OUTCOME_ALREADY_REPORTED}.`] : [],
+    ""
+  ].join(`
+`);
+}
+
 // src/core/build/prompts.ts
 var MAX_TOUCHED_BYTES = 64 * 1024;
 var MAX_TOUCHED_FILES = 24;
@@ -26594,8 +26709,11 @@ function buildDeveloperPrompt(parts) {
     "",
     ...parts.testFast === undefined ? [] : [...testFastRule(parts.testFast.fast, parts.testFast.full), ""],
     `Commit with \`git add\` and \`git commit\`. The git verbs you hold are exactly ${gitVerbList()}.`,
-    "`git restore <path>` is how to put a file back (there is no checkout in that list). Nothing",
-    "else about git is yours to do.",
+    "`git restore <path>` is how to put a file back (there is no checkout in that list). The read",
+    "verbs are yours so you can look at your own tree before you commit — run them from your working",
+    "directory, which already IS this worktree. Never `-C <path>`: it points git at another directory,",
+    "which is not yours to read or write, so it is refused on purpose. Nothing else about git is",
+    "yours to do.",
     "",
     "## Rules",
     "",
@@ -26608,8 +26726,9 @@ function buildDeveloperPrompt(parts) {
     "- Run each Definition of Done command verbatim and alone: no redirection, pipes or chaining.",
     "  Shell separators (`>`, `>>`, `2>&1`, `<`, `|`, `;`, `&&`, `||`, `&`, `$()`) split a line into",
     "  subcommands, and each subcommand must match its own grant, so a compound line is refused",
-    "  even when the script itself is allowed. The facilitator re-runs the Definition of Done",
-    "  after you anyway.",
+    "  even when the script itself is allowed.",
+    `- Do not append \`; echo $?\` or redirect a command's output to a file to capture its outcome.`,
+    `  The exit code is not lost by dropping it: ${OUTCOME_ALREADY_REPORTED}.`,
     "",
     "### Conventions",
     "",
@@ -28704,78 +28823,6 @@ function verdictReviewer(checkPayload, lastSpawn) {
   return lastSpawn;
 }
 
-// src/core/build/refusalKind.ts
-var MAX_SEPARATOR_RETRIES = 1;
-function classifyRefusal(command2, declared) {
-  const separator = unquotedShellSeparator(command2);
-  if (separator !== null)
-    return { kind: "separator", separator };
-  const argv = command2.trim().split(/\s+/);
-  if (argv[0] !== "git")
-    return undeclaredKind(command2, declared);
-  const verb = argv[1] ?? "";
-  if (verb === "" || verb.startsWith("-"))
-    return { kind: "unknown" };
-  if (isDeveloperGitVerb(verb))
-    return { kind: "unknown" };
-  return { kind: "verb", verb, equivalent: grantedEquivalent(verb, argv.slice(2)) };
-}
-function undeclaredKind(command2, declared) {
-  if (declared === undefined)
-    return { kind: "unknown" };
-  if (grantsCommand(declared, command2))
-    return { kind: "unknown" };
-  const slot = slotForCommand(command2);
-  return slot === "" ? { kind: "unknown" } : { kind: "undeclared", slot };
-}
-function grantedEquivalent(verb, args) {
-  if (verb === "checkout") {
-    const switching = args.some((a) => a === "-b" || a === "-B" || a === "--orphan" || a === "-t" || a === "--track");
-    if (switching)
-      return null;
-    const hasTarget = args.some((a) => !a.startsWith("-")) || args.includes("--");
-    return hasTarget ? "git restore <path>" : null;
-  }
-  if (verb === "reset") {
-    const mode = args.some((a) => /^--(hard|soft|mixed|merge|keep)$/.test(a));
-    if (mode)
-      return null;
-    if (args.includes("--"))
-      return "git restore --staged <path>";
-    const [first2, second] = args.filter((a) => !a.startsWith("-"));
-    if (first2 === "HEAD" && second !== undefined)
-      return "git restore --staged <path>";
-    return null;
-  }
-  return null;
-}
-function refusalCure(kind) {
-  switch (kind.kind) {
-    case "separator":
-      return "run each command alone — shell separators split a line into subcommands that each need their own grant";
-    case "verb":
-      return kind.equivalent === null ? `\`git ${kind.verb}\` is not granted` : `\`git ${kind.verb}\` is not granted; use \`${kind.equivalent}\``;
-    case "undeclared":
-      return `nothing in .tldrx/workspace.yml's \`commands:\` grants \`${kind.slot}\` — a developer's ` + "grant is built from the declared commands, so no re-run and no reopen note can make this " + `line runnable. The operator's cure: add a \`commands:\` slot whose value is exactly ` + `\`${kind.slot}\` (a slot grants that string plus any arguments), or a longer prefix of the ` + "refused line if less should be granted";
-    case "unknown":
-      return "";
-  }
-}
-function withCure(sentence, command2, declared) {
-  const cure = refusalCure(classifyRefusal(command2, declared));
-  return cure === "" ? sentence : `${sentence}. The cure: ${cure}`;
-}
-function separatorCurePrefix(command2) {
-  return [
-    `Your previous command \`${command2}\` was refused because it chains commands. Run each command alone.`,
-    "The permission layer splits a line at every shell separator (`&&`, `;`, `|`, `>`, `2>&1`, `$()`)",
-    "and each fragment must match its own grant, so a compound line is refused even when every",
-    "command in it is allowed on its own. This is the one retry: a second refusal blocks the story.",
-    ""
-  ].join(`
-`);
-}
-
 // src/core/build/review.ts
 var VERDICT_WORDS = ["approve", "fixlist", "changes"];
 var VERDICT_ENUM = VERDICT_WORDS.join("|");
@@ -28893,6 +28940,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 +29073,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 +29444,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 +36559,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 +36768,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 +36905,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 +37278,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 +38997,7 @@ class BuildSession {
   outcomes = new Map;
   refusals = new Map;
   capDeaths = new Map;
+  unfundedReviews = new Map;
   asIsSettlements = new Map;
   epics = new EpicState;
   lines = [];
@@ -39253,7 +39341,7 @@ class BuildSession {
         return;
       if (outcome?.status !== "review")
         return;
-      if (outcome.verdict === "error")
+      if (reviewStillOwed(outcome))
         return;
       if (outcome.verdict === "fixlist")
         return;
@@ -39313,6 +39401,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 +39475,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 +39655,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 +39874,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 +40213,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 +40458,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 +40491,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 +48650,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 +48676,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 +48695,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 +48726,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 +48742,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 +48770,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 +48795,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 +48881,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.22.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.22.0",
   "author": {
     "name": "Alan Martinez"
   }