done-done-axi 0.6.10 → 0.6.11

package/README.md

@@ -194,6 +194,10 @@ That first run is a trial on uncommitted files, not proof. Read the generated sc
 
 Every answer is an exit code: **0** pass, **1** fail, **2** usage or config error (including no agent or judge set, a check that fails before its judge, a capture the judge cannot be sent, or a judge that did not answer: never a result), **3** can't tell either way, **4** a `verify`, `maintain` or `rerun` run is still running, or a `verify` run waits at its gate.
 
+### Interaction polish needs proof too
+
+Opt in with `interaction_checklist` in `.done-done.yaml`: detail next/previous plus swipe, instant send/answer state, destructive undo, scroll position on back, long-list search/filter, and useful empty states. Each item needs judged real-product frames or an explicit not-applicable reason; missing proof is flagged, never silently passed. The [shipped checklist and wiring](docs/reference.md#interaction-checklist-opt-in) extend `check`, `receipt` and `verify`; existing approved-design checks stay unchanged without opt-in.
+
 ## Alone, and with the other tools
 
 done-done works on its own: the CLI and the skill need nothing else. It is one of three tools that each do one job and connect through small written contracts ([Vision](VISION.md)):

package/dist/cli.js

@@ -10,12 +10,12 @@ import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { Document, parseDocument } from 'yaml';
 import { ACPX_INSTALL, agentChoices, agentPath, agentRun, askAgent, findBin, JUDGES, modelFor, noAgent, noJudge, notStartable, routeOf, selectAgent, selectFallback, selectJudge, toollessReason } from './agents.js';
-import { AGENTS, CHEAP, globalConfigText, home, inputPattern, isAgent, isJudgeRoute, loadConfig, parseDuration, tilde, UsageError } from './config.js';
+import { AGENTS, CHEAP, INTERACTIONS, globalConfigText, home, inputPattern, isAgent, isJudgeRoute, loadConfig, parseDuration, tilde, UsageError } from './config.js';
 import { backend, judge, judgeable, onPath, quote, screen } from './judge.js';
 import { startInstance, stopInstance } from './instance.js';
 import { attemptProblem, changedSince, commitFix, dirtyTracked, FIX_SCHEMA, inWorktree, maintainSteps, journeyProposal, named, pathspec, readerProblem, repoState, triage } from './maintain.js';
 import { cellEnv, cellName, cellSuffix, hasMatrix, matrixManifest, splitMatrix } from './matrix.js';
-import { design, KINDS } from './design.js';
+import { design, interactions, KINDS } from './design.js';
 import { checkMedia } from './media.js';
 import { domIssues, domRecord, isDomRecord, lookIssues, SQUASHED_TEXT } from './dom.js';
 import { lint } from './lint.js';
@@ -53,7 +53,11 @@ const CHECKS_TEXT = `Checks block (--from): the newest "## Checks" heading, then
   proof: <the command or path that drove the real product; name the repo's done-done-verify-<app> skill, or say "no verify skill">
   evidence: <the evidence file paths, or "not proven: <cause>">
   approved_design (.done-done.yaml): a non-empty manifest of {screen, size: <width>x<height>, theme, mock: <repo PNG/JPEG>, capture: <unique filename>};
-  every claim needs every listed live screen, paired with its mock and a passing design verdict; missing or unsure matches fail by screen/size/theme`;
+  every claim needs every listed live screen, paired with its mock and a passing design verdict; missing or unsure matches fail by screen/size/theme
+  interaction_checklist (.done-done.yaml, opt-in): map the six ids in skills/done-done/interaction-checklist.json to {captures: [<live PNG/JPEG filename>, ...]}
+  or {not_applicable: <reason>}; detail-navigation, instant-state, destructive-undo, scroll-restoration, list-search, empty-next-step.
+  check/receipt/verify report every item: pass only with judged real-product frames, not_applicable with a reason, otherwise flagged (exit 1).
+  Omitted checklist: unchanged behavior; interaction_checklist: {} flags all six. Frames must be cited from sealed runs; static controls alone do not prove an interaction`;
 const RUNS_TEXT = `runs: each verify or maintain run lives in $DONE_DONE_HOME/runs/<app>/<run-id> (run.json, events.jsonl, logs/<step>.log,
   agents/<n>-<name>.json for each agent call) and goes on when the command that started it ends;
   verify steps: resolve, drive, check, judge (always; skipped only after a failed check), triage and fix (only with auto_fix.verify above 0), gate, receipt, report;
@@ -1024,7 +1028,17 @@ async function runCheck(argv, run) {
         if (judgeBlock)
             judgeBlock.approved_design = matches;
     }
+    const touches = await interactions(cfg, choice, captures, run ? join(run.dir, 'agents') : join(home(), 'agents'));
+    for (const r of touches) {
+        r.captures = r.captures.map(c => ({ ...c, path: receiptPath(repo, cfg, cite(c.path)) }));
+        if (r.status === 'flagged')
+            findings.push({ level: 'fail', why: `interaction checklist: ${r.id}: flagged: ${r.reason}` });
+    }
+    if (judgeBlock && touches.length)
+        judgeBlock.interaction_checklist = touches;
     const rep = report(findings, files, { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel, warnings });
+    if (touches.length)
+        rep.result.interaction_checklist = touches;
     if (matches.length)
         rep.result.design = matches;
     if (rep.code === PASS) {
@@ -1070,6 +1084,11 @@ function receiptFault(rec, short) {
         return `receipt for ${short} has a malformed judge block`;
     if (j.approved_design !== undefined && (!Array.isArray(j.approved_design) || !j.approved_design.length || !j.approved_design.every(v => v && v.verdict === 'pass' && [v.screen, v.size, v.theme].every(s => typeof s === 'string' && s.trim()) && rec.files.some(f => f.path === v.path && f.sha256 === v.sha256) && rec.files.some(f => f.path === v.mock && f.sha256 === v.mock_sha256))))
         return `receipt for ${short} has a malformed approved-design verdict`;
+    if (j.interaction_checklist !== undefined) {
+        const rows = j.interaction_checklist;
+        if (!Array.isArray(rows) || rows.length !== Object.keys(INTERACTIONS).length || new Set(rows.map(r => r?.id)).size !== rows.length || !rows.every(r => r && Object.hasOwn(INTERACTIONS, r.id) && typeof r.reason === 'string' && r.reason.trim() && Array.isArray(r.captures) && (r.status === 'not_applicable' ? !r.captures.length : r.status === 'pass' && r.captures.length && r.captures.every(c => c && rec.files.some(f => f.path === c.path && f.sha256 === c.sha256)))))
+            return `receipt for ${short} has a malformed interaction-checklist verdict`;
+    }
     const code = runsFault(rec.runs);
     if (code)
         return `receipt for ${short} is no real-product proof: ${code}`;

package/dist/config.js

@@ -12,6 +12,7 @@ export class UsageError extends Error {
         this.help = help;
     }
 }
+export const INTERACTIONS = JSON.parse(readFileSync(new URL('../skills/done-done/interaction-checklist.json', import.meta.url), 'utf8'));
 // The coding agents a user can set as agent.
 export const AGENTS = ['claude', 'codex', 'opencode', 'pi', 'gemini'];
 // The agents whose CLI can read an attached image with every tool off, so they judge through the answerer route;
@@ -68,6 +69,7 @@ const KEYS = {
     dom: { scope: 'repo', type: 'dom' },
     look: { scope: 'repo', type: 'look' },
     approved_design: { scope: 'repo', type: 'approved_design' },
+    interaction_checklist: { scope: 'repo', type: 'interaction_checklist' },
     base_ref: { scope: 'repo', type: 'string' },
     'evidence.root': { scope: 'repo', type: 'string' },
     'evidence.allow_dirty': { scope: 'repo', type: 'boolean' },
@@ -214,6 +216,25 @@ function apply(target, text, file, scope) {
             target[key] = { command: v.command, ready: has(r.url) ? { url: r.url } : { command: r.command }, ready_timeout: v.ready_timeout ?? '30s' };
             continue;
         }
+        if (key === 'interaction_checklist') {
+            const fail = () => { throw new UsageError(`${file}: interaction_checklist needs known checklist ids, each with only captures: [<PNG/JPEG filename>, ...] (1-8), or not_applicable: <non-empty reason>`); };
+            if (!isMap(value))
+                fail();
+            for (const [id, row] of Object.entries(value)) {
+                if (!Object.hasOwn(INTERACTIONS, id) || !isMap(row) || Object.keys(row).length !== 1)
+                    fail();
+                const r = row;
+                if (Object.hasOwn(r, 'not_applicable')) {
+                    if (typeof r.not_applicable !== 'string' || !r.not_applicable.trim())
+                        fail();
+                }
+                else if (!Array.isArray(r.captures) || !r.captures.length || r.captures.length > 8 || new Set(r.captures).size !== r.captures.length || !r.captures.every(p => typeof p === 'string' && !/[\\/\\\\]/.test(p) && p !== '..' && /\.(png|jpe?g)$/i.test(p)))
+                    fail();
+            }
+            target.interaction_checklist = value;
+            target.from[key] = scope;
+            continue;
+        }
         if (key === 'approved_design') {
             const fail = () => { throw new UsageError(`${file}: approved_design must be a non-empty list of unique {screen, size: <width>x<height> in pixels, theme, mock: <repo-relative PNG/JPEG>, capture: <unique PNG/JPEG filename>}`); };
             const relativeImage = (p) => typeof p === 'string' && !isAbsolute(p) && !p.split(/[\\/]/).includes('..') && /\.(png|jpe?g)$/i.test(p);
@@ -314,6 +335,7 @@ function defaultConfig(repo) {
         dom: null,
         look: null,
         approved_design: [],
+        interaction_checklist: null,
         base_ref: '',
         evidence: { local_root: join(home(), 'evidence'), root: '', allow_dirty: false, ignore_paths: [] },
         secrets: { patterns: {}, allow: [] },

package/dist/design.js

@@ -1,8 +1,52 @@
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { home, UsageError } from './config.js';
+import { home, INTERACTIONS, UsageError } from './config.js';
 import { askJudge, backend, prepare, readCache, screen, VERSION, writeCache } from './judge.js';
 import { decodePixels } from './media.js';
+// Only sealed, cited product frames reach here. Missing evidence is a finding, never a model-inferred pass.
+export async function interactions(cfg, choice, captures, records) {
+    if (cfg.interaction_checklist === null)
+        return [];
+    const out = [];
+    for (const [id, requirement] of Object.entries(INTERACTIONS)) {
+        const entry = cfg.interaction_checklist[id];
+        const row = { id, status: 'flagged', reason: 'no real-product frame cited for this item', captures: [] };
+        if (entry?.not_applicable) {
+            row.status = 'not_applicable';
+            row.reason = entry.not_applicable;
+        }
+        else if (entry?.captures) {
+            const frames = entry.captures.map(name => captures.filter(c => c.name.split(/[\\/\\\\]/).at(-1) === name && screen(c)));
+            if (frames.some(f => f.length !== 1))
+                row.reason = 'each configured frame must name exactly one cited, run-bound PNG/JPEG: ' + entry.captures.join(', ');
+            else {
+                const shots = frames.map(f => f[0]);
+                row.captures = shots.map(c => ({ path: c.name, sha256: c.sha256 }));
+                const images = Object.fromEntries(shots.map((c, i) => {
+                    const img = image(c);
+                    if (typeof img === 'string')
+                        throw new UsageError(`interaction checklist: ${img}`);
+                    return [`frame_${i}`, img];
+                }));
+                const q = { interaction: { kind: 'choice', instructions: `Check this interaction on the real product: ${requirement} Frames are in action order. Describe visible evidence for each part before answering. Do not infer working behavior, timing, swipe or scroll restoration from a control's presence or a final state. Missing or insufficient evidence is missing, never shown.`, options: { shown: 'Every required part is demonstrated by these real-product frames.', missing: 'A required part is absent, broken or cannot be established from these frames.' }, images: Object.keys(images), floor: cfg.judge.floor, personReason: true } };
+                const key = createHash('sha256').update(JSON.stringify([VERSION, q, row.captures, choice.route, choice.model])).digest('hex');
+                const dir = join(home(), 'runs', cfg.app, 'interactions');
+                let hit = readCache(dir, key);
+                if (!hit || !['pass', 'flagged'].includes(hit.status) || typeof hit.reason !== 'string') {
+                    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+                    const b = await backend(cfg, choice, n => `${records}/interaction-${stamp}-${id}-${n}.agent.json`, q, ASK_ATTEMPTS);
+                    const a = (await askJudge(cfg, b, choice, { item: id, frames: entry.captures }, q, images)).interaction;
+                    hit = { status: !a.abstained && a.answer === 'shown' ? 'pass' : 'flagged', reason: a.personReason || a.rationale || 'interaction not demonstrated' };
+                    writeCache(dir, key, hit);
+                }
+                row.status = hit.status;
+                row.reason = hit.reason;
+            }
+        }
+        out.push(row);
+    }
+    return out;
+}
 // The defect kinds, each its own question. Each asks for something the judge can see and measure, not whether it was
 // meant that way: a cheap model talks itself out of a judgment ("an intentional style", "the viewer's border"), not out of
 // a measurement. look is what the judge writes in its rationale before it answers.

package/docs/reference.md

@@ -544,6 +544,24 @@ After those checks pass, each live image is sent beside its approved mock throug
 
 With no manifest, claims behave as before. `design` and `look --mock` remain ad-hoc measurements of supplied screens, not coverage claims: use `check`, `receipt` or `verify` to prove the complete approved inventory. This checks the declared inventory; it cannot discover an approved shot omitted from the manifest or establish capture authenticity beyond the existing run record.
 
+#### Interaction checklist (opt-in)
+
+Visual comparisons do not prove interaction polish. The package ships six requirements in `skills/done-done/interaction-checklist.json`: `detail-navigation` (next/previous **and swipe**), `instant-state` (immediate feedback on every send/answer), `destructive-undo` (undo restores content), `scroll-restoration` (back keeps list position), `list-search` (search/filter on long lists), and `empty-next-step` (empty states explain what to do next).
+
+Wire the checklist in the repo's committed `.done-done.yaml`; it works with or without `approved_design`:
+
+```yaml
+interaction_checklist:
+  empty-next-step: { captures: [empty.png] }
+  list-search: { captures: [list.png, filtered.png] }
+  detail-navigation: { not_applicable: "This product has no detail views" }
+  # Map the other three items too; omitted items are flagged, not passed.
+```
+
+`check`, `receipt` and `verify` report all six under `interaction_checklist`, with `id`, `status`, `reason` and bound capture paths/hashes. Each entry accepts **only** `captures` (1–8 unique PNG/JPEG filenames, in action order) or `not_applicable` (a non-empty surface-specific reason). Capture real product frames through the project's recipe and cite them from sealed runs. Missing, ambiguous or uncited frames, an omitted item, a judge rejection or an unsure answer produce **flagged findings (exit 1)**. A pass requires the judge to tie every required part to those frames; a static control or final reply alone cannot prove swipe, timing, undo or scroll restoration. Include before/action/after frames where needed; insufficient visual evidence stays flagged. There is no automatic video-frame extraction.
+
+A surface that does not exist must be explicitly `not_applicable` with its reason, never silently passed. Applicability is a declared inventory, not automatic surface discovery: reviewers must check those reasons and enumerate all relevant actions. Receipts preserve all six results under `judge.interaction_checklist`; passing frame hashes are bound to cited evidence, and receipt/gate validation rejects flagged or malformed entries. Without this config key, existing approved-design behavior is unchanged. `interaction_checklist: {}` opts in and flags all six; ad-hoc `design` is still only a visual check.
+
 ### Record a receipt
 
 A receipt ties one passing check to one commit and to the exact bytes it cited, so a merge gate (or `gate` in CI) can re-verify the same proof later.
@@ -759,6 +777,7 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 | `matrix` | none, so each journey runs once; `theme`, `width`, `form` and `skip` set the [capture matrix](#capture-matrix) |
 | `dom` | none; page-check records per capture, see [DOM assertions](#dom-assertions) |
 | `look` | none; the look step's approved design reference (`tokens`, `max_control`), see [Look check](#look-check) |
+| `interaction_checklist` | none; opt-in six-item interaction evidence map; omitted/unproven items flagged, absent surfaces need reasons; see [Interaction checklist](#interaction-checklist-opt-in) |
 | `approved_design` | none; committed screen × pixel size × theme manifest of mocks and required live filenames; gates all claims, see [Approved-design coverage](#approved-design-coverage) |
 | `inputs` | `[]`; repo-relative paths or globs the drive must leave alone, see [Input guard](#input-guard) |
 | `base_ref` | none; a ref `verify` also drives, pairing its captures with the head's, see [Base-ref before](#base-ref-before) |

package/docs/releasing.md

@@ -1,5 +1,5 @@
-# 0.6.10 patch release
+# 0.6.11 patch release
 
 This release shows the running version in CLI help headers, labels prereleases without changing the bare `--version` line, and clarifies the signoff posting hint.
 
-Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.10 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.
+Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.11 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "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

@@ -70,6 +70,13 @@ journeys:
     command: done-done look http://127.0.0.1:3000/inbox --out "$DONE_DONE_EVIDENCE_ROOT/inbox.png"
 ```
 
+Interaction coverage is opt-in via `interaction_checklist` in the repo config. Read the shipped `skills/done-done/interaction-checklist.json`:
+next/previous plus swipe in details, instant send/answer feedback, destructive undo, list scroll restoration, long-list search/filter,
+and empty-state next steps. Map every item to real-product frame filenames (`captures`, in action order) or `not_applicable`
+with a surface-specific reason. `check`, `receipt` and `verify` flag omitted or unproven items; only frames the judge ties to the item
+can pass. Static controls do not prove motion or timing. Capture the interaction, never substitute a mock. Without the key, approved-design behavior is unchanged;
+`done-done check --help` and `docs/reference.md` explain wiring.
+
 To gate a worker's claim cheaply, `done-done lint <PR URL | report file> <evidence folder>` reads the newest `## Checks` block
 with no judge or model and prints `PASS` or `FAIL: <reason>` (exit 1 on a fail): missing lines, evidence that is absent,
 empty, stale, duplicated or already used by another PR, a n/a repro on a fix, or a PR of 1,000+ added lines all fail.

package/skills/done-done/interaction-checklist.json

@@ -0,0 +1,8 @@
+{
+  "detail-navigation": "Detail views offer next and previous navigation plus swipe between items. Demonstrate both controls and the swipe transition, not just a static detail screen.",
+  "instant-state": "Every send or answer immediately shows a pending, sent, answered or error state. Demonstrate the action and its immediate feedback; a final reply alone does not prove timing.",
+  "destructive-undo": "Destructive actions offer undo. Demonstrate the action, visible undo and restored content after undo.",
+  "scroll-restoration": "Lists preserve scroll position on returning from a detail view. Demonstrate the scrolled list, opening a detail and returning to the same position.",
+  "list-search": "Long lists have usable search or filtering. Demonstrate the long list and the changed results after searching or filtering.",
+  "empty-next-step": "Empty states explain the next step a user can take. Show the real empty state with its actionable explanation."
+}