tldr-experts 0.18.1 → 0.18.3

package/CHANGELOG.md

@@ -1,5 +1,243 @@
 # Changelog
 
+## 0.18.3 — 2026-09-13
+
+### Fixed
+
+- **A headless permission refusal now names its cure, a chained line is retried once with
+  the cure in front of the prompt, and the developer prompt lists the git verbs it holds
+  (#278).** Measured on two real unattended runs in one day: six refusals, sonnet AND opus
+  developers, with #271's "verbatim and alone" rule already in every prompt and explicit
+  operator notes saying the same. Every refused line was one of two shapes — a shell chain
+  (`git checkout -- f && sha256sum f && git status`, `scripts/gate/build.sh; echo "EXIT:$?"`,
+  `cmd > log 2>&1`, `diff <(…) | head`) or a git verb the developer does not hold
+  (`git checkout --`, `git status`, `git log`, `git rev-parse`) — and every one had the same
+  arc: no work since spawn, blocked after one attempt, a person reopens it, the same refusal
+  again. The ledger could not tell the two causes apart because it recorded both with #261's
+  one sentence, and a person reading it got the symptom (`was refused`) and not what would have
+  run. Three things move, one leaf each, none of them a second rule. The refused line is
+  CLASSIFIED (`build/refusalKind.ts`: `separator` when it chains commands, read through the
+  SAME tokenizer `splitArgv` runs every DoD command through, so a `;` inside quotes is an
+  argument there and here; `verb` when it is `git <verb>` alone and the verb is outside the
+  allowance, with the granted equivalent named where one exists — `checkout --` and
+  `checkout <path>` → `git restore <path>`, `reset -- <path>` and `reset HEAD <path>` → `git
+  restore --staged <path>`, and NONE invented for a branch switch or a `--hard`; `unknown` for
+  everything else, which keeps #261's sentence byte-identical there). The recorded reason
+  keeps #261's text as its base and appends `The cure: …` — on the gate's `blocked_reason`,
+  the story's review log and the handoff's `## Unknowns`, through one joiner. And a
+  `separator` refusal with no work in the tree is re-spawned ONCE within the same attempt,
+  the refused line and the rule as the prompt's first lines (`MAX_SEPARATOR_RETRIES = 1`,
+  pinned: the second refusal blocks, with the reason saying the cure was stated and refused
+  too); the retry's turn is a `run.yml` task row and an `agent.spawned` like any other, with
+  additive `retry: "separator-cure"` and `retry_after: <line>` on that spawn — never hidden.
+  `verb` and `unknown` are NEVER retried: a verb the allowance lacks will be lacking again,
+  and a cause the line does not show cannot be cured by restating it. Why the prompt moves
+  too: `developerTools()` granted `git restore` since #261 and nothing told the developer
+  which verbs it had, so a "mutate, observe RED, restore" story reached for the commonest one.
+  The verbs are now listed in the prompt from the one constant the grant is built from and the
+  classifier reads (`build/developerGrants.ts`), with `git restore <path>` named as the way to
+  put a file back — which moves the six frozen developer prompts in
+  `test/fixtures/build/golden/` by exactly those lines and nothing else (`*-events.txt`,
+  `*-run-tasks.txt`, `*-exit-codes.txt` are byte-identical: the fixture has no refusal).
+- **A story no longer merges into its epic from the base it was cut from after a sibling moved
+  that epic (#268).** A wave runs its stories at `--parallel N` from one tip and merges them one
+  after another, so every story but the first merges from a base that is already behind — and
+  its DoD proved a tree without the sibling's work in it. Measured 2026-09-13 in a field
+  workspace: a dependent story finished green, hit `CONFLICT (content)` in a handler and two of
+  its tests at the merge, and settled `blocked` with verdict `n-a` and no reviewer run; the
+  prose note telling the developer to rebase does not make anything rebase, so a person did it
+  by hand, three times in one week. Build now measures the story branch against the epic tip
+  immediately before the merge and, when the epic has moved, merges the epic INTO the story in
+  the story's own worktree and re-runs the story's DoD on the result. **The cost, plainly: one
+  extra DoD per story, and only when the epic actually moved since that story's base** — the
+  re-run is charged on the story's HEAD moving, so a story whose base is current pays nothing
+  and emits nothing. **A conflict blocks the story and names the conflicting files**, merges
+  nothing, and leaves the worktree exactly where the developer left it (`git merge --abort` has
+  already run) — a half-applied merge is worse than a blocked story, and "merge conflict" with
+  no paths in it is the refusal that sends a person to a worktree the executor has since
+  pruned. It is a merge and never a rebase, for the reason the fast-forward path already gives:
+  rewriting a branch a developer has committed to is the move the run-id-in-branch-name rule
+  exists to prevent, and every rescued sha (#129) is a promise a rebase breaks. Whether the epic
+  moved comes from the existing `baseStateOf`/`commitsBetween` derivation, and a count git could
+  not take is NOT read as "did not move" (#273): it falls through to the merge, which writes
+  nothing when the branch really was current. A move that happens is one new event,
+  `story.base_updated` (§2.9) — the record that the extra DoD was paid, and for which commits.
+- **A seed bullet over the claim cap no longer has its citation cut in half, and the refusal
+  stops naming a path that is not a file (#275).** Measured on 0.18.1 in a field workspace:
+  three seeds written the same day, every path in them verified with `test -e`, were refused by
+  `tldrx run new --seed` with `no such file: src/M… [src: .tldrx/seeds/<x>.md`. The mechanism is
+  a fold, not a missing file — `clean()` cut a 248-character bullet at 239, which landed INSIDE
+  its inline `[src: …]`; `renderSeed` then appended the importer's own token, whose `]` closed
+  the dangling marker, and the reader saw ONE file ref whose path was two citations glued
+  together. The cut now moves BACK to the start of the citation it would have split, so an
+  over-long bullet loses the citation it could not fit rather than half of it; the importer
+  cites the seed line on the rendered bullet anyway, so the provenance that matters survives.
+  Claims whose cut lands in prose are byte-identical, which is why the fix is the clip and not
+  the cap or a pre-measurement strip — those would rewrite short claims that are not broken.
+  The other half is the refusal, which was worth as much: an author can write an unterminated
+  `[src:` by hand and get the same fold with no clipping involved, so `run new` now says the
+  line carries an unterminated citation, that the path above is a fold and not a file to look
+  for, and quotes the bullet — and says nothing at all when it cannot read the line back,
+  rather than guessing. Where a string ends mid-citation is a question for the `[src:]` grammar
+  and only for it: `unclosedSrcMarker` and `foldsUnclosedSrcMarker` are new leaves in
+  `src/core/text/srcToken.ts`, and neither caller carries a regex of its own.
+- **A `git rev-list --count` that FAILED counted as zero commits, and `--discard-pending`
+  deleted the implicit plan on that zero (#273).** `commitsBetween` returned `0` both when it
+  counted nothing and when git could not answer at all, so "there is nothing built on this
+  branch" and "I could not look" were one number — and the caller that reads it,
+  `rederiveImplicitPlan`, keeps the plan only when the count is ABOVE zero. The failure
+  therefore landed on the destructive side: measured here on a story branch carrying a real
+  developer commit, with the base ref removed so the count could not be taken, `tldrx next
+  --prepare --discard-pending` printed "re-derived 04-build/implicit-plan.yml (--discard-pending;
+  no evidence, and no commit on story/… beyond epic/…)" and wrote a new plan over the one the
+  work was done against.
+  `commitsBetween` now returns `number | null` and every caller decides what `null` means for
+  it: the plan is KEPT with the command that could not answer named, which is the direction
+  #272 already chose where the same zero would have deleted a branch. That strict sibling
+  `commitsAhead`, opened by #272 precisely to route around this, is collapsed back in — one
+  implementation per derivation (§7), so there is a single way this repo counts commits and it
+  is the safe one. The other two callers: a merge whose count failed is now reported as
+  `mergedEarlier` ("what it carried is not recoverable") instead of as an EMPTY merge, the
+  2026-08-30 "four stories merged" trap read backwards; and `baseStateOf` keeps answering
+  `current` — inaction is the right reading of a branch that cannot be measured, and the
+  ordinary case is a story branch that does not exist yet — but carries the reason in a new
+  `uncounted` field, so a branch that IS there and could not be placed says so in the dispatch
+  line instead of being silently treated as up to date.
+
+## 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

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.3 | 2026-09-13 | `beta` | four fixes to the unattended build path, all measured on live runs: a headless permission refusal is now classified — a chained shell command, a git verb outside the developer's allowance, or neither — so a chained line gets one retry with the cure stated first, an ungranted verb names its granted equivalent, and the developer prompt now lists the git verbs it holds from the one constant the grant is built from, after six refusals in one day left a ledger that recorded the symptom and not the cause; a wave no longer merges a story into its epic from the base it was cut from once a sibling has moved that epic — the story is measured against the epic tip immediately before merge, the epic is merged into the story and its Definition of Done re-run only when the epic actually moved, and a conflict blocks the story naming the files rather than merging half of one; a seed bullet over the claim cap no longer has its citation cut in half, with the clip moving back to the citation's start instead; and a failed commit count is no longer read as zero, so `--discard-pending` can no longer delete a plan just because git could not answer. |
+| 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 |

package/dist/hooks/answer-capture.js

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-1tynpxvm.js";
+} from "./chunk-tjx8g39f.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-kwaqdq9w.js";
+} from "./chunk-jpp137mb.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-pday823f.js";
+} from "./chunk-qzsxhsyj.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-x64paqbg.js";
+} from "./chunk-6z5rmj0b.js";
 import {
   PHASE_IDS
-} from "./chunk-bgxj40rr.js";
-import"./chunk-zg7q0q4y.js";
-import"./chunk-vf992pfw.js";
+} from "./chunk-m1s8a6s0.js";
+import"./chunk-bznt6jb2.js";
+import"./chunk-ezfvp5kx.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,7 +28,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-8ak5kwd5.js";
+} from "./chunk-5stgwp3g.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -38,7 +38,7 @@ import {
   isScopedTemplate,
   parseYaml,
   scopedSlotOf
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-2caxb41h.js";
+} from "./chunk-ka7768vx.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-2ym87z6d.js";
-import"./chunk-pday823f.js";
+} from "./chunk-t44983nq.js";
+import"./chunk-qzsxhsyj.js";
 import {
   asRunBudget,
   currentActor,
@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-ct7kazfy.js";
+} from "./chunk-j5d0nard.js";
 import {
   EventLog
-} from "./chunk-x64paqbg.js";
+} from "./chunk-6z5rmj0b.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -34,18 +34,18 @@ import {
   newestActiveRun,
   renderRunEconomies,
   runSpend
-} from "./chunk-hwsng0xq.js";
-import"./chunk-zg7q0q4y.js";
+} from "./chunk-yre2scxn.js";
+import"./chunk-bznt6jb2.js";
 import {
   noteDeprecations
-} from "./chunk-8ak5kwd5.js";
+} from "./chunk-5stgwp3g.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-c1h38et6.js → chunk-0sy3tmfg.js}

@@ -7742,8 +7742,7 @@ function splitArgv(command) {
   if (/[\n\r]/.test(command))
     return null;
   const argv = [];
-  const pattern = /"([^"]*)"|'([^']*)'|([^\s"']+)/g;
-  for (const match of command.matchAll(pattern)) {
+  for (const match of command.matchAll(TOKEN_RE)) {
     if (match[1] !== undefined || match[2] !== undefined) {
       argv.push(match[1] ?? match[2] ?? "");
       continue;
@@ -7755,7 +7754,7 @@ function splitArgv(command) {
   }
   return argv.length === 0 ? null : argv;
 }
-
+var TOKEN_RE = /"([^"]*)"|'([^']*)'|([^\s"']+)/g;
 class DodCommandRefused extends Error {
 }
 async function runDodCommand(command, cwd, timeoutMs, allowed) {

package/dist/hooks/{chunk-rmpcrt4c.js → chunk-53wgfn01.js}

@@ -8,7 +8,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-ct7kazfy.js";
+} from "./chunk-j5d0nard.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -21,12 +21,12 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-x64paqbg.js";
+} from "./chunk-6z5rmj0b.js";
 import {
   cursorStage,
   isAttendedByHostView,
   openRunViews
-} from "./chunk-hwsng0xq.js";
+} from "./chunk-yre2scxn.js";
 import {
   backupPathFor,
   isAlive,
@@ -35,20 +35,20 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-vf992pfw.js";
+} from "./chunk-ezfvp5kx.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-8ak5kwd5.js";
+} from "./chunk-5stgwp3g.js";
 import {
   FRAMEWORK_ROOT,
   PLAN_STATUSES,
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";

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

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

package/dist/hooks/{chunk-x64paqbg.js → chunk-6z5rmj0b.js}

@@ -2,7 +2,7 @@ import {
   GATE_POLICIES,
   validateGatesPolicy,
   validateStagePolicy
-} from "./chunk-zg7q0q4y.js";
+} from "./chunk-bznt6jb2.js";
 import {
   asDocument,
   isRecord,
@@ -15,7 +15,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -49,6 +49,7 @@ var EVENT_TYPES = [
   "questions.policy_changed",
   "story.reopened",
   "story.base_fastforwarded",
+  "story.base_updated",
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",

package/dist/hooks/{chunk-zg7q0q4y.js → chunk-bznt6jb2.js}

@@ -1,6 +1,6 @@
 import {
   isRecord
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.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-vf992pfw.js → chunk-ezfvp5kx.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";

package/dist/hooks/{chunk-ct7kazfy.js → chunk-j5d0nard.js}

@@ -1,6 +1,6 @@
 import {
   STAGE_TUNING_DEFAULTS
-} from "./chunk-zg7q0q4y.js";
+} from "./chunk-bznt6jb2.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
@@ -25,7 +25,7 @@ import {
   requireVersion,
   requireVersion1,
   result
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/hooks/lib/actor.ts
 function currentActor() {
@@ -968,8 +968,10 @@ function looksLikeSpawnError(detail) {
 var MAX_ATTEMPTS = STAGE_TUNING_DEFAULTS.attempts;
 var REVIEWER_SHARE = STAGE_TUNING_DEFAULTS.reviewerShare;
 var REVIEWER_FLOOR_USD = 1;
-function developerPriceDivisor(attempt, attempts = MAX_ATTEMPTS, reviewerShare = REVIEWER_SHARE) {
-  return attempt <= 1 ? 1 + reviewerShare : attempts * (1 + reviewerShare);
+var STORY_CAP_MULTIPLIER = STAGE_TUNING_DEFAULTS.storyCapMultiplier;
+var STORY_CAP_FLOOR_USD = STAGE_TUNING_DEFAULTS.storyCapFloorUsd;
+function developerAttemptDivisor(attempt, attempts = MAX_ATTEMPTS) {
+  return attempt <= 1 ? 1 : attempts;
 }
 function remainingWork(input) {
   try {
@@ -1094,7 +1096,7 @@ class CapMath {
     const price = this.priceOf(storyId);
     if (price === null)
       return this.agentCap(1 / this.worstCaseShares());
-    return this.agentCap(this.shareOf(price / developerPriceDivisor(attempt, this.attempts(), this.reviewerShare())));
+    return this.agentCap(this.shareOf(this.storyCeiling(price) / developerAttemptDivisor(attempt, this.attempts())));
   }
   reviewer(storyId) {
     const price = this.priceOf(storyId);
@@ -1103,6 +1105,11 @@ class CapMath {
     const floor = Math.min(REVIEWER_FLOOR_USD, Math.max(this.input.stageBudgetUsd - this.input.stageSpentUsd, 0));
     return round2(Math.min(Math.max(derived, floor), this.maxBudgetUsd));
   }
+  storyCeiling(price) {
+    const declared = this.input.storyCapFloorUsd ?? STORY_CAP_FLOOR_USD;
+    const floor = this.input.stageBudgetUsd > 0 ? Math.min(declared, this.input.stageBudgetUsd) : declared;
+    return Math.max(price * (this.input.storyCapMultiplier ?? STORY_CAP_MULTIPLIER), floor);
+  }
   priceOf(storyId) {
     const price = this.prices.get(storyId);
     if (price === undefined || !Number.isFinite(price) || price <= 0)

package/dist/hooks/{chunk-kwaqdq9w.js → chunk-jpp137mb.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-vf992pfw.js";
+} from "./chunk-ezfvp5kx.js";
 import {
   FACT_CONFIDENCES,
   FACT_DECIDERS,
@@ -15,7 +15,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-8ak5kwd5.js";
+} from "./chunk-5stgwp3g.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -28,7 +28,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-c1h38et6.js";
+} from "./chunk-0sy3tmfg.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

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

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