tldr-experts 0.21.0 → 0.22.0

package/CHANGELOG.md

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

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.22.0 | 2026-09-14 | `beta` | A developer may now READ its own tree — `git status`, `log`, `diff` and `show` join the one constant the grant, the developer prompt and the refusal classifier all read; measured on a live unattended run where a developer was refused `git -C <worktree> log` twice and the story died, ~$5 for a command that changes nothing. `-C <path>` (and `--git-dir`, `--work-tree`) stays ungranted as a decision with its own refusal kind, `elsewhere`, because it points git at trees the story does not own. And every refusal cure now says WHY it is a cure: three consecutive developers on one story re-appended `; echo "EXIT:$?"` to a DoD command because the cure said what to drop and never that the facilitator re-runs the Definition of Done itself and records each exit code (#287, #294). Minor release: the developer's git allowance grew and a new refusal kind was added. |
 | 0.21.0 | 2026-09-13 | `beta` | `tldrx budget raise <phase> <usd> --stage <id>` now moves the stage's own `budget_usd` — the figure that actually sets a developer's and a reviewer's spawn ceiling — instead of the phase figure, which caps no spawn at all: measured on a live unattended run where raising the plan's per-story price and the phase ceiling moved a developer's cap by nothing, and only raising the stage figure moved it; a raise naming no `--stage` now says outright that it moved no spawn ceiling. And a reviewer a nearly-exhausted stage cannot fund is refused before it is spawned — the run that surfaced this handed a reviewer **$0.43**, which died before reading a line of diff and recorded `verdict: error`, parking the story with its dependents blocked; the refusal now costs $0 and records `verdict: n-a`, not an error the reviewer never formed (#244, #289). Minor release: a new flag, `--stage`, on `budget raise`. |
 | 0.20.0 | 2026-09-13 | `beta` | `tldrx seed check <file\|dir>` runs a hand-written seed through the same importer chain `run new --seed` runs, plus the authoring rules four unattended runs paid to learn — bullets under 200 characters, `[src:]` citations that resolve, `dod` lines byte-equal to a declared command with no shell separator, `depends_on` wherever two stories touch one file, a `Recommended:` on every open question — and prints the budget split and per-story caps a run would set, creating no run and spending nothing; `tldrx install --claude` now writes a second managed skill, `tldrx-plan`, that reads `workspace.yml` and the repo tree and turns "I want X" into seeds that pass the same check, naming only declared tools (#291). And a permission refusal over a command the workspace's `commands:` could have granted now names the operator's cure on the first dead developer instead of the fourth, measured on a live unattended run where four developers died and two review rounds ran before the missing command turned out to be one `workspace.yml` line away (#285). Minor release: a new CLI verb, `tldrx seed check`. |
 | 0.19.0 | 2026-09-13 | `beta` | `tldrx story reopen <id> --as-is --note "…"` settles a story a person finished by hand from its branch as it stands, spawning no developer — measured on a live unattended run where a hand-rebased branch had a green DoD and a clean merge-tree but no way to land, blocked by #271's since-the-spawn rule from a developer with nothing to do (#279). Everything after the missing developer is the ordinary path: the epic merges in first if it moved, the same DoD and reviewer judge the diff, the same merge lands it. The record never lies about who did the work — `story.reopened` carries `reason: as_is` with the actor and note, `task.done` carries `as_is`/`as_is_by`/`as_is_note`, and the review log names the branch and the signer. Two refusals are structural with no flag to skip either: a branch with no commit ahead of its epic, and a red DoD. The signature clears the moment a real developer attempt starts, so a requeued story after a `changes` verdict records a developer, not an as-is. Minor release: a new flag, `--as-is`, on `story reopen`. |

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "tldr-experts: an evidence-first, file-based AI development framework - five stages, a gate on every one, and every claim cited or refused. Installs the `tldrx` (and `tldr-experts`) command. Beta.",
   "license": "MIT",
   "author": "Alan Martinez",

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
   "name": "tldrx",
   "description": "tldr-experts: an evidence-first, file-based AI development framework. Five stages, a gate on every one, every claim cited or refused. Beta.",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "author": {
     "name": "Alan Martinez"
   }