tldr-experts 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,328 @@
 # Changelog
 
+## 0.18.0 — 2026-09-13
+
+### Added
+
+- **A run can now end in a pull request toward main, on purpose (#253).** Measured on two
+  workspaces on 0.16.1: $89.82 over 28 h and $26.38 over 5.6 h, and neither run could end in a
+  PR whatever it spent — every preset ends at `watch`, and `tldrx ship` refused to push the
+  branch it opens the PR for, citing a spec sentence that is not in the spec (what
+  `docs/spec.md` actually says is that the BUILD phase has no push wrapper). The last mile —
+  the only one the owner's sentence names, *"desde que le doy el run, hasta que me entrega un
+  PR hacia main"* — was a person typing `git push -u origin epic/<slug>`, then `tldrx ship`,
+  then watching the checks. It is now a decision taken once, at `tldrx run new --ship
+  <push|pr|merge>`, and frozen into `run.yml` as an additive `ship: {push, pr, auto_merge}`
+  block the way `gates_policy` is: not a sixth phase, because shipping has none of a phase's
+  properties — it spends nothing, produces a URL, and is gated by what every earlier gate
+  already signed. When `run auto` sees the run close it runs the same `tldrx ship` a person
+  would type: the epic is pushed through the ONE push wrapper in the codebase (in
+  `core/build/git.ts`, beside Build's git seam, with `core/run/ship.ts` pinned as its single
+  caller — the Build phase itself still has none), the PR opens with the body it always had,
+  and under `merge` the PR is armed with `gh pr merge --auto --merge` so the remote's own
+  checks decide. A PR that reports NO check is left open and the record says `merge: absent —
+  no checks to wait on` (§7), because GitHub's auto-merge over nothing to wait on is a merge
+  now, not a merge when green — the mutation that drops that guard reddens exactly one test.
+  `run.yml` gets one record (`pr_urls`, `merge`, per-repo `merges`, `shipped_at`) beside the
+  policy, so a loop re-run on a closed run ships nothing twice — while `tldrx ship` typed again
+  is the recovery after a partial failure: it re-arms the repo whose merge failed, leaves a
+  queued one alone, and never erases a recorded failure (pre-merge review caught the first
+  version overwriting it with an empty string and exit 0) — and `run.finished` carries `pr_url`
+  and `merge`.
+  A ship that is refused is the loop's exit 2 — it was asked for a PR and did not deliver one.
+  Absent the flag every run means what it meant: nothing pushed, nothing opened, the refusal
+  that names the `git push` command unchanged byte for byte. Every gate is still signed by
+  whoever `--gates` says, so an unattended ship is a deliberate `--gates none --ship merge`
+  and `run.yml` records both. Found on the way: `run.yml` is emitted key by key, so the
+  block was dropped by the first save until the emitter learned it — pinned by a round-trip
+  test.
+- **`questions_policy: recommended` — the loop answers a question that carries its own
+  `Recommended:` line, and escalates only the ones that do not (#251).** Measured 2026-09-12 on
+  two headless runs at 0.16.1, every gate `auto`, `--wait-answers 8h --wait-gates 8h`: $89.82
+  and 28 h wall on one, $26.38 and 5.6 h on the other, the agents busy 4.9 h and 56 min of it,
+  and **10 owner questions, 9 carrying a `Recommended:` line the asking agent had written**. The
+  loop parked on every one, sent `question.raised`, and waited for a person to type
+  `tldrx answer` — over a pick the framework already held in a parsed field (`RECOMMENDED_RE`),
+  on the decision card and in the notification payload. Nothing acted on it, by design:
+  `waitForAnswers` "reads and does nothing else", and `Fact.decided_by` had no honest value for
+  a machine's decision. So: `run new --questions <stage,stage|stage:recommended|all|none>` —
+  `--gates`' grammar, extracted to ONE parser both flags now call rather than a second copy of
+  "split on the first colon" — freezes `questions_policy` into `run.yml` beside `gates_policy`,
+  additive and absent by default, so a run opened without the flag is byte-identical to one
+  opened before it existed and reads `human` everywhere. Under `recommended` for the cursor
+  stage, the moment a stage parks the loop takes each blocking question whose block names one
+  of its own options on a `Recommended:` line, through the SAME `writeAnswerSlot` +
+  `captureAnswers` that `tldrx answer` is — the footer, the `question.answered` and the
+  `fact.added` are a person's bytes — and the fact says the rest: `decided_by: agent-default`
+  (a THIRD value beside `owner`/`driver`, because `owner` there would be an audit record lying
+  in the dangerous direction), `alternatives` (the options not taken) and `recommended_why`
+  (the line's own reason). One `question.auto_answered` per answer reaches the notify hook with
+  the pick, the alternatives and the `--supersede` line that reverses it; no `question.raised`
+  goes out for a question the loop answered; and the deferred-gate release #247 built is now
+  one closure both the human-answer and the loop-answer paths call, so the second cannot form
+  a second opinion about when a gate is worth asking about. It never invents a pick: no
+  `Recommended:` line, a letter naming no option, or a block tagged with the new additive §2.7
+  keys `irreversible: true` / `money: true` is escalated exactly as before — the fixture that
+  proves it goes red the moment the `money:` guard is dropped. `tldrx run questions set
+  <stage>:<policy> --note "…"` mirrors `run gates set` on a shared engine, one
+  `questions.policy_changed` event, every refusal the gates verb has. The close's decided-tally
+  counts `agent-default` apart from "not stated" — it IS stated — and names it only when it is
+  non-zero, so every close that recorded none reads as it did.
+- **`tldrx run auto --until-done [<n>]` relaunches the loop in-process after an exit it can do
+  nothing else with — a stage failure past `--retry-failed`, a thrown error that used to reach
+  `fail()` as a bare 1, a refusal whose remedy is mechanical — at most `n` times (default 5),
+  writing `run.relaunched` with the exit it recovered from; never over exit 4 (a person's),
+  never over a `budget.blocked` (nothing in-process moves the ceiling, #232/#244), and never
+  twice over the same last line. Measured 2026-09-12: five hand relaunches and 18 h before a
+  story ran (#252).** The loop body is now `runAutoOnce` and `runAuto` a bounded supervisor over
+  it — in the same process, because the loop holds no state and re-reads run.yml every
+  iteration, which is exactly what makes "run it again" honest. The run id the first attempt
+  resolves is pinned for every relaunch, and so is its spend baseline: "spent by this loop" and
+  `--max-usd` describe the one command a person typed, and a relaunch that reset the loop's own
+  ceiling would have been a ceiling in name only (a test pins it: `[fail, ok, ok]` under
+  `--max-usd 0.80` stops at exit 2 after two spawns, not three). One derivation,
+  `relaunchVerdict`, decides both the relaunch and whether the run-end notification is held, so
+  an attempt that is relaunched sends no `run.failed` and `run.finished` / `run.failed` go out
+  once, from the last attempt. A throw is caught only under the flag — without it the loop is
+  byte-identical, pinned against `--until-done 0`, and `fail()` still gets its exit 1. The
+  epic-claim-at-cut half of the issue is #262 and lives in the Build executor, not here.
+
+- **Build entry proves the Definition of Done can run IN A WORKTREE before a developer is
+  paid (#254).** Measured on a live workspace, 2026-09-12 at 0.16.1: **18 h from `run auto` to
+  the first story that could run**, five relaunches, two of them environment and both invisible
+  to Build entry. The repo's `install:` named `./install.sh`, which existed in the human's
+  checkout and was never committed — a `git worktree` carries TRACKED FILES ONLY — so every
+  story's install failed identically in its own tree, each time after the story was opened and
+  immediately before the paid turn, and each time a person fixed it and relaunched. The base
+  pre-flight (#41) was green throughout and was right to be: it measures in the checkout, which
+  is where the file is. So Build entry now asks the other question once, before `agent.spawned`:
+  one throwaway detached worktree at the base sha, the declared `install:` run inside it, then a
+  resolution of each declared DoD command's first token in that tree. **Never the suite** — the
+  base pre-flight already measures the suite in the checkout and paying twice for it at every
+  entry is a cost nobody asked for. A refusal is exit 2, once, naming the exact path or binary.
+  Two decisions are the whole design. The `install:` command's own path token is refused by
+  `git ls-files` with NOTHING executed, and that is sound only because of WHEN the install runs:
+  nothing has installed anything yet, so a relative path the install NAMES cannot be one it
+  PRODUCED. A DoD command's path token gets the opposite treatment — tracked-ness decides
+  nothing there, because `node_modules/.bin/vitest` is untracked in every repo on earth and is
+  present by the time the DoD runs; it is probed AFTER the install, in that tree, and an
+  untracked twin in the checkout is rendered as advice, never as the verdict. The same rule has
+  a second half: a `dod` list runs in order, so a path named by any command AFTER the first may
+  be an artefact an earlier `dod` command builds (`dod: ["npm run build", "dist/check.sh"]`) —
+  the probe runs no suite, cannot tell that from "nobody committed it", and therefore writes an
+  advisory instead of a refusal. A bare binary name is never downgraded, at any index: nothing
+  a `dod` command does can put one on this process's PATH. Refusing what would have worked is
+  the expensive direction for an entry gate, so wherever the two readings could not be told
+  apart, this refuses less — each half pinned by a control that reddens when it is removed.
+  One existing behaviour moved with it: an install that fails deterministically in a fresh tree
+  is now refused at entry instead of blocking story 1 (`story-worktree-deps.test.ts` (d) says
+  so and says why). The per-story install is untouched and still answers for an install that
+  passes on the base and fails on a story's branch. The result is cached beside the base result in
+  `04-build/preflight.yml` under an additive `worktree:` key, so a resumed run does not re-pay
+  the install, and the cache is narrowed by three things and not two: the base sha, the
+  declaration hash (the install, every command probed, and the whole allowlist — the operator's
+  fix is an edit to `workspace.yml` and that edit must not be invisible), and AGE. A green gets
+  six hours rather than the base green's forever, because this row is a claim about an
+  ENVIRONMENT — the host's PATH, the registry the install reached — and none of that is in the
+  sha; a red gets the base red's 30 minutes, because #162 is the filed failure where a row
+  measured over a broken environment kept refusing after somebody fixed it. The gate costs
+  exactly zero where it could learn exactly nothing: a repo with no `install:` whose DoD names
+  only bare binaries opens no worktree at all, since `PATH` is the same in both trees and the
+  base pre-flight has already RUN the command there.
+
+### Fixed
+
+- **One blocked story no longer stops every later wave — the boundary asks per STORY, from
+  `depends_on` (#260).** Measured 2026-09-12 on one workspace at 0.16.1: a loop told to build 8
+  stories built 5, never started 3, and reported the stage `done`. `03-plan/waves.yml` scheduled
+  W1=[S1] W2=[S2,S5,S6,S7,S8] W3=[S3] W4=[S4]; S7 blocked in W2 and the build skipped W3 and W4
+  outright, leaving S3 and S4 at `todo` while S2 — the only thing S3 depends on — was `done`. It
+  happened twice on the same run, the second time after a `story reopen S7` and a relaunch. The
+  mechanism was one line: after each wave the parallel path asked `waveFailed`, which is
+  `stories.some(status === "blocked")`, and broke out of the loop — `depends_on` appeared **zero
+  times** in `executors/build.ts`, so the one fact that could tell "a story that needs the
+  blocked code" from "a story that never did" was never read, though `validatePlan` already
+  guarantees every dependency sits in an earlier wave and is therefore settled at that moment.
+  The rule the `break` defended is kept, and it is the reason this is a frontier and not a
+  deletion: **a story runs when every one of its `depends_on` is `done`**, and a story whose
+  dependency did not land is NOT attempted — nothing fans out over code that was not landed,
+  which is how one red story becomes N of them. What changes is that the rule stops applying to
+  stories that never needed that code. A story held back is now `blocked` WITH the reason,
+  `dependency S7 blocked` — absent-with-reason, never a silent `todo` — and that sentence is
+  what `blocked_reason` on `gate.requested` and the continue note read, so the gate stops being
+  "held by stories" with nothing a person or a turn can act on (the #239 shape, one layer down).
+  It is transitive for free: S4 behind a blocked S3 reads `dependency S3 blocked`. The documents
+  stop hiding it too — the stage line counts every story `waves.yml` scheduled instead of the
+  rows the executor happened to hold (`5 of 8`, never `5 of 5`), the skipped stories are named
+  on stdout with the dependency each waits on instead of one line that said the next wave "may"
+  have depended on something, and the handoff's `none — every scheduled story reached done` is
+  now decided against `waves.yml`: a scheduled story with no outcome at all is named in
+  `## Unknowns` rather than dropped, which is the record that was lying in the dangerous
+  direction (§7). **`--parallel 1` is untouched**: the sequential path never stopped a later
+  story, a story whose dependency blocked is still attempted there, and this frontier replaces
+  the parallel path's stop only — turning today's finished stories into blocked ones would be a
+  second change, in the opposite direction. Both directions are pinned by tests that are the
+  same fixture with one field moved, and the existing test that froze the defect as correct (an
+  independent S4 stopped by a blocked S2) was rewritten to give S4 the `depends_on` that makes
+  its assertion true for the reason the code's own comment gives — argued in the test, never
+  flipped in silence.
+
+- **A fix-list finding now declares what it IS, and a documentation defect stops holding a story
+  (#255).** Measured 2026-09-12 across two workspaces at 0.16.1: three stories with a green
+  definition of done, a merged commit and an APPROVING reviewer settled `blocked` — every one of
+  them on a `fix-now` finding whose whole content was a stale docstring or an `[src: …]` line
+  that did not resolve. The reviewer was not wrong: the prompt says `fix-now` is "this story's
+  own correctness", and a stale docstring in the story's own files honestly reads that way. What
+  the record could not say was that the defect was TEXT — a disposition answers "where does this
+  go" and nothing answered "what is it" — so a blocked story held the Build gate's `stories`
+  condition and three unattended nights ended at a person. `severity` was no help and is not the
+  vehicle: it was a free string defaulted to `unrated` that NO consumer read (grep over `src`:
+  one render site), so the effect was binary, `fix-now` or nothing. Every finding now carries a
+  required `kind` — `correctness` and `security` are behaviour and hold the story exactly as
+  before, `docs` and `style` are the way the repo reads and do not — and a `docs`/`style` finding
+  submitted `fix-now` is routed to `defer-with-log`, staying in the artefact, in the PR body and
+  on `retro.md` with a `Normalised-from: fix-now` line saying what it was submitted as. Nothing
+  is lost; it just stops costing a night.
+  This makes a gate WEAKER on purpose, so both directions are priced and both are tested.
+  Unblocking is not free: declaring a `fix-now` finding `docs` costs the SAME `[src: …]` citation
+  `refuted` already costs, through the same §2.8 parser (owner decision, 2026-09-13) — one exit,
+  one rule. The sentence that forced it is "the docstring says cents, the code returns dollars":
+  its own words do not say which side is wrong, and a one-word field deciding that a money bug is
+  a typo is the one failure with no log line to find it by, so the reviewer cites the behaviour
+  that makes it harmless or leaves it `correctness`. When in doubt it blocks: a `kind` that is
+  absent, unreadable or outside the enum is refused — for FREE, indexed as a fault in the report
+  so it costs the story no attempt, because a reviewer that forgot a field did not do bad work.
+  Reading is tolerant the other way (§7): a fix list already on disk with no `Kind:` line, or one
+  whose `Kind:` does not narrow to the enum, reads as *not stated*, and not stated blocks.
+  The four reviewer-prompt goldens MOVED, and that is the change, not an accident: the schema
+  alone would have left a reviewer nobody told about the new field, so the prompt's own prose
+  explains it, and `test/build-golden.test.ts` froze that prose. The diff is exactly eleven
+  inserted lines at one insertion point in each of the four reviewer prompts and nothing else — no
+  event, no `run.yml` row, no exit code. The prose teaches only the JUDGEMENT (which of the four
+  words is true of the defect) and never spells the field name: gh #133's guard derives that list
+  from `REVIEW_SCHEMA` itself, and it caught the first version of this wording.
+
+- **The spawned developer can delete a file, and a permission refusal is now a recorded reason
+  instead of two burned attempts (#261).** Measured 2026-09-12 on one workspace at 0.16.1: story
+  S7, "delete an unused file", was undoable. The developer's allowance carried no verb that
+  removes a path — `Write`/`Edit` can empty a file, nothing could unlink it or take it out of
+  the index — so every `git rm` and `git mv` it tried came back "This command requires
+  approval", which in a headless `-p` run is a prompt nobody is there to answer. Worse was what
+  the framework did with that: a refused turn exits 0 and returns an envelope, so the DoD ran
+  green on an untouched tree, the empty commit went to review, the reviewer faulted a diff that
+  was never written, and the SECOND attempt bought the same wall — the developer's own sentence
+  living only in `result.raw.json`, in no event, no story file and no handoff. Two halves, and
+  the second is the one that generalises. The allowance grows the file-lifecycle git verbs —
+  `Bash(git rm *)`, `Bash(git mv *)`, `Bash(git restore *)`, the space form, never a bare `rm`
+  — because they are index operations on the story's OWN tree, undone by exactly the
+  `git checkout` that undoes an `Edit`, on a branch that never leaves the machine (`git push`
+  stays asserted absent); the 2026-08-29 audit's line — no permission-free shell, only git verbs
+  — is the reason the three are git verbs and is unchanged. And a tool call refused for approval
+  now BLOCKS the story at once with `` permission — `<command>` `` and why, one string reaching
+  the story file, the handoff's `## Unknowns` and `gate.requested`'s `blocked_reason`, so the
+  next verb that is missing costs one attempt and says so instead of two and nothing. What the detector
+  reads is a structural field first — `tool_result_meta[].non_execution_kind: "user-rejected"`, measured
+  on `claude` 2.1.270, present on both refusals measured and absent on every command that ran, including
+  one the layer allowed and git itself failed — and the `requires approval` sentence only as a fallback,
+  and only on a `Bash` call whose result errored. That fence exists because pre-merge review measured the
+  unfenced version reading a plain `Read` of a file CONTAINING the phrase as a refusal: this CHANGELOG is
+  one of the files that contains it, and the block happens before the DoD and the commit, so a false
+  positive would discard real work and spend the attempt. A refusal carrying neither signal is a miss
+  taken on purpose, and the sentence half depends on prose the host writes and can change without notice. What the
+  new grant covers, measured against `claude` 2.1.270 with `Bash(git rm *)` as the only rule:
+  `git rm -r`, `git rm -rf` and `git rm -r -- .` all pass (a trailing `*` matches the whole
+  argument tail, flags included); a path outside the repo is refused by GIT, not by the rule;
+  `git -C <elsewhere> rm` is refused by the rule, since the command does not begin `git rm`.
+  The open question about the same grammar, **#215** — does an `allow` rule of the
+  `Bash(<cmd> *)` form reach a command substitution in its arguments? — was measured alongside
+  this, `claude` 2.1.270, with `git rm -n` as a non-destructive instrument: under
+  `Bash(git rm *)`, `git rm -n -- "$(echo MARKER.txt)"`, `git rm -n "$(echo MARKER.txt)"` and
+  `git rm -n -r "$(echo .)"` were **all denied** ("Contains shell syntax that cannot be
+  statically analyzed"), while a bare `git rm MARKER.txt` ran. **The nuance matters more than
+  the result: the layer refuses the SYNTAX of a substitution, not the action** — in the same
+  measurement the agent rewrote the command with the value already expanded, and then it ran.
+  For `git rm <path>` that expanded form is exactly what this grant hands out, so the direction
+  is the safe one; nobody should build a guarantee on "substitutions are blocked", because what
+  is blocked is a spelling. And all of it is HOST behaviour, in the agent CLI's permission
+  layer, which can change without a line of tldrx moving — which is why the argument that holds
+  this grant up is the tree-scope one and not the permission layer's manners.
+- **`run.yml` can finally explain its own `cost_usd`, and a Build turn stopped losing its
+  accounting entirely (#222).** A field audit across three workspaces measured a row reading
+  `input_tokens: 84, output_tokens: 37150, cost_usd: 1.98` for a 124 KB prompt — while the
+  provider's own result for that same turn reported `cache_read_input_tokens: 4911750`. 84 plus
+  37,150 tokens do not cost $1.98; the 4.9 M cache reads do, and nothing on the row could say
+  so. Across 101 surviving transcripts in one workspace, cache reads were 97.3% of the input
+  side and the ledger's column saw 0.002% of it. The counters were parsed on every turn
+  (`spawnAgent.ts`) and thrown away one function later. They are now RECORDED: additively on the
+  task row, and — the half the issue did not know about — on the `agent.result` of the executor
+  path, which emitted **no `usage` at all**, so every Build and Watch turn lost all four
+  counters rather than only the two cache ones (measured: `grep -c usage` over the four frozen
+  golden `*-events.txt` returned 0, 0, 0, 0 with ten `agent.result` lines among them, and
+  `costView.ts`'s `toAttempt` therefore priced a whole Build off `{0,0,0,0}`). Nothing is
+  displayed that was not displayed before: this is a fix to the RECORD, and the dashboard and
+  `tldrx cost` are byte-identical. Two decisions worth naming. The cache counters are gated one
+  at a time rather than under `tokenSplit`'s both-or-nothing rule, because `input`+`output` are
+  two halves of one total that `turnTokens` adds and the cache counters are separate quantities
+  at separate prices (1.25x and 0.1x an input token) that nothing adds — and the spec's own
+  measured pair of calls is the proof that a paired rule would be wrong: the second reported
+  `cache_creation: 0` beside 37,059 cache reads, the single most useful number on the row. And
+  `turnTokens` names them in its input type while deliberately reading neither, so the exclusion
+  is a decision on the record rather than a field nobody has noticed yet: it returns one
+  unlabelled `number`, and folding 4.9 M cache reads into an `input_tokens: 84` would make that
+  number a total in no currency at all. `ExecutorTask` now carries the provider's `usage` whole
+  instead of a hand-copied two-field subset, which is what let the cache counters be dropped at
+  that seam in the first place, and the event block has one spelling for all three emitters
+  (`envelope.ts`'s `usagePayload`). A row from before this exists reads absent, as it should:
+  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 (#247).**
+  #203 holds back the `gate.requested` notification while open questions are the only thing
+  holding an `auto` gate, and released it when the answers landed if the gate was still
+  `pending`. Under `--wait-gates` that test is true by construction: the only thing that
+  self-closes an auto gate mid-wait runs one iteration later, inside the gate wait, after the
+  loop has already decided. Measured 2026-09-12 on two live workspaces, 3 of 3 questioned
+  stages: the Yes/No went out 600 ms after the last answer and the gate signed itself on the
+  very next poll — so the one tap the message invited ran `approve` on an already-approved gate,
+  and because the in-wait `gate.approved`/`stage.done` fall between two notify windows nothing
+  ever arrived to settle it: the bridge kept the prompt open and re-mentioned its owner every
+  escalate tick for two hours. *"esa pregunta está de más, es confusa."* The release now asks
+  the gate's CONDITIONS rather than its status — the same `reevaluateAutoGate` the poll uses,
+  extracted so the poll and the release read one measurement and neither can form a second
+  opinion (§7) — together with the policy that will act on them. Every condition holding and a
+  `--wait-gates` to sign it means there is no decision to take: nothing is sent, and the run
+  says which stage and why on stdout rather than going quiet. A gate something else still holds
+  is notified exactly as #203 promised, and now worded from that one reading: the re-measured
+  verdict supplies the summary's `held by:` sentence and the open questions are read in the same
+  breath, so a payload can no longer name four open questions beside `holding: "none"` — which
+  is what the adapter was handed, measured, and why it drew the default two buttons. #239 fixed
+  WHICH command a questions-held gate offers; this is WHEN, and whether, it is offered at all.
+- **A turn that wrote a lot of files could not be RECORDED, and the invocation died owing the
+  money it had just spent (#248).** Measured on a live headless run: `tldrx run auto … --retry-failed 2`,
+  eight stories, dead at *"refusing to append an invalid event: payload 4135 bytes exceeds the
+  4096 byte cap"*. The field was `outputs` — every run-relative path the turn wrote, 3924 bytes of
+  it under a 212-byte envelope — on the `agent.result` that `recordExecutorTasks` appends. What
+  that one refused append cost is the reason this is three fixes and not one. The append was
+  RAW, so it never reached the capped seam; the seam would not have saved it anyway, because
+  `capPayload` knew how to name exactly one absence and it was `detail`, which an `agent.result`
+  does not have. The throw landed one line AFTER the try/catch #160 built for precisely this, so
+  it escaped `runNext` entirely and came out of the CLI as exit 1 — a code `--retry-failed` does
+  not retry, since its branch keys on exit 5. A loop told to survive two failures survived zero.
+  And `claimEpicBranches` had put the run's epic branch in memory one line before the throw, with
+  the `store.save()` after it: the branch was cut, on disk, and `run.yml` did not say so, so the
+  relaunch read its OWN epic as a stranger's and refused to stack onto it — with the only way
+  back in being `tldrx next --reuse-epic`, which `run auto` does not expose. So: `capPayload`
+  learns `outputs`, and names it by COUNT (`outputs_omitted: 80`) with the full list written
+  beside the event at `<phase>/log/overflow/…-agent.result-outputs.txt` — never a truncated list,
+  which reads downstream as the whole one. The capped seam moves out of `runExecutor` to module
+  scope and all four raw `agent.result` appends route through it, not just the one that was hit:
+  all four carry `outputs` (measured), and the other three had simply not been reached yet. A
+  throw while recording rows now fails the STAGE with exit 5, in the same family as the executor's
+  own throw, and says how many of how many rows reached `run.yml` rather than a boolean that
+  would be false for a partial truth. It repaints no row: those turns finished, and only their
+  event failed to land. And a claim is saved the moment it is earned. `capPayload` still knows
+  its two fields BY NAME and has no general rule for shrinking whatever is biggest — a third
+  growable payload field has to be taught to it, deliberately, or it is refused whole.
+
 ## 0.17.0 — 2026-09-12
 
 ### Added

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 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 |
 | 0.16.0 | 2026-09-11 | `beta` | an unattended run can now clear the one kind of failure it was stopping on, and a gate that refuses says why it refused: measured 2026-09-10 on a real unattended `run auto`, the loop drove itself through what → how → plan and signed all three `auto` gates by itself, and still needed a person four times — three of those were content or money decisions a loop must not make, and the fourth was a plan that failed its own check by five characters over a cap, where a person relaunched the same command and the next attempt fixed the two files and passed, so the loop stopped on the one failure it could have cleared; `tldrx run auto --retry-failed <n>` now runs a failed stage again at most `n` times in a row, bounding exit `5` and nothing else — a usage error (`1`), a money refusal (`2`) and an awaiting-human park (`4`) are each attempted ONCE however large `n` is, because a phase ceiling means a human decides about money and a retry would turn that sentence into a delay — only CONSECUTIVE failures count since what is bounded is "this run is stuck" and not "this run has ever failed", a retry SPENDS as a fresh metered stage under the same phase ceiling and the same `--max-usd`, `0` is the default and a default invocation's lines are byte-identical to what they were, and when the bound is spent the loop stops on the failure's own exit `5` and says the count LAST, so the sentence that reaches a phone is what the loop tried and not a bare number; and an `auto` gate that REFUSES now writes down the verdict its note was always designed to carry — a gate sat pending ~40 minutes while `run status` and `--verbose` named no condition at all, and the reason surfaced only when a person guessed at the `tldrx approve` the status line suggested, which is the one route nobody unattended is going to take — recording all seven conditions WITH THEIR VALUES on the still-`pending` gate, since a note that dropped the passing ones would answer "was it the money" with the same silence, and naming the holding ids on the gate row and on the `waiting` line; it writes only over a `pending` gate, so a gate a person has since signed keeps THEIR words, and only when the verdict would change, so a four-hour `--wait-gates` poll writes once per distinct verdict rather than thousands of times — and that test and that write are a compare-and-set under the workspace lock, because pre-merge review reproduced, with two real processes, a check-then-act over an earlier snapshot erasing a concurrent `approve` outright, and the poll runs every two seconds precisely while a person is deciding |

package/dist/hooks/answer-capture.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-tj66vg1n.js";
+} from "./chunk-7hhjx1wk.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-54vzevgt.js";
+} from "./chunk-26xkmfdr.js";
 import {
   parseHookInput,
   readStdin
@@ -13,12 +13,12 @@ import {
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-jp6jscsd.js";
+} from "./chunk-00h4xah7.js";
 import {
   PHASE_IDS
-} from "./chunk-d0rp8c68.js";
-import"./chunk-k4nqzdw5.js";
-import"./chunk-nqwg5ddj.js";
+} from "./chunk-bm9aqtg3.js";
+import"./chunk-xxcy0tsa.js";
+import"./chunk-ab6cv5v5.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,7 +28,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-fm141jak.js";
+} from "./chunk-p0ns6fex.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -407,7 +407,11 @@ function answerProvenance(block, overrides, repoNames, fallbackRepos) {
   return {
     repos,
     unresolved: named.unresolved,
-    source: override?.decidedBy === undefined ? {} : { decided_by: override.decidedBy }
+    source: override?.decidedBy === undefined ? {} : { decided_by: override.decidedBy },
+    row: {
+      ...override?.alternatives === undefined || override.alternatives.length === 0 ? {} : { alternatives: override.alternatives },
+      ...override?.recommendedWhy === undefined ? {} : { recommended_why: override.recommendedWhy }
+    }
   };
 }
 function unresolvedEntries(captured) {
@@ -445,6 +449,7 @@ function captureAnswers(questionsPath, ctx) {
         fact: text,
         ...truncated ? { truncated: true } : {},
         ...clash === null ? {} : { conflicts_with: [clash.fact.id] },
+        ...prov.row,
         area,
         repos: prov.repos,
         kind: "answer",

package/dist/hooks/budget-gate.js

@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-3kmx3dmz.js";
+} from "./chunk-rw9zk47w.js";
 import {
   EventLog
-} from "./chunk-jp6jscsd.js";
+} from "./chunk-00h4xah7.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -35,10 +35,10 @@ import {
   renderRunEconomies,
   runSpend
 } from "./chunk-4mjxyfp9.js";
-import"./chunk-k4nqzdw5.js";
+import"./chunk-xxcy0tsa.js";
 import {
   noteDeprecations
-} from "./chunk-fm141jak.js";
+} from "./chunk-p0ns6fex.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,

package/dist/hooks/{chunk-jp6jscsd.js → chunk-00h4xah7.js}

@@ -1,7 +1,8 @@
 import {
   GATE_POLICIES,
-  validateGatesPolicy
-} from "./chunk-k4nqzdw5.js";
+  validateGatesPolicy,
+  validateStagePolicy
+} from "./chunk-xxcy0tsa.js";
 import {
   asDocument,
   isRecord,
@@ -27,6 +28,7 @@ var EVENT_TYPES = [
   "run.unlocked",
   "run.cancelled",
   "run.attended",
+  "run.relaunched",
   "phase.started",
   "phase.done",
   "stage.started",
@@ -44,6 +46,7 @@ var EVENT_TYPES = [
   "gate.rejected",
   "gate.revoked",
   "gate.policy_changed",
+  "questions.policy_changed",
   "story.reopened",
   "story.base_fastforwarded",
   "story.review_retried",
@@ -222,6 +225,12 @@ function skippedNote(skipped) {
 }
 var WARNED = new Set;
 
+// src/core/run/questionsPolicy.ts
+var QUESTION_POLICIES = ["human", "recommended"];
+function validateQuestionsPolicy(value, stageIds, issues) {
+  validateStagePolicy(value, stageIds, issues, { field: "questions_policy", policies: QUESTION_POLICIES });
+}
+
 // src/core/plan/branchModel.ts
 var BRANCH_MODELS = ["per-epic", "integration"];
 function isBranchModelKind(value) {
@@ -429,6 +438,9 @@ function describe(value) {
 // src/core/run/duration.ts
 var DURATION_BASES = ["spawned", "prepare-to-commit"];
 
+// src/core/run/shipPolicy.ts
+var AUTO_MERGE_POLICIES = ["never", "checks"];
+
 // src/core/run/RunFile.ts
 var STAGE_STATUSES = [
   "pending",
@@ -599,6 +611,32 @@ function validateRunFile(input) {
     if (doc[key] !== undefined)
       requireString(doc[key], key, issues);
   }
+  if (doc.ship !== undefined) {
+    if (isRecord(doc.ship)) {
+      requireKeys(doc.ship, ["push", "pr", "auto_merge"], "ship", issues);
+      for (const key of ["push", "pr"]) {
+        if (doc.ship[key] !== undefined && typeof doc.ship[key] !== "boolean") {
+          issues.push({ path: `ship.${key}`, message: `expected a boolean, got ${typeof doc.ship[key]}` });
+        }
+      }
+      requireEnum(doc.ship.auto_merge, AUTO_MERGE_POLICIES, "ship.auto_merge", issues);
+      if (requireArray(doc.ship.pr_urls, "ship.pr_urls", issues)) {
+        doc.ship.pr_urls.forEach((url, i) => requireString(url, `ship.pr_urls[${i}]`, issues));
+      }
+      requireString(doc.ship.merge, "ship.merge", issues);
+      if (doc.ship.merges !== undefined) {
+        if (isRecord(doc.ship.merges)) {
+          for (const [name, state] of Object.entries(doc.ship.merges))
+            requireString(state, `ship.merges.${name}`, issues);
+        } else {
+          issues.push({ path: "ship.merges", message: "expected a mapping of repo name to merge state" });
+        }
+      }
+      requireString(doc.ship.shipped_at, "ship.shipped_at", issues);
+    } else {
+      issues.push({ path: "ship", message: "expected a mapping" });
+    }
+  }
   if (doc.keep_worktrees !== undefined && typeof doc.keep_worktrees !== "boolean") {
     issues.push({ path: "keep_worktrees", message: `expected a boolean, got ${typeof doc.keep_worktrees}` });
   }
@@ -618,6 +656,7 @@ function validateRunFile(input) {
     }
   }
   validateGatesPolicy(doc.gates_policy, declaredStageIds, issues);
+  validateQuestionsPolicy(doc.questions_policy, declaredStageIds, issues);
   let stageCount = 0;
   let taskCount = 0;
   let running = 0;
@@ -715,7 +754,12 @@ function validateRunFile(input) {
           if (task.dedupe !== undefined && typeof task.dedupe !== "string") {
             issues.push({ path: `${tp}.dedupe`, message: "expected a string" });
           }
-          for (const key of ["input_tokens", "output_tokens"]) {
+          for (const key of [
+            "input_tokens",
+            "output_tokens",
+            "cache_creation_input_tokens",
+            "cache_read_input_tokens"
+          ]) {
             const value = task[key];
             if (value === undefined)
               continue;

package/dist/hooks/{chunk-54vzevgt.js → chunk-26xkmfdr.js}

@@ -3,9 +3,10 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-nqwg5ddj.js";
+} from "./chunk-ab6cv5v5.js";
 import {
   FACT_CONFIDENCES,
+  FACT_DECIDERS,
   FACT_KINDS,
   MAX_FACTS,
   MAX_FACT_CHARS,
@@ -14,7 +15,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-fm141jak.js";
+} from "./chunk-p0ns6fex.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -85,10 +86,10 @@ function validateFactsFile(input) {
         issues.push({ path: `${path}.source.q`, message: `expected ${readableSource(Q_RE)} or null` });
       }
       const decidedBy = row.source.decided_by;
-      if (decidedBy !== undefined && decidedBy !== "owner" && decidedBy !== "driver") {
+      if (decidedBy !== undefined && !FACT_DECIDERS.includes(decidedBy)) {
         issues.push({
           path: `${path}.source.decided_by`,
-          message: "expected owner, driver or absent"
+          message: `expected ${FACT_DECIDERS.join(", ")} or absent`
         });
       }
     } else if (row.source !== undefined) {
@@ -109,6 +110,21 @@ function validateFactsFile(input) {
         links.forEach((id2, i2) => requireString(id2, `${path}.conflicts_with[${i2}]`, issues));
       }
     }
+    if (row.alternatives !== undefined) {
+      if (requireArray(row.alternatives, `${path}.alternatives`, issues)) {
+        const options = row.alternatives;
+        if (options.length === 0) {
+          issues.push({
+            path: `${path}.alternatives`,
+            message: "expected at least one option not taken, or the key absent"
+          });
+        }
+        options.forEach((option, i2) => requireString(option, `${path}.alternatives[${i2}]`, issues));
+      }
+    }
+    if (row.recommended_why !== undefined) {
+      requireString(row.recommended_why, `${path}.recommended_why`, issues);
+    }
     const superseded = typeof row.superseded_by === "string";
     const retired = isRecord(row.retired) && row.retired.at !== null && row.retired.at !== undefined;
     if (superseded && retired) {
@@ -245,7 +261,9 @@ class FactsStore {
       superseded_by: null,
       retired: input.retired ?? null,
       ...cut || input.truncated === true ? { truncated: true } : {},
-      ...input.conflicts_with !== undefined && input.conflicts_with.length > 0 ? { conflicts_with: [...input.conflicts_with] } : {}
+      ...input.conflicts_with !== undefined && input.conflicts_with.length > 0 ? { conflicts_with: [...input.conflicts_with] } : {},
+      ...input.alternatives !== undefined && input.alternatives.length > 0 ? { alternatives: [...input.alternatives] } : {},
+      ...input.recommended_why === undefined ? {} : { recommended_why: input.recommended_why }
     };
     this.rows.push(fact);
     return fact;