tldr-experts 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,6 +1,83 @@
 # Changelog
 
 
+## 0.14.0 — 2026-09-09
+
+### Added
+
+- **`run auto` now closes an `agent` gate itself, over a note it wrote and had validated (#198).**
+  `gates_policy: agent` said who MAY sign a gate; nothing in the engine produced the evidence note
+  it is signed over. The only writer was the `tldrx gate template` skeleton a host session fills
+  in at a keyboard — so moving a run's gates to `agent` changed *who is permitted to sign* without
+  changing *whether the loop could keep going*, and an unattended run over an all-`agent` run still
+  stopped at every gate with exit 4. Measured on 0.13.1 against a real workspace: the owner ran
+  `tldrx run gates set what:agent / plan:agent / watch:agent`, whose own reply promises "an agent
+  may now close it", and the loop stopped at the next gate anyway.
+  It now spawns one bounded **gate signer** when a stage's checks have passed and its policy is
+  `agent`: the stage's own model and effort, a quarter of the stage's per-agent ceiling, a tool
+  allowance that reads anything and writes exactly one file (`.agent/<stage>/evidence.md`), and a
+  prompt carrying the stage's declared outputs, the seven `auto` conditions as measured, and the
+  §2.8 skeleton rendered by the same function `gate template` writes.
+  The important half is what did NOT change: the note goes through the unchanged
+  `approve --as-agent` path, so `verdict: sign` with every condition holding closes the gate under
+  the note's own `by:`, and a `refuse`, a note that does not validate, a signer that wrote nothing
+  and a signer that died are one outcome — pending for a person, with the reason named on stdout
+  and now in the `gate.requested` notification's summary. There is no path from the signer to an
+  approval the validator would not also have taken, and no flag turns it on: an `agent` policy is
+  already the owner's recorded decision, and a second opt-in would mean the policy never did what
+  it said. `human` gates are untouched and `--gate-agent` stays rendering-only.
+  The turn is recorded like any other (`agent.spawned` / `agent.result`, `role: gate-signer`, a
+  `run.yml` task row, a row in `tldrx cost`), and it runs BEFORE the stage moves to
+  `awaiting_gate` — measured while building this, the other order made the `--wait-gates`
+  heartbeat announce "a signature is waiting on you" while the engine's own signer was still
+  mid-turn, and a person signed the gate the engine was in the middle of signing, three runs out
+  of three.
+
+### Changed
+
+- **The pre-merge reviewer runs targeted tests, not the whole suite.** Measured over one fix
+  wave: the 4,200-test suite ran THREE times in series at ~10 min each — the implementer
+  (`AGENTS.md` §3 requires it), the reviewer, and `merge-wave.sh` (by design). Only the
+  reviewer's was avoidable, and it was avoidable because nothing had told it not to: the brief
+  said merely that it *may* run tests, so a fresh reviewer sensibly ran everything. It now says
+  the negative out loud — run only the test files that cover the diff, named from
+  `git diff --stat`, plus `bun run typecheck`, and **never** the full `bun test` — with the
+  reason attached, that the wave re-runs every gate on the MERGED tree, so the reviewer's run
+  verifies nothing the wave will not, on a tree that is not the one being merged. The rule is
+  in `.claude/skills/maintain/references/sub-agent-briefs.md`, where the reviewer reads it, and
+  stated once in the skill's §3 for the workflow reader.
+- **`AGENTS.md` §2 now says a slash in a branch name is a directory.** The review-record gate
+  (#192) builds `.review/<branch>.md` from the branch name VERBATIM, so `fix/x` wants
+  `.review/fix/x.md` — a nested directory, not `.review/fix-x.md`. Learned from the gate's
+  first refusal in the wild, which cost five minutes to read. The canonical fact lives in §2;
+  the maintain skill cites it rather than restating it.
+- **`ci` cancels a run a newer push has already superseded.** The workflow had no
+  `concurrency:` group, so every push started a run and none of them stopped. Measured over the
+  last week: 25 of 122 push-triggered runs began less than 10 minutes apart on a 5.2-minute
+  average, which is roughly an hour to two hours of runner time per week spent finishing
+  answers nobody would read. `ci.yml` now groups on `github.ref` with `cancel-in-progress`.
+  It weakens no gate: `ci` is not the release gate — `scripts/release-check.sh` runs the full
+  gates before anything is pushed and `publish.yml` re-runs them after the tag
+  (`docs/RELEASING.md`), and neither is touched here.
+- **The docs deploy now fires on `src/cli/helpText.ts`.** `docs-site/scripts/gen-cli.ts`
+  generates the site's `reference/cli-flags.md` and `cli.md` from that one registry, but the
+  workflow's `paths:` filter never listed it — so a help-registry change landed on `main`,
+  deployed nothing, and the published CLI reference kept showing the previous surface. It went
+  stale exactly that way after this week's CLI changes. The filter is otherwise unchanged, and
+  a test now pins the entry rather than trusting the next reader to notice.
+- **`publish.yml` depends on `ci`'s answer instead of recomputing it.** The release job ran
+  typecheck, tests and build as its own steps — a THIRD run of the same gates on the same sha,
+  after the local `release-check.sh --pre-push` and after `ci`. Measured: ~6.5 min a publish,
+  ~14 publishes in a week, ~87 min/week of runner time to re-derive something the repo already
+  knew. Publish now refuses unless the `ci` workflow has a `success` run for `github.sha`,
+  polled for up to 15 minutes through the REST API with `head_sha` (never `gh run list
+  --commit`, which returns `[]` for minutes while the runs exist — `AGENTS.md` §4). Nothing is
+  weakened: the same gates still run, once, and the checks only publish can do — tag equals
+  `package.json`, already-on-the-registry, `release-check.sh --ci`, OIDC trusted publishing —
+  are untouched. A `cancelled` ci run fails by name with the remedy, because the new
+  `cancel-in-progress` can supersede a release commit's run; merges stay frozen during a
+  release, as they already were.
+
 ## 0.13.1 — 2026-09-08
 
 ### Fixed
@@ -35,6 +112,44 @@
 
 ### Added
 
+- **`tldrx run auto --wait-gates <duration>` — the loop waits for a signature the way it
+  already waits for an answer (#197).** Measured on a real workspace the day the notify hook
+  first drove a run: the question loop closed itself — the hook delivered Q1, the owner
+  answered from his chat, and `run auto` printed `waited 132s … resuming` — and then the very
+  next thing the stage did was reach its human gate, where the same owner approved from the
+  same chat and the loop had already exited 4. Three human gates a feature run is three manual
+  re-launches the hook was supposed to make unnecessary. The cause was scoped, not accidental:
+  `--wait-answers` gates its whole wait on an open-question card, which is `null` when the park
+  is a gate, so the wait was never reached. `--wait-gates` is a sibling flag rather than a wider
+  `--wait-answers`, because the two parks are closed by different verbs and calling a signature
+  an "answer" would be the flag name lying about what a person did. Approved → the loop carries
+  on; rejected → it stops and prints the note, which is now its LAST line so the `run.failed`
+  payload carries it to the phone of whoever has to act on it; lapsed → exit 4 with the same
+  lines it always had, after one `gate.timeout` (new kind, `question.timeout`'s twin, carrying
+  the approve and reject lines, the gate's policy, `waited_ms`, and `cost_usd` only when this
+  loop is the one that measured it). Nothing is spent while it polls — it reads files — and
+  whether a gate is pending is read through `waitingFor`, the one derivation `tldrx run status`
+  and the dashboard already share, never a second copy. **It waits FOR a signature and never
+  produces one**: there is no engine-side signing in this loop, so a stage on
+  `gates_policy: agent` stops it exactly as a `human` one does and is waited on identically —
+  an owner who switched three gates to `agent` expecting the loop to carry on was measuring
+  who MAY sign, not that anything had. Both wait flags may be given together, and without the
+  flag a gate exits 4 on the spot exactly as before.
+- **The heartbeat stops telling a waiting owner that nothing is waiting on him at a GATE.**
+  `--notify-every`'s `status` payload learned in 0.11.1 not to say "Nothing is waiting on you"
+  over a run parked on a question — the fix that exists because a heartbeat is believed — but
+  its parked-ness came from the blocking-question predicate alone, so a run parked on a
+  signature got `waiting_on: []` and the exact sentence the fix was written to prevent. A
+  pending gate is now named in `waiting_on_gate` (`<phase>/<stage>`) beside `gate_policy`, the
+  summary says the run is waiting for a person to sign that stage, and `command` is the literal
+  `tldrx approve` line — the same spelling `gate.requested` and every decision card use, now
+  one exported helper instead of four literals. `waiting_on_gate` is a SIBLING key rather than
+  a member of `waiting_on`: an adapter maps every id in `waiting_on` to `tldrx answer <id>`,
+  and a stage id there would make it build a command nobody can type. Both keys are absent when
+  no gate is pending, so a heartbeat over a moving run is byte-identical to the one it sent
+  before. `gate.requested` now names the policy too, so an owner reading it on a phone knows
+  whether he is signing a `human` gate or overriding an `agent` one.
+
 - **`tldrx expert rescore [<name>] [--area <a>]` — score the knowledge you already paid for.**
   Its sibling `recompute` is arithmetic over the evidence rows already in `competencies.yml`;
   `rescore` RE-READS `knowledge/*.md` and derives their evidence again under today's rules. It

package/README.md

@@ -316,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.14.0 | 2026-09-09 | `beta` | an `agent` gate the engine can actually close, and three computations of the same answer cut to one: `gates_policy: agent` named who MAY sign a gate but nothing in the engine produced the evidence note it is signed over — measured on 0.13.1, an owner ran `tldrx run gates set what:agent`, was told "an agent may now close it", and the loop stopped at the next gate anyway with exit 4 — so `run auto` now spawns one bounded **gate signer** when a stage's checks pass under an `agent` policy: the stage's own model and effort, a quarter of its per-agent ceiling, a tool allowance that reads anything and writes exactly one file, and a prompt carrying the stage's declared outputs, the seven `auto` conditions as measured and the §2.8 skeleton `gate template` itself renders — the note going through the UNCHANGED `approve --as-agent` path, so a refusal, a note that does not validate, a signer that wrote nothing and a signer that died are one outcome, pending for a person with the reason named on stdout and now in the `gate.requested` summary, and there is no flag to turn it on because an `agent` policy is already the owner's recorded decision; the turn is recorded like any other (`role: gate-signer`, a `run.yml` task row, a row in `tldrx cost`) and taken BEFORE the stage moves to `awaiting_gate`, because the other order had a person sign the gate the engine was mid-signing, three runs out of three; and the suite stops being run three times per change — the pre-merge reviewer now runs only the test files that cover its diff plus `typecheck`, never the full `bun test`, since the wave re-runs every gate on the MERGED tree anyway, `publish.yml` refuses unless `ci` has a `success` run for the same sha instead of recomputing typecheck/tests/build (~87 min/week of runner time, with a `cancelled` ci run failing by name and the remedy), `ci` cancels a run a newer push has already superseded (25 of 122 push runs began under 10 minutes apart), the docs deploy finally fires on `src/cli/helpText.ts` so a help-registry change stops deploying nothing while the published CLI reference goes stale, and `AGENTS.md` §2 now says out loud that a slash in a branch name is a directory, which is what the review-record gate builds |
 | 0.13.1 | 2026-09-08 | `beta` | a stage prompt that opens by saying what to do: every stage prompt now leads with a generated brief — who the reader is, which stage of which run, that the template below is to be FILLED, the exact path of every declared output, and that a question goes in the questions file rather than back to an operator who is not there — because on a real workspace at 0.13.0 a What sub-agent read its 66,452-byte prompt, found no request in it, wrote none of its six declared outputs and asked what to do, $0.29 spent; the brief is generated from the same `outputs:` list `pending.json` records, so it cannot name a path the commit will not look for, and the failure was never a regression — the spliced citation grammar grew the stage section 5,007 B → 13,180 B and the missing instruction was finally outnumbered; and the `N runs are open` nudge, the one imperative-shaped sentence in that agent's window and the one it duly answered, stops reaching sub-agents at all — `spawnAgent` marks every child it spawns and `session-start` emits nothing when it sees the marker, an absent marker still being a human's session and behaving exactly as before |
 | 0.13.0 | 2026-09-08 | `beta` | evidence a role expert can actually earn, and a review that leaves a record: `--mode full`'s runs pass mines `tldrx-work/**` while the domain gate judged every citation it produced against folders of code — measured at four role experts, **$9.47 and one evidence row**, and unfixable from the workspace because the single spelling the matcher would reach is the one `domainPaths()` drops — so the gate now treats the run record as in-domain for the file mined FROM it, scoped to the pass and never to the expert's `kind:` (a light file citing a handoff is still out of domain and still says so), two shipped role templates stop declaring `.tldrx/map/**` and `.tldrx/map/{repo}/gotchas.md` paths that matched nothing at all, and a pass that validated, spent money and earned zero rows now prints `the level did not move — $X.XX bought 0 evidence row(s)` with its reasons carried into `check.passed` instead of a silent ledger; `tldrx expert rescore` recovers what was already bought for $0 by re-reading `knowledge/*.md` under today's rules, dating rows by the knowledge file's own `trained_at` and never by the clock, with `rescored_at` additive beside `at` — its ABSENCE keeping the meaning every existing row had — and one `evidence.rescored` line per file it actually moved, so a free re-derivation can never be read as a paid turn; `scripts/merge-wave.sh` refuses a branch carrying no `.review/<branch>.md` with **exit 10**, its own code because `2` in that script is already "merge conflict", a stale record refusing rather than warning and staleness measured as "the code moved" rather than "the sha differs", since committing the record moves the head past exactly the sha it names; and the mutation check moves from the reviewer, whose allowance is `Read`/`Grep`/`Glob`/`Bash(git diff *)` and holds no pen, to the developer's contract that can run it, leaving the reviewer the read it can actually perform |
 | 0.12.0 | 2026-09-08 | `beta` | records that can be attributed and spans that were actually measured: the reviewer can be pinned to its own model and effort per role (`reviewer:`) and per story stakes (`reviewer_by_stakes:`, keyed on a story's new optional `stakes:` enum), resolved field by field under `--model`/`--effort` and shipping NO opus default — because there is no evidence yet that a stronger reviewer finds more, only the record that lets the evidence accumulate: every verdict now names the model that produced it, a host review reading `basis: host-declared` off its own flags and a host that declared nothing reading `not recorded` rather than the bundle's suggestion; `run.yml` gains `created_with` and `last_written_by` beside the file format's own `version: 1`, and `agent.spawned`/`agent.result` carry `tldrx_version`, so a run that outlived an upgrade carries both ends of the range that drove it; a task row carries `duration_ms` that never travels without `duration_basis` — `spawned` is the wall clock around the sub-agent's process, `prepare-to-commit` is a ceiling that includes the host's own time — and `tldrx cost` shows a duration per attempt and a per-stage sum that names a mixed basis instead of adding two different quantities, with a pre-existing row reading `not recorded` and never `0s`; no surface prints a bare `$0.00` over work nobody metered — one implementation writes `≥ $12.40 (7 tasks unmetered)` or `not measured: 9 in-session tasks, 0 metered` across `run status`, `budget show`, the dashboard, `replay`, `run auto`, the Build handoff and every notification, and `budget.yml` gains `unmetered_tasks` and `spent_basis`; the surface a story actually changed is measured off its own diff over the range the reviewer was shown and appended as one `story.touches_widened` with `basis: "measured"` beside what was declared, advisory and never rewriting the operator's `touches:`; and a `maintain` skill encodes the maintenance circuit twelve hand-run waves actually measured — reproduce an issue on current `origin/main` before touching anything, a fresh reviewer before `merge-wave.sh` and not after, at most 3 issues and 2 implementers a cycle — pinned by a test that every command and `§N` it cites resolves |
@@ -347,7 +348,8 @@ path documented; `stable` = 1.0, semver from here on. The badge above shows the
 **One command: `scripts/release.sh X.Y.Z --tag beta`.** The tag is not optional in practice: omit
 `--tag` and the script writes `alpha`, which is no longer this project's status. It is the only
 sanctioned path — a Claude Code hook denies hand-made `git tag` / `npm publish`, and `publish.yml`
-runs `release-check.sh --ci` (the file checks only) plus its own typecheck, tests and build.
+runs `release-check.sh --ci` (the file checks only) and refuses to publish unless the `ci`
+workflow is already green for that exact sha.
 Checklist and judgement calls: `docs/RELEASING.md`.
 
 MIT, © 2026 Alan Martinez — a placeholder made while scaffolding; change it freely before anything ships.

package/dist/hooks/answer-capture.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-fyr7f9t6.js";
+} from "./chunk-3ns54mnq.js";
 import {
   FactsStore,
   formatJaccard

package/dist/hooks/session-start.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   questionsCard
-} from "./chunk-fyr7f9t6.js";
+} from "./chunk-3ns54mnq.js";
 import"./chunk-nwzevx0j.js";
 import {
   allow,