sign-off-axi 0.3.0 → 0.3.2

package/README.md

@@ -131,7 +131,7 @@ sign-off-axi post --type explainer --title "<question>" --media <video> [--about
 sign-off-axi init [dir] [--agent auto|<name>]   write the repo setup under <dir>/.sign-off/ (config, board, mocks/ and evidence/ folders)
                                                 and install the skill for each chosen coding agent (auto: each one on PATH)
 sign-off-axi doctor [dir]                       check that setup and each agent's skill; every failure names its fix
-sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]   check ask and report messages against the contract (docs/contract.md) without posting
+sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]   check ask, report and evidence messages against the contract (docs/contract.md) without posting
 sign-off-axi open  [--port 4410] [--bind <address>] [--evidence-root <dir>]   start the board in the background; prints its URL and pid
 sign-off-axi status                             is the board open started for this file running? its URL and pid
 sign-off-axi stop                               stop that board
@@ -145,11 +145,11 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 
 - The board is the one you name right after the command (`sign-off-axi answers ./decisions.json`). With none, it is the nearest `.sign-off/` board that `init` set up, found by the walk described in [Test runs never touch your board](#test-runs-never-touch-your-board); otherwise the default board there (`~/.sign-off/decisions.json`, or under `SIGN_OFF_HOME`). Answers are saved next to it.
 - Next-step commands in the output name paths under the working folder relative to it, and say `npx -y sign-off-axi` when sign-off-axi runs through `npx`.
-- `post --type design` asks for a pick between up to 6 mock options, each with an optional `--mock <value>=<path>` file (`.html`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) shown as a tall phone frame above its button (the recommended one first; on a phone the frames swipe sideways, the next one peeking in, and a tap opens one full size), plus a `--tradeoff` line and a `--recommend` badge. Mock paths are relative to the board file's folder and never escape it. One `.html` page can hold every variant: `--mock a=mocks/<key>/index.html?variant=a` loads the page with `?variant=a`. An `.html` mock or view loads the css, scripts, images and fonts beside it by relative name (`style.css`, `img/dot.png`), from its own folder only, never anything above it. The board adds a small pointing script to each `.html` mock: once the board turns it on for that frame, a tap on a part of the mock is kept from the mock and named back to the board as a path to that element, its tag and its words; it passes only text and gives the mock no reach into the board. With **Comment on the mocks** on, a tap opens a comment on that element: one per element, listed under the mocks with Edit and Delete, kept on the board and shown only on the exact mock file it was made on. An option with no mock, or whose file is gone, says "No mock for this option". `post --type decision` (the default) is exactly `raise`, and `raise` stays as its alias.
+- `post --type design` asks for a pick between up to 6 mock options, each with an optional `--mock <value>=<path>` file (`.html`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) shown as a tall phone frame above its button (the recommended one first; on a phone the frames swipe sideways, the next one peeking in, and a tap opens one full size), plus a `--tradeoff` line and a `--recommend` badge. Mock paths are relative to the board file's folder and never escape it. One `.html` page can hold every variant: `--mock a=mocks/<key>/index.html?variant=a` loads the page with `?variant=a`. An `.html` mock or view loads the css, scripts, images and fonts beside it by relative name (`style.css`, `img/dot.png`), from its own folder only, never anything above it. The board adds a small pointing script to each `.html` mock: once the board turns it on for that frame, a tap on a part of the mock is kept from the mock and named back to the board as a path to that element, its tag and its words; it passes only text and gives the mock no reach into the board. With **Comment on the mocks** on, a tap opens a comment on that element: one per element, listed under the mocks with Edit and Delete, kept on the board and shown, until it is sent, only on the exact mock file it was made on. The comments go to the agent with the next answer on that card (a pick, Other answer or **Another round**, which may then have no note), each with its element, in `wait` and `answers` (`comments`); once sent they are listed as sent and can no longer change. An option with no mock, or whose file is gone, says "No mock for this option". `post --type decision` (the default) is exactly `raise`, and `raise` stays as its alias.
 - `post --type evidence` posts the next numbered update (`update-1`, `update-2`, ...) with 1 to 12 screenshots or recordings (`.png`, `.jpg`, `.jpeg`, `.webp`, `.mp4`, `.webm`, up to 50 MB each), a short note and an optional commit or PR link. The files are copied into `evidence/<number>/` next to the board, so the board is the store: no hosted service. The page shows the updates newest first; each file is served only while its size and SHA-256 still match what was posted, and recordings play inline on a phone. The person gives a verdict, **Pass**, **Fail** or **Needs work**, with an optional note, read back with `answers` or `wait --key update-<number>`.
 - `post --type diagram` and `post --type interactive` show a question with a picture: `--view <path>` names one board-relative file, an image (`.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) drawn at card width for a diagram, or one self-contained `.html` page that runs in a sandboxed frame for interactive. Every mock and view is served under a Content-Security-Policy with no `fetch`, no remote files and no access to the dashboard or its tab. They answer like a decision.
 - `post --type explainer` shows a question with a narrated video the agent made itself (stills plus speech from a free local engine such as piper or espeak-ng, joined with ffmpeg; the skill has the recipe). `--media` names one `.mp4` or `.webm`, copied into `evidence/<number>/` and served hash-checked like evidence media; it plays on the card with its own controls, at phone width too. `--about` is a short summary and each `--chapter m:ss=<title>` is a button that plays the video from there. sign-off itself never makes the video: it calls no speech engine, no ffmpeg and no network service.
-- The person can also tap **Another round** inside **Other answer** (with the typed note), which wakes a waiting agent the same way an answer does; the agent reads it back in `answers --json` under `rounds`.
+- The person can also tap **Another round** inside **Other answer** (with the typed note), which wakes a waiting agent the same way an answer does; the agent reads it back in `answers --json` under `rounds`, with any comments on mock elements it carried.
 - **Dismiss** (the × on an item in a list, **Dismiss** under Needs you first and beside **Skip for now** in Triage, or **Clear all done** on Answered) hides items from the board, Today included; **Undo** in the toast brings them back, and so does **Restore** under **Dismissed (N)** at the end of Needs you first and Triage. The agent is not told, so an ask it waits on keeps waiting. The storage is in [docs/file-formats.md](docs/file-formats.md).
 - The person can comment on any item (**Send as a comment**, also inside **Other answer**: each card has that one place to type) and queue a free-text prompt for the agent (**Ask the agent**). `poll` blocks until one arrives and prints every new one once (`--json` prints `{"messages":[{"id","kind","key"?,"text","at"}]}`); the page then shows it as read by the agent. Typed notes that are not sent yet stay in the browser across reloads; everything sent is saved next to the board and survives a restart.
 - The board runs on your own machine only: no hosted service, no recurring cost. It listens on `127.0.0.1` unless `--bind <address>` (or `bind:` in the `config.yaml` that `init` writes) names one private address of this machine, such as its VPN address, so a phone or tablet on your own network can open it. A `hosts:` line in that config names private DNS names that lead to the bind address, such as its mesh VPN name (commas between them), so the board also opens by name; `doctor` checks each one resolves to the bind address. All interfaces and public addresses are refused. Beyond `127.0.0.1` the board makes an access token once (`decisions.token`, mode 600, next to the board), `open` prints it in the link, and every request without it is refused; the link sets a cookie, so the page and its media work after the first load. Delete the token file to shut old links out at once, then `stop` and `open` for a new one.
@@ -160,7 +160,7 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 - Each raised or posted item records when it was filed (`filed`), so Triage shows `Waiting since 09:15` and the Waiting on you tile `Oldest 09:15`; `post --replace` keeps an item's first time.
 - `open` is a no-op when the same board is already open on the same address, and fails with `CONFLICT` when it runs on another one. `--evidence-root` is the folder holding `.done-done/`, for decisions that link run evidence.
 - `--filer <id>` on `post` and `raise` saves who filed the item (an agent session id or any 1-128 of `A-Z a-z 0-9 . _ -`; `SIGN_OFF_FILER` sets it for every command, and a post with neither saves `CLAUDE_CODE_SESSION_ID` when it is set). `wait --filer <id>` then returns only answers to that filer's items it has not taken yet, marks each taken (`decisions.seen.jsonl`) and the card shows **Seen by agent**; it fails with `NOT_FOUND` when none of that filer's items is answered or waiting. The page never shows the filer id.
-- `on_answer: <command> [args]` in the `config.yaml` beside the board runs that command for every saved answer, read when the board starts. It runs with no shell, in the board's folder, and gets the answer as one JSON line on stdin (`{"key","answer","label","close","at","note"?,"title"?,"filer"?}`); the answer is never put into its arguments, so a typed note cannot inject a command. A failure is logged and never blocks the answer. With no shell, `|`, `>` and `&&` are passed as plain arguments, so put a pipeline in a script and name the script; a relative path such as `./hook.sh` is found from the board's folder. `doctor` checks that the command can run.
+- `on_answer: <command> [args]` in the `config.yaml` beside the board runs that command for every saved answer, read when the board starts. It runs with no shell, in the board's folder, and gets the answer as one JSON line on stdin (`{"key","answer","label","close","at","note"?,"title"?,"filer"?,"comments"?}`, where `comments`, present when the answer carried comments on mock elements, lists each as `id`, `mock`, `hash`, `ref`, `tag`, `words` and `text`); the answer is never put into its arguments, so a typed note cannot inject a command. A failure is logged and never blocks the answer. With no shell, `|`, `>` and `&&` are passed as plain arguments, so put a pipeline in a script and name the script; a relative path such as `./hook.sh` is found from the board's folder. `doctor` checks that the command can run.
 - `post --from <file> --replace --filer <id>` lets several programs feed one board: it replaces only that filer's items (and items with no filer that the file names by key), keeps every other item, the board's other top-level fields and all answers, and an empty items list removes that filer's items.
 - `wait` replaces a polling loop. With `--key` it returns at once if that decision is already answered, and waits for a key that is not raised yet; without it, it waits for the next answer to any decision still waiting and fails with `NOT_FOUND` when nothing is. It wakes on each save, gives up after `--timeout` seconds (600, ten minutes, by default) with code `TIMEOUT` and exit 1, and takes `--full` and `--json` like `answers`. Ctrl-C stops it without changing anything.
 - `open` records the board's pid, port and address next to the board file (`decisions.board.pid`). `status` and `stop` read it and only act on a pid that really serves that board, so no one has to guess a pid to kill. `open` on a board already served by `serve` records that server, so `stop` can close it too.
@@ -202,6 +202,8 @@ npm run build:skill           # regenerates skills/sign-off-axi/SKILL.md from sr
 npm pack                      # builds the publishable sign-off-axi tarball
 ```
 
+A release is a merged version-bump PR: CI publishes the new version to npm.
+
 ### Test runs never touch your board
 
 With no board named, a bare command uses the nearest `.sign-off/` that `init` set up, looking from the working folder up to its repo root (the folder holding `.git`) or up to HOME, but never HOME's own `.sign-off/`. The working folder's own `.sign-off/` is always used. A folder above it is searched only when that climb reaches a repo root or HOME, so a `.sign-off/` above a folder with neither (outside HOME, no `.git`) is never used, and the account's own home is never used. Otherwise the default board is `~/.sign-off/decisions.json`, under `SIGN_OFF_HOME` when it is set (it takes HOME's place for the default board and for where the climb stops), else under HOME.

package/dist/cli.js

@@ -10,8 +10,8 @@ import { basename, delimiter, dirname, extname, isAbsolute, join, relative, reso
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
-import { CHAPTERS_MAX, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendMessage, appendRound, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, writeItems } from './store.js';
-import { ContractError, KINDS, checkMessage, parseMessage } from './contract.js';
+import { CHAPTERS_MAX, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendMessage, appendRound, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, writeItems } from './store.js';
+import { ContractError, KINDS, MEDIA_BYTES, checkMessage, mediaFiles, parseMessage } from './contract.js';
 import { sweepVault } from './vault.js';
 const FORMAT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/file-formats.md';
 const CONTRACT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/contract.md';
@@ -74,10 +74,11 @@ examples:
 `,
     validate: `usage: sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]
 Checks message files against the communication contract without posting them: ${CONTRACT}
-A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask and report, schema 1 each.
+A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, report and evidence, schema 1 each.
+An evidence message's media paths read from the message file's folder: each file must be there, inside it, and 50 MB or less.
 Post one with \`sign-off-axi post --kind <kind> --from <message.json>\`, or --from - to read stdin.
 A board file given to raise --from or post --from may hold such messages as items: each is checked the same way before it is stored, and a report shows under Reports with no answer.
-In such a file a new item of a contract kind (a decision, the default, an ask, evidence or a report) must carry contract, kind and schema.
+In such a file a new item of a contract kind (a decision, the default, an ask or a report) must carry contract, kind and schema; new evidence is posted with post --kind evidence, one at a time.
 Each file gets a row with ok, or the error and one help line that names the fix. A field written twice, an unknown field or a broken limit refuses the file.
   --kind            each file must be this kind, so the wrong file is refused
   --expect-invalid  every file must be refused: exits 0 only then, 2 when any passes (the conformance check of invalid fixtures)
@@ -88,6 +89,7 @@ examples:
   sign-off-axi validate ask.json
   sign-off-axi validate --kind ask messages/*.json
   sign-off-axi validate --kind report report.json
+  sign-off-axi validate --kind evidence proof/evidence.json
   sign-off-axi validate --expect-invalid node_modules/sign-off-axi/fixtures/contract/*/invalid-*.json
 `,
     answers: `usage: sign-off-axi answers [board.json] [--key <key>] [--full] [--json]
@@ -156,6 +158,8 @@ examples:
 Posts an item for the user. --type decision (the default) is a yes/no or pick-one question, exactly like raise.
 --kind posts one contract message (${CONTRACT}), read from a file or from stdin with --from -: it must be that kind and pass every rule,
 else it is refused with one fix line and nothing is written. A key already on the board takes only the same message again; anything else exits 2.
+--kind evidence copies its media, read from the message file's folder (the current folder for stdin), into evidence/<number>/ like --type evidence;
+a "run" is shown as the update's proof record. With no key it posts the next update-<number>.
 Listing --option needs --recommend <value>, on every type: the option you would pick, shown first and marked. --from --replace feeds are not held to it.
 --filer names who posts (your agent session or any id of 1-128 of A-Z a-z 0-9 . _ -), saved on the item; then \`wait --filer <id>\` gets the answer.
 SIGN_OFF_FILER sets it for every command; with neither, the Claude Code session id is saved when there is one.
@@ -180,6 +184,7 @@ examples:
   sign-off-axi post .sign-off/decisions.json --type design --key sign-in --title "Pick the sign-in layout" --option a=A --option b=B --option c=C --mock a=mocks/sign-in/index.html?variant=a --mock b=mocks/sign-in/index.html?variant=b --mock c=mocks/sign-in/index.html?variant=c --tradeoff "..." --recommend b
   sign-off-axi post --type decision --title "Keep the weekly digest?" --recommend yes
   sign-off-axi post --kind ask --from ask.json --filer agent-41
+  sign-off-axi post --kind evidence --from proof/evidence.json --filer done-done
   sign-off-axi post .sign-off/decisions.json --type interactive --title "Does the sign-in flow feel right?" --view mocks/sign-in/demo.html --option yes=Yes --option no="Needs work" --recommend yes
   sign-off-axi post --type evidence --title "Sign-in screen on a phone" --about "The new screen loads in 1 second." --media phone.png --media flow.mp4 --link https://github.com/acme/app/pull/12
   sign-off-axi post --type explainer --title "Is the new sign-in clear?" --about "The new sign-in has 2 steps." --media explainer.mp4 --chapter 0:00=Start --chapter 0:12="Step 2"
@@ -252,9 +257,15 @@ const CONTRACT_TYPES = ['decision', 'ask', 'evidence', 'report'];
 /** Items of a --from file that carry contract or kind are contract messages: each is checked against its kind's rules before anything is stored.
  * A new item of a contract kind must carry them (contract section 2); one already on the board is not checked again. */
 function contractItems(items, from, file) {
-    const had = new Set(existsSync(file) ? readItems(file).items.map((i) => i?.key) : []);
+    const on = new Map((existsSync(file) ? readItems(file).items : []).map((i) => [i?.key, i]));
     items.forEach((m, i) => {
-        if (had.has(m?.key))
+        // Evidence in message form (no type) never comes in a feed, even under a key on the board: its media must be copied and numbered.
+        // A stored board-format evidence item passes through a feed unchanged; any other evidence under a key is refused.
+        const kept = on.get(m?.key)?.type === 'evidence';
+        if ((m?.kind === 'evidence' && m?.type === undefined) || (!kept && (m?.kind ?? m?.type) === 'evidence')) {
+            throw fail(`${from}: items[${i}]${isKey(m?.key) ? ` key ${m.key}` : ''}: evidence is posted one at a time, not in a --from file`, 'VALIDATION_ERROR', 'Post it with sign-off-axi post --kind evidence --from <message.json>');
+        }
+        if (on.has(m?.key))
             return;
         if (m?.contract === undefined && m?.kind === undefined) {
             if (!CONTRACT_TYPES.includes(m?.type ?? 'decision'))
@@ -396,20 +407,20 @@ function printAnswers(file, rows, waiting, values, help) {
     const done = rows.flatMap((d) => (d.answer ? [{ ...d.answer, title: d.title }] : []));
     const rounds = readRounds(file).filter((r) => rows.some((d) => d.key === r.key));
     if (values.json) {
-        const out = Object.fromEntries(done.map(({ key, answer, label, close, at, note }) => {
-            const asked = rounds.filter((r) => r.key === key).map(({ note, at }) => ({ note, at }));
-            return [key, { answer, label, close, at, note, ...(asked.length && { rounds: asked }) }];
-        }));
+        const asked = (key) => rounds.filter((r) => r.key === key).map(({ note, at, comments }) => ({ note, at, comments }));
+        const out = Object.fromEntries(done.map(({ key, answer, label, close, at, note, comments }) => [key, { answer, label, close, at, note, comments, ...(asked(key).length && { rounds: asked(key) }) }]));
         for (const r of rounds)
             if (!out[r.key])
-                out[r.key] = { rounds: rounds.filter((q) => q.key === r.key).map(({ note, at }) => ({ note, at })) };
+                out[r.key] = { rounds: asked(r.key) };
         return JSON.stringify(out);
     }
-    const notes = done.some((a) => a.note);
+    const notes = done.some((a) => a.note), sent = [...done, ...rounds].flatMap(({ key, comments = [] }) => comments.map(({ mock, ref, tag, words, text }) => ({ key, mock, ref, tag, words, text })));
     return toon({
         board: tilde(file),
         answers: done.length ? done.map(({ key, answer, at, label, close, title, note = '' }) => ({ key, answer, at, ...(values.full && { label, close, title }), ...(notes && { note }) })) : '0 saved yet',
         ...(rounds.length && { rounds: rounds.map(({ key, note, at }) => ({ key, note, at })) }),
+        // Comments on mock elements that went with an answer or a round, each with the element it points at.
+        ...(sent.length && { comments: sent }),
         waiting,
     }, help);
 }
@@ -565,7 +576,7 @@ function post(args, cmd = 'post') {
         const size = statSync(actual);
         if (!size.isFile() || size.size > MOCK_BYTES)
             throw fail(`--view ${values.view} must be a file of 5 MB or less`, 'VALIDATION_ERROR');
-        return storeIncoming(file, on, buildIncoming(values, { type, view: values.view }, filer), filer);
+        return storeIncoming(file, on, buildIncoming(values, { type, view: values.view }, filer, file), filer);
     }
     const mocks = values.mock?.map((m) => {
         const at = m.indexOf('=');
@@ -578,7 +589,7 @@ function post(args, cmd = 'post') {
             throw fail(`--mock ${path} escapes the board folder`, 'VALIDATION_ERROR', 'Keep mock files next to the board file');
         return { value: m.slice(0, at), path };
     });
-    return storeIncoming(file, on, buildIncoming(values, { type, tradeoff: values.tradeoff, mocks }, filer), filer);
+    return storeIncoming(file, on, buildIncoming(values, { type, tradeoff: values.tradeoff, mocks }, filer, file), filer);
 }
 /** For a program that feeds the board: the --from file, checked like any post, becomes the whole board, items and top-level fields. Answers stay.
  * With a filer it replaces only that filer's items (and items with no filer it names by key); every other item and top-level field stays. */
@@ -633,9 +644,9 @@ function replace(file, on, from, filer) {
         return toon({ board: tilde(file), items: items.length, changed }, [`Run \`sign-off-axi answers${on}\` to read the answers`]);
     });
 }
-const MEDIA_BYTES = 50_000_000;
-/** Copies the media into evidence/<n>/ next to the board and adds the item, numbered under the board lock: update-<n>, or an explainer under its own key. */
-function postMedia(file, on, values, type, filer) {
+/** Copies the media into evidence/<n>/ next to the board and adds the item, numbered under the board lock: update-<n>, or an explainer under its own key.
+ * `message` is a checked contract evidence message (post --kind evidence): its key, if any, takes only the same message again, and its run is stored as `evidence`. */
+function postMedia(file, on, values, type, filer, message) {
     fits(values.title);
     const explainer = type === 'explainer';
     const extra = (explainer ? ['mock', 'tradeoff', 'view', 'link'] : ['key', 'option', 'recommend', 'default', 'mock', 'tradeoff', 'view', 'chapter']).find((f) => values[f] !== undefined);
@@ -647,7 +658,7 @@ function postMedia(file, on, values, type, filer) {
         throw fail('--about is required for --type evidence: the short note', 'VALIDATION_ERROR', example);
     if (explainer && values.media?.length !== 1)
         throw fail('--type explainer needs one --media video (.mp4 or .webm)', 'VALIDATION_ERROR', example);
-    if (!values.media?.length || values.media.length > MEDIA_MAX)
+    if ((!message && !values.media?.length) || values.media.length > MEDIA_MAX)
         throw fail(`--type evidence needs 1 to ${MEDIA_MAX} --media files`, 'VALIDATION_ERROR', example);
     const kinds = explainer ? ['.mp4', '.webm'] : Object.keys(mediaTypes), options = optionsOf(values);
     recommended([{ options, recommend_value: values.recommend }], true);
@@ -669,10 +680,18 @@ function postMedia(file, on, values, type, filer) {
     });
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     return locked(`${file}.lock`, () => {
-        const items = existsSync(file) ? readItems(file).items : [];
+        const { items, extra } = existsSync(file) ? readItems(file) : { items: [], extra: {} };
         // Boards in one folder share evidence/, so a number is taken only by creating its folder; one in use is never written into.
         const current = board(file), store = join(dirname(file), 'evidence'), taken = current.map((d) => Number(/^update-(\d+)$/.exec(d.key)?.[1] ?? 0));
-        const own = explainer && (values.key ?? slug(values.title));
+        const own = message ? message.key : explainer && (values.key ?? slug(values.title)), had = message && own && items.find((x) => x?.key === own);
+        if (had) {
+            // The stored item, read back as the message it came from: its run, and each media file by hash.
+            const asMessage = ({ type: _t, number: _n, filed: _f, evidence: run, media: kept, ...rest }) => canon({ ...rest, run, media: kept?.map((x) => x.sha256) });
+            if (asMessage(had) !== canon({ ...message, media: sources.length ? sources.map((src) => sha256(readFileSync(src))) : undefined })) {
+                throw fail(`key ${own} already holds a different message on ${tilde(file)}`, 'CONFLICT', 'Post it under a new key');
+            }
+            return toon({ board: tilde(file), posted: [{ key: own, number: had.number, media: sources.length, title: had.title, status: 'already posted' }] }, [`Run \`sign-off-axi open${on}\` so the user can give a verdict`]);
+        }
         if (own && current.some((d) => d.key === own))
             throw fail(`key ${own} is already used on ${tilde(file)}`, 'CONFLICT', 'Post it under a new --key');
         mkdirSync(store, { recursive: true, mode: 0o700 });
@@ -688,17 +707,27 @@ function postMedia(file, on, values, type, filer) {
             }
         }
         const key = own || `update-${number}`, dir = join(store, String(number));
-        const media = sources.map((src, i) => {
-            const bytes = readFileSync(src), path = `evidence/${number}/${i + 1}${extname(src).toLowerCase()}`;
-            writeFileSync(join(dir, `${i + 1}${extname(src).toLowerCase()}`), bytes, { mode: 0o600 });
-            return { path, sha256: sha256(bytes), bytes: bytes.length };
-        });
+        let media;
+        try {
+            media = sources.map((src, i) => {
+                const bytes = readFileSync(src), path = `evidence/${number}/${i + 1}${extname(src).toLowerCase()}`;
+                writeFileSync(join(dir, `${i + 1}${extname(src).toLowerCase()}`), bytes, { mode: 0o600 });
+                return { path, sha256: sha256(bytes), bytes: bytes.length };
+            });
+        }
+        catch (e) {
+            // A file that cannot be read after all leaves no copies behind.
+            rmSync(dir, { recursive: true, force: true });
+            throw e;
+        }
         const { title, about, detail, close, link, recommend: recommend_value, default: default_if_silent } = values, filed = new Date().toISOString();
+        const { run, media: _paths, ...fields } = message ?? {};
         items.push(explainer ? { key, type, title, about, detail, options, recommend_value, default_if_silent, close, chapters, media, filer, filed }
-            : { key, type, number, title, about, detail, close, link, media, filer, filed });
+            : message ? { ...fields, key, type, number, ...(media.length ? { media } : {}), ...(run && { evidence: run }), filed }
+                : { key, type, number, title, about, detail, close, link, media, filer, filed });
         // The whole board is checked before it is written, so a bad post leaves the board and evidence/ as they were.
         const check = `${file}.${process.pid}.check`;
-        writeFileSync(check, JSON.stringify({ schema: 2, items }), { mode: 0o600 });
+        writeFileSync(check, JSON.stringify({ ...extra, schema: 2, items }), { mode: 0o600 });
         try {
             loadDecisions(check);
         }
@@ -712,7 +741,7 @@ function postMedia(file, on, values, type, filer) {
         writeItems(file, items);
         if (explainer)
             return toon({ board: tilde(file), raised: [{ key, status: 'raised', title }] }, [`Run \`sign-off-axi open${on}\` so the user can watch and answer`, waitFor(on, filer, key)]);
-        return toon({ board: tilde(file), posted: [{ key, number, media: media.length, title }] }, [`Run \`sign-off-axi open${on}\` so the user can give a verdict`, waitFor(on, filer, key)]);
+        return toon({ board: tilde(file), posted: [{ key, number, media: media.length, title, ...(message && { status: 'posted' }) }] }, [`Run \`sign-off-axi open${on}\` so the user can give a verdict`, waitFor(on, filer, key)]);
     });
 }
 /** Posts one contract message (docs/contract.md), from a file or from stdin with --from -: checked against --kind, then stored like a raised item. */
@@ -730,9 +759,13 @@ async function postKind(file, on, values) {
     catch (e) {
         throw fail(`${name}: cannot read: ${e.code}`, 'NOT_FOUND', 'Check the path names a readable file');
     }
+    let sources = [];
     try {
         m = parseMessage(bytes);
         checkMessage(m, kind);
+        // Media paths read from the message file's folder, or from the current folder for stdin.
+        if (m.kind === 'evidence')
+            sources = mediaFiles(m, from === '-' ? process.cwd() : dirname(resolve(from)));
     }
     catch (e) {
         throw e instanceof ContractError ? fail(`${name}: ${e.message}`, 'VALIDATION_ERROR', e.help) : e;
@@ -742,6 +775,8 @@ async function postKind(file, on, values) {
     }
     const filer = m.filer ?? filerOf(values, true), scratch = mkdtempSync(join(tmpdir(), 'sign-off-')), source = join(scratch, basename(name));
     try {
+        if (m.kind === 'evidence')
+            return await postMedia(file, on, { title: m.title, about: m.about, media: sources }, 'evidence', filer, { ...m, ...(filer && { filer }) });
         writeFileSync(source, JSON.stringify({ schema: 2, items: [{ ...m, ...(filer && { filer }) }] }));
         return await storeIncoming(file, on, buildIncoming({ from: source }, {}, filer, file), filer, true);
     }
@@ -782,7 +817,10 @@ function validate(args) {
         }
         try {
             m = parseMessage(raw);
-            return { file, ...checkMessage(m, want), ok: true, error: '', help: '' };
+            const kind = checkMessage(m, want);
+            if (m.kind === 'evidence')
+                mediaFiles(m, dirname(resolve(file)));
+            return { file, ...kind, ok: true, error: '', help: '' };
         }
         catch (e) {
             if (!(e instanceof ContractError))
@@ -810,13 +848,14 @@ function recommended(items, flags) {
     if (d)
         throw fail(`items[${items.indexOf(d)}] (key ${d.key}) lists options but no recommend_value`, 'VALIDATION_ERROR', `Add "recommend_value": "<value>", the option you would pick: one of ${values}`);
 }
-/** Flags are validated by the same loader as a file: write them as a one-decision file first. */
-function buildIncoming(values, extra = {}, filer, file = '') {
+/** Flags are validated by the same loader as a file: write them as a one-decision file first. Items are checked against the board they go to, so its answers_only or readonly holds. */
+function buildIncoming(values, extra, filer, file) {
+    const board = existsSync(file) ? readItems(file).extra : {};
     if (values.from !== undefined) {
         // An item that names its own filer keeps it.
         const source = resolve(values.from), raw = readItems(source).items;
         contractItems(raw, values.from, file);
-        const incoming = loadDecisions(source);
+        const incoming = loadDecisions(source, board);
         recommended(raw, false);
         return { incoming: incoming.map((d) => ({ filer, ...d })), raw: raw.map((i) => ({ filer, ...i })) };
     }
@@ -825,7 +864,7 @@ function buildIncoming(values, extra = {}, filer, file = '') {
     try {
         const { title, key = slug(title), about, detail, recommend: recommend_value, default: default_if_silent, close } = values;
         writeFileSync(source, JSON.stringify({ schema: 2, items: [{ key, title, about, detail, options: optionsOf(values), recommend_value, default_if_silent, close, ...extra, filer }] }));
-        const incoming = loadDecisions(source), raw = readItems(source).items;
+        const incoming = loadDecisions(source, board), raw = readItems(source).items;
         recommended(raw, true);
         return { incoming, raw };
     }
@@ -850,7 +889,11 @@ function storeIncoming(file, on, { incoming, raw }, filer, exact = false) {
             // A message that names no filed time matches the one the board stamped.
             const differs = () => exact ? canon({ ...items.find((x) => x?.key === d.key), ...(raw[i].filed === undefined && { filed: undefined }) }) !== canon(raw[i]) : same(had) !== same(d);
             if (had && differs()) {
-                throw fail(`key ${d.key} already holds a different ${exact ? 'message' : 'question'} on ${tilde(file)}`, 'CONFLICT', 'Raise it under a new --key');
+                // A contract message refused for its key exits 2 like any other refusal (contract section 4); raise --title keeps exit 1.
+                const contract = exact || raw[i]?.contract !== undefined || raw[i]?.kind !== undefined;
+                if (contract)
+                    process.once('exit', () => { process.exitCode = 2; });
+                throw fail(`key ${d.key} already holds a different ${contract ? 'message' : 'question'} on ${tilde(file)}`, 'CONFLICT', contract ? 'Post it under a new key' : 'Raise it under a new --key');
             }
             // Each new item records when it was raised, unless it names its own time.
             if (!had) {
@@ -1473,7 +1516,9 @@ const page = readFileSync(new URL('../web/index.html', import.meta.url));
 const pointer = Buffer.from(`<script>${readFileSync(new URL('../web/point.js', import.meta.url), 'utf8')}</script>`);
 const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const state = () => {
-    const answers = readAnswers(file, warn), taken = seenBy(file), rounds = readRounds(file, warn);
+    // The page marks sent comments in annotations, so answers and rounds go without theirs: a read-only board or an export carries none.
+    const answers = Object.fromEntries(Object.entries(readAnswers(file, warn)).map(([k, { comments: _, ...a }]) => [k, a])), taken = seenBy(file);
+    const rounds = readRounds(file, warn).map(({ comments: _, ...r }) => r);
     return {
         file,
         mockBase: `/mock/${loopback(bind) ? 'local' : mockPass(tokenOf(file))}/`,
@@ -1486,7 +1531,7 @@ const state = () => {
         seen: Object.values(answers).filter(taken).map((a) => a.key),
         rounds,
         messages: readMessages(file, warn),
-        annotations: readOnly() || answersOnly() ? [] : readAnnotations(file, warn),
+        annotations: readOnly() || answersOnly() ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
         dismissed: readDismissed(file, answers, rounds, warn),
     };
 };
@@ -1498,6 +1543,12 @@ const mockHash = (path) => { try {
 catch {
     return null;
 } };
+/** The comments that go with a card's next answer or round: not sent yet, and made on the mock file the card shows now. */
+const unsent = (d) => {
+    const sent = sentIds(file), now = new Map((d.mocks ?? []).map((m) => [m.value, mockHash(m.path)]));
+    return answersOnly() ? [] : readAnnotations(file).filter((a) => a.key === d.key && !sent.has(a.id) && now.get(a.mock) === a.hash)
+        .map(({ id, mock, hash, ref, tag, words, text }) => ({ id, mock, hash, ref, tag, words, text }));
+};
 /** A board whose file says `"readonly": true` shows its items and takes no answers, rounds or comments: another program feeds it. */
 const readOnly = () => readItems(file).extra.readonly === true;
 /** A board whose file says `"answers_only": true` takes answers and replies but no rounds, comments or prompts: another program feeds it. */
@@ -1656,7 +1707,10 @@ async function route(req) {
         return [200, state()];
     }
     if (req.url === '/api/annotations') {
-        const { id, deleted, key, mock, ref, tag, words, text, hash: shown } = JSON.parse(body) ?? {}, live = readAnnotations(file);
+        const { id, deleted, key, mock, ref, tag, words, text, hash: shown } = JSON.parse(body) ?? {}, live = readAnnotations(file), sent = sentIds(file);
+        // A comment that went with an answer or a round is the agent's now: it stays as it was sent.
+        if (id !== undefined && sent.has(id))
+            return [409, { error: 'This comment was sent' }];
         if (deleted === true) {
             if (!live.some((a) => a.id === id))
                 return [404, { error: 'This comment is gone' }];
@@ -1678,7 +1732,7 @@ async function route(req) {
         if (id !== undefined && !live.some((a) => a.id === id))
             return [404, { error: 'This comment is gone' }];
         // One comment per element: another on the same element of the same file edits the first.
-        const same = live.find((a) => a.key === key && a.mock === mock && a.hash === hash && a.ref === ref);
+        const same = live.find((a) => a.key === key && a.mock === mock && a.hash === hash && a.ref === ref && !sent.has(a.id));
         appendAnnotation(file, { id: same?.id, key, mock, hash, ref, tag, words, text: text.trim() });
         return [200, state()];
     }
@@ -1696,11 +1750,14 @@ async function route(req) {
         const { key, note = '' } = JSON.parse(body) ?? {};
         if (typeof note !== 'string' || [...note.trim()].length > NOTE_MAX)
             return [400, { error: `The note must be text of ${NOTE_MAX} characters or fewer` }];
-        if (!note.trim())
-            return [400, { error: 'Write a note first: another round needs your comment' }];
-        if (!loadDecisions(file).some((x) => x.key === key))
+        const d = loadDecisions(file).find((x) => x.key === key);
+        if (!d)
             return [404, { error: 'This question is no longer in the file' }];
-        appendRound(file, key, note.trim());
+        // Comments on the mocks are enough for a round; with none, the round needs a note.
+        const comments = unsent(d);
+        if (!note.trim() && !comments.length)
+            return [400, { error: 'Write a note first: another round needs your comment' }];
+        appendRound(file, key, note.trim(), comments);
         return [200, state()];
     }
     const { key, answer, note = '' } = JSON.parse(body) ?? {};
@@ -1727,7 +1784,7 @@ async function route(req) {
     const other = d.reply || d.options.length ? [REPLY] : [], option = d.options.find((o) => o.value === answer) ?? other.find((o) => o.value === answer);
     if (!option)
         return [400, { error: `The answer must be one of: ${[...d.options, ...other].map((o) => o.label).join(', ') || 'none, this item is only shown'}` }];
-    answered(appendAnswer(file, d, option, note.trim()), d);
+    answered(appendAnswer(file, d, option, note.trim(), unsent(d)), d);
     return [200, state()];
 }
 /** Runs the config's on_answer command for a saved answer, with no shell: the answer goes in as one JSON line on its stdin, never in its arguments. */

package/dist/contract.js

@@ -1,5 +1,7 @@
 // The v1 communication contract (docs/contract.md): one strict, versioned shape per kind of message.
-import { isKey } from './store.js';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { isKey, MEDIA_MAX } from './store.js';
 /** A message that does not match: what is wrong, and the one line that says how to fix it. */
 export class ContractError extends Error {
     help;
@@ -10,12 +12,16 @@ export class ContractError extends Error {
 }
 export const KINDS = ['ask', 'report', 'evidence', 'gate', 'finding'];
 /** The kinds this build checks, with the schema number of each. */
-export const SCHEMAS = { ask: 1, report: 1 };
+export const SCHEMAS = { ask: 1, report: 1, evidence: 1 };
 const COMMON = ['contract', 'kind', 'schema', 'key', 'title', 'filer', 'link', 'about'];
 const FIELDS = {
     ask: [...COMMON, 'detail', 'options', 'recommend_value', 'default_if_silent', 'close'],
     report: [...COMMON, 'filed', 'group', 'decided'],
+    evidence: [...COMMON, 'media', 'run'],
 };
+/** A done-done run: its id, full commit and the four Checks lines. */
+const RUN = ['run_id', 'commit', 'outcome', 'repro', 'proof', 'evidence'];
+export const MEDIA_BYTES = 50_000_000;
 /** Parses one message; a field written twice in any object refuses it, since plain JSON.parse keeps the last one quietly. */
 export function parseMessage(bytes) {
     let text, doc;
@@ -104,9 +110,9 @@ export function checkMessage(m, want) {
     const fields = FIELDS[m.kind], extra = Object.keys(m).find((f) => !fields.includes(f));
     if (extra === 'options' && m.kind === 'report')
         throw bad('options', 'is not a field of report: a report takes no answer', 'Remove "options", or post an ask to get an answer');
-    if (extra)
-        throw bad(escaped(extra), `is not a field of ${m.kind} schema ${m.schema}`, `Remove ${show(extra)}; ${m.kind} takes ${fields.slice(3).join(', ')}`);
-    if (!isKey(m.key))
+    if (extra !== undefined)
+        throw bad(escaped(extra) || '""', `is not a field of ${m.kind} schema ${m.schema}`, `Remove ${show(extra)}; ${m.kind} takes ${fields.slice(3).join(', ')}`);
+    if (!(m.kind === 'evidence' && !Object.hasOwn(m, 'key')) && !isKey(m.key))
         throw bad('key', Object.hasOwn(m, 'key') ? `${show(m.key)} must be 1-128 of A-Z a-z 0-9 . _ -` : 'is required', 'Set "key" to a short id such as "ship-signin-2"');
     if (!Object.hasOwn(m, 'title'))
         throw bad('title', 'is required', 'Add "title": the question, in 160 characters or fewer');
@@ -116,10 +122,46 @@ export function checkMessage(m, want) {
     if (Object.hasOwn(m, 'link') && !(typeof m.link === 'string' && /^(https?:\/\/[^\s\p{Cc}\p{Cs}]{1,500}|[a-f0-9]{7,40})$/u.test(m.link))) {
         throw bad('link', 'must be an http(s) link with no spaces or control characters, or a 7-40 character commit hash', 'Set "link" to a URL such as "https://example.com/pr/4" or a commit hash, or leave it out');
     }
-    if (m.kind === 'report') {
+    if (m.kind !== 'ask') {
+        const what = m.kind === 'report' ? 'what happened' : 'what this shows';
         if (!Object.hasOwn(m, 'about'))
-            throw bad('about', 'is required', 'Add "about": what happened, in 500 characters or fewer');
-        text('about', m.about, 500, 'what happened, in 500 characters or fewer');
+            throw bad('about', 'is required', `Add "about": ${what}, in 500 characters or fewer`);
+        text('about', m.about, 500, `${what}, in 500 characters or fewer`);
+    }
+    if (m.kind === 'evidence') {
+        if (!Object.hasOwn(m, 'media') && !Object.hasOwn(m, 'run'))
+            throw bad('media', 'or run is required', 'Add "media": ["shot.png"], files next to the message, or "run": the done-done run it proves');
+        if (Object.hasOwn(m, 'media')) {
+            if (!Array.isArray(m.media) || !m.media.length || m.media.length > MEDIA_MAX)
+                throw bad('media', `must list 1 to ${MEDIA_MAX} files`, 'Set "media" to file paths next to the message, such as ["shot.png"]');
+            m.media.forEach((p, n) => {
+                text(`media[${n}]`, p, 1000, 'a file path from the message file\'s folder, such as "shot.png"');
+                if (/^([\\/]|[A-Za-z]:)/.test(p) || p.split(/[\\/]/).includes('..'))
+                    throw bad(`media[${n}]`, `${show(p)} must be a relative path with no ..`, 'Give the path from the message file\'s folder, such as "evidence-out/after.png"');
+                if (!/\.(png|jpe?g|webp|mp4|webm)$/i.test(p))
+                    throw bad(`media[${n}]`, `${show(p)} must end in .png, .jpg, .jpeg, .webp, .mp4 or .webm`, 'Post a screenshot or recording in one of those formats');
+            });
+        }
+        if (Object.hasOwn(m, 'run')) {
+            const r = m.run;
+            if (!r || typeof r !== 'object' || Array.isArray(r))
+                throw bad('run', 'must be an object', `Set "run" to {${RUN.map(show).join(', ')}}`);
+            const odd = Object.keys(r).find((f) => !RUN.includes(f));
+            if (odd !== undefined)
+                throw bad(`run.${escaped(odd) || '""'}`, 'is not a field of run', `Remove ${show(odd)}; run has only ${RUN.join(', ')}`);
+            const missing = RUN.find((f) => !Object.hasOwn(r, f));
+            if (missing)
+                throw bad(`run.${missing}`, 'is required', `Add "${missing}" to "run"`);
+            if (!isKey(r.run_id))
+                throw bad('run.run_id', 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "run_id" to the done-done run id');
+            if (!(typeof r.commit === 'string' && /^[a-f0-9]{40}$/.test(r.commit)))
+                throw bad('run.commit', 'must be a full 40-character lowercase commit', 'Set "commit" to the full hash, such as the output of git rev-parse HEAD');
+            for (const f of RUN.slice(2))
+                text(`run.${f}`, r[f], 1000, `the run's ${f} Checks line, in 1000 characters or fewer`);
+        }
+        return { kind: m.kind, schema: m.schema };
+    }
+    if (m.kind === 'report') {
         // An exact UTC second that exists on the calendar: Date.parse would roll 2026-02-30 over to March.
         const at = typeof m.filed === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(m.filed) ? new Date(m.filed) : undefined;
         if (!at || Number.isNaN(at.getTime()) || at.toISOString().replace('.000', '') !== m.filed) {
@@ -144,8 +186,8 @@ export function checkMessage(m, want) {
         if (!o || typeof o !== 'object' || Array.isArray(o))
             throw bad(field, 'must be an object', 'Write each option as {"value":"<id>","label":"<text>"}');
         const odd = Object.keys(o).find((f) => f !== 'value' && f !== 'label');
-        if (odd)
-            throw bad(`${field}.${escaped(odd)}`, 'is not a field of an option', `Remove ${show(odd)}; an option has only value and label`);
+        if (odd !== undefined)
+            throw bad(`${field}.${escaped(odd) || '""'}`, 'is not a field of an option', `Remove ${show(odd)}; an option has only value and label`);
         if (!isKey(o.value))
             throw bad(`${field}.value`, 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "value" to a short id such as "yes"');
         if (options.slice(0, n).some((p) => p.value === o.value))
@@ -164,3 +206,35 @@ export function checkMessage(m, want) {
         throw bad('close', 'must be done or release', 'Set "close" to "done" or "release", or leave it out');
     return { kind: m.kind, schema: m.schema };
 }
+/** An evidence message's media files, from `base`, the message file's folder: each a file of 50,000,000 bytes or fewer whose real path,
+ * symlinks followed, stays inside that folder. Returns the real paths; validate checks them and copies nothing. */
+export function mediaFiles(m, base) {
+    const root = realpathSync(base), at = isKey(m.key) ? `key ${m.key}: ` : '';
+    return (m.media ?? []).map((p, n) => {
+        const bad = (rule, help) => new ContractError(`${at}media[${n}] ${show(p)} ${rule}`, help);
+        let real;
+        try {
+            real = realpathSync(resolve(root, p));
+        }
+        catch {
+            throw bad('is not there', `Put ${p} in the message file's folder, or fix the path`);
+        }
+        const rel = relative(root, real);
+        if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel))
+            throw bad('leads outside the message file\'s folder', 'Copy the file into the message file\'s folder instead of linking to it');
+        const info = statSync(real);
+        if (!info.isFile())
+            throw bad('is not a file', 'Name a screenshot or recording file');
+        if (!/\.(png|jpe?g|webp|mp4|webm)$/i.test(real))
+            throw bad('links to a file that does not end in .png, .jpg, .jpeg, .webp, .mp4 or .webm', 'Name the screenshot or recording itself');
+        try {
+            accessSync(real, constants.R_OK);
+        }
+        catch {
+            throw bad('cannot be read', 'Make the file readable, then post again');
+        }
+        if (info.size > MEDIA_BYTES)
+            throw bad(`is over ${MEDIA_BYTES} bytes`, 'Trim or compress the recording');
+        return real;
+    });
+}

package/dist/store.js

@@ -56,8 +56,9 @@ export function writeItems(path, items, extra) {
     writeFileSync(tmp, `${JSON.stringify({ ...(extra ?? old?.extra), schema: 2, items }, null, 2)}\n`, { mode: 0o600 });
     renameSync(tmp, path);
 }
-export function loadDecisions(path) {
-    const name = basename(path), { schema, items, extra } = readItems(path), list = schema === 1 ? 'decisions' : 'items';
+/** `board`: the top-level fields of the board the items are posted to, which decide in place of the file's own. */
+export function loadDecisions(path, board) {
+    const name = basename(path), { schema, items, extra: own } = readItems(path), list = schema === 1 ? 'decisions' : 'items', extra = board ?? own;
     const fed = extra.readonly === true || extra.answers_only === true;
     const seen = new Map();
     return items.map((d, i) => {
@@ -76,7 +77,7 @@ export function loadDecisions(path) {
                 throw bad(f, 'must be text');
         if (d.evidence !== undefined && (!d.evidence || !/^[A-Za-z0-9._-]{1,128}$/.test(d.evidence.run_id ?? '')
             || !/^[a-f0-9]{40}$/.test(d.evidence.commit ?? '')
-            || ['outcome', 'repro', 'proof', 'evidence'].some((f) => !isText(d.evidence[f]) || !d.evidence[f].trim() || d.evidence[f].length > 1000))) {
+            || ['outcome', 'repro', 'proof', 'evidence'].some((f) => !isText(d.evidence[f]) || !d.evidence[f].trim() || [...d.evidence[f]].length > 1000))) {
             throw bad('evidence', 'must name a done-done run, full commit, and four Checks lines');
         }
         // Any lowercase type word loads; the page shows a plain card for a type it has no renderer for.
@@ -86,7 +87,8 @@ export function loadDecisions(path) {
             if (d[f] !== undefined && !allowed.includes(d[f]))
                 throw bad(f, `must be ${allowed.join(' or ')}`);
         const stored = Object.hasOwn(STORED, d.type ?? '') ? STORED[d.type] : undefined;
-        if (stored) {
+        // An evidence update that links a done-done run may have no files of its own (contract evidence with run only).
+        if (stored && !(d.type === 'evidence' && d.media === undefined && d.evidence)) {
             const [max, kinds, ext] = stored;
             if (!Array.isArray(d.media) || !d.media.length || d.media.length > max || !d.media.every((m) => isText(m?.path)
                 && /^evidence\/\d+\/\w[\w-]*\.\w+$/.test(m.path) && ext.test(m.path) && /^[a-f0-9]{64}$/.test(m.sha256 ?? '') && Number.isInteger(m.bytes) && m.bytes >= 0)) {
@@ -161,7 +163,7 @@ export function loadDecisions(path) {
             ...(views && { view: d.view }), ...(d.reply && { reply: true }), ...(d.filer && { filer: d.filer }), ...(d.area && { area: d.area }),
             ...(d.group && { group: d.group }), ...(d.filed && { filed: d.filed }), ...(d.decided && { decided: d.decided }),
             ...(d.steps && { steps: d.steps.map(({ title, marks }) => ({ title, ...(marks?.length && { marks }) })) }),
-            ...(stored && { media: d.media.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })) }),
+            ...(stored && d.media && { media: d.media.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })) }),
             ...(d.type === 'evidence' && { number: d.number }),
             ...(d.type === 'explainer' && d.chapters && { chapters: d.chapters.map(({ at, title }) => ({ at, title })) }),
         };
@@ -172,29 +174,32 @@ export const roundsPath = (decisionsPath) => decisionsPath.replace(/\.json$/, ''
 const readRaw = (file) => (existsSync(file) ? readFileSync(file, 'utf8') : '');
 /** Latest answer per key; a line with an empty answer (an Undo with nothing to go back to) leaves the key unanswered. A torn line (a crash mid-write) is skipped and reported through warn. */
 export function readAnswers(decisionsPath, warn = () => { }) {
-    const latest = new Map();
+    const latest = new Map(), sent = new Map();
     readRaw(answersPath(decisionsPath)).split('\n').forEach((line, n) => {
         try {
             const a = line && JSON.parse(line);
             if (a?.answer === '')
                 latest.delete(a.key);
-            else if (a)
+            else if (a) {
                 latest.set(a.key, a);
+                if (a.comments)
+                    sent.set(a.key, [...(sent.get(a.key) ?? []), ...a.comments]);
+            }
         }
         catch {
             warn(`skipped unreadable line ${n + 1} in ${answersPath(decisionsPath)}`);
         }
     });
-    return Object.fromEntries(latest);
+    return Object.fromEntries([...latest].map(([key, a]) => [key, sent.has(key) ? { ...a, comments: sent.get(key) } : a]));
 }
 /** The option an Undo saves when the item had no answer before: an empty answer, so the item waits again. */
 export const CLEARED = { value: '', label: '' };
 /** Appends one answer line unless it equals the current answer and note, and returns the saved answer. Starts a new line after a torn fragment. */
-export function appendAnswer(decisionsPath, d, option, note = '') {
+export function appendAnswer(decisionsPath, d, option, note = '', comments = []) {
     const current = readAnswers(decisionsPath)[d.key];
-    if (option === CLEARED ? !current : current?.answer === option.value && (current.note ?? '') === note)
+    if (option === CLEARED ? !current : current?.answer === option.value && (current.note ?? '') === note && !comments.length)
         return;
-    const answer = { key: d.key, answer: option.value, label: option.label, close: d.close, at: now(), ...(note && { note }) };
+    const answer = { key: d.key, answer: option.value, label: option.label, close: d.close, at: now(), ...(note && { note }), ...(comments.length && { comments }) };
     appendLine(answersPath(decisionsPath), answer);
     return answer;
 }
@@ -235,10 +240,20 @@ export function readRounds(decisionsPath, warn = () => { }) {
     });
     return rounds;
 }
-/** Asks the agent for another round on a question, carrying the person's note. */
-export function appendRound(decisionsPath, key, note) {
-    appendLine(roundsPath(decisionsPath), { key, note, at: now() });
+/** Asks the agent for another round on a question, carrying the person's note and the comments on its mocks. */
+export function appendRound(decisionsPath, key, note, comments = []) {
+    appendLine(roundsPath(decisionsPath), { key, note, at: now(), ...(comments.length && { comments }) });
 }
+/** Ids of the comments that went with an answer or a round: sent, so locked. */
+export const sentIds = (decisionsPath) => new Set([answersPath, roundsPath].flatMap((path) => readRaw(path(decisionsPath)).split('\n').flatMap((line) => {
+    try {
+        const c = line && JSON.parse(line)?.comments;
+        return Array.isArray(c) ? c.map((x) => x?.id) : [];
+    }
+    catch {
+        return [];
+    }
+})));
 /** Items hidden from the board, one line per key and change; the agent is not told, and an ask it waits on keeps waiting. */
 export const dismissedPath = (decisionsPath) => decisionsPath.replace(/\.json$/, '') + '.dismissed.jsonl';
 export function appendDismissed(decisionsPath, keys, dismissed) {

package/fixtures/contract/README.md

@@ -9,7 +9,7 @@ fixtures/contract/<kind>.v<schema>/valid-<name>.json
 fixtures/contract/<kind>.v<schema>/invalid-<field>-<rule>.json
 ```
 
-- `<kind>` is `ask`, `report`, `evidence`, `gate` or `finding`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/` and `report.v1/`.
+- `<kind>` is `ask`, `report`, `evidence`, `gate` or `finding`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/`, `report.v1/` and `evidence.v1/`.
 - Each file holds one message. An evidence fixture that names `media` ships those files next to it.
 - Each kind has at least 2 valid files and 3 invalid ones: one with a required field missing, one over a limit, and one with an unknown field.
 - An invalid file breaks exactly one rule. Its name gives the field and the rule, such as `invalid-title-too-long.json`, and sign-off's own tests check that the refusal names that field.

package/fixtures/contract/evidence.v1/invalid-about-missing.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567","outcome":"Umer can see the updated sign-in screen.","repro":"repro: n/a: no bug","proof":"verify-sign-off: real browser journey","evidence":"after.png"}}

package/fixtures/contract/evidence.v1/invalid-commit-short.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","about":"Umer signs in on a phone. The screen loads in 1 second.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456","outcome":"Umer can see the updated sign-in screen.","repro":"repro: n/a: no bug","proof":"verify-sign-off: real browser journey","evidence":"after.png"}}

package/fixtures/contract/evidence.v1/invalid-detail-unknown.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","about":"Umer signs in on a phone. The screen loads in 1 second.","detail":"More words.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567","outcome":"Umer can see the updated sign-in screen.","repro":"repro: n/a: no bug","proof":"verify-sign-off: real browser journey","evidence":"after.png"}}

package/fixtures/contract/evidence.v1/invalid-media-not-there.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","about":"Umer signs in on a phone. The screen loads in 1 second.","media":["gone.png"]}

package/fixtures/contract/evidence.v1/invalid-media-parent-path.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","about":"Umer signs in on a phone. The screen loads in 1 second.","media":["../shot.png"]}

package/fixtures/contract/evidence.v1/invalid-media-too-many.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"key":"too-many","title":"Sign-in screen, second pass","about":"Umer checks the new layout.","media":["shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png","shot.png"],"link":"https://example.com/pr/4"}

package/fixtures/contract/evidence.v1/valid-media.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"key":"signin-phone-2","title":"Sign-in screen, second pass","about":"Umer checks the new layout.","media":["shot.png"],"link":"https://example.com/pr/4"}

package/fixtures/contract/evidence.v1/valid-run.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"evidence","schema":1,"title":"Sign-in screen on a phone","filer":"done-done","about":"Umer signs in on a phone. The screen loads in 1 second.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567","outcome":"Umer can see the updated sign-in screen.","repro":"repro: n/a: no bug","proof":"verify-sign-off: real browser journey","evidence":"after.png"}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "One review board for evidence, quick yes/no decisions and retro changes.",
   "type": "module",
   "bin": { "sign-off-axi": "dist/cli.js" },

package/web/index.html

@@ -133,10 +133,11 @@
   .sec-head { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; }
   .sec-head h2 { margin: 0; } .sec-head:has(+ .in-evidence) { margin: 1rem 0 0.375rem; }
   .rows { list-style: none; margin: 0; padding: 0 1rem; }
-  .rows li + li { border-top: 1px solid var(--line); }
+  .rows > li + li { border-top: 1px solid var(--line); }
   .compact { display: flex; align-items: center; gap: 0.75rem; padding: 0.75rem 0; color: var(--text); text-decoration: none; }
   .compact .t { display: grid; flex: 1; min-width: 0; }
-  .ans { display: grid; justify-items: end; text-align: right; } .ans b { color: var(--c-answered); } .ans time { color: var(--muted); font-size: 0.875rem; }
+  /* The answer sits under the title, never beside it: a long answer beside the title squeezed it to a letter a line. */
+  .ans { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0 0.5rem; margin-top: 0.125rem; } .ans b { color: var(--c-answered); } .ans time { color: var(--muted); font-size: 0.875rem; }
   .compact strong { font-size: 1.0625rem; font-weight: 600; line-height: 1.3; }
   .compact .meta { margin: 0.125rem 0 0; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
   .thumb, .compact .icon { width: 3.5rem; height: 3.5rem; border-radius: 0.625rem; }
@@ -238,7 +239,7 @@
     background: none; color: var(--muted); font-size: 1.5rem; line-height: 1.25; }
   .x:hover { background: var(--sunk); color: var(--text); }
   .head .st + .x { margin-left: 0; }
-  .rows li { display: flex; align-items: center; }
+  .rows > li { display: flex; align-items: center; }
   .rows li .compact { flex: 1; min-width: 0; }
   .rows li .x { margin: 0; }
   .clear { min-height: 2.75rem; padding: 0; border: 0; background: none; color: var(--accent); font-weight: 600; }
@@ -340,8 +341,8 @@
     .reports { grid-template-columns: 1fr 1fr; align-items: start; }
     /* Answered sets each row as its own card, two across; an opened row takes the whole width. */
     .rows.i-answered { display: grid; grid-template-columns: 1fr 1fr; gap: 0.75rem; align-items: start; padding: 0; border: 0; background: none; box-shadow: none; }
-    .rows.i-answered li { padding: 0 0.5rem 0 1rem; border: 1px solid var(--line); border-radius: 1rem; background: var(--surface); box-shadow: var(--shadow); }
-    .rows.i-answered li:has(.done[open]) { grid-column: 1 / -1; }
+    .rows.i-answered > li { padding: 0 0.5rem 0 1rem; border: 1px solid var(--line); border-radius: 1rem; background: var(--surface); box-shadow: var(--shadow); }
+    .rows.i-answered > li:has(.done[open]) { grid-column: 1 / -1; }
     .upd.portrait > .media { width: 8rem; }
     /* Evidence sets its updates two across; a page that is not an update keeps the whole width. */
     .list.in-evidence { grid-template-columns: 1fr 1fr; align-items: start; } .in-evidence > .row:not(.update) { grid-column: 1 / -1; }
@@ -393,7 +394,7 @@
     const drop = clearIfSaved(d.key, drafts.get(d.key));
     call('/api/answers', {
       method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, answer: o.value, note }),
-    }, typed ? undefined : drop).then(() => offerUndo(d, before)).then(() => typed && call('/api/messages', {
+    }, () => { editing.delete(d.key); if (!typed) drop(); }).then(() => offerUndo(d, before)).then(() => typed && call('/api/messages', {
       method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'comment', key: d.key, text: typed }),
     }, drop)).catch((e) => {
       shown(err).textContent = `Couldn't save: ${e.message}`;
@@ -562,9 +563,10 @@
     roundBtn.onclick = () => {
       roundBtn.disabled = true;
       const note = (drafts.get(d.key) ?? noteOf(d)).trim();
+      const drop = clearIfSaved(d.key, drafts.get(d.key));
       call('/api/rounds', {
         method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, note }),
-      }, clearIfSaved(d.key, drafts.get(d.key))).catch((e) => {
+      }, () => { editing.delete(d.key); drop(); }).catch((e) => {
         shown(err).textContent = `Couldn't ask: ${e.message}`;
         roundBtn.disabled = false;
       });
@@ -580,7 +582,7 @@
     const hint = !d.options.length ? 'Reply in a few words' : words ? `Your own answer in a few words. It also goes, as a note, ${also}.` : `A note, sent ${also}.`;
     const fold = el('details', { class: 'other', ...((unfolded.has(d.key) || drafts.get(d.key)) && { open: '' }) },
       el('summary', { 'aria-label': `${label}, ${d.title}` }, `${label}${status && ` · ${status}`}`),
-      asked.length ? el('p', { class: 'meta saved-note', dir: 'auto' }, `You asked for another round: ${asked[asked.length - 1].note}`) : '',
+      asked.length ? el('p', { class: 'meta saved-note', dir: 'auto' }, `You asked for another round: ${asked[asked.length - 1].note || 'with your comments on the mocks'}`) : '',
       ...comments.map((m) => el('p', { class: 'meta saved-note', dir: 'auto' }, `Your comment, ${m.delivered ? 'read by the agent' : 'not read yet'}: ${m.text}`)),
       el('label', { for: box.id }, hint), box,
       el('div', { class: 'actions' }, words ? sendBtn : '', round ? roundBtn : '', talk && !FROZEN ? commentBtn : ''));
@@ -668,16 +670,16 @@
     }));
   }
 
-  /** Comments on mock elements, not sent yet: the open editor per item, then the list, each comment shown only on the mock file it was made on. */
+  /** Comments on mock elements: the open editor per item, then the unsent list, then the sent ones. An unsent comment shows only on the mock file it was made on. */
   const editing = new Map(), talks = () => !state.readonly && !state.answers_only && !FROZEN;
   const redraw = (d) => document.querySelectorAll('.ann').forEach((n) => n.dataset.ann === d.key && n.replaceWith(annotations(d)));
   function annotations(d) {
     const hash = new Map((d.mocks ?? []).map((m) => [m.value, m.hash])), open = editing.get(d.key);
-    // A comment shows only on the mock file it was made on; the others are counted per mock.
+    // An unsent comment shows only on the mock file it was made on; the others are counted per mock. A sent one is always listed.
     const mine = [], old = new Map(), name = (m) => d.options.find((o) => o.value === m)?.label ?? m;
     for (const a of state.annotations ?? []) {
       if (a.key !== d.key) continue;
-      if (hash.get(a.mock) === a.hash) mine.push(a);
+      if (a.sent || hash.get(a.mock) === a.hash) mine.push(a);
       else old.set(a.mock, (old.get(a.mock) ?? 0) + 1);
     }
     const what = (a) => `${name(a.mock)} · ${a.tag}${a.words ? ` “${a.words.length > 40 ? `${a.words.slice(0, 40)}…` : a.words}”` : ''}`;
@@ -702,20 +704,24 @@
     let form = '';
     if (open && pages.length) {
       const box = el('textarea', { id: `ann-text-${d.key}`, rows: 2, maxlength: 500, dir: 'auto' }), save = el('button', {}, 'Save comment'), cancel = el('button', { class: 'quick' }, 'Cancel');
-      box.value = open.text ?? mine.find((a) => a.mock === open.mock && a.ref === open.ref)?.text ?? '';
+      box.value = open.text ?? mine.find((a) => !a.sent && a.mock === open.mock && a.ref === open.ref)?.text ?? '';
       box.oninput = () => (open.text = box.value);
       save.onclick = () => post(save, { id: open.id, key: d.key, mock: open.mock, ref: open.ref, tag: open.tag, words: open.words, text: box.value, hash: open.hash }, () => editing.delete(d.key));
       cancel.onclick = () => { editing.delete(d.key); redraw(d); };
       form = el('div', {}, el('label', { for: box.id }, `Comment on ${what(open)}`), box, el('div', { class: 'actions' }, save, cancel));
     }
-    const rows = mine.map((a) => {
+    const row = (a, ...buttons) => el('li', {}, el('div', {}, el('p', { class: 'meta' }, what(a)), el('p', { class: 'saved-note', dir: 'auto' }, a.text)), ...buttons);
+    // A comment goes with the card's next answer or round; once sent it is the agent's and stays as it was.
+    const sent = mine.filter((a) => a.sent).map((a) => row(a));
+    const rows = mine.filter((a) => !a.sent).map((a) => {
       const edit = el('button', { class: 'quick', 'aria-label': `Edit comment, ${what(a)}` }, 'Edit'), del = el('button', { class: 'quick', 'aria-label': `Delete comment, ${what(a)}` }, 'Delete');
       edit.onclick = () => { editing.set(d.key, { ...a }); redraw(d); };
       del.onclick = () => post(del, { id: a.id, deleted: true }, () => { if (editing.get(d.key)?.mock === a.mock && editing.get(d.key)?.ref === a.ref) editing.delete(d.key); });
-      return el('li', {}, el('div', {}, el('p', { class: 'meta' }, what(a)), el('p', { class: 'saved-note', dir: 'auto' }, a.text)), el('span', { class: 'actions' }, edit, del));
+      return row(a, el('span', { class: 'actions' }, edit, del));
     });
     return el('div', { class: 'ann', 'data-ann': d.key }, pages.length ? el('div', { class: 'actions' }, toggle) : '',
-      on ? el('p', { class: 'meta' }, 'Tap an element in a mock to comment on it. Turn this off to open a mock full size.') : '', form, rows.length ? el('p', { class: 'meta' }, 'Your comments on the mocks, not sent yet') : '', rows.length ? el('ul', {}, ...rows) : '',
+      on ? el('p', { class: 'meta' }, 'Tap an element in a mock to comment on it. Turn this off to open a mock full size.') : '', form, ...(rows.length ? [el('p', { class: 'meta' }, 'Your comments on the mocks, not sent yet'), el('ul', {}, ...rows), el('p', { class: 'meta' }, 'They go with your pick, your Other answer or Another round.')] : []),
+      ...(sent.length ? [el('p', { class: 'meta' }, 'Sent to the agent'), el('ul', {}, ...sent)] : []),
       ...[...old].map(([m, n]) => el('p', { class: 'meta' }, `${n} comment${n > 1 ? 's' : ''} on an earlier version of “${name(m)}” ${n > 1 ? 'are' : 'is'} hidden`)), err);
   }
 
@@ -771,12 +777,12 @@
       done.length > SHOWN ? el('p', { class: 'meta' }, `and ${done.length - SHOWN} earlier`) : '');
   }
 
-  /** A short row: a picture (or the area's mark) and the title; an answered item has its answer and time on the right. */
+  /** A short row: a picture (or the area's mark) and the title; an answered item has its answer and time under the title. */
   const compact = (d, a) => {
     const s = state.answers[d.key];
-    return [thumb(a, pic(d)), el('span', { class: 't' }, el('strong', { dir: 'auto' }, title(d)), s ? '' : el('span', { class: 'meta', dir: 'auto' }, d.about ?? NAMES[d.type] ?? d.type)),
-      s ? el('span', { class: 'ans' }, el('b', { dir: 'auto' }, s.answer === 'text' ? 'Your reply' : s.label),
-        el('time', {}, isToday(s.at) ? hhmm(s.at) : day(s.at))) : ''];
+    return [thumb(a, pic(d)), el('span', { class: 't' }, el('strong', { dir: 'auto' }, title(d)), s
+      ? el('span', { class: 'ans' }, el('b', { dir: 'auto' }, s.answer === 'text' ? 'Your reply' : s.label), el('time', {}, isToday(s.at) ? hhmm(s.at) : day(s.at)))
+      : el('span', { class: 'meta', dir: 'auto' }, d.about ?? NAMES[d.type] ?? d.type))];
   };
   let jump = null; // The item a Summary row was tapped for, scrolled to on its area's screen.
   /** A short list of an area on the Summary: a picture and the title; a tap opens the area at that item. */