tldr-experts 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # 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

package/README.md

@@ -335,6 +335,7 @@ 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`. |

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)
@@ -29008,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"],
@@ -36610,6 +36626,7 @@ function readReviewLedger(runDir, storyId) {
     blockedWithNothingRun: false,
     reopened: null,
     asIs: null,
+    lastMerge: null,
     fixRound: null,
     formatRetries: 0,
     formatRefusal: null,
@@ -36631,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;
@@ -36698,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;
@@ -36761,6 +36786,7 @@ function readReviewLedger(runDir, storyId) {
     blockedWithNothingRun,
     reopened,
     asIs,
+    lastMerge,
     fixRound,
     formatRetries,
     formatRefusal,
@@ -39430,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,
@@ -39468,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)
@@ -39606,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,
@@ -39690,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,
@@ -40492,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);
@@ -49275,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.22.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.22.0",
+  "version": "0.23.0",
   "author": {
     "name": "Alan Martinez"
   }