done-done-axi 0.5.2 → 0.6.0

package/README.md

@@ -125,11 +125,11 @@ done-done init
 ```yaml
 journeys:
   smoke:
-    command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log
+    command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs
     core: true
 ```
 
-The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails. A journey that only runs code checks (`npm test`, `yarn run check`, `tsc`, `pytest`, a linter or a build) is code-only: its log says the code checks pass, not that the product works, so `init --journey` refuses it and `check`, `receipt` and `gate` never count it as proof ([the rule](docs/reference.md#real-product-evidence)).
+The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails. The command also writes `steps.json` beside its captures: the target version, the state it started from, the steps a user takes and the result a user sees. `check`, `receipt` and `gate` read the claim against that record, so a test log wrapped in a script cannot prove a claim about the product ([the record](docs/reference.md#step-record)). A journey that only runs code checks (`npm test`, `yarn run check`, `tsc`, `pytest`, a linter or a build) is code-only: its log says the code checks pass, not that the product works, so `init --journey` refuses it and `check`, `receipt` and `gate` never count it as proof ([the rule](docs/reference.md#real-product-evidence)).
 
 Name your **core journey** with `core: true`: the one thing a user cannot live without, driven end to end on the real target (for a remote terminal app: pair, open a pane, type, see the output). If your app ships something users install and upgrade (an npm CLI, an Android app, a host service), also record an **upgrade journey** with `upgrade: true` that installs your previous release, upgrades over it in place, then drives the core journey: a fresh install alone is not how users get your release. `doctor` fails until both are named ([the rule](docs/reference.md#core-journey-and-release-path)).
 
@@ -138,7 +138,7 @@ Optional: `done-done init --hook <claude|codex|opencode|gemini|pi>` adds a sessi
 Record the recipe in the repo so anyone can re-run the proof, then commit it (and `.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, `.opencode/plugins/done-done.js` or `.pi/extensions/done-done.js` if you added a hook):
 
 ```sh
-done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
+done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs'
 git add .done-done.yaml
 git commit -m "Add done-done"
 ```

package/dist/cli.js

@@ -22,8 +22,9 @@ import { lint } from './lint.js';
 import { look } from './look.js';
 import { scanSecrets } from './secrets.js';
 import { mapChange } from './affected.js';
-import { codeOnly, codeOnlyJourneys, configFault, MARK, namedJourney, releaseArtifacts, RULE, runsFault } from './proof.js';
+import { codeOnly, codeOnlyJourneys, configFault, MARK, namedJourney, releaseArtifacts, RULE, runsFault, STEPS_FILE, STEPS_SHAPE, stepRecordFault, stepsFault } from './proof.js';
 const PASS = 0, FAIL = 1, USAGE = 2, INCONCLUSIVE = 3, WAITING = 4;
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 // The shape of a journey, so a new user or agent can write one without opening the reference.
 // done-done sets DONE_DONE_EVIDENCE_ROOT (the run's own folder) and replaces ${RUN_ID}, so the example works for any evidence root.
 const journeyExample = 'journeys: { smoke: { command: "<drive the core user journey on the real app> > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log", core: true } }';
@@ -33,6 +34,8 @@ const JOURNEYS_TEXT = `journeys (.done-done.yaml): the command runs with DONE_DO
   real product: a journey whose command only runs tests, typecheck, lint or a build (npm test, yarn run check, tsc, pytest, or a test or guard
   script such as bash tests/x.test.sh or node scripts/floor-guard.mjs) is code-only;
   init --journey refuses it, and check, receipt and gate refuse proof that comes only from code-only runs or a config of only code-only journeys
+  step record: the journey also writes steps.json into $DONE_DONE_EVIDENCE_ROOT, shaped ${STEPS_SHAPE};
+  check, receipt and gate refuse a claim that no cited run's step record covers (a run recorded before step records only warns)
   core (journeys.<name>.core: true): the core user journey, the one thing a user cannot live without, driven end to end on the real target
   (for a remote terminal: pair, open a pane, type, see the output); doctor requires one, here or as a "(core journey)" entry in the verify skill's feature map
   upgrade (journeys.<name>.upgrade: true): the release path users take: install the previous shipped version, upgrade over it in place, then drive the
@@ -430,7 +433,26 @@ function openRun(repo, cfg, journey, command, id) {
     const runId = id ?? newRunId(h.commit);
     mkdirSync(cfg.evidence.root, { recursive: true });
     mkdirSync(runDir(cfg, runId));
-    return { schema: 1, run_id: runId, journey, command, ...h, started_at: new Date().toISOString(), ended_at: null, exit: null, files: [] };
+    return { schema: 1, run_id: runId, journey, command, ...h, started_at: new Date().toISOString(), ended_at: null, exit: null, files: [], tool: VERSION };
+}
+// The step record a run's journey (or driving agent) wrote beside its captures; it is a record, not a capture, so it is not a run file.
+function readSteps(cfg, rec) {
+    delete rec.steps;
+    delete rec.steps_error;
+    const file = join(runDir(cfg, rec.run_id), STEPS_FILE);
+    if (!existsSync(file))
+        return;
+    try {
+        const steps = JSON.parse(readFileSync(file, 'utf8'));
+        const bad = stepRecordFault(steps);
+        if (bad)
+            rec.steps_error = bad;
+        else
+            rec.steps = steps;
+    }
+    catch (e) {
+        rec.steps_error = `it is not JSON (${e.message})`;
+    }
 }
 // The first line of a run's log that names a failure, trimmed: what a non-zero exit is about. Empty when none does.
 function firstFailure(log) {
@@ -441,7 +463,9 @@ function firstFailure(log) {
 }
 function closeRun(repo, cfg, rec, log) {
     const now = head(repo);
+    readSteps(cfg, rec);
     rec.files = captured(cfg, rec.run_id)
+        .filter((p) => basename(p) !== STEPS_FILE || dirname(p) !== rec.run_id)
         .sort()
         .map((p) => {
         const b = readFileSync(join(cfg.evidence.root, p));
@@ -802,7 +826,7 @@ async function runCheck(argv, run) {
             continue;
         }
         const rec = (atNow.length ? atNow : claims).reduce((a, b) => (b.started_at > a.started_at ? b : a));
-        runs.set(rec.run_id, { run_id: rec.run_id, journey: rec.journey, command: rec.command, ...(rec.feature && { feature: rec.feature }) });
+        runs.set(rec.run_id, { run_id: rec.run_id, journey: rec.journey, command: rec.command, ...(rec.feature && { feature: rec.feature }), ...(rec.tool && { tool: rec.tool }), ...(rec.steps && { steps: rec.steps }), ...(rec.steps_error && { steps_error: rec.steps_error }) });
         // Only a capture tied to a run record can reach the judge, so a stray cited file is never sent.
         const c = { name, bytes, sha256: hash, media: v };
         if (v.status === 'ok' && !record && pair)
@@ -835,6 +859,15 @@ async function runCheck(argv, run) {
     const codeRuns = runs.size ? runsFault([...runs.values()]) : null;
     if (codeRuns)
         findings.push({ level: 'fail', why: codeRuns });
+    // The user steps behind the captures: a cited real run needs a step record covering the claim. Runs from before step records warn.
+    const warnings = [];
+    if (claim && runs.size && !codeRuns) {
+        const s = stepsFault([...runs.values()], claim.outcome);
+        if (s.fault)
+            findings.push({ level: 'fail', why: s.fault });
+        if (s.warning)
+            warnings.push(s.warning);
+    }
     // Reuse: fail only when every cited file was already used for a different claim id. The ledger lives in the
     // evidence root next to the run records it guards: one per app (repo), shared by every checkout of it, never in git.
     const ledger = join(cfg.evidence.root, '.done-done', 'ledger');
@@ -890,12 +923,12 @@ async function runCheck(argv, run) {
     if (j.notJudged.length)
         judged.not_judged = j.notJudged;
     judged.note = 'PNG and JPEG screens and text captures (logs, JSON, CLI output) are judged; video and other files are not';
-    const rep = report(findings, files, { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel });
+    const rep = report(findings, files, { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel, warnings });
     if (rep.code === PASS) {
         mkdirSync(dirname(ledger), { recursive: true });
         appendFileSync(ledger, hashes.filter((h) => !used.get(h)?.has(claimId)).map((h) => `${h} ${claimId}\n`).join(''));
     }
-    return { code: rep.code, result: rep.result, judge: judged, judgeBlock, claim: claim?.outcome, skill: claim?.skill, files, cited, runs: [...runs.values()], head: now, findings };
+    return { code: rep.code, result: rep.result, judge: judged, judgeBlock, claim: claim?.outcome, skill: claim?.skill, files, cited, runs: [...runs.values()], head: now, findings, warnings };
 }
 async function cmdCheck(argv) {
     const r = await runCheck(argv);
@@ -933,8 +966,13 @@ function receiptFault(rec, short) {
     if (badJudge)
         return `receipt for ${short} has a malformed judge block`;
     const code = runsFault(rec.runs);
-    return code ? `receipt for ${short} is no real-product proof: ${code}` : null;
+    if (code)
+        return `receipt for ${short} is no real-product proof: ${code}`;
+    const steps = stepsFault(rec.runs, rec.claim);
+    return steps.fault ? `receipt for ${short} has no step record covering its claim: ${steps.fault}` : null;
 }
+// The warning a well-formed receipt still carries: its runs were recorded before step records.
+const receiptWarning = (rec) => stepsFault(rec.runs, rec.claim).warning;
 // Verify a recorded receipt for `headArg`, which may be a full sha or a ref (HEAD, a branch or a tag).
 // Read-only, so a missing or changed record is a failure, not a usage error.
 function verifyReceipt(repo, cfg, headArg) {
@@ -986,7 +1024,7 @@ function verifyReceipt(repo, cfg, headArg) {
     }
     if (bad.length)
         return fail(`cited evidence no longer matches the receipt: ${bad.join('; ')}`);
-    return { code: PASS, result: { command: 'receipt', result: 'pass', head: commit, tree: rec.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, at: rec.at, schema: rec.schema, judge: j, help: ['This receipt is valid for this head.'] } };
+    return { code: PASS, result: { command: 'receipt', result: 'pass', head: commit, tree: rec.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, at: rec.at, schema: rec.schema, judge: j, ...(receiptWarning(rec) && { warnings: [receiptWarning(rec)] }), help: ['This receipt is valid for this head.'] } };
 }
 async function cmdReceipt(argv) {
     const vi = argv.indexOf('--verify');
@@ -1024,7 +1062,7 @@ function recordReceipt(repo, cfg, r) {
         throw new UsageError('receipt: the check cited no evidence files, so no receipt was written; a receipt must bind at least one cited evidence file', 'Cite real proof: done-done receipt --outcome "<claim>" <files...>');
     const rec = { schema: 2, repo: cfg.app, head: r.head.commit, tree: r.head.tree, claim: r.claim ?? '', ...(r.skill && { skill: r.skill }), result: 'pass', at: new Date().toISOString(), files: r.cited, runs: r.runs, judge: r.judgeBlock };
     const path = writeReceipt(cfg, rec);
-    const result = { command: 'receipt', result: 'pass', head: r.head.commit, tree: r.head.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, receipt: shown(repo, path) };
+    const result = { command: 'receipt', result: 'pass', head: r.head.commit, tree: r.head.tree, claim: rec.claim, ...(rec.skill && { skill: rec.skill }), files: rec.files.length, receipt: shown(repo, path), ...(r.warnings.length && { warnings: r.warnings }) };
     return { code: PASS, result: { ...result, ...(r.judge && { judge: r.judge }), help: [`Verify this receipt (merge gate): done-done receipt --verify ${r.head.commit}`] } };
 }
 // Why evidence from `from` no longer proves `to`, or '' if it still does.
@@ -1070,6 +1108,8 @@ function checkHelp(code, findings, files, { cfg, repo, claim, source, citationBa
             ? `${absent} named file${absent > 1 ? 's are' : ' is'} not in this checkout. If the evidence is in another folder, check against it: ${form}`
             : `${absent} named file${absent > 1 ? 's are' : ' is'} not under --citation-base ${arg(citationBase)} either: check the paths in the Checks block`);
     }
+    if (findings.some((f) => f.why.includes('step record')))
+        help.push(`Have the journey write ${STEPS_FILE} into $DONE_DONE_EVIDENCE_ROOT, shaped ${STEPS_SHAPE}, naming the steps and the result the claim is about; then re-run it (${captureHint(cfg)}) and cite the new files`);
     // Proof refused as code-only needs a journey that drives the product, not a re-capture of the same run.
     if (findings.some((f) => f.why.endsWith(RULE)))
         help.push(`Capture the real product: ${captureHint(cfg).startsWith('done-done init') ? captureHint(cfg) : `${captureHint(cfg)}, or ${RECORD_REAL}`}, then cite its files`);
@@ -1101,6 +1141,8 @@ function report(findings, files, ctx) {
         result.findings = rows.items;
     if (rows.omitted)
         result.findings_omitted = rows.omitted;
+    if (ctx.warnings?.length)
+        result.warnings = ctx.warnings;
     result.help = checkHelp(code, findings, files, ctx);
     return { code, result };
 }
@@ -1330,11 +1372,12 @@ ${inst}${cells}${dom}${before}
 2. ${cfg.instance ? 'Drive that running instance' : 'Launch the app as the skill says, then drive'} that feature through the real user path, step by step as its recipe says.
    Never add steps or data to make the outcome look true: capture what that path shows, even when it contradicts the outcome.
 3. Save PNG screenshots of what a user sees once the path is done (the resulting state the outcome is about) into ${evidence} (also in $DONE_DONE_EVIDENCE_ROOT); when the outcome shows in text (a CLI's output, a log or JSON), save that text there as a .txt, .log or .json file instead.
-   The judge checks every capture there against the outcome, so a capture of an earlier step (such as an empty or half-filled form, or text from before the outcome) fails the drive: keep those in ${scratch}. Save nothing else there, and never edit a capture.
-4. Stop everything you started.
+   The judge checks every capture there against the outcome, so a capture of an earlier step (such as an empty or half-filled form, or text from before the outcome) fails the drive: keep those in ${scratch}. Save nothing else there but the step record of step 4, and never edit a capture.
+4. Write ${STEPS_FILE} into ${evidence} (also in $DONE_DONE_EVIDENCE_ROOT), the record of what you did, as JSON shaped ${STEPS_SHAPE}: the app version you drove (its package or build version, else the commit), the state it started from, each step a user takes in your own words, and what a user can see at the end. Write what you did, never what the outcome needs.
+5. Stop everything you started.
 
 Do not change any file in the repository. Do not run done-done: it refuses inside a drive, and done-done answers the run after you stop. Put logs and other scratch files in ${scratch} (also in $TMPDIR), never in /tmp.
-Keep working until all four steps are done: your next message without a tool call ends the drive and must be the answer.
+Keep working until all five steps are done: your next message without a tool call ends the drive and must be the answer.
 If you cannot launch the app or reach the feature, say why in blocker and save no capture.
 Answer with feature (the feature file you drove, such as features/<name>.md), captures (the file names you saved) and blocker ("" when you drove it),
 for example {"feature":"features/<name>.md","captures":["<name>.png"],"blocker":""}.`;
@@ -3657,7 +3700,7 @@ async function cmdLook(argv) {
 // The folder of a branch where a receipt copied from the evidence root is committed, for `gate`.
 const GATE_DIR = '.done-done-receipts';
 // The reason no committed receipt vouches for `tip`, or null when one does. Reads git objects only: no config, no judge, no evidence files.
-function gateFault(repo, tip, dir, pushed) {
+function gateFault(repo, tip, dir, pushed, warnings) {
     const short = tip.slice(0, 12);
     const names = git(repo, '-c', 'core.quotepath=off', 'ls-tree', '-r', '--name-only', tip, '--', dir).split('\n').filter((n) => n.endsWith('.json'));
     if (!names.length)
@@ -3689,6 +3732,9 @@ function gateFault(repo, tip, dir, pushed) {
             const at = Date.parse(rec.at);
             if (!(Math.floor(at / 1000) <= Math.floor(pushed / 1000)))
                 return `receipt time ${rec.at} is not before the push (${new Date(pushed).toISOString()})`;
+            const warn = receiptWarning(rec);
+            if (warn)
+                warnings.push(warn);
             return null;
         })();
         if (!why)
@@ -3713,8 +3759,9 @@ function cmdGate(argv) {
     const pushed = values.pushed === undefined ? Number(git(repo, 'log', '-1', '--format=%ct', tip)) * 1000 : Date.parse(values.pushed);
     if (Number.isNaN(pushed))
         throw new UsageError(`gate: --pushed ${values.pushed} is not a time`, 'Pass an ISO time such as 2026-10-20T09:05:56Z');
-    const why = gateFault(repo, tip, (values.dir ?? GATE_DIR).replace(/\/+$/, ''), pushed);
-    console.log(why === null ? 'PASS' : `FAIL: ${why}`);
+    const warnings = [];
+    const why = gateFault(repo, tip, (values.dir ?? GATE_DIR).replace(/\/+$/, ''), pushed, warnings);
+    console.log(why === null ? ['PASS', ...warnings.map((w) => `WARN: ${w}`)].join('\n') : `FAIL: ${why}`);
     return why === null ? PASS : FAIL;
 }
 function cmdLint(argv) {
@@ -4009,7 +4056,7 @@ async function main(argv) {
             return PASS;
         }
         if (cmd === '--version') {
-            console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+            console.log(VERSION);
             return PASS;
         }
         if (cmd === '--help' || cmd === '-h' || cmd === 'help') {

package/dist/proof.js

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

package/docs/reference.md

@@ -97,6 +97,8 @@ journeys:
     command: node scripts/capture-review.mjs --out $DONE_DONE_EVIDENCE_ROOT
 ```
 
+The script saves its captures into that folder and writes `steps.json` beside them: the target version, start state, user steps and end result ([Step record](#step-record)).
+
 Then run it:
 
 ```sh
@@ -255,9 +257,30 @@ A command is **code-only** when every step in it (split on `&&`, `||`, `;`, `|`
 
 - `init --journey` refuses a code-only command (exit 2, nothing written), and `init`'s verify skill refuses a code-only launch or feature drive.
 - `check` and `receipt` stop before the judge (exit 2) when every journey in `.done-done.yaml` is code-only, naming them, or when every cited capture comes from a code-only run, naming its journey or command. A test log cited beside real captures is fine: they carry the proof.
-- A receipt records the run behind each cited capture (`runs`), so `receipt --verify` and `gate` apply the same rule with no config: a receipt whose runs are all code-only, or one with no `runs` (written before this rule), fails.
+- A receipt records the run behind each cited capture (`runs`), so `receipt --verify` and `gate` apply the same rule with no config (and the [step record](#step-record) rule after it): a receipt whose runs are all code-only, or one with no `runs` (written before this rule), fails.
 - `doctor`'s `real_product` row is `missing` (and doctor exits 2) when every journey is code-only, and a `warning` naming the code-only journeys beside real ones.
 
+### Step record
+
+A capture shows a screen; the **step record** says what a user did to reach it. Every journey (and every agent drive) writes `steps.json` into its run folder, `$DONE_DONE_EVIDENCE_ROOT`, beside the captures:
+
+```json
+{
+  "target": { "version": "0.6.0" },
+  "start": "a fresh host with no paired phone",
+  "steps": ["pair the phone", "open a pane", "type `echo hi`"],
+  "result": "the pane shows hi on its own line"
+}
+```
+
+`target.version` is the version of the app driven, `start` the state it began from (for an upgrade journey: the previous version installed), `steps` the steps a user takes, in order, and `result` what a user can see at the end. All four are required; a file that is not JSON or lacks one is recorded as invalid. `run` and `verify` read the file when the run closes and keep it in the run record (`steps`, with `tool`, the done-done version that recorded the run, and `steps_error` when the file is invalid); it is a record, not a capture, so it is not listed in the run's files and the judge never reads it. A journey writes it as it drives, from what it really did, never from the claim.
+
+The check reads the claim against the record, with no model: at least half of the claim's words (four letters or more, without scaffolding such as `user`, `can`, `now`, `works`) must appear in the record's `start`, `steps` and `result`, matching word beginnings (`attach`, `attaches`, `attached`), and at least one of them in `result`. This runs after the code-only rule, which stays the first filter, and with it:
+
+- `check` and `receipt` stop before the judge (exit 2) when no cited capture comes from a run (not code-only) whose step record covers the claim, naming each run and the words its record never mentions. A log from a wrapper script whose record says `ran the unit suite` cannot satisfy a claim about attaching to a pane; a real CLI transcript whose record names the command and its output still satisfies a claim about that command. A cited run with no step record, or an invalid one, is refused the same way, with the shape to write.
+- A receipt keeps each run's step record (`runs[].steps`), so `receipt --verify` and `gate` apply the same rule to the receipt's claim with no config or evidence: a receipt whose runs have no covering record fails.
+- A run recorded before step records existed (its run record has no `tool`, or a receipt run has none) keeps working: `check`, `receipt`, `receipt --verify` and `gate` still pass, but say so in `warnings` (`gate` prints `WARN: ...` after `PASS`): re-run the journey so it writes `steps.json`.
+
 ### Core journey and release path
 
 A proof that drives some feature of the app does not show the app works when the one flow users need is broken, and a release proven by a fresh install does not show the upgrade users take works. So each app names two journeys, and `init`, `doctor` and the verify skill share one model-free rule for them (`src/proof.ts`).
@@ -333,7 +356,7 @@ A plain check is never a verdict on its own. A cited file that fails one of thes
 
 Files that are in no run record give an inconclusive result when another cited capture is one the judge reads: nothing ties them to a commit. So does a file that more than one run record claims when none of those runs is at the current commit (possible only with records from before each run had its own folder). Byte-identical captures from several runs are fine when one of those runs is at the current commit: that run ties the file to the commit. A file whose path is named in a run record but whose bytes no longer match fails as `changed after run <run-id>` (exit 2, before the judge), not inconclusive: the path ties it to that run, so editing it after the run is tampering, not untied evidence.
 
-A config whose journeys are all code-only, or cited captures that all come from code-only runs, stop the check the same way, before the judge, naming the journeys ([Real-product evidence](#real-product-evidence)).
+A config whose journeys are all code-only, or cited captures that all come from code-only runs, stop the check the same way, before the judge, naming the journeys ([Real-product evidence](#real-product-evidence)). So does a claim that no cited run's step record covers ([Step record](#step-record)).
 
 `evidence: not proven: <cause>` stops the check before its judge is asked, always: exit 2, no result, no receipt. `checks.not_proven` is gone: a config that still sets it is a config error (exit 2) that says to delete the line.
 
@@ -429,7 +452,7 @@ done-done receipt --verify <head>         # read-only: check a recorded receipt
 
 `receipt` takes the same claim inputs as `check` and runs that check. It writes `<root>/.done-done/receipts/<head>.json` only when the check passes on the current HEAD, the tracked tree is clean, and the check cited at least one evidence file; a dirty tracked tree, a failed or inconclusive check, a pass that cited no evidence, or a moved HEAD writes nothing and exits non-zero. The record holds the repo, the head and tree sha, the claim outcome, every cited file with its sha256, the run behind each cited capture (`runs`: run id, journey and command, the command `null` for a run opened by hand or driven by the agent) and a timestamp. Every receipt is schema 2 and holds a `judge` block: the route, model, independence and author, and each judged file's path, sha256 and verdict. A cited file is stored relative to the repo, or as `<evidence root>/<path>` when it is under an evidence root outside the repo, so the receipt still finds it from another checkout or a restored evidence root.
 
-`receipt --verify <head>` changes nothing. The argument may be a full commit sha or a ref (`HEAD`, a branch or a tag), resolved to the commit with `git rev-parse --verify <arg>^{commit}` before the receipt lookup; an unresolvable argument fails with the same missing-receipt shape. It succeeds only when the receipt exists, is PASS, the current HEAD is still that head, and every cited file still hashes to the recorded sha256. A receipt is written only after a judge pass, so it reads schema 2 only: any other receipt (one recorded without the judge, or by an older build that let a run past its gate) fails as malformed, and a schema 2 receipt needs a well-formed `judge` block whose every verdict is `pass` for a cited file with the same sha256, which the result shows, and `runs` that are not all code-only ([Real-product evidence](#real-product-evidence)); a receipt with no `runs`, written before that rule, fails: re-run `receipt` for the head. A receipt from `--from` (or a `verify` run that drove the skill) also records the verify skill that ran as `skill` (for example `done-done-verify-<app>`), which `--verify` and so the merge gate show; an older receipt without it still verifies. A missing or malformed receipt and a hash mismatch are failures (exit 1), not usage errors. When the mismatched path is named in a run record, the failure names it as `changed after run <run-id>`.
+`receipt --verify <head>` changes nothing. The argument may be a full commit sha or a ref (`HEAD`, a branch or a tag), resolved to the commit with `git rev-parse --verify <arg>^{commit}` before the receipt lookup; an unresolvable argument fails with the same missing-receipt shape. It succeeds only when the receipt exists, is PASS, the current HEAD is still that head, and every cited file still hashes to the recorded sha256. A receipt is written only after a judge pass, so it reads schema 2 only: any other receipt (one recorded without the judge, or by an older build that let a run past its gate) fails as malformed, and a schema 2 receipt needs a well-formed `judge` block whose every verdict is `pass` for a cited file with the same sha256, which the result shows, and `runs` that are not all code-only ([Real-product evidence](#real-product-evidence)) and carry a step record covering the claim ([Step record](#step-record); a run recorded before step records passes with a `warnings` entry); a receipt with no `runs`, written before that rule, fails: re-run `receipt` for the head. A receipt from `--from` (or a `verify` run that drove the skill) also records the verify skill that ran as `skill` (for example `done-done-verify-<app>`), which `--verify` and so the merge gate show; an older receipt without it still verifies. A missing or malformed receipt and a hash mismatch are failures (exit 1), not usage errors. When the mismatched path is named in a run record, the failure names it as `changed after run <run-id>`.
 
 ### Verify a change in one run
 
@@ -562,11 +585,11 @@ npx -y done-done-axi gate "$PR_HEAD_SHA"
 
 The receipt is committed in a follow-up commit, because a receipt cannot sit inside the commit it proves (its hash would change). `gate [<head>] [--dir <folder>] [--pushed <time>]` prints `PASS` or `FAIL: <reason>` and exits 0, 1, or 2 on a usage error. It passes when a receipt in `.done-done-receipts/` (or `--dir`):
 
-- is a well-formed pass from a judged run (the same shape `receipt --verify` requires, so its `runs` are not all code-only, see [Real-product evidence](#real-product-evidence)) and is filed as `<its head>.json`;
+- is a well-formed pass from a judged run (the same shape `receipt --verify` requires, so its `runs` are not all code-only, see [Real-product evidence](#real-product-evidence), and carry a step record covering its claim, see [Step record](#step-record)) and is filed as `<its head>.json`;
 - has a head that is `<head>` (default `HEAD`) or an ancestor of it, with every file changed since that head inside the receipts folder, so the proof still covers the code;
 - was made no later than the push (`--pushed`, an ISO time; default the commit time of `<head>`), compared to the second.
 
-`gate` trusts the committed JSON: it does not re-hash the evidence, which only `receipt --verify` can do, on the machine that holds it. It says so by name and does not claim more.
+A receipt whose runs were recorded before step records passes with `WARN: ...` lines after `PASS`. `gate` trusts the committed JSON: it does not re-hash the evidence, which only `receipt --verify` can do, on the machine that holds it. It says so by name and does not claim more.
 
 ### Where proof lives
 

package/package.json

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