done-done-axi 0.6.11 → 0.6.12

package/README.md

@@ -233,7 +233,7 @@ Another fleet works the same way: add the include text to whatever your workers
 - [Worked example: a CLI project](docs/example-cli.md): set up, one journey, check and receipt on a command-line tool.
 - [Worked example: create and maintain a verify skill](docs/example-create-maintain.md): init writes the skill, a source change makes it drift, maintain fixes it, then a real browser journey is judged.
 - [Full reference](docs/reference.md): every command and option, the Checks block rules, each file check, and both config files.
-- [Config reference](docs/reference.md#config): optional global `judge.account_command` selects a pooled Claude account for judge and agent calls; an exported `CLAUDE_CONFIG_DIR` wins, and a failed pick stops the call.
+- [Config reference](docs/reference.md#config): optional global `judge.account_command` selects a pooled Claude account for judge and agent calls; an exported `CLAUDE_CONFIG_DIR` wins; optional `judge.fallback_route: answerer:pi` with `agent_config.pi.model: openai-codex/gpt-6.1-sol` uses Codex when Claude has no eligible account, sign-in or usage left.
 - [Report a problem or ask a question](https://github.com/umeranjum17/done-done-axi/issues)
 
 ## What's next

package/dist/agents.js

@@ -397,10 +397,10 @@ export function selectJudge(cfg, found) {
         : agent !== knownAgentOf(found.agent) ? 'agent' : found.model && model !== found.model ? 'model' : 'session-only';
     return { route, agent, model, independence, author: { agent: found.agent, model: found.model } };
 }
-// The judge that answers when the set route's call fails (FALLBACK_ROUTES), at that agent's own default model; none for a route with no fallback.
+// One configured second route, else the legacy MiniMax fallback; use its own model, never the primary's.
 export function selectFallback(cfg, found) {
-    const route = FALLBACK_ROUTES[cfg.judge.route];
-    return route ? selectJudge({ ...cfg, judge: { ...cfg.judge, route, model: '' } }, found) : undefined;
+    const route = cfg.judge.fallback_route || FALLBACK_ROUTES[cfg.judge.route];
+    return route && route !== cfg.judge.route ? selectJudge({ ...cfg, judge: { ...cfg.judge, route, model: '' } }, found) : undefined;
 }
 const DRAIN_MS = 500;
 const OUTPUT_CAP = 64 << 20;
@@ -510,13 +510,16 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
         child.stdin.end(input);
     });
 }
+// A valid picker refusal is availability, not a malformed account configuration.
+export class ClaudeUnavailable extends UsageError {
+}
 let accountPick;
 // One pick (including failure) per process, shared by readers, drives and the judge; never change the caller's env.
 export function claudeAccount(agent, command) {
     if (agent !== 'claude' || !command || process.env.CLAUDE_CONFIG_DIR !== undefined)
         return Promise.resolve(undefined);
     return accountPick ??= Promise.resolve().then(() => {
-        const fail = (why) => { throw new UsageError(`judge.account_command: ${why}`, 'Fix judge.account_command in the global config, or export CLAUDE_CONFIG_DIR for this call'); };
+        const fail = (why, unavailable = false) => { throw new (unavailable ? ClaudeUnavailable : UsageError)(`judge.account_command: ${why}`, 'Fix judge.account_command in the global config, or export CLAUDE_CONFIG_DIR for this call'); };
         const r = spawnSync(command, { shell: true, encoding: 'utf8', timeout: 30_000, maxBuffer: 64 * 1024 });
         if (r.error)
             fail(r.error.code ?? 'command could not start');
@@ -528,9 +531,9 @@ export function claudeAccount(agent, command) {
             fail(r.status === 0 ? 'invalid JSON' : `command exited ${r.status}: ${errorLine(r.stderr) || 'no pick returned'}`);
         }
         if (r.status !== 0)
-            fail(`command exited ${r.status}: ${typeof pick?.reason === 'string' ? errorLine(pick.reason) : errorLine(r.stderr) || 'no pick returned'}`);
+            fail(`command exited ${r.status}: ${typeof pick?.reason === 'string' ? errorLine(pick.reason) : errorLine(r.stderr) || 'no pick returned'}`, pick?.ok === false || pick === null);
         if (pick?.ok !== true)
-            fail(typeof pick?.reason === 'string' ? errorLine(pick.reason) : 'ok must be true');
+            fail(typeof pick?.reason === 'string' ? errorLine(pick.reason) : 'ok must be true', pick?.ok === false || pick === null);
         if (typeof pick.id !== 'string' || !/^[A-Za-z0-9_.-]{1,128}$/.test(pick.id))
             fail('invalid account id');
         const folder = pick.set?.CLAUDE_CONFIG_DIR;

package/dist/cli.js

@@ -47,6 +47,8 @@ const JOURNEYS_TEXT = `journeys (.done-done.yaml): the command runs with DONE_DO
   spends (journeys.<name>.spends): what a run spends, e.g. "one live generation"; verify parks the journey until the user approves that run (respond --action approve)
   timeout (journeys.<name>.timeout): how long a verify run may drive the journey, e.g. 90s or 30m (default 30m); past it the journey is killed and the run is inconclusive
   matrix (.done-done.yaml): with theme, width or form axes the journey runs once per required cell with DONE_DONE_THEME, DONE_DONE_WIDTH, DONE_DONE_FORM and DONE_DONE_CELL (the capture name suffix) set; name each capture with its suffix, so every cell is captured or skipped with a reason`;
+// A claim about how the product looks or what it outputs needs a comparison with the approved result.
+const DESIGN_CLAIM = /\b(design(ed|s)?|redesign(ed)?|mock(up)?s?|prototype|approved)\b/i;
 const CHECKS_TEXT = `Checks block (--from): the newest "## Checks" heading, then these four keys, each at the start of a line:
   outcome: <what a user can now do>
   repro: <command that failed before and passes now, or n/a; a fix PR needs one>
@@ -54,6 +56,8 @@ const CHECKS_TEXT = `Checks block (--from): the newest "## Checks" heading, then
   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
+  approved_requirements (.done-done.yaml): approved assets, color tokens and interactions as {kind: asset|color|interaction, name, capture, mock?}; skip one only with {kind, name, exclusion: <reason>}
+  (reference images under design/, mocks/, approved/ or prototype/ must be listed or excluded; a design claim with no approved reference or base_ref baseline fails as not compared to approved result)
   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).
@@ -113,7 +117,9 @@ const CONFIG_TEXT = `config: ~/.done-done/config.yaml (global; DONE_DONE_HOME mo
   agent (either file): claude, codex, opencode, pi, gemini or acp:<target>, set by the user (done-done init --agent); done-done never picks one.
   global only: agent_config.<agent>.{model,effort} (effort: minimal, low, medium, high, xhigh, max), agent_args_override.<agent>
   (extra flags), agent_path_override.<agent> (binary), acpx_path, agent_timeout (one agent call, default 30m; a streaming agent that prints nothing for 5m is stopped early),
-  judge.account_command (optional shell command printing a Claude account pick; exported CLAUDE_CONFIG_DIR wins; failure stops the call),
+  judge.account_command (optional Claude account pick; exported CLAUDE_CONFIG_DIR wins),
+  judge.fallback_route (optional second judge, same values as judge.route; Claude usage/rate/sign-in limits or an empty pool trigger it;
+  e.g. answerer:pi with agent_config.pi.model: openai-codex/gpt-6.1-sol; unset keeps Claude failures as errors; no fallback chains),
   evidence.local_root, judge.{route,model,floor} (the judge and shared confidence floor, set by the user with
   init --judge; never picked). done-done doctor shows where each agent setting came from.`;
 // One table drives `--help` and every `<command> --help`: each command's usage lines and the flags it takes.
@@ -909,6 +915,20 @@ async function runCheck(argv, run) {
         else if (`${live[0].media.w}x${live[0].media.h}` !== e.size)
             coverageFaults.push(`${label}: live capture is ${live[0].media.w}x${live[0].media.h}, not the approved size`);
     }
+    // Approved assets, color tokens and interactions: each needs its own live capture, or an explicit exclusion with a reason.
+    const requirements = cfg.approved_requirements.filter(r => r.capture).map(r => ({ r, live: captures.filter(c => screen(c) && basename(cite(c.name)) === r.capture) }));
+    for (const { r, live } of requirements)
+        if (live.length !== 1)
+            coverageFaults.push(`${r.kind} ${r.name}: ${live.length ? 'ambiguous live captures' : 'no live capture'} (${r.capture})`);
+    // Committed approved reference images (design/, mocks/ ...) that no manifest row or exclusion accounts for.
+    const accounted = new Set([...cfg.approved_design.map(e => e.mock), ...cfg.approved_requirements.flatMap(r => [r.mock, r.kind === 'reference' ? r.name : undefined])]);
+    const unlisted = claim ? git(repo, 'ls-files', '-z', '--', ':(icase)design*/**', ':(icase)mock*/**', ':(icase)approved*/**', ':(icase)prototype*/**').split('\0').filter(f => /\.(png|jpe?g)$/i.test(f) && !accounted.has(f)) : [];
+    if (unlisted.length)
+        coverageFaults.push(`approved reference material is not in the approved_design manifest: ${unlisted.join(', ')}; list each as an approved_design screen, an approved_requirements mock, or {kind: reference, name: <path>, exclusion: <reason>}`);
+    // A design or output claim must be compared to the approved result (a manifest mock, or the base_ref baseline), not only rendered.
+    const compared = approved.length > 0 || requirements.some(({ r }) => r.mock) || heads.some(([c]) => c.before);
+    if (claim && !compared && DESIGN_CLAIM.test(claim.outcome))
+        coverageFaults.push('not compared to approved result: the claim is about design or output but nothing is compared to an approved reference or a same-model baseline; add an approved_design manifest (or an approved_requirements row with a mock) or set base_ref, because render, fit and dark-mode checks alone do not prove it');
     for (const why of coverageFaults)
         findings.push({ level: 'fail', why: `approved design: ${why}` });
     // A head capture of a base_ref run with no base capture of its name is reported, then judged alone.
@@ -993,28 +1013,29 @@ 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 pairUp = (label, mockFile, live, size) => {
+        const path = resolve(repo, mockFile);
+        let committed;
+        try {
+            committed = execFileSync('git', ['show', `${values['trusted-ref'] ?? now.commit}:${relative(repo, path)}`], { cwd: repo, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch {
+            throw new UsageError(`approved design: ${label}: approved mock is not committed: ${mockFile}`);
+        }
+        if (under(repo, realpathSync(path)) === null)
+            throw new UsageError(`approved design: mock leaves the repo: ${mockFile}`);
+        const mock = loadScreen(path);
+        if (mock.sha256 !== sha256(committed))
+            throw new UsageError(`approved design: approved mock differs from the committed reference: ${mockFile}`);
+        if (size && `${mock.media.w}x${mock.media.h}` !== size)
+            throw new UsageError(`approved design: ${label}: mock has the wrong pixel size`);
+        return { ...live, mock };
+    };
+    const agentRecords = run ? join(run.dir, 'agents') : join(home(), 'agents');
     let matches = [];
     if (approved.length) {
-        const pairs = approved.map(({ entry, live }) => {
-            const path = resolve(repo, entry.mock);
-            let committed;
-            try {
-                committed = execFileSync('git', ['show', `${values['trusted-ref'] ?? now.commit}:${relative(repo, path)}`], { cwd: repo, stdio: ['ignore', 'pipe', 'pipe'] });
-            }
-            catch {
-                throw new UsageError(`approved design: ${entry.screen} / ${entry.size} / ${entry.theme}: approved mock is not committed: ${entry.mock}`);
-            }
-            if (under(repo, realpathSync(path)) === null)
-                throw new UsageError(`approved design: mock leaves the repo: ${entry.mock}`);
-            const mock = loadScreen(path);
-            if (mock.sha256 !== sha256(committed))
-                throw new UsageError(`approved design: approved mock differs from the committed reference: ${entry.mock}`);
-            return { ...live[0], mock };
-        });
-        for (const [i, p] of pairs.entries())
-            if (`${p.mock.media.w}x${p.mock.media.h}` !== approved[i].entry.size)
-                throw new UsageError(`approved design: ${approved[i].entry.screen} / ${approved[i].entry.size} / ${approved[i].entry.theme}: mock has the wrong pixel size`);
-        const verdicts = await design(cfg, choice, pairs, run ? join(run.dir, 'agents') : join(home(), 'agents'));
+        const pairs = approved.map(({ entry, live }) => pairUp(`${entry.screen} / ${entry.size} / ${entry.theme}`, entry.mock, live[0], entry.size));
+        const verdicts = await design(cfg, choice, pairs, agentRecords);
         matches = verdicts.map((v, i) => {
             const { screen, size, theme } = approved[i].entry;
             if (v.verdict !== 'pass')
@@ -1028,7 +1049,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'));
+    const withMock = requirements.filter(({ r }) => r.mock);
+    if (withMock.length) {
+        const pairs = withMock.map(({ r, live }) => pairUp(`${r.kind} ${r.name}`, r.mock, live[0]));
+        const verdicts = await design(cfg, choice, pairs, agentRecords);
+        for (const [i, v] of verdicts.entries()) {
+            const { r } = withMock[i];
+            if (v.verdict !== 'pass')
+                findings.push({ level: 'fail', why: `approved design: ${r.kind} ${r.name}: ${v.verdict === 'unsure' ? 'match not proven: ' + v.reason : v.defects.map(d => `${d.kind}: ${d.where}`).join('; ')}`, file: v.path });
+        }
+    }
+    const touches = await interactions(cfg, choice, captures, agentRecords);
     for (const r of touches) {
         r.captures = r.captures.map(c => ({ ...c, path: receiptPath(repo, cfg, cite(c.path)) }));
         if (r.status === 'flagged')
@@ -1041,6 +1072,9 @@ async function runCheck(argv, run) {
         rep.result.interaction_checklist = touches;
     if (matches.length)
         rep.result.design = matches;
+    const excluded = cfg.approved_requirements.filter(r => r.exclusion).map(({ kind, name, exclusion }) => ({ kind, name, exclusion }));
+    if (excluded.length)
+        rep.result.approved_exclusions = excluded;
     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(''));

package/dist/config.js

@@ -13,10 +13,11 @@ export class UsageError extends Error {
     }
 }
 export const INTERACTIONS = JSON.parse(readFileSync(new URL('../skills/done-done/interaction-checklist.json', import.meta.url), 'utf8'));
+export const REQUIREMENT_KINDS = ['asset', 'color', 'interaction', 'reference'];
 // 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;
-// claude judges through claude-code. An acp:<target> agent cannot be sent an image. Codex image judging is not implemented.
+// claude judges through claude-code. An acp:<target> agent cannot be sent an image. Native Codex image judging is not implemented; use answerer:pi with openai-codex/<model>.
 export const ANSWERER_JUDGES = ['opencode', 'pi', 'gemini'];
 // BYOKit key routes: a judge on the user's own API key, read from this environment variable, with no agent CLI.
 // openai:key needs judge.model; a route with a model here runs it when judge.model is empty (the free MiniMax route).
@@ -69,6 +70,7 @@ const KEYS = {
     dom: { scope: 'repo', type: 'dom' },
     look: { scope: 'repo', type: 'look' },
     approved_design: { scope: 'repo', type: 'approved_design' },
+    approved_requirements: { scope: 'repo', type: 'approved_requirements' },
     interaction_checklist: { scope: 'repo', type: 'interaction_checklist' },
     base_ref: { scope: 'repo', type: 'string' },
     'evidence.root': { scope: 'repo', type: 'string' },
@@ -87,6 +89,7 @@ const KEYS = {
     'judge.floor': { scope: 'global', type: 'number' },
     'judge.env_file': { scope: 'global', type: 'string' },
     'judge.account_command': { scope: 'global', type: 'string' },
+    'judge.fallback_route': { scope: 'global', type: 'route' },
 };
 const SECTIONS = new Set(['evidence', 'secrets', 'checks', 'judge', 'signoff']);
 const MAPS = new Set(['auto_fix', 'agent_config', 'agent_args_override', 'agent_path_override']);
@@ -235,6 +238,30 @@ function apply(target, text, file, scope) {
             target.from[key] = scope;
             continue;
         }
+        if (key === 'approved_requirements') {
+            const fail = () => { throw new UsageError(`${file}: approved_requirements must be a non-empty list of unique {kind: ${REQUIREMENT_KINDS.join('|')}, name, capture: <live PNG/JPEG filename>, mock?: <repo-relative PNG/JPEG>} or {kind, name, exclusion: <reason>}; a reference row names a committed approved image and takes only an exclusion`); };
+            const image = (p) => typeof p === 'string' && !isAbsolute(p) && !p.split(/[\\/]/).includes('..') && /\.(png|jpe?g)$/i.test(p);
+            if (!Array.isArray(value) || !value.length)
+                fail();
+            const rows = value;
+            const ids = new Set(), names = new Set();
+            for (const r of rows) {
+                if (!isMap(r) || !REQUIREMENT_KINDS.includes(r.kind) || typeof r.name !== 'string' || !r.name.trim())
+                    fail();
+                const keys = Object.keys(r).filter(k => k !== 'kind' && k !== 'name').sort().join();
+                if (typeof r.exclusion === 'string' ? !r.exclusion.trim() || keys !== 'exclusion' : r.kind === 'reference' || !['capture', 'capture,mock'].includes(keys) || !image(r.capture) || /[\\/]/.test(r.capture) || (r.mock !== undefined && !image(r.mock)))
+                    fail();
+                const id = JSON.stringify([r.kind, r.name]);
+                if (ids.has(id) || (r.capture && names.has(r.capture)))
+                    fail();
+                ids.add(id);
+                if (r.capture)
+                    names.add(r.capture);
+            }
+            target.approved_requirements = rows;
+            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);
@@ -334,6 +361,7 @@ function defaultConfig(repo) {
         matrix: null,
         dom: null,
         look: null,
+        approved_requirements: [],
         approved_design: [],
         interaction_checklist: null,
         base_ref: '',
@@ -341,7 +369,7 @@ function defaultConfig(repo) {
         secrets: { patterns: {}, allow: [] },
         checks: { fix_title: '^(fix|bugfix|hotfix)\\b', upstream_catch_up: false, moved_from: false, generated_paths: [] },
         signoff: { post: false, board: '' },
-        judge: { route: '', model: '', floor: 0.7, env_file: '', account_command: '' },
+        judge: { route: '', fallback_route: '', model: '', floor: 0.7, env_file: '', account_command: '' },
         trusted: false,
         from: {},
     };
@@ -421,6 +449,8 @@ evidence:
 judge:
   # Which agent judges: claude-code (claude) or answerer:opencode. Any agent and model you choose, the author's own too.
   # route: answerer:opencode
+  # Optional second judge when Claude has no eligible account, sign-in or usage left; its agent_config model is used.
+  # fallback_route: answerer:pi       # agent_config.pi.model: openai-codex/gpt-6.1-sol
   # The judge's model; empty means that agent's agent_config model, or Luna for pi.
   model: ""
   # Every judge's pick must reach this probability to count: below it the verdict is unsure (inconclusive), never a pass.

package/dist/judge.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { accessSync, constants, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, delimiter, isAbsolute, join } from 'node:path';
-import { agentRun, askAgent, claudeAccount, notStartable } from './agents.js';
+import { agentRun, askAgent, claudeAccount, ClaudeUnavailable, notStartable } from './agents.js';
 import { home, KEY_ROUTES, parseDuration, tilde, UsageError } from './config.js';
 import { downscaleToPng } from './media.js';
 const MAX_SIDE = 1280; // long edge sent to the model, in pixels
@@ -225,10 +225,11 @@ export async function askJudge(cfg, be, choice, state, questions, images, shared
     catch (e) {
         const why = be.lastError() || e.message;
         if (choice.route === 'claude-code' && /not logged in/i.test(why))
-            throw new UsageError(`judge: claude is not signed in (${why})`, 'sign in with: claude auth login, then re-run this command');
+            throw new ClaudeUnavailable(`judge: claude is not signed in (${why})`, 'sign in with: claude auth login, then re-run this command');
         const freeTier = choice.agent === 'opencode' && /free tier can only be used from within OpenCode/.test(why);
         const hint = choice.route === 'claude-code' ? ` (check judge.model ${choice.model} and your plan's usage limit)` : Object.hasOwn(KEY_ROUTES, choice.route) ? ` (check judge.model ${choice.model} and the key in ${KEY_ROUTES[choice.route]})` : freeTier ? ` (${choice.model} is on OpenCode's free tier, which only runs inside OpenCode, and the judge runs with every tool off: set judge.model in ~/.done-done/config.yaml to a model that is not on the free tier)` : '';
-        throw new UsageError(`judge: the judge did not answer: ${why}${hint}`, again);
+        const Failure = choice.route === 'claude-code' && /rate.?limit|usage.?limit|not signed in|(?:every|all|no eligible).*account.*(?:floor|limit|available)/i.test(why) ? ClaudeUnavailable : UsageError;
+        throw new Failure(`judge: the judge did not answer: ${why}${hint}`, again);
     }
     const bad = malformed(answers);
     if (bad.length)
@@ -274,11 +275,12 @@ export async function judge(cfg, choose, outcome, captures, records, fallback) {
         return await judgeOn(cfg, choose, outcome, captures, records);
     }
     catch (e) {
-        const next = e instanceof UsageError && fallback?.();
+        const next = e instanceof UsageError && (choose().route !== 'claude-code' || e instanceof ClaudeUnavailable) && fallback?.();
         if (!next)
             throw e;
         try {
-            return await judgeOn(cfg, () => next, outcome, captures, records);
+            const result = await judgeOn(cfg, () => next, outcome, captures, records);
+            return { ...result, detail: `${next.route} answered after ${choose().route} unavailable${result.detail ? `; ${result.detail}` : ''}` };
         }
         catch (again) {
             if (!(again instanceof UsageError))

package/docs/reference.md

@@ -98,7 +98,7 @@ done-done doctor --probe
 
 done-done starts the coding agent you choose, and never picks one. `agent:` names exactly one (`claude`, `codex`, `opencode`, `pi`, `gemini` or `acp:<target>`); there is no auto-detection and no fallback list, so an agent that is not installed or cannot start stops the command with the reason. While no agent is set, a command that starts it asks in a terminal (a numbered list of agents, then of models) and saves the answer to the global config; anywhere else (an agent calling done-done) it exits 2 with `no agent is set: ask the user which agent to use (claude, codex, opencode, pi, gemini, acp:<target>); never pick one for them` and the command that saves the answer: `done-done init --agent <agent> --model <model>`. `doctor` reports an unset agent as missing with that same fix. The model is `agent_config.<agent>.model` (global config only), else the agent's cheap default (`claude-haiku-5-5` for claude, `opencode-go/muse-spark-1.3-contributor` for opencode, `flash-lite` for gemini; claude and opencode also default to `effort: low`). That table is the only place done-done names a default model, and `init` writes it into the global config. `agent_config.<agent>.effort` (`minimal`, `low`, `medium`, `high`, `xhigh` or `max`, or `''` for the CLI's own) goes to the CLI's own flag as written: `--effort` (claude), `-c model_reasoning_effort="<level>"` (codex), `--variant` (opencode) and `--thinking` (pi); gemini and `acp:<target>` have none, so an effort for them is a config error. `agent_args_override.<agent>` adds extra CLI flags after done-done's own (do not repeat a flag done-done passes), `agent_path_override.<agent>` starts that binary instead of the one on PATH, `acpx_path` names the acpx bridge, and `agent_timeout` (default `30m`) bounds each agent call: a verify drive, a maintain reader, the judge and the doctor probe. A streaming agent (pi, opencode, codex, `acp:<target>`) that prints nothing, on stdout or stderr, for 5 minutes is stopped early (30 seconds for the doctor probe); the no-answer reason then quotes its stderr and the call record path, so a hung agent costs minutes, not the whole timeout. A rate limit the CLI prints (HTTP 429, a usage limit) ends any agent call at that line, with the limit and its reset time as the reason (for pi's JSON events, the provider's own message, not the event); the one exception is a claude judge call with images, which stops only at claude's own rejected rate-limit event, so its retries run. claude and gemini print one answer at the end, so only `agent_timeout` bounds them. These defaults are the cost guard for those agents: done-done never defaults to a flagship model for them. codex, pi and `acp:<target>` have no public cheap alias, so with no `agent_config.<agent>.model` (for `acp:<target>`, `agent_config.acp:<target>.model`) they run their own configured model, which can be a flagship; that setting caps their cost. `agent: acp:<target>` (for example `acp:gemini`) starts any Agent Client Protocol agent through [acpx](https://github.com/openclaw/acpx), which you install yourself (`npm install -g acpx`). doctor reports an `acp:` agent missing, with that install step, when acpx is not on PATH or does not start.
 
-Each call is a fresh, single-shot session that must answer one JSON object matching a schema. The prompt goes on stdin (claude, codex, pi, gemini, acp) or into a 0600 prompt file (opencode), never in argv. done-done can start claude (`claude -p --output-format json --json-schema <schema> --model <model> --no-session-persistence`, all tools off with `--tools ''`; tool-less calls also pass `--setting-sources ''` and run from a scratch folder, so no project settings or hooks load; read-only calls allow only `--tools Read,Grep,Glob` and pass `--setting-sources ''` and `--strict-mcp-config`, so no user settings or MCP servers load), opencode (`opencode run "Follow the attached instructions." --format json -m <provider/model> -f <prompt file>`, with the schema in the 0600 prompt file and every tool denied through `OPENCODE_PERMISSION` except on an edit step ([Drive by agent](#drive-by-agent), Scope)), pi (`pi -p --mode json --no-session --no-tools`, tools off for every read or probe call, since pi has no read-only mode that refuses outside reads, and `--model <model>` only when one is set) and gemini (`gemini -p "Follow the instructions on stdin." -o json -m <model> --approval-mode plan|auto_edit`, where `plan` is read-only for the probe and read steps and `auto_edit` is used for edit steps; `--skip-trust` is added only to the tool-less probe in its scratch folder, so repo calls keep Gemini's workspace trust gate) and codex (`codex exec --json --ephemeral [-m <model>]`, the answer being the last agent message of its JSONL events; an edit step runs in codex's `--sandbox workspace-write` with the run's evidence and scratch folders added by `--add-dir` and network on, so the drive can launch the app and talk to it, while it keeps your own codex config). Codex readers and probes run a separate `--no-daemon exec --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox read-only` call, with project instructions disabled and your normal authentication untouched. Feature flags alone do not remove all tools: model metadata can force code-mode, collaboration and patch tools back on. done-done reads the CLI's public bundled catalog (`codex debug models --bundled`), writes a scratch-only copy with those capabilities removed, disables the remaining tool features and web search, and supplies it through `model_catalog_json`. A missing catalog, unsupported CLI or model not in that catalog fails with its cause; no unsafe fallback or copied login is used. `doctor --probe` now requires a real Codex answer, and `init` and maintain use the same clean reader. Codex image judging is not implemented, so it remains unavailable as a judge route. `acp:<target>` runs `acpx --cwd <dir> --format json --json-strict --deny-all --non-interactive-permissions deny [--model <model>] <target> exec --file -`, with the prompt and schema on stdin; every tool is denied. pi has no permission gate for edit steps, so doctor adds a `tool_gate` warning row whenever pi is the agent: every pi tool runs without approval. codex's sandbox covers its shell too, so doctor adds a `tool_gate` warning row whenever codex is the agent: a drive's recipe tool can write only where the drive may (see [Drive by agent](#drive-by-agent), Scope).
+Each call is a fresh, single-shot session that must answer one JSON object matching a schema. The prompt goes on stdin (claude, codex, pi, gemini, acp) or into a 0600 prompt file (opencode), never in argv. done-done can start claude (`claude -p --output-format json --json-schema <schema> --model <model> --no-session-persistence`, all tools off with `--tools ''`; tool-less calls also pass `--setting-sources ''` and run from a scratch folder, so no project settings or hooks load; read-only calls allow only `--tools Read,Grep,Glob` and pass `--setting-sources ''` and `--strict-mcp-config`, so no user settings or MCP servers load), opencode (`opencode run "Follow the attached instructions." --format json -m <provider/model> -f <prompt file>`, with the schema in the 0600 prompt file and every tool denied through `OPENCODE_PERMISSION` except on an edit step ([Drive by agent](#drive-by-agent), Scope)), pi (`pi -p --mode json --no-session --no-tools`, tools off for every read or probe call, since pi has no read-only mode that refuses outside reads, and `--model <model>` only when one is set) and gemini (`gemini -p "Follow the instructions on stdin." -o json -m <model> --approval-mode plan|auto_edit`, where `plan` is read-only for the probe and read steps and `auto_edit` is used for edit steps; `--skip-trust` is added only to the tool-less probe in its scratch folder, so repo calls keep Gemini's workspace trust gate) and codex (`codex exec --json --ephemeral [-m <model>]`, the answer being the last agent message of its JSONL events; an edit step runs in codex's `--sandbox workspace-write` with the run's evidence and scratch folders added by `--add-dir` and network on, so the drive can launch the app and talk to it, while it keeps your own codex config). Codex readers and probes run a separate `--no-daemon exec --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox read-only` call, with project instructions disabled and your normal authentication untouched. Feature flags alone do not remove all tools: model metadata can force code-mode, collaboration and patch tools back on. done-done reads the CLI's public bundled catalog (`codex debug models --bundled`), writes a scratch-only copy with those capabilities removed, disables the remaining tool features and web search, and supplies it through `model_catalog_json`. A missing catalog, unsupported CLI or model not in that catalog fails with its cause; no unsafe fallback or copied login is used. `doctor --probe` now requires a real Codex answer, and `init` and maintain use the same clean reader. Native Codex image judging is not implemented; Codex image judging is available through `answerer:pi` with `openai-codex/gpt-6.1-sol` on your existing Codex login. `acp:<target>` runs `acpx --cwd <dir> --format json --json-strict --deny-all --non-interactive-permissions deny [--model <model>] <target> exec --file -`, with the prompt and schema on stdin; every tool is denied. pi has no permission gate for edit steps, so doctor adds a `tool_gate` warning row whenever pi is the agent: every pi tool runs without approval. codex's sandbox covers its shell too, so doctor adds a `tool_gate` warning row whenever codex is the agent: a drive's recipe tool can write only where the drive may (see [Drive by agent](#drive-by-agent), Scope).
 
 ### Add a journey from a description
 
@@ -463,7 +463,20 @@ done-done check --from pr-body.md                               # always judged
     - `gemini`: plan mode plus a deny-all `--policy` file, which replaces your own policy folder and removes every tool, MCP ones too; the capture is an `@<file>` in the prompt, which Gemini CLI's own `@`-command code reads (outside the tool policy, per its source; not yet proven live, since Gemini CLI was not signed in on the test machine), only inside the scratch folder.
     - An `acp:<target>` agent cannot judge, since done-done cannot send it an image; doctor's `config` row says so when `judge.route` names one.
   - `openai:key`: a key-only route with no agent CLI. BYOKit's OpenAI backend sends the capture to the OpenAI Responses API on your own API key, which done-done reads from `OPENAI_API_KEY` and hands only to the kit (never printed or stored). Set `judge.model` to a model your key can use that reads images; there is no default. API billing applies.
-  - `minimax:key`: a key-only route on your MiniMax key, with no agent CLI. done-done reads `MINIMAX_API_KEY` and hands it only to the kit's Anthropic backend, which done-done points at MiniMax's Anthropic-compatible endpoint (`https://api.minimax.io/anthropic/v1`, the only address it will send the key to). `judge.model` is optional: empty runs `MiniMax-M3.1-Flash-Preview`, which reads images. This route is the only one with a fallback: when its call fails (a refused or missing key, a rate limit, no answer), `check`, `receipt` and `verify` judge the whole check again on `claude-code` at claude's cheap model (`agent_config.claude.model`, else the default), and the result's `judge` block names the route that answered. When the fallback fails too, the error carries both causes. Setting `judge.route: minimax:key` is your choice, like any route; `check --judge minimax:key` tries it for one call.
+  - `minimax:key`: a key-only route on your MiniMax key, with no agent CLI. done-done reads `MINIMAX_API_KEY` and hands it only to the kit's Anthropic backend, which done-done points at MiniMax's Anthropic-compatible endpoint (`https://api.minimax.io/anthropic/v1`, the only address it will send the key to). `judge.model` is optional: empty runs `MiniMax-M3.1-Flash-Preview`, which reads images. With no explicit `judge.fallback_route`, this route retains its built-in fallback: when its call fails (a refused or missing key, a rate limit, no answer), `check`, `receipt` and `verify` judge the whole check again on `claude-code` at claude's cheap model (`agent_config.claude.model`, else the default), and the result's `judge` block names the route that answered. When the fallback fails too, the error carries both causes. Setting `judge.route: minimax:key` is your choice, like any route; `check --judge minimax:key` tries it for one call.
+
+  **Optional second route.** Global `judge.fallback_route` accepts the same routes as `judge.route` and is unset by default. For `claude-code`, a rate/usage limit, missing sign-in, or an account picker returning no eligible account triggers one retry of the **whole check** on that route. Invalid picker JSON/configuration, malformed model answers and other Claude errors still stop the call. With no fallback configured, Claude failures keep their existing error and no verdict. Other routes retry on their existing judge errors; an explicit fallback replaces MiniMax's built-in fallback. There is only one hop (no chains, and the same route is not retried). The result's `judge.route`, `model` and fallback `detail` name the judge that answered; if both fail, both causes are reported. The fallback uses its own `agent_config.<agent>.model` or default, **not** the primary's `judge.model`. Key routes therefore need their own default model to work as a fallback (`minimax:key` has one; `openai:key` does not).
+
+  For Codex/Sol on the already signed-in Pi CLI (no API key, paid-key route or new login):
+
+  ```yaml
+  agent_config:
+    pi:
+      model: openai-codex/gpt-6.1-sol
+  judge:
+    route: claude-code
+    fallback_route: answerer:pi
+  ```
 
   A provider key for an `answerer:<agent>` judge, or `OPENAI_API_KEY` / `MINIMAX_API_KEY` for `openai:key` / `minimax:key`, is read from the environment of whoever runs done-done. To work in every shell, point `judge.env_file` (global config) at a file of `KEY=value` lines (`export` and quotes allowed); its names that the shell has not exported go to the judge's call only. done-done never writes a key into a config file and never prints one; `init --judge` on its own changes only the global config, in any directory.
 
@@ -544,6 +557,22 @@ 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.
 
+#### Assets, colors, interactions and unlisted references
+
+Screens are not the whole approval. Name every other approved item in `approved_requirements`, each with the live evidence it needs, or skip it with an explicit exclusion:
+
+```yaml
+approved_requirements:
+  - { kind: asset, name: logo, capture: logo.png, mock: design/logo.png }   # judged beside its approved image
+  - { kind: color, name: brand-accent, capture: accent.png }                # must be cited live evidence
+  - { kind: interaction, name: swipe-to-delete, capture: swipe.png }
+  - { kind: reference, name: design/spare.png, exclusion: owner dropped the spare illustration }
+```
+
+`kind` is `asset`, `color`, `interaction` or `reference`. A row needs a unique `capture` filename (one cited, run-bound PNG/JPEG; optional `mock` sends it through the design judge) **or** `exclusion: <reason>`, the only way to skip it. An uncovered row fails the claim before any judge call, naming the item. Exclusions are reported under `approved_exclusions`. Receipts do not yet bind requirement captures; they are enforced by `check`, `receipt` and `verify` at run time.
+
+**Behavior that tightens.** (1) Committed PNG/JPEG files under a top-level `design*/`, `mock*/`, `approved*/` or `prototype*/` folder that no `approved_design` `mock`, requirement `mock` or `kind: reference` row names fail every claim as "approved reference material is not in the approved_design manifest". (2) A claim whose outcome mentions design, mock, prototype or approved, with no `approved_design` manifest, no requirement `mock` and no `base_ref` baseline capture, fails with `not compared to approved result`; render, fit and dark-mode checks alone do not prove it. Manifests that list every reference and compare against it keep working unchanged.
+
 #### 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).
@@ -751,13 +780,14 @@ evidence:
   local_root: ~/.done-done/evidence   # evidence root for repos that set none (<local_root>/<app>)
 judge:                                # done-done's own judge; check, receipt, verify and design always start it
   # route: claude-code                # claude-code, answerer:<agent> (opencode, pi, gemini) openai:key (reads OPENAI_API_KEY) or minimax:key (reads MINIMAX_API_KEY, claude-code fallback), set by you (`init --judge` saves the first three; a key route is set by hand) and unset until then
+  # fallback_route: answerer:pi       # optional; its agent_config.pi.model can be openai-codex/gpt-6.1-sol
   model: ''                           # default: that agent's agent_config model, or openai-codex/gpt-6-luna for pi
   floor: 0.7                          # every judge's pick must reach this probability to count; below it the verdict is unsure (inconclusive), never a pass
   # env_file: ~/.config/done-done/judge.env  # KEY=value lines (a provider API key) handed to the judge for names your shell has not exported; the key stays in that file
   # account_command: account-picker pick claude --json  # optional shell command for Claude judge and agent calls (verify/maintain too), once per process; exported CLAUDE_CONFIG_DIR wins
 ```
 
-`judge.account_command` must print one JSON object: `{"ok":true,"id":"pool-1","set":{"CLAUDE_CONFIG_DIR":"/absolute/existing/folder"},"unset":["ANTHROPIC_API_KEY"]}`. Only the selected folder is set, and each `unset` name is deleted from the spawned environment; it cannot unset `CLAUDE_CONFIG_DIR`. The detail names only the account id. A failed or invalid pick stops the call with its cause and no verdict, never falling back to the default login. Unset, it preserves normal Claude sign-in behavior; other agents and API-key routes do not run it.
+`judge.account_command` must print one JSON object: `{"ok":true,"id":"pool-1","set":{"CLAUDE_CONFIG_DIR":"/absolute/existing/folder"},"unset":["ANTHROPIC_API_KEY"]}`. Only the selected folder is set, and each `unset` name is deleted from the spawned environment; it cannot unset `CLAUDE_CONFIG_DIR`. The detail names only the account id. A pick returning `ok: false` (or JSON `null`) is an unavailable Claude route and uses `judge.fallback_route` when configured; otherwise it stops with the same cause and no verdict. An invalid pick still stops the call. Neither case falls back to the default Claude login. Unset, it preserves normal Claude sign-in behavior; other agents and API-key routes do not run it.
 
 An `agent_config` entry merges with the defaults field by field, so `claude: { model: claude-sonnet-5-5 }` keeps `effort: low`; the other maps merge entry by entry. `done-done doctor` shows which file set each agent setting.
 
@@ -778,6 +808,7 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 | `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_requirements` | none; approved assets, colors and interactions with the live capture each needs, or an explicit `exclusion`, see [Assets, colors, interactions](#assets-colors-interactions-and-unlisted-references) |
 | `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.11 patch release
+# 0.6.12 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.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.
+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.12 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.11",
+  "version": "0.6.12",
   "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

@@ -98,6 +98,9 @@ fresh session of its own, looks at each capture. `check` and `receipt` start the
 and nothing turns it off: there is no result without it. When it says no judge is set, ask the user which
 judge (and model) to use and save their answer with the command it prints; never choose one for them. When
 the judge fails, report its error to the user; never call the work proven without a judge pass.
+An explicitly configured `judge.fallback_route` can judge when Claude has no eligible account, sign-in or usage left;
+`answerer:pi` with `agent_config.pi.model: openai-codex/gpt-6.1-sol` uses the existing Codex login.
+Read `done-done --help` for fallback configuration; results name the route that actually answered.
 
 ## Request