tldr-experts 0.3.0

package/env.yml

@@ -0,0 +1,79 @@
+# schema: draft
+#
+# The local dev environment manifest. `tldrx doctor` reads this file, runs each
+# `check` command, and prints what it found.
+#
+# The framework NEVER installs anything. `install` holds a copy-paste hint per OS
+# and nothing more. Keys: macos | linux | windows | all.
+#
+# `check` must exit 0 when the tool is usable and print something version-shaped
+# (the first dotted numeric run in stdout+stderr is taken as the version).
+
+version: 1
+
+tools:
+  - id: bun
+    required: true
+    min_version: "1.3.0"
+    check: "bun --version"
+    purpose: "Runs the tldrx CLI, the hooks and the test suite. Bun 1.3+ is required for native Bun.YAML."
+    install:
+      macos: "curl -fsSL https://bun.sh/install | bash"
+      linux: "curl -fsSL https://bun.sh/install | bash"
+      windows: "powershell -c \"irm bun.sh/install.ps1 | iex\"   (or: npm install -g bun)"
+
+  - id: node
+    required: true
+    min_version: "20.0.0"
+    check: "node --version"
+    purpose: "Runs the published build (package.json bin + engines). Also required by Claude Code itself."
+    install:
+      macos: "brew install node   (or: https://nodejs.org)"
+      linux: "https://nodejs.org/en/download/package-manager"
+      windows: "winget install OpenJS.NodeJS   (or: https://nodejs.org)"
+
+  - id: git
+    required: true
+    min_version: "2.30.0"
+    check: "git --version"
+    purpose: "Workspace detection, worktrees for parallel stories, churn data for map/hotspots.md."
+    install:
+      macos: "xcode-select --install   (or: brew install git)"
+      linux: "sudo apt-get install git   (or your distro's package manager)"
+      windows: "winget install Git.Git"
+
+  - id: claude
+    required: true
+    min_version: "2.0.0"
+    check: "claude --version"
+    purpose: "The pilot harness. Sub-agents run as `claude -p --output-format json`; hooks and the statusline are Claude Code primitives."
+    install:
+      all: "npm install -g @anthropic-ai/claude-code   (see https://code.claude.com/docs/en/quickstart)"
+
+  - id: python3
+    required: false
+    min_version: "3.10.0"
+    check: "python3 --version"
+    purpose: "Runtime for graphify (the code-map tool). Only needed if you want `tldrx map`."
+    install:
+      macos: "brew install python@3.12   (or: https://www.python.org/downloads)"
+      linux: "sudo apt-get install python3 python3-pip"
+      windows: "winget install Python.Python.3.12"
+
+  - id: graphify
+    required: false
+    min_version: "0.8.0"
+    check: "graphify --version"
+    purpose: "Deterministic tree-sitter code map. Feeds map/*.md. Absent = `tldrx map` cannot run; nothing else is affected."
+    install:
+      all: "pip install graphify   (requires python3 >= 3.10)"
+
+  - id: gh
+    required: false
+    min_version: "2.0.0"
+    check: "gh --version"
+    purpose: "Optional ticket adapter (GitHub issues) and PR operations."
+    install:
+      macos: "brew install gh"
+      linux: "https://github.com/cli/cli/blob/trunk/docs/install_linux.md"
+      windows: "winget install GitHub.cli"

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "tldr-experts",
+  "version": "0.3.0",
+  "description": "tldr-experts: a lightweight, file-based AI development workflow. Installs the `tldrx` (and `tldr-experts`) command. Alpha.",
+  "license": "MIT",
+  "author": "Alan Martinez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ederwii/tldr-experts.git"
+  },
+  "homepage": "https://github.com/ederwii/tldr-experts#readme",
+  "bugs": {
+    "url": "https://github.com/ederwii/tldr-experts/issues"
+  },
+  "keywords": [
+    "ai",
+    "workflow",
+    "claude-code",
+    "agentic",
+    "developer-experience",
+    "tldr",
+    "experts",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "tldrx": "dist/tldrx.js",
+    "tldr-experts": "dist/tldrx.js"
+  },
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "dist",
+    "env.yml",
+    "plugin",
+    "stages",
+    "templates",
+    "workflows"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "doctor": "bun bin/tldrx.ts doctor",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2",
+    "yaml": "^2.9.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
+  "name": "tldrx",
+  "description": "tldr-experts: a file-based AI development workflow. One loop, five phases, everything on disk. Alpha.",
+  "version": "0.3.0",
+  "author": {
+    "name": "Alan Martinez"
+  }
+}

package/plugin/README.md

@@ -0,0 +1,113 @@
+# tldrx — Claude Code plugin packaging
+
+Load it for development straight from this directory:
+
+```bash
+claude --plugin-dir ./plugin
+```
+
+Then type `/tldrx:tldrx`. (Plugin skills are always namespaced `/<plugin>:<skill>`.)
+
+## Or install it, and skip the flag
+
+`--plugin-dir` lasts one session and needs this checkout. For a project or a
+machine that should just have it:
+
+```bash
+tldrx install --claude          # ./.claude/   (this project; needs a git repo)
+tldrx install --claude --user   # ~/.claude/   (this machine)
+```
+
+That writes the same skill and the same six hooks into a real `.claude/`, plus the
+status line this plugin cannot install (see below). It is idempotent, it never
+touches `permissions`, and `--uninstall` takes exactly it back out. The README's
+[Claude Code integration](../README.md#claude-code-integration) section has the
+settings fragment it writes.
+
+**The two wirings differ in one thing only: how a hook is named.** The plugin
+spawns `bun ${CLAUDE_PLUGIN_ROOT}/../src/hooks/<name>.ts`, and it keeps doing that
+on purpose — a plugin must work for someone who cloned the repo and installed
+nothing, so it cannot depend on a global `tldrx`. The installed `settings.json`
+uses `tldrx hook <name>` instead, because that file gets committed and cloned onto
+a machine whose checkout is somewhere else, where an absolute path is simply wrong.
+Same scripts, same matchers, same timeouts, same decisions.
+
+## What is wired
+
+| Path | What it is |
+|---|---|
+| `.claude-plugin/plugin.json` | Manifest: `name`, `description`, `version`, `author`. |
+| `skills/tldrx/SKILL.md` | The facilitator. `disable-model-invocation: true` — only you can invoke it, and its body costs nothing until you do. |
+| `hooks/hooks.json` | Eight handlers over six hook scripts on four events. **All live** — see the table below. |
+| `agents/` | Deliberately empty — experts are generated per project. |
+
+## The hooks
+
+| Script | Event(s) | Matcher | What it does |
+|---|---|---|---|
+| `claim-sources.ts` | PreToolUse, PostToolUse | `Write\|Edit` | Computes the **would-be** content (Write: `content`; Edit: `old_string`→`new_string` applied to the file on disk) and, when it is a handoff under `tldrx-work/`, denies unless every `- ` bullet under Findings / Decisions / Unknowns / Evidence ledger ends with a resolvable `[src: …]` token (spec §2.8). On PostToolUse the same check can only report, so it emits `additionalContext`. |
+| `no-reask.ts` | PreToolUse | `Write\|Edit` | On `questions.md`: for each question the file does not already carry, denies when a non-retired `facts.yml` row in the same `area` scores Jaccard ≥ 0.6 over ≥4-char tokens, and names the fact. |
+| `answer-capture.ts` | PostToolUse, FileChanged | `Write\|Edit` / none | For every block that is `status: open` with a non-empty `[Answer]:`, writes the answer footer, appends a `facts.yml` row (`kind: answer`, `source.q`) plus `question.answered` and `fact.added` events, and echoes `tldrx: recorded Q4 → F020`. Never blocks. |
+| `dod-gate.ts` | PreToolUse | `Write\|Edit` | On a `stories/*.md` write that sets `status: done`: re-runs every command in the story's fenced ```` ```dod ```` block from the repo named by `repo:` (resolved through `workspace.yml`), each within `timeout_s` (default 900). Denies unless all exit 0, or if the block is missing. |
+| `budget-gate.ts` | PreToolUse | `Bash` | On a command matching `^(claude -p\|tldrx next)`: resolves the run (`--run`, the cwd, or the newest non-terminal `run.yml`), and denies when the cursor phase cannot afford the stage's `budget_usd` and `on_exceed: block`. Appends `budget.blocked`. |
+| `session-start.ts` | SessionStart | none | Up to three lines of "where we are" via `additionalContext`. Silent when there is no non-terminal run. |
+
+**Two rules the whole set obeys.** Only PreToolUse can block, and it blocks by
+printing `{"hookSpecificOutput": {"hookEventName": "PreToolUse",
+"permissionDecision": "deny", "permissionDecisionReason": "…"}}` and exiting `0` —
+an exit code never denies here. And every hook except `dod-gate` fails **open**: an
+internal error exits `0` and writes one line to stderr
+(`tldrx hook <name>: internal error, allowing — …`). `dod-gate` fails **closed**
+once it has identified the write as a story being marked done, because an unproven
+story must stay not-done.
+
+The `matcher` on the `FileChanged` entry is deliberately omitted: matcher support
+for that event is not in the verified docs, so the script filters on the path
+itself. The `budget-gate` matcher is `Bash`, not `Task` — the money is spent by a
+shell command whose estimate is in `tool_input.command`, and nothing in the
+verified docs says a subagent spawn arrives with a budget to check.
+
+Shapes were copied from the official docs, with the source URL recorded next to
+each one:
+
+- https://code.claude.com/docs/en/plugins.md
+- https://code.claude.com/docs/en/hooks.md
+- https://code.claude.com/docs/en/skills.md
+- https://code.claude.com/docs/en/statusline.md
+
+## The status line is not a hook
+
+`statusLine` is a **settings key**, not a hook event, and a plugin's own
+`settings.json` supports only `agent` and `subagentStatusLine` — so the plugin
+cannot install it for you. `tldrx install --claude` can, because it writes the real
+settings file; it puts in `{"type": "command", "command": "tldrx statusline"}`, and
+leaves any status line that is not tldrx's alone. If you are loading the plugin
+instead, add this to your `~/.claude/settings.json` or the project's
+`.claude/settings.json` yourself:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun /absolute/path/to/tldr-experts/src/hooks/statusline.ts",
+    "padding": 2
+  }
+}
+```
+
+It renders `[tldrx] <model> ctx:<n>% $<cost>` from the fields Claude Code already
+measures, and `[tldrx] no session data` when they are absent. The richer line from
+the concept doc (run id, phase, progress bar, budget ceiling) needs `run.yml`,
+which v0 does not write yet — so it is not rendered rather than faked.
+
+## Known `claude plugin validate` warnings
+
+`claude plugin validate ./plugin` exits 0 with two warnings. Both are deliberate:
+
+1. **`$doc: Unknown field '$doc'`** — JSON has no comments, and this repo's rule is
+   that every Claude Code shape carries its source URL beside it. The validator
+   itself confirms the field is *ignored at load time*, so it costs nothing.
+2. **`agents/README.md: No frontmatter block found`** — the directory holds
+   documentation, not an agent. Adding frontmatter would register a fake agent
+   named `README`, which is worse than a warning. Experts are generated per project
+   by `tldrx init`; nothing belongs here.

package/plugin/agents/README.md

@@ -0,0 +1,22 @@
+# Agents
+
+**Nothing ships here.**
+
+Experts in tldr-experts are *generated per project* by `tldrx init` (concept §4.5):
+one stack expertise per language/framework detected, one domain expert per detected
+domain. They are written to the project's `.tldrx/experts/<name>/` as a pair of
+files:
+
+```
+.tldrx/experts/<name>/
+  expert.md          role, domain, how to reason, what to cite
+  competencies.yml   {area, level 0-5, evidence: [...], last_trained}
+  knowledge/*.md     trained material, with file:line provenance (v1.1)
+```
+
+A shipped `agents/*.md` here would be the opposite of that: a fixed cast of
+personas that knows nothing about your code. If a stage needs a persona, it names
+it in `stage.yml` and the facilitator loads the generated file.
+
+See `templates/expert.md` and `templates/competencies.yml` for the shapes
+`tldrx init` will write.

package/plugin/hooks/hooks.json

@@ -0,0 +1,107 @@
+{
+  "description": "tldrx v0 hooks — LIVE. Shape verified from https://code.claude.com/docs/en/hooks.md: top-level `hooks` map keyed by event name, each entry { matcher?, hooks: [ { type, command, args?, timeout? } ] }. Exec form (`command` + `args`) and ${CLAUDE_PLUGIN_ROOT} are from that page. Only PreToolUse can deny, and it denies by printing {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"…\"}} and exiting 0 — never by an exit code. Every hook but DoD-gate fails OPEN. NOTE: the status line is NOT a hook event — it is the `statusLine` settings key, and a plugin settings.json only supports `agent` and `subagentStatusLine`. Wire it yourself; see plugin/README.md.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "_note": "claim-sources (spec §4) — the gate. Denies a handoff under tldrx-work/ whose Findings/Decisions/Unknowns/Evidence-ledger bullets do not each end with a resolvable [src: …] token.",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/claim-sources.ts"],
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "_note": "no-re-ask (spec §4, concept §1.2) — denies a NEW open question in tldrx-work/**/questions.md whose subject already has a non-retired facts.yml row (Jaccard >= 0.6 on >=4-char tokens, same area).",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/no-reask.ts"],
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "_note": "DoD-gate (spec §4, concept §8) — re-runs every command in a story's fenced ```dod block, in its repo, and denies unless each exits 0. This hook is not <50 ms by design, and it is the one hook that fails CLOSED.",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/dod-gate.ts"],
+            "timeout": 960
+          }
+        ]
+      },
+      {
+        "_note": "budget-gate (spec §4) — matcher is Bash, because the money is spent by `claude -p …` / `tldrx next`, which is a Bash command with the estimate in tool_input.command. The earlier `Task` matcher was a guess and is dropped: nothing in the verified docs says a subagent spawn arrives here with a budget to check.",
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/budget-gate.ts"],
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "_note": "answer-capture (spec §2.7/§4) — writes the answer footer, the facts.yml row and the question.answered event for every block that is `status: open` with a non-empty [Answer]:. Never blocks; echoes one line of additionalContext.",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/answer-capture.ts"],
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "_note": "claim-sources twin (spec §4: 'a PostToolUse twin re-checks and feeds back only'). Same script, same checks; on PostToolUse it can only report, so it emits additionalContext instead of a denial.",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/claim-sources.ts"],
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "FileChanged": [
+      {
+        "_note": "answer-capture again — a human editing questions.md in an editor never goes through Write/Edit. Matcher omitted: FileChanged's matcher support is not in the verified docs, so the script filters on the path itself.",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/answer-capture.ts"],
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "_note": "session-start (concept §3) — up to three lines of 'where we are' from the newest non-terminal run.yml, injected as additionalContext. Matcher omitted so it fires for every start reason (startup, resume, clear, compact, fork).",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/../src/hooks/session-start.ts"],
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/skills/tldrx/SKILL.md

@@ -0,0 +1,170 @@
+---
+# Fields verified from https://code.claude.com/docs/en/skills.md (§ "Frontmatter
+# reference"). `disable-model-invocation: true` means ONLY the user can invoke this
+# skill: its body stays out of context until someone types /tldrx — concept §1.3's
+# non-intrusive requirement, satisfied natively.
+name: tldrx
+description: The tldr-experts facilitator. Finds what is pending in this workspace and walks the human through it one item at a time, reading and writing files only. Invoke with /tldrx.
+disable-model-invocation: true
+argument-hint: "[optional: which item, or what you want to work on]"
+---
+
+# tldrx — status, then guide
+
+**Alpha.** Every command is implemented. `tldrx --help` is the authoritative
+surface — read it before you promise anything, and never narrate progress a tool
+did not make.
+
+## What you are
+
+A facilitator, not an author. You read files, hand ONE sub-agent ONE task, write
+the result back, and stop at the gate. You hold no state between steps — the files
+are the state. You do not decide anything that is the human's to decide.
+
+## Step 1, always
+
+```
+tldrx status --json
+```
+
+It is free, deterministic, and exits 0 whatever it finds (exit 3 only means there
+is no `.tldrx/` here — then the answer is `tldrx init`). It returns
+`{root, pending, items[], advice[]}`, each item `{kind, summary, command, details}`,
+already in the order the items block each other. `items` are the BLOCKERS and all
+`pending` counts; `advice` blocks nothing — relay it once, briefly. **That list is
+the agenda.** Do not ask "what would you like to do?" first.
+
+Then take item 1. One item at a time, in order. Say in one plain sentence what it
+is and why it matters — no jargon a first-time user would not have — then either
+ask or act, per the rule below. **After each item, re-run `tldrx status`**: acting
+on one item changes the list.
+
+## Ask, or act
+
+**The human decides** — you present, quote the relevant file section, and ASK.
+Never answer on their behalf, never pick a default, never "assume yes":
+
+- `init-questions` — facts about their project nobody could detect. Run
+  `tldrx interview --init` and relay each question. Piped stdin is ONE LINE PER
+  QUESTION in file order; a single letter `A`–`E` picks that option, other text is
+  recorded verbatim, an empty line or `s` skips, `q` stops. **Never pass
+  `--yes-to-defaults`** — it answers every question with its first option.
+- `seed-split` — a proposal that creates nothing until someone applies it. Show
+  `split.md`, the unanswered questions, and the seed documents still marked
+  `proposed`. Record decisions with `tldrx seed answer <split.yml> <Qid> "<text>"`;
+  edit `split.yml` if they want different runs.
+- a gate, an answer, or any ADR/decision document — quote it and ask.
+- a gate `tldrx status` reports as signed `by: auto` that they disagree with. It signs
+  only when its five conditions hold and cannot judge whether a decision was RIGHT: quote
+  the note — it carries all five measured values — and ask before revoking.
+
+**You act** once they have said what they want — these are mechanical:
+
+- `tldrx seed apply <split.yml> --dry-run`, then the real apply when they say so.
+- `tldrx answer <Qid> "<what they said>" --run <id>` · `tldrx approve --run <id>`
+  after they said yes · `tldrx reject --run <id> --note "<their reason>"`, and
+  `tldrx reject --run <id> --stage <phase>/<stage> --note "…"` to take back an
+  approval already given (including one the harness signed `by: auto`).
+- `tldrx questions lint --run <id>` when a stage wrote a `questions.md`: it exits 2
+  if any block is invisible to the parser, and `--fix` converts it without changing
+  a word. An unreadable file reads as "no questions" to everything downstream.
+- one stage of a run, via the in-session recipe below.
+- `tldrx expert train <name> --area <a> --mode <light|full> --print-prompt` — the
+  printed prompt costs nothing; running it is a spend, so see Money. The `expert`
+  entry arrives in `advice`, not `items`, and its `command` is always
+  `tldrx expert list`: it degrades a stage, it never blocks one. Its `details` name
+  the trainable experts and, separately, any role expert that has no past run to
+  mine — that one is not a task yet. Mention it once and carry on with `items`.
+
+## When nothing is pending
+
+`pending: 0` means open work — and what the work IS is the human's decision, not a
+lookup. Offer `tldrx run new <slug> --scope <s> [--seed <path>] [--budget <usd>]`,
+where `<s>` is a file stem in `.tldrx/workflows/` or the shipped `workflows/`:
+`feature` `bugfix` `hotfix` `refactor` `docs` `spike` `prototype` `migration`
+`integration` `performance` `security-patch` `upgrade` `retro`. If `run new --seed`
+prints `note: seed is N files / ~T tokens …` on stderr, relay it and offer
+`tldrx seed triage <path>` (free, spawns nothing): one run carrying that much seed
+pays for it at every stage.
+
+## Running one stage of a run
+
+```
+1  tldrx next --prepare [<run>]        # writes the prompt bundle; exits 0 and stops
+2  dispatch ONE sub-agent              # Agent tool, prompt = .agent/<stage>/prompt.md
+3  write .agent/<stage>/result.json    # {outputs, questions_asked, notes}
+4  tldrx next --commit [<run>] --cost-usd <n>   # validates outputs + checks, rolls up cost, gates
+```
+
+Step 1 names the bundle, the writable files and the finishing command. Step 2:
+pass `prompt.md` to the Agent tool **unedited** — it already inlines the stage
+body, the experts and every declared input — and tell the sub-agent to write ONLY
+the files `pending.json` lists, read nothing else, and end every bullet under
+Findings / Decisions / Unknowns / Evidence ledger with a `[src: …]` token. Step 4
+re-reads every output off disk and re-runs the checks whatever step 3 claimed.
+Pass `--cost-usd <n>` on step 4 when you know what the sub-agent cost: an in-session
+turn has no meter of its own, and without a declared number the task is recorded as
+`cost_usd: null, metered: false` — honest, but it makes the run's `spent` a lower
+bound rather than a total. Never guess one; omitting it is the correct move when you
+do not know.
+
+**One stage per `/tldrx` call.** When a run's remaining gates are mostly `auto`
+(`run.yml` `gates_policy:`) and nobody needs to watch, say so and offer
+`tldrx run auto <id>` — the headless loop. It spawns its own sessions, so suggest
+it for a terminal, never run it from inside this one.
+
+| exit | meaning | what you do |
+|---|---|---|
+| 0 | done, cursor advanced | `tldrx status` again |
+| 2 | refused — budget, a held lock, an uncommitted `--prepare` bundle, or you left off the run id | report it; do not retry blindly. A lock whose pid is dead clears with `tldrx run unlock <id>`; a run they have given up on closes with `tldrx run cancel <id> --note "<their reason>"` — both need their say-so first |
+| 3 | not found | `tldrx status` says what exists instead |
+| 4 | a human is needed | `tldrx approve` (gate) or `tldrx answer <Qid> "…"` (question) |
+| 5 | the stage failed | report the reason verbatim; the cost is spent, not refunded. If it names an unreadable `questions.md`, `tldrx questions lint --fix --run <id>` converts it without changing a word, then `--commit` again |
+
+**Several runs open**: every run-targeting command refuses with exit 2 rather than
+guessing, and lists the candidates. That means "you forgot the id", not "something
+broke" — pass it. `tldrx status` and `tldrx run status` always show all of them.
+
+## Money
+
+Before anything that spends: **state the ceiling and ask.** `tldrx next`,
+`tldrx run auto`, `tldrx expert train` (without `--print-prompt`) and
+`tldrx seed triage --propose` (`--max-usd 1.00` by default) all cost real money;
+`seed triage` without `--propose` is free. Never raise `--max-usd` or run
+`tldrx budget raise` for them — a stage that costs more than remains exits 2 and
+names the exact command; report it and let them decide.
+
+Three free read-only commands answer what it will cost and what it did: `tldrx run
+estimate` (the only one that guesses, and says so), `tldrx cost [--all]` (per attempt —
+retries are where the money is) and `tldrx budget show`. Quote them, never the arithmetic;
+`cost` reports an in-session turn as UNMETERED unless step 4 declared `--cost-usd`.
+
+## Rules you do not get to bend
+
+1. **Never hand-edit `run.yml` or `events.jsonl`.** The tools own them; the log is
+   append-only. Want a state change? Run the command that owns it.
+2. **Never answer a question on the human's behalf.** An invented answer poisons
+   `facts.yml` permanently — every future run will cite it.
+3. **Every claim carries a source**: `[src: path:line]`, `[src: <url>]`,
+   `[src: Q<n>]`, `[src: F<n>]`. Unsourced goes in Unknowns and becomes a question.
+4. **Never ask what is already known.** Grep `.tldrx/memory/facts.yml` first.
+5. **Verify from the source, not from your own output.** After a write, re-read it
+   from disk. A sub-agent reporting "ok" is not evidence.
+6. **Say which you are in: measured, inferred, or assumed.** Never blur them.
+7. **Stop at gates.** You never close one — not even an `auto` gate, which the
+   framework closes itself and only when all five of its conditions hold.
+8. **A checked section holds at least one item.** Nothing to report is still an
+   item: `- none [src: absent:<what you looked at>]`. Prose is refused.
+9. **`.tldrx/` and `tldrx-work/` are committed** — the files ARE the state. `init`
+   gitignores only the machine-local scratch (`graphify-out/`, `cache/`,
+   `worktrees/`, `tldrx-work/*/.lock`, `tldrx-work/*/.agent/`).
+
+## The loop, for orientation
+
+Every stage is the same four steps: **Investigate** (read code, docs and memory;
+findings carry sources) → **Handoff** (one `.md`: found, decided, still unknown) →
+**Interview** (only the unknowns become questions; answers land in `facts.yml`) →
+**Gate** (a human approves; recorded in `run.yml` + `events.jsonl`). The five
+phases — **what · how · plan · build · watch** — are that loop with different
+inputs, outputs and experts: `.tldrx/stages/<slug>/stage.yml` declares which,
+`.tldrx/workflows/<scope>.yml` declares the order.

package/stages/build/stage.md

@@ -0,0 +1,70 @@
+<!-- schema: draft -->
+<!-- Stage template: build (phase 4). -->
+<!--
+  READ THIS FIRST: unlike every other stage, this file is NOT the prompt.
+
+  `04-build` is run by the wave executor (spec §5, "Build executor"), which builds
+  its own per-story developer prompt and per-story reviewer prompt from the Plan
+  artefacts, and writes `04-build/handoff.md` itself. Editing this file changes the
+  documentation of the phase, not what the sub-agents are told. The prompts live in
+  `src/core/build/prompts.ts`; the pipeline lives in
+  `src/core/facilitator/executors/build.ts`.
+-->
+
+# Build — what the phase does
+
+## Role
+
+The facilitator is the contractor here, not an author. It hands each story to a
+developer sub-agent, proves the result, and merges it — and it writes the handoff
+from what it measured rather than asking anyone to summarise it.
+
+## Objective
+
+Turn `03-plan/waves.yml` into merged code on epic branches, one story at a time,
+in wave order. Done-when: every scheduled story is `done` (DoD green, reviewer
+approved, evidence written into its front matter) or `blocked` with a reason a
+human can act on, and every epic branch is left ready to merge **by hand**.
+
+## Inputs
+
+`03-plan/waves.yml`, `03-plan/stories/<id>.md`, `03-plan/epics/<id>.md`, the
+workspace conventions, and — per story — the content of every path its `touches`
+list names, read from that story's own worktree.
+
+## Investigate
+
+Per story, in `waves.yml` order:
+
+1. resolve the story's repo from `workspace.yml`, and refuse the whole phase if
+   that repo's tree is dirty;
+2. ensure `epic/<slug>` exists, cut from the repo's `default_branch`;
+3. open a worktree at `.tldrx/worktrees/<repo>/<story-id>` on `story/<id>`;
+4. spawn ONE developer sub-agent with cwd = that worktree.
+
+## Produce
+
+- `04-build/log/<story-id>.md` — the review log, one per story touched
+- `04-build/handoff.md` — Findings per story, Evidence ledger of dod commands
+- `03-plan/stories/<id>.md` — `status:` and `evidence:` written back
+- `epic/<slug>` branches, merged from `story/<id>`, **never pushed**
+
+## Rules
+
+- Done means proven: the ```dod block is re-run by the facilitator, in the story's
+  worktree, and every command must exit 0. A sub-agent's own "it works" is not
+  evidence and is never recorded as any.
+- A reviewer's `changes` requeues the story ONCE, with the review under
+  `## Previous attempt`. A second `changes` blocks it.
+- A DoD failure or a merge conflict blocks that story only — the wave carries on.
+- Nothing pushes. No epic is merged into a default branch.
+
+## Questions
+
+None. The Interview happened in What and How; a story that still needs a human
+answer is a Plan bug, and it surfaces here as `blocked`.
+
+## Stop
+
+At the gate. `tldrx approve` after merging the epic branches, or
+`tldrx reject --note "…"` to send the phase back.