tldr-experts 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -1,5 +1,275 @@
 # Changelog
 
+## 0.18.2 — 2026-09-13
+
+### Added
+
+- **The zero-touch recipe is written down, on the pages a person opens to run one (#276).**
+  Measured on origin/main at 0.18.1, after the first fully unattended run had ended in a merged
+  pull request: `--questions`, `--ship`, `--until-done`, `--gates none` and `run cancel` were
+  each documented, and no page chained them into the thing that had just worked — seed file →
+  `run new … --gates none --questions none --ship pr --budget` → a backgrounded
+  `run auto --run <id> --until-done`. `nohup`, `2>&1 &`, the log to `tail -f` and "how do I
+  check on it later" had zero hits repo-wide; `--ui plain`, the flag that keeps a backgrounded
+  log readable, lived in the spec and the changelog only. Three seeds written the same day had
+  failed `run new` on the 240-character claim clip (#275), and the rules a seed must follow to
+  survive the importer and the `[src:]` grammar existed only in the source. So: a "Zero-touch
+  run, start to finish" section at the top of the site's unattended-operation guide (EN + ES)
+  with the copyable block, one line per flag — including that `--ship merge` over a base
+  branch seen to require no check arms nothing and leaves the PR open for a person (#274) —
+  how to check on the run, how to stop
+  it (`run cancel` after the process, never before), and the honest boundary: this is the
+  happy path without a person, and a run a person signs is a different configuration. The
+  same block, six lines, in the README quick start and both quickstarts; `docs/guide/10` has
+  its switches, its flags and its cheat sheet brought up to `--until-done`, `--questions`,
+  `--ship`, `--gates none` and `_scoped`, and drops a sentence that predated the engine's own
+  gate signer; the seed authoring rules — one claim per bullet, ~200 characters with the
+  citation, token last, `path:line` that exists, `"; "` between sources, the four What
+  headings, a `Recommended:` line per question, `.tldrx/seeds/<nn>-<slug>.md` — are in
+  `docs/guide/05` and in the site section, measured against `markdownClaims.ts` and
+  `srcToken.ts` rather than remembered. `run auto` examples in the guides now say `--run <id>` (the generated flag reference keeps its positional form), the
+  spelling under which a bare `--until-done` cannot mistake the id for its count. The ES
+  landing page links the release notes, which stay English and generated (a translated copy
+  would be the second copy `gen-changelog.ts` exists to prevent); the untranslated `TLDRX_UI`
+  row on the ES flags page is generated from `gen-cli.ts`'s English-by-design env table and
+  was left alone.
+### Fixed
+
+- **The dependency frontier is the sequential path's too — nothing fans out over a story a dead
+  developer parked (#263).** Measured on a field run (2026-09-12, `run auto --yolo`): S3's
+  developer died on its own cap, `parkDeveloperFailure` put the story back at `todo` — deliberate,
+  a transport failure settles nothing about the work — and one second later the next wave started
+  S4, whose front matter says `depends_on: [S3]`. S4 reached `done` on an epic branch S3 had put
+  no line of code on, which is an audit record lying in the dangerous direction: a gate signer
+  reads `done` over work that was never delivered. #260 had already built the check that answers
+  this (`blockingDependency`: any dependency that is not `done` holds a story, and the story is
+  written `blocked` with the reason rather than left quietly at `todo`) and switched it on for
+  `--parallel N` only, on the grounds that the sequential loop had no defect of its own. It had
+  this one, and `lanes === 1` is the default and what `run auto` runs. Re-measured at 017dda8
+  before the change, one fixture, one field moved: at `--parallel 2` the dependent is held with
+  the reason `dependency S1 is not done` on `gate.requested`; at the default it is built and
+  reported `done`. Now the same one derivation is asked on every N — no second copy of the rule,
+  and #260's own direction is kept: a story that depends on nothing still runs after a parked one.
+  The park itself, the cap arithmetic and the DoD-decides half of #277 are all untouched.
+
+- **The plan's per-story price is a ceiling now, not a wall — and a story that dies on it with
+  work in its tree lets the DoD decide (#277).** We shipped this one ourselves, hours earlier:
+  #264 landed in 0.18.1 and made the Build executor actually read `03-plan/budget.yml`'s
+  per-story prices. Before it nothing did, so the number was decorative and every story got the
+  uniform stage share; from #264 on it became the hard ceiling of the developer's turn, at
+  `price ÷ (1 + reviewer_share)` = **0.8 × price** — a figure a planner writes before it has
+  read a line of the repo. The session running two live unattended runs on 0.18.1 measured the
+  consequence (their measurement, not this repo's suite): stories died mid-change on caps a
+  dollar or three wide, were left `todo` having spent real money, their dependants went
+  `blocked`, and both runs stalled with nothing delivered — the real cost of a story spanning
+  roughly an order of magnitude above what the planner had estimated. Two changes, one issue.
+  **The cap is now `max(price × story_cap_multiplier, story_cap_floor_usd)`** — defaults 3 and
+  $4.00, both new optional `stage.yml` keys alongside `attempts:` and `reviewer_share:`
+  (`schemas/stageTuning.ts`), refused by name out of range rather than clamped. 3 NARROWS
+  that gap for the low and middle of the range and does not close it: over the prices the
+  planner writes today ($1.20-$4.00) the ceiling lands at $4.00-$12.00, so a story at the
+  top of the observed spread still dies on it — **a story still dies on its cap whenever
+  its real cost exceeds `max(price x 3, $4.00)`**, which is the figure to check before
+  recalibrating. The expensive end is carried by the OTHER half below, not by the
+  multiplier: the work is committed and measured instead of lost. What neither half covers
+  — a stage still reporting `done` over a story that died — is #263, out of scope here. 3
+  is chosen against that division of labour and against keeping one story's worst case
+  legible in its stage; the floor is the developer-side sibling of
+  `REVIEWER_FLOOR_USD` ($1.00) and is a small multiple of it, because the developer reads the
+  repo, edits it, runs the story's whole DoD suite and commits where the reviewer reads one
+  diff. The error here is not symmetric — a price set too low costs a dead story plus
+  everything already paid for it, one set too high costs only the difference on work that lands
+  — so the arithmetic is deliberately allowed to over-run a single estimate and the STAGE's own
+  budget gate, metered against real spend, is what stops a stage that runs out.
+  **Derived at DISPATCH, off the price as it sits on disk, with no migration of `budget.yml`:**
+  that is load-bearing rather than tidy, because runs already in flight carry prices written by
+  an older planner and only a dispatch-time derivation covers them the moment this is installed.
+  `gh #91`'s property survives intact — attempt 1 is the pass the plan priced and gets the whole
+  ceiling, the contingency attempt after it gets an `attempts`-th — and the reviewer's share,
+  which never came out of the developer's ceiling in the first place, is untouched and now
+  visibly additive. The brake's mirror in `budget/remainingWork.ts` moves in step, pinned as
+  ever by `test/remaining-work.test.ts`. **And a developer killed by that ceiling with work in
+  its tree no longer parks the story `todo`:** it is a story with a diff and no verdict, so the
+  facilitator's own Definition of Done decides it — #271's rule over a second cause, the same
+  `workSince` tree comparison (committed or not, `tldrx-work/` and `.tldrx/` excluded), the same
+  "the cause is recorded either way". The death is named in words with its figure on the story's
+  review log, on its `task.done` (`budget_death:`, additive) and in the handoff's `## Unknowns`;
+  a red DoD blocks with both reasons on the row; a cap death that left no work still parks the
+  story exactly where it was, unchanged since 2026-08-30. The narrowing to a CAP death is
+  deliberate: a spawn that never started or a transport fault says nothing about a tree, while
+  `Reached maximum budget` says precisely that the turn was working when it stopped. The Plan
+  schema contract now tells the planner the price is a ceiling and to budget the expensive case
+  rather than the expected one — it is pricing before reading the code, which is exactly when an
+  estimate is least worth trusting. What this does NOT fix: a stage that still reports `done`
+  while a story died on its cap is #263, measured and filed separately, and is left untouched
+  here.
+
+- **`--ship merge` no longer arms an auto-merge over a base that requires nothing (#274).**
+  Measured on the zero-touch proof run (a field workspace, `--gates none --ship merge`, no human
+  in the loop): the PR merged at `06:20:14Z` while all four of its check runs were still pending
+  — they had started at 06:20:12/06:20:16/06:20:28 and completed between 06:21:38 and 06:24:56,
+  every one of them AFTER the merge — and the ship record said `queued — GitHub merges when its
+  checks pass`. The mechanism is a gap between two different sets: the guard counted the checks
+  the PR REPORTED (`gh pr view --json statusCheckRollup`), while `gh pr merge --auto` hands the
+  wait to GitHub's auto-merge, which waits on the base branch's REQUIREMENTS. That workspace's
+  `main` had none (`gh api …/branches/main/protection` → 404 `Branch not protected`), so `--auto`
+  did not mean "merge when green", it meant "merge now", and the ledger recorded a red-eligible
+  suite as merged on green — a record lying in the dangerous direction (§7). `ship` now asks the
+  BASE what it requires before arming anything: `repos/{owner}/{repo}/rules/branches/<base>` for
+  rulesets (repository and organization level) and, when that finds none,
+  `repos/{owner}/{repo}/branches/<base>/protection` for classic branch protection. Nothing is
+  armed without a requirement actually SEEN — `merge: absent — the base branch requires no check
+  before merge` when both were read and hold nothing back, and `absent — could not tell what the
+  base branch requires` when a probe could not be read, because for a merge "I could not tell" has
+  to behave like "there is nothing to wait on". A requirement imposed by a mechanism neither probe
+  can see (a merge queue, an org policy this token cannot read) reads as "requires nothing" and so
+  arms NOTHING: the residual gap can only ever cost a merge that was not armed, never a merge that
+  should not have happened. The `queued` sentence now says what `--auto` actually waits on — the
+  base's REQUIRED checks. Two edges of the probe are closed on the same side: a rule that arrives
+  carrying an `enforcement` other than `active` is a dry run and is not counted as a requirement
+  (GitHub already filters `evaluate`/`disabled` server-side and the response carries no such field
+  — measured against the official REST description — so this is belt-and-braces, and its absence is
+  read as that documented filter rather than as "unknown", which would refuse to arm on every real
+  repo); and only a 404 whose body reads `Branch not protected` means "no classic protection" — a
+  branch or a repo that is not there answers 404 too, and reading that as "requires nothing" would
+  arm a merge against a base nobody identified.
+
+## 0.18.1 — 2026-09-13
+
+### Added
+
+- **Per-story scoped checks, and the full suite once on the epic head (#257).** Measured on a
+  field run at 0.16.1: 99 `check.*` events on one 8-story epic — every story's Definition of Done
+  ran the whole declared list, the full suite among it, on every attempt and every fix round, and
+  the epic head that actually ships was never run at all. The DoD is a delta gate ("this story did
+  not break the tree"), proven until now by running everything because nothing narrower existed.
+  `workspace.yml` grows `commands.<slot>_scoped: "<cmd> {{paths}}"`, a template beside a declared
+  slot: a story's dod line whose command has one runs the template over the story's own paths —
+  declared `touches:` ∪ its committed diff ∪ its dirty entries, existing paths only, one derivation
+  in `build/scopedPaths.ts` — substituted at the argv level (a path with a space is ONE argument,
+  no shell), and the row says `scope: "paths"` with the paths. The moment the epic flips to `done`,
+  the deduped full commands of its stories run once in the epic worktree, after `install:` if
+  declared, as `scope: "full"` rows on the epic's `lane` attributed to the last story merged; a red
+  there blocks that story, so the `stories` gate condition refuses. The template is never a
+  command — not in the allowlist, not citable, not handed to the developer, refused at Plan time
+  by a sentence naming the suffix; the story's evidence keeps citing the DECLARED command and the
+  row's prose names what ran. A repo that declares no template runs, records and cites exactly
+  what it did before: the golden is byte-identical, and a `scope` key emitted unconditionally
+  reddens it. Pinned by a two-story fake-agent build — exactly 2 `scope: paths` rows with the
+  right paths and 1 `scope: full` row with `lane`, a red epic head blocking S2 with the gate
+  counting 1 blocked, and a control with no template emitting no `scope` key at all; skipping the
+  epic-head run or substituting nothing each reddens exactly one of those.
+
+### Fixed
+
+- **A cancelled run's epic branch no longer blocks the next run for the same feature: `run cancel`
+  releases it, and Build moves a finished run's leftover aside instead of refusing it as someone
+  else's (#272).** Measured 2026-09-13 on a headless proof run at a509dca: run A had cut
+  `epic/main-ci-green` and was cancelled; the ordinary retry after a cancelled attempt — same
+  feature, id `…-2` — reached Build and was refused, "already exists … did not cut it — refusing to
+  stack this run's commits onto someone else's epic", relaunched once under `--until-done`, got the
+  same last line and stopped as #252 designed. $3.70 of what/how/plan died on a leftover with ZERO
+  commits beyond `main` — the only work of the cancelled run sat on its story branch (#129), which
+  nothing touches. Two halves, one rule. `tldrx run cancel` now releases every branch its
+  `build.epic_branch` claims, after `closeRun` has taken the run's epic worktrees back: no commit
+  beyond the repo's default branch → deleted (it was the base under another name); commits → renamed
+  to `epic/<slug>@<run-id>` (one derivation, `build/epicRelease.ts`) so they survive under a name
+  that says whose they were; checked out somewhere → left alone and the checkout named; a base git
+  cannot count against → left alone, because a miscounted zero there deletes commits. And Build, at
+  the refusal, reads WHO owns the branch from the claims under `tldrx-work/`: an owner whose
+  `run.yml` is explicitly `cancelled` or `done` — never "no process", since a run killed mid-Build or
+  parked at a gate has no process and is still the owner — left a leftover, and Build moves it
+  aside by the same rule and cuts its own; an open owner, an unreadable owner, and a branch NO run
+  claims keep the refusal verbatim with one line naming which — the unclaimed case is what #262's
+  killed-mid-cut run leaves, and its relaunch must find its epic where it left it. Every move is
+  written where a person reads it, not only in the branch list: the owner's run.yml
+  (`build.epic_released`, additive), its `04-build/handoff.md` when it wrote one, an `epic.released`
+  event on its ledger and — from Build — on the new run's ledger and in its handoff's Decisions.
+  Pinned against a real repo: delete / rename-with-commits-surviving / worktree-kept for the cancel
+  half, and owner-cancelled → renamed + fresh epic + both records, owner-open → verbatim exit 2,
+  no-claim → verbatim exit 2 for the Build half; the golden build is byte-identical.
+- **A permission refusal on a story whose tree holds work no longer blocks it before the
+  facilitator's own Definition of Done can measure it, and the developer is told why a plumbed
+  DoD line is refused (#271).** Measured 2026-09-12 on a headless `run auto --until-done` at
+  0.18.0: the developer finished, committed, and then ran the workspace's DoD command wrapped in
+  `> log 2>&1; echo EXIT:$? >> log; tail …` — a line the agent's permission layer splits at every
+  separator and refuses because the fragments do not each match a grant (#215). #261's block did
+  exactly what it says: `blocked: permission — <that line>` on the gate, one attempt spent,
+  `--until-done` correctly parked. And it was the wrong verdict, because the refusal was the
+  developer's OWN attempt at verification, the work was already in the tree, and the facilitator
+  re-runs the DoD one step later regardless — $8.12 to reach a committed story nothing measured.
+  The refusal now stops a story only when the tree holds NO work. "Work" is `workSince`, one
+  derivation against the tree the developer was handed: the branch tip's tree differs from it
+  (`git diff --quiet`), OR the working copy is dirty (`git status --porcelain` semantics —
+  untracked files count, git-ignored files do not), both outside `tldrx-work/` and `.tldrx/`,
+  which a `root_is_repo` worktree carries and the framework writes during the turn. Uncommitted
+  work counts on purpose: the normal path already takes a dirty tree into the DoD and commits it
+  afterwards (`runDod` runs before `commitIfDirty`), and the incident's likeliest shape is a
+  developer refused while VERIFYING that never reaches its commit. An empty commit, an untouched
+  tree, a turn that wrote only framework state and a turn that wrote only an ignored file all
+  still block with #261's exact wording after one attempt. With work the refusal is RECORDED and
+  the Definition of Done decides: green, and the story goes on to review with the refused command
+  named on its review log (`- Developer: … was refused for approval …`), on `task.done` as an
+  additive `permission_refused`, and in the handoff's `## Unknowns`; red, and the story blocks
+  with BOTH reasons on one row, the DoD's first. Not blocking never means not recording, and a
+  refusal is its own story's and its own attempt's only. The spawned developer prompt also gains
+  one rule beside "Done means proven": run each DoD command verbatim and alone, with the
+  mechanism stated — `>`, `>>`, `2>&1`, `<`, `|`, `;`, `&&`, `||`, `&`, `$()` split a line into
+  subcommands and each must match its own grant, so a compound line is refused even when the
+  script is allowed — and that the facilitator re-runs the DoD anyway. That sentence moves the
+  frozen developer prompt in `test/build-golden.test.ts` by exactly those lines in six prompt
+  files; events, `run.yml` rows and exit codes are byte-identical. Pinned by nine tests: refusal
+  after a commit + green DoD → `check.*` ran, `done`, recorded on all three surfaces; uncommitted
+  work + green DoD → measured, committed by the facilitator, landed; + red DoD → `blocked` with
+  both reasons; empty commit, state-dir-only and ignored-file-only → `blocked: permission — …`
+  with no DoD spent, one spawn; two stories with the refusal on one → the other's record clean;
+  refused on attempt 1 and clean on attempt 2 → attempt 2's record clean; and the prompt sentence
+  once, in `## Rules`. Mutations, each measured: dropping the comparison (every refusal
+  continues) reddens #261's own test and the empty-commit, state-only and ignored-only cases; a
+  `headSha !== since` proxy reddens the uncommitted and empty-commit cases; dropping the dirty
+  half reddens the uncommitted case; dropping the state-dir exclusions reddens state-only;
+  counting ignored files (`git status --ignored`) reddens state-only and ignored-only; removing
+  the per-attempt reset reddens the attempt-2 case.
+- **The headless refusal under a `host-tokens` ceiling now writes its `budget.blocked` — it was
+  the one money-family exit 2 the ledger could not see (#266).** Measured 2026-09-12 on
+  `runNext.ts`: `budgetRefusal` and `hostTokensNote` both append a `budget.blocked` before
+  returning exit 2; `economyRefusal` — the §E.2 gate that refuses a headless spawn on a phase
+  priced in host tokens — returned the same exit with only its CLI lines and no
+  `store.append` at all. The `--until-done` supervisor (#252) keys its money guard on a
+  `budget.blocked` among the attempt's fresh events, so a refusal that wrote nothing read as
+  "a refusal with no money behind it" and was relaunched into the same refusal — harmless to
+  the wallet, since the gate fires before any spawn, but a relaunch that could never do
+  anything, and a run whose own audit trail never states why it stopped (the same
+  blind-instrument shape as #248). The gate now appends one row of the `hostTokensNote` shape
+  (`phase`, `economy: host-tokens`, `ceiling_tokens`, a `reason` naming the headless
+  invocation) before the exit; the refusal text is byte-for-byte what it was. Pinned by a
+  headless run on a host-tokens phase → exit 2 AND exactly one `budget.blocked` on the ledger,
+  with `stage.started` still at zero (the row records a refusal, not a stage); removing the
+  append reddens exactly that test.
+- **A Plan that priced its stories in a shape nothing reads is refused at the Plan gate, and the
+  Plan agent is now told the shape (#264).** Measured on a field run: `03-plan/budget.yml` carried
+  `ceiling_usd: 108`, a `stories:` list with an `estimate_usd` and a `why` per story, and
+  `total_estimate_usd: 111` — priced, sourced, and unreadable. The only reader, `loadPlanPrices`,
+  accepts `validateBudget`'s shape (`run`, `ceiling_usd`, `spent_usd`, `per_phase_usd`) and prices
+  only the `per_phase_usd` keys that are story ids, so the file failed validation before the map was
+  ever looked for and every story got the uniform cap: $5.40 for the story the plan had priced at
+  $28, about a quarter of what the reader's own arithmetic would have handed it. Nothing could have
+  gone otherwise — the Plan prompt named `budget.yml` as a filename and never its shape,
+  `validatePlan` had zero references to the file, and the one string that named the problem
+  (`priceIssue`) was computed at Build time and read by nothing. Two halves. The `## Output
+  schemas` section the Plan agent reads carries a fourth artefact, GENERATED like the other three:
+  its rule table from `BUDGET_REQUIRED_KEYS`, the list `validateBudget` itself enforces, and its
+  example run through that validator by the test that pins the contract — and `tldrx plan schema
+  --budget` prints it for a person. And the `plan` check runs `validateBudget` over
+  `03-plan/budget.yml` at the gate when the file exists, naming the file and every missing key
+  (`budget.yml spent_usd: missing required key \`spent_usd\``), so the shape is refused where it
+  costs nothing instead of pricing nothing one stage later. The file stays optional; only its shape
+  is not. The Build loader is untouched on purpose: it refuses to load on any `validatePlan` issue,
+  and the spec's rule for an invalid budget at Build time — an advisory and the uniform split, never
+  a refused build — is what a file edited after its gate still gets, which is why the budget check
+  is the gate's own function and not a fourth pass inside `validatePlan` (a guard test pins that
+  `validatePlan` does not learn it).
+
 ## 0.18.0 — 2026-09-13
 
 ### Added

package/README.md

@@ -41,6 +41,21 @@ tldrx run new payments --scope feature --seed docs/payments/ --budget 25
 tldrx run auto            # `next`, over and over, until something actually needs you
 ```
 
+Or hand a small, well-seeded change to the engine with nobody watching — measured once: a one-story
+bugfix went from seed to merged PR in 45 minutes with no human input:
+
+```bash
+tldrx run new login-timeout --scope bugfix --seed .tldrx/seeds/01-login-timeout.md \
+  --gates none --questions none --ship pr --budget 40
+nohup tldrx run auto --run <id> --until-done --max-usd 40 \
+  --wait-answers 8h --wait-gates 8h --notify-every 30m --ui plain > /tmp/<id>.log 2>&1 &
+```
+
+`--gates none` lets every gate sign itself, `--questions none` lets the loop take each question's own
+`Recommended:` pick, `--ship pr` opens the PR when the run is done. What each flag means, how to write
+the seed, how to check on it and how to stop it:
+[Zero-touch run, start to finish](https://ederwii.github.io/tldr-experts/guides/unattended-operation#zero-touch-run-start-to-finish).
+
 **To run it: Node ≥ 20, and nothing else** — the published package is a pre-built bundle with
 zero runtime dependencies, and `dist/` is a Node bundle (Bun runs it too, if you have it).
 **To build or contribute: Bun ≥ 1.3**, which compiles that bundle and runs the test suite.
@@ -316,6 +331,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.18.2 | 2026-09-13 | `beta` | three things measured on the first fully unattended run and on the live runs that followed it, one of them a regression 0.18.1 shipped hours earlier: `--ship merge` armed GitHub's auto-merge over a base that required nothing — the guard counted the checks the PR REPORTED while `--auto` waits on the base's REQUIREMENTS, so a proof run's pull request merged at 06:20:14 while all four of its checks finished between 06:21:38 and 06:24:56, and the record said `queued — GitHub merges when its checks pass`; ship now asks the base what it requires through rulesets and classic protection, names its three absences apart, and every unreadable answer arms nothing; the plan's per-story price had become a hard wall at 0.8x the planner's guess once 0.18.1 made those fields actually read, killing stories mid-flight at $1.28 and $3.25 against real costs an order of magnitude higher, so the ceiling is now `max(price x 3, $4.00)` derived at DISPATCH from the budget as it sits on disk — a run already in flight is covered without migrating anything — and, the half that carries the expensive end, a developer that dies on its cap with work in its tree commits it and lets the Definition of Done decide instead of parking the story, the same authority #271 gave a refused one; and the zero-touch recipe is written down where a person looks for it, seed file to backgrounded loop, on the README quick start and both documentation sites, with the honest boundary that this is the happy path without a person |
+| 0.18.1 | 2026-09-13 | `beta` | five things a run could not survive on its own, every one measured on the unattended proof runs that followed 0.18.0 rather than reasoned about: a priced plan was never priced — the planner wrote `stories[].estimate_usd` and Build read only `per_phase_usd` + `spent_usd`, so every story got the same $5.40 cap while the plan said $28, and the contract now names the shape and the plan check refuses a budget.yml that does not carry it; a headless refusal under a host-tokens ceiling wrote nothing to the ledger, so `--until-done` relaunched over a refusal it could not see, and now writes its `budget.blocked` first; a developer that had committed its work and was then refused a compound verification command was blocked BEFORE the facilitator ran the Definition of Done, so the DoD now decides when there is work and the refusal is recorded either way, with the prompt saying to run each DoD command verbatim and alone because shell separators split a line into subcommands that each need their own grant; a workspace can declare `<slot>_scoped` DoD commands that run per story on the paths it touched with the full suite once per epic head, after the full suite was measured running three times per story attempt; and a cancelled run no longer leaves an epic branch that refuses the ordinary retry — `run cancel` releases it and Build renames aside an epic whose owner run is closed, while an open or unknown owner still refuses verbatim and an uncounted branch is never deleted |
 | 0.18.0 | 2026-09-13 | `beta` | the release that lets an unattended run survive its own accidents and end somewhere, every item measured on live runs at 0.16.1 rather than reasoned about: a turn that wrote a lot of files could not be RECORDED — an `agent.result` whose `outputs` field held 3924 bytes of run-relative paths blew the 4096-byte event cap through a RAW append that never reached the capped seam, the throw landed one line after the try/catch built for exactly this and came out as exit 1, which `--retry-failed` does not retry since its branch keys on exit 5, so a loop told to survive two failures survived zero, and the epic branch had been cut on disk one line before the throw with the save after it, leaving the relaunch to read its own epic as a stranger's; `outputs` is now named by COUNT with the full list written beside the event rather than truncated, all four raw appends route through the capped seam at module scope, a throw while recording fails the STAGE with exit 5 saying how many of how many rows landed, the claim is saved the moment it is earned, and `capPayload` still knows its two fields BY NAME — a third growable field has to be taught to it deliberately or it is refused whole; Build entry now proves the Definition of Done can run IN A WORKTREE before a developer is paid, after 18 h from `run auto` to the first story that could run on one workspace, five relaunches, because the repo's `install:` named a file that existed in the human's checkout and was never committed and `git worktree` carries TRACKED FILES ONLY, so every story failed identically after the story was opened and immediately before the paid turn while the base pre-flight was green and right to be, measuring in the checkout where the file is — one throwaway worktree at the base sha, the install run inside it, each DoD command's first token resolved there, NEVER the suite, refusal exit 2 naming the exact path or binary, cached under an additive `worktree:` key narrowed by base sha, declaration hash and AGE (six hours for a green, because the row is a claim about an ENVIRONMENT that no sha contains; the base red's 30 minutes for a red), and costing zero where it could learn nothing; where the two readings could not be told apart it deliberately refuses LESS — a path named by a `dod` command after the first may be an artefact an earlier one builds, so that is an advisory and not a verdict; one blocked story no longer stops every later wave, after a loop told to build 8 stories built 5, never started 3, and reported the stage `done`, twice on the same run, because the parallel path asked only "did any story block" and `depends_on` appeared ZERO times in the Build executor — a story now runs when every one of its `depends_on` is `done`, one held back is `blocked` WITH the reason `dependency S7 blocked` (transitive for free) which is what the gate's `blocked_reason` and the continue note read, the stage line counts every story `waves.yml` scheduled rather than the rows the executor happened to hold, and a scheduled story with no outcome at all is named in `## Unknowns` instead of dropped, while `--parallel 1` is untouched on purpose — a story whose dependency blocked is still attempted there, and changing that would be a second change in the opposite direction; the spawned developer can now delete and rename paths in its own tree, after a story that was simply "delete an unused file" proved undoable — nothing in the allowance could unlink a path or take it out of the index, so every `git rm` came back needing approval nobody was there to give, the refused turn exited 0 with an envelope, the DoD ran green on an untouched tree and the reviewer faulted a diff that was never written, twice — the file-lifecycle git verbs are granted as index operations on the story's OWN tree (never a bare `rm`, `git push` still asserted absent), and a tool call refused for approval now BLOCKS the story at once with the command and why, reaching the story file, the handoff and the gate, so the next missing verb costs one attempt instead of two and nothing; that detector reads a structural field first and the English refusal sentence only as a fenced fallback, because pre-merge review measured the unfenced version reading a plain file-read of a document CONTAINING the phrase as a refusal — this very CHANGELOG is one of them — and a refusal carrying neither signal is a miss taken on purpose, with the sentence half depending on prose the host can change without notice; a fix-list finding now declares what it IS, after three stories with a green definition of done, a merged commit and an APPROVING reviewer settled `blocked`, each on a `fix-now` finding whose whole content was a stale docstring or a citation that did not resolve — the reviewer was not wrong and `severity` was never the vehicle (a free string NO consumer read, one render site under `src`), so a required `kind` splits behaviour from text: `correctness` and `security` hold the story exactly as before, a `docs`/`style` finding submitted `fix-now` is routed to `defer-with-log` with a `Normalised-from:` line, and because this makes a gate WEAKER on purpose the unblocking is priced — declaring a finding `docs` costs the SAME `[src: …]` citation that refuting one already costs, a `kind` that is absent or outside the enum is refused for free and indexed as a fault so it costs the story no attempt, a fix list already on disk with no `Kind:` line reads as not stated and not stated blocks, and the four reviewer-prompt goldens MOVED because the schema alone would have left a reviewer nobody told about the field; `run.yml` can finally explain its own `cost_usd` — a row read `input_tokens: 84, output_tokens: 37150, cost_usd: 1.98` for a 124 KB prompt while the provider reported 4,911,750 cache reads for that same turn, and across 101 transcripts in one workspace cache reads were 97.3% of the input side against a column that saw 0.002% of it — the counters were parsed on every turn and thrown away one function later, and the half the issue did not know about is that the executor path's `agent.result` emitted NO `usage` at all, so every Build and Watch turn lost all four counters and the whole Build was priced off zeroes (measured: zero `usage` lines across the four frozen goldens with ten `agent.result` among them); they are recorded additively and gated one at a time rather than both-or-nothing, `turnTokens` names them while deliberately reading neither so the exclusion is a decision on the record, nothing displayed changed — the dashboard and `tldrx cost` are byte-identical — and a row from before this reads absent, since nothing reconstructs a counter nobody wrote down; a gate about to sign itself is no longer sent as a Yes/No the owner cannot answer, after 3 of 3 questioned stages on two live workspaces sent the prompt 600 ms after the last answer and self-signed on the very next poll, so the one tap it invited ran `approve` on an already-approved gate and, because the in-wait approval fell between two notify windows, the bridge kept the prompt open and re-mentioned its owner every escalate tick for two hours — the release now asks the gate's CONDITIONS through the same re-evaluation the poll uses, extracted so neither can form a second opinion, sends nothing when there is no decision to take and says which stage and why on stdout instead of going quiet, and words a genuinely held gate from that one reading so a payload can no longer name four open questions beside `holding: "none"`; and three things a run could not do before: it can end in a pull request toward main on purpose, frozen at `run new --ship` with `push`, `pr` or `merge` into an additive `run.yml` block and not a sixth phase, pushed through the ONE push wrapper in the codebase with a PR that reports NO check left open and recorded as `merge: absent — no checks to wait on` because auto-merge over nothing to wait on is a merge now rather than a merge when green — pre-merge review caught the first version erasing a recorded merge failure with an empty string and exit 0, and the emitter dropped the whole block until it was taught the key; `questions_policy: recommended` answers a blocking question that carries its own `Recommended:` line and escalates the ones that do not, after 10 owner questions across two headless runs ($89.82 over 28 h and $26.38 over 5.6 h, the agents busy 4.9 h and 56 min of it) parked the loop on 9 that already held the pick in a parsed field, writing `decided_by: agent-default` as a THIRD value beside owner and driver because `owner` there would be an audit record lying in the dangerous direction, and never inventing a pick — no line, a letter naming no option, or a block marked irreversible or money escalates exactly as before; and `run auto --until-done [<n>]` relaunches the loop in-process after an exit it can do nothing else with, at most `n` times (default 5), after five hand relaunches and 18 h before a story ran — never over a person's exit 4, never over a budget block since nothing in-process moves a ceiling, never twice over the same last line, with the run id and the spend baseline pinned across relaunches so `--max-usd` still describes the one command a person typed; the epic-claim-at-cut half of that issue lives in the Build executor and is NOT fixed here |
 | 0.17.0 | 2026-09-12 | `beta` | three things the framework knew and recorded wrongly, each found by reading its own records rather than by using it: a gate notification now carries the condition HOLDING the gate as data instead of leaving it to be guessed from the text of the command it suggests — `holding` says questions, stories or nothing-mechanical, and when a story is blocked with a recorded reason the payload also hands over a ready-made rejection that lets the loop carry on, with the note DERIVED from the blocked story rather than canned, because a rejection's note is fed to the next turn's prompt and a generic one would hand that turn an empty instruction, so when no reason can be derived the offer is absent rather than invented; the emitted command keeps a literal placeholder and never interpolates the reason, which keeps the quoting hazard out of the record and puts it where a substituting client can see it; `run status` stopped printing more money left than it had ceiling — the run ceiling now has ONE live copy, read from `budget.yml` by every live screen, and `run.yml`'s mirror is documented as the creation value and no longer written by a raise, since the break was never that a raise failed to write the mirror but that an ordinary concurrent save carried a stale copy over it, and the fix was to delete the half-sync rather than to build a better one — pre-merge review caught the first version pairing a LIVE spend with that now-frozen ceiling inside `tldrx replay`, which would have reproduced the same impossible line in a different command on every run whose budget had been raised, measured on the real CLI as `$12.00 spent of $10.00 ceiling` with no concurrency required; and a task row now records the ROLE its turn actually ran under, where every Build turn had been filed as the developer including the reviewer's — the role was known at spawn and written to the event stream, and was dropped on the way to the ledger, so the audit record named the wrong actor for work it had itself measured; the new key is additive and written on EVERY row including the developer's, because a role present only on reviewers would make its absence mean developer-or-not-recorded and send a reader back to inferring the role from an absence, which is the guess the change exists to remove |
 | 0.16.1 | 2026-09-12 | `beta` | five things the framework knew and did not say, or said wrong — four of them found by using it rather than by reading it: a red base pre-flight now KEEPS its output, so a refusal that blocks every story in a Build names the failing test and cites the file, where it used to record only the last line of stdout — measured 2026-09-10, a stage refused with `tail: "Test run completed with non-success exit code: 2"` while the cause, `DockerUnavailableException`, sat on line 12 of 163,702 lines the run had already captured and thrown away, so diagnosing a refusal the framework had itself measured meant re-running the workspace's test command by hand; it now routes through the same seam #211 built for a story's DoD, which had been naming its failing test correctly all along on the same command, the same day, in the same repo — the path with the SMALLER blast radius was the legible one; a gate notification now offers the command that CLEARS it rather than always `tldrx approve` — questions open give `tldrx answer <id>`, unfinished stories give `tldrx run status`, and `approve` is offered only when nothing mechanical is outstanding, after an owner approved a Build gate by mistake twice in one evening over unbuilt stories, each time from a phone, each time needing a revoke, while a ten-minute heartbeat repeated `Run: tldrx approve` seven times under a sentence that correctly named the five open questions holding it; `tldrx reject --and-continue` lets a rejection mean "redo it this way and carry on" instead of ending the run — the loop resumed after an approve and stopped after a reject, so the button meaning "there is still work to do" was the one that stopped the work and only a terminal could revive it; five real rejections that night all meant continue, five cost a manual relaunch, and a bare `tldrx reject` still writes a byte-identical `run.yml` and stops exactly as before; the expert-recompute fixture anchors its evidence dates to a `now` it can move, so `bun test` stops going red by the calendar — pristine `main` was red at the exact sha of the published 0.16.0 with no commit in between, and a clock moved one year forward reddened FIVE cases, not the one that had already fired; and `test/merge-wave.test.ts`'s concurrency failure, documented as a known flake since #115 and carrying a written licence to re-run it, was never one: `merge-guard.sh` rewrote `.git/hooks/reference-transaction` IN PLACE while a sibling wave's `git merge` was exec'ing it — ETXTBSY on Linux at 31% under contention, benign on macOS, which is why it was green locally and red in CI, and why a same-sha re-run failed 2 for 2 rather than passing; the hook is now written to a temp file and RENAMED into place, the refusal that used to borrow `2`/`merge conflict` for a hook abort now says what it was and exits 11, and AGENTS.md §4 withdraws the re-run licence for those two cases while naming the interrupted-merge case (#237) as still open and undiagnosed — because "all real" for a whole file costs the same as "all flake", in the other direction |

package/dist/hooks/answer-capture.js

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-7hhjx1wk.js";
+} from "./chunk-nf2j945p.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-26xkmfdr.js";
+} from "./chunk-kwaqdq9w.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-ds9sew2e.js";
+} from "./chunk-pday823f.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-00h4xah7.js";
+} from "./chunk-gx6qa496.js";
 import {
   PHASE_IDS
-} from "./chunk-bm9aqtg3.js";
-import"./chunk-xxcy0tsa.js";
-import"./chunk-ab6cv5v5.js";
+} from "./chunk-x00a2vaz.js";
+import"./chunk-4y3pk4n2.js";
+import"./chunk-vf992pfw.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,15 +28,17 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-p0ns6fex.js";
+} from "./chunk-8ak5kwd5.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR,
   commandProbeIssues,
   factsPath,
-  parseYaml
-} from "./chunk-77y6q9mt.js";
+  isScopedTemplate,
+  parseYaml,
+  scopedSlotOf
+} from "./chunk-c1h38et6.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";
@@ -151,6 +153,8 @@ function loadWorkspace(root) {
   const commandRoles = new Map;
   const commandProbes = new Map;
   const iterationCommands = new Set;
+  const scopedCommands = new Map;
+  const scopedTemplates = new Set;
   const defaultBranches = new Map;
   let seedTriageThresholdTokens = null;
   const empty = () => ({
@@ -161,6 +165,8 @@ function loadWorkspace(root) {
     commandRoles,
     commandProbes,
     iterationCommands,
+    scopedCommands,
+    scopedTemplates,
     defaultBranches,
     seedTriageThresholdTokens
   });
@@ -192,13 +198,24 @@ function loadWorkspace(root) {
     defaultBranches.set(entry.name, typeof entry.default_branch === "string" && entry.default_branch !== "" ? entry.default_branch : FALLBACK_DEFAULT_BRANCH);
     const own = [];
     const roles = declared.get(entry.name) ?? new Map;
-    for (const value of roles.values()) {
+    const scoped = new Map;
+    for (const [role, value] of roles) {
+      const base = scopedSlotOf(role);
+      if (base !== null) {
+        const full = roles.get(base);
+        if (full !== undefined && scopedSlotOf(base) === null && isScopedTemplate(value)) {
+          scoped.set(full, value);
+          scopedTemplates.add(value);
+        }
+        continue;
+      }
       commands.add(value);
       if (!own.includes(value))
         own.push(value);
     }
     repoCommands.set(entry.name, own);
     commandRoles.set(entry.name, roles);
+    scopedCommands.set(entry.name, scoped);
     const fast = roles.get(ITERATION_ONLY_SLOT);
     if (fast !== undefined)
       iterationCommands.add(fast);

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-vmhfw2r1.js";
+} from "./chunk-2caxb41h.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-msswet35.js";
-import"./chunk-ds9sew2e.js";
+} from "./chunk-2ym87z6d.js";
+import"./chunk-pday823f.js";
 import {
   asRunBudget,
   currentActor,
@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-rw9zk47w.js";
+} from "./chunk-wx1jce1t.js";
 import {
   EventLog
-} from "./chunk-00h4xah7.js";
+} from "./chunk-gx6qa496.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -34,18 +34,18 @@ import {
   newestActiveRun,
   renderRunEconomies,
   runSpend
-} from "./chunk-4mjxyfp9.js";
-import"./chunk-xxcy0tsa.js";
+} from "./chunk-hwsng0xq.js";
+import"./chunk-4y3pk4n2.js";
 import {
   noteDeprecations
-} from "./chunk-p0ns6fex.js";
+} from "./chunk-8ak5kwd5.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-77y6q9mt.js";
+} from "./chunk-c1h38et6.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-qdvwnts3.js → chunk-1v05a468.js}

@@ -1,6 +1,6 @@
 import {
   toolInput
-} from "./chunk-msswet35.js";
+} from "./chunk-2ym87z6d.js";
 
 // src/hooks/lib/wouldBe.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-vmhfw2r1.js → chunk-2caxb41h.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-77y6q9mt.js";
+} from "./chunk-c1h38et6.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";

package/dist/hooks/{chunk-msswet35.js → chunk-2ym87z6d.js}

@@ -1,7 +1,7 @@
 import {
   parseHookInput,
   readStdin
-} from "./chunk-ds9sew2e.js";
+} from "./chunk-pday823f.js";
 
 // src/hooks/lib/decide.ts
 function deny(reason) {

package/dist/hooks/{chunk-xxcy0tsa.js → chunk-4y3pk4n2.js}

@@ -1,6 +1,6 @@
 import {
   isRecord
-} from "./chunk-77y6q9mt.js";
+} from "./chunk-c1h38et6.js";
 
 // src/core/run/stagePolicy.ts
 function validateStagePolicy(value, stageIds, issues, spec) {
@@ -66,13 +66,17 @@ var STAGE_TUNING_DEFAULTS = {
   attempts: 2,
   fixlistRounds: 1,
   reviewerShare: 0.25,
-  gateSignerShare: 0.25
+  gateSignerShare: 0.25,
+  storyCapMultiplier: 3,
+  storyCapFloorUsd: 4
 };
 var STAGE_TUNING_RANGES = {
   attempts: { key: "attempts", min: 1, max: 5, integer: true },
   fixlistRounds: { key: "fixlist_rounds", min: 0, max: 3, integer: true },
   reviewerShare: { key: "reviewer_share", min: 0, max: 1, integer: false },
-  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false }
+  gateSignerShare: { key: "gate_signer_share", min: 0, max: 1, integer: false },
+  storyCapMultiplier: { key: "story_cap_multiplier", min: 1, max: 20, integer: false },
+  storyCapFloorUsd: { key: "story_cap_floor_usd", min: 0, max: 200, integer: false }
 };
 var FIELDS = Object.keys(STAGE_TUNING_RANGES);
 function inTuningRange(range, value) {

package/dist/hooks/{chunk-p0ns6fex.js → chunk-8ak5kwd5.js}

@@ -3,7 +3,7 @@ import {
   parseSrcToken,
   srcToken,
   withoutSrcToken
-} from "./chunk-77y6q9mt.js";
+} from "./chunk-c1h38et6.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];

package/dist/hooks/{chunk-rr7n3j59.js → chunk-afttzftj.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-rw9zk47w.js";
+} from "./chunk-wx1jce1t.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -21,12 +21,12 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-00h4xah7.js";
+} from "./chunk-gx6qa496.js";
 import {
   cursorStage,
   isAttendedByHostView,
   openRunViews
-} from "./chunk-4mjxyfp9.js";
+} from "./chunk-hwsng0xq.js";
 import {
   backupPathFor,
   isAlive,
@@ -35,20 +35,20 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-ab6cv5v5.js";
+} from "./chunk-vf992pfw.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-p0ns6fex.js";
+} from "./chunk-8ak5kwd5.js";
 import {
   FRAMEWORK_ROOT,
   PLAN_STATUSES,
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-77y6q9mt.js";
+} from "./chunk-c1h38et6.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
@@ -78,6 +78,20 @@ function frameworkVersionSync() {
 function inlineList(values) {
   return `[${values.map((v) => yamlScalar(v)).join(", ")}]`;
 }
+function epicRelease(row) {
+  const parts = [
+    `branch: ${yamlScalar(row.branch)}`,
+    `repo: ${yamlScalar(row.repo)}`,
+    `outcome: ${yamlScalar(row.outcome)}`,
+    ...row.renamed_to === undefined ? [] : [`renamed_to: ${yamlScalar(row.renamed_to)}`],
+    `commits: ${String(row.commits)}`,
+    `base: ${yamlScalar(row.base)}`,
+    `via: ${yamlScalar(row.via)}`,
+    `at: ${yamlScalar(row.at)}`,
+    `reason: ${yamlScalar(row.reason)}`
+  ];
+  return `{${parts.join(", ")}}`;
+}
 function money(n) {
   return n.toFixed(2);
 }
@@ -174,7 +188,8 @@ function emitRunYaml(run) {
   }
   if (run.build !== undefined && run.build.epic_branch.length > 0) {
     const model = run.build.branch_model === undefined ? "" : `, branch_model: ${yamlScalar(run.build.branch_model)}`;
-    lines.push(`build: {epic_branch: ${inlineList(run.build.epic_branch)}${model}}`);
+    const released = run.build.epic_released === undefined || run.build.epic_released.length === 0 ? "" : `, epic_released: [${run.build.epic_released.map(epicRelease).join(", ")}]`;
+    lines.push(`build: {epic_branch: ${inlineList(run.build.epic_branch)}${model}${released}}`);
   }
   if (run.cancelled !== undefined) {
     lines.push(`cancelled: {by: ${yamlScalar(run.cancelled.by)}, at: ${yamlScalar(run.cancelled.at)}, ` + `note: ${yamlScalar(run.cancelled.note)}}`);