tldr-experts 0.18.2 → 0.18.3

package/dist/tldrx.js

@@ -7290,6 +7290,7 @@ var EVENT_TYPES = [
   "questions.policy_changed",
   "story.reopened",
   "story.base_fastforwarded",
+  "story.base_updated",
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",
@@ -8361,6 +8362,16 @@ function withoutSrcToken(line) {
 function hasSrcMarker(line) {
   return line.includes(SRC_MARKER);
 }
+function unclosedSrcMarker(text) {
+  const open = text.lastIndexOf(SRC_MARKER);
+  if (open < 0)
+    return null;
+  return text.includes("]", open + SRC_MARKER.length) ? null : open;
+}
+function foldsUnclosedSrcMarker(line) {
+  const token = parseSrcToken(line);
+  return token !== null && token.raw.indexOf(SRC_MARKER, SRC_MARKER.length) >= 0;
+}
 function classifySrc(src, repos) {
   const raw = src;
   if (raw === "")
@@ -10405,8 +10416,7 @@ function splitArgv(command) {
   if (/[\n\r]/.test(command))
     return null;
   const argv = [];
-  const pattern = /"([^"]*)"|'([^']*)'|([^\s"']+)/g;
-  for (const match of command.matchAll(pattern)) {
+  for (const match of command.matchAll(TOKEN_RE)) {
     if (match[1] !== undefined || match[2] !== undefined) {
       argv.push(match[1] ?? match[2] ?? "");
       continue;
@@ -10418,6 +10428,21 @@ function splitArgv(command) {
   }
   return argv.length === 0 ? null : argv;
 }
+var TOKEN_RE = /"([^"]*)"|'([^']*)'|([^\s"']+)/g;
+var SEPARATOR_RE = /\|\||&&|2>&1|>>|\$\((?!\()|[|&;<>`]/;
+function unquotedShellSeparator(command) {
+  if (/[\n\r]/.test(command))
+    return `
+`;
+  for (const match of command.matchAll(TOKEN_RE)) {
+    if (match[1] !== undefined || match[2] !== undefined)
+      continue;
+    const found = SEPARATOR_RE.exec(match[3] ?? "");
+    if (found !== null)
+      return found[0];
+  }
+  return null;
+}
 
 class DodCommandRefused extends Error {
 }
@@ -11300,7 +11325,12 @@ function clean(text) {
   const stripped = text.replace(GROUNDING_TAG_RE, "").replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
   if (stripped.length <= MAX_CLAIM_CHARS)
     return stripped;
-  return `${stripped.slice(0, MAX_CLAIM_CHARS - 1).trimEnd()}…`;
+  const cut = stripped.slice(0, MAX_CLAIM_CHARS - 1);
+  const open = unclosedSrcMarker(cut);
+  if (open === null)
+    return `${cut.trimEnd()}…`;
+  const kept = cut.slice(0, open).trimEnd();
+  return kept === "" ? stripped : `${kept}…`;
 }
 
 // src/core/distill/aidlcQuestions.ts
@@ -13892,7 +13922,7 @@ function createRunLocked(options) {
       write(temp, handoffPath, handoff, written);
       const check = validateHandoff(handoff, toSrcContext(workspace, temp));
       if (!check.ok) {
-        throw new NewRunError(`seeded handoff is invalid: ${describeHandoff(check.missingSections, check.emptySections, check.unsourced, check.unresolved)}`);
+        throw new NewRunError(`seeded handoff is invalid: ${describeHandoff(check.missingSections, check.emptySections, check.unsourced, check.unresolved, handoff)}`);
       }
     }
     let factsYaml = null;
@@ -13926,7 +13956,7 @@ function createRunLocked(options) {
       const srcCtx = toSrcContext(workspace, temp);
       const handoffCheck = validateHandoff(handoff, srcCtx);
       if (!handoffCheck.ok) {
-        throw new NewRunError(`distilled handoff is invalid: ${describeHandoff(handoffCheck.missingSections, handoffCheck.emptySections, handoffCheck.unsourced, handoffCheck.unresolved)}`);
+        throw new NewRunError(`distilled handoff is invalid: ${describeHandoff(handoffCheck.missingSections, handoffCheck.emptySections, handoffCheck.unsourced, handoffCheck.unresolved, handoff)}`);
       }
       if (result2.conflicts.length > 0) {
         const text = renderQuestions(runId, phaseId, at, result2.conflicts);
@@ -14096,7 +14126,7 @@ function assertValid(what, validation) {
   const first = validation.issues[0];
   throw new NewRunError(`refusing to create a run with an invalid ${what}: ${first?.path ?? ""} ${first?.message ?? ""}`);
 }
-function describeHandoff(missing, empty, unsourced, unresolved) {
+function describeHandoff(missing, empty, unsourced, unresolved, text = "") {
   if (missing.length > 0)
     return `missing section(s) ${missing.join(", ")}`;
   if (empty.length > 0) {
@@ -14104,7 +14134,24 @@ function describeHandoff(missing, empty, unsourced, unresolved) {
   }
   if (unsourced.length > 0)
     return `unsourced bullet(s) on line(s) ${unsourced.join(", ")}`;
-  return unresolved[0]?.message ?? "unknown problem";
+  const first = unresolved[0];
+  if (first === undefined)
+    return "unknown problem";
+  return `${first.message}${foldedCitationNote(text, first.line)}`;
+}
+var MAX_QUOTED_CHARS2 = 120;
+function foldedCitationNote(text, line) {
+  if (text === "" || line < 1)
+    return "";
+  const raw = text.split(`
+`)[line - 1];
+  if (raw === undefined || raw.trim() === "")
+    return "";
+  if (!foldsUnclosedSrcMarker(raw))
+    return "";
+  const trimmed = raw.trim();
+  const quoted = trimmed.length <= MAX_QUOTED_CHARS2 ? trimmed : `${trimmed.slice(0, MAX_QUOTED_CHARS2)}…`;
+  return ` — L${String(line)} carries an unterminated \`[src:\` citation, so the path above is two ` + `citations folded into one and is not a file to look for; close or remove the inline citation ` + `in the seed (shorter bullets are safest). L${String(line)} reads \`${quoted}\``;
 }
 function yymmdd(now) {
   return now.toISOString().slice(2, 10).replace(/-/g, "");
@@ -25784,14 +25831,10 @@ async function mergeNoFf(cwd, branch, message4) {
     detail: conflicts.length > 0 ? `conflict in ${conflicts.join(", ")}` : firstLine7(merged.stderr) || firstLine7(merged.stdout) || `git merge exited ${String(merged.exitCode)}`
   };
 }
-async function commitsBetween(cwd, base, head) {
-  const result2 = await git(["rev-list", "--count", `${base}..${head}`], cwd);
-  if (!result2.ok)
-    return 0;
-  const n = Number.parseInt(result2.stdout.trim(), 10);
-  return Number.isFinite(n) ? n : 0;
+function uncountedCount(base, head) {
+  return `\`git rev-list --count ${base}..${head}\` could not count what it carries`;
 }
-async function commitsAhead(cwd, base, head) {
+async function commitsBetween(cwd, base, head) {
   const result2 = await git(["rev-list", "--count", `${base}..${head}`], cwd);
   if (!result2.ok)
     return null;
@@ -25799,12 +25842,15 @@ async function commitsAhead(cwd, base, head) {
   return Number.isFinite(n) ? n : null;
 }
 async function baseStateOf(cwd, branch, base) {
-  const ahead = await commitsBetween(cwd, base, branch);
-  const behind = await commitsBetween(cwd, branch, base);
+  const counted = await commitsBetween(cwd, base, branch);
+  const countedBack = await commitsBetween(cwd, branch, base);
+  const ahead = counted ?? 0;
+  const behind = countedBack ?? 0;
   return {
     state: behind === 0 ? "current" : ahead === 0 ? "behind" : "diverged",
     ahead,
     behind,
+    uncounted: counted === null ? uncountedCount(base, branch) : countedBack === null ? uncountedCount(branch, base) : null,
     branchSha: await shaOf(cwd, branch),
     baseSha: await shaOf(cwd, base)
   };
@@ -26364,6 +26410,9 @@ function scopedNote(result2) {
 function dodGreen(outcome) {
   return outcome.dod.length > 0 && outcome.dod.every((r) => !dodRefused(r) && r.exitCode === 0 && !r.timedOut);
 }
+function dodFailure(dod) {
+  return dod.find((r) => dodRefused(r) || r.exitCode !== 0 || r.timedOut);
+}
 function dodFailureReason(result2, repo) {
   if (dodRefused(result2)) {
     return `\`${result2.command}\` was REFUSED in repo ${repo} and never ran — ` + `${result2.refusedBecause ?? DOD_REFUSAL_FALLBACK}`;
@@ -26374,6 +26423,15 @@ function dodFailureReason(result2, repo) {
   return `\`${result2.rendered ?? result2.command}\`${scopedNote(result2)} exited ${String(result2.exitCode ?? "?")} in repo ${repo}` + `${result2.timedOut ? " (timed out)" : ""} — ${result2.tail}` + (result2.outputPath === undefined ? "" : ` [src: ${result2.outputPath}:${String(result2.outputLine ?? 1)}]`);
 }
 
+// src/core/build/developerGrants.ts
+var DEVELOPER_GIT_VERBS = ["add", "commit", "rm", "mv", "restore"];
+function developerGitGrants() {
+  return DEVELOPER_GIT_VERBS.map((verb) => `Bash(git ${verb} *)`);
+}
+function isDeveloperGitVerb(verb) {
+  return DEVELOPER_GIT_VERBS.includes(verb);
+}
+
 // src/core/build/prompts.ts
 var MAX_TOUCHED_BYTES = 64 * 1024;
 var MAX_TOUCHED_FILES = 24;
@@ -26403,6 +26461,10 @@ function testFastRule(fast, full) {
     ]
   ];
 }
+function gitVerbList() {
+  const names = DEVELOPER_GIT_VERBS.map((verb) => `\`git ${verb}\``);
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1] ?? ""}`;
+}
 function buildDeveloperPrompt(parts) {
   const { story } = parts.story;
   const extra = parts.story.extraInputs ?? [];
@@ -26472,7 +26534,9 @@ function buildDeveloperPrompt(parts) {
     ...parts.commands.length === 0 ? ["- (this repo declares no commands in workspace.yml — the DoD will run nothing)"] : parts.commands.map((command2) => `- \`${command2}\``),
     "",
     ...parts.testFast === undefined ? [] : [...testFastRule(parts.testFast.fast, parts.testFast.full), ""],
-    "Commit with `git add` and `git commit`. Nothing else about git is yours to do.",
+    `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.",
     "",
     "## Rules",
     "",
@@ -28581,6 +28645,68 @@ function verdictReviewer(checkPayload, lastSpawn) {
   return lastSpawn;
 }
 
+// src/core/build/refusalKind.ts
+var MAX_SEPARATOR_RETRIES = 1;
+function classifyRefusal(command2) {
+  const separator = unquotedShellSeparator(command2);
+  if (separator !== null)
+    return { kind: "separator", separator };
+  const argv = command2.trim().split(/\s+/);
+  if (argv[0] !== "git")
+    return { kind: "unknown" };
+  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 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 "unknown":
+      return "";
+  }
+}
+function withCure(sentence, command2) {
+  const cure = refusalCure(classifyRefusal(command2));
+  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("|");
@@ -28752,7 +28878,7 @@ function renderReviewLog(outcome) {
     `- Branch: \`${outcome.branch}\` → \`${outcome.epicBranch}\` (${mergeWord(outcome)})`,
     `- Commit: ${outcome.commit ?? "(none)"}`,
     ...outcome.developerError === null ? [] : [`- Developer: **FAILED** — ${outcome.developerError}`],
-    ...outcome.permissionRefused == null ? [] : [`- 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 == 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.budgetDeath == null ? [] : [`- Developer: died on its per-story cap — ${outcome.budgetDeath}; the tree held work, ` + "so the Definition of Done below decided"],
     "",
     "## Definition of done",
@@ -29354,7 +29480,7 @@ function renderBuildHandoff(parts) {
     "",
     ...notDone.length === 0 && (parts.carried ?? []).length === 0 && (parts.unreadableStories ?? []).length === 0 && (parts.foreignWork ?? []).length === 0 && (parts.notStarted ?? []).length === 0 && refusedButMeasured.length === 0 && diedButMeasured.length === 0 ? [`- none — every scheduled story reached \`done\` and no carried finding is unowned ` + `[src: absent:04-build/log]`] : [],
     ...notDone.map((o) => `- ${o.id} is \`${o.status}\` and needs a human: ${o.reason ?? "see the review"} ` + `[src: ${o.reviewRel}:1]`),
-    ...refusedButMeasured.map((o) => `- ${o.id}'s developer had \`${o.permissionRefused ?? ""}\` refused for approval by the agent's own ` + `permission layer; its tree held committed work, so the Definition of Done decided and the story is ` + `\`${o.status}\` — a person may still want to know the command it could not run [src: ${o.reviewRel}:1]`),
+    ...refusedButMeasured.map((o) => withCure(`- ${o.id}'s developer had \`${o.permissionRefused ?? ""}\` refused for approval by the agent's own ` + `permission layer; its tree held committed work, so the Definition of Done decided and the story is ` + `\`${o.status}\` — a person may still want to know the command it could not run`, o.permissionRefused ?? "") + ` [src: ${o.reviewRel}:1]`),
     ...diedButMeasured.map((o) => `- ${o.id}'s developer died on its per-story cap (${o.budgetDeath ?? ""}) with work in its tree, ` + `so the Definition of Done decided and the story is \`${o.status}\` — the plan priced this story ` + `below what it cost, which is worth knowing before the next one [src: ${o.reviewRel}:1]`),
     ...(parts.notStarted ?? []).map((row2) => `- ${row2.id} was scheduled and never started, and is still \`${row2.status}\` — ` + `${row2.reason} [src: ${row2.rel}:1]`),
     ...carriedBullets(parts.carried ?? []),
@@ -29769,9 +29895,9 @@ function quoteLine(text3, line) {
   if (found === undefined || found.trim() === "")
     return null;
   const trimmed = found.trim();
-  return trimmed.length <= MAX_QUOTED_CHARS2 ? trimmed : `${trimmed.slice(0, MAX_QUOTED_CHARS2)}…`;
+  return trimmed.length <= MAX_QUOTED_CHARS3 ? trimmed : `${trimmed.slice(0, MAX_QUOTED_CHARS3)}…`;
 }
-var MAX_QUOTED_CHARS2 = 120;
+var MAX_QUOTED_CHARS3 = 120;
 function describeHandoff2(rel, validation, text3 = "") {
   if (validation.ok)
     return [];
@@ -35532,6 +35658,10 @@ function storyWorktreePath(root2, repo, runId, storyId) {
 async function refreshStoryBase(parts) {
   const id = parts.storyId;
   const base2 = await baseStateOf(parts.repoDir, parts.branch, parts.epicBranch);
+  if (base2.uncounted !== null && base2.branchSha !== "") {
+    parts.lines.push(`  · ${id}: ${base2.uncounted} — \`${parts.branch}\` was left exactly as it is, ` + `and the dispatch below is on its current tip`);
+    return;
+  }
   if (base2.state === "current")
     return;
   const where = relative14(parts.root, parts.worktree) || parts.worktree;
@@ -35646,6 +35776,24 @@ async function rescueUncommitted(parts) {
     return { sha, branch: parts.branch, worktree: null, failure: null };
   });
 }
+async function updateStoryBase(parts) {
+  const base2 = await baseStateOf(parts.repoDir, parts.branch, parts.epicBranch);
+  if (base2.state === "current" && base2.uncounted === null)
+    return { kind: "current", why: null };
+  await assertWorktreeOn(parts.worktree, parts.branch, "story worktree");
+  const from = await headSha(parts.worktree);
+  const merged = await mergeNoFf(parts.worktree, parts.epicBranch, `sync(${parts.storyId}): \`${parts.epicBranch}\` moved under this story before it merged back`);
+  if (!merged.ok)
+    return { kind: "blocked", conflicts: merged.conflicts, detail: merged.detail };
+  const to = await headSha(parts.worktree);
+  if (to === from || to === "")
+    return { kind: "current", why: base2.uncounted };
+  return { kind: "updated", from, to, behind: base2.behind, uncounted: base2.uncounted };
+}
+function staleBaseConflict(branch, epicBranch, conflicts, detail, where) {
+  const files = conflicts.length > 0 ? conflicts.join(", ") : detail;
+  return `\`${epicBranch}\` moved since \`${branch}\` was cut, and bringing the story up to it ` + `CONFLICTS in ${files} — nothing was merged and nothing is half-applied. ` + `Resolve it in ${where} (\`git merge ${epicBranch}\`), then reopen the story`;
+}
 
 // src/core/build/entryProbe.ts
 import { accessSync, constants, existsSync as existsSync72, statSync as statSync20 } from "node:fs";
@@ -35892,7 +36040,7 @@ function asideBranchOf(epicBranch, ownerRunId) {
   return `${epicBranch}${ASIDE_SEPARATOR}${ownerRunId}`;
 }
 function uncountedReason(base2, branch) {
-  return `\`git rev-list --count ${base2}..${branch}\` could not count what it carries, ` + "and an uncounted branch is never deleted";
+  return `${uncountedCount(base2, branch)}, and an uncounted branch is never deleted`;
 }
 async function releaseEpicBranch(parts) {
   const { repoDir, branch } = parts;
@@ -35902,7 +36050,7 @@ async function releaseEpicBranch(parts) {
   if (checkout !== null) {
     return { kind: "kept", branch, reason: `it is checked out in ${checkout}` };
   }
-  const commits = await commitsAhead(repoDir, parts.base, branch);
+  const commits = await commitsBetween(repoDir, parts.base, branch);
   if (commits === null)
     return { kind: "kept", branch, reason: uncountedReason(parts.base, branch) };
   const sha = await shaOf(repoDir, branch);
@@ -38645,6 +38793,10 @@ async function rederiveImplicitPlan(ctx, workspace, parts, lines) {
   const content = implicitPlanContent(parts);
   const storyBranch = storyBranchOf(ctx.runId, IMPLICIT_STORY_ID);
   const commits = await commitsBetween(repoDirOf(workspace, content.repo), content.branch, storyBranch);
+  if (commits === null) {
+    kept(uncountedCount(content.branch, storyBranch));
+    return;
+  }
   if (commits > 0) {
     kept(`\`${storyBranch}\` carries ${String(commits)} commit(s) beyond \`${content.branch}\``);
     return;
@@ -39102,55 +39254,64 @@ class BuildSession {
       };
     }
     const handed = await headSha(story.worktree);
-    const developer = await this.spawnDeveloper(story);
-    const capDeath = developer.error !== null && diedOnCap(developer.error);
+    let developer = await this.spawnDeveloper(story);
     let budgetDeath = null;
-    if (developer.error !== null) {
-      const proven = capDeath && await workSince({
-        workspaceRoot: this.workspace.root,
-        repoDir: story.repoDir,
-        worktree: story.worktree,
-        since: handed
-      });
-      if (!proven) {
-        return {
-          story,
-          cost: developer.cost,
-          dod: [],
-          commit: null,
-          failure: null,
-          developerError: developer.error,
-          before
-        };
+    let spent = 0;
+    let separatorRetries = 0;
+    for (;; ) {
+      spent = round25(spent + developer.cost);
+      const capDeath = developer.error !== null && diedOnCap(developer.error);
+      if (developer.error !== null) {
+        const proven2 = capDeath && await workSince({
+          workspaceRoot: this.workspace.root,
+          repoDir: story.repoDir,
+          worktree: story.worktree,
+          since: handed
+        });
+        if (!proven2) {
+          return {
+            story,
+            cost: spent,
+            dod: [],
+            commit: null,
+            failure: null,
+            developerError: developer.error,
+            before
+          };
+        }
+        budgetDeath = developer.error;
+        this.capDeaths.set(story.planned.story.id, developer.error);
       }
-      budgetDeath = developer.error;
-      this.capDeaths.set(story.planned.story.id, developer.error);
-    }
-    const spent = developer.cost;
-    if (developer.refused !== null) {
+      if (developer.refused === null)
+        break;
       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: permissionBlockReason(developer.refused),
-          developerError: null,
-          before
-        };
+      if (proven) {
+        this.refusals.set(story.planned.story.id, developer.refused);
+        break;
       }
-      this.refusals.set(story.planned.story.id, developer.refused);
+      if (classifyRefusal(developer.refused).kind === "separator" && separatorRetries < MAX_SEPARATOR_RETRIES) {
+        separatorRetries += 1;
+        developer = await this.spawnDeveloper(story, { after: developer.refused });
+        continue;
+      }
+      return {
+        story,
+        cost: spent,
+        dod: [],
+        commit: null,
+        failure: permissionBlockReason(developer.refused, { retried: separatorRetries > 0 }),
+        developerError: null,
+        before
+      };
     }
     const dod = await this.runDod(story);
-    const green = dod.length === 0 ? dodIsSatisfiedEmpty(this.plan) : dodGreen({ dod });
-    if (!green) {
-      const failing = dod.find((r) => dodRefused(r) || r.exitCode !== 0 || r.timedOut);
+    if (!this.dodProves(dod)) {
+      const failing = dodFailure(dod);
       const why = failing === undefined ? "the story declares no dod commands, so nothing could prove it" : dodFailureReason(failing, story.planned.story.repo);
       return {
         story,
@@ -39194,18 +39355,49 @@ class BuildSession {
       await this.block(story, "the story produced no commit to review", half.cost, dod);
       return "settled";
     }
+    const update = await updateStoryBase({
+      storyId: story.planned.story.id,
+      repoDir: story.repoDir,
+      worktree: story.worktree,
+      branch: story.branch,
+      epicBranch: story.epicBranch
+    });
+    if (update.kind === "blocked") {
+      await this.block(story, staleBaseConflict(story.branch, story.epicBranch, update.conflicts, update.detail, relative16(this.ctx.root, story.worktree) || story.worktree), half.cost, dod, { commit: commit2, conflicts: update.conflicts });
+      return "settled";
+    }
+    let proven = dod;
+    if (update.kind === "updated") {
+      this.lines.push(`  · ${story.planned.story.id}: \`${story.branch}\` was ${String(update.behind)} commit(s) behind ` + `\`${story.epicBranch}\`${update.uncounted === null ? "" : ` (${update.uncounted})`} — merged the epic ` + `into it (${update.from.slice(0, 7)} → ${update.to.slice(0, 7)}) and re-ran the DoD on the result`);
+      this.ctx.emit("story.base_updated", {
+        phase: this.ctx.phaseId,
+        story: story.planned.story.id,
+        repo: story.planned.story.repo,
+        branch: story.branch,
+        base: story.epicBranch,
+        from: update.from,
+        to: update.to,
+        commits: update.behind
+      });
+      proven = await this.runDod(story);
+      if (!this.dodProves(proven)) {
+        const failing = dodFailure(proven);
+        await this.block(story, `${failing === undefined ? "the story declares no dod commands, so nothing could prove it" : dodFailureReason(failing, story.planned.story.repo)}` + ` — re-run after \`${story.epicBranch}\` moved under \`${story.branch}\` ` + `(${update.from.slice(0, 7)} → ${update.to.slice(0, 7)}); nothing was merged`, half.cost, proven, { commit: commit2 });
+        return "settled";
+      }
+    }
     const carried = await commitsBetween(story.repoDir, story.epicBranch, story.branch);
     const epicShaBefore = await fullShaOf(story.repoDir, story.epicBranch);
     const merge = await this.mergeIntoEpic(story);
     if (!merge.ok) {
-      await this.block(story, `merge into \`${story.epicBranch}\` failed: ${merge.detail}`, half.cost, dod, {
+      await this.block(story, `merge into \`${story.epicBranch}\` failed: ${merge.detail}`, half.cost, proven, {
         commit: commit2,
         conflicts: merge.conflicts
       });
       return "settled";
     }
     this.noteMerged(story, carried);
-    return await this.reviewAndSettle(story, dod, commit2, half.cost, carried, epicShaBefore);
+    return await this.reviewAndSettle(story, proven, commit2, half.cost, carried, epicShaBefore);
   }
   async reviewAndSettle(story, dod, commit2, priorCost, carried, epicBase, supplied) {
     if (supplied === undefined && this.ctx.attendedByHost) {
@@ -39481,9 +39673,8 @@ class BuildSession {
   }
   async pipelineFromDod(story, developerCost) {
     const dod = await this.runDod(story);
-    const green = dod.length === 0 ? dodIsSatisfiedEmpty(this.plan) : dodGreen({ dod });
-    if (!green) {
-      const failing = dod.find((r) => dodRefused(r) || r.exitCode !== 0 || r.timedOut);
+    if (!this.dodProves(dod)) {
+      const failing = dodFailure(dod);
       await this.block(story, failing === undefined ? "the story declares no dod commands, so nothing could prove it" : dodFailureReason(failing, story.planned.story.repo), developerCost, dod);
       return "settled";
     }
@@ -39586,7 +39777,7 @@ class BuildSession {
       advisories: this.advisories
     });
   }
-  async spawnDeveloper(story) {
+  async spawnDeveloper(story, retry = null) {
     const cap2 = developerCap(this.capParts, story.planned.story.id, story.attempt);
     const commands = this.repoCommands(story.planned.story.repo);
     this.ctx.emit("agent.spawned", {
@@ -39595,10 +39786,11 @@ class BuildSession {
       role: "developer",
       model: this.model(),
       effort: this.ctx.effort,
-      max_budget_usd: cap2
+      max_budget_usd: cap2,
+      ...retry === null ? {} : { retry: "separator-cure", retry_after: retry.after }
     }, 0, "developer");
     const agent = await spawnAgent({
-      prompt: this.developerPrompt(story),
+      prompt: (retry === null ? "" : separatorCurePrefix(retry.after)) + this.developerPrompt(story),
       model: this.model(),
       effort: this.ctx.effort,
       maxBudgetUsd: cap2,
@@ -39640,6 +39832,9 @@ class BuildSession {
     });
     return { cost: round25(agent.costUsd), error, refused: null };
   }
+  dodProves(dod) {
+    return dod.length === 0 ? dodIsSatisfiedEmpty(this.plan) : dodGreen({ dod });
+  }
   async runDod(story) {
     const scoped = await this.scopedParts(story);
     const results = await runStoryDod({
@@ -40008,7 +40203,7 @@ class BuildSession {
     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.permissionRefused == null ? "" : ` — \`${outcome.permissionRefused}\` was refused for approval; the tree held committed work, so the DoD decided`));
+    this.lines.push(`  ${status === "done" ? "✓" : "·"} ${id} → \`${status}\`` + (outcome.reason === null ? "" : ` (${outcome.reason})`) + (outcome.permissionRefused == null ? "" : ` — ${withCure(`\`${outcome.permissionRefused}\` was refused for approval; the tree held committed work, so the DoD decided`, outcome.permissionRefused)}`));
   }
   writeLog(outcome) {
     const dir = join100(this.ctx.runDir, BUILD_PHASE, LOG_DIR);
@@ -40691,15 +40886,12 @@ function developerTools(repoCommands, options = {}) {
     ...BASE_TOOLS,
     ...options.skills === true ? ["Skill"] : [],
     ...repoCommands.flatMap((command2) => bashGrantsFor(command2)),
-    "Bash(git add *)",
-    "Bash(git commit *)",
-    "Bash(git rm *)",
-    "Bash(git mv *)",
-    "Bash(git restore *)"
+    ...developerGitGrants()
   ];
 }
-function permissionBlockReason(command2) {
-  return `permission — \`${command2}\` was refused for approval by the agent's own permission layer, ` + "and a headless turn has nobody to approve it: the same allowance would refuse it again, " + "so this attempt was not repeated";
+function permissionBlockReason(command2, options = {}) {
+  const base2 = `permission — \`${command2}\` was refused for approval by the agent's own permission layer, ` + "and a headless turn has nobody to approve it: the same allowance would refuse it again, " + "so this attempt was not repeated" + (options.retried === true ? " beyond the one re-spawn with the cure stated, which was refused too" : "");
+  return withCure(base2, command2);
 }
 function diedOnCap(error) {
   return error.includes("Reached maximum budget");
@@ -52045,6 +52237,8 @@ function bullet2(item, trail) {
       return `${prefix5}story ${text3(payload2.story) || "?"}'s \`touches:\` WIDENED by ${actor}` + ` (${basisOf(payload2)})` + ` — +${pathList(payload2.paths)}` + ` (${String(lengthOf(payload2.before))} → ${String(lengthOf(payload2.after))} path(s))` + `${note(payload2.note)}`;
     case "story.base_fastforwarded":
       return `${prefix5}story ${text3(payload2.story) || "?"}'s base fast-forwarded to` + ` \`${text3(payload2.base) || "?"}\` — ${text3(payload2.from) || "?"} → ${text3(payload2.to) || "?"}` + ` (${String(payload2.commits ?? "?")} commit(s))`;
+    case "story.base_updated":
+      return `${prefix5}story ${text3(payload2.story) || "?"}'s base UPDATED to` + ` \`${text3(payload2.base) || "?"}\` before merging — ${text3(payload2.from) || "?"} →` + ` ${text3(payload2.to) || "?"} (${String(payload2.commits ?? "?")} commit(s) behind), DoD re-run`;
     case "epic.released":
       return `${prefix5}epic \`${text3(payload2.branch) || "?"}\` of run ${text3(payload2.owner) || "?"} ` + (text3(payload2.outcome) === "deleted" ? `deleted — no commit beyond \`${text3(payload2.base) || "?"}\`` : `renamed to \`${text3(payload2.renamed_to) || "?"}\` — ${String(payload2.commits ?? "?")} commit(s) ` + `beyond \`${text3(payload2.base) || "?"}\` survive there`) + ` (${text3(payload2.via) || "?"})`;
     case "story.work_rescued":

package/package.json

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