tldr-experts 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,143 @@
 # Changelog
 
+
+## 0.9.0 — 2026-09-06
+
+### Added
+
+- **`AGENTS.md` is the canonical agent context, and `CLAUDE.md` imports it.** Four days of
+  live-maintenance tribal knowledge written down where every agent — Claude Code sessions in
+  fresh windows, Codex, anything reading `AGENTS.md` — starts with it: the golden evidence
+  rules (including "never quote a CLI flag from memory"), worktree+merge-wave discipline, the
+  five gates, the `gh run list --commit` lie and the non-empty-checks assertion, CHANGELOG
+  union and release ritual, the pinned house invariants, hermetic test rules, public-surface
+  guard rules, provider facts, and the known live traps. One file; the other imports it,
+  because two rule files drifting apart is the failure mode this repo exists to kill.
+- **Stack packs — `tldrx expert packs <enable|disable|status>`.** A `<lang>-stack` expert was a
+  name-only stub: the language name was the only stack-specific token in its body, so the
+  developer built from the model's habits and the reviewer had no stack checklist to hold a
+  story against (the repo's own audit scored the experts' knowledge 6/10). Off by default,
+  behind one per-project switch: `enable` materialises four language packs (TypeScript,
+  JavaScript, Python, .NET) and thirteen manifest-detected framework overlays (`react`,
+  `next-app-router`, `vite-react-spa`, `expo-router`, `node-express`, `prisma`,
+  `aspnet-minimal-apis`, `aspnet-controllers`, `mediatr-cqrs`, `efcore-npgsql`, `fastapi`,
+  `sqlalchemy-alembic`, `postgres-testcontainers`) into `.tldrx/experts/<lang>-stack/`, kept apart
+  from `knowledge/`, which no packs command ever touches. A pack is interrogative by owner
+  decision, never prescriptive over a repo's own conventions: **Defaults** apply only where the
+  project is silent and each one names the signal that overrides it, and **Checks** are questions
+  the Build reviewer now asks under every diff, each carrying a `verify:` hint and yielding to
+  the project's own convention when it has one. `enable` replaces a body only when it is an
+  untouched stub — an edited body is `kept:` and the command says so — and a body one shipment
+  behind is `upgraded:` rather than silently frozen at the version it was first materialised
+  with, told apart by two additive front-matter keys the materialised body carries: `pack:
+  <lang>@<hash>` names the shipment and `pack_body:` names the body's own bytes, so "somebody
+  edited this" (bytes differ) and "this is one shipment behind" (bytes match, shipment differs)
+  are never the same answer. `disable` removes `overlays/` and nothing else. Overlays are
+  detected from manifests (`package.json`'s two dependency groups kept apart, `*.csproj` /
+  `Directory.Packages.props`, `pyproject.toml` and `requirements*.txt`) and never inferred from
+  the language, because two workspaces of the same language can run opposite architectures — one
+  prescriptive ".NET pack" would be wrong for whichever one it disagreed with. No new prompt
+  mechanism: every renderer already prints an expert's body, so `body + overlays` composes once
+  in `loadExpertBundles` and reaches every stage prompt and the Build developer unchanged; the
+  reviewer, which carried no expert content at all, is handed the active packs' Checks explicitly
+  under a new `## Stack checks (the repo's own conventions win)` section, rendered only when BOTH
+  the workspace switch and the story's own stage-level `stack_experts` are on — so a developer
+  turn that was never shown a stack expert is never graded against Checks it was never briefed
+  on. `workspace.yml` gains `stack_packs` and `repos[].overlays` (each with its evidence string)
+  — additive, `version: 1` unchanged, and read back on every re-init so a regenerate never
+  silently turns the switch off. For a workspace that never threw the switch, this is today's
+  bytes, byte for byte. Once `enable` has run, `disable` stops the overlays and the reviewer's
+  Checks, but a pack body already materialised into `expert.md` stays there until you delete
+  it — `disable` removes only `overlays/`, by design (fix round 2, ruled) — and `enable` re-seeds
+  a body it finds missing or still an untouched stub.
+- **Project skills are named to the developer, independent of the packs switch.** A repo's own
+  `.claude/skills/*/SKILL.md` files are detected into `repos[].skills` and rendered under
+  `## Project skills` in every stage prompt and the Build developer's — name, description, and
+  the path to read — because skills are for doing and packs are for checking: the harness runs a
+  skill, the framework only says it exists. The Build developer's allowed tools gain `Skill` only
+  when that story's repo has one (whether an agent CLI's print mode actually denies an unlisted
+  `Skill` call is unverified — the framework's job is the list, not the enforcement). A skill git
+  does not track is flagged in the prompt and warned at Build start, by name and by repo, because
+  a story worktree carries tracked files only and the path the prompt names would not exist
+  there.
+- **The context ledger separates `expert.md` bytes from overlay bytes.** `pending.json` gains
+  `overlays`/`overlay_bytes` on a stack expert's row — additive and absent (not `0` or `[]`) when
+  nothing was inlined, so a bundle the switch never touched stays byte-identical to one written
+  before packs existed — and a new `project_skills_bytes` beside the other context groups, a
+  required count like its siblings, `0` when the workspace detected no project skills rather than
+  absent. `expert_md_bytes` keeps the meaning it has always had, `expert.md`'s own bytes and never
+  the composed total, and the operator line prints the two counts separately for the same reason.
+- Two out-of-scope findings from building this: stack-expert naming has two independent
+  derivations that agree today only because a mismatch fails silently (#152), and a project's own
+  `AGENTS.md`/`CLAUDE.md`/`CONTRIBUTING.md` are detected by presence only — their content never
+  reaches a stage prompt (#153).
+
+## 0.8.0 — 2026-09-04
+
+### Added
+
+- **`tldrx drive --tldr` — essentials only, for a run whose trail nobody will read.** It adds
+  one section to either mandate and stamps the header `· tldr ·`. The session reports in a
+  fixed shape — what `tldrx run status` already prints (phases, percentages, spend against the
+  ceiling, what is next) plus **at most three bullets of delta** — and stops narrating: no
+  recap of a sub-agent's report, no summary of a diff, no restating the status block in prose.
+  Free text is reserved for a strict blocker's guided question and for a correction.
+  It also turns off the half of the trail nothing consumes: no `tldrx note`, and gate evidence
+  at the template's minimum. A fact that must outlive the turn goes to `tldrx facts add`, which
+  every later prompt **does** read.
+  Measured on a ten-run workspace: of ~4.0 MB written, 2.16 MB is trail, and all **261**
+  declared stage `inputs:` contain **zero** occurrences of `handoff.md`, `retro.md` or
+  `gate-evidence` — ~445k tokens of output across those runs that no prompt ever reads back.
+  Operator notes alone are 133,689 B.
+  What `--tldr` deliberately does **not** do is drop the handoff: `claim-sources` is condition 5
+  of the seven `auto` conditions and runs whether or not a stage declared it, so a run without
+  one cannot close an `auto` or `agent` gate. The mandate briefs sub-agents to trim the *prose*
+  and never the `[src: …]` citations, and says why. `--tldr` works on `--attended` too — terse
+  output is orthogonal to who signs. Absence is today: without the flag both mandates render
+  byte-identically to before, and a test asserts it.
+- `MANDATE_TLDR_MAX_LINES` (`165`) bounds the `--tldr` variants; the standard mandate keeps the
+  tighter `MANDATE_MAX_LINES`. Two constants rather than one looser one, so the terse mode does
+  not spend every other run's skimmability budget.
+
+### Fixed
+
+- **`tldrx drive --unattended` told the driver four times to stop and never once to
+  continue, and the runs it drove did exactly that.** Measured over the eight driven runs
+  of a real workspace: 26 `budget.raised` and 26 `question.answered` events, and an owner
+  who had to type *"sigue con todas desatendido, no esperes por mi"* **inside** an
+  unattended run to restart a session the mandate had correctly halted. `grep -ic
+  "continue|keep going|proceed|do not stop|resume"` over `mandate.ts` returned `0`. The
+  unattended mandate now opens the discipline with a **`## Do not stop`** section that
+  defines the only thing that may halt a run — a STRICT blocker, one where no remaining
+  turn can proceed until the owner answers — and makes the driver **name the work the
+  blocker does not block** before it may call one strict. The three remaining halts are
+  narrowed to match: the preflight refusal is now *asked* rather than gone quiet on, the
+  budget bullet keeps "do not raise one, do not route around one" but no longer halts the
+  run (it asks, then keeps spending what the ceiling still funds), and the interrupt list
+  is strict blockers only, "never as a bare halt".
+- **A parked question is now a GUIDED question.** "State the question in one sentence" got
+  open prompts nobody could answer from a phone, so a product question stopped a run for
+  hours. Parking now asks for 2–5 lettered options with their consequences, what the run's
+  own docs and facts already decide, the option the driver would take, and what it will do
+  if no answer arrives. Both modes carry it.
+- **The old halt licence is gone.** "If the only safe version is *do nothing yet*, do
+  nothing yet and park it" was true about the write and read as true about the run. The
+  text now says which it means: not shipping an unguarded write is not the same as not
+  shipping anything.
+
+### Changed
+
+- **The ask channel is the console, and the framework stays agnostic about anything else.**
+  The mandate says *"Ask on the console, unless my launch message named another channel"* —
+  no chat vendor is named in shipped text, and a test asserts none ever is, so one
+  operator's bridge never becomes a dependency of everybody's run. A default the driver
+  falls back on when no answer reaches it is recorded as the **driver's** decision and may
+  never be cited back as the owner's — the distinction one run drew by hand and the text
+  now carries.
+- `MANDATE_MAX_LINES` moved once, `120` → `140`, with the reason recorded in the source.
+  The bound is still real and still asserted; the unattended mandate renders 137 lines and
+  the attended one 123. File formats remain `version: 1`.
+
 ## 0.7.0 — 2026-09-03
 
 ### Added

package/README.md

@@ -75,14 +75,30 @@ Two commands and a prompt — and the prompt now ships with the package:
 ```bash
 tldrx drive --unattended        # print the mandate; paste it into the session that drives the run
 tldrx drive --attended          # the same disciplines, but every gate stays yours to sign
+tldrx drive --unattended --tldr # essentials only, for a run whose trail you will not read
 ```
 
 `tldrx drive` needs no workspace, opens no run and writes nothing: it prints the discipline the
 first real runs were driven by — the three-role protocol (developer → a **fresh** adversarial
 reviewer, never the author → the host verifying both in the code, not in their reports), evidence
-labelled `measured` / `inferred` / `assumed`, product questions parked rather than decided, the
-reviewer calibrated to the story's stakes, and the cost declared once. The two modes differ in
-exactly two places: who drives the turns, and who may close a gate.
+labelled `measured` / `inferred` / `assumed`, product questions parked as **guided** ones rather
+than decided, the reviewer calibrated to the story's stakes, and the cost declared once. The two
+modes differ in exactly two places: who drives the turns, and who may close a gate.
+
+**The unattended mandate leads with `## Do not stop`.** A run only ends early because the session
+decides to, so the text defines the one thing that may end it — a strict blocker, where no
+remaining turn can proceed until you answer — and makes the driver name the work a blocker does
+*not* block before it may halt for it. Everything short of that is parked as a guided question
+(lettered options, the option the driver would take, asked on the console unless your launch
+message names another channel) and the run carries on down every path the question does not block.
+
+**`--tldr` is for the runs you will not audit.** The session reports what `tldrx run status`
+already prints — phases, percentages, spend against the ceiling, what is next — plus at most three
+bullets of delta, and stops narrating. It also drops the half of the trail nothing consumes:
+measured across ten real runs, of ~4.0 MB written 2.16 MB is trail, and all 261 declared stage
+`inputs:` contain **zero** references to `handoff.md`, `retro.md` or `gate-evidence`. It is a
+reporting contract, not a quality setting — the evidence discipline and the gate checks are
+untouched, and handoffs keep their citations because `claim-sources` gates on them.
 
 The rest of this section is what that mandate says, in the shape you would type it by hand.
 
@@ -272,7 +288,7 @@ draws before installing anything.
 The reference guide, in `docs/guide/`: [1 Quick start](docs/guide/01-quick-start.md) ·
 [2 The loop](docs/guide/02-the-loop.md) (the four steps, what a stage file controls, the two execution modes) ·
 [3 Runs and gates](docs/guide/03-runs-and-gates.md) (`run new`→`retro`, gate policy, `run auto`, unlock/cancel, dashboard, tickets) ·
-[4 Experts](docs/guide/04-experts.md) (loading rules, role experts, training, levels) ·
+[4 Experts](docs/guide/04-experts.md) (loading rules, role experts, stack packs, training, levels) ·
 [5 Seeds and triage](docs/guide/05-seeds-and-triage.md) (`--seed`, `--from`, splitting a big seed) ·
 [6 Budgets and cost](docs/guide/06-budgets-and-cost.md) · [7 Claude Code](docs/guide/07-claude-code.md) (plugin, hooks, `/tldrx`) ·
 [8 CLI reference](docs/guide/08-cli-reference.md) (every command, flag and exit code) ·
@@ -298,6 +314,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.9.0 | 2026-09-06 | `beta` | opt-in stack packs: four language pack bodies and thirteen framework overlays detected from manifests, interrogative by default (Defaults yield to any repo signal, Checks are questions with `verify:` hints), behind one per-project switch (`tldrx expert packs enable`) that materialises into `.tldrx/experts/<lang>-stack/` without touching trained knowledge; the Build reviewer gets `## Stack checks (the repo's own conventions win)`; every stage names the project's `.claude/skills` and the developer may invoke them; workspace.yml records overlays with evidence and skills with a tracked flag, `version: 1` unchanged |
+| 0.8.0 | 2026-09-04 | `beta` | the unattended mandate learns to keep going: a `## Do not stop` section that defines the one thing allowed to end a run early (a strict blocker, named against the work it does not block), product questions parked as **guided** ones with lettered options and a pre-declared fallback, and a budget stop that asks instead of halting — written against 26 `budget.raised` and 26 `question.answered` events on a real ten-run workspace where the owner had to re-authorise "unattended" mid-run. Plus `tldrx drive --tldr`: a reporting contract for runs nobody will audit — the `run status` block plus three bullets of delta, no operator notes, minimal gate evidence, handoffs trimmed of prose but never of the citations `claim-sources` gates on. The ask channel stays the console and the framework names no chat vendor |
 | 0.7.0 | 2026-09-03 | `beta` | Codex as a second honest automated runner: recorded JSONL contract, structured envelopes, role-based sandboxes, token/session provenance, and explicitly unmetered USD accounting; Claude remains the default and the pilot harness. Also absorbs the citation-honesty work previously staged as 0.6.2: a `file` src resolves against the branches the run RECORDED and NAMES the unmerged ref instead of passing in silence or breaking with the temp dir (#140), watcher cards name it the same way (#143), and every run close reports the questions nobody answered (#141) |
 | 0.6.1 | 2026-09-03 | `beta` | dogfooding fixes from the first fully-unattended runs: blocked stories never lose uncommitted work (rescue commits + `story.work_rescued`), a fix is only Resolved with a reachable sha, re-entered stages reconstruct their handoff from the ledger instead of degrading it, the Cost header reports the phase and names its lower bound (shared `spendBasis`), feature presets resolve their per-repo maps, Plan sees the command allowlist its gate enforces, the landing sells the unattended flow |
 | 0.6.0 | 2026-09-02 | `beta` | the dashboard suite — a "Now" hero strip, `--serve` live refresh, stage durations and gate notes on page and CLI, and a public demo generated from fixtures; honest dual-economy spend (metered + host, lower-bound named); gate provenance — `executed_by` + `authority` so a delegated signature never reads as a personal one, machine-signed reporting fixed; ONE `absent:` semantic shared by claim-sources and the auto gate; superseded stamps when an owner answer flips an earlier phase doc; run close commits its state and `ship` refuses a state-carrying epic; merge-wave gates `docs:build`, survives interruption and self-rewrite; a public-surface drift guard; env.yml validation (unique ids, tool cap) |

package/dist/hooks/budget-gate.js

@@ -29,7 +29,7 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-md1c7z7q.js";
+} from "./chunk-c4p5x1b4.js";
 import {
   EventLog
 } from "./chunk-b9rjx4qc.js";

package/dist/hooks/{chunk-pf9d8ag8.js → chunk-6ytv36jd.js}

@@ -7,7 +7,7 @@ import {
   nowRfc3339,
   openRunViews,
   validateRunBudget
-} from "./chunk-md1c7z7q.js";
+} from "./chunk-c4p5x1b4.js";
 import {
   EventLog,
   asRunFile,

package/dist/hooks/{chunk-md1c7z7q.js → chunk-c4p5x1b4.js}

@@ -752,33 +752,50 @@ function pathsIntersect(a, b) {
 // src/core/experts/expertKnowledge.ts
 var DEFAULT_KNOWLEDGE_MAX_BYTES = 48 * 1024;
 
-// src/core/facilitator/dispatchNotes.ts
-var DISPATCH_NOTES_MAX_BYTES = 8 * 1024;
-
-// src/core/experts/stackExperts.ts
+// src/core/experts/workspaceRepos.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
 import { join as join5 } from "node:path";
-function stackExpertNames(root, repos) {
+function readWorkspaceDocument(root) {
   const path = join5(root, PROJECT_FRAMEWORK_DIR, "workspace.yml");
   if (!existsSync4(path))
-    return [];
-  let doc;
+    return null;
   try {
-    doc = parseYaml(readFileSync4(path, "utf8"));
+    return parseYaml(readFileSync4(path, "utf8"));
   } catch {
-    return [];
+    return null;
   }
-  const list = doc?.repos;
+}
+function workspaceRepoRows(doc) {
+  if (typeof doc !== "object" || doc === null)
+    return [];
+  const list = doc.repos;
   if (!Array.isArray(list))
     return [];
-  const names = [];
+  const rows = [];
   for (const row of list) {
-    if (typeof row?.name !== "string" || !repos.includes(row.name))
+    if (typeof row !== "object" || row === null)
       continue;
-    const stack = Array.isArray(row.stack) ? row.stack : [];
-    for (const language of stack) {
-      if (typeof language !== "string" || language === "")
-        continue;
+    const record = row;
+    if (typeof record.name !== "string")
+      continue;
+    rows.push(record);
+  }
+  return rows;
+}
+function strings(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+// src/core/facilitator/dispatchNotes.ts
+var DISPATCH_NOTES_MAX_BYTES = 8 * 1024;
+
+// src/core/experts/stackExperts.ts
+function stackExpertNames(root, repos) {
+  const names = [];
+  for (const row of workspaceRepoRows(readWorkspaceDocument(root))) {
+    if (!repos.includes(row.name))
+      continue;
+    for (const language of strings(row.stack).filter((item) => item !== "")) {
       const expert = `${language}-stack`;
       if (!names.includes(expert))
         names.push(expert);

package/dist/hooks/session-start.js

@@ -15,7 +15,7 @@ import {
   openQuestions,
   runSnapshot,
   whatIsWaiting
-} from "./chunk-pf9d8ag8.js";
+} from "./chunk-6ytv36jd.js";
 import {
   evidencePath,
   expertsDir,
@@ -25,7 +25,7 @@ import {
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-md1c7z7q.js";
+} from "./chunk-c4p5x1b4.js";
 import {
   parseEvidence
 } from "./chunk-b9rjx4qc.js";
@@ -925,11 +925,19 @@ function evidenceCount(expert) {
 // src/core/experts/roleExperts.ts
 import { join as join5 } from "node:path";
 var ROLE_TEMPLATES_DIR = join5(TEMPLATES_DIR, "experts");
+// src/core/experts/packSections.ts
+var PACK_MAX_BYTES = 24 * 1024;
 // src/core/experts/domainRank.ts
 var MAX_GRAPH_BYTES = 64 * 1024 * 1024;
+// src/core/experts/packTemplates.ts
+import { join as join6 } from "node:path";
+var PACK_TEMPLATES_DIR = join6(TEMPLATES_DIR, "experts", "stack");
+var OVERLAY_TEMPLATES_DIR = join6(PACK_TEMPLATES_DIR, "overlays");
+var PACK_BODY_MAX_BYTES = 8 * 1024;
+var OVERLAY_MAX_BYTES = 6 * 1024;
 // src/core/training/mineRuns.ts
 import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync as readdirSync4, statSync as statSync4 } from "node:fs";
-import { join as join6, relative as relative2 } from "node:path";
+import { join as join7, relative as relative2 } from "node:path";
 var MAX_RUN_BYTES = 64 * 1024;
 var MINED_NAMES = ["handoff.md", "retro.md"];
 var MAX_DEPTH = 4;
@@ -953,7 +961,7 @@ function findMined(dir, depth) {
   for (const entry of [...entries].sort()) {
     if (entry.startsWith("."))
       continue;
-    const abs = join6(dir, entry);
+    const abs = join7(dir, entry);
     let isDir = false;
     try {
       isDir = statSync4(abs).isDirectory();

package/dist/hooks/statusline.js

@@ -2,8 +2,8 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-pf9d8ag8.js";
-import"./chunk-md1c7z7q.js";
+} from "./chunk-6ytv36jd.js";
+import"./chunk-c4p5x1b4.js";
 import"./chunk-b9rjx4qc.js";
 import"./chunk-rrkdfk7s.js";
 import"./chunk-5w5eg00k.js";