tldr-experts 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.23.0 — 2026-09-14
+
+### Fixed
+
+- **A fix list with nothing to fix now settles the story `done` instead of buying a developer round
+  (#295, first half).** Measured on a live unattended run (0.20.0): the reviewer signed a two-finding
+  fix list, both `docs` and both `defer-with-log`, and the story still parked at `review` — the Build
+  then spawned a fix round for it, which died four times on command-form refusals (#294) with nothing
+  to fix. The rule that a `fixlist` verdict parks the story was written when a fix list meant "here is
+  what the author must do next"; #255 then made all-deferred lists the normal outcome of a docs-only
+  review and never adjusted who settles the story. Now the count the operator line already prints —
+  findings still `fix-now` in the PARSED list, #255's routing included — decides: zero means the
+  reviewer signed and nothing is owed a developer, so the story is `done` with `verdict: fixlist` on
+  its record. The artifact is still written and its deferred findings still reach `retro.md`: settling
+  the story does not settle what it deferred. One `fix-now` finding parks it exactly as before.
+- **`story reopen --as-is` can settle a story whose work is already on the epic and whose review
+  never completed — review-only, merging nothing (#295, second half).** Under merge-before-review
+  (#282) a story's diff can sit entirely on the epic while nothing has judged it: measured twice on
+  2026-09-13, a reviewer that died and a later attempt that died on a bare `echo $?` with no work.
+  #279's guard — the branch must carry a commit the epic has not got — is right for a branch with no
+  work and blind to this mirror image, where there is nothing to MERGE and something to SETTLE; the
+  operator's only moves were inventing a commit for `--as-is` to take, which corrupts the
+  measurement, or leaving the story blocked with its dependents (#280). The guard is not relaxed. A
+  new, named case sits beside it: the review ledger now keeps the story's last recorded merge
+  (`commit` + `epic_base`) across reopen boundaries — a reopen resets what counts against a story,
+  not what the epic holds — and `--as-is` over a branch that carries nothing beyond its epic asks
+  whether anything judged that merge. `n-a` and `error` mean nothing did, and the turn runs
+  review-only: the branch is brought up to the epic `--ff-only` (nothing of its own to lose), the
+  DoD runs on the epic head, the reviewer is handed the recorded range, and nothing is merged —
+  `task.done` carries `as_is_reason: review-only`, the review log's developer line says so and names
+  the commit it reviewed. A review that STANDS (`changes`, `approve`, `fixlist`) still refuses, and
+  the refusal now names that verdict beside the #279 sentence: what is owed is a fix, not a third
+  opinion on the same bytes — which is also why the #279 pin test (two `changes` over a reset
+  branch) is untouched. The issue proposed "any verdict but `approve`"; that would have flipped that
+  pin, so the boundary shipped is the one in the issue's title: the review never completed.
+- **A turn's failure record can no longer borrow the word `success` from the provider (#296).**
+  MEASURED on two live unattended runs while the account sat over its usage limit: both a
+  developer and a reviewer died with `claude exited 1 with is_error=true: success`. That line is
+  two layers' verdicts concatenated and nothing reconciling them — our `is_error` beside the
+  provider's own `subtype`, which was the literal `"success"` — and the ONLY human-readable word
+  on it was the one that was wrong. Tomorrow's reader learns the story failed; the truth is it
+  never ran, which is exactly the direction §7 forbids an audit record to lie in. `describe()`
+  is reached only for a FAILURE, so a subtype asserting the turn succeeded cannot be that
+  failure's reason: it is now refused as a reason and reported as the contradiction it is —
+  `claude exited 1 with is_error=true: no reason named (the provider's own subtype said
+  "success")` — keeping BOTH facts rather than dropping either, because a record that hides the
+  disagreement is only marginally better than one that resolves it wrongly. A failure with no
+  reason anywhere now says `no reason named` instead of trailing off after the exit code. A
+  reason the provider DID name (`Reached maximum budget ($0.26)`) and a genuine error subtype
+  (`error_during_execution`) are printed exactly as before. **This does not classify the limit
+  and does not change any retry**: what `subtype`, `errors[]` or HTTP status either provider
+  emits on a quota limit is still unmeasured, and a detector built on a guessed signal is a
+  detector that never fires — so the record is fixed today and the cause stays honestly unnamed
+  until the raw document of a rate-limited turn is captured.
+
+## 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

package/README.md

@@ -335,6 +335,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.23.0 | 2026-09-14 | `beta` | `tldrx story reopen --as-is` now settles a story whose work is already merged into the epic but whose review never completed (`n-a` or `error` on its last recorded merge): a new, named review-only case that merges nothing and only routes the story to its reviewer, read from an additive ledger field; the existing refusal ("no commit the epic has not got") is untouched and now names the standing verdict when one exists (`changes`, `approve`, `fixlist` still refuse). A fix list whose findings are all deferred settles the story `done` instead of spawning a developer with nothing to fix, measured on a live run that paid for four such developers (#295). And a turn that died on a provider limit no longer records `success` borrowed from the provider's own subtype: the failure record says what the host saw (#296, first half — DETECTING the provider limit as its own non-execution kind is #298 and is NOT in this release). Minor release: `story reopen --as-is` behaves differently in a situation that exists today. |
+| 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`. |

package/dist/hooks/budget-gate.js

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

package/dist/hooks/{chunk-f5wkn522.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-6qnsx1tz.js → chunk-ah1pdax3.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-f5wkn522.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-6qnsx1tz.js";
+} from "./chunk-ah1pdax3.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-f5wkn522.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-6qnsx1tz.js";
-import"./chunk-f5wkn522.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

@@ -16449,7 +16449,7 @@ var ENTRIES = [
       {
         name: "as-is",
         arg: null,
-        meaning: "Settle the story from its BRANCH AS IT STANDS: the next Build turn runs the dod, the review and the merge over the commits already on `story/<run>/<id>`, and spawns NO developer. For a story a person finished by hand — a rebase after a conflict, a fix typed directly on the branch — which the plain verb cannot land, because a developer handed finished work has nothing to do and the story blocks on the no-work rule. It is not a shortcut past a gate: a red dod blocks the story, and so does a branch carrying no commit its epic has not already got. Requires --note; refused together with --for-fix.",
+        meaning: "Settle the story from its BRANCH AS IT STANDS: the next Build turn runs the dod, the review and the merge over the commits already on `story/<run>/<id>`, and spawns NO developer. For a story a person finished by hand — a rebase after a conflict, a fix typed directly on the branch — which the plain verb cannot land, because a developer handed finished work has nothing to do and the story blocks on the no-work rule. It is not a shortcut past a gate: a red dod blocks the story, and so does a branch carrying no commit its epic has not already got — with one named exception: a story whose work is ALREADY on the epic from an earlier turn and whose review never completed (the reviewer died, or the attempt after the merge died with no work) is settled review-only: nothing is merged, the dod runs on the epic head and the reviewer judges the range the story was merged as; a review that stands (`approve`, `changes`, `fixlist`) still refuses. Requires --note; refused together with --for-fix.",
         sub: "reopen"
       },
       runFlag(),
@@ -20652,10 +20652,17 @@ function describe4(exitCode, doc, stderr, timedOut, stdout, provider) {
     return `${name} exited ${exitCode} without a parseable result event: ${tail}`;
   }
   const errors2 = Array.isArray(doc.errors) ? doc.errors.filter((e) => typeof e === "string") : [];
-  const reason = errors2[0] ?? (typeof doc.subtype === "string" ? doc.subtype : "") ?? "";
-  const suffix = reason === "" ? "" : `: ${String(reason)}`;
-  return `${name} exited ${exitCode} with is_error=${String(doc.is_error === true)}${suffix}`;
-}
+  const verdict = `${name} exited ${exitCode} with is_error=${String(doc.is_error === true)}`;
+  const named = typeof errors2[0] === "string" && errors2[0] !== "" ? errors2[0] : "";
+  if (named !== "")
+    return `${verdict}: ${named}`;
+  const subtype = typeof doc.subtype === "string" ? doc.subtype : "";
+  if (subtype !== "" && !SUCCESS_SUBTYPES.has(subtype))
+    return `${verdict}: ${subtype}`;
+  const contradiction = subtype === "" ? "" : ` (the provider's own subtype said "${subtype}")`;
+  return `${verdict}: no reason named${contradiction}`;
+}
+var SUCCESS_SUBTYPES = new Set(["success"]);
 function firstLine3(text2) {
   const line = text2.split(`
 `).map((l) => l.trim()).find((l) => l !== "");
@@ -25937,6 +25944,7 @@ function carriedFindings(findings2) {
   return findings2.filter((f) => f.disposition === "defer-with-log" && !(f.resolved && f.resolvedSha !== null));
 }
 var CLAIMED_UNVERIFIED = "claimed-unverified";
+var FIXLIST_SETTLED_MARK = "every finding is routed away from `fix-now`, so the story is done without a fix round";
 function parseFixFindings(value) {
   const problems = [];
   const format = [];
@@ -26452,8 +26460,16 @@ function reviewStillOwed(outcome) {
 }
 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) {
-  return ahead === null ? `${AS_IS_NOT_AHEAD_MARK}: git could not count what \`${branch}\` carries beyond ` + `\`${epicBranch}\`, and a settlement that spawns no developer will not merge on a ` + "measurement it does not have. Nothing was merged" : `${AS_IS_NOT_AHEAD_MARK}: \`${branch}\` carries no commit \`${epicBranch}\` has not already ` + "got, so there is no work to settle. Commit the fix to the story branch first, then reopen it " + "--as-is. Nothing was merged";
+var AS_IS_JUDGED_MARK = "the last review of that work stands";
+var AS_IS_REVIEW_ONLY_MARK = "the review was run AS IT STANDS — nothing was merged and no developer was spawned";
+function asIsNotAheadReason(branch, epicBranch, ahead, judged) {
+  if (ahead === null) {
+    return `${AS_IS_NOT_AHEAD_MARK}: git could not count what \`${branch}\` carries beyond ` + `\`${epicBranch}\`, and a settlement that spawns no developer will not merge on a ` + "measurement it does not have. Nothing was merged";
+  }
+  return `${AS_IS_NOT_AHEAD_MARK}: \`${branch}\` carries no commit \`${epicBranch}\` has not already ` + "got, so there is no work to settle" + (judged === undefined ? "" : `, and ${AS_IS_JUDGED_MARK} — \`${judged.commit.slice(0, 7)}\` is on \`${epicBranch}\` and its ` + `review said \`${judged.verdict}\`, so the review is not what is owed`) + ". Commit the fix to the story branch first, then reopen it --as-is. Nothing was merged";
+}
+function reviewNeverCompleted(verdict) {
+  return verdict === "n-a" || verdict === "error";
 }
 function scopedNote(result2) {
   if (result2.scope !== "paths" || result2.rendered === undefined)
@@ -26477,7 +26493,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} *)`);
 }
@@ -26502,6 +26534,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;
@@ -26605,8 +26725,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",
     "",
@@ -26619,8 +26742,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",
     "",
@@ -28715,78 +28839,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("|");
@@ -28972,7 +29024,7 @@ function renderReviewLog(outcome) {
     `- Repo: \`${outcome.repo}\` · wave ${outcome.wave} · epic ${outcome.epic}`,
     `- Branch: \`${outcome.branch}\` → \`${outcome.epicBranch}\` (${mergeWord(outcome)})`,
     `- Commit: ${outcome.commit ?? "(none)"}`,
-    ...outcome.asIs == null ? [] : [`- Developer: **none** — ${AS_IS_MARK}. \`${outcome.branch}\` was settled as it stands, ` + `signed by ${outcome.asIs.actor}: ${outcome.asIs.note}. The Definition of Done below and ` + "the reviewer above judged that branch, unchanged."],
+    ...outcome.asIs == null ? [] : outcome.asIs.reason === "review-only" ? [`- Developer: **none** — ${AS_IS_REVIEW_ONLY_MARK}. \`${outcome.asIs.reviewed?.commit ?? outcome.commit ?? "(none)"}\` ` + `was already on \`${outcome.epicBranch}\` from an earlier turn and nothing had judged it; ` + `signed by ${outcome.asIs.actor}: ${outcome.asIs.note}. The Definition of Done below ran on the ` + "epic head, and the reviewer above judged the range that merge was recorded as."] : [`- Developer: **none** — ${AS_IS_MARK}. \`${outcome.branch}\` was settled as it stands, ` + `signed by ${outcome.asIs.actor}: ${outcome.asIs.note}. The Definition of Done below and ` + "the reviewer above judged that branch, unchanged."],
     ...outcome.developerError === null ? [] : [`- Developer: **FAILED** — ${outcome.developerError}`],
     ...outcome.permissionRefused == null ? [] : [withCure(`- 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.permissionRefused, outcome.declaredCommands)],
     ...outcome.budgetDeath == null ? [] : [`- Developer: died on its per-story cap — ${outcome.budgetDeath}; the tree held work, ` + "so the Definition of Done below decided"],
@@ -36574,6 +36626,7 @@ function readReviewLedger(runDir, storyId) {
     blockedWithNothingRun: false,
     reopened: null,
     asIs: null,
+    lastMerge: null,
     fixRound: null,
     formatRetries: 0,
     formatRefusal: null,
@@ -36595,6 +36648,7 @@ function readReviewLedger(runDir, storyId) {
   let lastDodOutputPath = null;
   let reopened = null;
   let asIs = null;
+  let lastMerge = null;
   let fixRound = null;
   let formatRetries = 0;
   let formatRefusal = null;
@@ -36662,6 +36716,13 @@ function readReviewLedger(runDir, storyId) {
         commit2 = payload.commit;
       if (typeof payload.epic_base === "string" && payload.epic_base !== "")
         epicBase = payload.epic_base;
+      if (typeof payload.commit === "string" && payload.commit !== "" && typeof payload.epic_base === "string" && payload.epic_base !== "") {
+        lastMerge = {
+          commit: payload.commit,
+          epicBase: payload.epic_base,
+          verdict: typeof payload.verdict === "string" && payload.verdict !== "" ? payload.verdict : "n-a"
+        };
+      }
       if (payload.status === "done")
         fixRound = null;
       asIs = null;
@@ -36725,6 +36786,7 @@ function readReviewLedger(runDir, storyId) {
     blockedWithNothingRun,
     reopened,
     asIs,
+    lastMerge,
     fixRound,
     formatRetries,
     formatRefusal,
@@ -39394,7 +39456,22 @@ class BuildSession {
       };
     }
     const ahead = await commitsBetween(story.repoDir, story.epicBranch, story.branch);
-    if (ahead === null || ahead === 0) {
+    if (ahead === 0) {
+      const merge = readReviewLedger(this.ctx.runDir, id).lastMerge;
+      if (merge !== null && reviewNeverCompleted(merge.verdict)) {
+        return await this.reviewOnlyHalf(planned, asIs, story, before, merge);
+      }
+      return {
+        story,
+        cost: 0,
+        dod: [],
+        commit: null,
+        failure: asIsNotAheadReason(story.branch, story.epicBranch, ahead, merge === null ? undefined : merge),
+        developerError: null,
+        before
+      };
+    }
+    if (ahead === null) {
       return {
         story,
         cost: 0,
@@ -39432,6 +39509,27 @@ class BuildSession {
     }
     return { story, cost: 0, dod, commit: commit2, failure: null, developerError: null, before };
   }
+  async reviewOnlyHalf(planned, asIs, story, before, merge) {
+    const id = planned.story.id;
+    const reviewed = { commit: merge.commit, epicBase: merge.epicBase };
+    this.asIsSettlements.set(id, { ...asIs, reason: "review-only", reviewed });
+    this.lines.push(`  · ${id}: ${AS_IS_REVIEW_ONLY_MARK} — \`${merge.commit.slice(0, 7)}\` is already on ` + `\`${story.epicBranch}\` and nothing judged it; running the dod on the epic head and the review ` + `over \`${reviewDiffRange(merge.epicBase, story.epicBranch, story.branch)}\``);
+    await this.writes.run(() => this.refreshStoryBase(planned, story.repoDir, story.worktree, story.branch, story.epicBranch));
+    const dod = await this.runDod(story);
+    if (!this.dodProves(dod)) {
+      const failing = dodFailure(dod);
+      return {
+        story,
+        cost: 0,
+        dod,
+        commit: null,
+        failure: failing === undefined ? "the story declares no dod commands, so nothing could prove it" : dodFailureReason(failing, planned.story.repo),
+        developerError: null,
+        before
+      };
+    }
+    return { story, cost: 0, dod, commit: merge.commit, failure: null, developerError: null, before, reviewOnly: reviewed };
+  }
   async buildHalf(planned) {
     const asIs = this.asIsFor(planned);
     if (asIs !== null)
@@ -39570,6 +39668,10 @@ class BuildSession {
       await this.block(story, "the story produced no commit to review", half.cost, dod);
       return "settled";
     }
+    if (half.reviewOnly !== undefined) {
+      this.noteMerged(story, null);
+      return await this.reviewAndSettle(story, dod, half.reviewOnly.commit, half.cost, null, half.reviewOnly.epicBase);
+    }
     const update = await updateStoryBase({
       storyId: story.planned.story.id,
       repoDir: story.repoDir,
@@ -39654,6 +39756,21 @@ class BuildSession {
     if (review.verdict === "fixlist") {
       const rel = this.writeFixlistFor(story, review, commit2, epicBase);
       const open2 = openFindings(review.fixlist).length;
+      if (open2 === 0) {
+        this.lines.push(`  · ${story.planned.story.id}: ${FIXLIST_SETTLED_MARK} (${rel})`);
+        await this.settle(story, "done", {
+          dod,
+          commit: commit2,
+          merged: true,
+          carried,
+          epicBase,
+          verdict: "fixlist",
+          review,
+          cost,
+          reason: null
+        });
+        return "settled";
+      }
       await this.settle(story, "review", {
         dod,
         commit: commit2,
@@ -40456,12 +40573,13 @@ class BuildSession {
       ...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 }
+      ...outcome.asIs == null ? {} : { as_is: true, as_is_by: outcome.asIs.actor, as_is_note: outcome.asIs.note },
+      ...outcome.asIs?.reason === undefined ? {} : { as_is_reason: outcome.asIs.reason }
     });
     if (pruning && (rescued === null || rescued.worktree === null)) {
       await removeWorktree(story.repoDir, story.worktree);
     }
-    this.lines.push(`  ${status === "done" ? "✓" : "·"} ${id} → \`${status}\`` + (outcome.reason === null ? "" : ` (${outcome.reason})`) + (outcome.asIs == null ? "" : ` — ${AS_IS_MARK}; ${outcome.asIs.actor} signed it`) + (outcome.permissionRefused == null ? "" : ` — ${withCure(`\`${outcome.permissionRefused}\` was refused for approval; the tree held committed work, so the DoD decided`, outcome.permissionRefused, outcome.declaredCommands)}`));
+    this.lines.push(`  ${status === "done" ? "✓" : "·"} ${id} → \`${status}\`` + (outcome.reason === null ? "" : ` (${outcome.reason})`) + (outcome.asIs == null ? "" : ` — ${outcome.asIs.reason === "review-only" ? AS_IS_REVIEW_ONLY_MARK : AS_IS_MARK}; ` + `${outcome.asIs.actor} signed it`) + (outcome.permissionRefused == null ? "" : ` — ${withCure(`\`${outcome.permissionRefused}\` was refused for approval; the tree held committed work, so the DoD decided`, outcome.permissionRefused, outcome.declaredCommands)}`));
   }
   writeLog(outcome) {
     const dir = join99(this.ctx.runDir, BUILD_PHASE, LOG_DIR);
@@ -49239,6 +49357,7 @@ function reopenStory(options) {
         `  signed by ${options.actor}: ${options.note}`,
         "  no developer will be spawned: the next Build turn runs the dod, the review and the merge " + "over the commits already on the story branch",
         "  it is not a shortcut past either gate — a red dod BLOCKS the story, and so does a branch " + "that carries no commit its epic has not already got; the refusal says which",
+        "  one named exception: work that is ALREADY on the epic with a review that never completed is " + "settled review-only — nothing merged, the dod on the epic head, the reviewer over the recorded range",
         "  the record will say the branch was taken as it stands and name you, so nothing reads as " + "though a developer delivered it",
         ...kept
       ]

package/package.json

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