done-done-axi 0.5.1 → 0.5.2

package/README.md

@@ -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,6 +21,7 @@ import { domIssues, domRecord, isDomRecord, lookIssues, SQUASHED_TEXT } from './
 import { lint } from './lint.js';
 import { look } from './look.js';
 import { scanSecrets } from './secrets.js';
+import { mapChange } from './affected.js';
 import { codeOnly, codeOnlyJourneys, configFault, MARK, namedJourney, releaseArtifacts, RULE, runsFault } from './proof.js';
 const PASS = 0, FAIL = 1, USAGE = 2, INCONCLUSIVE = 3, WAITING = 4;
 // The shape of a journey, so a new user or agent can write one without opening the reference.
@@ -237,6 +238,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"]],
@@ -788,7 +802,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 }) });
         // 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)
@@ -1506,12 +1520,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}`
@@ -3759,6 +3775,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 +3920,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 +3986,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')

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
 
@@ -276,6 +276,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
@@ -503,7 +519,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.
 

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.5.2",
   "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`.