tldr-experts 0.3.0

package/stages/build/stage.yml

@@ -0,0 +1,54 @@
+# schema: draft
+# Phase 4 of the loop. Concept §3 and §9; spec §5 "Build executor".
+#
+# This stage is NOT run by the default one-stage-one-agent path. `04-build` selects
+# the wave executor (src/core/facilitator/executors/build.ts), which reads
+# 03-plan/{waves.yml,stories/*.md,epics/*.md} and, story by story in wave order,
+# cuts the branch, opens the worktree, spawns ONE developer sub-agent in it, re-runs
+# the story's ```dod block, commits, merges into the epic branch, and spawns a
+# read-only reviewer. A story is `done` only when the DoD exited 0 and the reviewer
+# approved; its evidence is written back into the story's own front matter.
+#
+# `budget_usd` below is the WHOLE phase: the executor splits it by story count and
+# caps each share at budget.yml's `per_agent_max_usd`.
+name: build
+title: Build
+phase: 4
+model: sonnet
+# --effort for this stage's sub-agent (spec §2.3). The cost lever
+# `--max-budget-usd` is not: the budget flag only STOPS a turn already in flight.
+# `[assumption]` — Build writes code that a DoD and a reviewer will judge. A cheap
+# turn here is not a saving: it is a `changes` verdict and a second, paid attempt.
+effort: high
+budget_usd: 9
+timeout_s: 1800
+# Branches and commits are not revertible by a flag, so a dry run is refused
+# rather than half-honoured (spec §5, Build executor).
+dry_run_allowed: false
+
+inputs:
+  - "03-plan/waves.yml"
+  - ".tldrx/conventions/shared.md"
+  - ".tldrx/memory/facts.yml"
+
+# The handoff is written by the executor, deterministically, from exit codes and
+# merge results it holds — no sub-agent is asked to summarise what it already knows.
+# `04-build/log/<story-id>.md` is written per story and cited by every Finding.
+outputs:
+  - {path: "04-build/handoff.md", sections: [Findings, Decisions, Unknowns, "Evidence ledger"]}
+
+experts:
+  - developer
+
+# `requires:` used to list five acceptance criteria here. Nothing read them:
+# `normaliseGate` (src/core/run/workflowPreset.ts:216-231) reads only `.type`,
+# `validateStage` (src/core/schemas/stage.ts:72-76) checks only `gate.type`, the
+# prompt ships `stage.md` and never this file (src/core/facilitator/prompt.ts:101),
+# and no other file in the repo touches the key. Criteria no gate enforces and no
+# reader ever sees are worse than none — the enforcement that IS real is the
+# `checks:` list below.
+gate:
+  type: human-approval
+
+checks:
+  - claim-sources

package/stages/how/stage.md

@@ -0,0 +1,89 @@
+<!-- schema: draft -->
+<!-- Stage template: how (phase 2). Rendered into <record>/02-how/handoff.md. -->
+
+# How — handoff
+
+**Run:** `<run-id>` · **Stage:** `how` · **Expert(s):** `<from stage.yml>` · **Model:** `<from stage.yml>`
+**Spent:** `$<n>` of `$<budget_usd>`
+
+> Place the design on real files and modules from the code map. A component that does not cite an existing path is a wish, not a design.
+
+---
+
+## Findings
+
+> What Investigate actually established. **Every bullet ends with a source.**
+> `[src: path/to/file.ts:42]` · `[src: https://…]` · `[src: Q7]`
+> A bullet you cannot source does not belong here — move it to Unknowns.
+
+- The change lands in <module>, which today does <…>. `[src: …]`
+- The external API behaves as <…> per its official docs, fetched this run. `[src: …]`
+
+## Decisions
+
+> What was decided, and on the strength of what. Same rule: every bullet is sourced.
+> Label each one **measured** (it was run), **inferred** (mechanism plus evidence,
+> could be wrong) or **assumed** (nobody knows yet).
+
+- Approach <A> over <B>, because <…>. `[src: …]`
+
+## Unknowns
+
+> Only these become questions. Before writing one, grep `.tldrx/memory/facts.yml`:
+> re-asking a recorded fact is a framework test failure, not a style choice.
+> Each unknown states who or what could answer it.
+
+- Whether <…> is load-bearing for <…> — no test covers it. — *could be answered by:* `<person | file | command | doc>`
+
+## Evidence ledger
+
+> Every source cited above, once, with what it proved. This is what the next stage
+> and the reviewer read instead of re-deriving the work. **List items, not a table**
+> — this section is checked exactly like the other three, and a table holds no
+> list items for the gate to check.
+
+- … what this file establishes … `[src: <repo>:<path>:<line>]`
+- … what this command proved … `[src: $ <command> → exit 0]`
+
+## Outputs written
+
+- `design.md`
+- `contracts.md` (APIs / DTOs / events)
+- `risks.md`
+- `test-strategy.md`
+
+## Gate
+
+Blocked on: **<human approval | checks green>** — `stage.yml`'s `gate.type`. What is
+actually enforced is that file's `checks:` list, which `tldrx approve` re-runs against what
+is on disk before it will advance anything. Nothing advances until this is recorded in
+`run.yml` and `events.jsonl`.
+
+## Rules
+
+- Every bullet under Findings / Decisions / Unknowns / Evidence ledger is ONE line and ENDS with a source token. A bullet without one is refused by the `claim-sources` gate and the whole stage fails.
+- Each of Findings / Decisions / Unknowns / Evidence ledger must hold at least ONE list item; a section that is genuinely empty is written as `- none [src: absent:<what you looked at>]`, and a prose-only section is refused by the `claim-sources` gate.
+- Source token grammar (exact): `[src: <one or more sources separated by "; ">]` where a source is ONE of:
+  - `<repo>:<path>:<line>` or `<repo>:<path>:<start>-<end>` — a file with ONE line or ONE range. Never a whole file, never a comma list (`file.md:7,21` is invalid: write two sources or a range).
+  - `F<n>` — a fact id from `.tldrx/memory/facts.yml` (cite the id, never the file).
+  - `Q<n>` — a question from this run's questions.md.
+  - `https://…` — an external document (https only).
+  - `aidlc:<file>:<line>` / `aidlc:<file>#Q<n>` — an imported source, exactly as it already appears in intent.md/scope.md.
+  - `$ <command> → exit <n>` — only under Evidence ledger, only for commands listed in `.tldrx/workspace.yml`.
+  - `absent:<path>` — you looked there and found nothing.
+- Do not cite templates, expert files or directories (`.tldrx/experts/*` is not evidence).
+- Questions go in `questions.md`, and its shape is a PARSER's, not a style. One regex reads a block — `^## (Q\d+) · (.+)$` — and a heading that misses it is not half-read, it is read as ABSENT: the gate then records "0 open questions" and signs itself over questions nobody answered. Write each one EXACTLY like this, `·` being U+00B7 MIDDLE DOT:
+  ```
+  ## Q1 · Where does leaderboard state live?
+  <!-- id: Q1 | status: open | area: data-model | asked_by: architect | asked_at: 2026-08-29T14:02:11Z -->
+  Why asked: no ranking store exists in the map [src: absent:.tldrx/map/api/domains.md]
+
+  - A) New Postgres table, recomputed on hunt completion
+  - B) Redis sorted set
+  - C) other — write it below
+
+  [Answer]:
+  ```
+  All five metadata keys are required; `Why asked:` must END with a `[src: …]` token; 2–5 options lettered A–E in order; exactly one empty `[Answer]:` slot. Ids ascend. Never write `### Qn — …`, `**Answer:**`, or the answered footer — the hook writes that. `tldrx questions lint` checks the file; `--fix` converts a file already written the wrong way.
+- Before asking a question, grep `.tldrx/memory/facts.yml`; if the answer is there, cite `F<n>` instead of asking.
+- Write only the declared outputs; do not add sections beyond the ones listed under Produce.

package/stages/how/stage.yml

@@ -0,0 +1,53 @@
+# schema: draft
+# Phase 2 of the loop. Concept §3.
+# Design must be placed on REAL files and modules from the code map — not on
+# hypothetical components.
+name: how
+title: How
+phase: 2
+model: opus
+# --effort for this stage's sub-agent (spec §2.3). The cost lever
+# `--max-budget-usd` is not: the budget flag only STOPS a turn already in flight.
+# `[assumption]` — How is where the thinking is. Every component must land on a
+# real path and every contract must survive contact with the code, so this is the
+# one stage where effort is bought deliberately rather than saved.
+effort: high
+budget_usd: 6
+
+inputs:
+  - "01-what/intent.md"
+  - "01-what/scope.md"
+  - "01-what/success-metrics.md"
+  - ".tldrx/map/architecture.md"
+  - ".tldrx/map/conventions.md"
+  - ".tldrx/memory/facts.yml"
+
+outputs:
+  - "design.md"
+  - "contracts.md"
+  - "risks.md"
+  - "test-strategy.md"
+  - "handoff.md"
+  - "questions.md"
+
+# `domain` and `stack` used to be listed here. They were never expert NAMES:
+# `stack_experts: true` above already loads `<lang>-stack` for the run's repos,
+# and a `kind: domain` expert is picked by the paths this run actually cites
+# (spec §2.3, rules 2 and 3). A name nothing can create is a permanent
+# "NOT LOADED" line, so the rules are left to do their own work.
+experts:
+  - architect
+
+# `requires:` used to list three acceptance criteria here. Nothing read them:
+# `normaliseGate` (src/core/run/workflowPreset.ts:216-231) reads only `.type`,
+# `validateStage` (src/core/schemas/stage.ts:72-76) checks only `gate.type`, and
+# no other file in the repo touches the key. Three sentences a reviewer would
+# have to open this file to find, that no gate ever enforced, are worse than
+# none — the enforcement that IS real is the `checks:` list below.
+gate:
+  type: human-approval
+
+checks:
+  - claim-sources
+  - no-reask
+  - budget-gate

package/stages/plan/stage.md

@@ -0,0 +1,89 @@
+<!-- schema: draft -->
+<!-- Stage template: plan (phase 3). Rendered into <record>/03-plan/handoff.md. -->
+
+# Plan — handoff
+
+**Run:** `<run-id>` · **Stage:** `plan` · **Expert(s):** `<from stage.yml>` · **Model:** `<from stage.yml>`
+**Spent:** `$<n>` of `$<budget_usd>`
+
+> Cut the design into stories somebody could pick up cold, ordered by dependency, priced against the budget, and shaped the way this team actually works.
+
+---
+
+## Findings
+
+> What Investigate actually established. **Every bullet ends with a source.**
+> `[src: path/to/file.ts:42]` · `[src: https://…]` · `[src: Q7]`
+> A bullet you cannot source does not belong here — move it to Unknowns.
+
+- Story <id> touches <files>, and its acceptance criteria are testable by <…>. `[src: …]`
+- Stories <a> and <b> are independent and can run in the same wave. `[src: …]`
+
+## Decisions
+
+> What was decided, and on the strength of what. Same rule: every bullet is sourced.
+> Label each one **measured** (it was run), **inferred** (mechanism plus evidence,
+> could be wrong) or **assumed** (nobody knows yet).
+
+- Wave ordering is <…>, because <b> needs <a>'s contract. `[src: …]`
+
+## Unknowns
+
+> Only these become questions. Before writing one, grep `.tldrx/memory/facts.yml`:
+> re-asking a recorded fact is a framework test failure, not a style choice.
+> Each unknown states who or what could answer it.
+
+- Whether <…> can ship behind a flag or needs a migration first. — *could be answered by:* `<person | file | command | doc>`
+
+## Evidence ledger
+
+> Every source cited above, once, with what it proved. This is what the next stage
+> and the reviewer read instead of re-deriving the work. **List items, not a table**
+> — this section is checked exactly like the other three, and a table holds no
+> list items for the gate to check.
+
+- … what this file establishes … `[src: <repo>:<path>:<line>]`
+- … what this command proved … `[src: $ <command> → exit 0]`
+
+## Outputs written
+
+- `epics/<epic>.md`
+- `stories/<id>.md` (AC + test plan + touched files + repo)
+- `waves.yml`
+- `budget.yml`
+
+## Gate
+
+Blocked on: **<human approval | checks green>** — `stage.yml`'s `gate.type`. What is
+actually enforced is that file's `checks:` list, which `tldrx approve` re-runs against what
+is on disk before it will advance anything. Nothing advances until this is recorded in
+`run.yml` and `events.jsonl`.
+
+## Rules
+
+- Every bullet under Findings / Decisions / Unknowns / Evidence ledger is ONE line and ENDS with a source token. A bullet without one is refused by the `claim-sources` gate and the whole stage fails.
+- Each of Findings / Decisions / Unknowns / Evidence ledger must hold at least ONE list item; a section that is genuinely empty is written as `- none [src: absent:<what you looked at>]`, and a prose-only section is refused by the `claim-sources` gate.
+- Source token grammar (exact): `[src: <one or more sources separated by "; ">]` where a source is ONE of:
+  - `<repo>:<path>:<line>` or `<repo>:<path>:<start>-<end>` — a file with ONE line or ONE range. Never a whole file, never a comma list (`file.md:7,21` is invalid: write two sources or a range).
+  - `F<n>` — a fact id from `.tldrx/memory/facts.yml` (cite the id, never the file).
+  - `Q<n>` — a question from this run's questions.md.
+  - `https://…` — an external document (https only).
+  - `aidlc:<file>:<line>` / `aidlc:<file>#Q<n>` — an imported source, exactly as it already appears in intent.md/scope.md.
+  - `$ <command> → exit <n>` — only under Evidence ledger, only for commands listed in `.tldrx/workspace.yml`.
+  - `absent:<path>` — you looked there and found nothing.
+- Do not cite templates, expert files or directories (`.tldrx/experts/*` is not evidence).
+- Questions go in `questions.md`, and its shape is a PARSER's, not a style. One regex reads a block — `^## (Q\d+) · (.+)$` — and a heading that misses it is not half-read, it is read as ABSENT: the gate then records "0 open questions" and signs itself over questions nobody answered. Write each one EXACTLY like this, `·` being U+00B7 MIDDLE DOT:
+  ```
+  ## Q1 · Where does leaderboard state live?
+  <!-- id: Q1 | status: open | area: data-model | asked_by: architect | asked_at: 2026-08-29T14:02:11Z -->
+  Why asked: no ranking store exists in the map [src: absent:.tldrx/map/api/domains.md]
+
+  - A) New Postgres table, recomputed on hunt completion
+  - B) Redis sorted set
+  - C) other — write it below
+
+  [Answer]:
+  ```
+  All five metadata keys are required; `Why asked:` must END with a `[src: …]` token; 2–5 options lettered A–E in order; exactly one empty `[Answer]:` slot. Ids ascend. Never write `### Qn — …`, `**Answer:**`, or the answered footer — the hook writes that. `tldrx questions lint` checks the file; `--fix` converts a file already written the wrong way.
+- Before asking a question, grep `.tldrx/memory/facts.yml`; if the answer is there, cite `F<n>` instead of asking.
+- Write only the declared outputs; do not add sections beyond the ones listed under Produce.

package/stages/plan/stage.yml

@@ -0,0 +1,48 @@
+# schema: draft
+# Phase 3 of the loop. Concept §3 and §9.
+# Renders into the team's shape: sprints for scrum, a WIP-limited flow board for
+# kanban, a plain ordered list for none. Read .tldrx/process.yml, never assume.
+name: plan
+title: Plan
+phase: 3
+model: sonnet
+# --effort for this stage's sub-agent (spec §2.3). The cost lever
+# `--max-budget-usd` is not: the budget flag only STOPS a turn already in flight.
+# `[assumption]` — Plan is decomposition against a design that already exists:
+# split, order, size, cite. Medium; the hard judgement was made upstream in How.
+effort: medium
+budget_usd: 4
+
+inputs:
+  - "02-how/design.md"
+  - "02-how/contracts.md"
+  - "02-how/test-strategy.md"
+  - ".tldrx/process.yml"
+  - ".tldrx/map/workspace.md"
+
+outputs:
+  - "epics/<epic>.md"
+  - "stories/<id>.md"
+  - "waves.yml"
+  - "budget.yml"
+  - "handoff.md"
+  - "questions.md"
+
+experts:
+  - delivery
+  - architect
+
+# `requires:` used to list four acceptance criteria here. Nothing read them:
+# `normaliseGate` (src/core/run/workflowPreset.ts:216-231) reads only `.type`,
+# `validateStage` (src/core/schemas/stage.ts:72-76) checks only `gate.type`, the
+# prompt ships `stage.md` and never this file (src/core/facilitator/prompt.ts:101),
+# and no other file in the repo touches the key. Criteria no gate enforces and no
+# reader ever sees are worse than none — the enforcement that IS real is the
+# `checks:` list below.
+gate:
+  type: human-approval
+
+checks:
+  - claim-sources
+  - plan
+  - budget-gate

package/stages/watch/stage.md

@@ -0,0 +1,85 @@
+<!-- Stage template: watch (phase 5). One sub-agent per shipped feature. -->
+
+# Watch — `{{run}}`
+
+## Role
+
+You are the operations expert for run `{{run}}`, repos `{{repos}}`. You have been
+on call. You know the difference between a dashboard someone built and a dashboard
+someone trusts, and you have been paged at 3am by an alert on a metric that was
+never emitted.
+
+## Objective
+
+Write ONE watcher card for ONE shipped feature, so that six months from now a
+person who has never seen this code can answer: **is it still working?**
+
+Done when the card exists, every item in its four checked sections carries a
+`[src: …]` token, and its Query block would run as pasted.
+
+## Feature
+
+(replaced by the facilitator)
+
+## Inputs
+
+(replaced by the facilitator)
+
+## Investigate
+
+1. Read the diff first. It is what actually landed; a story's `touches:` list was
+   written before the code existed and is an intention, not evidence.
+2. Find what the feature EMITS — a log line, a metric, a counter, an event, a row
+   written somewhere queryable. Cite it at `<repo>:<path>:<line>`.
+3. If it emits nothing, stop looking for a way to phrase it as though it does.
+   Write `absent:<what you looked at>` and say what to instrument. That is a
+   correct, useful answer and it is the answer this stage exists to be able to give.
+4. Take the baseline from the evidence you have — a number in the diff, a number in
+   a fact, a number a command printed. If nobody has measured it, say so under
+   **Looks broken when** as an assumption rather than inventing one under
+   **Healthy baseline**.
+5. Check the gotchas for this repo before writing the Query: a query that ignores a
+   known trap is a query that will mislead someone at 3am.
+
+## Produce
+
+The single file named under **Feature**, with the front matter given there and
+these H2 sections, in order:
+
+- `## Signal` — the log line / metric / event that proves it works.
+- `## Where` — the dashboard, log stream, table or console it is read in.
+- `## Healthy baseline` — a measured number, and when it was measured.
+- `## Looks broken when` — what the same signal looks like on the bad day.
+- `## Query` — one fenced block, copy-pasteable.
+- `## Sources` — each citation above, once, with what it establishes.
+
+## Rules
+
+- Every list item under Signal / Where / Healthy baseline / Looks broken when is ONE
+  line and ENDS with a `[src: …]` token. An item without one is refused.
+- Source grammar (exact): `[src: <one or more sources separated by "; ">]`, a source being
+  `<repo>:<path>:<line>` (or `:<start>-<end>`) · `F<n>` · `https://…` ·
+  `$ <command> → exit <n>` · `absent:<path>`. Never a whole file, never a comma list.
+- A section with genuinely nothing in it is written as `- none [src: absent:<what you looked at>]`,
+  never as prose.
+- Do not cite a file you were not given. If it is not inlined above, you have not read it.
+- Do not describe a signal you would add. The card records what the code emits today.
+
+Facts on record:
+
+{{facts}}
+
+Conventions:
+
+{{conventions}}
+
+## Questions
+
+None. This stage asks nothing: everything it needs is inlined above, and what is
+not there is an `absent:` source rather than a question. If the code emits nothing,
+the card saying so IS the finding.
+
+## Stop
+
+Write the one file. Do not write the handoff — the framework writes that from your
+card. Do not touch any other file. Budget: `${{budget_usd}}`.

package/stages/watch/stage.yml

@@ -0,0 +1,61 @@
+# schema: draft
+# Phase 5 of the loop. Concept §3 and §10; the card's schema is spec §2.16.
+#
+# Generated from what Build actually instrumented. If nothing was instrumented,
+# the watcher says so — an aspirational watcher is worse than no watcher.
+#
+# This stage is run by the WATCH EXECUTOR (src/core/facilitator/executors/watch.ts),
+# not by the default one-agent path: it spawns one sub-agent per shipped feature,
+# and how many features there are is a fact about the run rather than about the
+# stage. That is also why `watchers/<feature>.md` is NOT listed under `outputs:` —
+# a declared output is re-read from disk BY NAME (spec §5), and these have no name
+# until the pre-pass has grouped the done stories by epic. The executor validates
+# every card itself, with the same parser `claim-sources` uses, and stamps its
+# status: `verified` only when nothing under `## Signal` cites `absent:`.
+name: watch
+title: Watch
+phase: 5
+model: haiku
+# --effort for this stage's sub-agent (spec §2.3). The cost lever
+# `--max-budget-usd` is not: the budget flag only STOPS a turn already in flight.
+# `[assumption]` — Watch renders a card per shipped feature from evidence the
+# executor has already grouped and handed over. Low: it is a transcription job
+# with a validator behind it, not an analysis.
+effort: low
+budget_usd: 2
+timeout_s: 900
+
+# Read PER FEATURE by the executor rather than inlined wholesale: the done stories
+# of ONE epic, that epic's file, the read-only diff of its branch against the
+# repo's default branch, the `observability`/`deploy` facts, and the gotchas of the
+# repos it touched. One sub-agent never sees another feature's evidence.
+#
+# The draft array form on purpose (as in stages/what/stage.yml): the v0 skeleton
+# validator requires `inputs` to be an array, and a bare list is read as all
+# OPTIONAL — which is right here, since a run whose Plan produced nothing still has
+# a Watch stage to complete. `[assumption]`
+inputs:
+  - "03-plan/stories"
+  - "03-plan/epics"
+  - ".tldrx/map/{repo}/gotchas.md"
+  - ".tldrx/memory/facts.yml"
+
+outputs:
+  - {path: "handoff.md", sections: [Findings, Decisions, Unknowns, "Evidence ledger"]}
+
+experts:
+  - operations
+
+# `requires:` used to list four acceptance criteria here. Nothing read them:
+# `normaliseGate` (src/core/run/workflowPreset.ts:216-231) reads only `.type`,
+# `validateStage` (src/core/schemas/stage.ts:72-76) checks only `gate.type`, the
+# prompt ships `stage.md` and never this file (src/core/facilitator/prompt.ts:101),
+# and no other file in the repo touches the key. Criteria no gate enforces and no
+# reader ever sees are worse than none — the enforcement that IS real is the
+# `checks:` list below.
+gate:
+  type: human-approval
+
+checks:
+  - claim-sources
+  - budget-gate

package/stages/what/stage.md

@@ -0,0 +1,89 @@
+<!-- schema: draft -->
+<!-- Stage template: what (phase 1). Rendered into <record>/01-what/handoff.md. -->
+
+# What — handoff
+
+**Run:** `<run-id>` · **Stage:** `what` · **Expert(s):** `<from stage.yml>` · **Model:** `<from stage.yml>`
+**Spent:** `$<n>` of `$<budget_usd>`
+
+> Turn a phrase, a document or a ticket into a scope somebody can disagree with. Accepts a document as input: read it, extract the claims it actually makes, and ask only about the gaps.
+
+---
+
+## Findings
+
+> What Investigate actually established. **Every bullet ends with a source.**
+> `[src: path/to/file.ts:42]` · `[src: https://…]` · `[src: Q7]`
+> A bullet you cannot source does not belong here — move it to Unknowns.
+
+- The request is <…>, stated as <…> in the source document. `[src: …]`
+- The system today does <…> in this area. `[src: …]`
+
+## Decisions
+
+> What was decided, and on the strength of what. Same rule: every bullet is sourced.
+> Label each one **measured** (it was run), **inferred** (mechanism plus evidence,
+> could be wrong) or **assumed** (nobody knows yet).
+
+- In scope: <…>. Out of scope: <…>, because <…>. `[src: …]`
+
+## Unknowns
+
+> Only these become questions. Before writing one, grep `.tldrx/memory/facts.yml`:
+> re-asking a recorded fact is a framework test failure, not a style choice.
+> Each unknown states who or what could answer it.
+
+- Who owns <…>, and what happens today when <…>? — *could be answered by:* `<person | file | command | doc>`
+
+## Evidence ledger
+
+> Every source cited above, once, with what it proved. This is what the next stage
+> and the reviewer read instead of re-deriving the work. **List items, not a table**
+> — this section is checked exactly like the other three, and a table holds no
+> list items for the gate to check.
+
+- … what this file establishes … `[src: <repo>:<path>:<line>]`
+- … what this command proved … `[src: $ <command> → exit 0]`
+
+## Outputs written
+
+- `intent.md`
+- `scope.md` (in / out, MoSCoW)
+- `success-metrics.md`
+- `open-questions.md`
+
+## Gate
+
+Blocked on: **<human approval | checks green>** — `stage.yml`'s `gate.type`. What is
+actually enforced is that file's `checks:` list, which `tldrx approve` re-runs against what
+is on disk before it will advance anything. Nothing advances until this is recorded in
+`run.yml` and `events.jsonl`.
+
+## Rules
+
+- Every bullet under Findings / Decisions / Unknowns / Evidence ledger is ONE line and ENDS with a source token. A bullet without one is refused by the `claim-sources` gate and the whole stage fails.
+- Each of Findings / Decisions / Unknowns / Evidence ledger must hold at least ONE list item; a section that is genuinely empty is written as `- none [src: absent:<what you looked at>]`, and a prose-only section is refused by the `claim-sources` gate.
+- Source token grammar (exact): `[src: <one or more sources separated by "; ">]` where a source is ONE of:
+  - `<repo>:<path>:<line>` or `<repo>:<path>:<start>-<end>` — a file with ONE line or ONE range. Never a whole file, never a comma list (`file.md:7,21` is invalid: write two sources or a range).
+  - `F<n>` — a fact id from `.tldrx/memory/facts.yml` (cite the id, never the file).
+  - `Q<n>` — a question from this run's questions.md.
+  - `https://…` — an external document (https only).
+  - `aidlc:<file>:<line>` / `aidlc:<file>#Q<n>` — an imported source, exactly as it already appears in intent.md/scope.md.
+  - `$ <command> → exit <n>` — only under Evidence ledger, only for commands listed in `.tldrx/workspace.yml`.
+  - `absent:<path>` — you looked there and found nothing.
+- Do not cite templates, expert files or directories (`.tldrx/experts/*` is not evidence).
+- Questions go in `questions.md`, and its shape is a PARSER's, not a style. One regex reads a block — `^## (Q\d+) · (.+)$` — and a heading that misses it is not half-read, it is read as ABSENT: the gate then records "0 open questions" and signs itself over questions nobody answered. Write each one EXACTLY like this, `·` being U+00B7 MIDDLE DOT:
+  ```
+  ## Q1 · Where does leaderboard state live?
+  <!-- id: Q1 | status: open | area: data-model | asked_by: architect | asked_at: 2026-08-29T14:02:11Z -->
+  Why asked: no ranking store exists in the map [src: absent:.tldrx/map/api/domains.md]
+
+  - A) New Postgres table, recomputed on hunt completion
+  - B) Redis sorted set
+  - C) other — write it below
+
+  [Answer]:
+  ```
+  All five metadata keys are required; `Why asked:` must END with a `[src: …]` token; 2–5 options lettered A–E in order; exactly one empty `[Answer]:` slot. Ids ascend. Never write `### Qn — …`, `**Answer:**`, or the answered footer — the hook writes that. `tldrx questions lint` checks the file; `--fix` converts a file already written the wrong way.
+- Before asking a question, grep `.tldrx/memory/facts.yml`; if the answer is there, cite `F<n>` instead of asking.
+- Write only the declared outputs; do not add sections beyond the ones listed under Produce.

package/stages/what/stage.yml

@@ -0,0 +1,61 @@
+# schema: draft
+# Phase 1 of the loop. Concept §3.
+# Accepts a phrase OR a document: Investigate reads the doc, extracts claims plus
+# gaps, and Interview asks about the gaps only.
+name: what
+title: What
+phase: 1
+model: sonnet
+# --effort for this stage's sub-agent (spec §2.3). The cost lever
+# `--max-budget-usd` is not: the budget flag only STOPS a turn already in flight.
+# `[assumption]` — What is elicitation over a small, capped input set: read
+# the seeds, name what is in and out. Medium is the level that reads carefully
+# without paying to reason about a design it has not been asked for.
+effort: medium
+budget_usd: 4
+
+# `seed: true` — this stage ALSO receives the run's seed documents: the files
+# `tldrx run new --seed <file|dir>` recorded in `run.yml` for it (spec §2.3). They
+# cannot be named here because they differ per run; the stage opts in, the run
+# says what the seed was, and an unseeded run simply has none. This replaces the
+# old `"<free text, a PRD, any document, or a Jira epic>"` placeholder, which was
+# prose no code could act on — the facilitator inlined zero documents for it.
+#
+# The §2.3 spelling is `inputs: {seed: true, required: [...], optional: [...]}`
+# and the loader accepts it; the shipped file uses the draft array form plus this
+# top-level key because the v0 skeleton validator still requires `inputs` to be an
+# array (`src/core/schemas/stage.ts`). `[assumption]`
+seed: true
+inputs:
+  - ".tldrx/memory/facts.yml"
+  - ".tldrx/map/{repo}/domains.md"
+
+outputs:
+  - "intent.md"
+  - "scope.md"
+  - "success-metrics.md"
+  - "open-questions.md"
+  - "handoff.md"
+  - "questions.md"
+
+# `domain` used to be listed here and was never an expert NAME — a `kind: domain`
+# expert is picked by the paths this run cites (spec §2.3, rule 3), which a stage
+# file written once for every workspace cannot know. Rules 2 and 3 still apply to
+# this stage; only the placeholder is gone.
+experts:
+  - product
+
+# `requires:` used to list three acceptance criteria here. Nothing read them:
+# `normaliseGate` (src/core/run/workflowPreset.ts:216-231) reads only `.type`,
+# `validateStage` (src/core/schemas/stage.ts:72-76) checks only `gate.type`, the
+# prompt ships `stage.md` and never this file (src/core/facilitator/prompt.ts:101),
+# and no other file in the repo touches the key. Criteria no gate enforces and no
+# reader ever sees are worse than none — the enforcement that IS real is the
+# `checks:` list below.
+gate:
+  type: human-approval
+
+checks:
+  - claim-sources
+  - no-reask
+  - budget-gate

package/templates/budget.yml

@@ -0,0 +1,17 @@
+# schema: draft
+# Written to tldrx-work/<run>/budget.yml. Concept §11.
+#
+# ceiling_usd is a refusal, not a warning: a stage whose estimate exceeds what
+# remains does not start. spent_usd is rolled up from events.jsonl — never typed
+# by hand, never estimated by an agent.
+version: 1
+run: "260828-example-slug"
+ceiling_usd: 25
+spent_usd: 0
+
+per_phase_usd:
+  what: 4
+  how: 6
+  plan: 4
+  build: 9
+  watch: 2

package/templates/competencies.yml

@@ -0,0 +1,14 @@
+# schema: draft
+# Written to .tldrx/experts/<name>/competencies.yml. Concept §6.
+#
+# `level` is COMPUTED from evidence count and recency. It is never self-declared
+# and an expert may not edit its own. The star chart in the dashboard is this file
+# rendered — nothing more.
+version: 1
+expert: example-expert
+
+areas:
+  - area: "oauth"
+    level: 0                # 0-5, computed
+    evidence: []            # each entry cites a file:line, a doc URL, or a run id
+    last_trained: null