done-done-axi 0.5.1 → 0.6.0

package/README.md

@@ -125,11 +125,11 @@ done-done init
 ```yaml
 journeys:
   smoke:
-    command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log
+    command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs
     core: true
 ```
 
-The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails. A journey that only runs code checks (`npm test`, `yarn run check`, `tsc`, `pytest`, a linter or a build) is code-only: its log says the code checks pass, not that the product works, so `init --journey` refuses it and `check`, `receipt` and `gate` never count it as proof ([the rule](docs/reference.md#real-product-evidence)).
+The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails. The command also writes `steps.json` beside its captures: the target version, the state it started from, the steps a user takes and the result a user sees. `check`, `receipt` and `gate` read the claim against that record, so a test log wrapped in a script cannot prove a claim about the product ([the record](docs/reference.md#step-record)). A journey that only runs code checks (`npm test`, `yarn run check`, `tsc`, `pytest`, a linter or a build) is code-only: its log says the code checks pass, not that the product works, so `init --journey` refuses it and `check`, `receipt` and `gate` never count it as proof ([the rule](docs/reference.md#real-product-evidence)).
 
 Name your **core journey** with `core: true`: the one thing a user cannot live without, driven end to end on the real target (for a remote terminal app: pair, open a pane, type, see the output). If your app ships something users install and upgrade (an npm CLI, an Android app, a host service), also record an **upgrade journey** with `upgrade: true` that installs your previous release, upgrades over it in place, then drives the core journey: a fresh install alone is not how users get your release. `doctor` fails until both are named ([the rule](docs/reference.md#core-journey-and-release-path)).
 
@@ -138,7 +138,7 @@ Optional: `done-done init --hook <claude|codex|opencode|gemini|pi>` adds a sessi
 Record the recipe in the repo so anyone can re-run the proof, then commit it (and `.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, `.opencode/plugins/done-done.js` or `.pi/extensions/done-done.js` if you added a hook):
 
 ```sh
-done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
+done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs'
 git add .done-done.yaml
 git commit -m "Add done-done"
 ```
@@ -158,6 +158,8 @@ done-done check --outcome "it starts" ~/.done-done/evidence/your-app/*/*.log
 
 Each command prints one machine-readable result. By default it is [TOON](https://github.com/toon-format/spec) (the compact AXI convention). `run` shows `result: recorded`: it captured evidence, and says nothing about whether it proves the claim. `check` starts your judge on each capture, and only a check the judge passes shows `result: pass`; with no judge set it asks for one, and a judge that fails stops with the cause (exit 2), never a result. Add `--json` for JSON, or `--full` to list every evidence file or finding instead of the first few. After later runs, use the `run_id` the result prints in place of the first `*`.
 
+Not sure which journeys a change touches? `done-done affected` lists them from the verify skill's feature map and the paths each feature cites (the core journey when it cannot tell, never fewer), and exits 1 until a receipt for HEAD covers them. Bare `done-done`, which the session hooks run, names them too.
+
 When a check passes, save a receipt and re-verify it later:
 
 ```sh
@@ -177,6 +179,7 @@ Run `done-done` with no arguments to see the current config and the next step.
 
 - 🧪 **The real product, not code checks**: Proof must come from driving the app, CLI or site the way a user does. A config whose journeys only run tests, typecheck, lint or a build, or proof whose captures all come from such runs, is refused by `check`, `receipt` and `gate`, and `doctor` flags it ([rule](docs/reference.md#real-product-evidence)).
 - 🎯 **The core journey and the upgrade users take**: Each app names the one flow a user cannot live without, driven end to end on the real target, and an app that ships an installable artifact also names the upgrade over its previous release. `doctor` and the verify skill `init` writes require both ([rule](docs/reference.md#core-journey-and-release-path)).
+- 🧭 **The journeys your change needs**: `done-done affected [<base>]` reads the diff since the last receipt (or the default branch), maps each changed file to the journeys whose command runs it and the verify skill features whose file cites it, adds the core journey when a file is in no feature or journey, and exits 1 until a receipt for HEAD has a run of each. It flags the files no feature covers, so the feature map grows with the code ([how](docs/reference.md#affected-journeys)).
 - 🔗 **Tied to a commit**: Every run records the commit, and whether there were uncommitted changes.
 - 🖼️ **Real media**: Empty, cut-off, blank or tiny screenshots fail. Videos must hold real frames (needs `ffprobe`).
 - ⏱️ **Fresh**: Proof from an older commit fails. Commits that only touch docs can be set to keep it fresh.
@@ -216,7 +219,7 @@ cat "$(npm root -g)/done-done-axi/integrations/firstmate/brief-include.md" >> "$
 cp "$(npm root -g)/done-done-axi/integrations/firstmate/merge-gate" "$FM_HOME/config/merge-gate"
 ```
 
-- **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run a journey on its committed change, write a `## Checks` block, pass `check`, and record a `receipt`. The evidence and receipt stay in `~/.done-done/evidence/<app>` after teardown deletes the worktree.
+- **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run the journeys `done-done affected` lists for its committed change, write a `## Checks` block, pass `check`, record a `receipt`, and see `affected` exit 0. The evidence and receipt stay in `~/.done-done/evidence/<app>` after teardown deletes the worktree.
 - **`merge-gate`** (optional): `merge-gate <task-id> <worktree|-> <head> <pr-url|->`. In the worktree, it refuses a PR whose head is not `<head>`, then runs `done-done check --from <PR URL or $FM_HOME/data/<task-id>/checks.md> --trusted-ref <default branch>` (`origin/HEAD`, else `origin/main` or `origin/master`, else the local `main` or `master` in a repo with no remote), then `done-done receipt --verify <head>`. Both paths read done-done's rules from your default branch, never from the task's own branch, so merge `.done-done.yaml` there before you rely on it. The gate does not fetch: it reads the local `origin` refs, so run `git fetch origin` before you run it. It needs `done-done` on PATH (the `npm install` line above). A nonzero exit refuses the merge, and done-done's output says why. A worktree of `-` means the task recorded none, so there is no repo to check: the gate refuses (exit 2) rather than check whatever folder it was called from. Its `check` always starts the judge the user set, which must pass each capture; with none set, the gate refuses (exit 2). Upstream Firstmate does not call a merge gate yet, so this file has no effect until it does; you can run it by hand before a merge.
 
 Another fleet works the same way: add the include text to whatever your workers read first, and run `merge-gate` before each merge, with `FM_HOME` set to the folder that holds `data/<task-id>/checks.md` for local-only tasks.
@@ -230,7 +233,7 @@ Another fleet works the same way: add the include text to whatever your workers
 
 ## What's next
 
-So far: `init`, `doctor`, `run` (including `--open` and `--close`), `check`, `receipt`, `lint` (a no-model gate on a Checks block), `gate` (a no-model CI check of a committed receipt), `verify` (by journey or by your coding agent, with a gate you answer with `respond`), `maintain`, the capture judge (always on), the `design` visual check, the `look` step, the run tools (`status`, `attach`, `logs`, `rerun`, `abort`, `signoff`, `history`) and the opt-in session hooks for Claude Code, Codex, opencode, Gemini CLI and pi. Coming next: help writing the proof steps for your app.
+So far: `init`, `doctor`, `run` (including `--open` and `--close`), `check`, `receipt`, `affected` (the journeys a diff needs), `lint` (a no-model gate on a Checks block), `gate` (a no-model CI check of a committed receipt), `verify` (by journey or by your coding agent, with a gate you answer with `respond`), `maintain`, the capture judge (always on), the `design` visual check, the `look` step, the run tools (`status`, `attach`, `logs`, `rerun`, `abort`, `signoff`, `history`) and the opt-in session hooks for Claude Code, Codex, opencode, Gemini CLI and pi. Coming next: help writing the proof steps for your app.
 
 ## Develop
 

package/dist/affected.js

@@ -0,0 +1,94 @@
+import { posix } from 'node:path';
+import { codeOnly } from './proof.js';
+// The tracked files and folders a text names. Paths are read relative to the repo, then to `from` (a feature file's folder,
+// for its markdown links); a folder counts only when written with a slash (src/), so a prose word never names one.
+// ponytail: a path with brackets or parens (pages/[id].tsx) is not read; add those characters when a repo cites one.
+function refs(text, tracked, from) {
+    const files = new Set();
+    const dirs = new Set();
+    const exact = new Set(tracked);
+    for (let tok of text.match(/[\w@.\/+-]+/g) ?? []) {
+        tok = tok.replace(/\.+$/, '');
+        if (!tok)
+            continue;
+        if (!tok.includes('/')) {
+            if (/\.[A-Za-z]\w*$/.test(tok))
+                for (const t of tracked)
+                    if (t === tok || t.endsWith(`/${tok}`))
+                        files.add(t);
+            continue;
+        }
+        for (const p of [posix.normalize(tok), ...(from ? [posix.join(from, tok)] : [])]) {
+            const clean = p.replace(/^\.\//, '').replace(/\/+$/, '');
+            if (!clean || clean.startsWith('..'))
+                continue;
+            if (exact.has(clean))
+                files.add(clean);
+            else if (tracked.some((t) => t.startsWith(`${clean}/`)))
+                dirs.add(clean);
+        }
+    }
+    return { files, dirs: [...dirs] };
+}
+const covers = (r, p) => r.files.has(p) || r.dirs.some((d) => p.startsWith(`${d}/`));
+// The journeys and features `changed` needs. features: each feature file's text by name; skill: the skill folder; coreFeature:
+// the feature the feature map marks (core journey), for the fallback; noBase: why there is no diff to read, if so.
+export function mapChange(o) {
+    // A code-only journey is no proof, so the change never needs one.
+    const real = Object.keys(o.journeys).filter((n) => !codeOnly(o.journeys[n].command));
+    const jRefs = new Map(real.map((n) => [n, refs(o.journeys[n].command, o.tracked)]));
+    const featDir = posix.join(o.skill, 'features');
+    const fRefs = new Map(Object.entries(o.features).map(([n, text]) => [n, refs(text, o.tracked, featDir)]));
+    // The journeys each feature names: `run <journey>` or `verify <journey>`, or a file its command runs that the feature cites too.
+    const named = new Map(Object.entries(o.features).map(([n, text]) => {
+        const said = new Set([...text.matchAll(/\b(?:run|verify)\s+`?([\w.-]+)/g)].map((m) => m[1]));
+        const r = fRefs.get(n);
+        return [n, real.filter((j) => said.has(j) || [...jRefs.get(j).files].some((f) => r.files.has(f)))];
+    }));
+    const journeys = new Map();
+    const features = new Map();
+    const hit = (m, name, why) => m.set(name, [...(m.get(name) ?? []), why]);
+    const unmapped = [];
+    for (const c of o.changed) {
+        let found = false;
+        for (const [j, r] of jRefs)
+            if (covers(r, c)) {
+                hit(journeys, j, `its command runs ${c}`);
+                found = true;
+            }
+        // The skill's own SKILL.md and feature map are what every feature follows, so they need every feature.
+        const shared = c.startsWith(`${o.skill}/`) && !(c.startsWith(`${featDir}/`) && posix.basename(c, '.md') in o.features);
+        for (const [f, r] of fRefs) {
+            if (!shared && c !== posix.join(featDir, `${f}.md`) && !covers(r, c))
+                continue;
+            found = true;
+            const why = shared ? `every feature follows ${c}` : c === posix.join(featDir, `${f}.md`) ? `feature ${f} changed` : `feature ${f} cites ${c}`;
+            const js = named.get(f);
+            if (js.length)
+                for (const j of js)
+                    hit(journeys, j, why);
+            else
+                hit(features, f, why);
+        }
+        if (!found)
+            unmapped.push(c);
+    }
+    // Uncertain: the core journey runs too; with no core journey named, every real journey does, so the answer is never less.
+    const uncertain = o.noBase ?? (unmapped.length ? `${unmapped.length} changed ${unmapped.length === 1 ? 'file is' : 'files are'} in no feature or journey` : '');
+    let fallback = null;
+    if (uncertain) {
+        const core = real.filter((j) => o.journeys[j].core);
+        const why = `uncertain: ${uncertain}`;
+        if (core.length)
+            core.forEach((j) => hit(journeys, j, why));
+        else if (o.coreFeature && o.coreFeature in o.features)
+            (named.get(o.coreFeature).length ? named.get(o.coreFeature).forEach((j) => hit(journeys, j, why)) : hit(features, o.coreFeature, why));
+        else if (real.length)
+            real.forEach((j) => hit(journeys, j, `${why}, and no core journey is named`));
+        else
+            Object.keys(o.features).forEach((f) => hit(features, f, `${why}, and no core journey is named`));
+        fallback = why;
+    }
+    const list = (m) => [...m].map(([name, why]) => ({ name, why: [...new Set(why)] }));
+    return { journeys: list(journeys), features: list(features), unmapped, fallback };
+}

package/dist/cli.js

@@ -21,8 +21,10 @@ import { domIssues, domRecord, isDomRecord, lookIssues, SQUASHED_TEXT } from './
 import { lint } from './lint.js';
 import { look } from './look.js';
 import { scanSecrets } from './secrets.js';
-import { codeOnly, codeOnlyJourneys, configFault, MARK, namedJourney, releaseArtifacts, RULE, runsFault } from './proof.js';
+import { mapChange } from './affected.js';
+import { codeOnly, codeOnlyJourneys, configFault, MARK, namedJourney, releaseArtifacts, RULE, runsFault, STEPS_FILE, STEPS_SHAPE, stepRecordFault, stepsFault } from './proof.js';
 const PASS = 0, FAIL = 1, USAGE = 2, INCONCLUSIVE = 3, WAITING = 4;
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 // The shape of a journey, so a new user or agent can write one without opening the reference.
 // done-done sets DONE_DONE_EVIDENCE_ROOT (the run's own folder) and replaces ${RUN_ID}, so the example works for any evidence root.
 const journeyExample = 'journeys: { smoke: { command: "<drive the core user journey on the real app> > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log", core: true } }';
@@ -32,6 +34,8 @@ const JOURNEYS_TEXT = `journeys (.done-done.yaml): the command runs with DONE_DO
   real product: a journey whose command only runs tests, typecheck, lint or a build (npm test, yarn run check, tsc, pytest, or a test or guard
   script such as bash tests/x.test.sh or node scripts/floor-guard.mjs) is code-only;
   init --journey refuses it, and check, receipt and gate refuse proof that comes only from code-only runs or a config of only code-only journeys
+  step record: the journey also writes steps.json into $DONE_DONE_EVIDENCE_ROOT, shaped ${STEPS_SHAPE};
+  check, receipt and gate refuse a claim that no cited run's step record covers (a run recorded before step records only warns)
   core (journeys.<name>.core: true): the core user journey, the one thing a user cannot live without, driven end to end on the real target
   (for a remote terminal: pair, open a pane, type, see the output); doctor requires one, here or as a "(core journey)" entry in the verify skill's feature map
   upgrade (journeys.<name>.upgrade: true): the release path users take: install the previous shipped version, upgrade over it in place, then drive the
@@ -237,6 +241,19 @@ const COMMANDS = {
   a "moved-from: <owner>/<repo>@<ref> <dst>=<src>" body line says came from a repo of the same owner; both are off by default.
   checks.generated_paths: ["gen/**", "*.snap"] adds your own globs to the generated files above; the default is none.
   Every run is appended to lint.log next to the store. Exit 0 PASS or WARN, 1 FAIL, 2 usage error. Needs gh for a PR URL`],
+    },
+    affected: {
+        usage: [['done-done affected [<base>]', "the journeys a change needs, from the verify skill's feature map and the paths it cites (the core journey when unsure); exit 1 until a receipt for HEAD covers them"]],
+        flags: [],
+        more: [`affected: model-free. The change is the diff from <base>, else from the newest receipt before HEAD (the commits since the last proof),
+  else from the merge base with the default branch (origin/HEAD, origin/main, origin/master, main, master), plus uncommitted changes to tracked files;
+  evidence.ignore_paths and .done-done-receipts/ need nothing. A journey is needed when its command runs a changed file; a feature
+  (features/<name>.md) when it cites a changed file (a repo path, a markdown link, a folder written with a slash such as src/, or a bare
+  file name) or is the changed file, and then each journey it names (run <journey>, or a file the journey's command runs); a feature
+  that names no journey is driven by your agent (verify --feature <name>). A changed file nothing covers, or no base, is uncertain:
+  the core journey is needed too (every journey when none is core), never less, and the file is flagged for the feature map.
+  Result: fresh (exit 0) when the receipt for HEAD has a run of every needed journey and feature and nothing is uncommitted;
+  stale (a receipt for an earlier commit, a receipt that misses a needed journey, or uncommitted changes) or missing (no receipt) exit 1`],
     },
     status: {
         usage: [['done-done status [--run <run-id>]', "show a run's steps, result, findings and next step"]],
@@ -416,7 +433,26 @@ function openRun(repo, cfg, journey, command, id) {
     const runId = id ?? newRunId(h.commit);
     mkdirSync(cfg.evidence.root, { recursive: true });
     mkdirSync(runDir(cfg, runId));
-    return { schema: 1, run_id: runId, journey, command, ...h, started_at: new Date().toISOString(), ended_at: null, exit: null, files: [] };
+    return { schema: 1, run_id: runId, journey, command, ...h, started_at: new Date().toISOString(), ended_at: null, exit: null, files: [], tool: VERSION };
+}
+// The step record a run's journey (or driving agent) wrote beside its captures; it is a record, not a capture, so it is not a run file.
+function readSteps(cfg, rec) {
+    delete rec.steps;
+    delete rec.steps_error;
+    const file = join(runDir(cfg, rec.run_id), STEPS_FILE);
+    if (!existsSync(file))
+        return;
+    try {
+        const steps = JSON.parse(readFileSync(file, 'utf8'));
+        const bad = stepRecordFault(steps);
+        if (bad)
+            rec.steps_error = bad;
+        else
+            rec.steps = steps;
+    }
+    catch (e) {
+        rec.steps_error = `it is not JSON (${e.message})`;
+    }
 }
 // The first line of a run's log that names a failure, trimmed: what a non-zero exit is about. Empty when none does.
 function firstFailure(log) {
@@ -427,7 +463,9 @@ function firstFailure(log) {
 }
 function closeRun(repo, cfg, rec, log) {
     const now = head(repo);
+    readSteps(cfg, rec);
     rec.files = captured(cfg, rec.run_id)
+        .filter((p) => basename(p) !== STEPS_FILE || dirname(p) !== rec.run_id)
         .sort()
         .map((p) => {
         const b = readFileSync(join(cfg.evidence.root, p));
@@ -788,7 +826,7 @@ async function runCheck(argv, run) {
             continue;
         }
         const rec = (atNow.length ? atNow : claims).reduce((a, b) => (b.started_at > a.started_at ? b : a));
-        runs.set(rec.run_id, { run_id: rec.run_id, journey: rec.journey, command: rec.command });
+        runs.set(rec.run_id, { run_id: rec.run_id, journey: rec.journey, command: rec.command, ...(rec.feature && { feature: rec.feature }), ...(rec.tool && { tool: rec.tool }), ...(rec.steps && { steps: rec.steps }), ...(rec.steps_error && { steps_error: rec.steps_error }) });
         // Only a capture tied to a run record can reach the judge, so a stray cited file is never sent.
         const c = { name, bytes, sha256: hash, media: v };
         if (v.status === 'ok' && !record && pair)
@@ -821,6 +859,15 @@ async function runCheck(argv, run) {
     const codeRuns = runs.size ? runsFault([...runs.values()]) : null;
     if (codeRuns)
         findings.push({ level: 'fail', why: codeRuns });
+    // The user steps behind the captures: a cited real run needs a step record covering the claim. Runs from before step records warn.
+    const warnings = [];
+    if (claim && runs.size && !codeRuns) {
+        const s = stepsFault([...runs.values()], claim.outcome);
+        if (s.fault)
+            findings.push({ level: 'fail', why: s.fault });
+        if (s.warning)
+            warnings.push(s.warning);
+    }
     // Reuse: fail only when every cited file was already used for a different claim id. The ledger lives in the
     // evidence root next to the run records it guards: one per app (repo), shared by every checkout of it, never in git.
     const ledger = join(cfg.evidence.root, '.done-done', 'ledger');
@@ -876,12 +923,12 @@ async function runCheck(argv, run) {
     if (j.notJudged.length)
         judged.not_judged = j.notJudged;
     judged.note = 'PNG and JPEG screens and text captures (logs, JSON, CLI output) are judged; video and other files are not';
-    const rep = report(findings, files, { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel });
+    const rep = report(findings, files, { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel, warnings });
     if (rep.code === PASS) {
         mkdirSync(dirname(ledger), { recursive: true });
         appendFileSync(ledger, hashes.filter((h) => !used.get(h)?.has(claimId)).map((h) => `${h} ${claimId}\n`).join(''));
     }
-    return { code: rep.code, result: rep.result, judge: judged, judgeBlock, claim: claim?.outcome, skill: claim?.skill, files, cited, runs: [...runs.values()], head: now, findings };
+    return { code: rep.code, result: rep.result, judge: judged, judgeBlock, claim: claim?.outcome, skill: claim?.skill, files, cited, runs: [...runs.values()], head: now, findings, warnings };
 }
 async function cmdCheck(argv) {
     const r = await runCheck(argv);
@@ -919,8 +966,13 @@ function receiptFault(rec, short) {
     if (badJudge)
         return `receipt for ${short} has a malformed judge block`;
     const code = runsFault(rec.runs);
-    return code ? `receipt for ${short} is no real-product proof: ${code}` : null;
+    if (code)
+        return `receipt for ${short} is no real-product proof: ${code}`;
+    const steps = stepsFault(rec.runs, rec.claim);
+    return steps.fault ? `receipt for ${short} has no step record covering its claim: ${steps.fault}` : null;
 }
+// The warning a well-formed receipt still carries: its runs were recorded before step records.
+const receiptWarning = (rec) => stepsFault(rec.runs, rec.claim).warning;
 // Verify a recorded receipt for `headArg`, which may be a full sha or a ref (HEAD, a branch or a tag).
 // Read-only, so a missing or changed record is a failure, not a usage error.
 function verifyReceipt(repo, cfg, headArg) {
@@ -972,7 +1024,7 @@ function verifyReceipt(repo, cfg, headArg) {
     }
     if (bad.length)
         return fail(`cited evidence no longer matches the receipt: ${bad.join('; ')}`);
-    return { code: PASS, result: { command: 'receipt', result: 'pass', head: commit, tree: rec.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, at: rec.at, schema: rec.schema, judge: j, help: ['This receipt is valid for this head.'] } };
+    return { code: PASS, result: { command: 'receipt', result: 'pass', head: commit, tree: rec.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, at: rec.at, schema: rec.schema, judge: j, ...(receiptWarning(rec) && { warnings: [receiptWarning(rec)] }), help: ['This receipt is valid for this head.'] } };
 }
 async function cmdReceipt(argv) {
     const vi = argv.indexOf('--verify');
@@ -1010,7 +1062,7 @@ function recordReceipt(repo, cfg, r) {
         throw new UsageError('receipt: the check cited no evidence files, so no receipt was written; a receipt must bind at least one cited evidence file', 'Cite real proof: done-done receipt --outcome "<claim>" <files...>');
     const rec = { schema: 2, repo: cfg.app, head: r.head.commit, tree: r.head.tree, claim: r.claim ?? '', ...(r.skill && { skill: r.skill }), result: 'pass', at: new Date().toISOString(), files: r.cited, runs: r.runs, judge: r.judgeBlock };
     const path = writeReceipt(cfg, rec);
-    const result = { command: 'receipt', result: 'pass', head: r.head.commit, tree: r.head.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, receipt: shown(repo, path) };
+    const result = { command: 'receipt', result: 'pass', head: r.head.commit, tree: r.head.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, receipt: shown(repo, path), ...(r.warnings.length && { warnings: r.warnings }) };
     return { code: PASS, result: { ...result, ...(r.judge && { judge: r.judge }), help: [`Verify this receipt (merge gate): done-done receipt --verify ${r.head.commit}`] } };
 }
 // Why evidence from `from` no longer proves `to`, or '' if it still does.
@@ -1056,6 +1108,8 @@ function checkHelp(code, findings, files, { cfg, repo, claim, source, citationBa
             ? `${absent} named file${absent > 1 ? 's are' : ' is'} not in this checkout. If the evidence is in another folder, check against it: ${form}`
             : `${absent} named file${absent > 1 ? 's are' : ' is'} not under --citation-base ${arg(citationBase)} either: check the paths in the Checks block`);
     }
+    if (findings.some((f) => f.why.includes('step record')))
+        help.push(`Have the journey write ${STEPS_FILE} into $DONE_DONE_EVIDENCE_ROOT, shaped ${STEPS_SHAPE}, naming the steps and the result the claim is about; then re-run it (${captureHint(cfg)}) and cite the new files`);
     // Proof refused as code-only needs a journey that drives the product, not a re-capture of the same run.
     if (findings.some((f) => f.why.endsWith(RULE)))
         help.push(`Capture the real product: ${captureHint(cfg).startsWith('done-done init') ? captureHint(cfg) : `${captureHint(cfg)}, or ${RECORD_REAL}`}, then cite its files`);
@@ -1087,6 +1141,8 @@ function report(findings, files, ctx) {
         result.findings = rows.items;
     if (rows.omitted)
         result.findings_omitted = rows.omitted;
+    if (ctx.warnings?.length)
+        result.warnings = ctx.warnings;
     result.help = checkHelp(code, findings, files, ctx);
     return { code, result };
 }
@@ -1316,11 +1372,12 @@ ${inst}${cells}${dom}${before}
 2. ${cfg.instance ? 'Drive that running instance' : 'Launch the app as the skill says, then drive'} that feature through the real user path, step by step as its recipe says.
    Never add steps or data to make the outcome look true: capture what that path shows, even when it contradicts the outcome.
 3. Save PNG screenshots of what a user sees once the path is done (the resulting state the outcome is about) into ${evidence} (also in $DONE_DONE_EVIDENCE_ROOT); when the outcome shows in text (a CLI's output, a log or JSON), save that text there as a .txt, .log or .json file instead.
-   The judge checks every capture there against the outcome, so a capture of an earlier step (such as an empty or half-filled form, or text from before the outcome) fails the drive: keep those in ${scratch}. Save nothing else there, and never edit a capture.
-4. Stop everything you started.
+   The judge checks every capture there against the outcome, so a capture of an earlier step (such as an empty or half-filled form, or text from before the outcome) fails the drive: keep those in ${scratch}. Save nothing else there but the step record of step 4, and never edit a capture.
+4. Write ${STEPS_FILE} into ${evidence} (also in $DONE_DONE_EVIDENCE_ROOT), the record of what you did, as JSON shaped ${STEPS_SHAPE}: the app version you drove (its package or build version, else the commit), the state it started from, each step a user takes in your own words, and what a user can see at the end. Write what you did, never what the outcome needs.
+5. Stop everything you started.
 
 Do not change any file in the repository. Do not run done-done: it refuses inside a drive, and done-done answers the run after you stop. Put logs and other scratch files in ${scratch} (also in $TMPDIR), never in /tmp.
-Keep working until all four steps are done: your next message without a tool call ends the drive and must be the answer.
+Keep working until all five steps are done: your next message without a tool call ends the drive and must be the answer.
 If you cannot launch the app or reach the feature, say why in blocker and save no capture.
 Answer with feature (the feature file you drove, such as features/<name>.md), captures (the file names you saved) and blocker ("" when you drove it),
 for example {"feature":"features/<name>.md","captures":["<name>.png"],"blocker":""}.`;
@@ -1506,12 +1563,14 @@ async function runSteps(dir) {
                         const b = await drive(where, evidence, env, cfg.base_ref);
                         return b.ok ? String(b.answer?.blocker ?? '').trim() : `${author.agent} did not finish the drive: ${b.error}`;
                     });
-                const sealed = closeRun(at, cfg, rec);
-                if (!fix)
-                    run.record = join(recordsDir(cfg), `${rec.run_id}.json`);
                 const picked = typeof answer?.feature === 'string' ? answer.feature.replace(/^.*features\//, '').replace(/\.md$/, '') : '';
                 if (skillFeatures(at, cfg).includes(picked))
                     run.feature ??= picked;
+                if (run.feature)
+                    rec.feature = run.feature;
+                const sealed = closeRun(at, cfg, rec);
+                if (!fix)
+                    run.record = join(recordsDir(cfg), `${rec.run_id}.json`);
                 log('drive', { agent: author.agent, model: author.model, feature: run.feature ?? 'none', ...(a.ok ? { captures: answer?.captures, blocker } : { error: a.error }), record: a.record ?? a.recordError });
                 const why = !a.ok ? `${author.agent} did not finish the drive: ${a.error}${a.record ? `; call record ${a.record}` : ''}`
                     : blocker ? `${author.agent} could not drive the feature: ${blocker}`
@@ -3641,7 +3700,7 @@ async function cmdLook(argv) {
 // The folder of a branch where a receipt copied from the evidence root is committed, for `gate`.
 const GATE_DIR = '.done-done-receipts';
 // The reason no committed receipt vouches for `tip`, or null when one does. Reads git objects only: no config, no judge, no evidence files.
-function gateFault(repo, tip, dir, pushed) {
+function gateFault(repo, tip, dir, pushed, warnings) {
     const short = tip.slice(0, 12);
     const names = git(repo, '-c', 'core.quotepath=off', 'ls-tree', '-r', '--name-only', tip, '--', dir).split('\n').filter((n) => n.endsWith('.json'));
     if (!names.length)
@@ -3673,6 +3732,9 @@ function gateFault(repo, tip, dir, pushed) {
             const at = Date.parse(rec.at);
             if (!(Math.floor(at / 1000) <= Math.floor(pushed / 1000)))
                 return `receipt time ${rec.at} is not before the push (${new Date(pushed).toISOString()})`;
+            const warn = receiptWarning(rec);
+            if (warn)
+                warnings.push(warn);
             return null;
         })();
         if (!why)
@@ -3697,8 +3759,9 @@ function cmdGate(argv) {
     const pushed = values.pushed === undefined ? Number(git(repo, 'log', '-1', '--format=%ct', tip)) * 1000 : Date.parse(values.pushed);
     if (Number.isNaN(pushed))
         throw new UsageError(`gate: --pushed ${values.pushed} is not a time`, 'Pass an ISO time such as 2026-10-20T09:05:56Z');
-    const why = gateFault(repo, tip, (values.dir ?? GATE_DIR).replace(/\/+$/, ''), pushed);
-    console.log(why === null ? 'PASS' : `FAIL: ${why}`);
+    const warnings = [];
+    const why = gateFault(repo, tip, (values.dir ?? GATE_DIR).replace(/\/+$/, ''), pushed, warnings);
+    console.log(why === null ? ['PASS', ...warnings.map((w) => `WARN: ${w}`)].join('\n') : `FAIL: ${why}`);
     return why === null ? PASS : FAIL;
 }
 function cmdLint(argv) {
@@ -3759,6 +3822,124 @@ async function cmdDesign(argv) {
     });
     return code;
 }
+// The receipts in the evidence root that are well-formed passes filed under their own head, by head.
+function receiptsByHead(cfg) {
+    const dir = receiptsDir(cfg);
+    const found = new Map();
+    for (const name of existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith('.json')) : []) {
+        try {
+            const rec = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+            if (!receiptFault(rec, name) && name === `${rec.head}.json`)
+                found.set(rec.head, rec);
+        }
+        catch {
+            // A receipt that cannot be read vouches for nothing; receipt --verify names its fault.
+        }
+    }
+    return found;
+}
+// The default branch to diff a change against, as the Firstmate merge gate picks it: origin/HEAD, else origin/main or
+// origin/master, else the local main or master. '' when there is none.
+function defaultBranch(repo) {
+    try {
+        return git(repo, 'symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD');
+    }
+    catch {
+        return ['origin/main', 'origin/master', 'main', 'master'].find((r) => spawnSync('git', ['rev-parse', '-q', '--verify', `${r}^{commit}`], { cwd: repo, stdio: 'ignore' }).status === 0) ?? '';
+    }
+}
+const isAncestor = (repo, a, b) => spawnSync('git', ['merge-base', '--is-ancestor', a, b], { cwd: repo, stdio: 'ignore' }).status === 0;
+// Which journeys the change needs (src/affected.ts) and whether HEAD's proof covers them. The change is read from `baseArg`,
+// else from the newest receipt before HEAD (the commits since the last proof), else from the merge base with the default
+// branch; with none, the mapping is uncertain and the core journey is needed.
+function affectedOf(repo, cfg, baseArg) {
+    const now = head(repo);
+    const receipts = receiptsByHead(cfg);
+    let base = null;
+    if (baseArg !== undefined) {
+        try {
+            base = { commit: git(repo, 'rev-parse', '--verify', `${baseArg}^{commit}`), from: baseArg };
+        }
+        catch {
+            throw new UsageError(`affected: ${baseArg} is not a commit in this checkout`, 'Pass a branch, tag or commit: done-done affected [<base>]');
+        }
+    }
+    else {
+        // ponytail: one git call per receipt to find the ones before HEAD; index receipts by commit when a repo keeps thousands.
+        const older = [...receipts.keys()].filter((h) => h !== now.commit && isAncestor(repo, h, now.commit));
+        const nearest = older.find((h) => older.every((o) => isAncestor(repo, o, h)));
+        const ref = nearest ? '' : defaultBranch(repo);
+        const mb = ref ? spawnSync('git', ['merge-base', ref, 'HEAD'], { cwd: repo, encoding: 'utf8' }).stdout.trim() : '';
+        if (nearest)
+            base = { commit: nearest, from: `the last receipt, for ${nearest.slice(0, 12)}` };
+        else if (mb && mb !== now.commit)
+            base = { commit: mb, from: `the merge base with ${ref}` };
+    }
+    const list = (...a) => git(repo, ...a).split('\0').filter(Boolean);
+    const tracked = list('ls-files', '-z');
+    // ignore_paths and committed gate receipts need no journey.
+    const counts = (p) => !p.startsWith(`${GATE_DIR}/`) && !cfg.evidence.ignore_paths.some((g) => matchesGlob(p, g));
+    // Untracked files are no part of the change until added, as everywhere else in done-done.
+    const uncommitted = list('diff', '--name-only', '--no-renames', '-z', 'HEAD').filter(counts);
+    const changed = [...new Set([...(base ? list('diff', '--name-only', '--no-renames', '-z', base.commit, 'HEAD').filter(counts) : []), ...uncommitted])];
+    const featDir = join(repo, cfg.skill, 'features');
+    const features = Object.fromEntries(skillFeatures(repo, cfg).map((n) => [n, repoText(join(featDir, `${n}.md`)) ?? '']));
+    const coreLine = featureMap(repo, cfg).split('\n').find((l) => /^\s*[-*] /.test(l) && l.includes(MARK.core));
+    const m = mapChange({ changed, tracked, journeys: cfg.journeys, skill: cfg.skill, features, coreFeature: coreLine?.match(/\]\(([^)#]+)\.md\)/)?.[1], noBase: base ? undefined : 'no receipt before HEAD and no default branch to diff against' });
+    const needed = [...m.journeys.map((j) => j.name), ...m.features.map((f) => `feature ${f.name}`)];
+    // Proof: a valid receipt for HEAD whose runs include every journey and feature the change needs, with nothing uncommitted.
+    const verified = verifyReceipt(repo, cfg, 'HEAD');
+    const runs = verified.code === PASS ? receipts.get(now.commit)?.runs ?? [] : [];
+    const covered = (n) => n.startsWith('feature ') ? runs.some((r) => r.feature === n.slice(8)) : runs.some((r) => r.journey === n || r.command === cfg.journeys[n].command.replaceAll('${RUN_ID}', r.run_id));
+    const missing = verified.code === PASS && !uncommitted.length ? needed.filter((n) => !covered(n)) : needed;
+    const stale = base && receipts.has(base.commit) ? base.commit : null;
+    const proof = verified.code !== PASS ? stale ? `stale: the receipt is for ${stale.slice(0, 12)}, and HEAD is ${now.commit.slice(0, 12)}` : `missing: ${verified.result.reason}`
+        : uncommitted.length ? `stale: uncommitted changes (${named(uncommitted)}); proof counts only from a commit`
+            : missing.length ? `stale: the receipt for HEAD has no run of ${missing.join(', ')}`
+                : 'fresh';
+    return { now, base, changed, m, proof, missing };
+}
+// `done-done affected [<base>]`: the journeys a change needs, and exit 1 until a receipt for HEAD covers them.
+function cmdAffected(argv) {
+    const { positionals } = parseArgs({ args: argv, allowPositionals: true });
+    if (positionals.length > 1)
+        throw new UsageError('affected takes at most one base', 'Re-run as: done-done affected [<base>]');
+    const repo = repoRoot();
+    const cfg = loadConfig(repo);
+    const a = affectedOf(repo, cfg, positionals[0]);
+    const fresh = a.proof === 'fresh';
+    const changed = cap(a.changed);
+    const why = (w) => (FULL || w.length <= 3 ? w.join('; ') : `${w.slice(0, 3).join('; ')}; +${w.length - 3} more (--full lists them)`);
+    const drive = [
+        ...a.m.journeys.filter((j) => a.missing.includes(j.name)).map((j) => `done-done run ${j.name}`),
+        ...a.m.features.filter((f) => a.missing.includes(`feature ${f.name}`)).map((f) => `done-done verify --feature ${f.name} --outcome "<what a user can now do>"`),
+    ];
+    emit({
+        command: 'affected',
+        result: fresh ? 'fresh' : a.proof.split(':')[0],
+        head: a.now.commit,
+        base: a.base ? `${a.base.commit.slice(0, 12)} (${a.base.from})` : 'none',
+        proof: a.proof,
+        changed: changed.items,
+        ...(changed.omitted && { changed_omitted: changed.omitted }),
+        journeys: a.m.journeys.map((j) => ({ name: j.name, why: why(j.why) })),
+        ...(a.m.features.length && { features: a.m.features.map((f) => ({ name: f.name, drive: 'verify --feature', why: why(f.why) })) }),
+        ...(a.m.unmapped.length && { unmapped: a.m.unmapped }),
+        ...(a.m.fallback && { fallback: `${a.m.fallback}, so the core journey runs too` }),
+        help: [
+            ...(fresh
+                ? [`The receipt for HEAD covers every journey this change needs (${[...a.m.journeys.map((j) => j.name), ...a.m.features.map((f) => f.name)].join(', ') || 'none'})`]
+                : [
+                    ...(a.proof.startsWith('stale: uncommitted') ? ['Commit the change first: proof counts only from a commit'] : []),
+                    ...(drive.length ? [`Capture fresh proof: ${drive.join(' && ')}`] : ['No journey needs a new run: re-run check and receipt for HEAD citing the evidence that still counts']),
+                    'Then check it and record the receipt: done-done receipt --from <the PR URL or checks.md>',
+                ]),
+            // A fresh receipt does not close the gap: the feature map still misses these files.
+            ...(a.m.unmapped.length ? [`Flag the gap: ${named(a.m.unmapped)} ${a.m.unmapped.length === 1 ? 'is' : 'are'} in no feature or journey; add ${a.m.unmapped.length === 1 ? 'it' : 'them'} to the feature file that drives ${a.m.unmapped.length === 1 ? 'it' : 'them'} in ${cfg.skill}/features (done-done maintain reports what no feature covers), or record a journey: done-done init --journey <name> -- <command>`] : []),
+        ],
+    });
+    return fresh ? PASS : FAIL;
+}
 // Bare `done-done`: orient a new user or agent with the config state and the next step.
 function cmdBare() {
     let repo;
@@ -3786,11 +3967,26 @@ function cmdBare() {
     const check = '`done-done check --outcome "<what you proved>" <files it recorded>`';
     const receipt = verifyReceipt(repo, cfg, 'HEAD');
     result.receipt = receipt.code === PASS ? `valid for HEAD ${String(receipt.result.head).slice(0, 12)}` : receipt.result.reason ?? receipt.result.result;
-    result.help = receipt.code === PASS
-        ? [`HEAD has a valid receipt for "${receipt.result.claim}"; prove the next commit with done-done verify --outcome "<what a user can now do>"`]
-        : journeys.length
-            ? [`Capture proof with \`done-done run ${journeys[0]}\`, then check it with ${check}`]
-            : [...driveHint(repo, cfg), `Add a journey to .done-done.yaml (${journeyExample}), commit, then \`done-done run smoke\` and ${check}`];
+    // The journeys this change still needs (done-done affected), so a session hook shows them with no extra call.
+    let needs = [];
+    try {
+        const a = affectedOf(repo, cfg);
+        if (a.proof !== 'fresh') {
+            needs = a.missing;
+            result.affected = { proof: a.proof, needs };
+        }
+    }
+    catch (e) {
+        result.affected = `not read: ${(e.stderr || e.message).trim()}`;
+    }
+    const runs = needs.filter((n) => !n.startsWith('feature ')).map((n) => `done-done run ${n}`);
+    result.help = runs.length
+        ? [`This change needs fresh proof: ${runs.join(' && ')} (done-done affected says why), then check it with ${check}`]
+        : receipt.code === PASS
+            ? [`HEAD has a valid receipt for "${receipt.result.claim}"; prove the next commit with done-done verify --outcome "<what a user can now do>"`]
+            : journeys.length
+                ? [`Capture proof with \`done-done run ${journeys[0]}\`, then check it with ${check}`]
+                : [...driveHint(repo, cfg), `Add a journey to .done-done.yaml (${journeyExample}), commit, then \`done-done run smoke\` and ${check}`];
     emit(result);
     return PASS;
 }
@@ -3837,6 +4033,8 @@ async function main(argv) {
             return cmdLint(rest);
         if (cmd === 'gate')
             return cmdGate(rest);
+        if (cmd === 'affected')
+            return cmdAffected(rest);
         if (cmd === 'status')
             return cmdStatus(rest);
         if (cmd === 'attach')
@@ -3858,7 +4056,7 @@ async function main(argv) {
             return PASS;
         }
         if (cmd === '--version') {
-            console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+            console.log(VERSION);
             return PASS;
         }
         if (cmd === '--help' || cmd === '-h' || cmd === 'help') {

package/dist/proof.js

@@ -102,6 +102,24 @@ export function configFault(journeys) {
     const code = codeOnlyJourneys(journeys);
     return names.length && code.length === names.length ? `every journey in .done-done.yaml is code-only (${code.join(', ')}): ${RULE}` : null;
 }
+export const STEPS_FILE = 'steps.json';
+export const STEPS_SHAPE = '{"target": {"version": "<version of the app driven>"}, "start": "<the state it started from>", "steps": ["<a step a user takes>", ...], "result": "<what a user can see at the end>"}';
+// Why parsed JSON is not a step record, or null.
+export function stepRecordFault(s) {
+    const r = s;
+    const text = (v) => typeof v === 'string' && v.trim() !== '';
+    if (!r || typeof r !== 'object' || Array.isArray(r))
+        return `it is not a JSON object shaped ${STEPS_SHAPE}`;
+    if (!text(r.target?.version))
+        return 'target.version is missing';
+    if (!text(r.start))
+        return 'start is missing';
+    if (!Array.isArray(r.steps) || !r.steps.length || !r.steps.every(text))
+        return 'steps must be a non-empty list of strings';
+    if (!text(r.result))
+        return 'result is missing';
+    return null;
+}
 // Why these capture runs are no real-product evidence (none recorded, or every one code-only), or null.
 export function runsFault(runs) {
     if (!Array.isArray(runs) || !runs.length)
@@ -112,6 +130,46 @@ export function runsFault(runs) {
         return null;
     return `every cited capture comes from a code-only run (${[...new Set(runs.map((r) => r.journey ?? r.command))].join(', ')}): ${RULE}`;
 }
+// Words that carry no claim: the claim's own scaffolding, not what a user does or sees.
+const GENERIC = new Set('that this with from into when then than have will does your their they them user users able now works work working shows show shown once after before also each every what which while where there here only just more most some such same been being were should would could done proof proves prove outcome correct correctly properly real product the and for are can its'.split(' '));
+const words = (t) => t.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+// A word of the claim is in the record when the record has a word that starts like it (attach, attaches, attached).
+const same = (a, b) => a.startsWith(b.slice(0, Math.min(5, b.length))) || b.startsWith(a.slice(0, Math.min(5, a.length)));
+// The words of the claim that the step record never mentions, or [] when it covers the claim: at least half of the claim's
+// words are in the record, and one of them in its result. A pure word match, no model: a test log's record ("ran the unit
+// suite") cannot cover a claim about a pane, and a CLI transcript whose record names the command and its output covers a CLI claim.
+export function uncovered(outcome, s) {
+    const terms = [...new Set(words(outcome).filter((w) => w.length >= 4 && !GENERIC.has(w)))];
+    if (!terms.length)
+        return [];
+    const all = words([s.start, ...s.steps, s.result].join(' '));
+    const result = words(s.result);
+    const hit = terms.filter((t) => all.some((w) => same(t, w)));
+    return hit.length * 2 >= terms.length && hit.some((t) => result.some((w) => same(t, w))) ? [] : terms.filter((t) => !hit.includes(t));
+}
+// Whether the runs behind a claim carry a step record covering it. A fault: no real run (one that is not code-only) has one.
+// A warning: a real run was recorded before step records existed, so it keeps working but nothing ties its captures to user steps.
+export function stepsFault(runs, outcome) {
+    const real = runs.filter((r) => !codeOnly(r.command));
+    const why = (r) => {
+        if (r.steps_error)
+            return `run ${r.run_id}'s step record ${STEPS_FILE} is invalid: ${r.steps_error}`;
+        if (!r.steps)
+            return `run ${r.run_id} has no step record (${STEPS_FILE} beside its captures)`;
+        const bad = stepRecordFault(r.steps);
+        if (bad)
+            return `run ${r.run_id}'s step record ${STEPS_FILE} is invalid: ${bad}`;
+        const miss = uncovered(outcome, r.steps);
+        return miss.length ? `run ${r.run_id}'s step record (${r.steps.steps.length} step${r.steps.steps.length > 1 ? 's' : ''}, target ${r.steps.target.version}) never mentions ${miss.join(', ')}` : '';
+    };
+    const reasons = real.map(why);
+    if (!real.length || reasons.some((w) => !w))
+        return { fault: null, warning: null };
+    const old = real.filter((r) => !r.tool);
+    if (old.length)
+        return { fault: null, warning: `run ${old.map((r) => r.run_id).join(', ')} was recorded before step records, so nothing shows the user steps behind its captures; re-run the journey so it writes ${STEPS_FILE}` };
+    return { fault: `no cited capture comes from a run whose step record covers the claim: ${reasons.join('; ')}`, warning: null };
+}
 export const MARK = { core: '(core journey)', upgrade: '(upgrade journey)' };
 // Where the role is named: the journey that carries it and drives the product, else the feature-map entry with its mark, else null.
 export function namedJourney(role, journeys, featureMap = '') {

package/docs/index.html

@@ -108,6 +108,7 @@
     <ul class="plain">
       <li><b>The real product, not code checks.</b> Proof comes from driving the app the way a user does; a journey that only runs tests, typecheck or lint is refused.</li>
       <li><b>The core journey and the upgrade users take.</b> Each app names the one flow a user cannot live without, end to end on the real target; an app users install also proves the upgrade over its last release, not only a fresh install.</li>
+      <li><b>The journeys your change needs.</b> <code>affected</code> maps a diff to the journeys it touches through the verify skill's feature map, runs the core journey when it cannot tell, and fails until a receipt for the commit covers them.</li>
       <li><b>Tied to a commit.</b> Every run records the commit, and whether there were uncommitted changes.</li>
       <li><b>Real media.</b> Empty, cut-off, blank or tiny screenshots fail. Videos must hold real frames.</li>
       <li><b>Fresh, and not reused.</b> Proof from an older commit fails, and so does proof reused for a different claim.</li>

package/docs/reference.md

@@ -1,6 +1,6 @@
 # done-done reference
 
-Everything `init`, `doctor`, `run`, `check`, `receipt` and the config files do. For the overview and quick start, see the [README](../README.md).
+Everything `init`, `doctor`, `run`, `affected`, `check`, `receipt` and the config files do. For the overview and quick start, see the [README](../README.md).
 
 ## Install
 
@@ -97,6 +97,8 @@ journeys:
     command: node scripts/capture-review.mjs --out $DONE_DONE_EVIDENCE_ROOT
 ```
 
+The script saves its captures into that folder and writes `steps.json` beside them: the target version, start state, user steps and end result ([Step record](#step-record)).
+
 Then run it:
 
 ```sh
@@ -255,9 +257,30 @@ A command is **code-only** when every step in it (split on `&&`, `||`, `;`, `|`
 
 - `init --journey` refuses a code-only command (exit 2, nothing written), and `init`'s verify skill refuses a code-only launch or feature drive.
 - `check` and `receipt` stop before the judge (exit 2) when every journey in `.done-done.yaml` is code-only, naming them, or when every cited capture comes from a code-only run, naming its journey or command. A test log cited beside real captures is fine: they carry the proof.
-- A receipt records the run behind each cited capture (`runs`), so `receipt --verify` and `gate` apply the same rule with no config: a receipt whose runs are all code-only, or one with no `runs` (written before this rule), fails.
+- A receipt records the run behind each cited capture (`runs`), so `receipt --verify` and `gate` apply the same rule with no config (and the [step record](#step-record) rule after it): a receipt whose runs are all code-only, or one with no `runs` (written before this rule), fails.
 - `doctor`'s `real_product` row is `missing` (and doctor exits 2) when every journey is code-only, and a `warning` naming the code-only journeys beside real ones.
 
+### Step record
+
+A capture shows a screen; the **step record** says what a user did to reach it. Every journey (and every agent drive) writes `steps.json` into its run folder, `$DONE_DONE_EVIDENCE_ROOT`, beside the captures:
+
+```json
+{
+  "target": { "version": "0.6.0" },
+  "start": "a fresh host with no paired phone",
+  "steps": ["pair the phone", "open a pane", "type `echo hi`"],
+  "result": "the pane shows hi on its own line"
+}
+```
+
+`target.version` is the version of the app driven, `start` the state it began from (for an upgrade journey: the previous version installed), `steps` the steps a user takes, in order, and `result` what a user can see at the end. All four are required; a file that is not JSON or lacks one is recorded as invalid. `run` and `verify` read the file when the run closes and keep it in the run record (`steps`, with `tool`, the done-done version that recorded the run, and `steps_error` when the file is invalid); it is a record, not a capture, so it is not listed in the run's files and the judge never reads it. A journey writes it as it drives, from what it really did, never from the claim.
+
+The check reads the claim against the record, with no model: at least half of the claim's words (four letters or more, without scaffolding such as `user`, `can`, `now`, `works`) must appear in the record's `start`, `steps` and `result`, matching word beginnings (`attach`, `attaches`, `attached`), and at least one of them in `result`. This runs after the code-only rule, which stays the first filter, and with it:
+
+- `check` and `receipt` stop before the judge (exit 2) when no cited capture comes from a run (not code-only) whose step record covers the claim, naming each run and the words its record never mentions. A log from a wrapper script whose record says `ran the unit suite` cannot satisfy a claim about attaching to a pane; a real CLI transcript whose record names the command and its output still satisfies a claim about that command. A cited run with no step record, or an invalid one, is refused the same way, with the shape to write.
+- A receipt keeps each run's step record (`runs[].steps`), so `receipt --verify` and `gate` apply the same rule to the receipt's claim with no config or evidence: a receipt whose runs have no covering record fails.
+- A run recorded before step records existed (its run record has no `tool`, or a receipt run has none) keeps working: `check`, `receipt`, `receipt --verify` and `gate` still pass, but say so in `warnings` (`gate` prints `WARN: ...` after `PASS`): re-run the journey so it writes `steps.json`.
+
 ### Core journey and release path
 
 A proof that drives some feature of the app does not show the app works when the one flow users need is broken, and a release proven by a fresh install does not show the upgrade users take works. So each app names two journeys, and `init`, `doctor` and the verify skill share one model-free rule for them (`src/proof.ts`).
@@ -276,6 +299,22 @@ journeys:
     upgrade: true
 ```
 
+### Affected journeys
+
+```sh
+done-done affected            # the change since the last receipt, else since the default branch
+done-done affected origin/main
+```
+
+`affected [<base>]` says which journeys a change needs and whether HEAD's proof covers them. It is model-free and reads git, `.done-done.yaml` and the verify skill only.
+
+- **The change.** The files that differ from `<base>`, else from the newest receipt whose head is before HEAD (the commits since the last proof), else from the merge base with the default branch (`origin/HEAD`, `origin/main`, `origin/master`, then the local `main` or `master`, the order the [Firstmate merge gate](../README.md#use-with-firstmate-or-another-agent-fleet) uses), plus uncommitted changes to tracked files. Untracked files are not part of the change until added. A file that matches `evidence.ignore_paths`, or a committed receipt under `.done-done-receipts/` ([CI gate](#ci-gate)), needs nothing.
+- **The mapping.** A journey is needed when its command runs the changed file (`node journeys/e2e.mjs` runs `journeys/e2e.mjs`). A feature of the verify skill (`features/<name>.md`) is needed when its file cites the changed file: a repo path, a markdown link (read from the feature's folder), a folder written with a slash (`src/` covers every file under it) or a bare file name, which matches each tracked file of that name as `maintain` reads one; or when the feature file itself changed. The skill's `SKILL.md` and `features/README.md` are what every feature follows, so a change to them needs every feature. A needed feature brings each journey it names (`run <journey>` or `verify <journey>` in its text, or a file the journey's command runs that it cites too); a feature that names no journey is driven by your agent: `done-done verify --feature <name>`. A code-only journey ([Real-product evidence](#real-product-evidence)) is never needed.
+- **Uncertain means more, never less.** A changed file that no feature or journey covers, or no base to diff against, makes the mapping uncertain: the core journey ([Core journey and release path](#core-journey-and-release-path)) is needed too, or the feature the feature map marks `(core journey)`, or every journey when none is named. Each such file is listed under `unmapped` and flagged in `help`: add it to the feature file that drives it (`done-done maintain` reports recent files no feature covers), or record a journey for it.
+- **The proof.** `fresh` (exit 0) when the receipt for HEAD verifies ([Record a receipt](#record-a-receipt)), its `runs` include a run of every needed journey (by name, or by the journey's command) and every needed feature (a `verify --feature` drive, which the receipt records as the run's `feature`), and no tracked file has an uncommitted change. Otherwise exit 1: `stale` when the newest receipt is for an earlier commit (it names that commit and the journeys the new commits need), when the receipt for HEAD misses a needed journey or feature, or when there are uncommitted changes; `missing` when there is no receipt at all. `help` gives the commands that capture the missing proof (`done-done run <journey>`, `done-done verify --feature <name>`), then the receipt step.
+
+The result lists the base and where it came from, the changed files (`--full` for more than five), each needed journey and feature with why (the first three reasons; `--full` for all), the unmapped files and the fallback. Bare `done-done` adds an `affected` block with the proof and the journeys still needed whenever the proof is not fresh, so every [session hook](#set-up-a-repo) shows them with no extra call. A `<base>` that is not a commit is a usage error (exit 2).
+
 ### Check a claim
 
 ```sh
@@ -317,7 +356,7 @@ A plain check is never a verdict on its own. A cited file that fails one of thes
 
 Files that are in no run record give an inconclusive result when another cited capture is one the judge reads: nothing ties them to a commit. So does a file that more than one run record claims when none of those runs is at the current commit (possible only with records from before each run had its own folder). Byte-identical captures from several runs are fine when one of those runs is at the current commit: that run ties the file to the commit. A file whose path is named in a run record but whose bytes no longer match fails as `changed after run <run-id>` (exit 2, before the judge), not inconclusive: the path ties it to that run, so editing it after the run is tampering, not untied evidence.
 
-A config whose journeys are all code-only, or cited captures that all come from code-only runs, stop the check the same way, before the judge, naming the journeys ([Real-product evidence](#real-product-evidence)).
+A config whose journeys are all code-only, or cited captures that all come from code-only runs, stop the check the same way, before the judge, naming the journeys ([Real-product evidence](#real-product-evidence)). So does a claim that no cited run's step record covers ([Step record](#step-record)).
 
 `evidence: not proven: <cause>` stops the check before its judge is asked, always: exit 2, no result, no receipt. `checks.not_proven` is gone: a config that still sets it is a config error (exit 2) that says to delete the line.
 
@@ -413,7 +452,7 @@ done-done receipt --verify <head>         # read-only: check a recorded receipt
 
 `receipt` takes the same claim inputs as `check` and runs that check. It writes `<root>/.done-done/receipts/<head>.json` only when the check passes on the current HEAD, the tracked tree is clean, and the check cited at least one evidence file; a dirty tracked tree, a failed or inconclusive check, a pass that cited no evidence, or a moved HEAD writes nothing and exits non-zero. The record holds the repo, the head and tree sha, the claim outcome, every cited file with its sha256, the run behind each cited capture (`runs`: run id, journey and command, the command `null` for a run opened by hand or driven by the agent) and a timestamp. Every receipt is schema 2 and holds a `judge` block: the route, model, independence and author, and each judged file's path, sha256 and verdict. A cited file is stored relative to the repo, or as `<evidence root>/<path>` when it is under an evidence root outside the repo, so the receipt still finds it from another checkout or a restored evidence root.
 
-`receipt --verify <head>` changes nothing. The argument may be a full commit sha or a ref (`HEAD`, a branch or a tag), resolved to the commit with `git rev-parse --verify <arg>^{commit}` before the receipt lookup; an unresolvable argument fails with the same missing-receipt shape. It succeeds only when the receipt exists, is PASS, the current HEAD is still that head, and every cited file still hashes to the recorded sha256. A receipt is written only after a judge pass, so it reads schema 2 only: any other receipt (one recorded without the judge, or by an older build that let a run past its gate) fails as malformed, and a schema 2 receipt needs a well-formed `judge` block whose every verdict is `pass` for a cited file with the same sha256, which the result shows, and `runs` that are not all code-only ([Real-product evidence](#real-product-evidence)); a receipt with no `runs`, written before that rule, fails: re-run `receipt` for the head. A receipt from `--from` (or a `verify` run that drove the skill) also records the verify skill that ran as `skill` (for example `done-done-verify-<app>`), which `--verify` and so the merge gate show; an older receipt without it still verifies. A missing or malformed receipt and a hash mismatch are failures (exit 1), not usage errors. When the mismatched path is named in a run record, the failure names it as `changed after run <run-id>`.
+`receipt --verify <head>` changes nothing. The argument may be a full commit sha or a ref (`HEAD`, a branch or a tag), resolved to the commit with `git rev-parse --verify <arg>^{commit}` before the receipt lookup; an unresolvable argument fails with the same missing-receipt shape. It succeeds only when the receipt exists, is PASS, the current HEAD is still that head, and every cited file still hashes to the recorded sha256. A receipt is written only after a judge pass, so it reads schema 2 only: any other receipt (one recorded without the judge, or by an older build that let a run past its gate) fails as malformed, and a schema 2 receipt needs a well-formed `judge` block whose every verdict is `pass` for a cited file with the same sha256, which the result shows, and `runs` that are not all code-only ([Real-product evidence](#real-product-evidence)) and carry a step record covering the claim ([Step record](#step-record); a run recorded before step records passes with a `warnings` entry); a receipt with no `runs`, written before that rule, fails: re-run `receipt` for the head. A receipt from `--from` (or a `verify` run that drove the skill) also records the verify skill that ran as `skill` (for example `done-done-verify-<app>`), which `--verify` and so the merge gate show; an older receipt without it still verifies. A missing or malformed receipt and a hash mismatch are failures (exit 1), not usage errors. When the mismatched path is named in a run record, the failure names it as `changed after run <run-id>`.
 
 ### Verify a change in one run
 
@@ -503,7 +542,7 @@ The result is `clean` (no findings but notices, exit 0), `drift` (findings to fi
 
 Every command prints one machine-readable result on stdout. By default it is [TOON](https://github.com/toon-format/spec) in the AXI convention (the shape `no-mistakes axi status` uses): scalar `key: value` lines, tabular arrays, and a `help` list that names the exact next command. `--json` prints the same result as JSON. `--full` lists every evidence file or finding; without it, lists longer than five rows are truncated and the count of dropped rows is reported (`evidence_omitted`, `findings_omitted`, `history_omitted` or `log_omitted`). `doctor` always lists every check: its rows (eight checks, nine with --probe, plus `tool_gate` when the agent is pi or codex) never truncate.
 
-Running `done-done` with no subcommand prints the repo's config state (`config: present | missing | none`), its journeys, its run count (the runs `history` lists), whether `HEAD` has a valid receipt (`receipt: valid for HEAD <sha>`, or why not), and the next step; with a valid receipt the next step is to prove the next commit. `done-done --version` prints the version. Usage and config errors also print one result: the `command` that failed, an `error` field and a `help` line with the recovery command (for example `done-done init` when no config exists, or the command's valid flags after an unknown one).
+Running `done-done` with no subcommand prints the repo's config state (`config: present | missing | none`), its journeys, its run count (the runs `history` lists), whether `HEAD` has a valid receipt (`receipt: valid for HEAD <sha>`, or why not), when the proof is not fresh the journeys the change still needs (`affected`, see [Affected journeys](#affected-journeys)), and the next step; with a valid receipt that covers them the next step is to prove the next commit. `done-done --version` prints the version. Usage and config errors also print one result: the `command` that failed, an `error` field and a `help` line with the recovery command (for example `done-done init` when no config exists, or the command's valid flags after an unknown one).
 
 `done-done --help` lists every command. `done-done <command> --help` (or `-h`) prints that command's usage lines and flags in the same shape for every command (plus the journey format for `init` and `run`, and the Checks block for `check` and `receipt`), and exits 0.
 
@@ -546,11 +585,11 @@ npx -y done-done-axi gate "$PR_HEAD_SHA"
 
 The receipt is committed in a follow-up commit, because a receipt cannot sit inside the commit it proves (its hash would change). `gate [<head>] [--dir <folder>] [--pushed <time>]` prints `PASS` or `FAIL: <reason>` and exits 0, 1, or 2 on a usage error. It passes when a receipt in `.done-done-receipts/` (or `--dir`):
 
-- is a well-formed pass from a judged run (the same shape `receipt --verify` requires, so its `runs` are not all code-only, see [Real-product evidence](#real-product-evidence)) and is filed as `<its head>.json`;
+- is a well-formed pass from a judged run (the same shape `receipt --verify` requires, so its `runs` are not all code-only, see [Real-product evidence](#real-product-evidence), and carry a step record covering its claim, see [Step record](#step-record)) and is filed as `<its head>.json`;
 - has a head that is `<head>` (default `HEAD`) or an ancestor of it, with every file changed since that head inside the receipts folder, so the proof still covers the code;
 - was made no later than the push (`--pushed`, an ISO time; default the commit time of `<head>`), compared to the second.
 
-`gate` trusts the committed JSON: it does not re-hash the evidence, which only `receipt --verify` can do, on the machine that holds it. It says so by name and does not claim more.
+A receipt whose runs were recorded before step records passes with `WARN: ...` lines after `PASS`. `gate` trusts the committed JSON: it does not re-hash the evidence, which only `receipt --verify` can do, on the machine that holds it. It says so by name and does not claim more.
 
 ### Where proof lives
 

package/integrations/firstmate/brief-include.md

@@ -15,8 +15,11 @@ wherever this text or the skill says `done-done`. If done-done cannot run, repor
    installs the previous release and upgrades over it in place before it drives the core journey; `done-done doctor`
    fails until both are named. Commit `.done-done.yaml` and the journey script. If `init` says no agent is set, ask the user which agent
    and model to use and run the command it prints; never choose one yourself.
-2. Commit your change, then run `done-done run <journey>` from the repo root. Proof only counts from a clean,
-   committed tree.
+2. Commit your change, then run `done-done affected` from the repo root: it lists the journeys and verify-skill
+   features your diff needs (the core journey when it cannot tell). Run each listed journey with
+   `done-done run <journey>` and drive each listed feature with `done-done verify --feature <name>`. Proof only counts
+   from a clean, committed tree. When it flags files that no feature or journey covers, cite them in the feature file
+   that drives them (or record a journey for them) and commit that too.
 3. Write a Checks block (the shape `done-done --help` prints) that cites the run's files by the paths `run` printed:
    ```
    ## Checks
@@ -37,4 +40,5 @@ wherever this text or the skill says `done-done`. If done-done cannot run, repor
 
 Exit 1 (fail), 2 (stopped before a verdict) or 3 (inconclusive) is never done: fix the proof and re-run, or report what done-done found.
 `evidence: not proven: <cause>` stops `check` with exit 2 before the judge is asked, with no result and no receipt: report the task as not proven, never as done.
-Any commit after the receipt makes the proof stale: run, check and receipt again on the new head.
+Any commit after the receipt makes the proof stale: run, check and receipt again on the new head. Before you report
+done, `done-done affected` must exit 0: the receipt for your head covers every journey the change needs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
   "type": "module",

package/skills/done-done/SKILL.md

@@ -41,6 +41,9 @@ driven end to end on the real target (for a remote terminal: pair, open a pane,
 does not show the app works. An app that ships something users install and upgrade (an npm CLI, an Android app, a host service) also
 names an upgrade journey (`--upgrade`): install the previous release, upgrade over it in place, then drive the core journey; a fresh
 install alone is not release proof. `doctor` fails until both are named.
+To know which journeys a change needs, run `done-done affected` after you commit: it maps the diff through the verify skill's feature map
+(the paths each feature cites, the journeys it names), adds the core journey when a changed file is in no feature or journey (never fewer),
+and exits 1 until the receipt for HEAD has a run of each. Cite a file it flags in the feature file that drives it.
 A run waiting at its judge gate (`awaiting_approval`) did not pass, and nothing moves it past its judge: show the user
 its findings and captures, and end it with `done-done respond --action fix` only when they say so.
 A journey that `spends` runs only after the user approves spending: `done-done run <journey>` refuses it, so ask the user and use `verify`.