sign-off-axi 0.6.0 → 0.6.2

package/README.md

@@ -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. 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.
+- **Discard** takes a card off the board with one tap on a reason (Not relevant, Replaced by newer or Done elsewhere): it moves to **Archived**, **Undo** brings it back for 10 seconds, and its agent is told why once those 10 seconds are over. **Select** in Decide and Designs discards several at once, and **Restore** under Archived brings one back (`sign-off-axi dismiss <key> --reason replaced` and `restore <key>` do the same from a shell; without `--reason`, `dismiss` hides a card and tells no one). `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.
 
 ### One ticket ties a task's cards together
 

package/dist/cli.js

@@ -14,11 +14,21 @@ 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, appendPartComment, annotationsPath, markCommentsRead, readPartComments, replyComment, asks, appendAnswer, appendDismissed, appendPromoted, appendSendBack, appendTicket, readTickets, rollUp, appendTicketComment, ticketCommentFault, ticketFault, appendProject, readProjects, projectFault, iconPathFault, iconContentFault, ICON_BYTES, ICON_TYPES, PRIORITIES, appendDesignAnswer, answerLines, appendMark, readTrail, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, appendOpened, readOpened, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, reading, readDismissed, readItems, readPromoted, sameDecision, readMessages, readRounds, roundsPath, sameRound, 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, DISCARD_REASONS, readDiscards, UNDO_MS, appendPromoted, appendSendBack, appendTicket, readTickets, rollUp, appendTicketComment, ticketCommentFault, ticketFault, appendProject, readProjects, projectFault, iconPathFault, iconContentFault, ICON_BYTES, ICON_TYPES, PRIORITIES, REPORT_PARTS, REPORT_PURPOSES, appendDesignAnswer, answerLines, appendMark, readTrail, trailPath, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, appendOpened, readOpened, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, reading, readDismissed, readItems, readPromoted, sameDecision, readMessages, readRounds, roundsPath, sameRound, 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 { copiesOf } from './images.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
+/** The version this copy runs, read from package.json once: a pre-release version says so, and a git checkout whose HEAD carries no tag
+ * for that version is a dev build ahead of its release, `<version>-dev`. An installed copy has no .git, so it shows its version as published.
+ * --version prints `version`; the help header and the board (the sidebar's foot, Today's More) show `label`. */
+const VERSION = ((version) => {
+    if (version.includes('-'))
+        return { version, label: `${version}, pre-release` };
+    const root = new URL('..', import.meta.url);
+    const tags = existsSync(new URL('.git', root)) && (spawnSync('git', ['tag', '--points-at', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 }).stdout ?? '').split('\n');
+    return tags && !tags.some((t) => t === version || t === `v${version}`) ? { version: `${version}-dev`, label: `${version}-dev` } : { version, label: version };
+})(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
 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';
 /** Coding agents init installs the skill for: the `npx skills add -a` name, the command that shows it is installed,
@@ -31,7 +41,8 @@ const AGENTS = {
     pi: { bin: 'pi', dir: '.agents/skills', home: join(homedir(), '.agents', 'skills') },
     'gemini-cli': { bin: 'gemini', dir: '.agents/skills', home: join(homedir(), '.gemini', 'skills') },
 };
-const TOP_HELP = `usage: sign-off-axi [command] [board.json] [flags]
+const TOP_HELP = `version: ${VERSION.label}
+usage: sign-off-axi [command] [board.json] [flags]
 commands[26]:
   (none)=list, raise, post, answers, wait, poll, deeper, owner, open, status, stop, serve, export, init, report, signin, dismiss, restore, promote, feedback, ticket, project, refile, doctor, notify, validate, help
 board: the nearest .sign-off/ board (the walk's bounds and SIGN_OFF_HOME: README, "Test runs never touch your board"), else ~/.sign-off/decisions.json; a board file given always wins
@@ -43,7 +54,7 @@ examples:
   sign-off-axi post .sign-off/decisions.json --type design --title "Pick the sign-in layout" --option a=A --option b=B --mock a=mocks/a.html --mock b=mocks/b.html --recommend b
   sign-off-axi post .sign-off/decisions.json --type diagram --title "Is this the sign-in flow?" --view mocks/sign-in/flow.svg
   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
-  sign-off-axi report init .sign-off/reports/sign-in-flow
+  sign-off-axi report init .sign-off/reports/sign-in-flow --purpose research
   sign-off-axi post --kind report --from .sign-off/reports/sign-in-flow/report.json
   sign-off-axi report init .sign-off/plans/sign-in --plan
   sign-off-axi post --kind plan --from .sign-off/plans/sign-in/plan.json --filer my-session-id
@@ -106,8 +117,8 @@ 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, evidence, gate, finding and design at schema 1, report at schema 3 (schema 2 still passes) and plan at schema 2 (schema 1 still passes).
-A report 3 and a plan 2 are guided pages: fields the board draws as one scroll, no page of your own (see report init).
+A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, evidence, gate, finding and design at schema 1, report at schema 5 (schemas 2 to 4 still pass) and plan at schema 3 (schemas 1 and 2 still pass).
+A report 3 to 5 and a plan 2 or 3 are guided pages: fields the board draws as one scroll, no page of your own (see report init). A report 5 names what it is for in "purpose".
 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.
 A report is a page to tap through: its "view" (.html) and "preview" (its picture, beside it) are checked for their shape here; the files themselves are checked at post, from the board file's folder, filled with no FILL: lines left (see report init).
 A plan's "view" (.html) is checked for its shape here; the file itself is checked at post, from the board file's folder.
@@ -278,15 +289,17 @@ Run it when you see the sign-in worked. A card posted with --start also closes b
 examples:
   sign-off-axi signin done --key npm-login
 `,
-    dismiss: `usage: sign-off-axi dismiss <key> [board.json]
+    dismiss: `usage: sign-off-axi dismiss <key> [board.json] [--reason not-relevant|replaced|done-elsewhere]
        sign-off-axi dismiss --filer <id> [board.json]
-Hides a card from the board, like its Dismiss button. The agent is not told, and an ask it waits on keeps waiting.
+Hides a card from the board. The agent is not told, and an ask it waits on keeps waiting.
+--reason discards it instead, like the board's Discard: the card moves to Archived and its agent's wait hands the reason over (Not relevant, Replaced by newer or Done elsewhere) once Undo's 10 seconds are over.
 --filer <id> closes a finished task: every card that id still has waiting leaves the board. Run it when your work ends, so nothing of yours is left on Decide.
 Evidence and reports leave the main view by themselves a day after they were filed; they stay under Archived on their screen, and restore brings one back for good.
 restore <key> [board.json] brings it back. Find the key with \`sign-off-axi list --full\`.
 examples:
   sign-off-axi dismiss ship-the-new-sign-in-screen-this-week
   sign-off-axi dismiss --filer agent-41
+  sign-off-axi dismiss fleet-dashboard-first-look --reason replaced
   sign-off-axi restore ship-the-new-sign-in-screen-this-week
 `,
     refile: `usage: sign-off-axi refile <key> [board.json] --media <file>... [--link <commit or URL>]
@@ -299,7 +312,7 @@ Brings back a card that dismiss hid. See \`sign-off-axi dismiss --help\`.
 `,
     ticket: `usage: sign-off-axi ticket [board.json] [--json]
        sign-off-axi ticket [board.json] --id <id> [--json]
-       sign-off-axi ticket [board.json] --id <id> [--title <text>] [--progress <0-100>] [--parent <id>] [--priority P0-P3] [--project <name>] [--hold yes|no] [--asked yes|no]
+       sign-off-axi ticket [board.json] --id <id> [--title <text>] [--progress <0-100>] [--parent <id>] [--priority P0-P3] [--project <name>] [--hold yes|no] [--asked yes|no] [--release <text>] [--state <state>] [--pr <url>]...
        sign-off-axi ticket [board.json] --id <id> --comment '<json>'
 A ticket is one piece of work: its id, title, percent done and, optionally, the ticket it sits under, its priority, its project (whose icon its rows show),
 whether it is on hold and whether you asked for it (the board's Tickets tab then lists it under Your asks). It stands alone: nothing else needs it.
@@ -309,6 +322,9 @@ With any other flag, writes it: a new ticket needs --title (progress starts at 0
 A card names its ticket with --ticket <id> on raise and post (every --type and --kind), or "ticket" in a message or --from item:
 its screen then shows a Ticket row, the title and progress, that opens the ticket, which lists its asks, designs, proof and reports.
 A card whose ticket is not on the board shows no row; a ticket with no cards shows an empty page.
+--release labels the release (up to 40 characters). --state is queued, "in progress", "on hold" or done; it takes precedence over progress/hold for grouping.
+--pr takes full HTTP(S) URLs, repeatable or comma separated; it replaces the linked PR list. Empty --release, --state or --pr clears that field.
+Without --state, grouping stays Done at 100%, else On hold with --hold yes, else In progress above 0%, else To do.
 It writes one line to <board>.tickets.jsonl beside the board (${FORMAT}).
 --comment hands over a comment the person made on the ticket elsewhere (the fleet dashboard), in that dashboard's thread record: {"id","at","text","error","picked","replies":[{"at","text","by"}]},
 times in whole seconds since 1970. Send it again as it moves: the board shows it Sent, Delivered (no error), Read (picked) and Replied (the last reply) on the ticket, and a reply in Today.
@@ -354,8 +370,13 @@ examples:
   sign-off-axi feedback fleet-dashboard-full --reply "The colours now come from the new tokens." --link https://github.com/owner/repo/pull/245
   sign-off-axi feedback fleet-dashboard-full --acted --link https://github.com/owner/repo/pull/245
 `,
-    report: `usage: sign-off-axi report init <folder> [--plan] [--page]
+    report: `usage: sign-off-axi report init <folder> [--purpose research|plan|decision|audit|incident|status|other] [--plan] [--page]
 Writes the guided template to fill: <folder>/report.json, or <folder>/plan.json with --plan. A file already there is kept.
+Every report names what it is for in "purpose", its kind: research (research and discovery), plan (implementation plan), decision (decision and recommendation),
+audit, incident (incident and retro), status, or other. --purpose fills it in and writes that kind's parts to fill, one section each, which post then requires
+(research: question, scope, method, sources with links and a user report, options, findings with their confidence, not-checked, recommendation, open-questions;
+plan: goal, current, design with a diagram, slices with their size, tests, risks, rollout, estimate, owner-calls; see the skill for the others).
+The board shows the kind on the report's row and head, its parts as a strip, and filters by it.
 The board draws it as one scroll: what this is (the answer and one picture), what I understood, what I found and recommend, what you decide (plans), and the next step.
 Numbers sit behind a Details tap; every part has a Go deeper button that asks you (see \`sign-off-axi deeper --help\`) and a read receipt that shows when the person read it.
 Replace every FILL: line, then post it: post --kind report --from <folder>/report.json, or post --kind plan --from <folder>/plan.json --filer <your id>.
@@ -653,8 +674,9 @@ function board(file, say = warn) {
     for (const key of Object.keys(answers))
         if (!decisions.some((d) => d.key === key))
             say(`left out the answer for ${key}: that question is no longer in ${basename(file)}`);
-    const promoted = new Set(readPromoted(file, say));
-    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined, dismissed: hidden.has(d.key), ...(promoted.has(d.key) && { promoted: true }) }));
+    // A discard holds while its card is hidden and nothing came after it: no restore, no plain dismiss, no answer or round.
+    const promoted = new Set(readPromoted(file, say)), discards = new Map(readDiscards(file).filter((x) => x.last && hidden.has(x.key)).map(({ key, reason, at }) => [key, { reason, at }]));
+    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined, dismissed: hidden.has(d.key), ...(discards.has(d.key) && { discarded: discards.get(d.key) }), ...(promoted.has(d.key) && { promoted: true }) }));
 }
 function ready(file, on, root) {
     if (!existsSync(file))
@@ -684,7 +706,7 @@ function list(args) {
     ];
     const where = tilde(file) + (existsSync(file) ? '' : ' (no file yet; raise creates it)');
     if (values.full) {
-        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: awaitsVerdict(d.type, d.answer) ? (d.dismissed ? 'dismissed' : d.type === 'evidence' ? 'shown' : d.kind === 'design' && !d.promoted ? 'in review' : 'waiting') : d.answer.answer, title: d.title, about: d.about ?? '', detail: d.detail ?? '',
+        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: awaitsVerdict(d.type, d.answer) ? (d.discarded ? `discarded: ${DISCARD_REASONS[d.discarded.reason]}` : d.dismissed ? 'dismissed' : d.type === 'evidence' ? 'shown' : d.kind === 'design' && !d.promoted ? 'in review' : 'waiting') : d.answer.answer, title: d.title, about: d.about ?? '', detail: d.detail ?? '',
                 recommend: d.recommend_value ?? '', default_if_silent: d.default_if_silent ?? '', close: d.close })) }, help);
     }
     return toon({
@@ -697,12 +719,16 @@ function list(args) {
 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));
+    // A card the person discarded, with their reason: it left the board and nothing more will come on it.
+    const gone = rows.flatMap((d) => (d.discarded ? [{ key: d.key, reason: d.discarded.reason, label: DISCARD_REASONS[d.discarded.reason], at: d.discarded.at, title: d.title }] : []));
     if (values.json) {
         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, notes, decisions, pick, replaces }) => [key, { answer, label, close, at, note, comments, notes, decisions, pick, replaces, ...(asked(key).length && { rounds: asked(key) }) }]));
         for (const r of rounds)
             if (!out[r.key])
                 out[r.key] = { rounds: asked(r.key) };
+        for (const { key, reason, label, at } of gone)
+            out[key] = { ...out[key], discarded: { reason, label, at } };
         return JSON.stringify(out);
     }
     const notes = done.some((a) => a.note), changed = done.some((a) => a.replaces), sent = [...done, ...rounds].flatMap(({ key, comments = [] }) => comments.map(({ mock, ref, tag, words, text }) => ({ key, mock, ref, tag, words, text })));
@@ -719,6 +745,7 @@ function printAnswers(file, rows, waiting, values, help) {
         ...(sent.length && { comments: sent }),
         // A plan's send-back: each section's verdict and note, and each decision's pick.
         ...(plan.length && { plan }),
+        ...(gone.length && { discarded: gone.map(({ key, label, at }) => ({ key, reason: label, at })) }),
         waiting,
     }, help);
 }
@@ -747,6 +774,17 @@ function eventLines(file, rows, answers, rounds) {
         ...rounds.map(({ key, note, at, comments }) => ({ at, line: { ...head('round', key), note, at, ...tail(key, comments) } }))]
         .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0)).map(({ line }) => JSON.stringify(line)).join('\n');
 }
+/** Discarded cards as the agent reads them: each key, the person's reason and when; nothing more will come on them. */
+function discardOut(file, gone, on, values) {
+    const rows = gone.map((d) => ({ key: d.key, title: d.title, reason: d.discarded.reason, label: DISCARD_REASONS[d.discarded.reason], at: d.discarded.at }));
+    if (values.events) {
+        const kind = kindOf(file);
+        return rows.map(({ key, title, reason, label, at }) => JSON.stringify({ event: 'discarded', ...kind(key), key, title, reason, label, at, ...(gone.find((d) => d.key === key).filer && { filer: gone.find((d) => d.key === key).filer }) })).join('\n');
+    }
+    if (values.json)
+        return JSON.stringify(Object.fromEntries(rows.map(({ key, reason, label, at }) => [key, { discarded: { reason, label, at } }])));
+    return toon({ board: tilde(file), discarded: rows.map(({ key, title, label, at }) => ({ key, reason: label, at, title })) }, ['The person discarded these cards: stop the work they asked for', `Run \`sign-off-axi wait${on}\` for the next answer`]);
+}
 /** Go deeper asks as the agent reads them: what part, what it is about, the question if the person typed one, and how to answer. */
 function deeperOut(file, asks, on, events) {
     if (events) {
@@ -919,6 +957,18 @@ async function wait(args) {
             if (found.length) {
                 return printAnswers(file, found, waiting, values, [waiting ? `Run \`sign-off-axi wait${on}\` for the next of the ${waiting} waiting` : filer !== undefined && rows.some((d) => d.guided) ? `Run \`sign-off-axi wait${on}\` for the next Go deeper ask` : `Run \`sign-off-axi stop${onBoard}\` to close the board`]);
             }
+            // A card the person discarded wakes the wait once its Undo window is over, so an undone discard never reaches the agent:
+            // the filer's own wait takes it (read), any other passes it on (delivered); a keyed wait reads it each time, as it reads an answer.
+            const trail = readTrail(file, loadDecisions(file)), sent = (d) => d.discarded && trail.find((t) => t.kind === 'discard' && t.key === d.key && t.at === d.discarded.at);
+            const untaken = (d) => { const t = sent(d); return !!t && (values.key !== undefined ? d.key === values.key : !(filer !== undefined ? t.read : t.delivered)); };
+            const gone = await locked(`${trailPath(file)}.lock`, () => {
+                const got = rows.filter((d) => untaken(d) && Date.now() - Date.parse(d.discarded.at) >= UNDO_MS);
+                for (const d of got)
+                    appendMark(file, { op: filer !== undefined ? 'read' : 'delivered', key: d.key });
+                return got;
+            }, 'another wait is still taking discards');
+            if (gone.length)
+                return discardOut(file, gone, on, values);
             // A Go deeper ask on this filer's guided page wakes the wait once, and is marked read when it is handed over.
             if (filer !== undefined) {
                 const asks = await locked(`${deeperPath(file)}.lock`, () => {
@@ -965,8 +1015,8 @@ async function wait(args) {
                 if (event)
                     return vaultEvent(file, [{ key: values.key, at: event.at, status: event.status }], values);
             }
-            // A dismissed ask is hidden from the board, not withdrawn: it is not counted as waiting, but the agent still waits on it.
-            if (values.key === undefined && !rows.some((d) => waits({ ...d, dismissed: false }) || (filer !== undefined && d.guided)) && !live && !unknown) {
+            // A dismissed ask is hidden from the board, not withdrawn: it is not counted as waiting, but the agent still waits on it. A discarded one is withdrawn once handed over.
+            if (values.key === undefined && !rows.some((d) => waits({ ...d, dismissed: !!d.discarded && !untaken(d) }) || (filer !== undefined && d.guided)) && !live && !unknown) {
                 throw fail(`nothing${filer ? ` posted by ${filer}` : ''} is waiting on ${tilde(file)}`, 'NOT_FOUND', `Run \`sign-off-axi answers${onBoard}\` to read the saved answers`, `Run \`sign-off-axi raise${on} --title "<question>"\` to ask a new one`);
             }
             const left = deadline - Date.now();
@@ -1261,9 +1311,12 @@ function dismiss(restoring) {
     const cmd = restoring ? 'restore' : 'dismiss';
     return (args) => {
         // dismiss --filer <id> closes a finished task: every card that filer still has waiting leaves the board.
-        const f = restoring ? -1 : args.findIndex((a) => a === '--filer'), filer = f < 0 ? undefined : args[f + 1], rest = f < 0 ? args : args.filter((_, i) => i !== f && i !== f + 1);
+        const flag = (name) => (restoring ? -1 : args.findIndex((a) => a === name)), f = flag('--filer'), r = flag('--reason');
+        const filer = f < 0 ? undefined : args[f + 1], reason = r < 0 ? undefined : args[r + 1], drop = [f, r].filter((x) => x >= 0).flatMap((x) => [x, x + 1]), rest = args.filter((_, i) => !drop.includes(i));
         if (f >= 0 && !isKey(filer))
             throw fail('--filer needs an id of 1-128 of A-Z a-z 0-9 . _ -', 'VALIDATION_ERROR', 'Pass the id you posted with');
+        if (r >= 0 && (f >= 0 || !Object.hasOwn(DISCARD_REASONS, reason ?? '')))
+            throw fail(f >= 0 ? '--reason discards one card, so it does not take --filer' : `--reason must be one of ${Object.keys(DISCARD_REASONS).join(', ')}`, 'VALIDATION_ERROR', 'sign-off-axi dismiss <key> --reason replaced');
         const at = rest.findIndex((a) => !a.startsWith('-') && !existsSync(a) && !a.endsWith('.json')), key = rest[at];
         if (at < 0 && f < 0)
             throw fail(`${cmd} needs a card key`, 'VALIDATION_ERROR', `sign-off-axi ${cmd} <key> [board.json]`);
@@ -1277,8 +1330,8 @@ function dismiss(restoring) {
             }
             if (!isKey(key) || !board(file).some((x) => x.key === key))
                 throw fail(`no card with key ${key} on ${tilde(file)}`, 'NOT_FOUND', `Run \`sign-off-axi list${on} --full\` to see the keys`);
-            appendDismissed(file, [key], !restoring);
-            return toon({ board: tilde(file), [restoring ? 'restored' : 'dismissed']: [key] }, [`Run \`sign-off-axi ${restoring ? 'dismiss' : 'restore'}${on} ${key}\` to undo`]);
+            appendDismissed(file, [key], !restoring, reason);
+            return toon({ board: tilde(file), [restoring ? 'restored' : reason ? 'discarded' : 'dismissed']: [key], ...(reason && { reason: DISCARD_REASONS[reason] }) }, [`Run \`sign-off-axi ${restoring ? 'dismiss' : 'restore'}${on} ${key}\` to undo`]);
         });
     };
 }
@@ -1334,14 +1387,24 @@ function feedback(args) {
  * What it prints carries the roll-up: a ticket with tickets under it is as far along as they are on average. */
 function ticket(args) {
     const { file, values, on } = parse('ticket', args, { id: { type: 'string' }, title: { type: 'string' }, progress: { type: 'string' }, parent: { type: 'string' }, priority: { type: 'string' },
-        project: { type: 'string' }, hold: { type: 'string' }, asked: { type: 'string' }, comment: { type: 'string' }, json: { type: 'boolean' } });
+        project: { type: 'string' }, hold: { type: 'string' }, asked: { type: 'string' }, release: { type: 'string' }, state: { type: 'string' }, pr: { type: 'string', multiple: true }, comment: { type: 'string' }, json: { type: 'boolean' } });
     if (values.comment !== undefined)
         return ticketComment(file, values, on);
-    const { id, title, parent } = values, write = [title, values.progress, parent, values.priority, values.project, values.hold, values.asked].some((v) => v !== undefined);
+    const { id, title, parent } = values, write = [title, values.progress, parent, values.priority, values.project, values.hold, values.asked, values.release, values.state, values.pr].some((v) => v !== undefined);
     if (id === undefined && write)
-        throw fail('--title, --progress, --parent, --priority, --project, --hold and --asked need --id <ticket id>', 'VALIDATION_ERROR', 'sign-off-axi ticket --id T-29 --title "Ship the new settings page" --progress 40');
-    const cardsOf = (t) => board(file).filter((d) => d.ticket === t.id && !d.dismissed).reverse().sort((x, y) => (Date.parse(y.filed ?? '') || 0) - (Date.parse(x.filed ?? '') || 0));
-    const row = (t) => ({ id: t.id, title: t.title, progress: t.progress, parent: t.parent ?? '', priority: t.priority ?? '', project: t.project ?? '', hold: t.hold ? 'yes' : 'no', asked: t.asked ? 'yes' : 'no' });
+        throw fail('--title, --progress, --parent, --priority, --project, --hold, --asked, --release, --state and --pr need --id <ticket id>', 'VALIDATION_ERROR', 'sign-off-axi ticket --id T-29 --title "Ship the new settings page" --progress 40');
+    // The board is read once per command, and its warnings print once, however many tickets name cards.
+    let byTicket;
+    const cardsOf = (t) => {
+        if (!byTicket) {
+            byTicket = new Map();
+            for (const d of board(file))
+                if (d.ticket !== undefined && !d.dismissed)
+                    byTicket.set(d.ticket, [...(byTicket.get(d.ticket) ?? []), d]);
+        }
+        return [...(byTicket.get(t.id) ?? [])].reverse().sort((x, y) => (Date.parse(y.filed ?? '') || 0) - (Date.parse(x.filed ?? '') || 0));
+    };
+    const row = (t) => ({ id: t.id, title: t.title, progress: t.progress, parent: t.parent ?? '', priority: t.priority ?? '', project: t.project ?? '', hold: t.hold ? 'yes' : 'no', asked: t.asked ? 'yes' : 'no', release: t.release ?? '', state: t.state ?? '', prs: t.prs ?? [] });
     if (id === undefined) {
         const all = rollUp(readTickets(file, warn));
         if (values.json)
@@ -1371,14 +1434,14 @@ function ticket(args) {
             throw fail(`no ticket ${id} on ${tilde(file)} yet: a new ticket needs --title`, 'VALIDATION_ERROR', `sign-off-axi ticket${on} --id ${id} --title "<what the work is>" --progress 0`);
         // A later write changes only what it gives; an empty --parent, --priority, --project, --hold or --asked takes that field off.
         const next = { ...had, id, title: title ?? had.title, progress: progress ?? had?.progress ?? 0 };
-        for (const [k, v] of Object.entries({ parent, priority: values.priority, project: values.project, hold: yesNo(values.hold), asked: yesNo(values.asked) }))
+        for (const [k, v] of Object.entries({ parent, priority: values.priority, project: values.project, hold: yesNo(values.hold), asked: yesNo(values.asked), release: values.release, state: values.state, prs: values.pr === undefined ? undefined : values.pr.every((v) => v === '') ? '' : [...new Set(values.pr.flatMap((v) => v.split(',').map((u) => u.trim())))] }))
             if (v === '')
                 delete next[k];
             else if (v !== undefined)
                 next[k] = v;
         const fault = ticketFault(next);
         if (fault)
-            throw fail(`ticket ${id}: ${fault.replace(/^(title|progress|parent|priority|project|hold|asked)/, '--$1').replace('must be true or false', 'must be yes or no')}`, 'VALIDATION_ERROR', 'Run `sign-off-axi ticket --help`');
+            throw fail(`ticket ${id}: ${fault.replace(/^(title|progress|parent|priority|project|hold|asked|release|state|prs)/, '--$1').replace(/^--prs\b/, '--pr').replace('must be true or false', 'must be yes or no')}`, 'VALIDATION_ERROR', 'Run `sign-off-axi ticket --help`');
         const same = had && JSON.stringify(row(had)) === JSON.stringify(row(next));
         if (!same)
             appendTicket(file, next);
@@ -1391,7 +1454,7 @@ function ticketComment(file, values, on) {
     const { id } = values, EXAMPLE = `sign-off-axi ticket${on} --id T-29 --comment '{"id":"3f9a1c2e7b6d4a10","at":1792820000,"text":"Is the export in this?","error":null,"picked":1792820300,"replies":[]}'`;
     if (id === undefined || !isKey(id))
         throw fail('--comment needs --id <ticket id>, 1-128 of A-Z a-z 0-9 . _ -', 'VALIDATION_ERROR', EXAMPLE);
-    if (['title', 'progress', 'parent', 'priority', 'project', 'hold', 'asked'].some((k) => values[k] !== undefined))
+    if (['title', 'progress', 'parent', 'priority', 'project', 'hold', 'asked', 'release', 'state', 'pr'].some((k) => values[k] !== undefined))
         throw fail('--comment is written on its own, with no other ticket field', 'VALIDATION_ERROR', EXAMPLE);
     let c;
     try {
@@ -2434,16 +2497,52 @@ function init(args) {
         `Run \`sign-off-axi doctor ${shellPath(dir)}\` to check the setup`, `Run \`sign-off-axi open ${shellPath(board)}\` to show the board to the user`
     ]);
 }
+/** What each part of a report 5 asks for, as its template's FILL lines, and whether it reads as what was found or what is recommended; the items a part needs come with it. */
+const PART_FILL = {
+    question: ['the question, and why it matters now', 'found'], scope: ['what is in and what is out', 'found'], method: ['how you looked: what you read, ran and asked', 'found'],
+    sources: ['where the answers come from', 'found', [
+            { title: 'FILL: a primary source (docs, code, a maintainer)', text: 'FILL: what it says, in one line', link: 'FILL: https link', source: 'primary' },
+            { title: 'FILL: another primary source', text: 'FILL: what it says', link: 'FILL: https link', source: 'primary' },
+            { title: 'FILL: what users report (an issue, a forum, Reddit, Hacker News)', text: 'FILL: what they say, with how many', link: 'FILL: https link', source: 'user' }
+        ]],
+    options: ['the options, on the same axes', 'found', [
+            { title: 'FILL: option A', text: 'FILL: its pros and cons in one line', more: 'FILL: Cost: value.\nFILL: Setup: value.' },
+            { title: 'FILL: option B', text: 'FILL: its pros and cons in one line', more: 'FILL: Cost: value.\nFILL: Setup: value.' }
+        ]],
+    findings: ['what you found', 'found', [{ title: 'FILL: one finding', text: 'FILL: one line, with its source', confidence: 'medium' }]],
+    'not-checked': ['what you did not check, and what you could not read', 'found'],
+    recommendation: ['what you recommend, and the runner-up', 'recommend'], 'open-questions': ['what is still open', 'recommend'],
+    goal: ['the goal, and what is not a goal', 'found'], current: ['how it works today', 'found'],
+    design: ['the design, with its diagram', 'recommend'], slices: ['the slices, in order, each with its size', 'recommend', [{ title: 'FILL: slice 1', text: 'FILL: what ships in it', size: 'FILL: S, half a day' }]],
+    tests: ['how each slice is tested and proven', 'recommend', [{ title: 'FILL: slice 1', text: 'FILL: the test, and the proof that it works' }]],
+    risks: ['each risk, and how you roll back', 'recommend'], rollout: ['how it reaches people', 'recommend'], estimate: ['how long it takes, as a range', 'recommend'],
+    'owner-calls': ['what you need the user to decide', 'recommend'], context: ['the forces at play, said plainly', 'found'],
+    consequences: ['what follows from the choice, good and bad', 'recommend'], standard: ['the standard checked against, with its link', 'found'],
+    fixes: ['what to fix, most urgent first', 'recommend'], impact: ['who was hurt, how much and for how long', 'found'],
+    timeline: ['what happened, in order, with times', 'found', [{ title: 'FILL: 09:12', text: 'FILL: what happened' }]], 'root-cause': ['why it happened (the system, not a person)', 'found'],
+    actions: ['what changes so it does not happen again', 'recommend'], done: ['what is done', 'found'], 'in-progress': ['what is in progress', 'found'],
+    blocked: ['what is held up, and on what', 'found'], 'up-next': ['what comes next', 'recommend'],
+};
+/** A report 5's sections for its kind: one per part, each a FILL line naming what it asks for; the plan's design carries a diagram to draw. */
+const kindSections = (purpose) => REPORT_PARTS[purpose].map(([part, name]) => {
+    const [ask, stage, items] = PART_FILL[part];
+    return { id: part, part, stage, heading: `FILL: ${name}: ${ask}`, body: `FILL: ${ask}, in a line or two`, ...(items && { items }),
+        ...(purpose === 'plan' && part === 'design' && { diagram: [{ label: 'Flow', src: 'FILL: diagrams/flow.html, inline SVG in light and dark' }] }) };
+});
 /** report init <folder>: the guided template (report.json, or plan.json with --plan) to fill in, or with --page the older scaffold page and its picture. */
 function report(args) {
     let parsed;
     try {
-        parsed = parseArgs({ args, allowPositionals: true, strict: true, options: { plan: { type: 'boolean' }, page: { type: 'boolean' } } });
+        parsed = parseArgs({ args, allowPositionals: true, strict: true, options: { plan: { type: 'boolean' }, page: { type: 'boolean' }, purpose: { type: 'string' } } });
     }
     catch (e) {
         throw fail(e.message, 'VALIDATION_ERROR', 'Run `sign-off-axi report --help`');
     }
-    const [sub, dir, extra] = parsed.positionals, { plan, page } = parsed.values;
+    const [sub, dir, extra] = parsed.positionals, { plan, page, purpose } = parsed.values;
+    if (purpose !== undefined && (plan || page))
+        throw fail(`--purpose does not go with --${plan ? 'plan' : 'page'}: ${plan ? 'a plan is always an implementation plan' : 'a page report has no purpose field'}`, 'VALIDATION_ERROR', 'sign-off-axi report init <folder> --purpose research');
+    if (purpose !== undefined && !REPORT_PURPOSES.includes(purpose))
+        throw fail(`--purpose ${purpose} must be one of ${REPORT_PURPOSES.join(', ')}`, 'VALIDATION_ERROR', 'sign-off-axi report init <folder> --purpose research');
     if (sub !== 'init' || dir === undefined || extra !== undefined || (plan && page)) {
         throw fail(sub !== 'init' ? `unknown report command ${sub ?? '(none)'}` : extra !== undefined ? `unexpected argument ${extra}: report init takes one folder` : plan && page ? '--plan and --page do not go together' : 'report init needs the folder to write the template in', 'VALIDATION_ERROR', 'sign-off-axi report init <folder> [--plan]');
     }
@@ -2457,10 +2556,14 @@ function report(args) {
             kept.push(shellPath(path));
         else {
             const filed = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
-            writeFileSync(path, readFileSync(new URL(`../web/${kind}-template.json`, import.meta.url), 'utf8').replace('"FILL: UTC time"', JSON.stringify(filed)), { flag: 'wx' });
+            const template = readFileSync(new URL(`../web/${kind}-template.json`, import.meta.url), 'utf8').replace('"FILL: UTC time"', JSON.stringify(filed));
+            // With --purpose the template holds that kind's parts, one section each; with none, the general shape and purpose to fill.
+            const kinded = purpose && { ...JSON.parse(template), purpose, ...(REPORT_PARTS[purpose].length && { sections: kindSections(purpose) }) };
+            writeFileSync(path, kinded ? `${JSON.stringify(kinded, null, 2)}\n` : template, { flag: 'wx' });
             created.push(shellPath(path));
         }
         return toon({ folder: shellPath(out), created: created.length ? created : 'nothing new (re-run is a no-op)', kept }, [
+            ...(plan || purpose ? [] : [`Set "purpose" to what the report is for: ${REPORT_PURPOSES.join(', ')} (or run report init again with --purpose <kind> in a new folder)`]),
             `Replace every FILL: line in ${kind}.json with your own words: the answer first, one picture (bars, steps or tiles), what you understood, then the sections${plan ? ' and the decisions' : ''}`,
             `${plan ? 'A plan' : 'A design or architecture report'} needs one real diagram: a flow or architecture drawing as inline SVG, in light and dark, as "diagram" on the visual (see the skill)`,
             'Keep each line short: the board shows it in one scroll, the numbers behind a Details tap and the long answer behind Go deeper',
@@ -2975,6 +3078,7 @@ const state = () => {
         readonly: extra.readonly === true,
         answers_only: extra.answers_only === true,
         ...profile(),
+        version: VERSION.label,
         answers,
         seen: Object.values(answers).filter(taken).map((a) => a.key),
         seen_at: Object.fromEntries(Object.values(answers).flatMap((a) => { const t = seenAt(file)(a); return t ? [[a.key, t]] : []; })),
@@ -2987,6 +3091,7 @@ const state = () => {
         annotations: fed ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
         comments: extra.readonly === true ? [] : readPartComments(file),
         dismissed: readDismissed(file, answers, rounds, warn, fed ? [] : items),
+        discarded: Object.fromEntries(readDiscards(file).filter((x) => x.last).map(({ key, reason, at }) => [key, { reason, at }])),
         promoted: readPromoted(file, warn),
         tickets: rollUp(readTickets(file, warn)),
         projects: readProjects(file, warn),
@@ -3343,13 +3448,15 @@ async function route(req) {
         return [200, state()];
     }
     if (req.url === '/api/dismiss') {
-        const { keys, dismissed } = JSON.parse(body) ?? {};
+        const { keys, dismissed, reason } = JSON.parse(body) ?? {};
         if (!Array.isArray(keys) || !keys.length || keys.length > 200 || typeof dismissed !== 'boolean')
             return [400, { error: 'Send 1 to 200 keys and dismissed true or false' }];
+        if (reason !== undefined && (!dismissed || !Object.hasOwn(DISCARD_REASONS, reason)))
+            return [400, { error: `A discard's reason is one of ${Object.keys(DISCARD_REASONS).join(', ')}` }];
         const have = new Map(board(file).map((x) => [x.key, x]));
         if (!keys.every((k) => isKey(k) && have.has(k)))
             return [404, { error: 'This item is no longer in the file' }];
-        appendDismissed(file, [...new Set(keys)], dismissed);
+        appendDismissed(file, [...new Set(keys)], dismissed, reason);
         return [200, state()];
     }
     if (req.url === '/api/engagement' || req.url === '/api/engagement/seen') {
@@ -3641,7 +3748,7 @@ if (argv[0]?.startsWith('-') && !['--help', '-v', '-V', '--version'].includes(ar
     argv.unshift('list');
 await runAxiCli({
     description: 'Ask the user yes/no or pick-one questions on one local board and read their answers back',
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    version: VERSION.version,
     argv,
     topLevelHelp: TOP_HELP,
     getCommandHelp: (cmd) => HELP[cmd],

package/dist/contract.js

@@ -2,7 +2,7 @@
 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, PRIORITIES, REPORT_FORMS } from './store.js';
+import { isKey, MEDIA_MAX, PRIORITIES, REPORT_FORMS, REPORT_PARTS, REPORT_PURPOSES } 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;
@@ -12,11 +12,13 @@ export class ContractError extends Error {
     }
 }
 /** The kinds, with the schema number of each. */
-export const SCHEMAS = { ask: 1, report: 4, evidence: 1, gate: 1, finding: 1, plan: 3, design: 1 };
-/** Older schemas this sign-off-axi still takes, so a board that holds them loads and re-posts: the page-based report 2 and plan 1. */
-const OLDER = { report: [2, 3], plan: [1, 2] };
+export const SCHEMAS = { ask: 1, report: 5, evidence: 1, gate: 1, finding: 1, plan: 3, design: 1 };
+/** Older schemas this sign-off-axi still takes, so a board that holds them loads and re-posts: the page-based report 2, the guided report 3 and 4 (4 with no purpose), and plan 1 and 2. */
+const OLDER = { report: [2, 3, 4], plan: [1, 2] };
 /** The guided schemas: a report 3 and a plan 2 are fields the board draws as one guided page, not a page the agent draws. */
-export const guided = (m) => (m?.kind === 'report' && [3, 4].includes(m.schema)) || (m?.kind === 'plan' && [2, 3].includes(m.schema));
+export const guided = (m) => (m?.kind === 'report' && [3, 4, 5].includes(m.schema)) || (m?.kind === 'plan' && [2, 3].includes(m.schema));
+/** The schemas with versioned engagement, whose owning filer is required: report 4 and 5, plan 3. */
+export const engaged = (m) => (m?.kind === 'report' && [4, 5].includes(m.schema)) || (m?.kind === 'plan' && m.schema === 3);
 export const KINDS = Object.keys(SCHEMAS);
 const COMMON = ['contract', 'kind', 'schema', 'key', 'title', 'filer', 'ticket', 'priority', 'link', 'about'];
 const FIELDS = {
@@ -30,7 +32,7 @@ const FIELDS = {
 };
 const GUIDE = ['understood', 'visual', 'sections', 'next'];
 const GUIDE_FIELDS = {
-    report: [...COMMON, 'filed', 'group', 'decided', 'asked_by', ...GUIDE],
+    report: [...COMMON, 'filed', 'group', 'decided', 'asked_by', 'purpose', ...GUIDE],
     plan: [...COMMON, 'project', 'decisions', ...GUIDE],
 };
 /** A done-done run: its id, full commit and the four Checks lines. */
@@ -223,6 +225,32 @@ export function checkMessage(m, want, flags = false) {
         if (/^([\\/]|[A-Za-z]:)/.test(o.src) || o.src.split(/[\\/]/).includes('..') || /[?#\\]/.test(o.src) || !/\.html?$/i.test(o.src))
             throw bad(`${field}[${n}].src`, `${show(o.src)} must be a relative .html path with no .., ?, # or \\`, 'Draw the diagram as inline SVG in an .html page (by hand or with the archify skill), then set "src" to that file next to the message');
     });
+    /** A report 5's parts: each part of its kind once, in a section naming it, with what that part needs (a source's link, a finding's confidence, a slice's size, a design's diagram). */
+    const kindParts = (parts) => {
+        const init = `Run \`${REPORT_INIT.replace('<folder>', '<new folder>')} --purpose ${m.purpose}\` for a template with every part, or add the section`;
+        const of = (part) => m.sections.findIndex((o) => o.part === part), items = (part) => m.sections[of(part)].items ?? [];
+        for (const [part, name] of parts) {
+            const at = of(part), twice = m.sections.findIndex((o, n) => o.part === part && n > at);
+            if (at < 0)
+                throw bad('sections', `has no ${show(part)} part (${name}): a ${m.purpose} report needs ${parts.map(([p]) => p).join(', ')}`, `Add a section with "part": ${show(part)}, ${name.toLowerCase()}. ${init}`);
+            if (twice >= 0)
+                throw bad(`sections[${twice}].part`, `repeats ${part}`, 'Give each part one section');
+        }
+        const need = (part, ok, rule, help) => { if (!ok)
+            throw bad(`sections[${of(part)}]`, `(${part}) ${rule}`, help); };
+        if (m.purpose === 'research') {
+            need('sources', items('sources').length >= 3 && items('sources').every((it) => it.link && it.source), 'must list at least 3 sources, each with its "link" and "source"', 'List each source as an item with "link" (where to read it) and "source": "primary" (docs, code, a maintainer) or "user" (what users report)');
+            need('sources', items('sources').some((it) => it.source === 'user'), 'must hold at least one user report ("source": "user")', 'Add what users report, with its link: a GitHub issue, a forum thread, Reddit, Hacker News or X; if a site blocked you, say so in "not-checked"');
+            need('options', items('options').length >= 2, 'must compare at least 2 options, one item each', 'Give each option an item with the same axes in "more", one "Axis: value." per line, so the board draws one table');
+            need('findings', items('findings').length >= 1 && items('findings').every((it) => it.confidence), 'must list each finding with its "confidence"', 'Give each finding an item with "confidence": "high", "medium" or "low"');
+        }
+        if (m.purpose === 'plan') {
+            const d = m.sections[of('design')];
+            need('design', !!(d.diagram || (d.items ?? []).some((it) => it.diagram) || m.visual?.diagram), 'needs a diagram (on the section, an item or the visual)', 'Draw the design as inline SVG in an .html page and add "diagram": [{"label": "Flow", "src": "diagrams/flow.html"}] (see the skill)');
+            need('slices', items('slices').length >= 1 && items('slices').every((it) => it.size), 'must list each slice with its "size"', 'Give each slice an item with "size", such as "S, half a day"');
+            need('tests', items('tests').length >= 1, 'must list how each slice is tested and proven', 'Add an item per slice: the test and the proof that it works');
+        }
+    };
     /** The guided page every plan 2 and report 3 is: what I understood, one picture, sections with expandable items, and the next step. Returns the section ids. */
     const guide = (minSections) => {
         list('understood', 1, 6, ['label', 'text'], '{"label":"You asked","text":"Make the first start smooth."}').forEach((o, n) => {
@@ -267,7 +295,9 @@ export function checkMessage(m, want, flags = false) {
             details('visual.details', v.details);
         if (Object.hasOwn(v, 'diagram'))
             diagrams('visual.diagram', v.diagram);
-        const ids = list('sections', minSections, 6, ['id', 'stage', 'heading', 'body', 'items', 'details', 'diagram'], '{"id":"steps","stage":"recommend","heading":"Eight steps, 22 to 31 Oct","body":"..."}').map((o, n) => {
+        // A report 5 is built of its kind's parts: up to 10 sections, each naming the part it is, and items that carry a source's link, a finding's confidence or a slice's size.
+        const v5 = m.kind === 'report' && m.schema >= 5, parts = v5 ? REPORT_PARTS[m.purpose] ?? [] : [];
+        const ids = list('sections', minSections, v5 ? 10 : 6, ['id', 'stage', 'heading', 'body', 'items', 'details', 'diagram', ...(v5 ? ['part'] : [])], '{"id":"steps","stage":"recommend","heading":"Eight steps, 22 to 31 Oct","body":"..."}').map((o, n) => {
             const at = `sections[${n}]`;
             if (!(typeof o.id === 'string' && /^[a-z0-9-]{1,40}$/.test(o.id)))
                 throw bad(`${at}.id`, 'must be 1-40 of a-z 0-9 -', 'Set "id" to a short slug such as "steps"');
@@ -275,8 +305,11 @@ export function checkMessage(m, want, flags = false) {
                 throw bad(`${at}.stage`, `${show(o.stage)} is not found or recommend`, 'Set "stage" to "found" (what I found) or "recommend" (what I recommend)');
             text(`${at}.heading`, o.heading, 80, 'the section heading, in 80 characters or fewer');
             text(`${at}.body`, o.body, 300, 'the section\'s lead, in 300 characters or fewer');
+            if (Object.hasOwn(o, 'part') && !parts.some(([p]) => p === o.part)) {
+                throw bad(`${at}.part`, parts.length ? `${show(o.part)} is not a part of a ${m.purpose} report: ${parts.map(([p]) => p).join(', ')}` : `is not used by a report whose purpose is ${m.purpose}`, parts.length ? `Set "part" to the part this section is, one of ${parts.map(([p]) => p).join(', ')}` : 'Remove "part"');
+            }
             if (Object.hasOwn(o, 'items'))
-                list(`${at}.items`, 1, 8, ['title', 'text', 'more', 'tone', 'diagram'], '{"title":"Ship 0.2.5","text":"You test it.","more":"..."}', o.items).forEach((it, k) => {
+                list(`${at}.items`, 1, 8, ['title', 'text', 'more', 'tone', 'diagram', ...(v5 ? ['link', 'source', 'confidence', 'size'] : [])], '{"title":"Ship 0.2.5","text":"You test it.","more":"..."}', o.items).forEach((it, k) => {
                     text(`${at}.items[${k}].title`, it.title, 80, 'the item, in 80 characters or fewer');
                     text(`${at}.items[${k}].text`, it.text, 160, 'one line under it, in 160 characters or fewer');
                     if (Object.hasOwn(it, 'more'))
@@ -284,6 +317,14 @@ export function checkMessage(m, want, flags = false) {
                     tone(`${at}.items[${k}]`, it);
                     if (Object.hasOwn(it, 'diagram'))
                         diagrams(`${at}.items[${k}].diagram`, it.diagram);
+                    if (Object.hasOwn(it, 'link') && !(typeof it.link === 'string' && /^https?:\/\/[^\s\p{Cc}\p{Cs}]{1,500}$/u.test(it.link)))
+                        throw bad(`${at}.items[${k}].link`, 'must be an http(s) link with no spaces', 'Set "link" to where the source can be read, such as "https://github.com/owner/repo/issues/12"');
+                    if (Object.hasOwn(it, 'source') && !['user', 'primary'].includes(it.source))
+                        throw bad(`${at}.items[${k}].source`, `${show(it.source)} is not user or primary`, 'Set "source" to "user" (what users report: an issue, a forum, Reddit, Hacker News) or "primary" (docs, code, a maintainer\'s answer, your own check)');
+                    if (Object.hasOwn(it, 'confidence') && !['high', 'medium', 'low'].includes(it.confidence))
+                        throw bad(`${at}.items[${k}].confidence`, `${show(it.confidence)} is not high, medium or low`, 'Set "confidence" to how sure you are of the finding: "high", "medium" or "low"');
+                    if (Object.hasOwn(it, 'size'))
+                        text(`${at}.items[${k}].size`, it.size, 24, 'how big the slice is, such as "S, half a day", in 24 characters or fewer');
                 });
             if (Object.hasOwn(o, 'details'))
                 details(`${at}.details`, o.details);
@@ -294,6 +335,8 @@ export function checkMessage(m, want, flags = false) {
         const twice = ids.findIndex((id, n) => ids.indexOf(id) < n);
         if (twice >= 0)
             throw bad(`sections[${twice}].id`, `repeats ${ids[twice]}`, 'Give every section its own id');
+        if (parts.length)
+            kindParts(parts);
         if (!Object.hasOwn(m, 'next'))
             throw bad('next', 'is required', 'Add "next": {"heading":"Go ahead, and I start on 22 Oct","lines":["..."]}');
         one('next', m.next, ['heading', 'lines'], '{"heading":"...","lines":["..."]}');
@@ -320,7 +363,8 @@ export function checkMessage(m, want, flags = false) {
         throw bad('schema', `${m.schema} of ${m.kind} is not in this sign-off-axi`, `Upgrade sign-off-axi, or post ${m.kind} schema ${SCHEMAS[m.kind]}`);
     if (g && /FILL:/.test(JSON.stringify(m)))
         throw bad('message', 'still has FILL: lines from the template', 'Replace every FILL: line with your own words, then post again');
-    const fields = guided(m) ? GUIDE_FIELDS[m.kind] : FIELDS[m.kind], extra = Object.keys(m).find((f) => !fields.includes(f));
+    // A guided report 5 names what it is for; report 4 and older have no purpose field.
+    const fields = (guided(m) ? GUIDE_FIELDS[m.kind] : FIELDS[m.kind]).filter((f) => f !== 'purpose' || (m.kind === 'report' && m.schema >= 5)), 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 === 'options' && m.kind === 'plan')
@@ -332,7 +376,7 @@ export function checkMessage(m, want, flags = false) {
     if (!Object.hasOwn(m, 'title'))
         throw bad('title', 'is required', 'Add "title": the question, in 160 characters or fewer');
     text('title', m.title, 160, 'the question, in 160 characters or fewer');
-    if (g && m.schema === SCHEMAS[m.kind] && !isKey(m.filer))
+    if (engaged(m) && !isKey(m.filer))
         throw bad('filer', 'is required', 'Set "filer" to the owning agent id');
     if (Object.hasOwn(m, 'filer') && !isKey(m.filer))
         throw bad('filer', 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "filer" to your agent session id or tool name, or leave it out');
@@ -383,6 +427,13 @@ export function checkMessage(m, want, flags = false) {
             text('video', m.video, 10, 'the video length such as "0:28", in 10 characters or fewer, or leave it out');
         if (Object.hasOwn(m, 'asked_by'))
             text('asked_by', m.asked_by, 40, 'who asked for it, such as "You asked" or "Docs agent", in 40 characters or fewer, or leave it out');
+        if (m.schema >= 5) {
+            const set = `Set "purpose" to what this report is for, one of ${REPORT_PURPOSES.join(', ')}`;
+            if (!Object.hasOwn(m, 'purpose'))
+                throw bad('purpose', 'is required: the kind of report, which the board shows on its row and head', set);
+            if (!REPORT_PURPOSES.includes(m.purpose))
+                throw bad('purpose', `${show(m.purpose)} is not one of ${REPORT_PURPOSES.join(', ')}`, set);
+        }
         // A report is a page to tap through and a picture of it for the card: text alone is a status note, not a report.
         if (g) {
             guide(1);