tldr-experts 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 0.27.0 — 2026-09-14
+
+### Added
+
+- **The Plan gate holds a plan to its shape, not only to whether it can execute (#316, #317,
+  #318, #319).** A planning audit of 9 runs (relayed, not re-run) found 25 of 54 build-gate
+  rejections were dependency reopens and every multi-story plan in one workspace a
+  one-story-per-wave chain; a 4-wave plan left 2 stories never attempted, while the 2-wave cap
+  lived only as skill prose and a `seed check` advisory nothing enforced. The `plan` check now
+  refuses more waves than the framework carries per run unless `waves.yml` records the new
+  optional `wave_cap_reason` (an additive root key — `version: 1` only grows), refuses a story
+  scheduled later than its `depends_on` requires, and names in its detail a dod command some
+  stories of one epic and repo carry and a sibling does not — an advisory, because which
+  stories share a shape is not machine-readable and the evidence is one epic. Vertical slices,
+  inventory files in `touches:` and end-to-end placement are Plan-prompt rules rather than
+  checks, because no stack-independent name marks a route file and no changed-file set exists
+  at Plan time to compare against. Every rule, number and sentence comes from one file,
+  `src/core/plan/planShape.ts`, which the gate, the rendered "Plan shape" section
+  (`tldrx plan schema`) and `seed check` all read; the gate's pass is its own, not
+  `validatePlan`'s, so a plan approved before it still loads at Build.
+
+- **`tldrx run auto --rebalance-finished` moves a blocked phase's shortfall out of money a
+  finished phase can no longer spend (#314).** MEASURED on a field run: `04-build` was refused
+  $11.07 short while `01-what` had finished $16.25 under its ceiling and the run total had $141
+  of room; `run auto` stopped and a person typed `budget raise 04-build 12 --take-from 01-what`
+  and relaunched. The move was already sanctioned — nothing looked for it. With the flag, the
+  budget gate moves EXACTLY the shortfall before refusing, out of phases whose every stage is
+  `done`/`skipped`, none stale, priced in `metered-usd` and with no unmetered turn (a lower-bound
+  spend proves nothing about what is left) — so `05-watch` with a stage still to run never gives.
+  It goes through `budget raise --take-from`'s own code, so the run ceiling never grows; it never
+  passes a recorded grant, not even under `on_grant_exceed: warn`; it never makes a partial move.
+  Each move is one `budget.raised` with both phases' before/after, `source` and the launcher as
+  actor. OPT-IN, not a default or a `budget.yml` key, because a phase ceiling is a person's
+  decision about money — the reason `--retry-failed` and `--until-done` never touch exit 2.
+  Without the flag every money refusal now names the finished phases' unspent money and the exact
+  `--take-from` move, and `budget.blocked` records `short_usd`, `finished_unspent_usd` and
+  `uncovered_usd`. An agent gate on the stage a move unblocked still falls to a person, and its
+  reason now names the flag, the launcher and the donor phase instead of "a person moved" it.
+
+### Fixed
+
+- **`tldrx ship` no longer opens a PR over a stale or red epic (#315).** Four PRs it opened in
+  one audit window came back red and needed a person, because between choosing the base and
+  `gh pr create` nothing fetched the base or ran a workspace command. Ship now fetches the base,
+  merges it into the epic in a throwaway worktree when behind, and runs the `done` stories'
+  Definition of Done on that tree; a conflict or a red command refuses (exit 2) naming the
+  paths or the command. Under `ship.push` the base is merged into the epic (forward, never
+  rebased or forced) and pushed with it; without it the branch is untouched. `--dry-run` runs
+  the same checks and exits the same way.
+
+- **A reviewer is given at least $2.00, not $1.00 — the old floor sat below the reviews that
+  finish (#307, owner decision: "A: piso $2").** MEASURED in the issue across 44 reviewer task
+  rows in two workspaces: the 37 that returned a verdict cost $0.17–$1.02 (median $0.50), so the
+  most expensive COMPLETED review already spent more than the $1.00 floor allowed; and a 3-story
+  run whose Plan priced every story at $8–$9 put every reviewer on that floor — at the shipped
+  defaults an $8 story derives `8 × 0.25 / (2 × 1.25)` = $0.80 — and one died with
+  `Reached maximum budget ($1)` before reading the diff, parking its story at `review`. $1.00
+  was never measured; it was chosen because it looked reasonable. `REVIEWER_FLOOR_USD` is now
+  $2.00, a fixed constant — no new key, event or schema. The consequence the owner accepted:
+  #289's refuse-before-spawn now fires when a stage has less than $2.00 left, and the refusal
+  already says so with the figure (`a review costs at least $2.00`). The budget brake's copy of
+  the floor in `budget/remainingWork.ts` is now IMPORTED from `build/caps.ts` rather than
+  restated, so the brake's estimate and the executor's cap read one definition (`caps.ts`
+  imports only two schema leaves, so the budget-gate hook stays cheap). The Build golden moves
+  by exactly that figure: the four reviewer `agent.spawned` lines carry `max_budget_usd: 2`.
+  `test/build-parallel.test.ts`'s three-story wave moves from a $9 to a $12 stage, because at $9
+  three $2.00 floors plus three developers sum past the ceiling the test proves the wave fits
+  inside. The seed-check / plan-gate warning (part 3 of #307) is not in this change.
+
+- **A developer whose DoD goes red gets the story's next attempt, instead of blocking it on the
+  first miss (#313).** Reported in #313's audit of 12 run folders (relayed, not re-measured
+  here): 17 human `tldrx story reopen`s were a red DoD — a snapshot not regenerated, a pinned
+  inventory the story's own change moved, a lint rule — that the developer never got a second
+  look at, each one waiting on a person to read the kept output and type the reopen. MEASURED on
+  `70da3d1` with the fake agent: a story at `attempts: 2` whose attempt 1 left a red DoD ended
+  `blocked` with ONE `task.started`. Mechanism: `settleHalf` blocked on any half-A failure,
+  while the reviewer's `changes` verdict already requeued while `attempt < attempts` — two
+  failures on the merits, one retry budget honoured for only one of them. A red DoD now takes
+  the same bound: the attempt settles back at the status it started from (not `blocked` — it is
+  about to run again) with `the DoD was red on attempt 1 of 2`, keeps its worktree, and the next developer prompt carries the kept output under `## Previous
+  attempt` with the DoD header (#211); the last attempt blocks, saying `the DoD stayed red on 2
+  of 2 attempts` when both were red. Narrow on purpose — a refused developer (#271), a cap death
+  (#277), a REFUSED or absent-binary dod command (#165, #209), no dod commands and a reopen that
+  changed nothing (#308) still block on the first attempt, because a second one buys the same
+  outcome. The attempts a red DoD spent are counted off `events.jsonl`, not memory: review of
+  the first cut MEASURED three red DoDs under `attempts: 2` when a spawn fault ended an
+  invocation between attempts and the next process started counting from zero. No new event,
+  no new field; the host door (`--prepare`/`--commit`) is unchanged. `tldrx learn`'s chapter 5
+  now narrates — and asserts — the two red attempts before the reopen.
+
 ## 0.26.1 — 2026-09-14
 
 ### Changed

package/README.md

@@ -335,6 +335,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.27.0 | 2026-09-14 | `beta` | Five changes for unattended runs, from a planning audit and live field measurement. The `plan` check now refuses a plan with more waves than the framework carries per run (unless `waves.yml` names a `wave_cap_reason`), refuses a story scheduled before its `depends_on` allows, and flags a dod command siblings carry that one story doesn't (#316–#319). `tldrx run auto --rebalance-finished` moves a blocked phase's exact shortfall out of a finished phase's unspent ceiling before refusing, through `budget raise --take-from` itself, so the run ceiling never grows and no grant is ever assumed; every money refusal now names the unspent total and the exact command to fix it (#314). `tldrx ship` fetches and merges the base into the epic and re-runs the `done` stories' DoD before opening a PR, so a stale or red epic refuses instead of shipping a PR that comes back red (#315). A reviewer's budget floor rises from $1.00 to $2.00, matching what completed reviews actually cost, so a review no longer dies mid-diff on a floor that was never measured (#307). And a developer whose DoD goes red gets the story's next attempt instead of blocking on the first miss, with the kept output handed to the next attempt and the bound counted from `events.jsonl` so it holds across process restarts; a refused developer, a cap death, or a broken dod command still blocks immediately (#313). |
 | 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. |

package/dist/hooks/budget-gate.js

@@ -22,7 +22,7 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-bbrhs055.js";
+} from "./chunk-2qkbh9b6.js";
 import {
   EventLog
 } from "./chunk-41k19q8t.js";

package/dist/hooks/{chunk-bbrhs055.js → chunk-2qkbh9b6.js}

@@ -222,6 +222,16 @@ function hostTokenCeiling(budget, phaseId) {
   return budget.ceiling_host_tokens ?? budget.ceiling_usd;
 }
 
+// src/core/build/caps.ts
+var MAX_ATTEMPTS = STAGE_TUNING_DEFAULTS.attempts;
+var REVIEWER_SHARE = STAGE_TUNING_DEFAULTS.reviewerShare;
+var REVIEWER_FLOOR_USD = 2;
+var STORY_CAP_MULTIPLIER = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function shortBy(estimate, remaining) {
+  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
+}
+
 // src/core/budget/remainingWork.ts
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "node:fs";
 import { join as join6 } from "node:path";
@@ -794,6 +804,7 @@ function validateBudget(input) {
 }
 
 // src/core/plan/validatePlan.ts
+var WAVES_FILE = "waves.yml";
 var PLAN_BUDGET_FILE = "budget.yml";
 
 // src/core/build/plan.ts
@@ -971,12 +982,11 @@ function looksLikeSpawnError(detail) {
 }
 
 // src/core/budget/remainingWork.ts
-var MAX_ATTEMPTS = STAGE_TUNING_DEFAULTS.attempts;
-var REVIEWER_SHARE = STAGE_TUNING_DEFAULTS.reviewerShare;
-var REVIEWER_FLOOR_USD = 1;
-var STORY_CAP_MULTIPLIER = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
-var STORY_CAP_FLOOR_USD = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
-function developerAttemptDivisor(attempt, attempts = MAX_ATTEMPTS) {
+var MAX_ATTEMPTS2 = STAGE_TUNING_DEFAULTS.attempts;
+var REVIEWER_SHARE2 = STAGE_TUNING_DEFAULTS.reviewerShare;
+var STORY_CAP_MULTIPLIER2 = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD2 = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function developerAttemptDivisor(attempt, attempts = MAX_ATTEMPTS2) {
   return attempt <= 1 ? 1 : attempts;
 }
 function remainingWork(input) {
@@ -1028,7 +1038,7 @@ function measure(input) {
   const ids = new Set(all.map((story) => story.id));
   const prices = progress.implicit ? new Map : loadPlanPrices(join6(input.runDir, PLAN_DIR), ids).prices;
   const verdicts = reviewVerdictsByStory(input.runDir);
-  const attempts = input.attempts ?? MAX_ATTEMPTS;
+  const attempts = input.attempts ?? MAX_ATTEMPTS2;
   const caps = new CapMath(input, prices, all.length);
   const stories = [];
   const blocked = [];
@@ -1112,9 +1122,9 @@ class CapMath {
     return round2(Math.min(Math.max(derived, floor), this.maxBudgetUsd));
   }
   storyCeiling(price) {
-    const declared = this.input.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD;
+    const declared = this.input.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD2;
     const floor = this.input.stageBudgetUsd > 0 ? Math.min(declared, this.input.stageBudgetUsd) : declared;
-    return Math.max(price * (this.input.storyCapMultiplier ?? STORY_CAP_MULTIPLIER), floor);
+    return Math.max(price * (this.input.storyCapMultiplier ?? STORY_CAP_MULTIPLIER2), floor);
   }
   priceOf(storyId) {
     const price = this.prices.get(storyId);
@@ -1126,10 +1136,10 @@ class CapMath {
     return this.input.stageBudgetUsd <= 0 ? 1 : usd / this.input.stageBudgetUsd;
   }
   attempts() {
-    return this.input.attempts ?? MAX_ATTEMPTS;
+    return this.input.attempts ?? MAX_ATTEMPTS2;
   }
   reviewerShare() {
-    return this.input.reviewerShare ?? REVIEWER_SHARE;
+    return this.input.reviewerShare ?? REVIEWER_SHARE2;
   }
   worstCaseShares() {
     return Math.max(this.storyCount, 1) * this.attempts() * (1 + this.reviewerShare());
@@ -1235,18 +1245,12 @@ function wouldExceedHostTokens(budget, phaseId, spentTokens) {
   };
 }
 
-// src/core/build/caps.ts
-var MAX_ATTEMPTS2 = STAGE_TUNING_DEFAULTS.attempts;
-var REVIEWER_SHARE2 = STAGE_TUNING_DEFAULTS.reviewerShare;
-var STORY_CAP_MULTIPLIER2 = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
-var STORY_CAP_FLOOR_USD2 = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
-function shortBy(estimate, remaining) {
-  return Math.max(0.01, Math.ceil((estimate - remaining) * 100) / 100);
-}
+// src/core/budget/rebalance.ts
+var SETTLED = new Set(["done", "skipped"]);
 
 // src/core/budget/budgetView.ts
 function raiseCommand(runId, phaseId, amountUsd) {
   return `tldrx budget raise ${phaseId} ${amountUsd.toFixed(2)} --run ${runId}`;
 }
 
-export { currentActor, nowRfc3339, spentBasis, tallyOf, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, BUILD_PHASE2 as BUILD_PHASE, remainingWork, wouldExceed, wouldExceedHostTokens, shortBy, raiseCommand };
+export { currentActor, nowRfc3339, spentBasis, tallyOf, DEFAULT_ON_HOST_TOKENS_EXCEED, DEFAULT_ON_GRANT_EXCEED, DEFAULT_ECONOMY, economyFor, isHostTokens, validateRunBudget, asRunBudget, expertsDir, loadExperts, readExpertDomain, pathsIntersect, stackExpertNames, WAVES_FILE, BUILD_PHASE2 as BUILD_PHASE, shortBy, remainingWork, wouldExceed, wouldExceedHostTokens, raiseCommand };

package/dist/hooks/{chunk-pwzy19er.js → chunk-w685jj9h.js}

@@ -3,12 +3,13 @@ import {
   DEFAULT_ECONOMY,
   DEFAULT_ON_GRANT_EXCEED,
   DEFAULT_ON_HOST_TOKENS_EXCEED,
+  WAVES_FILE,
   asRunBudget,
   nowRfc3339,
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-bbrhs055.js";
+} from "./chunk-2qkbh9b6.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -421,6 +422,11 @@ class RunStore {
     this.currentBudget = fn(structuredClone(this.currentBudget));
     this.budgetMutated = true;
   }
+  refreshCeilings() {
+    if (this.budgetMutated)
+      return;
+    this.currentBudget = this.ceilingsToWrite();
+  }
   append(event) {
     this.events.append(event);
   }
@@ -621,6 +627,33 @@ var MIN_SLICE_BYTES = 2 * 1024;
 // src/core/facilitator/contextLedger.ts
 var DEFAULT_PROMPT_MAX_BYTES = 400 * 1024;
 
+// src/core/plan/planShape.ts
+var MAX_WAVES_PER_RUN = 2;
+var RUN_SIZE_ISSUES = "#286/#244/#280";
+var WAVE_CAP_REASON_KEY = "wave_cap_reason";
+var PLAN_SHAPE_RULES = [
+  {
+    issue: "#316",
+    text: `**At most ${String(MAX_WAVES_PER_RUN)} waves** (patch for ${RUN_SIZE_ISSUES} — the framework's measured ` + "carry today, not a design preference). A later wave waits on every earlier merge, so each extra wave is " + "a stall: a 4-wave plan left 2 stories never attempted. The `plan` check refuses more unless the root of " + `\`${WAVES_FILE}\` records \`${WAVE_CAP_REASON_KEY}: "<why these stories cannot share a wave>"\`.`
+  },
+  {
+    issue: "#316",
+    text: "**Every story runs in the EARLIEST wave its `depends_on` allows.** `depends_on: []` runs in W1; a story " + "whose dependencies all finish in W1 runs in W2. The `plan` check refuses a story held later with nothing " + "making it wait. If something does — two stories editing one file — that is a `depends_on` edge: write it."
+  },
+  {
+    issue: "#317",
+    text: "**Each story is a vertical slice.** When its own dod goes green, what it adds is reachable from a route, " + "endpoint, command or job that a user or caller actually hits — not only from its own tests. A component " + "no route renders, or a handler nothing registers, is refused at Build review as unreachable: put the wiring " + "in the same story, and the wiring's file in its `touches`. No check reads this; the review does."
+  },
+  {
+    issue: "#318",
+    text: "**Inventory files go in `touches` up front.** Grep for the tests, snapshots and generated files that " + "ENUMERATE what the story adds — route trees, guard tables, allow-lists, architecture or coverage " + "inventories, approved snapshots — and declare them. They change because the story's change forces them " + "to, not because anyone meant to edit them, and each one left out is a `touches` widening at Build."
+  },
+  {
+    issue: "#319",
+    text: "**End-to-end coverage is not the last story.** Either a test-harness story runs in W1 and later stories " + "depend on it and run against it, or each UI or feature story carries the e2e command in its own dod. A " + "final e2e story that depends on everything is the story never reached. The `plan` check names a command " + "some stories of one epic and repo carry and a sibling does not — an advisory: say in that story why not."
+  }
+];
+
 // src/core/run/runOutcome.ts
 import { join as join3 } from "node:path";
 

package/dist/hooks/session-start.js

@@ -20,14 +20,14 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-pwzy19er.js";
+} from "./chunk-w685jj9h.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-bbrhs055.js";
+} from "./chunk-2qkbh9b6.js";
 import {
   isFinished
 } from "./chunk-41k19q8t.js";

package/dist/hooks/statusline.js

@@ -2,8 +2,8 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-pwzy19er.js";
-import"./chunk-bbrhs055.js";
+} from "./chunk-w685jj9h.js";
+import"./chunk-2qkbh9b6.js";
 import"./chunk-41k19q8t.js";
 import"./chunk-m1s8a6s0.js";
 import"./chunk-yre2scxn.js";