@erclx/canon 5.39.0 → 5.41.0

package/src/commands/pr.ts

@@ -57,6 +57,7 @@ import {
   pruneFramesWithLegacy,
   pushFrame,
   readFrame,
+  referenceSlug,
   type TreeEntry,
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -69,7 +70,9 @@ import {
   type LiftRefusal,
   type PullState,
   readBaseStanding,
+  readChangedPaths,
 } from '@/pr/lift'
+import { loadPaintedPatterns } from '@/pr/painted'
 import {
   dropAddressLine,
   findLocalServer,
@@ -182,6 +185,7 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
 interface FramesOptions extends ReadOptions {
   readonly add?: string
   readonly box?: string
+  readonly reference?: string
   readonly head?: string
   readonly pass?: string
   readonly theme?: string
@@ -194,6 +198,7 @@ type FramesCommandRefusal =
   | 'bad-mode'
   | 'no-number'
   | 'bad-box'
+  | 'bad-reference'
   | 'bad-head'
   | 'bad-pass'
   | 'bad-theme'
@@ -210,13 +215,15 @@ const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
   'no-number':
     '--add and --drop write for one pull request, so name its number.',
   'bad-box':
-    '--add takes --box <n>, a positive whole number naming the checklist box.',
+    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference <page>/<frame>, never both.',
+  'bad-reference':
+    '--reference takes <page>/<frame>, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
   'bad-head':
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
     '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
   'bad-theme':
-    '--theme takes dark or light and goes with --add, so a second shot of one box never replaces the first.',
+    '--theme takes dark or light and goes with --add --box, so a second shot of one box never replaces the first.',
   'bad-days': '--prune takes a positive whole number of days.',
   'unreadable-frame':
     'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
@@ -421,6 +428,24 @@ export function register(program: Command): void {
         'points the change at a locative the path does not name. Read the bullet on',
         "the record's preview before filing an unmet path as a stale claim.",
         '',
+        'Refusals, read off `reason`:',
+        '  no-section          the body carries no `## Key changes` heading, so it',
+        '                      claims nothing',
+        '  no-claims           the heading is there and no span resolved, which is',
+        '                      the extractor failing over prose and raises nothing',
+        '  no-changes          the pull request changed no files, so no claim has',
+        '                      anything to answer',
+        '  unreadable-body     the pull request body could not be read',
+        '  unreadable-tree     the file tree of the head could not be read',
+        '  no-base             GitHub reported no merge base for the pull request',
+        '  bad-base            `--base` names a ref sharing no history with HEAD',
+        '  unreadable-changes  the changed files could not be listed',
+        '  ambiguous-pull      two open pull requests share the branch against',
+        '                      different bases, so name a number',
+        '  gh-missing          `gh` is not on the path, so no pull request could be',
+        '                      resolved',
+        '  gh-failed           `gh` could not answer for this repository or branch',
+        '',
         'Exit codes:',
         '  0  every claimed path is in the diff',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -455,6 +480,17 @@ export function register(program: Command): void {
         'tip from the remote with `git ls-remote` and reports which commit each',
         'source names.',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'Read the verdict off the record rather than off the exit. A stale head',
         'exits 0, because an operator shell profile can wrap this binary in a',
         'function whose status comes from a trailing command.',
@@ -492,6 +528,19 @@ export function register(program: Command): void {
         'an empty row list, and reading that as passing is the false green the',
         'sha key alone does not close.',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  runs-unreadable   the check runs for the tip could not be read, which is',
+        '                    unread rather than none',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'A branch conflicting with its base gets no merge ref, so no run ever',
         'starts for it and the state stays pending. The record carries',
         '`conflicted: true` beside it when `mergeStateStatus` reads DIRTY and no',
@@ -538,6 +587,19 @@ export function register(program: Command): void {
         '  fallback  a pass posted before the marker shipped, off GitHub stamps',
         '  none      the thread carries no pass, so the next one is a first pass',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  reviews-unreadable  the reviews could not be parsed, which is unread',
+        '                      rather than none',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'Exit codes:',
         '  0  the thread was read, whether it carries a pass or not',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -656,6 +718,17 @@ export function register(program: Command): void {
         'The record carries `owed` and the same marked fields. --check refuses',
         'with --preview, --local, or --checklist as check-writes.',
         '',
+        'Refusals, read off `reason`:',
+        '  unreadable-checklist  --checklist named a path that could not be read,',
+        '                        or one holding nothing',
+        '  no-branch             the pull request carries no head branch name',
+        '  no-base               GitHub reported no merge base for the pull request',
+        '  unreadable-changes    GitHub could not list what the pull request changed',
+        '  gh-missing            `gh` is not on the path',
+        '  gh-failed             `gh` could not read or edit the pull request or its',
+        '                        comments',
+        '  no-object-head        the pull request object reported no head commit',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body, reported no-evidence, or checked',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -696,7 +769,11 @@ export function register(program: Command): void {
         'they are read:',
         '  review    the newest `## Review` is closed at the head, off its marker',
         '  ui        the newest `## UI review` is closed at the head, bound only',
-        '            where `canon pr evidence --check` carries a checklist',
+        '            where `canon pr evidence --check` carries a checklist. A close',
+        '            on an earlier commit still holds when it is an ancestor of the',
+        '            head and no painted path changed since, and the record names',
+        '            it as `carriedFrom`. A painted change refuses `ui-behind` and',
+        '            lists the paths as `paintedPaths`',
         '  evidence  the evidence check reads settled',
         '  standing  the head is fresh against the base, not stale or conflicted',
         '  ci        every check run on the tip passed, waited on up to --wait',
@@ -705,8 +782,21 @@ export function register(program: Command): void {
         'wait, so a reviewer whose partner is still driving refuses at once. The',
         'head and the reviews are read again before the mutation.',
         '',
+        'Painted paths are what a browser renders (`.tsx`, `.jsx`, `.vue`,',
+        '`.svelte`, `.astro`, `.html`, `.css`, `.scss`, `.svg`, images, fonts)',
+        'minus test, spec, and story files. A project adds to or trims the list',
+        'in `canon/config/painted.json` as `{ "painted": [glob], "unpainted":',
+        '[glob] }`.',
+        '',
+        'A pull request that is already ready has the review, ui, and evidence',
+        'gates read too. One that reads not clear returns to draft with reason',
+        '`redrafted` and the failing reason as `failed`, exit 1. Standing and CI',
+        'are reported and never cause a re-draft. A ready pull request that',
+        'clears reports `already-ready`, exit 0. Under --check nothing is',
+        'written and the first failing reason is reported.',
+        '',
         'Reasons:',
-        '  lifted, already-ready, clear (--check)',
+        '  lifted, already-ready, redrafted, clear (--check)',
         '  pull-closed, review-missing, review-open, review-unmarked,',
         '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
         '  evidence-owed, standing-stale, standing-conflict, standing-unknown,',
@@ -784,6 +874,15 @@ export function register(program: Command): void {
         '  building    a deploy of the tip is still running, so wait',
         '  no-build    no deploy of this branch has succeeded',
         '',
+        'Refusals before either read, read off `reason`:',
+        '  bad-timeout         --timeout was not a positive number',
+        '  check-timeout       --check was combined with --timeout',
+        '  no-branch           the pull request carries no head branch name',
+        '  unreadable-changes  the changed paths of the pull request could not be read',
+        '  gh-missing          `gh` is not on the path',
+        '  gh-failed           `gh` could not read the pull request, or list or',
+        '                      dispatch the workflow',
+        '',
         'Exit codes:',
         '  0  a preview was published, or --check read fresh',
         '  1  refused, or --check read anything but fresh',
@@ -838,6 +937,10 @@ export function register(program: Command): void {
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
         '',
+        'Refusals, read off `reason`:',
+        '  gh-missing  `--remove` needs `gh` and it is not on the path',
+        '  gh-failed   `--remove` could not read or edit the comment',
+        '',
         'Exit codes:',
         '  0  a server was found, or --remove finished, including a no-op',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -913,6 +1016,10 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--add <file>', 'Push this PNG as a frame')
     .option('--box <n>', 'The checklist box the frame shows, with --add')
+    .option(
+      '--reference <address>',
+      'The design reference the capture shows, as <page>/<frame>, with --add in place of --box',
+    )
     .option(
       '--head <sha>',
       "The head the frame was driven at, with --add, defaulting to the pull request's",
@@ -937,7 +1044,8 @@ export function register(program: Command): void {
         `An add writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
-        'with --theme, and `link` names that',
+        'with --theme, or ref-<page>--<frame>.png for a design reference capture',
+        'passed as --reference <page>/<frame> in place of --box, and `link` names that',
         `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
         'requests and resolves until its own pull request is dropped. The pass',
         'segment keeps a second pass at one head and box from replacing an image',
@@ -958,10 +1066,11 @@ export function register(program: Command): void {
         '  ok                an add pushed, or a drop or prune finished',
         '  bad-mode          not exactly one of --add, --drop, --prune',
         '  no-number         --add or --drop named no pull request',
-        '  bad-box           --add without a positive --box',
+        '  bad-box           --add with both --box and --reference, or neither',
+        '  bad-reference     --reference is not <page>/<frame> in the safe name form',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
         '  bad-pass          --add without a compact UTC --pass stamp',
-        '  bad-theme         --theme is not dark or light, or no --add',
+        '  bad-theme         --theme is not dark or light, or no --add, or rides a --reference',
         '  bad-days          --prune without a positive number of days',
         '  unreadable-frame  the --add file is missing, empty, or not a PNG',
         '  read-only         GitHub refused the write, as on a fork token',
@@ -2986,10 +3095,18 @@ function framesArgumentRefusal(
   if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
   if (
     opts.add !== undefined &&
-    (opts.box === undefined || !POSITIVE_WHOLE.test(opts.box))
+    (opts.box === undefined) === (opts.reference === undefined)
   ) {
     return 'bad-box'
   }
+  if (opts.add !== undefined && opts.box !== undefined) {
+    if (!POSITIVE_WHOLE.test(opts.box)) return 'bad-box'
+  }
+  if (opts.reference !== undefined) {
+    if (opts.add === undefined || referenceSlug(opts.reference) === undefined) {
+      return 'bad-reference'
+    }
+  }
   if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
   if (
     opts.add !== undefined &&
@@ -2999,7 +3116,9 @@ function framesArgumentRefusal(
   }
   if (
     opts.theme !== undefined &&
-    (opts.add === undefined || !isFrameTheme(opts.theme))
+    (opts.add === undefined ||
+      opts.reference !== undefined ||
+      !isFrameTheme(opts.theme))
   ) {
     return 'bad-theme'
   }
@@ -3101,7 +3220,8 @@ async function runFrames(
   if (head === undefined || head === '') return refuseFrames('no-object-head')
   if (!isFrameHead(head)) return refuseFrames('bad-head')
 
-  const box = Number(opts.box)
+  const box = opts.box === undefined ? undefined : Number(opts.box)
+  const reference = opts.reference
   const pass = opts.pass ?? ''
   const theme = opts.theme as FrameTheme | undefined
   const result = await pushFrame(api, {
@@ -3109,6 +3229,7 @@ async function runFrames(
     head,
     pass,
     box,
+    reference,
     theme,
     bytes: bytes ?? new Uint8Array(),
   })
@@ -3117,7 +3238,7 @@ async function runFrames(
   return finish(
     {
       number: pull,
-      box,
+      ...(box === undefined ? { reference } : { box }),
       ...(theme === undefined ? {} : { theme }),
       head,
       pass,
@@ -3169,6 +3290,43 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
 const READY_MUTATION =
   'mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { isDraft } } }'
 
+const CONVERT_DRAFT_MUTATION =
+  'mutation($id: ID!) { convertPullRequestToDraft(input: {pullRequestId: $id}) { pullRequest { isDraft } } }'
+
+/**
+ * Runs one pull request mutation and answers whether the draft flag now reads
+ * `isDraft`. The flag is read back rather than the exit trusted, since the
+ * mutation can answer 200 with an errors array and no change.
+ */
+async function flipDraft(
+  root: string,
+  mutation: string,
+  field: 'markPullRequestReadyForReview' | 'convertPullRequestToDraft',
+  nodeId: string,
+  isDraft: boolean,
+): Promise<boolean> {
+  const result = await execa(
+    'gh',
+    ['api', 'graphql', '-f', `query=${mutation}`, '-f', `id=${nodeId}`],
+    {
+      cwd: root,
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return false
+  try {
+    const body = JSON.parse(String(result.stdout)) as {
+      data?: Record<string, { pullRequest?: { isDraft?: boolean } } | undefined>
+    }
+    return body.data?.[field]?.pullRequest?.isDraft === isDraft
+  } catch {
+    return false
+  }
+}
+
 function gitRunner(root: string): GitRunner {
   return async (args) => {
     const result = await execa('git', ['-C', root, ...args], {
@@ -3292,44 +3450,23 @@ function liftApi(root: string, number: string, baseRef: string): LiftApi {
         return undefined
       }
     },
-    markReady: async (nodeId) => {
-      const result = await execa(
-        'gh',
-        [
-          'api',
-          'graphql',
-          '-f',
-          `query=${READY_MUTATION}`,
-          '-f',
-          `id=${nodeId}`,
-        ],
-        {
-          cwd: root,
-          reject: false,
-          timeout: GH_TIMEOUT_MS,
-          env: gitEnv(),
-          extendEnv: false,
-        },
-      )
-      if (result.exitCode !== 0) return false
-      // The flag is read back rather than the exit trusted, since the
-      // mutation can answer 200 with an errors array and no change.
-      try {
-        const body = JSON.parse(String(result.stdout)) as {
-          data?: {
-            markPullRequestReadyForReview?: {
-              pullRequest?: { isDraft?: boolean }
-            }
-          }
-        }
-        return (
-          body.data?.markPullRequestReadyForReview?.pullRequest?.isDraft ===
-          false
-        )
-      } catch {
-        return false
-      }
-    },
+    markReady: (nodeId) =>
+      flipDraft(
+        root,
+        READY_MUTATION,
+        'markPullRequestReadyForReview',
+        nodeId,
+        false,
+      ),
+    markDraft: (nodeId) =>
+      flipDraft(
+        root,
+        CONVERT_DRAFT_MUTATION,
+        'convertPullRequestToDraft',
+        nodeId,
+        true,
+      ),
+    readChanged: (from, to) => readChangedPaths(git, from, to),
     sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
     now: () => Date.now(),
   }
@@ -3385,6 +3522,7 @@ async function runLift(
   const record = await lift(liftApi(root, resolved.number, `origin/${base}`), {
     isCheck: opts.check ?? false,
     waitSeconds,
+    painted: loadPaintedPatterns(root),
   })
 
   logStep(record.reason)
@@ -3393,9 +3531,11 @@ async function runLift(
       ? `#${resolved.number} is ready for review at ${record.head?.slice(0, 8)}`
       : record.reason === 'already-ready'
         ? `#${resolved.number} is already ready for review`
-        : record.reason === 'clear'
-          ? `every gate reads clear for #${resolved.number}`
-          : LIFT_REFUSALS[record.reason],
+        : record.reason === 'redrafted'
+          ? `#${resolved.number} is back to draft, since ${record.failed === undefined ? 'a gate' : LIFT_REFUSALS[record.failed]}`
+          : record.reason === 'clear'
+            ? `every gate reads clear for #${resolved.number}`
+            : LIFT_REFUSALS[record.reason],
   )
   for (const gate of record.gates) {
     if (!gate.isOk) logWarn(`${gate.gate}: ${gate.reason ?? 'not clear'}`)

package/src/commands/records.ts

@@ -44,6 +44,7 @@ import {
   plural,
 } from '@/cli/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { fanInFindings } from '@/tasks/fan-in'
 import { readLivePlans, stackFindings } from '@/tasks/stack'
 
 /** Returned when a record carries a finding, which is the gating result. */
@@ -100,6 +101,10 @@ export function register(program: Command): void {
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
         '',
+        'Refusals, read off `reason`:',
+        "  no-folder     none of the kind's directories exist at either record root",
+        '  unknown-kind  the argument names no published kind',
+        '',
         'Exit codes:',
         '  0  every check passed',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -216,6 +221,10 @@ export function register(program: Command): void {
         'and the release tags merged into HEAD after that day, or never when it',
         'carries no date.',
         '',
+        'Refusals, read off `reason`:',
+        '  unknown-kind     any kind but `canonical`',
+        '  unreadable-tags  the release tags could not be read',
+        '',
         'Exit codes:',
         '  0  the reading completed, whatever it found',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -734,7 +743,7 @@ async function runValidate(
 }
 
 /**
- * Appends the one plans finding that reads across files. It sits in the command
+ * Appends the plans findings that read across files. They sit in the command
  * layer because `src/records/` sits below `src/tasks/`.
  */
 async function validateWithStacks(
@@ -744,9 +753,16 @@ async function validateWithStacks(
   const outcome = await validateRecords(root, kind)
   if (!outcome.ok || kind !== 'plans') return outcome
 
-  const stacked = stackFindings(await readLivePlans(root))
+  const live = await readLivePlans(root)
 
-  return { ...outcome, findings: [...outcome.findings, ...stacked] }
+  return {
+    ...outcome,
+    findings: [
+      ...outcome.findings,
+      ...stackFindings(live),
+      ...fanInFindings(live),
+    ],
+  }
 }
 
 function report(

package/src/commands/secrets.ts

@@ -60,6 +60,12 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  at least one value was found',
         '',
+        'Reasons:',
+        '  no-manifest, no-publish, no-shipped-files',
+        '    nothing is published from this tree, so the corpus is absent',
+        '  no-files-field  a publish would pack the whole tree and none of it was read',
+        '  no-git          git could not list the tree, so the corpus is unknown',
+        '',
         'Examples:',
         '  canon secrets scan',
         '  canon secrets scan --json',

package/src/commands/sessions.ts

@@ -69,6 +69,14 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-registry       no session registry exists, so nothing was read and',
+        '                    the roster is not empty',
+        '  no-repository     `--branch` resolved no repository. Run inside one or',
+        '                    pass `--repository`',
+        '  no-self-identity  `--self` found nothing to name this session with',
+        '  no-self-row       `--self` found no roster row for this session',
         '',
         'Exit codes:',
         '  0  the roster was read',

package/src/commands/tasks.ts

@@ -176,6 +176,18 @@ export function register(program: Command): void {
         'listed, and pending-branch while a Pending branch: line names a branch',
         'whose own pull request is not recorded yet. A stem skips both.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board        the repository holds no `.canon/tasks/` board',
+        '  no-match        no task matches the selector',
+        '  ambiguous       more than one task matches the selector',
+        '  no-outcomes     the task carries no outcomes to check',
+        '  open-outcomes   an outcome is still unchecked',
+        '  earlier-slice   `--pull-request` names a number that is not the last on',
+        '                  the task',
+        '  pending-branch  a `Pending branch:` line names a branch whose pull',
+        '                  request is not recorded yet',
+        '  bad-input       a malformed selector',
+        '',
         'Exit codes:',
         '  0  the task was archived',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -209,6 +221,12 @@ export function register(program: Command): void {
         'decided against at any outcome state, and the two never share a',
         'refusal set since they answer different questions.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  a missing `--reason`, or a `--by` that resolves to nobody',
+        '',
         'Exit codes:',
         '  0  the task was declined',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -243,6 +261,12 @@ export function register(program: Command): void {
         '  every Run now row names the files it touches',
         '  a file two Run now rows share is listed, never failed',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board     the repository holds no `.canon/tasks/` board',
+        '  no-ordering  the board has no ordering file',
+        '  no-groups    the board groups rows under headings of its own, with no',
+        '               declared columns',
+        '',
         'Exit codes:',
         '  0  every check passed',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -422,6 +446,12 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  a number that is not a pull request number',
         '',
         'Exit codes:',
         '  0  the line was added, appended to, corrected, or already correct',
@@ -468,6 +498,13 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board       the repository holds no `.canon/tasks/` board',
+        '  no-match       no task matches the selector',
+        '  no-plan        the plan named does not exist',
+        '  several-plans  the task line links more than one plan',
+        '  bad-input      a malformed argument',
         '',
         'Exit codes:',
         '  0  the line was added, appended to, corrected, or already correct',
@@ -514,6 +551,14 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board      the repository holds no `.canon/tasks/` board',
+        '  no-match      no task matches the selector',
+        '  ambiguous     more than one task matches the selector',
+        '  no-outcomes   the task carries no outcomes',
+        '  out-of-range  a `--close` position past the end of the outcome list',
+        '  bad-input     a malformed position',
         '',
         'Exit codes:',
         '  0  every named outcome is closed',
@@ -557,6 +602,10 @@ export function register(program: Command): void {
         'archive holds labels the live board no longer shows and a scan',
         'confined to the board hands out one already spent.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board         the repository holds no `.canon/tasks/` board',
+        '  label-contended  `--claim` lost five reservations, and the verb exits 2',
+        '',
         'Exit codes:',
         '  0  the label is derived',
         '  1  refused with no-board',
@@ -593,6 +642,9 @@ export function register(program: Command): void {
         'or both, read from priority.md and backlog.md through the parsers',
         'validate uses. It lists the live root only, never archive/ or declined/.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board  the repository holds no `.canon/tasks/` board',
+        '',
         'Exit codes:',
         '  0  the list is derived',
         '  1  refused with no-board',

package/src/commands/teach.ts

@@ -120,6 +120,19 @@ export function register(program: Command): void {
         'rewriting anything, canon teach list <topic> prints the canon serve',
         'line, with the teach folder written from where you stand.',
         '',
+        'Reasons, on stderr or in the JSON record:',
+        '  no-teach      the root carries no .canon/teach/ folder',
+        '  no-workspace  no workspace matches the topic',
+        '  ambiguous     two workspaces claim one topic',
+        '  exists        a workspace already covers the topic an open names',
+        '  no-file       the workspace carries no file the verb writes into',
+        '  no-section    RESOURCES.md carries no heading the entries belong under',
+        '  listed        a URL is already read, or a lead is offered as listed',
+        '  defined       a term already carries a glossary entry',
+        '  bad-input     the command line is malformed',
+        '  no-port       up found every port in reach taken',
+        '  bind-failed   up could not bind, such as a privileged port',
+        '',
       ].join('\n'),
     )