tldr-experts 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # 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

package/README.md

@@ -288,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) ·
@@ -314,6 +314,7 @@ 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 |

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";