done-done-axi 0.6.0 → 0.6.3

package/README.md

@@ -1,22 +1,21 @@
+<a id="done-done"></a>
 <div align="center">
 
-<img src="docs/logo.svg" width="72" height="72" alt="done-done logo">
+<img src="docs/logo.svg" width="64" height="64" alt="done-done">
 
-# done-done
+[![npm](https://img.shields.io/npm/v/done-done-axi?label=done-done&color=5754d7)](https://www.npmjs.com/package/done-done-axi) [![Node 22.18+](https://img.shields.io/badge/node-22.18%2B-3fb950)](https://nodejs.org) [![Early preview](https://img.shields.io/badge/status-preview-d29922)](#whats-next)
 
-### No proof, no "done".
-
-**[Landing page](https://umeranjum17.github.io/done-done-axi/)**
+</div>
 
-done-done won't accept "done" without real, fresh proof from your product, captured at the exact commit being called done.
+# Prove your app really works.
 
-[![Node 22.18+](https://img.shields.io/badge/node-22.18%2B-3fb950?logo=nodedotjs&logoColor=white)](https://nodejs.org) [![Status: early preview](https://img.shields.io/badge/status-early%20preview-d29922)](#whats-next) [![npm: done-done-axi](https://img.shields.io/npm/v/done-done-axi?logo=npm&logoColor=white&label=npm)](https://www.npmjs.com/package/done-done-axi)
+A command-line check of real screenshots, recordings and output.
 
-</div>
+For developers using coding agents. Tests can pass while the app is still broken.
 
-## Install in 3 steps
+<img src="docs/media/demo.png" width="320" alt="Real sample app: Release checklist shows Capture the real app checked and Done. The actual claude-haiku-5-5 judge passes that captured screenshot at sample commit 08d635e46a98.">
 
-You need Node 22.18 or later and git.
+<sub>Real sample app + live judge verdict, at the captured commit.</sub>
 
 ```sh
 npm install -g done-done-axi
@@ -24,31 +23,29 @@ cd your-app && done-done init
 done-done doctor
 ```
 
-1. **Install.** This puts `done-done` (and the long name `done-done-axi`) on your PATH. No `sudo`? Add `--prefix ~/.local` and put `~/.local/bin` on your `PATH`.
-2. **Set up your repo.** `init` writes a minimal `.done-done.yaml` and asks you, in a terminal, which coding agent and which judge to use. done-done never picks either for you. Outside a terminal, pass `--agent <agent> --model <model> --judge <agent> --judge-model <model>` instead.
-3. **Check the setup.** `doctor` changes nothing and names each missing piece with the exact command that fixes it.
+[Website](https://umeranjum17.github.io/done-done-axi/) · [Setup](#install-in-3-steps) · [Agent skill](#use-it-from-your-agent) · [Reference](docs/reference.md) · [npm](https://www.npmjs.com/package/done-done-axi)
 
-Then prove something: `done-done verify --outcome "<what a user can now do>"`. [Manual CLI](#manual-cli) below walks through journeys, `check` and `receipt`.
+## Install in 3 steps
 
-<div align="center">
+You need **[Node 22.18+](https://nodejs.org) and git**, plus your own signed-in coding agent or API key for the judge. Early preview; see [what's next](#whats-next).
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/media/flow-dark.svg">
-  <img src="docs/media/flow-light.svg" alt="How it works: capture your real app, tie every file to the exact commit, then check: pass with exit 0 or fail with exit 1." width="710">
-</picture>
+1. **Install.** The first line above puts `done-done` (and the long name `done-done-axi`) on your PATH. No `sudo`? Add `--prefix ~/.local` and put `~/.local/bin` on your `PATH`.
+2. **Set up your repo.** `init` writes a minimal `.done-done.yaml` and asks you, in a terminal, which coding agent and which judge to use. done-done never picks either for you. Outside a terminal, pass `--agent <agent> --model <model> --judge <agent> --judge-model <model>` instead.
+3. **Check the setup.** `doctor` changes nothing and names each missing piece with the exact command that fixes it. It checks setup, not whether your app works.
 
-<br><br>
+Review and commit the capture recipe and verify skill, then ask for proof:
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/media/hero-dark.svg">
-  <img src="docs/media/hero-light.svg" alt="A terminal: done-done records a run of a demo notes app and the check passes. After a code change, the same check fails because the proof is for an older commit." width="560">
-</picture>
+```sh
+done-done verify --outcome "<what a user can now do>"
+```
 
-</div>
+Your agent drives the real product and saves screenshots or output. A fresh judge checks whether each capture shows your claim. No judge pass, no receipt. You choose the agents and models; captures go to your chosen judge's provider, on your own plan or key. [Manual CLI](#manual-cli) walks through recording a journey, checking it and saving a receipt.
 
 ## Why
 
-"Done" is easy to say. Screenshots get reused, recordings go stale, and a green test run is not the app.
+<a id="no-proof-no-done"></a>
+
+**No proof, no "done".** "Done" is easy to say. Screenshots get reused, recordings go stale, and a green test run is not the app.
 
 done-done runs your capture and ties every screenshot, recording and log it saves to the exact commit. When someone says "done", it checks the proof they point to: is it really there, is it a real picture or video, is it from this commit, and is it new? If not, the check fails. If it can't tell, it says so instead of passing.
 
@@ -103,77 +100,7 @@ The skill is the recommended path, but it is not the only one.
 
 ### Manual CLI
 
-**1. Install**
-
-```sh
-npm install -g --prefix ~/.local done-done-axi
-```
-
-`--prefix ~/.local` installs into your home folder, so it needs no `sudo`. This installs two names for the same CLI: `done-done-axi` and the short `done-done` used below. If `command -v done-done` prints nothing, add `~/.local/bin` to your `PATH`: `export PATH="$HOME/.local/bin:$PATH"`.
-
-To skip the install, run `npx -y done-done-axi` wherever this README says `done-done`.
-
-**2. Set it up in your app's repo**
-
-```sh
-cd your-app
-done-done init
-```
-
-`init` writes a minimal `.done-done.yaml` (only if you don't already have one) that names your app, and a commented global `~/.done-done/config.yaml` (only if there is none). done-done never picks the coding agent it starts: `init` asks you in a terminal, or takes `--agent <agent> --model <model>`. It never picks the judge either, the agent of its own that `check`, `receipt`, `verify` and `design` always start to look at each capture: `init` asks in a terminal, or takes `--judge <agent> --judge-model <model>`. Any agent and model you choose runs, your coding agent's own too (the judge is a fresh session of its own). The config keys are in the [reference](docs/reference.md#config). A plain `init` never overwrites an existing config. When your coding agent is set, `init` also has it write a verify skill, `.agents/skills/done-done-verify-<app>/SKILL.md`, from the repo's own files (never overwriting one; with no agent set, no skill is written; an older `verify-<app>` skill is renamed to this once). Check its launch never touches real accounts or your own state. Evidence lives outside the repo, in `~/.done-done/evidence/<app>`, so it outlives the checkout that captured it. For an `answerer:pi` judge with no explicit model, done-done uses `openai-codex/gpt-6-luna`; `judge.model` or `agent_config.pi.model` overrides it. Then describe how to capture proof — swap the command for whatever drives your real app the way a user does and saves its screenshots, recordings or output (here a CLI's own output):
-
-```yaml
-journeys:
-  smoke:
-    command: npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs
-    core: true
-```
-
-The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails. The command also writes `steps.json` beside its captures: the target version, the state it started from, the steps a user takes and the result a user sees. `check`, `receipt` and `gate` read the claim against that record, so a test log wrapped in a script cannot prove a claim about the product ([the record](docs/reference.md#step-record)). A journey that only runs code checks (`npm test`, `yarn run check`, `tsc`, `pytest`, a linter or a build) is code-only: its log says the code checks pass, not that the product works, so `init --journey` refuses it and `check`, `receipt` and `gate` never count it as proof ([the rule](docs/reference.md#real-product-evidence)).
-
-Name your **core journey** with `core: true`: the one thing a user cannot live without, driven end to end on the real target (for a remote terminal app: pair, open a pane, type, see the output). If your app ships something users install and upgrade (an npm CLI, an Android app, a host service), also record an **upgrade journey** with `upgrade: true` that installs your previous release, upgrades over it in place, then drives the core journey: a fresh install alone is not how users get your release. `doctor` fails until both are named ([the rule](docs/reference.md#core-journey-and-release-path)).
-
-Optional: `done-done init --hook <claude|codex|opencode|gemini|pi>` adds a session hook or plugin to the repo that shows each session the bare `done-done` state. Each agent's file and behavior are in the [reference](docs/reference.md#set-up-a-repo).
-
-Record the recipe in the repo so anyone can re-run the proof, then commit it (and `.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, `.opencode/plugins/done-done.js` or `.pi/extensions/done-done.js` if you added a hook):
-
-```sh
-done-done init --journey smoke --core -- 'npm start > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log && node record-steps.mjs'
-git add .done-done.yaml
-git commit -m "Add done-done"
-```
-
-A `run -- <command>` whose command matches no recorded journey still runs, but its result hints that the recipe is not in the repo. For a proof you drive by hand or by your agent instead of a journey, `done-done run --open` prints a run id and a folder to capture into, and `done-done run --close <run-id>` seals it ([how](docs/reference.md#run-a-journey)).
-
-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](docs/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](docs/reference.md#keep-the-verify-skill-true)).
-
-**3. Run it, then check it**
-
-```sh
-done-done run smoke
-done-done check --outcome "it starts" ~/.done-done/evidence/your-app/*/*.log
-```
-
-Each command prints one machine-readable result. By default it is [TOON](https://github.com/toon-format/spec) (the compact AXI convention). `run` shows `result: recorded`: it captured evidence, and says nothing about whether it proves the claim. `check` starts your judge on each capture, and only a check the judge passes shows `result: pass`; with no judge set it asks for one, and a judge that fails stops with the cause (exit 2), never a result. Add `--json` for JSON, or `--full` to list every evidence file or finding instead of the first few. After later runs, use the `run_id` the result prints in place of the first `*`.
-
-Not sure which journeys a change touches? `done-done affected` lists them from the verify skill's feature map and the paths each feature cites (the core journey when it cannot tell, never fewer), and exits 1 until a receipt for HEAD covers them. Bare `done-done`, which the session hooks run, names them too.
-
-When a check passes, save a receipt and re-verify it later:
-
-```sh
-done-done receipt --outcome "it starts" ~/.done-done/evidence/your-app/*/*.log
-done-done receipt --verify "$(git rev-parse HEAD)"
-```
-
-No journey yet? `done-done verify --outcome "<what a user can now do>"` has your coding agent drive one feature of the verify skill the way a user does (`--feature <name>` picks it). Your judge then checks the captures. When it says a capture is wrong or unclear, or a capture it cannot read (a video or other file) is not judged, the run waits at its gate (exit 4) until you answer with `done-done respond --action fix`, which ends it `fail` so you fix the product or the recipe and run again: nothing moves a run past its judge, and no receipt is written without a judge pass. Until then, a new `verify` or `rerun` of the same claim in that checkout is refused, so nothing goes around the gate ([details](docs/reference.md#drive-by-agent)).
-
-With `auto_fix: { verify: <n> }` (0, the default, reports only), a failed verify is fixed with your own agent: your judge first sorts each wrong screen (a product bug to fix, or a question that waits at the gate for you), then your agent fixes the product in a done-done worktree with your ignored files copied in, and verify runs again there, up to n times. A pass ends `changed`, with the fix on a `done-done/verify-<run-id>` branch and your branch untouched ([details](docs/reference.md#fix-the-product)).
-
-While a `verify` or `maintain` run goes, `done-done status` shows its steps and next move, `done-done attach` streams its events, and `done-done logs --step <name>` shows one step's log. `done-done rerun` runs a failed verify run again from the failed step, `done-done abort` stops a live run, `done-done signoff` writes a verify run's sign-off message, and `done-done history` lists past runs.
-
-Run `done-done` with no arguments to see the current config and the next step.
+Prefer a terminal to an agent skill? The [manual walkthrough](docs/manual-cli.md) covers installation without sudo, choosing agents, capture recipes, core and upgrade journeys, hooks, `doctor`, checks, receipts and the verify/fix loop. All behavior details live there or in the [reference](docs/reference.md).
 
 ## What it checks
 
@@ -199,7 +126,7 @@ Every answer is an exit code: **0** pass, **1** fail, **2** usage or config erro
 
 done-done works on its own: the CLI and the skill need nothing else. It is one of three tools that each do one job and connect through small written contracts ([Vision](VISION.md)):
 
-- [`sign-off-axi`](https://www.npmjs.com/package/sign-off-axi): the board where agents ask you questions. `done-done signoff` writes a run's gate (when the judge was unsure) or its evidence in sign-off's message format and prints the post command; it never posts. Without sign-off you answer at the terminal with `done-done respond`.
+- [`sign-off-axi`](https://www.npmjs.com/package/sign-off-axi): the board where agents ask you questions. `done-done signoff` writes a run's gate (when the judge was unsure) or its evidence in sign-off's message format and prints the post command; it never posts on its own. With the opt-in (`done-done signoff --post`, or `signoff.post: true` in `.done-done.yaml`) it posts that message to the board through sign-off-axi, records the card on the run, and `done-done signoff --wait` brings the answer back to the same run. Without sign-off you answer at the terminal with `done-done respond`.
 - [`learn-from-mistakes-axi`](https://www.npmjs.com/package/learn-from-mistakes-axi): the retro tool that finds mistakes your agents keep repeating, with evidence. Neither tool needs the other.
 - [`first-draft-axi`](https://www.npmjs.com/package/first-draft-axi): turns a prompt into design mocks. Pass a mock to `done-done design <screen> --mock <screen>=<mock>` to judge a captured screen next to it.
 
@@ -228,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)
 
@@ -255,6 +183,6 @@ npx -y --allow-git=all github:umeranjum17/done-done-axi --help
 
 `dist/` is committed, so installing from GitHub needs no build step. `npm test` rebuilds it and fails while the rebuilt `dist/` differs from the commit or has files git does not track, so `git add` the new `dist/` files with your change.
 
-The terminal pictures (hero, run, pass, reasons, config) are real output from the current build, with a stub judge (no model); redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
+The first-screen PNG pairs an actual sample-app screenshot with its real configured-judge pass and captured commit. Start a fresh sample with `node docs/media/demo.mjs <fresh-scratch-directory> 0` (the server prints its owned port), open a native run in its `app/` repo, drive the checklist in the browser, save `app.png` at 400×140 DPR 2 into the run's evidence folder, seal it and run `check` with your configured judge. Save the open result as `<scratch>/open.json` and the check result as `<scratch>/check.json`; `/proof` displays that screenshot and verdict. Capture `/proof` at 400×230 DPR 2 with `chrome-devtools-axi`. It refuses to show a pass without a real passing result. Keep scratch outside the repo and stop the server afterwards. The lower terminal illustrations (hero, run, pass, reasons, config) use a stub judge (no model); redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
 
 The landing page ([`docs/index.html`](docs/index.html), served by GitHub Pages from `main` `/docs`) is static: change it in the same PR as any README change it repeats (install steps, what it checks, the other tools).

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/cli.js

@@ -10,7 +10,7 @@ import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { Document, parseDocument } from 'yaml';
 import { ACPX_INSTALL, agentChoices, agentPath, agentRun, askAgent, editOnlyReason, findBin, JUDGES, modelFor, noAgent, noJudge, notStartable, routeOf, selectAgent, selectFallback, selectJudge, toollessReason } from './agents.js';
-import { AGENTS, CHEAP, globalConfigText, home, inputPattern, isAgent, isJudgeRoute, loadConfig, parseDuration, UsageError } from './config.js';
+import { AGENTS, CHEAP, globalConfigText, home, inputPattern, isAgent, isJudgeRoute, loadConfig, parseDuration, tilde, UsageError } from './config.js';
 import { backend, judge, judgeable, onPath, quote, screen } from './judge.js';
 import { startInstance, stopInstance } from './instance.js';
 import { attemptProblem, changedSince, commitFix, dirtyTracked, FIX_SCHEMA, inWorktree, maintainSteps, named, pathspec, readerProblem, repoState, triage } from './maintain.js';
@@ -60,11 +60,17 @@ const RUNS_TEXT = `runs: each verify or maintain run lives in $DONE_DONE_HOME/ru
   hashed before and after the drive; the check step fails naming each changed, appeared or
   disappeared path (never file contents), and the before/after hash lists go into the run record; no key: unchanged
   gate: a judge fail or unsure (or an agent drive with no judged capture) parks the run as awaiting_approval (exit 4); nothing moves it
-  past the judge: respond --action fix ends it fail, with no receipt (approve and skip answer only a spend gate)
+  past the judge: respond --action fix ends it fail, with no receipt (skip ends it fail too, without the fix; approve answers only a spend gate)
   auto_fix: { verify: <n> } (config; 0, the default, reports only): the judge sorts each wrong screen (fix or ask; an ask, an unsure
   answer or a mixed result parks at the gate), then the agent the user set fixes the product in a done-done worktree with your
   ignored files copied in, and verify runs again there, up to n times. Result: changed (the fix on a done-done/verify-<run-id>
   branch, your HEAD still fails; exit 1) or blocked (dirty checkout, a guard, or every attempt used; exit 1)`;
+const SIGNOFF_TEXT = `sign-off (.done-done.yaml): the board where the person answers. done-done writes the message (contract v1) and, with the opt-in, posts it:
+  signoff.post: true lets every signoff post to the board; --post posts one run. Without it, signoff only writes the message and prints the post command.
+  signoff.board names the board file (default: the nearest .sign-off/ board sign-off-axi finds); --board names it for one run.
+  signoff --wait waits for the answer to the card that run posted (--timeout, default 10m) and feeds it back to that run: a gate's
+  approve, skip or fix ends or resumes the run, exactly as done-done respond does. The card (its key and board) is recorded on the run,
+  so status shows it. The board is sign-off's own: done-done posts through sign-off-axi and never edits a board.`;
 const MAINTAIN_TEXT = `maintain reads the verify skill and the source; HEAD, git status and the content of changed files must be the same before and after.
   locate: the verify skill (.agents/skills/done-done-verify-<app>/SKILL.md); none: blocked, create it with done-done init
   hygiene: every local link in the skill resolves; features/README.md lists each features/*.md file once
@@ -124,8 +130,11 @@ const FLAGS = {
     '--mock <screen>=<mock>': 'judge this screen next to its approved mock (repeat per screen; the screen is judged even when not listed)',
     '--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: end it fail, then fix the product or the verify skill (done-done maintain checks it against the source)',
+    '--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',
     '--reason "<why>"': 'why (required for approve and skip at a spend gate); kept in the run with who answered',
+    '--post': 'with signoff: post the message to the sign-off board through sign-off-axi and record the card on the run (the opt-in: without it, signoff only writes the message)',
+    '--board <file>': 'with signoff: the board file to post to (default: the nearest .sign-off/ board sign-off-axi finds)',
+    '--timeout <duration>': 'with signoff --wait: how long to wait for the answer (default 10m)',
     '--limit <n>': 'how many past runs to list (default all)',
     '--out <file.png>': 'where look writes the screenshot; its page-check record goes next to it as <file>.dom.json (default: look.png in $DONE_DONE_EVIDENCE_ROOT inside a journey, else in the current folder)',
     '--agent <agent>': 'the coding agent done-done starts (claude, codex, opencode, pi, gemini or acp:<target>), saved as agent in ~/.done-done/config.yaml; without it, init asks in a terminal',
@@ -289,9 +298,13 @@ const COMMANDS = {
         more: [RUNS_TEXT],
     },
     signoff: {
-        usage: [['done-done signoff [--run <run-id>]', "write the run's sign-off message (contract v1): a gate for a run waiting at its gate, evidence for a finished run; it prints the post command and never posts"]],
-        flags: ['--run <run-id>'],
-        more: [RUNS_TEXT],
+        usage: [
+            ['done-done signoff [--run <run-id>]', "write the run's sign-off message (contract v1): a gate for a run waiting at its gate, evidence for a finished run; without the opt-in it prints the post command and never posts"],
+            ['done-done signoff --post [--board <file>]', 'post that message to the sign-off board through sign-off-axi and record the card on the run'],
+            ['done-done signoff --wait [--timeout <duration>]', 'wait for the answer to the card this run posted and feed it back to that run'],
+        ],
+        flags: ['--run <run-id>', '--post', '--board <file>', '--wait', '--timeout <duration>'],
+        more: [RUNS_TEXT, SIGNOFF_TEXT],
     },
     history: {
         usage: [['done-done history [--limit <n>]', 'list past runs, newest first']],
@@ -1949,6 +1962,12 @@ const reapJourney = (dir, run) => {
     if (run.runner?.instance_pgid && createOnce(join(dir, 'instance.killed')))
         killGroup(run.runner.instance_pgid);
 };
+// The exit code a run's state means: 0 pass, 1 fail, 2 stopped, 3 inconclusive, 4 still running or waiting at its gate.
+const runCode = (run, status) => status === 'pending' || status === 'running' || status === 'awaiting_approval' ? WAITING
+    : run.stopped && status === 'failed' ? USAGE
+        : status === 'cancelled' || status === 'failed' || run.result === 'fail' || run.result === 'drift' || (run.kind === 'verify' && (run.result === 'changed' || run.result === 'blocked')) ? FAIL
+            : run.result === 'inconclusive' || run.result === 'blocked' ? INCONCLUSIVE
+                : PASS;
 // One run as status shows it. A run still marked running whose runner is gone is shown as failed at its step.
 // `gone`: the caller saw its runner child exit, which also covers a runner that died before it wrote its pid.
 function showRun(dir, cfg, command, gone = false) {
@@ -1963,7 +1982,7 @@ function showRun(dir, cfg, command, gone = false) {
         reason = `the runner died at step ${at?.name}${run.runner ? ` (pid ${run.runner.pid}, last heartbeat ${beat}s ago)` : ' before it started'}`;
         reapJourney(dir, run);
     }
-    const code = status === 'pending' || status === 'running' || status === 'awaiting_approval' ? WAITING : run.stopped && status === 'failed' ? USAGE : status === 'cancelled' || status === 'failed' || run.result === 'fail' || run.result === 'drift' || (run.kind === 'verify' && (run.result === 'changed' || run.result === 'blocked')) ? FAIL : run.result === 'inconclusive' || run.result === 'blocked' ? INCONCLUSIVE : PASS;
+    const code = runCode(run, status);
     const drive = run.journey ?? (run.feature ? `--feature ${arg(run.feature)}` : '');
     const again = run.kind === 'maintain' ? 'done-done maintain' : `done-done verify ${drive ? `${drive} ` : ''}--outcome ${arg(run.claim)}${run.claim_id ? ` --claim-id ${arg(run.claim_id)}` : ''}`;
     const findings = cap(run.findings ?? []);
@@ -1987,6 +2006,8 @@ function showRun(dir, cfg, command, gone = false) {
         result.response = run.response;
     if (run.spend)
         result.spend = run.spend;
+    if (run.signoff)
+        result.signoff = run.signoff;
     if (ev.items.length)
         result.evidence = ev.items;
     if (ev.omitted)
@@ -2134,7 +2155,8 @@ async function cmdVerify(argv) {
 }
 // Run the steps in this process (--foreground), or in a detached runner with no pipe back to this process, so the
 // runner goes on when this command or its shell ends; --wait (the default) holds this command until the run ends.
-async function launch(dir, cfg, command, how) {
+// Start the run's runner and wait for it to end; the caller shows the run.
+async function startRunner(dir, how) {
     if (how.foreground) {
         const stop = heartbeat(dir);
         try {
@@ -2143,7 +2165,7 @@ async function launch(dir, cfg, command, how) {
         finally {
             stop();
         }
-        return showRun(dir, cfg, command);
+        return { gone: false };
     }
     const fd = openSync(join(dir, 'logs', 'runner.log'), 'a');
     const child = spawn(process.execPath, [CLI_PATH, '__runner', dir], { cwd: loadRun(dir).repo, detached: true, stdio: ['ignore', fd, fd] });
@@ -2151,7 +2173,11 @@ async function launch(dir, cfg, command, how) {
     closeSync(fd);
     if (!how['no-wait'])
         await waitRun(dir, child.pid);
-    return showRun(dir, cfg, command, !alive(child.pid));
+    return { gone: !alive(child.pid) };
+}
+async function launch(dir, cfg, command, how) {
+    const { gone } = await startRunner(dir, how);
+    return showRun(dir, cfg, command, gone);
 }
 async function cmdMaintain(argv) {
     const { values } = parseArgs({ args: argv, options: { wait: { type: 'boolean' }, 'no-wait': { type: 'boolean' }, foreground: { type: 'boolean' } } });
@@ -2391,20 +2417,12 @@ function answeredBy(repo) {
     }
 }
 // Answer a run waiting at its gate. At a spend gate, approve runs the journey and skip ends the run with nothing spent. At
-// the judge gate only fix answers: it ends the run fail, since nothing moves a run past its judge and no receipt is ever
-// written without a judge pass. The runner has exited, so this command finishes the run; the respond lock lets only one
-// answer (or an abort) close it.
-async function cmdRespond(argv) {
-    const { values } = parseArgs({ args: argv, options: { run: { type: 'string' }, action: { type: 'string' }, reason: { type: 'string' } } });
-    const action = values.action;
-    if (action !== 'approve' && action !== 'skip' && action !== 'fix')
-        throw new UsageError('respond needs --action approve, skip or fix', 'Run: done-done respond --run <run-id> --action <approve|skip|fix> [--reason "<why>"]');
-    const reason = values.reason?.replace(/\s+/g, ' ').trim() ?? '';
-    const repo = repoRoot();
-    const cfg = loadConfig(repo);
-    const root = runsRoot(cfg.app);
-    const id = pickId(root, repo, 'respond', cfg, values.run);
-    const dir = join(root, id);
+// the judge gate only fix and skip answer: fix ends the run fail (the product or the verify skill is fixed next, and the run
+// goes again), skip ends it fail too, without the fix. Nothing moves a run past its judge, so approve never answers it and
+// no receipt is ever written without a judge pass. The runner has exited, so this command finishes the run; the respond
+// lock lets only one answer (or an abort) close it.
+// A sign-off board answer and a terminal answer both come through here, so they change the run the same way.
+async function answerGate(dir, id, action, reason, by) {
     const notAtGate = (r) => new UsageError(`run ${id} is not waiting at its gate (it is ${r.status === 'awaiting_approval' ? 'being answered' : shownStatus(r)})`, `Read it: done-done status --run ${id}`);
     if (!createOnce(join(dir, 'respond.lock')))
         throw notAtGate(loadRun(dir));
@@ -2414,12 +2432,11 @@ async function cmdRespond(argv) {
             throw notAtGate(run);
         if (run.gate.spend && action === 'fix')
             throw new UsageError(`run ${id} is at a spend gate, which takes --action approve or skip`, `Run: done-done respond --run ${id} --action approve|skip --reason "<why>"`);
-        if (!run.gate.spend && action !== 'fix')
-            throw new UsageError(`run ${id} is at its judge gate, which takes only --action fix: done-done never moves a run past its judge, and writes no receipt without a judge pass`, `Run: done-done respond --run ${id} --action fix, then fix the product or the verify skill's recipe, commit, and run again`);
+        if (!run.gate.spend && action === 'approve')
+            throw new UsageError(`run ${id} is at its judge gate, which takes only --action fix or skip: done-done never moves a run past its judge, and writes no receipt without a judge pass`, `Run: done-done respond --run ${id} --action fix, then fix the product or the verify skill's recipe, commit, and run again`);
         if (action !== 'fix' && !reason)
             throw new UsageError(`respond --action ${action} needs --reason "<why>": the spend answer is recorded with who and why`, `Run: done-done respond --run ${id} --action ${action} --reason "<why>"`);
         const gate = run.steps.find((s) => s.name === 'gate');
-        const by = answeredBy(repo);
         run.response = { action, by, ...(reason && { reason }), at: now() };
         logEvent(dir, { step: 'gate', response: action, by, ...(reason && { reason }) });
         // The spend gate: approve runs the journey in a new runner; skip ends the run with nothing spent.
@@ -2428,34 +2445,106 @@ async function cmdRespond(argv) {
             if (action !== 'approve') {
                 setStep(dir, run, drive, 'failed');
                 finishRun(dir, run, 'fail', `gate: ${by} chose ${action}: the journey was not run, so nothing was spent`);
-                return showRun(dir, cfg, 'respond');
+                return { gone: false };
             }
             Object.assign(run, { spend: { by, reason, at: run.response.at }, status: 'pending', gate: undefined, response: undefined, runner: undefined });
             setStep(dir, run, drive, 'pending');
             for (const lock of ['runner.lock', 'respond.lock'])
                 rmSync(join(dir, lock));
-            return launch(dir, cfg, 'respond', {});
+            return await startRunner(dir, {});
         }
         setStep(dir, run, gate, 'failed');
-        finishRun(dir, run, 'fail', `gate: ${by} chose fix: ${reason || run.gate.findings[0].what}`);
-        return showRun(dir, cfg, 'respond');
+        finishRun(dir, run, 'fail', `gate: ${by} chose ${action}: ${reason || run.gate.findings[0].what}`);
+        return { gone: false };
     }
     catch (e) {
         rmSync(join(dir, 'respond.lock'), { force: true });
         throw e;
     }
 }
+// Answer a run waiting at its gate, from the terminal.
+async function cmdRespond(argv) {
+    const { values } = parseArgs({ args: argv, options: { run: { type: 'string' }, action: { type: 'string' }, reason: { type: 'string' } } });
+    const action = values.action;
+    if (action !== 'approve' && action !== 'skip' && action !== 'fix')
+        throw new UsageError('respond needs --action approve, skip or fix', 'Run: done-done respond --run <run-id> --action <approve|skip|fix> [--reason "<why>"]');
+    const reason = values.reason?.replace(/\s+/g, ' ').trim() ?? '';
+    const repo = repoRoot();
+    const cfg = loadConfig(repo);
+    const root = runsRoot(cfg.app);
+    const id = pickId(root, repo, 'respond', cfg, values.run);
+    const dir = join(root, id);
+    const answered = await answerGate(dir, id, action, reason, answeredBy(repo));
+    return showRun(dir, cfg, 'respond', answered.gone);
+}
+// The sign-off board's own CLI (github.com/umeranjum17/sign-off): done-done posts through it and never edits a board.
+// It prints one document: `field: value` lines, a table and a help list.
+function signoffRun(args, cwd) {
+    const r = spawnSync('sign-off-axi', args, { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+    if (r.error?.code === 'ENOENT')
+        throw new UsageError('sign-off-axi is not on PATH, so nothing was posted', 'Install the board CLI: npm install -g sign-off-axi, then run this again');
+    return { code: r.status ?? 1, out: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+}
+// One field of that document: the value of the first line that starts with `name:`.
+const signoffField = (out, name) => {
+    const line = out.split('\n').find((l) => l.startsWith(`${name}:`));
+    if (!line)
+        return '';
+    const raw = line.slice(name.length + 1).trim();
+    return raw.startsWith('"') && raw.endsWith('"') && raw.length > 1 ? raw.slice(1, -1) : raw;
+};
+// Its help line: the value of the first `help[n]:` line.
+const signoffHelp = (out) => {
+    const line = out.split('\n').find((l) => l.startsWith('help['));
+    if (!line)
+        return '';
+    const raw = line.slice(line.indexOf(':') + 1).trim();
+    return raw.startsWith('"') && raw.endsWith('"') && raw.length > 1 ? raw.slice(1, -1) : raw;
+};
+// Post the message to the board and read back the card it made.
+function postToBoard(cwd, board, kind, file, key) {
+    const { code, out } = signoffRun(['post', ...(board ? [board] : []), '--kind', kind, '--from', file], cwd);
+    if (code !== 0)
+        throw new UsageError(signoffField(out, 'error') || `sign-off-axi post ended with exit ${code}`, signoffHelp(out) || 'Read it: sign-off-axi post --help');
+    const shown = out.split('\n').some((l) => { const t = l.trim(); return t === key || t.startsWith(`${key},`) || t.startsWith(`${key} `); });
+    if (!shown)
+        throw new UsageError(`sign-off-axi posted without the card ${key}, so the run has no sign-off card`, 'Read the board: sign-off-axi list');
+    return { board: signoffField(out, 'board') || board, key };
+}
+// Wait for the answer to a card on the board and read it back.
+function waitForAnswer(cwd, board, key, seconds) {
+    const { code, out } = signoffRun(['wait', ...(board ? [board] : []), '--key', key, '--json', '--timeout', String(seconds)], cwd);
+    if (code !== 0)
+        throw new UsageError(signoffField(out, 'error') || `sign-off-axi wait ended with exit ${code}`, signoffHelp(out) || `Wait again: done-done signoff --wait`);
+    let answers;
+    try {
+        answers = JSON.parse(out);
+    }
+    catch {
+        throw new UsageError(`sign-off-axi wait printed no answer for the card ${key}`, `Read it: sign-off-axi answers --key ${key}`);
+    }
+    const answer = answers[key];
+    if (!answer)
+        throw new UsageError(`the board card ${key} has no answer`, `Read it: sign-off-axi answers --key ${key}`);
+    return { value: answer.answer, ...(answer.label && { label: answer.label }), ...(answer.at && { at: answer.at }), ...(answer.note && { note: answer.note }) };
+}
 // sign-off's communication contract v1 (github.com/umeranjum17/sign-off, docs/contract.md): done-done sends `gate` and
 // `evidence`, schema 1. Each value is checked against the contract's limits first, so a run that cannot make a valid
-// message writes no file. done-done never posts it: sign-off is the user's choice, so the help line names the post command.
-const GATE_LABELS = { approve: 'Approve the spend', skip: 'Skip the spend', fix: 'Fix first' };
-function cmdSignoff(argv) {
-    const { values } = parseArgs({ args: argv, options: { run: { type: 'string' } } });
+// message writes no file. Without the opt-in done-done never posts it: sign-off is the user's choice, so the help line
+// names the post command. With the opt-in (--post, or signoff.post in .done-done.yaml) done-done posts it through
+// sign-off-axi, records the card on the run and can wait for the answer to feed back to that run.
+// The contract fixes a gate's options: approve (Approve), skip (Skip the judge) and fix (Fix first), and it takes two or
+// three of them. A spend gate answers approve or skip; a judge gate answers fix or skip, never approve: nothing moves a
+// run past its judge.
+const GATE_LABELS = { approve: 'Approve', skip: 'Skip the judge', fix: 'Fix first' };
+async function cmdSignoff(argv) {
+    const { values } = parseArgs({ args: argv, options: { run: { type: 'string' }, post: { type: 'boolean' }, board: { type: 'string' }, wait: { type: 'boolean' }, timeout: { type: 'string' } } });
     const repo = repoRoot();
     const cfg = loadConfig(repo);
     const root = runsRoot(cfg.app);
     const id = pickId(root, repo, 'signoff', cfg, values.run);
-    const run = loadRun(join(root, id));
+    const dir = join(root, id);
+    let run = loadRun(dir);
     const refuse = (what, help) => { throw new UsageError(`run ${id} cannot make a valid sign-off message, so no file was written: ${what}`, help); };
     const text = (field, v, max, help = `Read it: done-done status --run ${id}`) => {
         const n = [...v].length;
@@ -2472,6 +2561,44 @@ function cmdSignoff(argv) {
     // names the capture file alone: strip any <evidence root>/<one run folder>/ prefix.
     const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const bare = (s) => s.replaceAll(new RegExp(`${esc(cfg.evidence.root)}${esc(sep)}[^${esc(sep)}]+${esc(sep)}`, 'g'), '');
+    // The board: the one the user names (--board, or signoff.board), else the nearest .sign-off/ board sign-off-axi finds.
+    const boardName = values.board ?? cfg.signoff.board;
+    const board = boardName ? resolve(repo, tilde(boardName)) : '';
+    // The opt-in: --post posts this run, signoff.post in .done-done.yaml posts every run. Without it nothing is posted.
+    const posts = values.post === true || cfg.signoff.post;
+    // Wait for the answer to the card this run posted and feed it back to that run.
+    const awaitCard = async (card) => {
+        const limit = parseDuration(values.timeout ?? '10m');
+        if (limit === null)
+            throw new UsageError(`--timeout ${values.timeout} is not a duration such as 90s, 10m or 1h`, 'Run: done-done signoff --wait --timeout 10m');
+        const answer = waitForAnswer(repo, board || tilde(card.board), card.key, Math.round(limit / 1000));
+        card.answer = { value: answer.value, ...(answer.label && { label: answer.label }), ...(answer.at && { at: answer.at }), ...(answer.note && { note: answer.note }) };
+        run = loadRun(dir);
+        run.signoff = card;
+        saveRun(dir, run);
+        logEvent(dir, { step: 'signoff', answered: card.key, answer: answer.value });
+        if (card.kind === 'gate') {
+            const action = answer.value;
+            if (action !== 'approve' && action !== 'skip' && action !== 'fix')
+                throw new UsageError(`the board card ${card.key} was answered ${action}, which is not an action of done-done respond`, `Read it: done-done status --run ${id}`);
+            const reason = answer.note?.replace(/\s+/g, ' ').trim() || `answered ${action} on the sign-off board card ${card.key}`;
+            await answerGate(dir, id, action, reason, answeredBy(repo));
+        }
+        run = loadRun(dir);
+        emit({
+            command: 'signoff', run_id: id, kind: card.kind, file: card.file, board: card.board,
+            card: { key: card.key, at: card.at }, answer: card.answer,
+            run: { status: shownStatus(run), ...(run.result && { result: run.result }), ...(run.reason && { reason: run.reason }) },
+            help: [`Read the run: done-done status --run ${id}`],
+        });
+        return runCode(run, shownStatus(run));
+    };
+    // Without the opt-in, --wait only reads the card the run already posted; it never posts one.
+    if (values.wait && !posts) {
+        if (!run.signoff)
+            throw new UsageError(`run ${id} has no sign-off card, so there is no answer to wait for`, `Post it first: done-done signoff --post --run ${id}`);
+        return await awaitCard(run.signoff);
+    }
     let msg, file;
     if (run.kind === 'verify' && run.status === 'awaiting_approval' && run.gate) {
         const { findings, spend, head } = run.gate;
@@ -2480,8 +2607,8 @@ function cmdSignoff(argv) {
             contract: 1, kind: 'gate', schema: 1, key: `dd-gate-${id}`, filer: 'done-done',
             title: text('title', spend ? `Spend ${spend} on the ${cfg.app} ${drove} run?` : `End the ${cfg.app} ${drove} run its judge did not pass, to fix it?`, 160),
             about: text('about', `${bare(findings[0].what)}${more}`, 500), run: runRef(head.commit),
-            // A spend gate takes approve or skip; the judge gate only fix, since nothing moves a run past its judge.
-            options: (spend ? ['approve', 'skip'] : ['fix']).map((value) => ({ value, label: GATE_LABELS[value] })),
+            // The contract's gate vocabulary: a spend gate takes approve or skip, a judge gate fix or skip, and nothing else.
+            options: (spend ? ['approve', 'skip'] : ['fix', 'skip']).map((value) => ({ value, label: GATE_LABELS[value] })),
             recommend_value: spend ? 'approve' : 'fix', close: 'done',
         };
         file = join(root, id, 'signoff-gate.json');
@@ -2542,7 +2669,23 @@ function cmdSignoff(argv) {
         return refuse(`it is ${shownStatus(run)}${run.kind === 'verify' ? '' : ` (a ${run.kind} run)`}; signoff writes a gate for a verify run waiting at its gate, or evidence for a finished verify run`, `Read it: done-done status --run ${id}`);
     writeFileSync(file, `${JSON.stringify(msg, null, 2)}\n`);
     const at = citable(repo, file);
-    emit({ command: 'signoff', run_id: id, kind: msg.kind, file: at, help: [`Post it to the sign-off board (done-done never posts): npx -y sign-off-axi post --kind ${msg.kind} --from ${arg(at)}`] });
+    if (!posts) {
+        emit({ command: 'signoff', run_id: id, kind: msg.kind, file: at, help: [`Post it to the sign-off board (done-done never posts): npx -y sign-off-axi post --kind ${msg.kind} --from ${arg(at)}`] });
+        return PASS;
+    }
+    // Post it through the board's own CLI and record the card it made, so the claim traces to the run and its card.
+    const posted = postToBoard(repo, board, String(msg.kind), at, String(msg.key));
+    const card = { key: posted.key, kind: msg.kind, board: posted.board, file: at, at: now() };
+    run.signoff = card;
+    saveRun(dir, run);
+    logEvent(dir, { step: 'signoff', posted: card.key, kind: card.kind });
+    if (values.wait)
+        return await awaitCard(card);
+    emit({
+        command: 'signoff', run_id: id, kind: card.kind, file: at, board: card.board,
+        card: { key: card.key, at: card.at },
+        help: [`Wait for the answer: done-done signoff --wait --run ${id}`, `Read the card: sign-off-axi answers --key ${card.key}`],
+    });
     return PASS;
 }
 function runsOf(repo, cfg) {
@@ -4050,7 +4193,7 @@ async function main(argv) {
         if (cmd === 'history')
             return cmdHistory(rest);
         if (cmd === 'signoff')
-            return cmdSignoff(rest);
+            return await cmdSignoff(rest);
         if (cmd === '__runner') {
             await runSteps(rest[0]);
             return PASS;