@erclx/canon 4.73.0 → 4.75.0

package/docs/agents/pr-evidence.md

@@ -0,0 +1,108 @@
+---
+title: The pull request evidence comparison
+description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+---
+
+# The pull request evidence comparison
+
+`canon pr evidence` renders one comment naming every changed image under an
+`evidence/` path segment, comparing each against the pull request's merge base
+with the trunk. `git-pr` posts it when a pull request opens or is edited, and
+`git-followup` posts it again after every later push, so a reviewer never has
+to open Files Changed to see what a case looked like before and after.
+
+```bash
+canon pr evidence
+canon pr evidence 1341 --json
+```
+
+## Why the comparison anchors at the merge base
+
+The comparison is always base against the current head, never the previous
+push against the new one. A follow-up only ever moves the after side of the
+comment, so what the comment claims can only grow to match what the branch
+actually shows, and a reviewer who opens it midway through a review round
+never reads a stale before image describing an intermediate commit nobody is
+looking at anymore.
+
+## What counts as evidence
+
+A changed path qualifies when one of its segments is literally `evidence` and
+its filename carries an image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`,
+`avif`, `svg`). The second half of that test exists because an `evidence/`
+folder holds whatever else a project keeps beside its captures. This
+repository's own tree carries eight `.md` files, two `.sh` scripts, a `.tsv`,
+a `.json`, and an `.html` file against a single `.png`, and every one of them
+would render as a broken `![]()` embed without the extension filter.
+
+## What the record carries
+
+The record groups every evidence path by state, the remainder of its
+directory under the `evidence/` segment, and within a state by filename stem,
+so a `before/hero.png` and an `after/hero.png` naming the same case group as
+one entry rather than two unrelated files. Each entry carries whether it
+existed at the base commit, which decides whether the comment shows a base
+image or marks the case new.
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason               | What it means                                                                 |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `ok`                 | A body was rendered. `commentId` is set when a marked comment already exists. |
+| `no-evidence`        | Nothing in the diff carries an `evidence/` segment. An ordinary silent no-op. |
+| `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.                          |
+| `no-branch`          | The pull request carries no head branch name.                                 |
+| `no-object-head`     | The pull request object reported no head commit.                              |
+| `no-base`            | No base resolves against the trunk.                                           |
+| `unreadable-tree`    | git could not read the tree at the base commit.                               |
+| `unreadable-changes` | git could not list what this branch changed.                                  |
+
+`no-evidence` is not a refusal a caller reports. A project on a stack that
+carries no evidence path, such as `base` or `python`, hits this reason on
+every pull request and posts nothing, which is the correct behavior rather
+than a gap.
+
+## What `[number]` selects, and what it does not
+
+Naming a number picks which pull request the rendered body claims to
+describe: its head commit and, when one already exists, the marked comment to
+edit in place. The base and the changed set are always read from the local
+checkout's own history, `git diff` and `git ls-tree` against the merge base
+with the trunk, rather than fetched for the named pull request over the API.
+That is correct for `git-pr` and `git-followup`, which never pass a number
+and always run from the worktree building the branch, so the local checkout
+and the named pull request describe the same branch. Naming a number for a
+pull request built somewhere else compares this checkout's own diff against a
+head commit that describes a different one.
+
+## One comment, found by its own marker
+
+Every body this verb renders ends with a trailing marker naming the head it
+describes:
+
+```markdown
+<!-- pr-evidence: head=<sha> -->
+```
+
+`canon pr evidence` reads that marker back off every comment on the pull
+request, the same way `canon pr review-state` reads its own marker off a
+review body, and reports the REST id of whichever comment carries it as
+`commentId`. A caller with no `commentId` posts a new comment. A caller
+holding one edits that comment in place with a `PATCH` rather than posting a
+second one.
+
+Putting the lookup here, in the one place both `git-pr` and `git-followup`
+call, is what keeps two close-out comments from landing beside each other the
+way `review-pr` once posted, before that skill's own guard existed. It is
+also why this verb renders the whole comment body rather than handing each
+skill a record to format on its own: a fix to the table shape or the
+collapsed-details wrapper lands once, not twice.
+
+## What a collapsed comment still leaves to GitHub
+
+GitHub already draws its own before-and-after comparison on the Files Changed
+tab for any tracked image that changed. This comment does not make that view
+redundant. The diff view shows what moved between two commits a reader has
+already opened, and the comment is what lets a reader see the same comparison
+without opening it at all.

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+description: The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -39,14 +39,14 @@ Nothing fires it automatically. The five record folders are gitignored, so the s
 
 ### What each kind checks
 
-| Kind         | What it reports                                                                                                                                                                                                                                                                                                  |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot                                                                               |
-| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                            |
-| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                       |
-| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                  |
-| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                   |
-| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal |
+| Kind         | What it reports                                                                                                                                                                                                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, a question carrying no suggestion or no answer slot, and a batch still staged with a `**Batch N**` sub-heading inside the one file rather than split into its own plan |
+| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                                                             |
+| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                                                        |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                                                   |
+| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                                                    |
+| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal                                  |
 
 The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
 
@@ -104,6 +104,26 @@ A transform runs only where the missing value is recoverable from the file itsel
 
 Exit codes: `0` nothing carried a known transform, or `--write` repaired everything it found. `1` refused for a reason `validate` shares, every candidate it found failed to repair, or `--write` repaired only some of them. `2` a record carries a known transform and `--write` was not passed.
 
+## Ordinal
+
+`canon records ordinal <kind> <slug>` reports the next ordinal `intake` and `groundwork` share, or claims it with `--claim`. The two kinds share one sequence, per `standards/intake.md` and `standards/groundwork.md`, so this reads both `.canon/intake/` and `.canon/groundwork/` regardless of which kind was asked for.
+
+```bash
+canon records ordinal intake my-topic
+canon records ordinal groundwork my-topic --claim
+canon records ordinal groundwork my-topic --claim --json
+```
+
+| Option          | Behavior                                               |
+| --------------- | ------------------------------------------------------ |
+| `--json`        | Add a machine-readable record on stdout                |
+| `--claim`       | Create the folder atomically instead of only reporting |
+| `--root <path>` | Project root, defaulting to the main worktree          |
+
+Without `--claim` this only reports, so two sessions reading at once can still report the same number, which is what let two sessions open two different record folders under one ordinal on the same day. `--claim` closes that: it reserves the number at a path both an `intake` claim and a `groundwork` claim resolve to identically, whichever kind is asking, and only creates the kind's own `<nn>-<slug>/` folder once that reservation is won. A losing reservation is retried against a freshly read ordinal rather than reported as a collision, bounded to five attempts before refusing as `ordinal-contended`.
+
+Exit codes: `0` reported the next ordinal, or `--claim` created the folder. `1` refused, `unknown-kind` when the argument names neither `intake` nor `groundwork`. `2` `--claim` lost every retry to a collision.
+
 ## Size
 
 `canon records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus the scratch folder, and it gates nothing.

package/docs/agents/tasks.md

@@ -141,6 +141,8 @@ A relative path resolves against the project root first and against `.canon/task
 
 `canon tasks plan-citations` reads a task's `Plan:` line against those same two bases in the opposite order, and tests that the target lands under the live plans folder, which this verb does not. Both answer the same file for every spelling a board writes. Liveness is a separate refusal here: a plan resolving inside `.canon/plans/archive/` returns `archived` rather than a launchable reading, since it answers every question and describes work that already shipped.
 
+A plan still staging its batches with a `**Batch N**` sub-heading inside one file's `**Files to touch:**` reads `launchable: false` the same way, alongside the operator-call case. It reports as an entry in `open` labeled `Batch staging`, stating that the plan must split into one file per batch before it can dispatch, since the row waits on a split rather than on the operator.
+
 | Option          | Effect                                      |
 | --------------- | ------------------------------------------- |
 | `--json`        | Emit a machine-readable record on stdout    |

package/docs/target-projects.md

@@ -143,6 +143,10 @@ The first line takes the `.canon/` ignore entry, and the verb refuses until the
 
 Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
 
+### Back records up off this machine, once
+
+Moving records under `.canon/` relocates them, and relocating them is not the same as backing them up. Run `canon records push` once a private repository exists for them, and it prints the one-time setup command when it finds none, since the task board, the memory pen, and the groundwork trails otherwise live on one disk with nothing pushing them off it. `canon init` prints the same reminder as a notice-only step rather than trying to run this non-interactively, since the private repository does not exist yet at scaffold time.
+
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 
 A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the nearest non-blank line above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.

package/governance/rules/ui/440-surface-capture.md

@@ -37,3 +37,4 @@ paths:
 - A project whose own established convention already commits that same comparison may route a flagged case's evidence there instead of a separate evidence folder. Only an established convention already committing the same comparison qualifies, not a preference for skipping a second folder.
 - Commit an evidence case for the first time only after running the capture twice with no code change between the runs and confirming the two outputs are byte-identical.
 - Recommitting an unbounded sweep on every run reaches a gigabyte of repository history inside a hundred merges. A small, committed evidence set is what a reviewer needs and what lets GitHub draw its own before-and-after comparison on the pull request.
+- `git-pr` and `git-followup` maintain a comparison comment on the pull request automatically once a case is committed, so a reviewer never has to open Files Changed to see it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.73.0",
+  "version": "4.75.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/design.ts

@@ -7,6 +7,7 @@ import {
   DESIGN_PROJECT_SUBDIR,
 } from '@/design/adapter'
 import { buildDesignCss } from '@/design/css'
+import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
@@ -80,9 +81,16 @@ export function register(program: Command): void {
       '--no-components',
       'Custom properties only, without the component rules',
     )
-    .action((opts: { components: boolean }) => {
+    .option(
+      '--figures',
+      'Embed the hand-drawn figure fonts (Virgil, Excalifont), which the unconditional component styling never carries on its own',
+    )
+    .action((opts: { components: boolean; figures?: boolean }) => {
       process.stdout.write(
-        buildDesignCss(undefined, { components: opts.components }),
+        buildDesignCss(undefined, {
+          components: opts.components,
+          embedFonts: opts.figures ? HAND_DRAWN_FONT_FACES : undefined,
+        }),
       )
     })
 

package/src/commands/pr.ts

@@ -20,6 +20,11 @@ import {
   treeRoots,
 } from '@/pr/bijection'
 import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import {
+  findEvidenceCommentId,
+  groupEvidence,
+  renderEvidenceBody,
+} from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import { KEY_CHANGES } from '@/pr/paths'
 import { type ReviewListing, resolveReviewScope } from '@/pr/review-scope'
@@ -81,6 +86,27 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
     'The reviews on this pull request could not be read. An empty answer here would report a reviewed pull request as never reviewed, which routes the next pass to the whole change, so nothing is reported.',
 }
 
+/**
+ * Why `canon pr evidence` produced no comment body, past the ones
+ * `readIdentity` already owns (`gh-missing`, `gh-failed`, `no-branch`) and the
+ * one `identity.head` owns (`no-object-head`).
+ */
+type EvidenceRefusal =
+  | 'gh-failed'
+  | 'no-base'
+  | 'unreadable-tree'
+  | 'unreadable-changes'
+
+const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
+  'gh-failed':
+    'gh could not answer for this repository. Name the pull request number.',
+  'no-base': 'No base resolves against the trunk. Fetch origin and re-run.',
+  'unreadable-tree':
+    'git could not read the tree at the base commit, so no path could be judged added or changed.',
+  'unreadable-changes':
+    'git could not list what this branch changed, so the set is unknown.',
+}
+
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
 type SourceRefusal =
   | 'gh-missing'
@@ -289,6 +315,46 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: ReadOptions) => {
       process.exitCode = await runReviewState(number, opts)
     })
+
+  pr.command('evidence')
+    .description(
+      "Render a before/after comparison for the pull request's changed evidence images",
+    )
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Compares the merge base with the trunk against the current head, never',
+        'the previous push against the new one, so the comment never claims more',
+        'than the branch currently shows. A path counts as evidence when one of',
+        'its segments is literally `evidence` and the filename carries an image',
+        'extension (png, jpg, jpeg, gif, webp, avif, svg). A README, a capture',
+        'script, or a raw data file kept beside the images is left out rather',
+        'than rendered as a broken embed.',
+        '',
+        'Read `reason` on the JSON record before posting anything:',
+        '  ok           a body was rendered, with `commentId` set when a marked',
+        '               comment already exists and should be edited in place',
+        '  no-evidence  nothing in the diff carries an evidence/ segment, which',
+        '               is an ordinary, silent no-op rather than a refusal',
+        '',
+        'Exit codes:',
+        '  0  read, whether it produced a body or reported no-evidence',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr evidence --json',
+        '  canon pr evidence 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: ReadOptions) => {
+      process.exitCode = await runEvidence(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1019,6 +1085,160 @@ async function runReviewState(
   return 0
 }
 
+/**
+ * Every path `git ls-tree` reports for `ref`, or undefined when the read
+ * failed. One call for the whole tree rather than one `cat-file -e` per
+ * evidence path, since existence at base is checked once per changed path and
+ * a batch read is one round trip instead of many.
+ */
+async function listTreePaths(
+  root: string,
+  ref: string,
+): Promise<Set<string> | undefined> {
+  const result = await $`git -C ${root} ls-tree -r --name-only ${ref}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return undefined
+  return new Set(result.text().split('\n').filter(Boolean))
+}
+
+async function runEvidence(
+  number: string | undefined,
+  opts: ReadOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr evidence')
+
+  const read = await readIdentity(root, number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
+  }
+
+  const { identity } = read
+  if (identity.head === undefined) {
+    return refuseWith(
+      'no-object-head',
+      PULL_REFUSALS['no-object-head'],
+      emitJson,
+      root,
+    )
+  }
+
+  const base = await resolveBaseRef(root)
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  }
+
+  const [changed, baseTree] = await Promise.all([
+    listChangedFiles(root, base),
+    listTreePaths(root, base),
+  ])
+  if (changed === undefined) {
+    return refuseWith(
+      'unreadable-changes',
+      EVIDENCE_REFUSALS['unreadable-changes'],
+      emitJson,
+      root,
+    )
+  }
+  if (baseTree === undefined) {
+    return refuseWith(
+      'unreadable-tree',
+      EVIDENCE_REFUSALS['unreadable-tree'],
+      emitJson,
+      root,
+    )
+  }
+
+  const grouped = await groupEvidence(changed, async (path) =>
+    baseTree.has(path),
+  )
+
+  if (grouped.kind === 'refused') {
+    logStep('Skipped')
+    logInfo(
+      'No changed path carries an evidence/ segment, so there is nothing to post.',
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          ...(identity.number !== undefined && { number: identity.number }),
+          reason: 'no-evidence',
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  const repo =
+    repoRow === null
+      ? undefined
+      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
+
+  if (repo === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
+  const body = renderEvidenceBody(grouped.states, repo, base, identity.head)
+
+  let commentId: number | undefined
+  if (identity.number !== undefined) {
+    const commentsRow = await gh(root, [
+      'pr',
+      'view',
+      String(identity.number),
+      '--json',
+      'comments',
+    ])
+    if (commentsRow !== null) {
+      try {
+        const parsed = JSON.parse(commentsRow) as {
+          comments?: readonly { url?: string; body: string }[]
+        }
+        commentId = findEvidenceCommentId(parsed.comments ?? [])
+      } catch {
+        commentId = undefined
+      }
+    }
+  }
+
+  const caseCount = grouped.states.reduce((n, s) => n + s.items.length, 0)
+
+  logStep('Scope')
+  logInfo(
+    `${plural(caseCount, 'case')} across ${plural(grouped.states.length, 'state')}`,
+  )
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        reason: 'ok',
+        base,
+        head: identity.head,
+        body,
+        ...(commentId !== undefined && { commentId }),
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/commands/records.ts

@@ -3,6 +3,13 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
 import { migrateRecord } from '@/records/migrate'
+import {
+  type ClaimOutcome,
+  claimOrdinal,
+  highestOrdinal,
+  isOrdinalKind,
+  ORDINAL_KINDS,
+} from '@/records/ordinal'
 import {
   type FolderSize,
   formatBytes,
@@ -40,6 +47,9 @@ const EXIT_FINDINGS = 2
 /** Returned when a record carries a known transform and `--write` was not passed. */
 const EXIT_MIGRATABLE = 2
 
+/** Returned when `--claim` loses every retry to a collision. */
+const EXIT_CONTENDED = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -51,6 +61,10 @@ interface MigrateCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
 }
 
+interface OrdinalCommandOptions extends ValidateCommandOptions {
+  readonly claim?: boolean
+}
+
 export function register(program: Command): void {
   const records = program
     .command('records')
@@ -140,6 +154,49 @@ export function register(program: Command): void {
       process.exitCode = await runMigrate(kind, opts)
     })
 
+  records
+    .command('ordinal')
+    .description(
+      'Report or claim the next ordinal shared by intake and groundwork folders',
+    )
+    .argument('<kind>', `Ordinal-bearing folder: ${ORDINAL_KINDS.join(', ')}`)
+    .argument('<slug>', 'The kebab-case slug the new folder will carry')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--claim',
+      'Create the folder atomically instead of only reporting the ordinal',
+    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'intake and groundwork folders share one ordinal sequence, so this reads',
+        'both .canon/intake/ and .canon/groundwork/ regardless of which kind was',
+        'asked for.',
+        '',
+        'Exit codes:',
+        '  0  reported the next ordinal, or --claim created the folder',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  --claim lost every retry to a collision',
+        '',
+        'Without --claim this only reports, so two sessions reading at once can',
+        'still report the same number. --claim resolves that by creating the',
+        'folder as part of the same act, retrying past a losing race rather than',
+        'reporting one.',
+        '',
+        'Examples:',
+        '  canon records ordinal intake my-topic',
+        '  canon records ordinal groundwork my-topic --claim',
+        '  canon records ordinal groundwork my-topic --claim --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, slug: string, opts: OrdinalCommandOptions) => {
+      process.exitCode = await runOrdinal(kind, slug, opts)
+    })
+
   records
     .command('size')
     .description('Report what each record folder holds and how much is recent')
@@ -726,3 +783,84 @@ export function migrateExitCode(
   if (!write) return EXIT_MIGRATABLE
   return refused.length > 0 ? 1 : 0
 }
+
+async function runOrdinal(
+  kind: string,
+  slug: string,
+  opts: OrdinalCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isOrdinalKind(kind)) {
+    return reportRefusal(
+      'canon records ordinal',
+      {
+        reason: 'unknown-kind',
+        message: `Not an ordinal-bearing kind: ${kind}. Expected one of: ${ORDINAL_KINDS.join(', ')}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const claim = opts.claim ?? false
+
+  if (!claim) {
+    const next = String((await highestOrdinal(root)) + 1).padStart(2, '0')
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: true, root, kind, slug, ordinal: next, claimed: false })}\n`,
+      )
+    } else {
+      intro('canon records ordinal')
+      logStep('Next')
+      logInfo(`${next}-${slug} (report only, pass --claim to create it)`)
+      outro()
+    }
+
+    return 0
+  }
+
+  return reportOrdinal(root, await claimOrdinal(root, kind, slug), emitJson)
+}
+
+function reportOrdinal(
+  root: string,
+  outcome: ClaimOutcome,
+  emitJson: boolean,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stderr.write(`${outcome.message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({
+          ok: false,
+          reason: outcome.reason,
+          message: outcome.message,
+          lastOrdinal: outcome.lastOrdinal,
+        })}\n`,
+      )
+      return EXIT_CONTENDED
+    }
+
+    intro('canon records ordinal')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return EXIT_CONTENDED
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, ...outcome, claimed: true })}\n`,
+    )
+  } else {
+    intro('canon records ordinal')
+    logStep('Claimed')
+    logInfo(outcome.path)
+    outro()
+  }
+
+  return 0
+}