sign-off-axi 0.5.4 → 0.5.6

package/README.md

@@ -49,7 +49,7 @@ Four places, in the bar at the bottom of a phone and the sidebar on a desk.
   <tr>
     <td align="center" width="25%"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/phone-today-dark.webp"><img src="docs/media/phone-today.webp" alt="Today: counts of what needs you, what was proven and new reports, then the waiting asks"></picture><br><b>Today</b><br>What needs you, what was proven, what is new.</td>
     <td align="center" width="25%"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/phone-decide-dark.webp"><img src="docs/media/phone-decide.webp" alt="Decide: one card per ask that waits on you, filtered by type"></picture><br><b>Decide</b><br>Every ask that waits on you, one tap each.</td>
-    <td align="center" width="25%"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/phone-evidence-dark.webp"><img src="docs/media/phone-evidence.webp" alt="Evidence: a capture of the finished work with its result, grouped by project"></picture><br><b>Evidence</b><br>Proof that a change works, with its honest result.</td>
+    <td align="center" width="25%"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/phone-evidence-dark.webp"><img src="docs/media/phone-evidence.webp" alt="Evidence: a capture of the finished work with its result, newest first"></picture><br><b>Evidence</b><br>Proof that a change works, with its honest result.</td>
     <td align="center" width="25%"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/phone-reports-dark.webp"><img src="docs/media/phone-reports.webp" alt="Reports: explainer pages you asked for"></picture><br><b>Reports</b><br>Explainers you asked for, to read.</td>
   </tr>
 </table>
@@ -77,7 +77,7 @@ A board that fills up with noise stops being read, so the rules sit at the door.
 - A question must say why it is asked, what each answer does, which one the agent recommends and what happens if you stay quiet; one that does not is refused with the fix ([the question standard](docs/contract.md#ask-schema-1)).
 - One decision is one card: raising the same question again changes nothing, and `--merge <key>` folds an older card into the better-asked one.
 - Proof posted as a Pass/Fail question is refused, and proof that is mostly text, a placeholder or a test card is refused too: proof goes to Evidence, as a capture of the real product; a report must be a page to tap, not a wall of words.
-- **Dismiss** hides a card from the board, **Undo** brings it back (`sign-off-axi dismiss <key>` and `restore <key>` do the same from a shell). `sign-off-axi dismiss --filer <id>` closes a finished task: every card that id still waits on leaves the board. Evidence and reports leave the main view a day after they were filed and wait under **Archived**; nothing is deleted, and Restore brings one back. A new ask that repeats an open ask on the same decision is refused, and answering one closes its twins.
+- **Dismiss** hides a card from the board, **Undo** brings it back (`sign-off-axi dismiss <key>` and `restore <key>` do the same from a shell). `sign-off-axi dismiss --filer <id>` closes a finished task: every card that id still waits on leaves the board. Reports leave the main view a day after they were filed and wait under **Archived**; nothing is deleted, and Restore brings one back. Evidence stays on its screen for good, newest first, until dismissed. Posting an evidence message again under its key, from the same filer, replaces the card. A new ask that repeats an open ask on the same decision is refused, and answering one closes its twins.
 
 ## What you can ask
 

package/dist/cli.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { acknowledgeOwner, checkOwner, deliveries, dispatchOwners, registerOwner } from './owner.js';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
-import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, asks, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
+import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendPartComment, annotationsPath, markCommentsRead, readPartComments, replyComment, asks, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, reading, readDismissed, readItems, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, diagramPages, diagramViews, guided, mediaFiles, parseMessage, reportPage } from './contract.js';
 import { faults, isStill } from './evidence-text.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
@@ -147,7 +147,7 @@ Blocks until the user answers, then prints the answer the way answers does. Use
   --timeout  seconds to wait, 600 (10 minutes) by default; then exits 1 with code TIMEOUT
   --full     adds the button label, close and title
   --json     {"<key>":{"answer","label","close","at","note"?}} for the new answers; note only when the user wrote one
-  --events   needs --filer (or SIGN_OFF_FILER); JSON lines for new answers, another-round asks and Go deeper (each wait returns one batch).
+  --events   needs --filer (or SIGN_OFF_FILER); JSON lines for new answers, another-round asks, Go deeper and comments on a part (each wait returns one batch).
              Answer and round lines come in the order they were saved (${CONTRACT}#7-answers):
              {"event":"answer","contract":1,"kind","schema","key","title","answer","label","close","at","note"?,"filer"?,"comments"?}
              {"event":"round","contract":1,"kind","schema","key","title","note","at","filer"?,"comments"?}; a board-format item reports as ask schema 1
@@ -329,6 +329,7 @@ Do not run an active wait listener for the same owner alongside the dispatcher.
     deeper: `usage: sign-off-axi deeper [board.json] [--filer <id>] [--all] [--json]
        sign-off-axi deeper [board.json] --filer <id> --id <id> --text "<answer>" [--more]
 Every part of a plan 3 or report 4 offers Ask a question, Go deeper, Simplify this, Show an example, Why?, and free text. Ask a question needs text and Send; Go deeper, Simplify this, Show an example and Why? send immediately. Free text and follow-ups use custom. Older guided schemas retain Go deeper. Engagement v1 replies require the owning --filer or registered owner session; stale targets are refused. The person taps it; wait --filer wakes with the ask, or this command lists the ones nobody finished.
+The same --id --text replies to a comment on a part (the id in wait's comment event).
 Answer in plain words about the part they tapped, a few lines at a time: each --more piece streams into that spot on the board while they watch, and a last call without --more ends it.
   --id     the ask to answer   --text  the answer, or - to read stdin (2000 characters or fewer per piece)
   --more   more pieces follow   --all  also the finished asks
@@ -684,6 +685,16 @@ function deeperOut(file, asks, on, events) {
     return toon({ board: tilde(file), deeper: asks.map(({ id, key, part, about, q = '', at, action }) => ({ id, key, part, about, q, at, ...(action && { action }) })) }, ['The person tapped Go deeper: answer in plain words, a few lines at a time, as the part they tapped',
         `Run \`sign-off-axi deeper${on} --id <id> --text "<what you found>" --more\` for each piece, then once more without --more to finish`]);
 }
+/** Comments on the parts of a guided page as the agent reads them; answer one with `deeper --id <id> --text`. */
+function commentOut(file, said, on, events) {
+    const titles = new Map(board(file).map((d) => [d.key, d.title]));
+    if (events) {
+        const kind = kindOf(file);
+        return said.map(({ id, key, part, about, verdict, text, at }) => JSON.stringify({ event: 'comment', ...kind(key), key, title: titles.get(key), id, part, about, ...(verdict && { verdict }), ...(text && { text }), at })).join('\n');
+    }
+    return toon({ board: tilde(file), comments: said.map(({ id, key, part, about, verdict = '', text = '', at }) => ({ id, key, part, about, verdict, text, at })) }, ['The person commented on a part: read it, change the page if it is right, and reply in plain words',
+        `Run \`sign-off-axi deeper${on} --id <id> --text "<your reply>"\` to answer one`]);
+}
 /** `deeper`: the Go deeper asks nobody has finished, or with --id and --text one piece of the answer the board streams under the part the person tapped. */
 async function owner(args) {
     const { file, values } = parse('owner', args, { filer: { type: 'string' }, host: { type: 'string' }, session: { type: 'string' }, cwd: { type: 'string' }, model: { type: 'string' }, dispatch: { type: 'boolean' }, verbose: { type: 'boolean' }, ack: { type: 'string' }, timeout: { type: 'string' } });
@@ -729,6 +740,18 @@ async function deeper(args) {
         markDeeperRead(file, open.filter((x) => !x.read).map((x) => x.id));
         return toon({ board: tilde(file), deeper: open.map(({ id, key, part, about, q = '', at, done, action }) => ({ id, key, part, about, q, at, done: !!done, ...(action && { action }) })) }, [`Run \`sign-off-axi deeper${on} --id <id> --text "<answer>"\` to answer one`]);
     }
+    const said = readPartComments(file).find((x) => x.id === values.id);
+    if (said) {
+        if (filer !== undefined && !board(file).some((d) => d.key === said.key && d.filer === filer))
+            throw new InputError('Request does not belong to this filer');
+        if (said.reply !== undefined)
+            throw fail(`comment ${values.id} is already answered`, 'CONFLICT', 'The person can comment again');
+        const reply = values.text === '-' ? readFileSync(0, 'utf8') : values.text;
+        if (typeof reply !== 'string' || !reply.trim() || [...reply.trim()].length > 2000)
+            throw fail('--text must be the reply, 2000 characters or fewer', 'VALIDATION_ERROR', 'Run `sign-off-axi deeper --help`');
+        replyComment(file, said.id, reply.trim());
+        return toon({ id: said.id, key: said.key, part: said.part, answered: 'done' }, [`Run \`sign-off-axi wait${on}\` for the next answer or ask`]);
+    }
     const ask = readDeeper(file).find((x) => x.id === values.id);
     if (!ask)
         throw fail(`no Go deeper ask with id ${values.id}`, 'NOT_FOUND', `Run \`sign-off-axi deeper${on}\` to see the open ones`);
@@ -784,10 +807,10 @@ async function wait(args) {
         seenRounds.set(r.key, (seenRounds.get(r.key) ?? 0) + 1);
     // A save wakes the loop at once; the 1 second timer is the fallback where file events are unavailable.
     let wake = () => { }, watcher, vaultWarned = false;
-    const name = basename(answersPath(file)), asking = basename(deeperPath(file));
+    const name = basename(answersPath(file)), asking = basename(deeperPath(file)), talking = basename(annotationsPath(file));
     try {
         try {
-            watcher = watch(dirname(file), (_, changed) => (changed === name || changed === asking) && wake()).on('error', () => { });
+            watcher = watch(dirname(file), (_, changed) => (changed === name || changed === asking || changed === talking) && wake()).on('error', () => { });
         }
         catch { }
         for (let first = true;; first = false) {
@@ -831,6 +854,14 @@ async function wait(args) {
                 }, 'another wait is still taking Go deeper asks');
                 if (asks.length)
                     return deeperOut(file, asks, onBoard + (filer ? ` --filer ${filer}` : ''), values.events);
+                // A comment on a part of this filer's page wakes the wait once, and is marked read when it is handed over.
+                const said = await locked(`${annotationsPath(file)}.lock`, () => {
+                    const got = readPartComments(file).filter((x) => !x.read && (values.key === undefined || x.key === values.key) && rows.some((d) => d.key === x.key));
+                    markCommentsRead(file, got.map((x) => x.id));
+                    return got;
+                }, 'another wait is still taking comments');
+                if (said.length)
+                    return commentOut(file, said, on, values.events);
             }
             // Private vault expiries and refusals reach a filer wait only once its ordinary answers are out; each is taken once.
             let live = 0, unknown = false;
@@ -1352,18 +1383,25 @@ function postMedia(file, named, on, values, type, filer, message) {
         // 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 = message ? message.key : explainer && (values.key ?? slug(values.title)), had = message && own && items.find((x) => x?.key === own);
+        // The same filer posting a key again with a changed proof replaces the card it posted, as a new update filed now; another filer's, or one already answered, is refused.
+        let replaced = false;
         if (had) {
             // The stored item, read back as the message it came from: its run, and each media file by hash. The notice record is the board's, not the message's.
             const asMessage = ({ type: _t, number: _n, filed: _f, announced: _a, 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');
+                if (had.filer === undefined || had.filer !== message.filer || Object.hasOwn(readAnswers(file), own))
+                    throw fail(`key ${own} already holds a different message on ${tilde(file)}`, 'CONFLICT', 'Post it under a new key');
+                items.splice(items.indexOf(had), 1);
+                replaced = true;
             }
+        }
+        if (had && !replaced) {
             return toon({ board: tilde(file), posted: [{ key: own, number: had.number, media: sources.length, title: had.title, status: 'already posted' }] }, explainer ? [`Run \`sign-off-axi open${on}\` so the user can give a verdict`] : []);
         }
         const answers = readAnswers(file);
         if (message && own && Object.hasOwn(answers, own) && !awaitsVerdict(message.kind, answers[own]))
             throw fail(`key ${own} was answered on ${tilde(file)} and is no longer there`, 'CONFLICT', 'Post it under a new key');
-        if (own && current.some((d) => d.key === own))
+        if (own && !replaced && 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 });
         let number = Math.max(0, ...taken, ...readdirSync(store).map(Number).filter(Number.isInteger)) + 1;
@@ -2460,7 +2498,7 @@ async function exportBoard(args) {
     config = join(dirname(parsed.named), 'config.yaml');
     guardReady = warmGuard();
     await guardReady;
-    const { file: _, messages: _messages, annotations: _annotations, ...frozen } = state(), files = {}, q = encodeURIComponent;
+    const { file: _, messages: _messages, annotations: _annotations, comments: _comments, ...frozen } = state(), files = {}, q = encodeURIComponent;
     let missing = 0;
     // The same URLs the page asks the server for, read through the same hash and path checks.
     const inline = async (url, query, document = false) => {
@@ -2501,12 +2539,14 @@ async function exportBoard(args) {
     return toon({ board: tilde(parsed.file), exported: tilde(out), items: frozen.decisions.length, inlined: Object.keys(files).length, ...(missing && { missing }) }, [`Open ${tilde(out)} in a browser: one read-only file, no server needed`]);
 }
 const page = readFileSync(new URL('../web/index.html', import.meta.url));
-/** The board's favicon, home-screen icon and install manifest, served beside the page; see web/icon.svg. */
-const ICONS = Object.fromEntries([['icon.svg', 'image/svg+xml'], ['apple-touch-icon.png', 'image/png'], ['icon-192.png', 'image/png'], ['icon-512.png', 'image/png'], ['icon-maskable-512.png', 'image/png'], ['manifest.webmanifest', 'application/manifest+json']]
+/** The board's design tokens, favicon, home-screen icon and install manifest, served beside the page; see web/tokens.css and web/icon.svg. */
+const ICONS = Object.fromEntries([['tokens.css', 'text/css; charset=utf-8'], ['icon.svg', 'image/svg+xml'], ['apple-touch-icon.png', 'image/png'], ['icon-192.png', 'image/png'], ['icon-512.png', 'image/png'], ['icon-maskable-512.png', 'image/png'], ['manifest.webmanifest', 'application/manifest+json']]
     .map(([name, type]) => [`/${name}`, { type, bytes: readFileSync(new URL(`../web/${name}`, import.meta.url)) }]));
 /** Added to each design mock page and plan page so the person can point at a part of it; see web/point.js. */
 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');
+/** Added to each diagram page: on the page opened by itself, a way back to its plan or report, and a phone's drawing-alone page sized to the drawing; see web/diagram-page.js. */
+const diagramPage = (back, label) => Buffer.from(`<script data-back="${back}" data-label="${label}">${readFileSync(new URL('../web/diagram-page.js', import.meta.url), 'utf8')}</script>`);
 /** A card whose picture is a colour-bar test card or a placeholder is not shown: a card posted before the guard can hold one. Read by the
  * stored hash, so each picture is measured once. */
 const unfitMedia = new Map();
@@ -2620,6 +2660,7 @@ const state = () => {
         rounds,
         messages: readMessages(file, warn),
         annotations: readOnly() || answersOnly() ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
+        comments: readOnly() || answersOnly() ? [] : readPartComments(file),
         dismissed: readDismissed(file, answers, rounds, warn, archivable(file, loadDecisions(file))),
     };
 };
@@ -2755,7 +2796,8 @@ async function route(req) {
         const d = loadDecisions(file).find((x) => x.key === key);
         // A guided document's diagram views: ~diagram.<n>, n counting them in the order visual, then each section and its items.
         const dgs = d?.guided ? diagramViews(d) : [];
-        const mock = value?.startsWith('diagram.') ? dgs[Number(value.slice(8))]?.src : value ? d?.mocks?.find((m) => m.value === value)?.path : value === '' && d?.view;
+        const diagram = value?.startsWith('diagram.') ? dgs[Number(value.slice(8))] : undefined;
+        const mock = diagram ? diagram.src : value ? d?.mocks?.find((m) => m.value === value)?.path : value === '' && d?.view;
         try {
             const path = rest.map(decodeURIComponent).join('/'), type = assetTypes[extname(path).toLowerCase()];
             if (!mock || !type)
@@ -2763,8 +2805,12 @@ async function route(req) {
             const actual = under(dirname(under(dirname(file), mockFile(mock))), path);
             if (statSync(actual).size > MOCK_BYTES)
                 return [404, { error: 'Mock is unavailable' }];
-            // Every HTML view gets the bridge: document readers need its size handshake too.
-            return [200, { media: readFileSync(actual), type, point: type === 'text/html' }];
+            const bytes = readFileSync(actual);
+            // A diagram is its one pinned page: the file the plan posted, or nothing. A plan posted before the pin carries none and is served as it was.
+            if (diagram?.sha256 && (actual !== under(dirname(file), mockFile(mock)) || bytes.length !== diagram.bytes || sha256(bytes) !== diagram.sha256))
+                return [404, { error: 'Diagram file changed since it was posted' }];
+            // Every HTML view gets the bridge: document readers need its size handshake too. A diagram also gets its way back.
+            return [200, { media: bytes, type, point: type === 'text/html', ...(diagram && type === 'text/html' && d && { page: diagramPage(`/#${d.type === 'plan' && !reading(d) ? 'waiting' : 'reports'}/${d.key}`, `Back to the ${d.type === 'plan' ? 'plan' : 'report'}`) }) }];
         }
         catch {
             return [404, { error: 'Mock is unavailable' }];
@@ -2828,8 +2874,8 @@ async function route(req) {
         return [404, { error: 'Not found' }];
     if (readOnly())
         return [403, { error: 'This board is read-only' }];
-    // Dismiss only hides an item on this page and sends nothing to the feeding program, so an answers-only board takes it too.
-    if (!['/api/answers', '/api/dismiss', '/api/signin', '/api/reads'].includes(req.url) && answersOnly())
+    // Dismiss only hides an item on this page and sends nothing to the feeding program, and Go deeper only asks for an explanation, so an answers-only board takes both.
+    if (!['/api/answers', '/api/dismiss', '/api/signin', '/api/reads', '/api/deeper', '/api/engagement', '/api/engagement/seen'].includes(req.url) && answersOnly())
         return [403, { error: 'This board takes answers only' }];
     if (!req.headers['content-type']?.startsWith('application/json'))
         return [415, { error: 'Send JSON' }];
@@ -2848,7 +2894,22 @@ 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), sent = sentIds(file);
+        const c = JSON.parse(body) ?? {};
+        // A comment on a part of a guided page: Agree, Disagree or words, kept beside the design notes for the author agent's wait to take.
+        if (c.part !== undefined) {
+            const d = loadDecisions(file).find((x) => x.key === c.key), about = typeof c.part === 'string' && d && guidePart(d, c.part);
+            if (!about)
+                return [404, { error: 'This part is no longer on the board' }];
+            if (c.verdict !== undefined && c.verdict !== 'agree' && c.verdict !== 'disagree')
+                return [400, { error: 'Send agree or disagree' }];
+            if (c.text !== undefined && (typeof c.text !== 'string' || [...c.text.trim()].length > NOTE_MAX))
+                return [400, { error: `Write the comment in ${NOTE_MAX} characters or fewer` }];
+            if (!c.verdict && !c.text?.trim())
+                return [400, { error: 'Write the comment first' }];
+            appendPartComment(file, c.key, c.part, about, c.verdict, c.text?.trim());
+            return [200, state()];
+        }
+        const { id, deleted, key, mock, ref, tag, words, text, hash: shown } = c, 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' }];
@@ -3153,7 +3214,7 @@ const server = createServer(async (req, res) => {
         return bytes ? pipeline(createReadStream(path, { start, end }), res, () => { }) : res.end();
     }
     if (body && typeof body === 'object' && 'media' in body) {
-        const { media: bytes, type, point } = body, media = point ? Buffer.concat([bytes, pointer]) : bytes;
+        const { media: bytes, type, point, page } = body, media = point ? Buffer.concat([bytes, pointer, ...(page ? [page] : [])]) : bytes;
         const headers = { 'content-type': type, 'x-content-type-options': 'nosniff', 'content-security-policy': FRAME_CSP, 'accept-ranges': 'bytes', 'content-length': media.length };
         // One byte range, so phone browsers can play and seek a recording.
         const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? '');

package/dist/contract.js

@@ -1,4 +1,5 @@
 // The v1 communication contract (docs/contract.md): one strict, versioned shape per kind of message.
+import { createHash } from 'node:crypto';
 import { accessSync, constants, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { isKey, MEDIA_MAX, REPORT_FORMS } from './store.js';
@@ -211,8 +212,12 @@ export function checkMessage(m, want, flags = false) {
         text(`${field}[${n}].label`, o.label, 40, 'the number\'s name, in 40 characters or fewer');
         text(`${field}[${n}].value`, o.value, 120, 'the number and its unit, in 120 characters or fewer');
     });
-    /** A diagram: 1 to 3 views of one picture (Today, After), each a board-relative .html file the board frames. */
-    const diagrams = (field, v) => list(field, 1, 3, ['label', 'src'], '{"label":"Today","src":"diagrams/flow.html"}', v).forEach((o, n) => {
+    /** A diagram: 1 to 3 views of one picture (Today, After), each a board-relative .html file the board frames. Post adds each file's `sha256` and `bytes`, as it does for media. */
+    const diagrams = (field, v) => list(field, 1, 3, ['label', 'src', 'sha256', 'bytes'], '{"label":"Today","src":"diagrams/flow.html"}', v).forEach((o, n) => {
+        if (Object.hasOwn(o, 'sha256') && !/^[a-f0-9]{64}$/.test(o.sha256))
+            throw bad(`${field}[${n}].sha256`, 'must be 64 lowercase hex digits', 'Leave "sha256" and "bytes" out; post pins the file');
+        if (Object.hasOwn(o, 'bytes') && !(Number.isInteger(o.bytes) && o.bytes >= 0))
+            throw bad(`${field}[${n}].bytes`, 'must be a whole number of bytes', 'Leave "sha256" and "bytes" out; post pins the file');
         text(`${field}[${n}].label`, o.label, 40, 'the view name, such as "Today", in 40 characters or fewer');
         text(`${field}[${n}].src`, o.src, 256, 'a page path from the board file\'s folder, such as "diagrams/flow.html"');
         if (/^([\\/]|[A-Za-z]:)/.test(o.src) || o.src.split(/[\\/]/).includes('..') || /[?#\\]/.test(o.src) || !/\.html?$/i.test(o.src))
@@ -663,7 +668,8 @@ export const diagramViews = (m) => [m?.visual?.diagram, ...(m?.sections ?? []).f
 const DIAGRAM_MIN_PX = 12;
 const PHONE_PX = 390, PHONE_DRAW_PX = PHONE_PX - 16;
 /** A guided plan's or report's diagram pages, from `base`, the board file's folder: each a file of 5 MB or less whose real path stays inside it,
- * with a drawing whose smallest text is at least 12 px at 390 and no brand marks (their licenses differ). The first broken rule throws. */
+ * with a drawing whose smallest text is at least 12 px at 390 and no brand marks (their licenses differ). The first broken rule throws.
+ * Each view that passes is pinned with the file's `sha256` and `bytes`, so the board serves only the file that was posted and the revision covers its content. */
 export function diagramPages(m, base) {
     const at = isKey(m.key) ? `key ${m.key}: ` : '';
     let root = resolve(base);
@@ -692,7 +698,7 @@ export function diagramPages(m, base) {
         catch {
             throw bad('cannot be read', 'Make the file readable, then post again');
         }
-        const html = readFileSync(real, 'utf8'), svg = html.match(/<svg\b[^>]*\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+[\d.]+[^>]*>([\s\S]*?)<\/svg>/i);
+        const file = readFileSync(real), html = file.toString('utf8'), svg = html.match(/<svg\b[^>]*\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+[\d.]+[^>]*>([\s\S]*?)<\/svg>/i);
         if (!svg)
             throw bad('has no <svg> drawing with a viewBox', 'Render it with the archify skill: an architecture diagram with a viewBox 320 to 340 wide and its legend hidden');
         if (/data-brand-mark/i.test(html))
@@ -701,6 +707,8 @@ export function diagramPages(m, base) {
         const small = Math.min(...sizes), real12 = small * PHONE_DRAW_PX / Number(svg[1]);
         if (sizes.length && real12 < DIAGRAM_MIN_PX)
             throw bad(`has text of ${Math.round(real12 * 10) / 10} px at ${PHONE_PX} (${small} in a ${svg[1]} wide drawing), under ${DIAGRAM_MIN_PX}`, `Draw it narrower, an architecture viewBox 320 to 340 wide with no sublabels and the legend hidden ("legend": {"mode": "hidden"} in "meta"), so every text is ${DIAGRAM_MIN_PX} px or more on a phone`);
+        v.sha256 = createHash('sha256').update(file).digest('hex');
+        v.bytes = file.length;
     }
 }
 /** The longest a block of plain text on a report page may run: about five lines on a phone. */

package/dist/owner.js

@@ -49,7 +49,7 @@ export async function dispatchOwners(file, cli, filer, verbose = false) {
     for (const ask of readDeeper(file).filter(x => !x.done && items.some(d => d.key === x.key && (filer === undefined || d.filer === filer)))) {
         const owner = ownerFor(file, ask);
         if (!owner) {
-            record(file, ask.id, 'queued', 'No registered owner session');
+            record(file, ask.id, 'queued', 'No agent is watching this document right now. Your ask is saved for when one does.');
             continue;
         }
         // One final reply is atomic in the existing deeper log; replay never appends a second answer.

package/dist/store.js

@@ -325,7 +325,7 @@ export const SCREENS_ONLY = 'screens';
 /** True while an answer leaves the item waiting: none yet, or only screen notes. */
 export const awaitsVerdict = (type, a) => !a || (type === 'design' && a.answer === SCREENS_ONLY);
 const DESIGN_LABEL = { approve: 'Approved', change: 'Changes requested', [SCREENS_ONLY]: 'Screens reviewed' };
-/** Saves a design answer with screen-specific notes and an optional listed direction pick. A screen save omits the verdict: the design keeps its saved verdict, a change on a screen of an approved design sets it to change, and with none yet it waits as screens-only. */
+/** Saves a design answer with screen-specific notes and an optional listed direction pick. A screen save omits the verdict: the design keeps its saved verdict, a requested change on a screen sets it to change, and any other screen save with none yet waits as screens-only. */
 export function appendDesignAnswer(decisionsPath, d, verdict, notes, pick, requested) {
     const bad = (rule) => new InputError(`key ${d.key}: ${rule}`);
     if (verdict !== undefined && verdict !== 'approve' && verdict !== 'change')
@@ -352,7 +352,7 @@ export function appendDesignAnswer(decisionsPath, d, verdict, notes, pick, reque
         throw bad('pick must be one listed option, and a design verdict needs one when options were offered');
     const current = readAnswers(decisionsPath)[d.key];
     const decided = current?.answer === 'approve' || current?.answer === 'change' ? current.answer : undefined;
-    const kept = (verdict ?? (decided === 'approve' && requested === true ? 'change' : decided ?? SCREENS_ONLY));
+    const kept = (verdict ?? (requested === true ? 'change' : decided ?? SCREENS_ONLY));
     const keptPick = (pick ?? (options.some(o => o.value === current?.pick) ? current?.pick : undefined));
     const answer = { key: d.key, answer: kept, label: DESIGN_LABEL[kept], close: d.close ?? 'done', at: now(), notes, ...(keptPick !== undefined && { pick: keptPick }) };
     if (current?.answer === answer.answer && JSON.stringify([current.notes, current.pick]) === JSON.stringify([answer.notes, answer.pick]))
@@ -462,10 +462,10 @@ export const asks = (d) => d.type !== 'evidence' && !reading(d) && (d.options.le
 export const reading = (d) => d.type === 'plan' && !!d.guided && !d.decisions?.length;
 /** A sign-in whose fixed link has expired has nothing left to open: it is not waiting, here or on the board's page (web/index.html lapsed() says the same). A start command makes a new link per tap and never lapses. */
 export const lapsed = (d) => d.type === 'signin' && !d.start && !!d.expires && Date.parse(d.expires) <= Date.now();
-/** Evidence and reports (nothing to answer) archive on their own this long after they were filed: dismissed, never deleted. */
+/** Reports (nothing to answer) archive on their own this long after they were filed: dismissed, never deleted. Evidence is kept for good: only a dismiss line hides a proof. */
 export const ARCHIVE_MS = 24 * 3_600_000;
 /** Keys hidden now: the last line for each dismissed it, and no answer or round came after it. A torn line is skipped and reported through warn.
- * `items`, when given, adds the archive: evidence and reports filed over a day ago that no log line ever named. Restore writes a line, so a restored item stays. */
+ * `items`, when given, adds the archive: reports filed over a day ago that no log line ever named. Restore writes a line, so a restored item stays. */
 export function readDismissed(decisionsPath, answers, rounds, warn = () => { }, items = []) {
     const hidden = new Map(), named = new Set();
     readRaw(dismissedPath(decisionsPath)).split('\n').forEach((line, n) => {
@@ -482,7 +482,7 @@ export function readDismissed(decisionsPath, answers, rounds, warn = () => { },
             warn(`skipped unreadable line ${n + 1} in ${dismissedPath(decisionsPath)}`);
         }
     });
-    const archived = items.filter((d) => !asks(d) && !named.has(d.key) && Date.now() - Date.parse(d.filed ?? '') > ARCHIVE_MS).map((d) => d.key);
+    const archived = items.filter((d) => d.type !== 'evidence' && !asks(d) && !named.has(d.key) && Date.now() - Date.parse(d.filed ?? '') > ARCHIVE_MS).map((d) => d.key);
     return [...[...hidden].filter(([key, at]) => !(answers[key]?.at > at) && !rounds.some((r) => r.key === key && r.at > at)).map(([key]) => key), ...archived];
 }
 export const messagesPath = (decisionsPath) => decisionsPath.replace(/\.json$/, '') + '.messages.jsonl';
@@ -521,7 +521,7 @@ export function readAnnotations(decisionsPath, warn = () => { }) {
                 all.delete(a.id);
             else if (a && ['id', 'key', 'mock', 'hash', 'ref', 'tag', 'words', 'text'].every((k) => typeof a[k] === 'string'))
                 all.set(a.id, a);
-            else if (a)
+            else if (a && a.part === undefined && a.op === undefined)
                 warn(`skipped unreadable line ${n + 1} in ${annotationsPath(decisionsPath)}`);
         }
         catch {
@@ -530,6 +530,33 @@ export function readAnnotations(decisionsPath, warn = () => { }) {
     });
     return [...all.values()];
 }
+export function readPartComments(decisionsPath) {
+    const all = new Map();
+    readRaw(annotationsPath(decisionsPath)).split('\n').forEach((line) => {
+        try {
+            const x = line && JSON.parse(line), c = x && all.get(x.id);
+            if (typeof x?.part === 'string' && typeof x.id === 'string')
+                all.set(x.id, { id: x.id, key: x.key, part: x.part, about: x.about, ...(x.verdict && { verdict: x.verdict }), ...(x.text && { text: x.text }), at: x.at });
+            else if (c && x.op === 'read')
+                c.read ??= x.at;
+            else if (c && x.op === 'reply') {
+                c.reply = x.text;
+                c.replied = x.at;
+                c.read ??= x.at;
+            }
+        }
+        catch { }
+    });
+    return [...all.values()];
+}
+export function appendPartComment(decisionsPath, key, part, about, verdict, text) {
+    const id = randomBytes(6).toString('hex'), at = now();
+    appendLine(annotationsPath(decisionsPath), { id, key, part, about, ...(verdict && { verdict }), ...(text && { text }), at });
+    return { id, key, part, about, ...(verdict && { verdict }), ...(text && { text }), at };
+}
+export const markCommentsRead = (decisionsPath, ids) => { for (const id of ids)
+    appendLine(annotationsPath(decisionsPath), { op: 'read', id, at: now() }); };
+export const replyComment = (decisionsPath, id, text) => appendLine(annotationsPath(decisionsPath), { op: 'reply', id, text, at: now() });
 /** Saves a comment (a new id unless it edits one) or, with only an id, deletes it. */
 export const appendAnnotation = (decisionsPath, a) => appendLine(annotationsPath(decisionsPath), { ...a, id: a.id ?? randomBytes(6).toString('hex'), at: now() });
 /** The parts of a guided page that can be read and asked about, with the name the agent hears: this, understood, each section and item, each decision, next. Undefined for a part it has not got. */

package/package.json

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

package/skills/sign-off-axi/SKILL.md

@@ -73,7 +73,7 @@ sign-off refuses a question that breaks these rules, naming the field and one fi
 - `--recommend` the answer you would pick, with `--recommend-reason` in one line.
 - `--default`: what happens if the user stays quiet, and `--silent-by <ISO UTC time>` when.
 - A card you posted by mistake: `npx -y sign-off-axi dismiss <key>` hides it, `restore <key>` brings it back. When the user dismisses a card, you are not told: `answers` still returns a dismissed answer.
-- When your task ends (merged, dropped, or answered some other way), run `npx -y sign-off-axi dismiss --filer <id>`: every card you posted that still waits leaves Decide. Evidence and reports leave the main view by themselves a day after they were filed; they wait under Archived on their screen and `restore <key>` brings one back. Nothing is deleted.
+- When your task ends (merged, dropped, or answered some other way), run `npx -y sign-off-axi dismiss --filer <id>`: every card you posted that still waits leaves Decide. Reports leave the main view by themselves a day after they were filed; they wait under Archived on their screen and `restore <key>` brings one back. Evidence stays on the Evidence screen until dismissed, and posting it again under the same key with a changed proof replaces the card. Nothing is deleted.
 
 A good yes/no question:
 
@@ -105,18 +105,18 @@ npx -y sign-off-axi raise --ask-ref <captain-message-id-or-hold-id> --title "Whi
 - Write each part for the reader, in the order the board shows it: *What this is* (the answer and one picture: bars, steps or tiles), *What I understood* (the request in your words, so they can say it is off), *What I found*, *What I recommend* (plans), *What you decide* (plans, at most five questions, each with your pick and why), *Next step*.
   - Answer first: the heading of the picture is the answer, one plain sentence.
   - One picture per point; the numbers go in `details`, behind a tap, never in the sentence.
-  - Short lines: `text` one line, `more` the part that opens in place; never a paragraph the reader must scroll.
+  - Short lines: `text` one line, `more` the part that opens in place, with a line break between points; never a paragraph the reader must scroll.
   - Plain words for a person who does not write code; no ids, no file paths, no tool names.
   - Name the date the facts were true if they will go stale.
 - A research report (a comparison, an option study, a "should we use X?" question) must clear a higher bar than an explainer. A few options backed only by your own numbers is rejected.
   - Name the must-haves first. Survey the whole real field, then short-list against them. Say in one line why each option was cut.
-  - Give every short-listed option the same axes and its full pros and cons, as one comparable table: one `found` item per option, pros and cons in `text`, and each axis as "Axis: value." in the same order in `more`.
+  - Give every short-listed option the same axes and its full pros and cons, as one comparable table: one `found` item per option, pros and cons in `text`, and in `more` each axis on its own line as "Axis: value.", the same axes in the same order. The board then draws the section as one table; an older board shows the same lines as text.
   - Back each claim with outside proof and its link: GitHub issues (open bugs, regressions, upgrade breaks, how the maintainers answered), Reddit, Hacker News, X, forums and blogs. If a site blocks fetching, say what you could not read. Vendor marketing, star counts and your own team's work-log numbers are not proof.
   - Keep what you checked yourself apart from what others claim: a separate section, or each line starting "Checked:" or "Reported:".
   - End with one clear recommendation and a runner-up, each with its reasons.
 - A plan clears the same research bar for every choice in it, then gives what a go-ahead needs: the options with their pros and cons, your recommendation, the scope (what is in and what is out), the steps in order, each risk with what you do about it, and how done is proven (`Done when` in `understood`, and where the proof lands in `next`).
 - New guided defaults are plan schema 3 and report schema 4 (contract 1), with your required filer. Older schemas still load. Every part offers **Ask a question**, **Go deeper**, **Simplify this**, **Show an example**, **Why?**, plus free text and follow-ups. Ask a question focuses the section composer; text and Send are required. Other presets send immediately. Question/custom need nonblank text (at most 500 code points); free text and follow-ups use custom. Answer the exact action and question in its section: explain, give detail, use simpler words, give an example, or explain why. All use one engagement path: version 1 carries action, immutable owner, document revision and target, with an optional selection (authored field, code-point start/end, exact quote): when present, answer about those quoted words in their place in the document. Read these fields with `deeper --json --all`; answer the requested action from the original document, never rewrite text or change plan decisions. Active replies need `--filer <your id>`; registered sessions acknowledge the exact id first. Stale targets and other owners are refused. The answer expands in place and stays New across reload until visibly read. Keep the owner dispatcher/listener alive after reports and sent plans, and after every reply.
-- The board shows who read each part and when, and the supported presets under every part. When the person taps one, `wait --filer <id>` returns the ask (including action, part and any question), or run `npx -y sign-off-axi deeper <board> --filer <id>` to list the open ones. Active listeners answer in plain words, a few lines at a time: `npx -y sign-off-axi deeper <board> --filer <id> --id <id> --text "<what you found>" --more` for each piece, then once without `--more` to finish. Registered dormant owners instead acknowledge and send one final answer as described above. The board streams each piece into the spot they tapped. Never answer with a long essay: say less, they can ask a follow-up.
+- The board shows who read each part and when, and the supported presets under every part. When the person taps one, `wait --filer <id>` returns the ask (including action, part and any question), or run `npx -y sign-off-axi deeper <board> --filer <id>` to list the open ones. Active listeners answer in plain words, a few lines at a time: `npx -y sign-off-axi deeper <board> --filer <id> --id <id> --text "<what you found>" --more` for each piece, then once without `--more` to finish. Registered dormant owners instead acknowledge and send one final answer as described above. The board streams each piece into the spot they tapped. A person's Agree, Disagree or Comment on a part reaches the same wait as an event with the part and the words; reply to it with the same `deeper --id <id> --text` and change the page if they are right. Never answer with a long essay: say less, they can ask a follow-up.
 - Open the board at 390 px wide and look before you tell the person it is there: the first screen must give the answer and the picture.
 - Only if you must keep an HTML page of your own (a demo to tap), run `report init <folder> --page` and post it with `--type report --view --preview`.
 
@@ -126,7 +126,7 @@ Only where structure, order or dependency is the point: how a change flows, what
 
 - Add `"diagram": [{"label": "Today", "src": "diagrams/flow.html"}]` (1 to 3 views, shown as tabs) to the `visual`, a section or an item, beside the rows, which stay as the list. `src` is a page next to the plan or report file, as `view` is.
 - Draw an `architecture` diagram with a `viewBox` 320 to 340 wide (320 is Archify's smallest): two columns, labels under about 16 characters, no sublabels, `"legend": {"mode": "hidden"}` in `meta`. Sequence, workflow and `compare` pages are too wide for a phone; show the same flow as a numbered column instead, and draw Today and After as two pages, one per tab.
-- Post refuses a diagram whose smallest text is under 12 px on a 390 px phone, one with brand marks (never set `brand`), or one that is not there.
+- Post refuses a diagram whose smallest text is under 12 px on a 390 px phone, one with brand marks (never set `brand`), or one that is not there. Post pins each page (its `sha256` and `bytes`, written for you): a page changed after posting is not shown, so draw a changed page again and post the plan again.
 - Run `ARCHIFY_UPDATE_CHECK_DISABLED=1 archify finalize` with `--quality showcase`, so it makes no network call. Archify draws in its own mono type; sign-off cannot change it.
 - On a phone the board shows the picture and **Full size**, which opens the drawing alone at the full width of the screen; on a desk **Show me** opens the interactive page in place. Look at both at 390 before you say it is posted.
 
@@ -149,7 +149,7 @@ When the user must choose how something looks or works, do this:
 4. Write a short trade-off in plain words (5 lines or fewer: what each variant does well and badly) and recommend one.
 5. Post it on the project board with `npx -y sign-off-axi post .sign-off/decisions.json --type design --key <key>`, one `--option` and one `--mock` per variant, `--tradeoff` and `--recommend` (see `post --help`). Mock paths are relative to `.sign-off/`: `--mock a=mocks/<key>/a.html`, or `--mock a=mocks/<key>/index.html?variant=a` for the one-page form. When a variant also runs live at a URL, add `--link a=<http or https URL>` for it (one per variant): the card shows an Open live link under that mock, which opens in a new tab. Then run `npx -y sign-off-axi open .sign-off/decisions.json` and give the user the URL.
 6. Wait with `npx -y sign-off-axi wait .sign-off/decisions.json --key <key>`.
-7. Read the answer with `npx -y sign-off-axi answers .sign-off/decisions.json --key <key> --json`. A pick holds `answer` and maybe a `note`; `"answer": "text"` is the user's own answer (Other answer), in its `note`. A `rounds` entry with no `answer`, or newer than the `answer`'s `at`, means the user wants another round: read its note, build 3 new variants and post them under a new key. A `comments` list on the answer or the round holds the user's comments on parts of a mock: `mock` is the option, `ref`, `tag` and `words` name the element, `text` is the comment; apply them to that variant.
+7. Read the answer with `npx -y sign-off-axi answers .sign-off/decisions.json --key <key> --json`. A pick holds `answer` and maybe a `note`, the comment the user sent with it; `"answer": "text"` is the user's own answer (Send as my own answer, or Send reply), in its `note`. A `rounds` entry with no `answer`, or newer than the `answer`'s `at`, means the user wants another round: read its note, build 3 new variants and post them under a new key. A `comments` list on the answer or the round holds the user's comments on parts of a mock: `mock` is the option, `ref`, `tag` and `words` name the element, `text` is the comment; apply them to that variant.
 8. Build the winner into the real code, then delete `.sign-off/mocks/<key>/`.
 
 Build mocks with a fast, cheap model: a mock is throwaway work. If first-draft is installed, it can build the mocks and write its `Open in first-draft: <label> <url>` links at the end of `--tradeoff`; the board shows them as real links.

package/web/diagram-page.js

@@ -0,0 +1,22 @@
+// Added to each diagram page the board serves. Only on the page opened by itself (Full size, not the card's frame): a way back to the plan or report,
+// and on a phone's drawing-alone page (embed=1) the page is sized to the drawing, with the drawing's own surface carried down the rest of the screen, so no grey area follows it.
+(() => {
+  if (parent !== window) return;
+  const me = document.currentScript, back = me.dataset.back, label = me.dataset.label;
+  const style = document.createElement('style');
+  style.textContent = '.so-back { display: flex; align-items: center; gap: 0.375rem; box-sizing: border-box; width: fit-content; min-height: 2.75rem; margin: 0.25rem 0.5rem; padding: 0 0.875rem; border: 1px solid currentColor; border-radius: 999px; color: inherit; font: 600 0.9375rem/1 system-ui, sans-serif; text-decoration: none; }'
+    + '.so-back:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }';
+  const surface = document.querySelector('.diagram-container');
+  if (new URLSearchParams(location.search).get('embed') === '1') {
+    style.textContent += 'html, body { height: auto !important; min-height: 0 !important; }';
+    if (surface) {
+      // The drawing sits on its own surface over the page's colour; the page takes that surface too, so the screen below the drawing is the drawing's own.
+      const s = getComputedStyle(surface);
+      style.textContent += `body { background-image: ${s.backgroundImage}, linear-gradient(${s.backgroundColor}, ${s.backgroundColor}) !important; background-size: ${s.backgroundSize}, auto !important; }`
+        + '.diagram-container { background: none !important; }';
+    }
+  }
+  const link = document.createElement('a');
+  link.className = 'so-back'; link.href = back; link.textContent = `← ${label}`;
+  document.head.append(style); document.body.prepend(link);
+})();