done-done-axi 0.6.2 → 0.6.3

package/README.md

@@ -155,6 +155,7 @@ Another fleet works the same way: add the include text to whatever your workers
 
 - [Vision](VISION.md): the three-tool family, the rules they share, and where done-done goes next.
 - [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.
 - [Report a problem or ask a question](https://github.com/umeranjum17/done-done-axi/issues)
 

package/dist/agents.js

@@ -22,6 +22,32 @@ function errorLine(text) {
 }
 // A provider's rate limit (HTTP 429, a usage limit with its reset time). The CLI may retry it for many minutes, so the call stops at the first line that says so.
 const RATE_LIMIT = /\b429\b|rate[ -]?limit|usage limit|too many requests/i;
+// A JSON event line (pi --mode json) that mentions a limit: the readable text inside it, not the event. The first string
+// that says so, and the provider's own message when that string is `429: {"message":"..."}`; any other line as it is.
+const limitText = (line) => {
+    const found = (v) => {
+        if (typeof v === 'string')
+            return RATE_LIMIT.test(v) ? v : undefined;
+        if (v && typeof v === 'object')
+            for (const x of Object.values(v)) {
+                const f = found(x);
+                if (f)
+                    return f;
+            }
+    };
+    let text;
+    try {
+        text = found(JSON.parse(line));
+    }
+    catch { }
+    const body = text?.match(/^\d+: (\{.*\})$/s)?.[1];
+    try {
+        return (body && JSON.parse(body).message) || text || line;
+    }
+    catch {
+        return text ?? line;
+    }
+};
 const isRejectedRateLimit = (l) => {
     try {
         const e = JSON.parse(l);
@@ -388,6 +414,8 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
             }
             else {
                 line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l)));
+                if (line)
+                    line = limitText(line);
             }
             if (!line || error)
                 return;

package/dist/maintain.js

@@ -76,6 +76,9 @@ const localTarget = (t) => (/^[a-z][\w+.-]*:/i.test(t) ? '' : t.split('#')[0]);
 // of the tracked files', so host:port text is never read as a citation.
 // ponytail: a file name after a / may open with one bracket or paren group (pages/[id].tsx); [[...rest]].tsx is not a citation, add when a repo cites one.
 const CITE = /(?<![\w/.-])((?:(?:[\w.-]+|\([\w.-]+\)|\[[\w.-]+\])\/)*(?:[\w-][\w.-]*|(?<=\/)(?:\[[\w.-]+\]|\([\w.-]+\))[\w.-]*)\.[A-Za-z]\w*):(\d+)(?:-(\d+))?\b/g;
+// A file name in running text, with or without a line: a repo path or a bare name with an extension. Only the names that
+// citedFiles finds among the tracked files count, so ordinary words and URLs are ignored.
+const NAMED = /(?<![\w/.:-])(?:[\w.-]+\/)*[\w-][\w.-]*\.[A-Za-z]\w*(?![\w/-])/g;
 // Whether the file at `p` really lies under the repo: a symlinked folder on the way to it is followed, so it counts by where it points.
 const realInside = (repo, p) => realpathSync(p).startsWith(`${realpathSync(repo)}${sep}`);
 // Why repo-relative `file` has no line `line` (through `end`), or '' when it has.
@@ -265,8 +268,11 @@ async function pass(run, dir, cfg, h, prefix = '') {
         const left = new Set();
         let total = 0;
         let capped = false;
-        for (const m of cites(text)) {
-            for (const p of citedFiles(repo, tracked, m[1])) {
+        // Files the feature file cites with a line, then files it only names (`public/index.html`, init writes no line numbers).
+        // The skill's own files are never source.
+        const names = [...cites(text).map((m) => m[1]), ...(text.match(NAMED) ?? [])];
+        for (const name of names) {
+            for (const p of citedFiles(repo, tracked, name).filter((p) => !p.startsWith(`${rel(skill)}/`))) {
                 if (seen.has(p) || left.has(p))
                     continue;
                 if (capped) {
@@ -322,21 +328,32 @@ async function pass(run, dir, cfg, h, prefix = '') {
                 add({ kind: 'coverage', file: rel(file), what: 'the feature entry is not a readable file, so no reader covers it' });
             return undefined;
         });
-        return text === undefined ? [] : [{ name, text }];
+        return text === undefined ? [] : [{ name, text, file }];
     });
+    // SKILL.md states the launch and readiness check, which drift like a feature does (a renamed health route): it is read too,
+    // but only when it names tracked source (a skill that names none has nothing to compare), and after the features.
+    const main = join(skill, 'SKILL.md');
+    const mainText = agentBlock || regular.length >= MAX_CALLS - 1 ? undefined : tryRead(main, undefined, () => (lstatSync(main).isFile() ? readFileSync(main, 'utf8') : undefined));
+    const skillRel = `${rel(skill)}/`;
+    if (mainText && [...cites(mainText).map((m) => m[1]), ...(mainText.match(NAMED) ?? [])].some((n) => citedFiles(repo, tracked, n).some((p) => !p.startsWith(skillRel))))
+        regular.push({ name: 'SKILL.md', text: mainText, file: main });
     const readers = [];
-    for (const { name, text } of regular) {
-        const file = join(featDir, name);
+    for (const { name, text, file } of regular) {
         if (text.length > FEATURE_CHARS)
             add({ kind: 'truncated', file: rel(file), what: `the reader saw only the first ${FEATURE_CHARS} characters of this feature file` });
+        const source = toolless ? citedSource(rel(file), text.slice(0, FEATURE_CHARS)) : '';
+        // A reader with no tools and no source can only call the feature right: that is not a clean pass.
+        if (toolless && !source)
+            add({ kind: 'coverage', file: rel(file), what: 'names no tracked source file, so the reader had no source to compare it with; name the files it comes from (path or path:line)' });
         const prompt = `You are a read-only source reader for done-done maintain. Do not edit, create or delete any file, and do not run the app or any command.
 ${toolless ? 'You have no tools: the source that the feature file cites is below, each line after its line number, and it is all you can read.' : 'The repository is your working directory.'} Below is one feature file from the verification skill at ${cfg.skill} (app ${cfg.app}).
 ${toolless ? 'Use the cited source, not the skill, and explain' : "Read the product's source code, not the skill, and explain"} how this user-facing feature works today.
 - drift: each statement in the feature file that the source contradicts or no longer supports, each {claim: the feature file's words, why: what the source does instead, file, line: the source location that shows it}. Empty when the file is right.
+Statements about done-done itself (its instance block, DONE_DONE_* variables, the evidence folder, maintain) are not the product's behavior: never report them as drift.
 - recipe: one short recipe to verify the feature live, the way a user reaches it.
 
 Feature file ${rel(file)}:
-${text.slice(0, FEATURE_CHARS)}${toolless ? citedSource(rel(file), text.slice(0, FEATURE_CHARS)) : ''}`;
+${text.slice(0, FEATURE_CHARS)}${source}`;
         const a = await askAgent({ ...agent, prompt, schema: READER_SCHEMA, cwd: repo, tools: toolless ? 'none' : 'read', record: record(`reader-${name.replace(/\.md$/, '')}`) });
         if (!a.ok)
             add({ kind: 'coverage', file: rel(file), what: `the reader did not answer: ${a.error}` });

package/docs/example-create-maintain.md

@@ -0,0 +1,77 @@
+# Worked example: create and maintain a verify skill
+
+done-done on a tiny public sample, **Pocket Notes**: a zero-dependency Node web app where you type a note, press a button and see it in a list. It walks the whole loop with a real coding agent and a real judge: `init` writes a verify skill, a source change makes the skill drift, `maintain` finds and fixes it, a real browser journey captures the screen, and the judge passes it. Nothing is stubbed and no image is copied in.
+
+You need Node 22.18+, git, Chrome or Chromium, and a coding agent and judge you are signed in to (any pair `done-done init --help` lists). Replace the `--agent`/`--model` and `--judge`/`--judge-model` values with yours; a free or cheap model is fine. A throwaway `DONE_DONE_HOME` keeps this off your own config and evidence.
+
+**1. Install the built package and make the sample.**
+
+```sh
+d=$(mktemp -d) && cd "$d"
+npm pack done-done-axi && npm install -g --prefix "$d/prefix" ./done-done-axi-*.tgz   # or: npm install -g done-done-axi
+export PATH="$d/prefix/bin:$PATH" DONE_DONE_HOME="$d/home"
+cp -r "$d/prefix/lib/node_modules/done-done-axi/docs/examples/pocket-notes" . && cd pocket-notes
+git init -q -b main && npm install && git add -A && git commit -qm "Pocket Notes"
+```
+
+The sample is in the package under `docs/examples/pocket-notes/` (also in this repo): `server.mjs` (an HTTP server: `GET`/`POST /api/notes`, `GET /health`, the page at `/`, port from `PORT`, data folder from `NOTES_DATA`), `public/index.html` (a heading, a `Write a note` field, an `Add note` button and the list) and the journey script of step 5. Any small web app works the same way. Add a `.gitignore` with `node_modules` and `notes.json` before the commit.
+
+**2. `init` has your agent write the skill.**
+
+```sh
+done-done init --agent <agent> --model <model> --judge <judge> --judge-model <model>
+```
+
+It writes `.done-done.yaml` and `.agents/skills/done-done-verify-pocket-notes/` (`SKILL.md` plus one file per feature, one marked the core journey). Read it: the launch should use a temp `NOTES_DATA` and its own port, and each feature should name its source (`public/index.html`). Commit it. `done-done doctor` should pass.
+
+**3. Change the source; the skill is now stale.** Rename the button to `Save note`, the placeholder to `Type a note` and the health route to `/healthz`, and commit:
+
+```sh
+sed -i 's#/health#/healthz#' server.mjs
+sed -i 's#Write a note#Type a note#; s#>Add note<#>Save note<#' public/index.html
+git commit -qam "Rename Add to Save, health to /healthz"
+```
+
+**4. `maintain` finds the drift, then fixes the skill.**
+
+```sh
+done-done maintain --foreground          # result: drift, with each finding
+printf 'auto_fix:\n  maintain: 2\n' >> .done-done.yaml && git commit -qam "Allow maintain fixes"
+done-done maintain --foreground          # result: changed, a commit on done-done/maintain-<run-id>
+git merge --ff-only done-done/maintain-<run-id>
+done-done maintain --foreground          # result: clean
+```
+
+The first run reports that the feature file says `Write a note` and `Add note` and `SKILL.md` says `/health`, each with the source line. The fix commit touches only the skill folder; your branch is untouched until you merge it. (Before 0.6.3 a tool-less reader was given no source when a feature file named it without a line number, so this step ended `clean` without reading anything.)
+
+**5. A real journey.** `init --journey` records it (the command drives the product; a test run would be refused):
+
+```yaml
+instance:
+  command: PORT=$DONE_DONE_PORT NOTES_DATA=$TMPDIR node server.mjs
+  ready: { url: http://127.0.0.1:$DONE_DONE_PORT/healthz }
+journeys:
+  add-note:
+    command: node scripts/prove-core.mjs
+    core: true
+```
+
+`scripts/prove-core.mjs` (already in the sample; `npm install` fetched `playwright-core`) opens `$DONE_DONE_BASE_URL` in headless Chrome at 390x844 with `playwright-core` (`executablePath` from `DONE_DONE_CHROME`, else `/usr/bin/chromium`), fills `Type a note` with `milk`, clicks `Save note`, waits for `milk` in the list and saves `$DONE_DONE_EVIDENCE_ROOT/note-listed.png`. It also writes `steps.json` beside it (target version, start state, the user's steps, the end result): `check` refuses a capture whose run has no step record that covers the claim ([Step record](reference.md#step-record)).
+
+The repo's own `journeys/create-maintain.mjs` runs this whole walkthrough unattended (`done-done run create-maintain`).
+
+**6. Run, check, receipt.** Commit first, then:
+
+```sh
+done-done run add-note
+done-done check --outcome "a user can type a note, press Save note, and see it in the list" <the png the run printed>
+done-done receipt --outcome "<same claim>" <same png>
+```
+
+The judge looks at the screenshot (`result: pass`, exit 0). Open the picture yourself too.
+
+What it shows:
+
+- Keep each outcome to what one capture shows; a claim with several parts comes back `inconclusive`.
+- The agent's skill is a draft: read it, and let `maintain` keep it true as the source moves.
+- A model free-tier or weekly limit ends a call with the provider's own message and reset time (exit 2), never a result.

package/docs/examples/pocket-notes/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pocket-notes",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A tiny notes web app: add a note and see it in the list.",
+  "scripts": {
+    "start": "node server.mjs",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "playwright-core": "^1.64.1"
+  }
+}

package/docs/examples/pocket-notes/public/index.html

@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Pocket Notes</title>
+<style>
+  body { font: 16px system-ui, sans-serif; margin: 0; background: #f6f5f1; color: #222; }
+  main { max-width: 420px; margin: 0 auto; padding: 24px 16px; }
+  h1 { font-size: 22px; margin: 0 0 16px; }
+  form { display: flex; gap: 8px; }
+  input { flex: 1; padding: 10px; font: inherit; border: 1px solid #bbb; border-radius: 6px; }
+  button { padding: 10px 14px; font: inherit; border: 0; border-radius: 6px; background: #1d6b4f; color: #fff; }
+  ul { list-style: none; padding: 0; margin: 16px 0 0; }
+  li { background: #fff; border-radius: 6px; padding: 10px 12px; margin-bottom: 8px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Pocket Notes</h1>
+  <form id="add"><input id="text" placeholder="Write a note" autocomplete="off"><button type="submit">Add note</button></form>
+  <ul id="notes"></ul>
+</main>
+<script>
+  const list = document.getElementById('notes');
+  async function refresh() {
+    const notes = await (await fetch('/api/notes')).json();
+    list.innerHTML = '';
+    for (const n of notes) {
+      const li = document.createElement('li');
+      li.textContent = n.text;
+      list.append(li);
+    }
+  }
+  document.getElementById('add').addEventListener('submit', async (e) => {
+    e.preventDefault();
+    const input = document.getElementById('text');
+    await fetch('/api/notes', { method: 'POST', body: JSON.stringify({ text: input.value }) });
+    input.value = '';
+    refresh();
+  });
+  refresh();
+</script>
+</body>
+</html>

package/docs/examples/pocket-notes/scripts/prove-core.mjs

@@ -0,0 +1,21 @@
+// Drives the real Pocket Notes page the way a user does and saves what it sees under $DONE_DONE_EVIDENCE_ROOT.
+import { writeFileSync } from 'node:fs';
+import { chromium } from 'playwright-core';
+
+const base = process.env.DONE_DONE_BASE_URL;
+const out = process.env.DONE_DONE_EVIDENCE_ROOT;
+const browser = await chromium.launch({ executablePath: process.env.DONE_DONE_CHROME || '/usr/bin/chromium', args: ['--no-sandbox'] });
+const page = await browser.newPage({ viewport: { width: 390, height: 844 } });
+await page.goto(base);
+await page.getByPlaceholder('Type a note').fill('milk');
+await page.getByRole('button', { name: 'Save note' }).click();
+await page.getByText('milk', { exact: true }).waitFor();
+await page.screenshot({ path: `${out}/note-listed.png` });
+await browser.close();
+// The step record done-done reads beside the capture: what a user did and what they see at the end.
+writeFileSync(`${out}/steps.json`, JSON.stringify({
+  target: { version: '1.0.0' },
+  start: 'the Pocket Notes page with an empty list',
+  steps: ['type milk in the Type a note field', 'press Save note'],
+  result: 'the note milk is listed below the form',
+}));

package/docs/examples/pocket-notes/server.mjs

@@ -0,0 +1,30 @@
+import { createServer } from 'node:http';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const port = Number(process.env.PORT || 4100);
+const dataFile = join(process.env.NOTES_DATA || '.', 'notes.json');
+const page = readFileSync(new URL('./public/index.html', import.meta.url));
+
+const load = () => (existsSync(dataFile) ? JSON.parse(readFileSync(dataFile, 'utf8')) : []);
+const save = (notes) => writeFileSync(dataFile, JSON.stringify(notes));
+
+createServer((req, res) => {
+  if (req.url === '/health') return res.end('ok');
+  if (req.url === '/api/notes' && req.method === 'GET') return res.setHeader('content-type', 'application/json'), res.end(JSON.stringify(load()));
+  if (req.url === '/api/notes' && req.method === 'POST') {
+    let body = '';
+    req.on('data', (c) => (body += c));
+    req.on('end', () => {
+      const { text } = JSON.parse(body || '{}');
+      if (!text || !text.trim()) return res.writeHead(400).end('text is required');
+      const notes = load();
+      notes.push({ id: notes.length + 1, text: text.trim() });
+      save(notes);
+      res.writeHead(201).end(JSON.stringify(notes.at(-1)));
+    });
+    return;
+  }
+  res.setHeader('content-type', 'text/html');
+  res.end(page);
+}).listen(port, () => console.log(`pocket-notes on http://127.0.0.1:${port}`));

package/docs/manual-cli.md

@@ -47,7 +47,7 @@ A `run -- <command>` whose command matches no recorded journey still runs, but i
 
 At any point, `done-done doctor` checks the setup and changes nothing except the `--probe` call record. Each item reports `ok`, `warning` or `missing` with the exact fix command; an agent you have not set yet is `missing`, with the command that saves your choice, and so is a config whose journeys only run code checks, one that names no core journey, or an app that ships an installable artifact with no upgrade journey. `done-done doctor --probe` also asks the agent one question to prove it answers; on a new machine that probe fails until the agent is signed in (for pi, run `pi` and then `/login`). The quick start above never calls the coding agent, so `run` and `check` work before it is signed in; `check` does call the judge, so set one first. The items are listed in the [reference](reference.md#check-the-setup).
 
-`done-done maintain` keeps the verify skill true: it checks the skill's links and feature index, checks that every `file:line` it cites exists, and has your coding agent read the source for each feature, read-only, to report drift. It ends `clean`, `drift` with the findings to fix, or `blocked`. It never runs without that reader: an agent that is not set asks, and one that cannot start or cannot read without tools stops it before the run (exit 2). With `auto_fix: { maintain: <n> }` (as in no-mistakes; 0, the default, reports only), your judge first sorts each drift finding (a skill out of date, or a product that may be wrong, which stops and asks you), then your agent fixes the skill folder only, in a done-done worktree, and maintain runs again, up to n times. A clean end is `changed`: one commit on a `done-done/maintain-<run-id>` branch, your branch untouched ([reference](reference.md#keep-the-verify-skill-true)).
+`done-done maintain` keeps the verify skill true: it checks the skill's links and feature index, checks that every `file:line` it cites exists, and has your coding agent read the source for each feature, read-only, to report drift. It reads each feature file's named source files (with or without a line) and `SKILL.md`'s launch claims; a reader with nothing to read ends it `blocked`, never `clean`. It ends `clean`, `drift` with the findings to fix, or `blocked`. It never runs without that reader: an agent that is not set asks, and one that cannot start or cannot read without tools stops it before the run (exit 2). With `auto_fix: { maintain: <n> }` (as in no-mistakes; 0, the default, reports only), your judge first sorts each drift finding (a skill out of date, or a product that may be wrong, which stops and asks you), then your agent fixes the skill folder only, in a done-done worktree, and maintain runs again, up to n times. A clean end is `changed`: one commit on a `done-done/maintain-<run-id>` branch, your branch untouched ([reference](reference.md#keep-the-verify-skill-true)).
 
 **3. Run it, then check it**
 

package/docs/reference.md

@@ -80,7 +80,7 @@ done-done doctor --probe
 
 #### Agents
 
-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; 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.
+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 cannot be a tool-less call: probed live on codex-cli 0.159.2 with your config.toml honored, its MCP server read a canary file outside the folder and `--disable multi_agent` left its multi-agent tools on, so done-done never starts codex tool-less: the judge exits with the reason, starting nothing; `doctor --probe` shows a warning with that reason and asks codex nothing; a codex maintain run stops before any run with exit 2 and the reason, as a gemini maintain run does. `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).
 
@@ -536,7 +536,7 @@ done-done maintain        # --no-wait, --wait (the default), or --foreground (fo
 
 - `locate`: the verify skill (`skill`, default `.agents/skills/done-done-verify-<app>`) must have a `SKILL.md`; with none, the run ends `blocked` and points at `done-done init`.
 - `hygiene` (plain code): every local markdown link in the skill must resolve (`dead-link`); `features/README.md` must exist (`index`), list each `features/*.md` file (`unlisted`) and list it only once (`duplicate`).
-- `source-wave`: one fresh reader per feature file, at the configured agent (`agent`, `agent_config`). Every reader except claude's gets no tools (pi `--no-tools`, opencode and acp with every tool denied); codex and gemini cannot read tool-less at all, so `maintain` never runs without a reader: an agent that cannot read tool-less, or that done-done cannot start, stops it before any run with exit 2 and the reason (use claude, opencode, pi or acp). Where readers run, plain code puts the feature file and the text of each tracked file it cites into the prompt, each file capped at 20,000 characters (a cut file is marked `[truncated after 20000 characters]` in the prompt, with no finding of its own) and all of a feature's cited text at 60,000 characters, with one `truncated` notice naming the feature and the cited files left out when any are dropped. Only claude readers get read-only tools in the repo (`--tools Read,Grep,Glob` with `--setting-sources ''` and `--strict-mcp-config`, so no user settings or MCP servers load): a live probe showed opencode reads through an in-repo symlink to an outside target, while claude refuses it. Each reader explains the feature from source and returns its drift (each statement the source contradicts, with the source file:line) and one live recipe. Readers run one after another; a run makes at most 30 recorded agent calls, each bounded by `agent_timeout`; a tool-less call that does not answer valid JSON is tried up to three times in all within its record, so a run starts at most 90 agent processes. A feature file longer than 20,000 characters is read only up to that cap, and a `truncated` notice names it; the notice is listed but does not make the result `drift`. A symlink on the skill path (the skill folder, its features folder, the index or a feature file) is a blocking `coverage` finding and is never read, so a committed link cannot send a file outside the repo to the agent; a skill reached through a symlinked ancestor is refused at `locate`. Readers cannot read outside the repo: claude runs without `--add-dir` or a permission bypass, so reads outside its working directory are refused.
+- `source-wave`: one fresh reader per feature file, at the configured agent (`agent`, `agent_config`). Every reader except claude's gets no tools (pi `--no-tools`, opencode and acp with every tool denied); codex and gemini cannot read tool-less at all, so `maintain` never runs without a reader: an agent that cannot read tool-less, or that done-done cannot start, stops it before any run with exit 2 and the reason (use claude, opencode, pi or acp). Where readers run, plain code puts the feature file and the text of each tracked file it cites into the prompt, each file capped at 20,000 characters (a cut file is marked `[truncated after 20000 characters]` in the prompt, with no finding of its own) and all of a feature's cited text at 60,000 characters, with one `truncated` notice naming the feature and the cited files left out when any are dropped. Only claude readers get read-only tools in the repo (`--tools Read,Grep,Glob` with `--setting-sources ''` and `--strict-mcp-config`, so no user settings or MCP servers load): a live probe showed opencode reads through an in-repo symlink to an outside target, while claude refuses it. A feature file names its source by path with or without a line (`public/index.html`, `src/app.js:12`; `init` writes names without lines), and each named tracked file is sent. A tool-less reader whose feature file names no tracked file is `coverage` (the run ends `blocked`): with no source it could only call the feature right, so a `clean` would mean nothing was read. `SKILL.md` is read the same way, after the features, when it names tracked source: its launch and readiness claims (a health route, a port variable) drift like a feature's. Statements about done-done itself (the `instance` block, `DONE_DONE_*` variables) are never drift. Each reader explains the feature from source and returns its drift (each statement the source contradicts, with the source file:line) and one live recipe. Readers run one after another; a run makes at most 30 recorded agent calls, each bounded by `agent_timeout`; a tool-less call that does not answer valid JSON is tried up to three times in all within its record, so a run starts at most 90 agent processes. A feature file longer than 20,000 characters is read only up to that cap, and a `truncated` notice names it; the notice is listed but does not make the result `drift`. A symlink on the skill path (the skill folder, its features folder, the index or a feature file) is a blocking `coverage` finding and is never read, so a committed link cannot send a file outside the repo to the agent; a skill reached through a symlinked ancestor is refused at `locate`. Readers cannot read outside the repo: claude runs without `--add-dir` or a permission bypass, so reads outside its working directory are refused.
 - `reconcile`: the tool-less call names at most 500 recently changed paths, most recent first, and says how many older ones it left out (those get no `unmapped` check). Plain code checks each `path:line` the skill cites (`citation`) and each file:line a reader cites. A bare file name (`app.js:50`) is checked against the tracked files whose path ends with it, and the line must exist in one of them; no tracked match is a finding. A repo path (`src/app.js:50`) must be a tracked file too, so an untracked or ignored file is a citation finding in the skill and an unverified drift in a reader's answer. A bare name is a citation only when its extension is one that a tracked file has, so host:port text such as `api.example.com:8443` is ignored. A reader's drift cites files the same way, and its drift becomes a `drift` finding only when its citation exists, and unverified citations are listed under `unverified` in the run's status (and in the step log), with a count and the first few. An answer item in an unexpected shape, or a list field that is not a list, is listed there too and never trusted. One tool-less call merges the recipes into as few app states as it can and names files changed in the last 30 days (`git log`, outside the skill folder) that no feature covers; each one that is in that list becomes an `unmapped` finding. maintain gives no result without its readers: with no agent set it asks, as in [Agents](#agents). Gemini cannot be a reader yet: its no-tools mode is read-only plan mode, not tool-free, so `maintain` with gemini stops with exit 2 before any run.
 
 The result is `clean` (no findings but notices, exit 0), `drift` (findings to fix by hand, or with `auto_fix`, exit 1), or `blocked` (no skill, a skill path that is a symlink or cannot be read, a reader that did not answer, more feature files than the call cap, or a repo that changed; exit 3). A blocked run still lists the findings from the plain checks it finished. `status` lists the findings (`--full` for all of them), each with an id, kind, file, line and what is wrong. Each agent call is recorded in `agents/<n>-<name>.json` in the run folder, without the prompt text; the readers' answers are in `logs/source-wave.log` and the merged recipes in `logs/reconcile.log`.

package/package.json

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