done-done-axi 0.6.4 → 0.6.5

package/dist/cli.js

@@ -128,6 +128,8 @@ const FLAGS = {
     '--run <run-id>': 'the run to show (default: the newest run of this checkout)',
     '--probe': 'ask the configured agent one JSON-schema question and require a valid answer (one call at the agent\'s model: its cheap default where it has one, else its own; set agent_config.<agent>.model to choose)',
     '--mock <screen>=<mock>': 'judge this screen next to its approved mock (repeat per screen; the screen is judged even when not listed)',
+    '--mock <file>': 'with look: the approved design of this page (PNG or JPEG); the judge the user set compares the capture with it, as design --mock does, and a defect fails look',
+    '--act <selector>': 'with look: click the element this CSS selector names, then require the page to change what a user can read (its text, elements or address) within 5s; repeat to click several in order; look measures and captures the page they leave',
     '--step <name>': 'the step log to show (verify: resolve, drive, check, judge, gate, receipt, report; maintain: locate, hygiene, source-wave, reconcile, triage, fix, report)',
     '--feature <name>': 'with no journey, the author agent drives this feature of the verify skill (features/<name>.md); default: the only feature, else the agent picks the one the outcome is about',
     '--action <approve|skip|fix>': 'at a spend gate, approve: spend and run the journey; skip: end the run with nothing spent. At the judge gate only fix or skip: fix ends it fail, then the product or the verify skill is fixed (done-done maintain checks it against the source); skip ends it fail without the fix',
@@ -220,12 +222,14 @@ const COMMANDS = {
   passed, 1 a screen failed, 3 none failed but one is unsure`],
     },
     look: {
-        usage: [['done-done look <url> [--out <file.png>]', 'open a page in headless Chrome at a phone viewport, capture it with its page-check record, and fail on any squashed, clipped or cut-off UI']],
-        flags: ['--out <file.png>'],
-        more: [`look: one deterministic step a journey calls as its command or inside its script; no judge, no model. It measures horizontal
+        usage: [['done-done look <url> [--act <selector>]... [--mock <file>] [--out <file.png>]', 'open a page in headless Chrome at a phone viewport, click each action, capture it with its page-check record, and fail on any squashed, clipped or cut-off UI, an action that changes nothing, or a mismatch with the design']],
+        flags: ['--act <selector>', '--mock <file>', '--out <file.png>'],
+        more: [`look: one step a journey calls as its command or inside its script; with no --mock, no judge and no model. It measures horizontal
   overflow, squashed text, text clipped by its container and elements cut off by the left, right or top edge, writes the
-  screenshot and its .dom.json record, and exits 1 naming each element, kind and text, 0 when there is none. A hit always
-  fails: never wrap it in || true. Needs Chrome or Chromium (DONE_DONE_CHROME names the binary)`],
+  screenshot and its .dom.json record, and exits 1 naming each element, kind and text, 0 when there is none. Each --act is
+  clicked and must change the page. With a look block in .done-done.yaml (the approved reference: tokens, max_control) it
+  also fails on a control drawn as the browser's own and on one taller than max_control. A hit always fails: never wrap it
+  in || true. Exit 3 when the only doubt is an unsure judge. Needs Chrome or Chromium (DONE_DONE_CHROME names the binary)`],
     },
     gate: {
         usage: [['done-done gate [<head>] [--dir <folder>] [--pushed <time>]', 'no-model check for a hosted runner: PASS or FAIL: <reason> for a receipt committed under .done-done-receipts/']],
@@ -764,6 +768,7 @@ async function runCheck(argv, run) {
     const captures = [];
     // The run behind each cited capture, for the real-product rule and the receipt.
     const runs = new Map();
+    const warnings = [];
     // base_ref: a capture in <run id>/before/ of a run that drove its base ref pairs with <run id>/<the same name>.
     const pairOf = (inRoot) => {
         const [id, dir, ...rest] = inRoot?.split(sep) ?? [];
@@ -809,7 +814,7 @@ async function runCheck(argv, run) {
         const inRoot = under(cfg.evidence.root, path);
         const pair = pairOf(inRoot);
         if (cfg.dom && !pair && ['png', 'jpeg', 'webp', 'gif', 'mp4', 'webm'].includes(v.type))
-            for (const why of domIssues(cfg.dom, path))
+            for (const why of domIssues(cfg.dom, path, cfg.look))
                 findings.push({ level: 'fail', why: `${name}: ${why}` });
         // A base capture may equal its head capture byte for byte: the pair's judge, not this check, says the screen did not change.
         if (seen.has(hash) && !record && !pair)
@@ -839,7 +844,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 }), ...(rec.tool && { tool: rec.tool }), ...(rec.steps && { steps: rec.steps }), ...(rec.steps_error && { steps_error: rec.steps_error }) });
+        runs.set(rec.run_id, { run_id: rec.run_id, commit: rec.commit, 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)
@@ -849,7 +854,11 @@ async function runCheck(argv, run) {
             if (rec.base)
                 heads.push([c, inRoot, rec]);
         }
-        const stale = staleness(repo, cfg, rec.commit, now.commit);
+        const kept = [];
+        const stale = staleness(repo, cfg, rec.commit, now.commit, rec, kept);
+        for (const w of kept)
+            if (!warnings.includes(w))
+                warnings.push(w);
         if (stale)
             findings.push({ level: 'fail', why: `${name}: ${stale} (run ${rec.run_id})` });
         if (rec.dirty && !cfg.evidence.allow_dirty)
@@ -873,7 +882,6 @@ async function runCheck(argv, run) {
     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)
@@ -1079,7 +1087,7 @@ function recordReceipt(repo, cfg, r) {
     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.
-function staleness(repo, cfg, from, to) {
+function staleness(repo, cfg, from, to, run, warnings = []) {
     if (from === to)
         return '';
     let changed;
@@ -1092,6 +1100,19 @@ function staleness(repo, cfg, from, to) {
     const outside = changed.filter((p) => !cfg.evidence.ignore_paths.some((g) => matchesGlob(p, g)));
     if (changed.length && !outside.length)
         return '';
+    // A head change that touches no journey or feature the run covered leaves its proof valid; both commits are reported.
+    const needs = outside.filter((p) => !p.startsWith(`${GATE_DIR}/`));
+    if (run && (run.journey || run.feature) && needs.length) {
+        const m = mapDiff(repo, cfg, needs, git(repo, 'ls-files', '-z').split('\0').filter(Boolean));
+        if (!m.journeys.some((j) => j.name === run.journey) && !m.features.some((f) => f.name === run.feature)) {
+            warnings.push(`run ${run.run_id} is for commit ${from.slice(0, 12)} and HEAD is ${to.slice(0, 12)}: its ${run.journey ? `journey ${run.journey}` : `feature ${run.feature}`} is untouched by the ${needs.length} changed file${needs.length === 1 ? '' : 's'} (done-done affected)`);
+            return '';
+        }
+    }
+    if (run && changed.length && !needs.length) {
+        warnings.push(`run ${run.run_id} is for commit ${from.slice(0, 12)} and HEAD is ${to.slice(0, 12)}: only gate receipts changed`);
+        return '';
+    }
     return `evidence is for commit ${from.slice(0, 12)}, HEAD is ${to.slice(0, 12)}${outside.length ? ` (changed: ${outside.slice(0, 3).join(', ')}${outside.length > 3 ? ', ...' : ''})` : ''}`;
 }
 // Quote an argument only when a shell would split it.
@@ -3812,9 +3833,9 @@ async function cmdDoctor(argv) {
     emit(result);
     return missingRequired.length ? USAGE : PASS;
 }
-// The design check: every named screen, and each --mock screen, judged for visual defects.
+// The look step: one page measured, with its actions clicked, against the project's look reference and the --mock design.
 async function cmdLook(argv) {
-    const { values, positionals } = parseArgs({ args: argv, options: { out: { type: 'string' } }, allowPositionals: true });
+    const { values, positionals } = parseArgs({ args: argv, options: { out: { type: 'string' }, mock: { type: 'string' }, act: { type: 'string', multiple: true } }, allowPositionals: true });
     if (positionals.length !== 1)
         throw new UsageError('look needs one page URL', 'Re-run with the page to check: done-done look <url>');
     // A path to a page on disk opens as its file:// URL.
@@ -3822,23 +3843,36 @@ async function cmdLook(argv) {
     const capture = resolve(values.out ?? join(process.env.DONE_DONE_EVIDENCE_ROOT || '.', 'look.png'));
     if (!capture.endsWith('.png'))
         throw new UsageError(`--out ${values.out} must be a .png file`);
+    const cfg = loadConfig(repoOrCwd());
+    // The mock and the judge are checked before Chrome starts, so a bad one costs no capture.
+    const mock = values.mock === undefined ? undefined : loadScreen(values.mock);
+    const choice = mock && (await preflightJudge(cfg, false));
     mkdirSync(dirname(capture), { recursive: true });
-    const record = await look(url, capture, 390, 844);
-    const hits = lookIssues(record);
+    const record = await look(url, capture, 390, 844, values.act ?? []);
+    const hits = lookIssues(record, cfg.look);
+    const [judged] = mock && choice ? await design(cfg, choice, [{ ...loadScreen(capture), mock }], join(home(), 'agents')) : [];
+    for (const d of judged?.defects ?? [])
+        hits.push(`${url} differs from the approved design ${values.mock}: ${d.kind}: ${d.where}`);
+    const code = hits.length ? FAIL : judged?.verdict === 'unsure' ? INCONCLUSIVE : PASS;
     const shown = cap(hits);
+    const again = `done-done look ${[positionals[0], ...(values.act ?? []).flatMap((a) => ['--act', a]), ...(values.mock ? ['--mock', values.mock] : []), ...(values.out ? ['--out', values.out] : [])].map(quote).join(' ')}`;
     emit({
         command: 'look',
         // look measures the layout; it gives no verdict on the outcome, which only the judged check does.
-        result: hits.length ? 'fail' : 'clean',
+        result: code === FAIL ? 'fail' : code === INCONCLUSIVE ? 'inconclusive' : 'clean',
         url,
         viewport: '390x844',
         capture,
         record: domRecord(capture),
+        ...(cfg.look && { reference: { ...cfg.look, ...(values.mock && { mock: values.mock }) } }),
+        ...(judged && { judge: { route: choice.route, model: choice.model, verdict: judged.verdict, ...(judged.reason && { reason: judged.reason }), ...(judged.cached && { cached: true }) } }),
         hits: shown.items,
         ...(shown.omitted && { hits_omitted: shown.omitted }),
-        help: hits.length ? [`Fix each element named above so it fits the 390 px wide screen, then re-run: done-done look ${quote(positionals[0])}${values.out ? ` --out ${quote(values.out)}` : ''}`] : ['No squashed, clipped or cut-off UI on this page; look at the capture to check the rest'],
+        help: code === FAIL ? [`Fix each element or action named above so it fits the 390 px wide screen, the design and its reference, then re-run: ${again}`]
+            : code === INCONCLUSIVE ? [`The judge is unsure the page matches ${values.mock}: look at both yourself, then re-run: ${again}`]
+                : ['No squashed, clipped or cut-off UI on this page; look at the capture to check the rest'],
     });
-    return hits.length ? FAIL : PASS;
+    return code;
 }
 // The folder of a branch where a receipt copied from the evidence root is committed, for `gate`.
 const GATE_DIR = '.done-done-receipts';
@@ -3916,6 +3950,25 @@ function cmdLint(argv) {
     console.log(!v.ok ? `FAIL: ${v.why}` : v.warn ? `WARN: ${v.warn}` : 'PASS');
     return v.ok ? PASS : FAIL;
 }
+// A screen or mock file for the design judge.
+function loadScreen(name) {
+    let bytes;
+    try {
+        bytes = readFileSync(name);
+    }
+    catch (e) {
+        throw new UsageError(`${name}: cannot read (${e.code ?? e.message})`, 'Pass screen and mock files that exist');
+    }
+    return { name, bytes, sha256: sha256(bytes), media: checkMedia(name, bytes) };
+}
+function repoOrCwd() {
+    try {
+        return repoRoot();
+    }
+    catch {
+        return process.cwd();
+    }
+}
 async function cmdDesign(argv) {
     const { values, positionals } = parseArgs({ args: argv, options: { mock: { type: 'string', multiple: true } }, allowPositionals: true });
     const mocks = new Map();
@@ -3928,25 +3981,8 @@ async function cmdDesign(argv) {
     const names = [...new Set([...positionals, ...[...mocks.keys()].filter((p) => !positionals.some((n) => resolve(n) === p))])];
     if (!names.length)
         throw new UsageError('design needs at least one screen file', 'Re-run with the screens to check: done-done design <screens...>');
-    const load = (name) => {
-        let bytes;
-        try {
-            bytes = readFileSync(name);
-        }
-        catch (e) {
-            throw new UsageError(`${name}: cannot read (${e.code ?? e.message})`, 'Pass screen and mock files that exist');
-        }
-        return { name, bytes, sha256: sha256(bytes), media: checkMedia(name, bytes) };
-    };
-    const screens = names.map((n) => ({ ...load(n), ...(mocks.has(resolve(n)) && { mock: load(mocks.get(resolve(n))) }) }));
-    let repo;
-    try {
-        repo = repoRoot();
-    }
-    catch {
-        repo = process.cwd();
-    }
-    const cfg = loadConfig(repo);
+    const screens = names.map((n) => ({ ...loadScreen(n), ...(mocks.has(resolve(n)) && { mock: loadScreen(mocks.get(resolve(n))) }) }));
+    const cfg = loadConfig(repoOrCwd());
     const choice = await preflightJudge(cfg, false);
     const judged = await design(cfg, choice, screens, join(home(), 'agents'));
     const count = (v) => judged.filter((j) => j.verdict === v).length;
@@ -3992,6 +4028,13 @@ function defaultBranch(repo) {
     }
 }
 const isAncestor = (repo, a, b) => spawnSync('git', ['merge-base', '--is-ancestor', a, b], { cwd: repo, stdio: 'ignore' }).status === 0;
+// The journeys and features `changed` needs (src/affected.ts), from the verify skill at the working tree.
+function mapDiff(repo, cfg, changed, tracked, noBase) {
+    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));
+    return mapChange({ changed, tracked, journeys: cfg.journeys, skill: cfg.skill, features, coreFeature: coreLine?.match(/\]\(([^)#]+)\.md\)/)?.[1], noBase });
+}
 // 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.
@@ -4025,10 +4068,7 @@ function affectedOf(repo, cfg, baseArg) {
     // 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 m = mapDiff(repo, cfg, changed, tracked, 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');

package/dist/config.js

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse } from 'yaml';
 import { checkMatrix } from './matrix.js';
-import { parseDom } from './dom.js';
+import { parseDom, parseLook } from './dom.js';
 export class UsageError extends Error {
     help;
     // The exact next command, when the error has one.
@@ -66,6 +66,7 @@ const KEYS = {
     instance: { scope: 'repo', type: 'instance' },
     matrix: { scope: 'repo', type: 'matrix' },
     dom: { scope: 'repo', type: 'dom' },
+    look: { scope: 'repo', type: 'look' },
     base_ref: { scope: 'repo', type: 'string' },
     'evidence.root': { scope: 'repo', type: 'string' },
     'evidence.allow_dirty': { scope: 'repo', type: 'boolean' },
@@ -219,6 +220,14 @@ function apply(target, text, file, scope) {
             target.dom = d;
             continue;
         }
+        if (key === 'look') {
+            const l = parseLook(value, dirname(file));
+            if (typeof l === 'string')
+                throw new UsageError(`${file}: look ${l}`);
+            target.from[key] = scope;
+            target.look = l;
+            continue;
+        }
         if (!ok)
             throw new UsageError(`${file}: ${key} must be ${want[spec.type] ?? `a ${spec.type}`}${key === 'matrix' ? `: ${checkMatrix(value)}` : ''}`);
         if (key === 'agent_config')
@@ -279,6 +288,7 @@ function defaultConfig(repo) {
         instance: null,
         matrix: null,
         dom: null,
+        look: null,
         base_ref: '',
         evidence: { local_root: join(home(), 'evidence'), root: '', allow_dirty: false, ignore_paths: [] },
         secrets: { patterns: {}, allow: [] },

package/dist/dom.js

@@ -5,10 +5,12 @@
 //    "console_errors": ["<message>", ...], "failed_requests": [{"url": "<request url>", "status": <HTTP status, 0 when none>}],
 //    "squashed_text": [{"element": "<element>", "text": "<its text, ~40 chars>", "chars": <width>, "lines": <n>, "words": <n>}],
 //    "clipped_text": [{"element": "<element>", "text": "<its text>", "by": "<the container that cuts it>"}],
-//    "cut_off": [{"element": "<element>", "text": "<its text>", "edges": ["left" | "right" | "top", ...]}]}
-// squashed_text, clipped_text and cut_off are optional, so a record written before them stays valid.
+//    "cut_off": [{"element": "<element>", "text": "<its text>", "edges": ["left" | "right" | "top", ...]}],
+//    "controls": [{"element": "<element>", "text": "<its label>", "native": <true when drawn as the browser's own control>, "height": <px, absent for a textarea or list box>}],
+//    "actions": [{"selector": "<what was clicked>", "text": "<its label>", "failed": "<why it did not complete, absent when it did>"}]}
+// squashed_text, clipped_text, cut_off, controls and actions are optional, so a record written before them stays valid.
 import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, resolve } from 'node:path';
 // The measurement the recipe passes to its browser tool's eval, so no agent invents one: every visible element with its
 // own non-empty text is squashed when its box is under 8 characters wide (box width / the average glyph width of its
 // font) while its text is wider than the box, or when its text sits on more line boxes than it has words.
@@ -67,6 +69,39 @@ export const LOOK = `() => {
   }
   return { overflow: document.documentElement.scrollWidth > vw, overflowing: [...document.querySelectorAll('body *')].filter((e) => e.getBoundingClientRect().right > vw + 1).slice(0, 10).map(name), ...out };
 }`.replace(/\s*\n\s*/g, ' ');
+// Every visible control with its label and height, and whether it is drawn as the browser's own: its background and
+// border are what the browser gives the same control (same tag, input type and colour scheme) on a page with no styles.
+// A checkbox, radio, range, colour or file input is not measured, and a textarea or list box has no height to hold.
+export const CONTROLS = `() => {
+  const name = (e) => e.tagName.toLowerCase() + (e.id ? '#' + e.id : e.classList[0] ? '.' + e.classList[0] : '');
+  const f = document.createElement('iframe'); f.style.cssText = 'position:fixed;width:0;height:0;border:0'; document.documentElement.append(f);
+  const d = f.contentDocument; d.open(); d.write('<!doctype html><body>'); d.close();
+  const keys = ['backgroundColor', 'borderTopStyle', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius']; const out = [];
+  for (const e of document.querySelectorAll('button, select, textarea, input, [role=button]')) {
+    const s = getComputedStyle(e); const r = e.getBoundingClientRect();
+    if (!e.getClientRects().length || s.visibility !== 'visible' || r.width < 1 || r.height < 1 || (e.tagName === 'INPUT' && ['checkbox', 'radio', 'range', 'color', 'file'].includes(e.type))) continue;
+    let native = false;
+    if (['BUTTON', 'SELECT', 'TEXTAREA', 'INPUT'].includes(e.tagName)) { const t = d.createElement(e.tagName); if (e.tagName === 'INPUT') t.type = e.type; t.style.colorScheme = s.colorScheme; d.body.append(t); const u = f.contentWindow.getComputedStyle(t); native = keys.every((k) => s[k] === u[k]); }
+    const tall = e.tagName === 'TEXTAREA' || (e.tagName === 'SELECT' && (e.multiple || e.size > 1));
+    out.push({ element: name(e), text: (e.getAttribute('aria-label') || e.innerText || e.value || e.placeholder || '').replace(/\\s+/g, ' ').trim().slice(0, 40), native, ...(!tall && { height: Math.round(r.height) }) });
+  }
+  f.remove(); return out;
+}`.replace(/\s*\n\s*/g, ' ');
+// What a user can read of the page: its address, how many elements it has and its visible text. An action completes when
+// this changes: a card moves, a reply shows as saved, a toast says so.
+const STATE = "(() => location.href + '\\n' + document.querySelectorAll('body *').length + '\\n' + document.body.innerText)()";
+// Where to click the action `sel` names, with its label and the page state before it, or why it cannot be clicked.
+export const AIM = `(sel) => {
+  const e = document.querySelector(sel); if (!e) return { text: '', failed: 'is not on the page' };
+  e.scrollIntoView({ block: 'center' }); const r = e.getBoundingClientRect(); const x = r.left + r.width / 2; const y = r.top + r.height / 2;
+  const text = (e.getAttribute('aria-label') || e.innerText || e.value || '').replace(/\\s+/g, ' ').trim().slice(0, 40);
+  if (e.disabled || e.getAttribute('aria-disabled') === 'true') return { text, failed: 'is disabled' };
+  const hit = document.elementFromPoint(x, y);
+  if (!hit || (hit !== e && !e.contains(hit))) return { text, failed: 'is covered by ' + (hit ? hit.tagName.toLowerCase() + (hit.id ? '#' + hit.id : hit.classList[0] ? '.' + hit.classList[0] : '') : 'nothing that takes a click') };
+  return { text, x, y, before: ${STATE} };
+}`.replace(/\s*\n\s*/g, ' ');
+// Whether the page state differs from `before` within `ms`, checked each 50 ms.
+export const CHANGED = `async (before, ms) => { for (let t = 0; t <= ms; t += 50) { if (${STATE} !== before) return true; await new Promise((r) => setTimeout(r, 50)); } return false; }`;
 const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const strings = (a) => Array.isArray(a) && a.every((s) => typeof s === 'string');
 // An optional record list: absent, or every item has an element and text and passes `more`.
@@ -100,8 +135,41 @@ export function parseDom(v) {
         return 'fail_on_overflow must be true or false';
     return { allow_console: v.allow_console ?? [], allow_requests: v.allow_requests ?? [], fail_on_overflow: v.fail_on_overflow ?? true };
 }
+// The look block read from config in `repo`, or the reason it is not one. max_control is a number of px, or the name of
+// a custom property in the tokens file (--ctl-h: 2.75rem), read as px with a rem or em of 16 px.
+export function parseLook(v, repo) {
+    if (v == null)
+        v = {};
+    if (!isMap(v))
+        return 'a mapping with optional tokens and max_control';
+    for (const k of Object.keys(v))
+        if (!['tokens', 'max_control'].includes(k))
+            return `unknown key ${k} (tokens, max_control)`;
+    const { tokens, max_control: max } = v;
+    if (tokens !== undefined && (typeof tokens !== 'string' || !tokens))
+        return 'tokens must be the path of the design tokens file';
+    if (typeof max === 'number')
+        return max > 0 ? { ...(tokens && { tokens }), max_control: max } : 'max_control must be more than 0 px';
+    if (max === undefined)
+        return tokens ? { tokens } : {};
+    if (typeof max !== 'string' || !/^--[\w-]+$/.test(max))
+        return 'max_control must be a number of px or the name of a token such as --ctl-h';
+    if (!tokens)
+        return `max_control ${max} names a token, so tokens must name the file that sets it`;
+    let text;
+    try {
+        text = readFileSync(resolve(repo, tokens), 'utf8');
+    }
+    catch (e) {
+        return `tokens ${tokens} does not read: ${e.code ?? e.message}`;
+    }
+    const m = new RegExp(`(?<![\\w-])${max}\\s*:\\s*([\\d.]+)(px|rem|em)\\s*[;}]`).exec(text);
+    if (!m)
+        return `max_control ${max} is not set in ${tokens} as a px, rem or em size`;
+    return { tokens, max_control: Number(m[1]) * (m[2] === 'px' ? 1 : 16) };
+}
 // Every non-allowed issue the capture's page-check record shows; a missing or malformed record is an issue too.
-export function domIssues(dom, capture) {
+export function domIssues(dom, capture, ref) {
     const path = domRecord(capture);
     let r;
     try {
@@ -114,22 +182,28 @@ export function domIssues(dom, capture) {
     if (!isMap(r) || typeof r.url !== 'string' || typeof r.overflow !== 'boolean' || !strings(r.overflowing ?? []) || !strings(r.console_errors)
         || !Array.isArray(r.failed_requests) || !r.failed_requests.every((q) => isMap(q) && typeof q.url === 'string' && typeof q.status === 'number')
         || !list(r.squashed_text, (q) => [q.chars, q.lines, q.words].every((n) => typeof n === 'number'))
-        || !list(r.clipped_text, (q) => typeof q.by === 'string') || !list(r.cut_off, (q) => strings(q.edges)))
-        return [`page-check record ${basename(path)} is not {url, overflow, overflowing, console_errors, failed_requests: [{url, status}], squashed_text: [{element, text, chars, lines, words}], clipped_text: [{element, text, by}], cut_off: [{element, text, edges}]}`];
+        || !list(r.clipped_text, (q) => typeof q.by === 'string') || !list(r.cut_off, (q) => strings(q.edges))
+        || !list(r.controls, (q) => typeof q.native === 'boolean' && ['number', 'undefined'].includes(typeof q.height))
+        || !(r.actions === undefined || (Array.isArray(r.actions) && r.actions.every((q) => isMap(q) && typeof q.selector === 'string' && typeof q.text === 'string' && ['string', 'undefined'].includes(typeof q.failed)))))
+        return [`page-check record ${basename(path)} is not {url, overflow, overflowing, console_errors, failed_requests: [{url, status}], squashed_text: [{element, text, chars, lines, words}], clipped_text: [{element, text, by}], cut_off: [{element, text, edges}], controls: [{element, text, native, height}], actions: [{selector, text, failed}]}`];
     const allowed = (list, s) => list.some((re) => new RegExp(re).test(s));
     return [
-        ...lookIssues({ ...r, overflow: dom.fail_on_overflow && r.overflow }),
+        ...lookIssues({ ...r, overflow: dom.fail_on_overflow && r.overflow }, ref),
         ...r.console_errors.filter((m) => !allowed(dom.allow_console, m)).map((m) => `${r.url} console error: ${m}`),
         ...r.failed_requests.filter((q) => (q.status === 0 || q.status >= 400) && !allowed(dom.allow_requests, q.url)).map((q) => `${r.url} request failed (${q.status || 'no response'}): ${q.url}`),
     ];
 }
-// The look defects a page-check record shows: horizontal overflow, squashed, clipped and cut-off text or elements.
-export function lookIssues(r) {
+// The look defects a page-check record shows: horizontal overflow, squashed, clipped and cut-off text or elements, and an
+// action that did not complete; against a reference, also a control drawn as the browser's own or taller than max_control.
+export function lookIssues(r, ref) {
     const quoted = (t) => (t ? ` "${t}"` : '');
     return [
         ...(r.overflow ? [`${r.url} overflows the viewport horizontally${r.overflowing?.length ? ` (${r.overflowing.join(', ')})` : ''}`] : []),
         ...(r.squashed_text ?? []).map((q) => `${r.url} squashed text: ${q.element} "${q.text}" is ${q.chars} characters wide (lines ${q.lines}, words ${q.words})`),
         ...(r.clipped_text ?? []).map((q) => `${r.url} clipped text: ${q.element}${quoted(q.text)} is cut by ${q.by}`),
         ...(r.cut_off ?? []).map((q) => `${r.url} cut off: ${q.element}${quoted(q.text)} runs past the ${q.edges.join(' and ')} edge of the viewport`),
+        ...(ref ? r.controls ?? [] : []).filter((q) => q.native).map((q) => `${r.url} unstyled control: ${q.element}${quoted(q.text)} is drawn as the browser's own control, not with the design's style`),
+        ...(ref?.max_control ? r.controls ?? [] : []).filter((q) => q.height > ref.max_control + 0.5).map((q) => `${r.url} oversized control: ${q.element}${quoted(q.text)} is ${q.height} px tall, over the ${ref.max_control} px the design allows`),
+        ...(r.actions ?? []).filter((q) => q.failed).map((q) => `${r.url} action did not complete: ${q.selector}${quoted(q.text)} ${q.failed}`),
     ];
 }

package/dist/look.js

@@ -3,14 +3,17 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { UsageError } from './config.js';
-import { domRecord, LOOK, SQUASHED_TEXT } from './dom.js';
+import { AIM, CHANGED, CONTROLS, domRecord, LOOK, SQUASHED_TEXT } from './dom.js';
 import { findBin } from './agents.js';
 // done-done look: opens one page in headless Chrome at a phone viewport over the DevTools protocol (Node's own
-// WebSocket, no browser library), writes the screenshot and its page-check record next to it, and returns the record.
+// WebSocket, no browser library), clicks each action in `acts` in order (a CSS selector each) and waits for it to complete,
+// then writes the screenshot and its page-check record next to it, and returns the record.
 // Chrome runs without its sandbox so it starts in containers: point look at your own app, not untrusted sites.
 const BROWSERS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'];
 const WAIT = 30_000;
-export async function look(url, capture, width, height) {
+// How long an action has to change what a user can read of the page.
+const ACT = 5_000;
+export async function look(url, capture, width, height, acts = []) {
     const bin = process.env.DONE_DONE_CHROME ? findBin(process.env.DONE_DONE_CHROME) : BROWSERS.map(findBin).find(Boolean);
     if (!bin)
         throw new UsageError(`look needs Chrome or Chromium: ${process.env.DONE_DONE_CHROME ? `DONE_DONE_CHROME=${process.env.DONE_DONE_CHROME} is not an executable` : `none of ${BROWSERS.slice(0, 4).join(', ')} is on PATH`}`, 'Install Chrome or Chromium, or set DONE_DONE_CHROME to its binary');
@@ -93,8 +96,23 @@ export async function look(url, capture, width, height) {
             throw new Error(`${url} did not load: ${nav.errorText}`);
         await loaded;
         // Web fonts change text widths, so measure once they are in and two frames have painted.
-        await evaluate('document.fonts.ready.then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))))');
-        const record = { url, ...(await evaluate(`(${LOOK})()`)), console_errors: consoleErrors, failed_requests: failed, squashed_text: await evaluate(`(${SQUASHED_TEXT})()`) };
+        const settle = () => evaluate('document.fonts.ready.then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))))');
+        await settle();
+        // Each action is a real click at its centre, so a control under a toast or overlay fails as covered.
+        const actions = [];
+        for (const selector of acts) {
+            const at = await evaluate(`(${AIM})(${JSON.stringify(selector)})`);
+            if (!at.failed) {
+                for (const type of ['mousePressed', 'mouseReleased'])
+                    await send('Input.dispatchMouseEvent', { type, x: at.x, y: at.y, button: 'left', clickCount: 1 });
+                if (!(await evaluate(`(${CHANGED})(${JSON.stringify(at.before)}, ${ACT})`)))
+                    at.failed = `changed nothing a user can read on the page (its text, elements or address) within ${ACT / 1000}s`;
+            }
+            actions.push({ selector, text: at.text, ...(at.failed && { failed: at.failed }) });
+        }
+        if (acts.length)
+            await evaluate('scrollTo(0, 0)').then(settle);
+        const record = { url, ...(await evaluate(`(${LOOK})()`)), console_errors: consoleErrors, failed_requests: failed, squashed_text: await evaluate(`(${SQUASHED_TEXT})()`), controls: await evaluate(`(${CONTROLS})()`), ...(acts.length && { actions }) };
         const shot = await send('Page.captureScreenshot', { format: 'png' });
         writeFileSync(capture, Buffer.from(shot.data, 'base64'));
         writeFileSync(domRecord(capture), `${JSON.stringify(record, null, 2)}\n`);

package/docs/reference.md

@@ -177,18 +177,23 @@ done-done never drives the browser: the recipe or journey writes one page-check
 {"url": "http://127.0.0.1:4100/", "overflow": true, "overflowing": ["div#wide"], "console_errors": ["boom"], "failed_requests": [{"url": "http://127.0.0.1:4100/x.js", "status": 404}],
  "squashed_text": [{"element": "h3.card-title", "text": "Approved", "chars": 1.6, "lines": 8, "words": 1}],
  "clipped_text": [{"element": "h3.card-title", "text": "Answered: the release notes are approved", "by": "its own box"}],
- "cut_off": [{"element": "div.clock", "text": "12:30", "edges": ["top"]}]}
+ "cut_off": [{"element": "div.clock", "text": "12:30", "edges": ["top"]}],
+ "controls": [{"element": "button#request", "text": "Request changes", "native": true, "height": 21}],
+ "actions": [{"selector": "#request", "text": "Request changes", "failed": "changed nothing a user can read on the page (its text, elements or address) within 5s"}]}
 ```
 
+`controls` and `actions` are optional too; [`done-done look`](#look-check) writes `controls` on every page and `actions` when it clicks one. With a [`look` block](#look-check), the check fails on each control in `controls` drawn as the browser's own, and on one taller than `max_control`; it fails on each `actions` item with a `failed` reason with or without one. A recipe that drives its own browser runs done-done's `CONTROLS` measurement (exported from `dom.js` next to `LOOK`) for `controls`, and `AIM` and `CHANGED` around each click for `actions`.
+
 With your browser tool, for example chrome-devtools-axi: `overflow` and `overflowing` from `eval` (document `scrollWidth` beyond `clientWidth`, and the elements whose right edge passes it), `console_errors` from `console --type error`, `failed_requests` (status 400 or more, or 0 for no response) from `network`, `squashed_text` from `eval` of done-done's measurement function, run in each frame of the page (an embedded frame too). It lists every visible HTML element with its own text (SVG text has no layout box and is skipped; widths are untransformed layout pixels, so a scaled ancestor does not shrink them) whose box is under 8 characters wide (its width over the average glyph width of its font) while its text is wider than the box, or whose text sits on more lines (distinct line boxes) than it has words: a title wrapped one letter per line in a narrow column. `squashed_text`, `clipped_text` and `cut_off` are optional, so a record written without them stays valid; [`done-done look`](#look-check) writes all of them, and the check fails on each `clipped_text` and `cut_off` item as it does on `squashed_text`. The agent drive prompt carries the recipe, and a verify skill should carry it too. Verify's check and `done-done check` fail naming the capture and each issue not on an allow list, and fail when a capture has no record or a record is not this shape. No `dom` block keeps today's behaviour.
 
 ### Look check
 
-`done-done look` is the look step a journey calls on a web page. It opens the page in headless Chrome at a 390x844 phone viewport (a mobile device at 1x scale), measures the look defects in the DOM, writes the screenshot with its page-check record next to it, and exits 1 on any hit, naming the element, the kind and its text. It is a measurement step, not a verdict: with no hit it ends `result: clean` (exit 0), never `pass`, and its capture is judged when a `check` or `verify` cites it. No model runs here, so the same page gives the same answer. A worker's claim that a phone UI works needs this 390 px capture of the real page, plus the page's scroll-container count, as proof; a mock or another width is not proof.
+`done-done look` is the look step a journey calls on a web page. It opens the page in headless Chrome at a 390x844 phone viewport (a mobile device at 1x scale), clicks each `--act` and checks it completes, measures the look defects in the DOM, writes the screenshot with its page-check record next to it, and exits 1 on any hit, naming the element, the kind and its text. It is a measurement step, not a verdict: with no hit it ends `result: clean` (exit 0), never `pass`, and its capture is judged when a `check` or `verify` cites it. Without `--mock` no model runs here, so the same page gives the same answer. A worker's claim that a phone UI works needs this 390 px capture of the real page, plus the page's scroll-container count, as proof; a mock or another width is not proof.
 
 ```sh
 done-done look http://127.0.0.1:3000/inbox --out "$DONE_DONE_EVIDENCE_ROOT/inbox.png"
 done-done look ./public/inbox.html                     # a path on disk opens as its file:// URL
+done-done look "$DONE_DONE_BASE_URL/#decide" --act '#item-1 .approve' --mock design/decide.png --out "$DONE_DONE_EVIDENCE_ROOT/decide.png"
 ```
 
 A journey in `.done-done.yaml` that calls it (one command per screen, `&&` between them, so the first hit stops the journey):
@@ -211,17 +216,31 @@ journeys:
   | squashed text | done-done's [squashed-text measurement](#dom-assertions): a text block under 8 characters wide while its text does not fit, or on more lines than it has words |
   | clipped text | part of an element's text shows and part runs past a container that hides its overflow (`overflow: hidden` or `clip`), with no `text-overflow: ellipsis` (sideways) or line clamp (downwards): a card title cut to one line |
   | cut off | part of an element shows and part lies past the left, right or top edge of the viewport: a status-bar clock clipped at the top. The page is at its top, so content below the bottom edge is fine |
+  | action did not complete | an `--act <selector>` names nothing, a disabled control, or one covered where its centre is (a toast over a button), or its click changes nothing a user can read within 5 seconds: the page's visible text, its element count and its address all stay the same. A card that moves, a reply that shows as saved or a toast that says so is a change; a button that is only there is not |
+  | unstyled control | with a `look` block: a button, select, textarea or input drawn as the browser's own, its background and border the ones the browser gives the same control (same tag, input type and colour scheme) on a page with no styles. Checkbox, radio, range, colour and file inputs are not measured |
+  | oversized control | with `look.max_control`: a button, select, input or `role=button` taller than that many px. A textarea or list box is not measured |
+  | differs from the approved design | with `--mock <file>`: the [design check](#design-check)'s judge (the one the user set) names a defect on the capture next to that approved mock, the same request as `design --mock`, cached the same way |
 
   Something entirely outside its container or the viewport is hidden on purpose (a closed drawer, a visually hidden label) and is not a hit; a cut element's children are not listed again. Content in a scrolling container (`overflow: auto` or `scroll`, such as a carousel) scrolls into view and is not clipped.
-- **What it writes.** `--out <file.png>` (default `look.png` in `$DONE_DONE_EVIDENCE_ROOT` inside a journey, else in the current folder) gets the viewport screenshot, exactly the viewport size in pixels, and `<file>.dom.json` next to it the page-check record of [DOM assertions](#dom-assertions), with the page's console errors and failed requests too. look itself fails only on the four kinds above; with a `dom` block, verify's check also reads the record and applies its allow lists to console errors and failed requests.
+- **The approved reference.** A `look` block in `.done-done.yaml` is the project's approved design reference; with none, look behaves as before:
+
+  ```yaml
+  look:
+    tokens: web/tokens.css   # the approved design tokens file, relative to the repo
+    max_control: --ctl-h     # the tallest a control may be: px (44), or a token in tokens set in px, rem or em (a rem or em is 16 px)
+  ```
+
+  The block alone turns on the unstyled-control check; `max_control` adds the size check. A token that is not set in the file, a tokens file that does not read or an unknown key is a config error (exit 2). The per-page reference is its mock: pass `--mock <file>` with the approved design of that screen. The `--act` clicks are real mouse clicks at each control's centre, in order, and the page they leave is the one measured and captured, so a journey drives the page to the state to check with them.
+- **What it writes.** `--out <file.png>` (default `look.png` in `$DONE_DONE_EVIDENCE_ROOT` inside a journey, else in the current folder) gets the viewport screenshot, exactly the viewport size in pixels, and `<file>.dom.json` next to it the page-check record of [DOM assertions](#dom-assertions), with the page's console errors and failed requests too. look itself fails only on the kinds above; with a `dom` block, verify's check also reads the record and applies its allow lists to console errors and failed requests.
 - **Chrome.** look starts its own headless Chrome or Chromium (`google-chrome`, `google-chrome-stable`, `chromium` or `chromium-browser` on PATH, or `DONE_DONE_CHROME` naming the binary) with a throwaway profile, and removes both when it ends. It runs Chrome without its sandbox so it starts in containers, so point it at your own app, not untrusted sites. No Chrome is a usage error (exit 2) that says how to install or point to one; a page that does not load (its network error, or no load event within 30 seconds) is exit 2 with the cause.
-- **Limits.** Only the main frame is measured, not an embedded frame; a transform or `clip-path` that hides part of a box is not seen; nothing is clicked or scrolled first, so drive the page to the state to check (a URL per state) before you call look. Look at the capture too: a defect the DOM cannot see (a stretched image, a colour) is the [design check](#design-check)'s.
+- **Limits.** Only the main frame is measured, not an embedded frame; a transform or `clip-path` that hides part of a box is not seen; nothing is scrolled first, and only `--act` clicks; drive any other state (typing, a URL per state) before you call look. Look at the capture too: a defect the DOM cannot see (a stretched image, a colour) is the [design check](#design-check)'s.
 
 | Result | Exit |
 |---|---|
 | no hit | 0 |
 | a hit of any kind | 1 |
-| bad flags, no Chrome, or the page did not load | 2 |
+| bad flags, a bad `look` block, no Chrome, the page did not load, or `--mock` with no judge set | 2 |
+| no hit, but the `--mock` judge is unsure | 3 |
 
 ### Lint check
 
@@ -349,7 +368,7 @@ evidence: <paths of the evidence files, or "not proven: <cause>">
 |---|---|
 | Not empty | The file must contain bytes. |
 | Valid media | The magic bytes match the extension. PNG and JPEG are complete (end markers present) and at least 64×64. PNG is not a blank frame. WebP and GIF are not truncated. MP4/MOV and WebM/MKV decode at least two video packets (`ffprobe`). Text and log files hold text; JSON parses. |
-| Fresh | The file is in a run record whose commit is HEAD. The one exception: if the only commits since the run touch `ignore_paths`, the evidence still counts. An empty commit does not count as touching only `ignore_paths`. |
+| Fresh | The file is in a run record whose commit is HEAD. Two exceptions: if the only commits since the run touch `ignore_paths`, the evidence still counts; and if the changed files touch no journey or feature the run covered (the same mapping as `done-done affected`, model-free), the proof holds and the result warns with both commits. A change that does touch the run's journey is stale. A receipt keeps each run's `commit` beside its own `head`. An empty commit does not count as touching only `ignore_paths`. |
 | Clean | The run was not dirty, unless `evidence.allow_dirty: true`. The run command also exited 0. |
 | Not reused | Fails when the files are byte-identical within one claim. Also fails when every file was already used to prove a different claim in this repo. A claim is named by `--claim-id <id>`, by default the current branch (with `--from <PR URL>`, the PR's branch; on a detached HEAD, the commit), so rewording the outcome is not reuse. One branch is one claim: several claims on one branch each need their own `--claim-id`, or they share one reuse scope. The ledger is `<root>/.done-done/ledger` in the evidence root, so each repo keeps its own (pin `app`, as `init` does, so two repos with the same directory name do not share one); `DONE_DONE_HOME` moves it only with the default evidence root. |
 
@@ -653,6 +672,7 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 | `instance` | none; the app under test started per run, see [Run-instance harness](#run-instance-harness) |
 | `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) |
 | `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) |
 | `evidence.root` | `<local_root>/<app>`, outside the repo. A relative path is under the repo; an absolute path is used as-is |

package/package.json

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

@@ -50,7 +50,11 @@ its findings and captures, and end it with `done-done respond --action fix` only
 A journey that `spends` runs only after the user approves spending: `done-done run <journey>` refuses it, so ask the user and use `verify`.
 
 For a web page, `done-done look <url>` is the look step a journey calls: it captures the page at a 390x844 phone viewport
-with its page-check record and exits 1 on squashed, clipped or cut-off UI, naming each element. A hit fails the journey;
+with its page-check record and exits 1 on squashed, clipped or cut-off UI, naming each element. `--act <selector>` clicks a
+control and fails when the page does not change (a card moves, a reply saves, a toast shows): a button that is only there
+is not proof it works. A `look` block in `.done-done.yaml` (`tokens`, `max_control`) is the approved reference: look
+then fails on a control drawn as the browser's own or taller than `max_control`, and `--mock <file>` has the judge compare
+the page with its approved mock. A hit fails the journey;
 never wrap it in `|| true` or log the exit and go on. A claim that a phone UI works needs a 390 px capture of the real
 page and the page's scroll-container count as proof: a mock, a different width or a claim with no count is not proof. A journey in `.done-done.yaml` that calls it: