tldr-experts 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 0.26.1 — 2026-09-14
+
+### Changed
+
+- **A patch is fixes again, and this release is one: 0.26.1, not 0.27.0 (owner decision).**
+  MEASURED with `git tag -l`: v0.19.0 through v0.26.0 are eight releases, every one a minor and
+  none a patch, while 0.21.0, 0.22.0, 0.23.0, 0.25.0 and 0.26.0 carry nothing but `### Fixed`.
+  Mechanism: `docs/RELEASING.md` said "bump minor when a command, file schema or hook changes
+  behaviour; patch for fixes only", and every fix changes some command's behaviour — so the
+  rule had no fix left to call a patch, and the version number stopped telling an upgrader
+  whether a release was safe to take blind. The rule now reads by capability: a *patch* is
+  fixes, including a fix that makes a command do what it already promised (a refusal where it
+  should have refused, a message that keeps what it should say); a *minor* is a new
+  capability — a new command, flag, file field or schema, hook or event, or a changed meaning
+  of an existing one. The maintain skill used to gloss the old rule beside its citation, which
+  made two copies to move; it now cites `docs/RELEASING.md` "What to consider" only, and
+  `test/maintain-skill.test.ts` refuses a skill line that restates what a patch or a minor is
+  (RED on the old gloss, which it quoted).
+
+### Fixed
+
+- **A Build fix round whose developer lands no diff is refused, not settled `done` (#308).**
+  MEASURED live on a client workspace (0.24.0, two `--for-fix` reopens, one Build re-run): the
+  developer read the file, said it "already satisfies every acceptance criterion", spent $1.69
+  across two spawns and changed nothing — and the stage closed with the story `done`, the epic
+  head unchanged and every gap the reopen note named still in the tree. Mechanism, confirmed at
+  `f1c9aa8`: `commitIfDirty` hands back the OLD head sha on a clean tree, so `settleHalf`'s "no
+  commit to review" gate never fired, `mergeNoFf` was a no-op on an already-merged tip, and the
+  ledger closes a fix round on `done` alone. `workSince` — the "did the tree move since the one
+  the developer was handed" comparison the two refusal branches already use — was never asked on
+  the success path, where a fix round is precisely the case "nothing changed and the DoD is still
+  green" looks normal, because that tree was accepted once already. Now, for a story a PERSON put
+  back with a note — a fix round or a plain reopen, off the ledger — `buildHalf` asks it BEFORE
+  the DoD: no work, and the attempt blocks with the existing `task.done`/`blocked` vocabulary and
+  a reason that carries the note's first line (`NO_DIFF_MARK`, exported and pinned) — no DoD paid
+  for, no reviewer asked to judge an empty diff, the fix round still open because nothing landed.
+  A first attempt that lands nothing is deliberately NOT gated: "added nothing — identical to the
+  epic" is a pinned rendering decision, not this defect. Three RED tests in
+  `test/story-reopen.test.ts` (no-write developer on a fix round, the same bytes rewritten, a
+  no-write developer on a plain reopen — each settled `done` before); the neighbouring fix-round
+  tests now land a REAL diff, because the fake developer's default rewrote the bytes the first
+  attempt committed, which is #308's shape exactly. Golden byte-identical.
+- **`tldrx ship` refuses an epic carrying a story the reviewer rejected (#282).** MEASURED on a
+  live unattended run (0.18.2, 8 stories), story S5: DoD green, `48f8bdd merge(S5)` on the epic,
+  THEN `check.failed check:review verdict:changes`; the requeue did the same (`7fd2468 merge(S5)`,
+  `changes` again) and the story settled `blocked` — the epic carried, twice, code the reviewer
+  rejected twice. Merging BEFORE the review is design (#166: the reviewer reads the merged diff from
+  the epic base) and every verdict settles with `merged: true`; the defect was downstream. `ship`'s
+  only story refusal was #210's "zero stories done", so with one `done` story beside S5 it pushed
+  the epic and opened the PR with the rejected code in its diff, while the body listed S5 under
+  "Not done" with no word that the diff was there — a record lying in the dangerous direction (§7).
+  Reproduced at `bdc43e7` with the fake agent (`GOLDEN_ROUNDS`, S2 scripted `changes` twice): S1
+  `done`, S2 `blocked`, every S2 `task.done` commit an ancestor of `epic/e1`, and `ship --dry-run`
+  exited 0 printing the `gh pr create` line. Now `ship` asks the ledger's `lastMerge` (#295 — the
+  last `task.done` carrying `commit` and `epic_base`, which survives a reopen precisely so "what
+  does the epic hold" can be asked) for every story not `done`, and a `changes` there is a
+  rejection that stands: exit 2 — a gate DID say no, unlike #210's 1 — naming the story, the merge
+  and the handoff's own reason, with #210's remedy (`tldrx story reopen <id> --note`, re-run Build,
+  or open the PR by hand). Not widened to a merged diff nobody judged (`n-a`/`error`) — that is #311,
+  filed from this change. Guards, all passing before: a `changes` a later attempt merged over and got approved
+  ships; a story whose diff never merged ships; a story parked at `review` under a SIGNED fix list
+  ships with its findings listed. Two mutations of the predicate each redden a different test.
+  Golden byte-identical: nothing in Build changed. The unattended path was already closed one
+  door earlier — the auto gate refuses to self-sign over any story not `done`
+  (`autoGate.ts` `UNFINISHED_STORIES`, pinned in `test/build-executor.test.ts`) — so this reaches
+  a PR only after a person approved the Build gate, which is exactly when the record has to say
+  what the diff contains.
+
+- **A stage-failure line keeps the branch it exists to name when the worktree path is wider than
+  the line (#310, #293).** MEASURED 2026-09-14 under a ~115-char session scratchpad, the very place
+  `AGENTS.md §2` sends every agent to work: the epic-worktree refusal put the absolute path FIRST
+  and the two branch names after it, `oneLine` kept the first 220 chars, and the operator line —
+  and `run.yml`'s task row, and the `stage.failed` event — read `epic worktree /private/tmp/…/
+  _epic-260829-build-E1 is checked out on \`epic/someb…`: the branch cut two characters in, while
+  the same test passed on the same sha under a short `TMPDIR`. A refusal that loses its subject
+  exactly when the path is long is a refusal that names the wrong thing when it matters most.
+  Two halves, one implementation each: `assertWorktreeOn` now says the branches first and the
+  path last (`… is checked out on \`X\`, not \`Y\` — refusing … — at <path>`), and `oneLine`'s
+  cap keeps a line's head AND its tail, losing the middle — so what a cut takes is the middle of
+  a directory whose root the operator already knows. The cap itself stays at 220: each of the
+  three records is still one bounded line. `test/build-executor.test.ts` builds the refusal under
+  a path wider than the cap on purpose (the fixture roots in `os.tmpdir()`, which reads
+  `TMPDIR` at call time) and pins both branches, the worktree's own directory and the bound in
+  all three records — RED on the old order (only the path and `…` survived), and each half
+  reverted alone reddens it on its own assertion; the unit test on `assertWorktreeOn` pins the
+  order. The existing WRONG-branch test asserts the worktree's relative directory rather than
+  the whole absolute path, so it no longer depends on how long the box's `TMPDIR` is.
+
 ## 0.26.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.26.1 | 2026-09-14 | `beta` | Three refusals that stop a bad state from settling quietly. A Build fix round whose developer lands no diff is refused before the DoD instead of closing `done` on an unmoved tree, because `commitIfDirty` hands back the old head sha on a clean commit and the existing "no commit to review" gate never fires for it — `workSince` is now asked on the success path too, for any story a person put back with a note. `tldrx ship` refuses an epic carrying a story the reviewer marked `changes`: it asks the ledger's `lastMerge` for every story not `done` and exits 2 naming the story, the merge and the handoff's reason, instead of opening a PR whose "Not done" list hid rejected code already merged into the diff. And a stage-failure line keeps the branch it names when the worktree path is wider than the line: the refusal puts the branches before the path, and `oneLine` keeps a line's head and tail instead of dropping the identifiers that sat at the end. |
 | 0.26.0 | 2026-09-14 | `beta` | Two field defects from the same class — a reader of an event payload trusting a field its writer never set — plus the ceiling that killed the turn that earned it. A wide story's measured `touches_widened` no longer throws after the turn has settled: the cap knows the three lists by name and drops them whole by count, every reader derives before/after through one function, and an executor that throws after paid turns leaves their rows and money in `run.yml` and saves before it emits. The cost surfaces then agree with each other: a turn whose result was lost to that fault reads as UNMETERED, LOWER BOUND on `tldrx cost` and in the Build handoff through the door other unmeasured turns already use, a turn still in flight reads as nothing, and a late result retires the lost mark instead of counting twice. Replay reads the reason a failed stage recorded instead of printing "no reason recorded" for every one. |
 | 0.25.0 | 2026-09-14 | `beta` | The other half of the two-session protocol and four holes measured on live runs. `scripts/release.sh` now waits on a running wave's lock before touching the tree and never hands back the marker it wrote — release has precedence, the wave yields, exit 14 when it gives up; the heading gate also refuses an unreleased version at or below `package.json`; the marker carries its phase and `--status` reports a release queued behind a wave (#304). In-session `tldrx next --prepare` and `--commit` ask the same dependency frontier the headless loop asks: a terminal hold records the dependent `blocked`, a pending hold refuses without writing, a held `--commit` keeps the work it sits on and says where it is (#300). A Watch card refused for an unsourced `## Where` item comes back to its writer marked, the refusal names the cure, and the brief shows one non-file example, so a retry edits the card instead of regenerating it blind (#301). And `run.yml` no longer loses an external write to a live loop: a save carries only the fields the store changed over a fresh read, ownership is declared, `cancelled` is terminal and wins in the file and in the process, a file that cannot be merged is kept beside as `.bak` and said so, and a file recording another run is refused (#305). Minor release: a new exit code on a public script, a stricter merge gate, and `--prepare`/`--commit` refuse where they used to proceed. |
 | 0.24.0 | 2026-09-14 | `beta` | Five fixes from one unattended night, all measured on live runs. The two-session protocol is mechanical where it was chat: the merge wave refuses a merged tree with two unreleased CHANGELOG headings or one at or below the last release (exit 12), `release.sh` holds a `.RELEASE-IN-PROGRESS` marker the wave waits on (exit 13 when it gives up), `merge-wave.sh --status` reads holder, branch and phase in one line, and the `maintain` skill gains a worker-mode section (#299). A per-story cap says what it was derived from — plan price × stage scale — and names the lever that moves it, and a plan whose prices exceed the stage budget is told so instead of being scaled in silence (#281). A story whose dependency is still at `review` waits in `todo` instead of being written `blocked`, and a dependency block left by an earlier version is released once the dependency is `done` (#280). `--until-done` compares the refusal across attempts, not the advice line printed under it, so a failure that made progress keeps its relaunches (#297). And the Build handoff no longer fails its own `claim-sources` check over a refused command that spans lines: one physical line per element, the break shown as `⏎` and explained once in the document (#283). Minor release: the wave and `--until-done` behave differently in situations that exist today. |

package/dist/tldrx.js

@@ -16573,6 +16573,7 @@ var ENTRIES = [
       "It pushes ONLY when the run says so. Publishing a branch is a decision, so by default a branch the remote has not seen is a refusal that names the `git push` command rather than running it. The decision is taken once, at `tldrx run new --ship <push|pr|merge>` (#253): then this verb pushes the epic first, through the one push wrapper in the codebase (the Build phase itself still has none, spec §5), and under `merge` arms `gh pr merge --auto --merge` after the PR opens — unless the PR reports NO check at all, or the BASE branch was not seen to require one (#274: `--auto` waits on the base's requirements, not on the PR's reported checks, so over a base that requires nothing it merges at once), in which case the PR is left open and run.yml says which absence it was. `run auto` calls this verb when it sees the run close and skips a run whose record already carries `shipped_at`; typing `tldrx ship` again is the recovery after a partial failure — a repo whose merge is recorded `failed` is armed again, one recorded `queued` is left alone, and the record is the union, so a recorded failure is never erased. A run without the block is never written.",
       "The body is WRITTEN for a PR (#167): an **Outcome** line saying how much of the plan landed (`partial: 1 of 3 stories delivered; S2 — …`); what shipped and what did not, from the handoff's own done/not-done split; the reviewer findings still open, read from the run's fix lists; and the LAST phase handoff the run has on disk — `04-build/handoff.md` on a run that built something — verbatim and complete, inside a `<details>` block. It goes to `gh` as a file, never as an argument, so a long body cannot overflow an argv limit.",
       "It REFUSES a run that delivered no story (exit 1 — nothing behind it, #210). `ship` already knew: the body it renders keeps only the handoff bullets that say `done`, and with none it wrote `(nothing settled `done` in this run)` into a PR it opened anyway. The refusal names the counts and the first blocked story's own reason, and `--dry-run` is refused in the same words. A run that delivered at least one story ships exactly as it did before.",
+      "It REFUSES an epic carrying a story the reviewer REJECTED (exit 2 — a gate said no, #282). A story merges into its epic BEFORE its review, by design, so a `changes` verdict leaves the diff on the branch: with one story `done` beside it the PR opened with the rejected code in its diff and a body that listed the story under \"Not done\" without saying so. The refusal reads the ledger's last merge for every story not `done` — the last `task.done` carrying `commit` and `epic_base` — and names the story, that merge and the handoff's own reason. A `changes` a later attempt merged over and got approved is not a rejection, a story whose diff never merged has nothing to refuse, and a story parked at `review` under a SIGNED fix list ships with its findings listed. `--dry-run` is refused in the same words.",
       "It moves no gate and no cursor and appends no event. On a run with no `ship:` block it never writes to the run at all; on a run with one it writes exactly that block's record (`pr_urls`, `merge`, `merges`, `shipped_at`) and nothing else. To mirror the plan's epics and stories to a ticket tool, `tldrx tickets sync` is the verb that does that, and it stays separate.",
       "It refuses cleanly, in a sentence, when there is no epic branch, no handoff, no remote, no `gh` on PATH, or when several epic branches leave the choice open.",
       "When the branch exists in SEVERAL repos — the normal shape of a chained multi-repo run, whose epics share one integration branch — it opens one PR per repo: the same body, the repo name in the title, and every URL listed at the end. `--repo` narrows it to one.",
@@ -25908,7 +25909,7 @@ async function assertWorktreeOn(path, branch, what = "worktree") {
   const on = await currentBranch(path);
   if (on === branch)
     return;
-  throw new WorktreeBranchMismatchError(`${what} ${path} is checked out on \`${on === "" ? "(no branch)" : on}\`, not \`${branch}\` — ` + "refusing to touch it, because a merge here would land on another run's branch");
+  throw new WorktreeBranchMismatchError(`${what} is checked out on \`${on === "" ? "(no branch)" : on}\`, not \`${branch}\` — ` + `refusing to touch it, because a merge here would land on another run's branch — at ${path}`);
 }
 async function shaReachability(cwd, sha, ref) {
   const resolved = await git(["rev-parse", "--verify", "--quiet", `${sha}^{commit}`], cwd);
@@ -26572,6 +26573,11 @@ var AS_IS_MARK = "the branch was taken AS IT STANDS — no developer was spawned
 var AS_IS_NOT_AHEAD_MARK = "nothing to take as it stands";
 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";
+var NO_DIFF_MARK = "the developer produced no diff";
+function noDiffAfterReopenReason(parts) {
+  const round4 = parts.fix ? "the fix round" : "the reopen";
+  return `${NO_DIFF_MARK}: the tree is the one it was handed (\`${parts.handed.slice(0, 7)}\`), ` + `and ${round4} ${parts.actor} signed says \`${firstLine7(parts.note)}\`. ` + "Nothing changed, so nothing could have landed it — no DoD ran and no reviewer was spawned. " + "Reopen it with a note that names what the developer has to change";
+}
 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";
@@ -40086,6 +40092,26 @@ class BuildSession {
         before
       };
     }
+    const reopen = this.reopenFor(planned);
+    if (reopen !== null) {
+      const proven = await workSince({
+        workspaceRoot: this.workspace.root,
+        repoDir: story.repoDir,
+        worktree: story.worktree,
+        since: handed
+      });
+      if (!proven) {
+        return {
+          story,
+          cost: spent,
+          dod: [],
+          commit: null,
+          failure: noDiffAfterReopenReason({ handed, ...reopen }),
+          developerError: null,
+          before
+        };
+      }
+    }
     const dod = await this.runDod(story);
     if (!this.dodProves(dod)) {
       const failing = dodFailure(dod);
@@ -40455,6 +40481,14 @@ class BuildSession {
       return;
     this.lines.push(`  · ${planned.story.id} was reopened by ${ledger4.reopened.actor} (${ledger4.reopened.note}) — ` + `the verdicts before that do not count against it, so it runs as attempt 1 of ${String(this.attempts)}`);
   }
+  reopenFor(planned) {
+    const ledger4 = readReviewLedger(this.ctx.runDir, planned.story.id);
+    if (ledger4.fixRound !== null)
+      return { note: ledger4.fixRound.note, actor: ledger4.fixRound.actor, fix: true };
+    if (ledger4.reopened !== null)
+      return { note: ledger4.reopened.note, actor: ledger4.reopened.actor, fix: false };
+    return null;
+  }
   waveFailed(wave) {
     return wave.stories.some((planned) => this.statusOf(planned) === "blocked");
   }
@@ -43531,7 +43565,10 @@ function nowish(options) {
 function oneLine7(text3, max = 220) {
   const line = text3.split(`
 `)[0]?.trim() ?? "";
-  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+  if (line.length <= max)
+    return line;
+  const tail2 = Math.floor((max - 1) / 2);
+  return `${line.slice(0, max - 1 - tail2)}…${line.slice(line.length - tail2)}`;
 }
 function phaseMoney(store, phaseId) {
   const phase = store.budget.phases.find((entry) => entry.id === phaseId);
@@ -43746,6 +43783,19 @@ async function shipRun(options) {
     };
   }
   const stories = runStories(store);
+  const rejected = rejectedOnEpic(store.runDir, stories, view);
+  if (rejected.length > 0) {
+    const ids = rejected.map((row2) => row2.id);
+    return refuse2([
+      `${store.runId} carries a story the reviewer rejected, and its diff is on \`${branch}\``,
+      ...rejected.map((row2) => `  ${row2.id} — its last merge into the epic (commit ${row2.commit.slice(0, 7)} over epic base ` + `${row2.epicBase.slice(0, 7)}) was judged \`changes\`${row2.reason === null ? "" : `: ${row2.reason}`}`),
+      "  A story merges into the epic BEFORE its review, so a `changes` verdict leaves the diff on the branch;",
+      `  a PR over \`${branch}\` would carry that code, and its body would list ${ids.join(", ")} under "Not done"`,
+      "  without saying the diff is there.",
+      `  Unblock ${ids.length === 1 ? "it" : "them"} (` + (ids.length === 1 ? `\`tldrx story reopen ${ids[0] ?? ""} --note "<why>"\`` : `\`tldrx story reopen <id> --note "<why>"\` for each`) + ") and re-run Build so a verdict that stands lands over it,",
+      "  or open the PR by hand if you mean to ship the branch as it stands."
+    ]);
+  }
   const body = writeShipBody(store, branch, handoff, stories, new Set(loadWorkspace(options.root).repos.keys()));
   try {
     return await shipTo(options, store, branch, body, stories);
@@ -44195,6 +44245,23 @@ function remedyPaths(refused2, excused) {
     return `${PROJECT_WORK_DIR} ${PROJECT_FRAMEWORK_DIR}`;
   return refused2.map(quote2).join(" ");
 }
+function rejectedOnEpic(runDir2, stories, view) {
+  const rows = [];
+  for (const story of stories) {
+    if (story.status === "done")
+      continue;
+    const merge = readReviewLedger(runDir2, story.id).lastMerge;
+    if (merge === null || merge.verdict !== "changes")
+      continue;
+    rows.push({
+      id: story.id,
+      commit: merge.commit,
+      epicBase: merge.epicBase,
+      reason: view?.unfinished.find((row2) => row2.id === story.id)?.reason ?? null
+    });
+  }
+  return rows;
+}
 function settledTouches(stories) {
   const rows = [];
   for (const story of stories) {

package/package.json

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