done-done-axi 0.5.0 → 0.5.2

package/README.md

@@ -126,23 +126,26 @@ done-done init
 journeys:
   smoke:
     command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log
+    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)).
 
+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)).
+
 Optional: `done-done init --hook <claude|codex|opencode|gemini|pi>` adds a session hook or plugin to the repo that shows each session the bare `done-done` state. Each agent's file and behavior are in the [reference](docs/reference.md#set-up-a-repo).
 
 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 -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
+done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
 git add .done-done.yaml
 git commit -m "Add done-done"
 ```
 
 A `run -- <command>` whose command matches no recorded journey still runs, but its result hints that the recipe is not in the repo. For a proof you drive by hand or by your agent instead of a journey, `done-done run --open` prints a run id and a folder to capture into, and `done-done run --close <run-id>` seals it ([how](docs/reference.md#run-a-journey)).
 
-At any point, `done-done doctor` checks the setup and changes nothing except the `--probe` call record. Each item reports `ok`, `warning` or `missing` with the exact fix command; an agent you have not set yet is `missing`, with the command that saves your choice, and so is a config whose journeys only run code checks. `done-done doctor --probe` also asks the agent one question to prove it answers; on a new machine that probe fails until the agent is signed in (for pi, run `pi` and then `/login`). The quick start above never calls the coding agent, so `run` and `check` work before it is signed in; `check` does call the judge, so set one first. The items are listed in the [reference](docs/reference.md#check-the-setup).
+At any point, `done-done doctor` checks the setup and changes nothing except the `--probe` call record. Each item reports `ok`, `warning` or `missing` with the exact fix command; an agent you have not set yet is `missing`, with the command that saves your choice, and so is a config whose journeys only run code checks, one that names no core journey, or an app that ships an installable artifact with no upgrade journey. `done-done doctor --probe` also asks the agent one question to prove it answers; on a new machine that probe fails until the agent is signed in (for pi, run `pi` and then `/login`). The quick start above never calls the coding agent, so `run` and `check` work before it is signed in; `check` does call the judge, so set one first. The items are listed in the [reference](docs/reference.md#check-the-setup).
 
 `done-done maintain` keeps the verify skill true: it checks the skill's links and feature index, checks that every `file:line` it cites exists, and has your coding agent read the source for each feature, read-only, to report drift. It ends `clean`, `drift` with the findings to fix, or `blocked`. It never runs without that reader: an agent that is not set asks, and one that cannot start or cannot read without tools stops it before the run (exit 2). With `auto_fix: { maintain: <n> }` (as in no-mistakes; 0, the default, reports only), your judge first sorts each drift finding (a skill out of date, or a product that may be wrong, which stops and asks you), then your agent fixes the skill folder only, in a done-done worktree, and maintain runs again, up to n times. A clean end is `changed`: one commit on a `done-done/maintain-<run-id>` branch, your branch untouched ([reference](docs/reference.md#keep-the-verify-skill-true)).
 
@@ -155,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
@@ -173,6 +178,8 @@ Run `done-done` with no arguments to see the current config and the next step.
 ## What it checks
 
 - 🧪 **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.
@@ -212,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.
@@ -226,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,16 +21,23 @@ 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, RULE, runsFault } from './proof.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.
 // 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 real app> > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log" } }';
+const journeyExample = 'journeys: { smoke: { command: "<drive the core user journey on the real app> > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log", core: true } }';
 const JOURNEYS_TEXT = `journeys (.done-done.yaml): the command runs with DONE_DONE_EVIDENCE_ROOT (this run's own new folder in the evidence
   root) and DONE_DONE_RUN_ID set, and \${RUN_ID} in it is replaced; it must write its files into that folder, e.g.
   ${journeyExample}
-  real product: a journey whose command only runs tests, typecheck, lint or a build (npm test, yarn run check, tsc, pytest) is code-only;
+  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
+  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
+  core journey; doctor requires one when a tracked file shows the app ships an installable artifact (an npm package with a bin, an Expo or Android app,
+  Python console scripts, a Rust [[bin]], goreleaser, a systemd service), since a fresh install alone is no release proof
   spends (journeys.<name>.spends): what a run spends, e.g. "one live generation"; verify parks the journey until the user approves that run (respond --action approve)
   timeout (journeys.<name>.timeout): how long a verify run may drive the journey, e.g. 90s or 30m (default 30m); past it the journey is killed and the run is inconclusive
   matrix (.done-done.yaml): with theme, width or form axes the journey runs once per required cell with DONE_DONE_THEME, DONE_DONE_WIDTH, DONE_DONE_FORM and DONE_DONE_CELL (the capture name suffix) set; name each capture with its suffix, so every cell is captured or skipped with a reason`;
@@ -75,7 +82,9 @@ const DOCTOR_TEXT = `doctor changes nothing except the --probe call record (the
   set and its model; missing when none is set, with the command that saves the user's choice), judge (the judge route is ready:
   for claude-code an executable claude binary and the judge kit, for answerer:<agent> that agent's CLI and the
   kit, for a key route (openai:key, minimax:key) its API key and the kit; doctor does not call the model; missing when none is set, with the command
-  that saves the user's choice).
+  that saves the user's choice),
+  core_journey (a journey with core: true that drives the product, or a "(core journey)" entry in the verify skill's features/README.md),
+  upgrade_journey (when a tracked file shows the app ships an installable artifact, a journey with upgrade: true or an "(upgrade journey)" entry).
   also listed: verify_skill (.agents/skills/done-done-verify-<app>/), agent_settings (agent, model, effort,
   args, path and agent_timeout, each with the file it came from: the global config, .done-done.yaml or default),
   judge_choice (the judge, and how far it is from the author: another agent, another model, or session-only), ffprobe (video evidence only).
@@ -92,6 +101,8 @@ const CONFIG_TEXT = `config: ~/.done-done/config.yaml (global; DONE_DONE_HOME mo
 const FLAGS = {
     '-- <command...>': 'run this command instead of a journey; ${RUN_ID} in it becomes the run id',
     '--journey <name>': 'record this command as a journey in .done-done.yaml; ${RUN_ID} in it becomes the run id',
+    '--core': 'with --journey: mark it the core user journey (core: true), the one thing a user cannot live without, driven end to end on the real target',
+    '--upgrade': 'with --journey: mark it the upgrade journey (upgrade: true): install the previous shipped version, upgrade over it in place, then drive the core journey',
     '--open': 'open a run for a hand- or agent-driven proof; prints its id and folder',
     '--close <run-id>': 'seal an open run and record the files in its folder',
     '--outcome "<claim>"': 'the outcome the evidence files prove; the files follow as arguments',
@@ -134,8 +145,10 @@ const COMMANDS = {
             ['done-done init --hook pi', 'also add this repo\'s done-done state to the first prompt of each pi session'],
             ['done-done init --hook gemini', 'also show this repo\'s done-done state at each Gemini CLI session start'],
             ['done-done init --journey <name> -- <command...>', "record a journey's capture recipe in .done-done.yaml"],
+            ['done-done init --journey <name> --core -- <command...>', 'record the core user journey: the one thing a user cannot live without, end to end on the real target'],
+            ['done-done init --journey upgrade --upgrade -- <command...>', 'record the release path: install the previous shipped version, upgrade over it in place, drive the core journey'],
         ],
-        flags: ['--agent <agent>', '--model <model>', '--judge <agent>', '--judge-model <model>', '--hook <agent>', '--journey <name>', '-- <command...>'],
+        flags: ['--agent <agent>', '--model <model>', '--judge <agent>', '--judge-model <model>', '--hook <agent>', '--journey <name>', '--core', '--upgrade', '-- <command...>'],
         more: [JOURNEYS_TEXT, CONFIG_TEXT],
     },
     doctor: {
@@ -225,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"]],
@@ -311,6 +337,20 @@ function cap(items) {
 }
 // A hint that names the exact command that moves the work forward, naming the journey when there is one.
 const RECORD_REAL = "done-done init --journey <name> -- '<command that drives the real app and saves screenshots, a recording or its transcript into $DONE_DONE_EVIDENCE_ROOT>'";
+const CORE_FIX = "Name the core user journey, the one thing a user cannot live without, driven end to end on the real target: done-done init --journey <name> --core -- '<command that drives it and saves its captures into $DONE_DONE_EVIDENCE_ROOT>'";
+const UPGRADE_FIX = "Record the release path users take: done-done init --journey upgrade --upgrade -- '<command that installs the previous shipped version, upgrades over it in place, then drives the core journey>'";
+// The verify skill's feature map, where a journey-less repo names its core and upgrade journeys; '' when there is none.
+const featureMap = (repo, cfg) => repoText(join(repo, cfg.skill, 'features', 'README.md')) ?? '';
+// What shows this repo ships an installable or upgradable artifact (src/proof.ts releaseArtifacts), from its tracked files.
+function shipped(repo) {
+    const files = execFileSync('git', ['ls-files', '-z'], { cwd: repo, encoding: 'utf8', maxBuffer: Infinity, stdio: ['ignore', 'pipe', 'pipe'] }).split('\0').filter(Boolean);
+    return releaseArtifacts(files, (f) => repoText(join(repo, f)));
+}
+// The fixes for a core or upgrade journey this repo does not name yet, as doctor's rows ask for them.
+const journeyAsks = (repo, cfg) => {
+    const map = featureMap(repo, cfg);
+    return [...(namedJourney('core', cfg.journeys, map) ? [] : [CORE_FIX]), ...(namedJourney('upgrade', cfg.journeys, map) || !shipped(repo).length ? [] : [UPGRADE_FIX])];
+};
 // A code-only journey is never named: its run is no proof.
 function captureHint(cfg) {
     const code = codeOnlyJourneys(cfg.journeys);
@@ -762,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)
@@ -1480,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}`
@@ -2499,7 +2541,7 @@ const SCAFFOLD_SCHEMA = {
         harness: STR,
         observe: STR,
         isolate: STR,
-        features: { type: 'array', minItems: 1, items: { type: 'object', properties: { title: STR, reach: STR, drive: STR, source: STR, capture: { type: 'string', enum: ['screenshot', 'text'] } }, required: ['title', 'reach', 'drive', 'source', 'capture'], additionalProperties: false } },
+        features: { type: 'array', minItems: 1, items: { type: 'object', properties: { title: STR, reach: STR, drive: STR, source: STR, capture: { type: 'string', enum: ['screenshot', 'text'] }, core: { type: 'boolean' }, upgrade: { type: 'boolean' } }, required: ['title', 'reach', 'drive', 'source', 'capture', 'core', 'upgrade'], additionalProperties: false } },
     },
     required: ['surface', 'launch', 'ready', 'harness', 'observe', 'isolate', 'features'],
     additionalProperties: false,
@@ -2562,7 +2604,7 @@ function repoContext(repo, skill) {
     const out = left.length ? `\n\n[left out: ${left.length} files cannot be read or pass the ${CONTEXT_CHARS}-character cap: ${left.slice(0, 20).join(', ')}${left.length > 20 ? `, +${left.length - 20} more` : ''}]` : '';
     return { files: new Set(files), read, text: `${list}\n\n${parts.join('\n\n')}${out}` };
 }
-function scaffoldPrompt(cfg, context, toolless) {
+function scaffoldPrompt(cfg, context, toolless, ships) {
     return `You write the verify skill for the app ${cfg.app}, which \`done-done init\` saves at ${cfg.skill}: how an agent launches this repo's app safely, drives it the way a user does, and captures proof that it works. Do not edit, create or delete any file, and do not run the app or any command.
 ${toolless ? "You have no tools: the repo's tracked file list and the text of its key files are below, and they are all you can read." : 'The repository is your working directory: read the files below first, then any other file you need.'} Use only what the repo shows: never invent a command, path, flag, route or label. Never open a secret-looking file: a .env or .env.* file, a path whose name contains secret, credential, token or password, or a *.pem, *.key or *.p12 file. Never write a secret value into steps or why; name the environment variable instead.
 
@@ -2573,14 +2615,16 @@ A proof drives the running product the way a user does: a test suite, typecheck,
 - harness: what drives it: a browser tool, a terminal (tmux or PTY), curl, or a shell.
 - observe: the proof to capture: screenshots of the resulting state, terminal transcripts and exit codes, response bodies, files written.
 - isolate: how each run keeps its own instance and state, and never drives a session or account the user owns.
-- features: up to ${MAX_FEATURES} things a user does with the app, the most important first, each {title, reach: how a user gets there, drive: the concrete steps through the repo's real handles (the command and its arguments, the route, the page label, the journey name), source: the repo file that shows the feature, capture: screenshot for a screen, text for output}.
+- features: up to ${MAX_FEATURES} things a user does with the app, the most important first, each {title, reach: how a user gets there, drive: the concrete steps through the repo's real handles (the command and its arguments, the route, the page label, the journey name), source: the repo file that shows the feature, capture: screenshot for a screen, text for output, core, upgrade}.
+- core: true on exactly one feature, listed first: the core user journey, the one thing a user cannot live without, driven end to end on the real target the way a user does it (for a remote terminal app: pair, open a pane, type, see the output), never a part of it or a setting. Every other feature has core false.
+${ships.length ? `- upgrade: this app ships an installable or upgradable artifact (${ships.slice(0, 3).join('; ')}), so users get each release by upgrading over the version they have. Set upgrade true on one feature whose drive installs the previous shipped version, upgrades over it in place the way a user does (install the new APK over the old one, update the host or CLI package in place), then drives the core journey; a fresh install alone is no release proof. It may be the core feature itself when its drive does all of that.` : '- upgrade: false on every feature: no tracked file shows the app ships an installable or upgradable artifact.'}
 Each source is one path exactly as the tracked file list spells it, with no other words (scripts/verify/drive.sh, never a list or a note); launch.source may be empty only when safe is false.
 
 ${context}`;
 }
 // Why an answer cannot be rendered into the skill, or '' when it can. A citation must be a tracked file the agent was
 // shown: shown is every tracked file for claude, which reads the repo itself, and the text plain code gave a tool-less agent.
-function scaffoldProblem(a, tracked, shown) {
+function scaffoldProblem(a, tracked, shown, ships) {
     const s = a;
     const text = (v) => typeof v === 'string' && clause(v) !== '';
     const citation = (p) => {
@@ -2604,24 +2648,34 @@ function scaffoldProblem(a, tracked, shown) {
     if (!Array.isArray(s.features) || !s.features.length)
         return 'has no features';
     for (const f of s.features) {
-        if (!f || typeof f !== 'object' || !text(f.title) || !text(f.reach) || !text(f.drive) || !text(f.source) || !['screenshot', 'text'].includes(f.capture))
-            return 'has a feature without a title, reach, drive, source or capture';
+        if (!f || typeof f !== 'object' || !text(f.title) || !text(f.reach) || !text(f.drive) || !text(f.source) || !['screenshot', 'text'].includes(f.capture) || typeof f.core !== 'boolean' || typeof f.upgrade !== 'boolean')
+            return 'has a feature without a title, reach, drive, source, capture, core or upgrade';
         const why = citation(f.source);
         if (why)
             return `the feature "${f.title}" ${why}`;
         if (codeOnly(f.drive))
             return `the feature "${f.title}" drive ${f.drive.trim()} is code-only: ${RULE}`;
     }
+    // The skill lists the first MAX_FEATURES, so the core and upgrade features must be among them.
+    const kept = s.features.slice(0, MAX_FEATURES);
+    const cores = kept.filter((f) => f.core).length;
+    if (cores !== 1)
+        return `names ${cores} core journeys among its first ${MAX_FEATURES} features, and the skill needs exactly one: the one thing a user cannot live without, end to end on the real target`;
+    if (ships.length && !kept.some((f) => f.upgrade))
+        return `names no upgrade journey, and the app ships an installable artifact (${ships.slice(0, 3).join('; ')}): a fresh install alone is no release proof`;
     return '';
 }
-function verifySkillMd(app, agent, s, isolated, features, omitted) {
+function verifySkillMd(app, agent, s, isolated, features, omitted, ships) {
     const name = `done-done-verify-${app}`;
     const source = cited(s.launch.source);
     const launch = isolated
         ? `${s.launch.steps.trim()}\n\nSafe: ${clause(s.launch.why)} (from \`${source}\`).`
         : `Not isolated: ${clause(s.launch.why)}. The launch below is not shown to use a stub or demo engine with its own state, so it may use real accounts or the owner's own state. ${NO_EDIT}.\n\n${s.launch.steps.trim()}${source ? `\n\nFrom \`${source}\`.` : ''}`;
+    const core = features.find((f) => f.core);
+    const upgrade = features.find((f) => f.upgrade);
+    const link = (f) => `[${f.title}](features/${f.slug}.md)`;
     const found = [
-        ...features.map((f) => `- [${f.title}](features/${f.slug}.md): ${clause(f.reach)} (\`${cited(f.source)}\`)`),
+        ...features.map((f) => `- [${f.title}](features/${f.slug}.md)${marks(f)}: ${clause(f.reach)} (\`${cited(f.source)}\`)`),
         ...(omitted ? [`- ${omitted} more found and not listed; add them by hand or run maintain later.`] : []),
     ];
     return `---
@@ -2647,6 +2701,10 @@ Harness: ${clause(s.harness)}. Drive through the repo's real handles that each f
 
 ${found.join('\n')}
 
+## Core journey
+
+${link(core)} is the core user journey: the one thing a user cannot live without. A proof that the app works drives it end to end on the real target; a proof of another feature alone does not show the app works.
+${ships.length ? `\n## Release proof\n\nThis app ships an installable artifact (${ships.slice(0, 3).join('; ')}), and users get a release by upgrading over the version they have. ${link(upgrade)} is the release proof: install the previous shipped version, upgrade over it in place, then drive the core journey. A fresh install alone is no release proof.\n` : ''}
 ## Evidence
 
 What to capture: ${clause(s.observe)}. Exercise the real user path, not internal setters; done-done's judge checks every capture in the run folder against the outcome, so save only captures of the resulting state there and keep any of earlier steps outside it; verify side effects alongside what is visible. Evidence goes to the run folder \`done-done run\` prints.
@@ -2661,8 +2719,10 @@ function verifyFeatureMd(app, s, f) {
     const drive = clause(f.drive);
     return `# ${f.title}\n\nPart of the ${app} verification map. Source: \`${cited(f.source)}\`.\n\n## How to get to it (user POV)\n\n${clause(f.reach)}.\n\n## Driving it\n\nHarness: ${clause(s.harness)}.\n\n1. Launch the app as SKILL.md says and wait until it is ready.\n2. ${drive[0].toUpperCase()}${drive.slice(1)}.\n3. Capture: ${capture}, as SKILL.md's Evidence section says.\n4. Stop what you started.\n\n${NO_EDIT}.\n`;
 }
+// An entry's role marks, the text doctor reads (src/proof.ts namedJourney).
+const marks = (f) => `${f.core ? ` ${MARK.core}` : ''}${f.upgrade ? ` ${MARK.upgrade}` : ''}`;
 function verifyFeaturesMd(app, features, omitted) {
-    const index = features.map((f) => `- [${f.title}](${f.slug}.md): ${clause(f.reach)}`).join('\n');
+    const index = features.map((f) => `- [${f.title}](${f.slug}.md)${marks(f)}: ${clause(f.reach)}`).join('\n');
     const more = omitted ? `\n\n${omitted} more found and not listed; add them by hand or run maintain later.` : '';
     return `# ${app} features\n\nThe repo's maintained verification map; a proof that drives one entry point is incomplete when this lists others.\n\n${index}${more}\n`;
 }
@@ -2729,11 +2789,12 @@ async function scaffoldVerify(repo, cfg) {
     if (!context.files.size)
         return { status: "not written: the repo has no tracked files to cite; commit the repo's files, then re-run init", failed: true };
     const record = join(home(), 'agents', `init-${new Date().toISOString().replace(/[:.]/g, '-')}-${agent.agent.replace(/[^\w-]/g, '-')}.json`);
-    const a = await askAgent({ ...agent, prompt: scaffoldPrompt(cfg, context.text, toolless), schema: SCAFFOLD_SCHEMA, cwd: repo, tools: toolless ? 'none' : 'read', record });
+    const ships = shipped(repo);
+    const a = await askAgent({ ...agent, prompt: scaffoldPrompt(cfg, context.text, toolless, ships), schema: SCAFFOLD_SCHEMA, cwd: repo, tools: toolless ? 'none' : 'read', record });
     const where = a.record ? `; record ${a.record}` : a.recordError ? `; the call record could not be written: ${a.recordError}` : '';
     if (!a.ok)
         return { status: `not written: ${agent.agent} did not answer: ${a.error}; done-done doctor --probe checks the agent${where}`, failed: true };
-    const problem = scaffoldProblem(a.answer, context.files, toolless ? context.read : context.files);
+    const problem = scaffoldProblem(a.answer, context.files, toolless ? context.read : context.files, ships);
     if (problem)
         return { status: `not written: ${agent.agent}'s answer is unusable: ${problem}${where}`, failed: true };
     const s = a.answer;
@@ -2750,7 +2811,7 @@ async function scaffoldVerify(repo, cfg) {
     const files = new Map([[join('features', 'README.md'), verifyFeaturesMd(cfg.app, features, omitted)]]);
     for (const f of features)
         files.set(join('features', `${f.slug}.md`), verifyFeatureMd(cfg.app, s, f));
-    files.set('SKILL.md', verifySkillMd(cfg.app, agent.agent, s, isolated, features, omitted));
+    files.set('SKILL.md', verifySkillMd(cfg.app, agent.agent, s, isolated, features, omitted, ships));
     const targets = [...files].map(([rel, body]) => ({ rel, p: join(dir, rel), body }));
     link = linked(targets.map(({ p }) => p));
     if (link !== undefined)
@@ -3120,7 +3181,7 @@ async function cmdInit(argv) {
     const dash = argv.indexOf('--');
     const { values } = parseArgs({
         args: dash < 0 ? argv : argv.slice(0, dash),
-        options: { agent: { type: 'string' }, model: { type: 'string' }, judge: { type: 'string' }, 'judge-model': { type: 'string' }, hook: { type: 'string' }, journey: { type: 'string' } },
+        options: { agent: { type: 'string' }, model: { type: 'string' }, judge: { type: 'string' }, 'judge-model': { type: 'string' }, hook: { type: 'string' }, journey: { type: 'string' }, core: { type: 'boolean' }, upgrade: { type: 'boolean' } },
         allowPositionals: false,
     });
     const parts = dash < 0 ? [] : argv.slice(dash + 1);
@@ -3135,6 +3196,8 @@ async function cmdInit(argv) {
         throw new UsageError('--judge-model needs --judge', `Run: done-done init --judge <agent> --judge-model ${values['judge-model']}`);
     if (journey === null && parts.length)
         throw new UsageError('init needs --journey <name> to record a command after --');
+    if (journey === null && (values.core || values.upgrade))
+        throw new UsageError(`--${values.core ? 'core' : 'upgrade'} marks the journey init records, so it needs --journey <name> and a command after --`, `Run: done-done init --journey <name> --${values.core ? 'core' : 'upgrade'} -- '<command>'`);
     if (journey !== null && !parts.some((p) => p.trim()))
         throw new UsageError(`init --journey ${journey} needs a command after --`);
     if (journey !== null && !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(journey))
@@ -3209,6 +3272,9 @@ async function cmdInit(argv) {
         if (top.journeys == null)
             doc.set('journeys', doc.createNode({}));
         doc.setIn(['journeys', journey, 'command'], command);
+        for (const role of ['core', 'upgrade'])
+            if (values[role])
+                doc.setIn(['journeys', journey, role], true);
         writeFileSync(`${file}.tmp`, doc.toString({ lineWidth: 0 }));
         renameSync(`${file}.tmp`, file);
         const fresh = loadConfig(repo);
@@ -3236,7 +3302,7 @@ async function cmdInit(argv) {
             ...(renamed && { skill_renamed: renamed }),
             verify_skill: verify.status,
             ...agentHook.out,
-            help: [`Capture proof: done-done run ${journey}, then: ${check}`, ...agentHook.help, ...ag.help, ...jg.help, ...(verify.failed ? [SCAFFOLD_HELP] : []), `Commit ${commitFirst(fresh.skill)}`],
+            help: [`Capture proof: done-done run ${journey}, then: ${check}`, ...journeyAsks(repo, fresh), ...agentHook.help, ...ag.help, ...jg.help, ...(verify.failed ? [SCAFFOLD_HELP] : []), `Commit ${commitFirst(fresh.skill)}`],
         });
         return code;
     }
@@ -3280,6 +3346,7 @@ app: ${JSON.stringify(cfg.app)}
             ...(Object.keys(cfg.journeys).length
                 ? [`Capture proof: ${captureHint(cfg)}, then: ${check}`]
                 : [`Add a journey that drives the real app and saves proof under $DONE_DONE_EVIDENCE_ROOT (each run's own folder in ${root}), e.g. ${journeyExample}`, `Then commit, run \`done-done run smoke\`, and: ${check}`]),
+            ...journeyAsks(repo, loadConfig(repo)),
             ...agentHook.help,
             ...ag.help,
             ...jg.help,
@@ -3521,7 +3588,25 @@ async function cmdDoctor(argv) {
             : code.length ? { check: 'real_product', status: 'warning', detail: `${code.join(', ')} ${code.length > 1 ? 'are' : 'is'} code-only (${RULE}): proof only from ${code.length > 1 ? 'them' : 'it'} is refused; ${names.filter((n) => !code.includes(n)).join(', ')} drive${names.length - code.length > 1 ? '' : 's'} the product`, fix: `Cite captures from the journeys that drive the product; delete ${code.join(', ')} from .done-done.yaml if it is not needed` }
                 : { check: 'real_product', status: 'ok', detail: names.length ? `${names.join(', ')} drive${names.length > 1 ? '' : 's'} the product` : 'no journeys: verify has the agent drive the verify skill\'s features', fix: '' });
     }
-    const required = ['git', 'config', 'evidence_root', 'real_product', 'agent', 'judge', ...(values.probe ? ['probe'] : [])];
+    // The core journey and, for an app that ships an installable artifact, the upgrade-in-place journey: named in config or the feature map.
+    if (!cfg || !repo) {
+        checks.push(unknownRow('core_journey'), unknownRow('upgrade_journey'));
+    }
+    else {
+        const map = featureMap(repo, cfg);
+        const core = namedJourney('core', cfg.journeys, map);
+        checks.push(core
+            ? { check: 'core_journey', status: 'ok', detail: `${core} is the core user journey`, fix: '' }
+            : { check: 'core_journey', status: 'missing', detail: `no core user journey is named: a journey with core: true that drives the product, or a ${MARK.core} entry in ${cfg.skill}/features/README.md`, fix: CORE_FIX });
+        const ships = shipped(repo);
+        const upgrade = namedJourney('upgrade', cfg.journeys, map);
+        checks.push(!ships.length
+            ? { check: 'upgrade_journey', status: 'ok', detail: 'no tracked file shows an installable or upgradable artifact, so no upgrade journey is needed', fix: '' }
+            : upgrade
+                ? { check: 'upgrade_journey', status: 'ok', detail: `${upgrade} upgrades in place (the app ships ${ships.slice(0, 3).join('; ')})`, fix: '' }
+                : { check: 'upgrade_journey', status: 'missing', detail: `the app ships an installable artifact (${ships.slice(0, 3).join('; ')}${ships.length > 3 ? `; +${ships.length - 3} more` : ''}) and no upgrade journey is named: a fresh install alone is no release proof`, fix: UPGRADE_FIX });
+    }
+    const required = ['git', 'config', 'evidence_root', 'real_product', 'core_journey', 'upgrade_journey', 'agent', 'judge', ...(values.probe ? ['probe'] : [])];
     const missingRequired = checks.filter((c) => c.status === 'missing' && required.includes(c.check));
     const result = { command: 'doctor', result: missingRequired.length ? 'fail' : 'pass', checks };
     // Several missing items can share one fix (set up the config once); name each fix only once.
@@ -3690,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;
@@ -3717,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;
 }
@@ -3768,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/dist/config.js

@@ -170,9 +170,9 @@ function apply(target, text, file, scope) {
                                                         : spec.type === 'auto_fix' ? isMap(value) && Object.entries(value).every(([k, n]) => AUTO_FIX_STEPS.includes(k) && Number.isInteger(n) && n >= 0)
                                                             : spec.type === 'matrix' ? !checkMatrix(value)
                                                                 : spec.type === 'regexes' ? (key === 'secrets.allow' ? Array.isArray(value) : isMap(value)) && Object.values(value).every(isRegex)
-                                                                    : isMap(value) && Object.values(value).every((j) => j && typeof j.command === 'string' && (j.spends === undefined || (typeof j.spends === 'string' && j.spends.trim() !== '')));
+                                                                    : isMap(value) && Object.values(value).every((j) => j && typeof j.command === 'string' && (j.spends === undefined || (typeof j.spends === 'string' && j.spends.trim() !== '')) && [j.core, j.upgrade].every((b) => b === undefined || typeof b === 'boolean'));
         const want = {
-            journeys: 'a map of name: {command: <string>, spends: <what a run spends>}',
+            journeys: 'a map of name: {command: <string>, spends: <what a run spends>, core: <true for the core user journey>, upgrade: <true for the upgrade-in-place journey>}',
             instance: '{command: <string>, ready: {url: <http url>} or {command: <shell command>}, ready_timeout: <duration>}',
             matrix: 'a mapping with optional theme (a list of names), width (a list of CSS pixel widths) and form (a list of names), plus skip (a list of partial cells, each with a reason)',
             agent: `one of ${AGENTS.join(', ')}, or acp:<target>`,

package/dist/proof.js

@@ -1,5 +1,6 @@
 // The one rule for real-product evidence, shared by init, doctor, check, receipt and gate. It is model-free and reads
-// the command text only: a command is code-only when every step in it is a test, typecheck, lint or build runner, or
+// the command text only: a command is code-only when every step in it is a test, typecheck, lint or build runner (a test or
+// guard script by its file name or folder counts as one), or
 // shell plumbing around one, and at least one step is such a runner. Its output says the code checks pass, never that
 // the product works. Any other step (a capture script, done-done look, the app's own binary, curl, adb) drives the product.
 // Steps that neither drive the product nor check the code: they move files and text around a runner.
@@ -19,6 +20,11 @@ const SUBCOMMANDS = {
     dotnet: /^(test|build)$/, swift: /^(test|build)$/, flutter: /^(test|analyze)$/, dart: /^(test|analyze)$/, xcodebuild: /^test$/, mix: /^test$/,
     playwright: /^test$/, cypress: /^run$/,
 };
+// A script that is a test or a code guard by its name or place: *.test.* and *.spec.* (x_test.go too), test_*.py, a file in a
+// test/, tests/ or __tests__/ folder, a script named test, and a guard or lint script (floor-guard.mjs, lint.sh).
+const TEST_FILE = /(^|\/)(tests?|__tests__)\/|[._-](test|spec)\.\w+$|(^|\/)test_\w+\.py$|(^|\/)tests?\.\w+$|(^|\/|[._-])(guard|lint)\.\w+$/;
+// Interpreters whose first argument is the script they run (go, deno and bun after run).
+const INTERPRETERS = new Set(['node', 'tsx', 'ts-node', 'bun', 'deno', 'go', 'python', 'python3', 'ruby', 'perl', 'php']);
 // A package script by name: test, check, lint, typecheck, build... and their variants (test:unit, check-types).
 const SCRIPT = /^(t|tst|tests?|checks?|lint|lints|typecheck|type-check|types|tsc|format|fmt|prettier|eslint|build|coverage|validate|unit|spec|vet)([:._-].*)?$/i;
 const INSTALL = /^(i|install|ci|add)$/;
@@ -50,6 +56,15 @@ function stepKind(step) {
         return 'plumbing';
     if (RUNNERS.has(base))
         return 'runner';
+    // A test or guard script, run directly (./tests/smoke.test.sh, bash tests/x.test.sh) or by an interpreter (node scripts/floor-guard.mjs).
+    if (TEST_FILE.test(w))
+        return 'runner';
+    if (INTERPRETERS.has(base)) {
+        const args = rest.filter((a) => !a.startsWith('-'));
+        const script = ['go', 'deno', 'bun'].includes(base) && args[0] === 'run' ? args[1] : args[0];
+        if (script && TEST_FILE.test(script))
+            return 'runner';
+    }
     if (PACKAGE_MANAGERS.has(base)) {
         const args = rest.filter((a) => !a.startsWith('-'));
         if (!args.length || INSTALL.test(args[0]))
@@ -97,3 +112,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}`;
 }
+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 = '') {
+    const j = Object.keys(journeys).find((n) => journeys[n][role] && !codeOnly(journeys[n].command));
+    if (j)
+        return `journey ${j}`;
+    const line = featureMap.split('\n').find((l) => /^\s*[-*] /.test(l) && l.includes(MARK[role]));
+    return line ? `feature map entry ${line.replace(/^\s*[-*] /, '').split(MARK[role])[0].trim()}` : null;
+}
+// What shows an app ships an installable or upgradable artifact, from its tracked files: each match as "<file>: <what>".
+// read gives a tracked file's text (undefined when it cannot be read).
+export function releaseArtifacts(files, read) {
+    const found = [];
+    for (const f of files) {
+        const name = f.split('/').pop();
+        let what = '';
+        if (name === 'package.json') {
+            try {
+                const p = JSON.parse(read(f) ?? '');
+                if (p && p.private !== true && (typeof p.bin === 'string' ? p.bin : p.bin && Object.keys(p.bin).length))
+                    what = 'an npm package with a bin users install';
+            }
+            catch { }
+        }
+        else if (name === 'eas.json')
+            what = 'an Expo app build';
+        else if (name === 'AndroidManifest.xml')
+            what = 'an Android app';
+        else if (/^build\.gradle(\.kts)?$/.test(name) && /\bapplicationId\b/.test(read(f) ?? ''))
+            what = 'an Android app';
+        else if (name === 'pyproject.toml' && /^\[(project|tool\.poetry)\.scripts\]/m.test(read(f) ?? ''))
+            what = 'a Python package with console scripts';
+        else if (name === 'Cargo.toml' && /^\[\[bin\]\]/m.test(read(f) ?? ''))
+            what = 'a Rust binary';
+        else if (/^\.goreleaser\.ya?ml$/.test(name))
+            what = 'a goreleaser release';
+        else if (name.endsWith('.service'))
+            what = 'a systemd service (a host or daemon)';
+        if (what)
+            found.push(`${f}: ${what}`);
+    }
+    return found;
+}

package/docs/index.html

@@ -107,6 +107,8 @@
     <h2>What it checks</h2>
     <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
 
@@ -16,7 +16,7 @@ done-done init
 
 `init` writes a minimal `.done-done.yaml` only when one does not exist: just `app`, the repo directory name, so every checkout of the repo finds the same evidence (see [Where proof lives](#where-proof-lives)). It sets no `evidence.root`, so evidence goes outside the repo. When an existing config puts `evidence.root` inside the repo (an older `root: .proof`), `init` adds it to `.gitignore` when git does not already ignore it. A plain `init` never rewrites the config: re-running is a no-op and a customized `.done-done.yaml` is left byte-for-byte; `.gitignore` gains a line only when the ignore entry is missing. A malformed `.done-done.yaml` makes `init` exit 2 with the file named and untouched. Its result says whether the config was `written` or left `unchanged`, the evidence root, what it added to `.gitignore`, the verify skill outcome (`verify_skill`), and the next step.
 
-`init` also has the agent the user set write the verify skill at `skill` (default `.agents/skills/done-done-verify-<app>`) from the repo's own files: plain code gives it the tracked file list and the text of the files that show how the repo proves itself (manifests, `.done-done.yaml` journeys, verify, e2e, smoke and demo scripts, `bin/` files, Dockerfiles, then source files (including Vue, Svelte, HTML, CSS and common compiled-language sources); JSON, YAML and Markdown are excluded except for manifests; at most 150,000 characters, and the prompt names what it left out; a `.env` or `.env.*` file, a file or folder whose path contains `secret`, `credential`, `token` or `password`, and `*.pem`, `*.key`, `*.p12` files never have their text sent by `init`, the agent is told not to open them, and no launch or feature can cite them; the tracked file list still names them), and one read-only call answers with the launch, readiness check, harness, evidence and up to five features (claude reads the repo with its read tools; every other agent gets only that text, and codex and gemini cannot run it tool-less). Launch prefers the repo's own safe proof path, a stub or demo engine with its own state, and when the repo shows none, `SKILL.md` opens Launch with `Not isolated:` and what the launch would touch, and `verify_skill` says so. `Safe:` is written only when the model marks the launch safe and its source is a tracked file that is not a manifest such as `package.json` or `README.md`; any other launch is `Not isolated:`, and its steps are not parsed. Each feature names the repo file it comes from. The prompt says a test suite, typecheck, lint or build is never a launch, a drive or the proof, and plain code refuses an answer whose launch steps or a feature's drive is code-only ([Real-product evidence](#real-product-evidence)), as it refuses an answer that cites a file the repo does not track, a secret-looking file, or, for a tool-less agent, a tracked file whose text its prompt left out. It writes `SKILL.md`, plus `features/README.md` and one file per feature with numbered drive and capture steps; `features/README.md` says how many more were found and not written. With no agent set, no skill is written and `init` asks for the agent (exit 2); an agent that fails or answers with an uncited or missing field writes no skill, and `verify_skill` names the cause and the call record (exit 1). On a repo with nothing tracked yet (a fresh `git init`), no skill is written and no agent is asked — no answer could cite a tracked file — and `verify_skill` names the remedy: commit the repo's files, then re-run (exit 1). The write is all-or-nothing: when any target already exists — `SKILL.md`, `features/README.md` or a `features/<name>.md`, as a file or a directory — nothing is written and `verify_skill` says `skipped: <paths> already exist; delete the skill folder to regenerate`, so a re-run after a lost `SKILL.md` can never pair new answers with the old feature map; a finished skill is left byte-identical and a re-run asks the agent nothing. A symlink on the path skips the scaffold and reports why in `verify_skill`, with exit 0. Otherwise the files are written into a temporary directory inside the skill's parent and moved into place, so a failed write leaves no partial skill: the temporary directory and any moved file are removed, `init` exits 1, and `verify_skill` names the error and says to re-run `init`. The config is kept either way. A `skill` path with a `..` segment is refused (exit 2) before anything is written. A repo whose older `init` wrote `.agents/skills/verify-<app>` (and sets no `skill`) keeps working: every command reads that folder, and the next `init` moves it once to `.agents/skills/done-done-verify-<app>` (also updating the `name:` line in its `SKILL.md`) and reports `skill_renamed: <old> -> <new>`; when the prefixed folder already exists, the old one is left alone. Commit `.done-done.yaml` and the verify skill before the first capture: a capture from a tree with uncommitted changes fails `check`, and `init` says so in its help.
+`init` also has the agent the user set write the verify skill at `skill` (default `.agents/skills/done-done-verify-<app>`) from the repo's own files: plain code gives it the tracked file list and the text of the files that show how the repo proves itself (manifests, `.done-done.yaml` journeys, verify, e2e, smoke and demo scripts, `bin/` files, Dockerfiles, then source files (including Vue, Svelte, HTML, CSS and common compiled-language sources); JSON, YAML and Markdown are excluded except for manifests; at most 150,000 characters, and the prompt names what it left out; a `.env` or `.env.*` file, a file or folder whose path contains `secret`, `credential`, `token` or `password`, and `*.pem`, `*.key`, `*.p12` files never have their text sent by `init`, the agent is told not to open them, and no launch or feature can cite them; the tracked file list still names them), and one read-only call answers with the launch, readiness check, harness, evidence and up to five features (claude reads the repo with its read tools; every other agent gets only that text, and codex and gemini cannot run it tool-less). Launch prefers the repo's own safe proof path, a stub or demo engine with its own state, and when the repo shows none, `SKILL.md` opens Launch with `Not isolated:` and what the launch would touch, and `verify_skill` says so. `Safe:` is written only when the model marks the launch safe and its source is a tracked file that is not a manifest such as `package.json` or `README.md`; any other launch is `Not isolated:`, and its steps are not parsed. Each feature names the repo file it comes from. The prompt says a test suite, typecheck, lint or build is never a launch, a drive or the proof, asks for exactly one feature marked `core` (the core user journey) and, when a tracked file shows the app ships an installable artifact, one marked `upgrade` (see [Core journey and release path](#core-journey-and-release-path)), and plain code refuses an answer with no core feature, more than one, or no upgrade feature for such an app; `SKILL.md` gains a `Core journey` section (and a `Release proof` section for such an app) and `features/README.md` marks those entries `(core journey)` and `(upgrade journey)`. The prompt also says and plain code refuses an answer whose launch steps or a feature's drive is code-only ([Real-product evidence](#real-product-evidence)), as it refuses an answer that cites a file the repo does not track, a secret-looking file, or, for a tool-less agent, a tracked file whose text its prompt left out. It writes `SKILL.md`, plus `features/README.md` and one file per feature with numbered drive and capture steps; `features/README.md` says how many more were found and not written. With no agent set, no skill is written and `init` asks for the agent (exit 2); an agent that fails or answers with an uncited or missing field writes no skill, and `verify_skill` names the cause and the call record (exit 1). On a repo with nothing tracked yet (a fresh `git init`), no skill is written and no agent is asked — no answer could cite a tracked file — and `verify_skill` names the remedy: commit the repo's files, then re-run (exit 1). The write is all-or-nothing: when any target already exists — `SKILL.md`, `features/README.md` or a `features/<name>.md`, as a file or a directory — nothing is written and `verify_skill` says `skipped: <paths> already exist; delete the skill folder to regenerate`, so a re-run after a lost `SKILL.md` can never pair new answers with the old feature map; a finished skill is left byte-identical and a re-run asks the agent nothing. A symlink on the path skips the scaffold and reports why in `verify_skill`, with exit 0. Otherwise the files are written into a temporary directory inside the skill's parent and moved into place, so a failed write leaves no partial skill: the temporary directory and any moved file are removed, `init` exits 1, and `verify_skill` names the error and says to re-run `init`. The config is kept either way. A `skill` path with a `..` segment is refused (exit 2) before anything is written. A repo whose older `init` wrote `.agents/skills/verify-<app>` (and sets no `skill`) keeps working: every command reads that folder, and the next `init` moves it once to `.agents/skills/done-done-verify-<app>` (also updating the `name:` line in its `SKILL.md`) and reports `skill_renamed: <old> -> <new>`; when the prefixed folder already exists, the old one is left alone. Commit `.done-done.yaml` and the verify skill before the first capture: a capture from a tree with uncommitted changes fails `check`, and `init` says so in its help.
 
 ```sh
 done-done init --agent opencode --model opencode-go/muse-spark-1.3-contributor
@@ -30,7 +30,7 @@ Record a journey's capture recipe in the repo so any checkout can re-run the pro
 done-done init --journey smoke -- 'echo added: milk > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
 ```
 
-`init --journey <name> -- <command>` writes `journeys.<name>.command` into `.done-done.yaml` (creating the file with the pinned `app` when missing) and reports `written` or `updated` with the journey name. `${RUN_ID}` in the command becomes the run id, exactly as in `run`. The recipe is committed, so an absolute path inside the repo is refused (exit 2, nothing written) with the relative form to use; name the path relative to the repo, or use a placeholder such as `${B:?}` that the caller sets. A code-only command (one that only runs tests, typecheck, lint or a build, see [Real-product evidence](#real-product-evidence)) is refused the same way, before anything is written, with the shape of a command to record instead. Commit the config: proof only counts from a clean tree.
+`init --journey <name> -- <command>` writes `journeys.<name>.command` into `.done-done.yaml` (creating the file with the pinned `app` when missing) and reports `written` or `updated` with the journey name. `${RUN_ID}` in the command becomes the run id, exactly as in `run`. The recipe is committed, so an absolute path inside the repo is refused (exit 2, nothing written) with the relative form to use; name the path relative to the repo, or use a placeholder such as `${B:?}` that the caller sets. A code-only command (one that only runs tests, typecheck, lint or a build, see [Real-product evidence](#real-product-evidence)) is refused the same way, before anything is written, with the shape of a command to record instead. `--core` also writes `core: true` (the core user journey) and `--upgrade` writes `upgrade: true` (the release path), see [Core journey and release path](#core-journey-and-release-path); either flag without `--journey` is a usage error. `init`'s help names the `--core` and `--upgrade` commands while the repo still needs them. Commit the config: proof only counts from a clean tree.
 
 ```sh
 done-done init --hook claude
@@ -70,7 +70,7 @@ done-done init --hook pi
 done-done doctor
 ```
 
-`doctor` answers "is this repo worth driving" and changes nothing except the `--probe` call record (the agent itself may keep its own session files). It checks ten items, each reported `ok`, `warning` or `missing` with the exact fix command (plus a `tool_gate` `warning` row when the agent is pi or codex; see [Agents](#agents)): `git` (inside a repository), `config` (a valid `.done-done.yaml`), `evidence_root` (writable), `verify_skill` (`.agents/skills/done-done-verify-<app>/SKILL.md`), `agent` (the coding agent the user set and its model; `missing` when none is set, with the command that saves the user's choice, or when it is not installed or done-done cannot start it yet; see [Agents](#agents)), `agent_settings` (each effective agent setting, `agent`, its model, effort, how many extra flags are set (never their values), binary and `agent_timeout`, and where it came from: the global config, `.done-done.yaml` or `default`), `judge` (`missing` when no judge is set, with the command that saves the user's choice; else the judge kit is present, and the route's own setup: for `claude-code` an executable `claude` binary (`agent_path_override.claude`, else PATH), with your own sign-in checked only when a capture is judged; for `answerer:<agent>` the agent on PATH; for `openai:key` the `OPENAI_API_KEY` variable and a `judge.model`; for `minimax:key` the `MINIMAX_API_KEY` variable; doctor does not call the model; it is checked even with no agent set), `ffprobe` (video evidence only) and `judge_choice` (the route and model the judge runs and the author it judges, see [Judge relevance](#judge-relevance): `ok`, naming how far apart they are (`agent`, `model` or `session-only`), since any judge the user sets runs; `missing`, with no fix of its own, until the agent is set; `missing` when no judge is set or the judge config is incomplete, such as a key route with no `judge.model`) and `real_product` (whether the journeys drive the product, see [Real-product evidence](#real-product-evidence): `ok` naming them, or with no journeys, since `verify` then drives the verify skill; a `warning` naming code-only journeys beside real ones; `missing` when every journey is code-only, with the command that records a real one). `git`, `config`, `evidence_root`, `real_product`, `agent` and `judge` are required, since done-done gives no result without its agent and judge, and refuses all proof from a code-only config: `doctor` exits 0 when they are all ok and 2 otherwise. A missing `verify_skill` or `ffprobe`, or a `warning`, never fails it. In a fresh repo with nothing set up, `doctor` names each missing piece, starting with `done-done init`.
+`doctor` answers "is this repo worth driving" and changes nothing except the `--probe` call record (the agent itself may keep its own session files). It checks twelve items, each reported `ok`, `warning` or `missing` with the exact fix command (plus a `tool_gate` `warning` row when the agent is pi or codex; see [Agents](#agents)): `git` (inside a repository), `config` (a valid `.done-done.yaml`), `evidence_root` (writable), `verify_skill` (`.agents/skills/done-done-verify-<app>/SKILL.md`), `agent` (the coding agent the user set and its model; `missing` when none is set, with the command that saves the user's choice, or when it is not installed or done-done cannot start it yet; see [Agents](#agents)), `agent_settings` (each effective agent setting, `agent`, its model, effort, how many extra flags are set (never their values), binary and `agent_timeout`, and where it came from: the global config, `.done-done.yaml` or `default`), `judge` (`missing` when no judge is set, with the command that saves the user's choice; else the judge kit is present, and the route's own setup: for `claude-code` an executable `claude` binary (`agent_path_override.claude`, else PATH), with your own sign-in checked only when a capture is judged; for `answerer:<agent>` the agent on PATH; for `openai:key` the `OPENAI_API_KEY` variable and a `judge.model`; for `minimax:key` the `MINIMAX_API_KEY` variable; doctor does not call the model; it is checked even with no agent set), `ffprobe` (video evidence only) and `judge_choice` (the route and model the judge runs and the author it judges, see [Judge relevance](#judge-relevance): `ok`, naming how far apart they are (`agent`, `model` or `session-only`), since any judge the user sets runs; `missing`, with no fix of its own, until the agent is set; `missing` when no judge is set or the judge config is incomplete, such as a key route with no `judge.model`) and `real_product` (whether the journeys drive the product, see [Real-product evidence](#real-product-evidence): `ok` naming them, or with no journeys, since `verify` then drives the verify skill; a `warning` naming code-only journeys beside real ones; `missing` when every journey is code-only, with the command that records a real one), `core_journey` (`ok` naming the journey with `core: true` that drives the product, or the verify skill's `(core journey)` feature-map entry; `missing` otherwise, with the `init --journey <name> --core` command) and `upgrade_journey` (`ok` when no tracked file shows an installable artifact, or naming the journey with `upgrade: true` or the `(upgrade journey)` entry and the files that show the artifact; `missing` when the app ships one and names no upgrade journey, with the `init --journey upgrade --upgrade` command), see [Core journey and release path](#core-journey-and-release-path). `git`, `config`, `evidence_root`, `real_product`, `core_journey`, `upgrade_journey`, `agent` and `judge` are required, since done-done gives no result without its agent and judge, and refuses all proof from a code-only config: `doctor` exits 0 when they are all ok and 2 otherwise. A missing `verify_skill` or `ffprobe`, or a `warning`, never fails it. In a fresh repo with nothing set up, `doctor` names each missing piece, starting with `done-done init`.
 
 ```sh
 done-done doctor --probe
@@ -251,13 +251,47 @@ done-done checks the base ref out in a scratch git worktree of its own under the
 
 done-done proves the real product works, not that its code checks pass. One model-free rule, on a command's text alone, decides which runs count; `init`, `doctor`, `check`, `receipt` and `gate` all use it.
 
-A command is **code-only** when every step in it (split on `&&`, `||`, `;`, `|` and newlines, with redirections dropped and wrappers such as `npx`, `env`, `VAR=value`, `sh -c`, `pnpm exec`, `uv run`, `bundle exec` and `python -m` read through) is a test, typecheck, lint or build runner or shell plumbing around one (`cd`, `echo`, `tee`, `mkdir`, `cp`, `cat`, `npm ci`...), and at least one step is a runner. The runners are a package script named `test`, `check`, `lint`, `typecheck`, `types`, `tsc`, `build`, `format`, `coverage`, `validate` and their variants (`npm test`, `yarn run check`, `pnpm test:unit`, `bun test`), and tools such as `tsc`, `eslint`, `prettier`, `biome`, `jest`, `vitest`, `mocha`, `node --test`, `playwright test`, `cypress run`, `pytest`, `tox`, `mypy`, `ruff`, `go test`, `cargo test`, `make test`, `gradle test`, `mvn test`, `dotnet test`, `flutter test`, `deno test`, `rspec` and `phpunit`. Any other step (a capture script, `done-done look`, the app's own binary, `npm start`, `curl`, `adb`, `playwright screenshot`) drives the product, so a command with one is not code-only. A run opened by hand (`run --open`) or driven by the agent (`verify` with no journey) has no command and is never code-only.
+A command is **code-only** when every step in it (split on `&&`, `||`, `;`, `|` and newlines, with redirections dropped and wrappers such as `npx`, `env`, `VAR=value`, `sh -c`, `pnpm exec`, `uv run`, `bundle exec` and `python -m` read through) is a test, typecheck, lint or build runner or shell plumbing around one (`cd`, `echo`, `tee`, `mkdir`, `cp`, `cat`, `npm ci`...), and at least one step is a runner. The runners are a package script named `test`, `check`, `lint`, `typecheck`, `types`, `tsc`, `build`, `format`, `coverage`, `validate` and their variants (`npm test`, `yarn run check`, `pnpm test:unit`, `bun test`), and tools such as `tsc`, `eslint`, `prettier`, `biome`, `jest`, `vitest`, `mocha`, `node --test`, `playwright test`, `cypress run`, `pytest`, `tox`, `mypy`, `ruff`, `go test`, `cargo test`, `make test`, `gradle test`, `mvn test`, `dotnet test`, `flutter test`, `deno test`, `rspec` and `phpunit`, and a test or guard script by its file name or folder, run directly or by an interpreter (`bash tests/relaunch.test.sh`, `node scripts/floor-guard.mjs`, `node scripts/test.mjs`, `python3 tests/test_pair.py`, `go run ./cmd/pair_test.go`): a `*.test.*` or `*.spec.*` file (`x_test.go` too), `test_*.py`, a file in a `test/`, `tests/` or `__tests__/` folder, a script named `test`, or one whose name ends in `guard` or `lint` (`floor-guard.mjs`, `lint.sh`). Any other step (a capture script, `done-done look`, the app's own binary, `npm start`, `curl`, `adb`, `playwright screenshot`) drives the product, so a command with one is not code-only. A run opened by hand (`run --open`) or driven by the agent (`verify` with no journey) has no command and is never code-only.
 
 - `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.
 - `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.
 
+### 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`).
+
+- The **core journey** is the one thing a user cannot live without, driven end to end on the real target the way a user does it: for a remote terminal app, pair, open a pane, type, see the output. A config names it with `journeys.<name>.core: true` (`init --journey <name> --core -- <command>`); a code-only journey never counts. A repo with no journeys names it in its verify skill's `features/README.md` with an entry line (`- ...`) that carries `(core journey)`.
+- The **upgrade journey** is the release path users take: install the previous shipped version, upgrade over it in place (install the new APK over the old one, update the host or CLI package in place), then drive the core journey. It is needed when a tracked file shows the app ships an installable or upgradable artifact: a `package.json` with a `bin` that is not `"private": true`, an `eas.json`, an `AndroidManifest.xml`, a `build.gradle` with an `applicationId`, a `pyproject.toml` with `[project.scripts]` or `[tool.poetry.scripts]`, a `Cargo.toml` with `[[bin]]`, a `.goreleaser.yml`, or a systemd `*.service` unit. A config names it with `journeys.<name>.upgrade: true` (`init --journey upgrade --upgrade -- <command>`), or the feature map with `(upgrade journey)`. One journey may be both.
+- `doctor`'s `core_journey` and `upgrade_journey` rows are required, and `init`'s verify skill refuses an answer that names neither or, for an app that ships an artifact, no upgrade journey.
+
+```yaml
+journeys:
+  pair-type:
+    command: scripts/proof/pair-open-type.sh > "$DONE_DONE_EVIDENCE_ROOT/pair-type.log"
+    core: true
+  upgrade:
+    command: scripts/proof/upgrade-from-last-release.sh > "$DONE_DONE_EVIDENCE_ROOT/upgrade.log"
+    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
@@ -485,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.
 
@@ -499,7 +533,7 @@ Running `done-done` with no subcommand prints the repo's config state (`config:
 | 3 | inconclusive (could not be proven either way) |
 | 4 | the run is still running, or a `verify` run waits at its gate (`verify`, `maintain --no-wait`, `rerun`, `status`, `respond`) |
 
-`doctor` exits 2 when a required item (`git`, `config`, `evidence_root`, `real_product`, `agent`, `judge`, and `probe` with `--probe`) is missing.
+`doctor` exits 2 when a required item (`git`, `config`, `evidence_root`, `real_product`, `core_journey`, `upgrade_journey`, `agent`, `judge`, and `probe` with `--probe`) is missing.
 
 ### Merge gate on the desktop
 
@@ -580,6 +614,8 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 | `skill` | `.agents/skills/done-done-verify-<app>` |
 | `journeys.<name>.command` | none |
 | `journeys.<name>.spends` | none; what a run of the journey spends, so `verify` waits for the user approval, see [Journeys that spend](#journeys-that-spend) |
+| `journeys.<name>.core` | false; `true` marks the core user journey, see [Core journey and release path](#core-journey-and-release-path) |
+| `journeys.<name>.upgrade` | false; `true` marks the upgrade-in-place journey, see [Core journey and release path](#core-journey-and-release-path) |
 | `secrets.patterns`, `secrets.allow` | `{}` and `[]`; extra `<name>: <regex>` secret shapes and known-safe regexes, see [Secrets in the evidence](#secrets-in-the-evidence) |
 | `journeys.<name>.timeout` | `30m`; a positive duration such as `90s` or `30m` (up to about 24 days), used by `verify` |
 | `instance` | none; the app under test started per run, see [Run-instance harness](#run-instance-harness) |

package/integrations/firstmate/brief-include.md

@@ -9,10 +9,17 @@ wherever this text or the skill says `done-done`. If done-done cannot run, repor
    site the way a user does and writes its screenshots, recordings or transcript into `$DONE_DONE_EVIDENCE_ROOT`
    (done-done sets it to the run's own folder): `done-done init --journey <name> -- <command>`, so the recipe lives in
    the repo and anyone can re-run the proof. Never record a test, typecheck, lint or build run (`npm test`,
-   `yarn run check`, `tsc`): it is code-only, `init` refuses it, and `check`, `receipt` and the gate refuse its proof. Commit `.done-done.yaml` and the journey script. If `init` says no agent is set, ask the user which agent
+   `yarn run check`, `tsc`): it is code-only, `init` refuses it, and `check`, `receipt` and the gate refuse its proof.
+   Record the app's core journey with `--core` (the one thing a user cannot live without, driven end to end on the
+   real target) and, when the app ships something users install and upgrade, a release journey with `--upgrade` that
+   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
@@ -33,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.0",
+  "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

@@ -36,6 +36,14 @@ captured as screenshots, a recording or its transcript), never from a test, type
 that only wraps one (`npm test`, `yarn run check`, `tsc`, `pytest`), and `check`, `receipt` and `gate` refuse proof from it. Proof counts only
 from a committed tree: commit the done-done setup (config, capture script) before you capture. `fail` or
 `inconclusive` is not done: fix the cause and re-run, or tell the user exactly what is still unproven.
+Every app names its core journey (`core: true` on a journey, or `init --journey <name> --core`): 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); a proof of some other feature
+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`.