@erclx/canon 4.60.0 → 4.61.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.60.0",
+  "version": "4.61.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-tasks/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: Why creating and archiving a task file is one skill, the origin inv
 
 ## Gap
 
-Without this skill, a task file gets a filename and frontmatter invented on the spot, so the board sorts wrong and the regenerated index reads fields that are not there. A task arrives with no origin, which is either lost context or work nobody decided to do, and by the time anyone notices there is no way to recover which it was. The phase label gets derived from a version file rather than from what the board already means, and a single-digit phase sorts after a double-digit one because nobody padded it.
+Without this skill, a task file gets a filename and frontmatter invented on the spot, so the board sorts wrong and the regenerated index reads fields that are not there. A task arrives with no origin, which is either lost context or work nobody decided to do, and by the time anyone notices there is no way to recover which it was. The phase label gets derived from a version file rather than from what the board already means, and a single-digit phase sorts after a double-digit one because nobody padded it. A label picked off the live board alone repeats one the archive already spent, since the archive holds most of what has ever been allocated and a board-only scan cannot see it.
 
 Archiving fails in two ways that both lose work. Moving the file, editing the ordering file, and regenerating the index as three separate acts drifts from the one command the merge hook calls, so the attended and unattended paths stop agreeing. And an all-`[x]` task gets archived while its pull request is still open, because marking outcomes happens on the branch as the first step of shipping. The board is gitignored, so nothing restores a task archived early.
 
@@ -18,7 +18,7 @@ Placing a row without checking for another writer collides the same way. Two ses
 - Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
 - Read the tasks standard before writing, rather than working the filename and frontmatter from memory
 - Require an origin at creation, because that is the only moment the invariant is enforceable
-- Propose the phase label from what is already on the board and pad it to two digits
+- Read the phase label from `canon tasks next-label` rather than proposing one by hand
 - Check the roster for a live orchestrator before writing a row, and hand off rather than write when one is found
 - Confirm the work reached the default branch before archiving
 - Run the archive command and route on the reason it refuses, since each reason has one resolution

package/claude/skills/claude-tasks/SKILL.md

@@ -27,11 +27,11 @@ A task with no origin is either lost context or work nobody decided to do. This
 
 Accept work whose origin is the conversation itself only when the user says so explicitly, and record what it was in the intro paragraph instead of writing a link line to a file that does not exist.
 
-### Step 2: propose the phase label
+### Step 2: allocate the phase label
 
-List the existing filenames in `.canon/tasks/` and read `index.md` for what each holds. Propose the next label from what is already on the board, and say which neighbors it sits between.
+Run `canon tasks next-label --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows.
 
-Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the board is the only surface that knows what a label currently means. Pad the phase to two digits in the filename, since index entries sort by filename alone and a bare `v9.0` sorts after `v15.0`. <!-- canon-allow-reference: illustrates the padding rule's own sort collision, not a citation of a real task -->
+Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the verb's two folders are the only surface that knows what a label currently means.
 
 ### Step 3: write the file
 
@@ -138,7 +138,7 @@ Create:
 ```plaintext
 ✅ Created: .canon/tasks/vXX.Y-<slug>.md
 
-<label> sits between <neighbor> and <neighbor>.
+<label>, next after <highest>.
 <board or backlog, and why it landed there>.
 
 **Origin with no task:**

package/claude/skills/setup-indexes/REQUIREMENT.md

@@ -15,6 +15,8 @@ One failure predates the scan. `setup-init` declines an install that wants the C
 
 Drafted frontmatter is a proposal, and a session that writes it before the user sees it turns a review into a cleanup. The convention block has the mirror failure. A session that paraphrases it into `CLAUDE.md` produces a copy that reads correctly and no longer matches its source, so the two drift with nothing reporting it. And a project with no `CLAUDE.md` gets one scaffolded to hold the block, which installs a file the project declined.
 
+A fourth failure sits after the scan rather than inside it. `## Present candidates` had no branch for a scan that finds zero folders, so an empty result walked straight into the ask with nothing to choose from. `setup-init` folds this skill into the onboarding chain, and a fresh scaffold usually carries no markdown-heavy folder yet, so the ordinary onboarding run reached the undefined case.
+
 ## Must
 
 - Bootstrap all-or-nothing per chosen folder, since a folder carrying partial frontmatter hard-errors on regen
@@ -36,6 +38,7 @@ Drafted frontmatter is a proposal, and a session that writes it before the user
 
 - A folder with fewer than the sibling threshold stays out of the candidate list unless the user names it explicitly, so the scan proposes and the user overrides
 - A `CLAUDE.md` already carrying the convention section skips the seed silently rather than appending a second copy
+- A scan that finds no candidate reports a one-line result and returns, skipping the ask and every step between it and the seed offer, rather than opening a prompt with nothing in it
 
 ## Out of scope
 

package/claude/skills/setup-indexes/SKILL.md

@@ -29,6 +29,14 @@ For each candidate, capture:
 
 ## Present candidates
 
+If the scan found no candidate, report the flat result and skip ahead:
+
+```plaintext
+No folder has three or more markdown siblings without an index.md already. Nothing to bootstrap.
+```
+
+Skip past the ask below and every step between it and the seed offer, straight to `## Offer the convention seed`. There is no candidate to ask about, so this stops rather than opening a prompt with nothing in it.
+
 Output one line per candidate:
 
 ```plaintext

package/docs/agents/commands.md

@@ -36,6 +36,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon tasks plan-link`       | Write or correct a task's `Plan:` line to point at a plan, by stem and plan path or slug (`--json`)                                                                                                                                                                                                                    |
 | `canon tasks outcome`         | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                                                                                                                                                                              |
 | `canon tasks validate`        | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                                                                                                                                                                            |
+| `canon tasks next-label`      | Report the next unused phase label across the board and its archive (`--json`)                                                                                                                                                                                                                                         |
 | `canon intake list`           | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                                                                                                                                                                  |
 | `canon intake answer`         | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                                                                                                                                                                                         |
 | `canon teach list`            | Report learning workspaces and the ordinal a new one takes, or what one workspace holds and what its records schedule (`--json`)                                                                                                                                                                                       |

package/docs/agents/tasks.md

@@ -5,6 +5,32 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
 
 # Tasks
 
+## Next label
+
+`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. It reports and never writes.
+
+```bash
+canon tasks next-label
+canon tasks next-label --json
+```
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `label`, the next free `vXX.Y`, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
+
+Exit codes: `0` derived, `1` refused with `no-board`.
+
+The minor digit rolls from 9 to 0 on the next major rather than growing a second digit, which is the single-digit-minor shape every phase label already takes. `canon tasks archive` moves a task's file from the live folder into the archive without renumbering it, so the same label counts toward the maximum wherever it currently sits, and a label claimed by two different files folds into the same scan without a dedicated check.
+
+It reports rather than gates. Two sessions calling it in the same second can still take the same answer, since the board is gitignored files rather than a store with a lock, and `standards/versioning.md` permits free renumbering, so a collision costs a rename rather than anything worse.
+
+```bash
+canon tasks next-label --json | jq -r '.label'
+```
+
 ## Archive
 
 `canon tasks archive` moves a shipped task from `.canon/tasks/` into `.canon/tasks/archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.

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

@@ -30,5 +30,7 @@ paths:
 
 ## Sharing a capture
 
-- Attach a capture to the pull request by hand when a reviewer needs to see it.
-- Do not commit a capture. Do not remove the capture folder from `.gitignore`.
+- Do not commit the sweep. It stays ignored.
+- Commit a flagged case's evidence output so the pull request carries the comparison, rather than attaching it by hand.
+- 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.

package/package.json

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

package/src/commands/tasks.ts

@@ -9,6 +9,7 @@ import {
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
+import { type LabelOutcome, nextLabel } from '@/tasks/label'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -87,6 +88,11 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface NextLabelCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 export function register(program: Command): void {
   const tasks = program
     .command('tasks')
@@ -379,6 +385,40 @@ export function register(program: Command): void {
     .action(async (task: string | undefined, opts: OutcomeCommandOptions) => {
       process.exitCode = await runOutcome(task, opts)
     })
+
+  tasks
+    .command('next-label')
+    .description(
+      'Report the next unused phase label across the board and its archive',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads .canon/tasks/ and its archive/ sibling together, since the',
+        'archive holds labels the live board no longer shows and a scan',
+        'confined to the board hands out one already spent.',
+        '',
+        'Exit codes:',
+        '  0  the label is derived',
+        '  1  refused with no-board',
+        '',
+        'It reports and never writes. Two sessions calling it in the same',
+        'second can still take the same answer, since the board is',
+        'gitignored files rather than a store with a lock.',
+        '',
+        'Examples:',
+        '  canon tasks next-label',
+        '  canon tasks next-label --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: NextLabelCommandOptions) => {
+      process.exitCode = await runNextLabel(opts)
+    })
 }
 
 function collectPosition(value: string, previous: string[]): string[] {
@@ -649,6 +689,50 @@ function reportOutcome(
   return 0
 }
 
+async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await nextLabel(root)
+
+  return reportNextLabel(outcome, opts.json ?? false, root)
+}
+
+function reportNextLabel(
+  outcome: LabelOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks next-label')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('canon tasks next-label')
+  logStep(outcome.label)
+  logInfo(
+    outcome.highest
+      ? `next after ${outcome.highest}.`
+      : 'the board and its archive hold no label yet.',
+  )
+  outro()
+
+  return 0
+}
+
 async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await validateBoard(root)

package/src/tasks/label.ts

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs'
+import { relative } from 'node:path'
+import { archiveDir, listTaskStems, tasksDir } from '@/tasks/archive'
+
+/** Every label in the corpus today stops here before rolling to the next major. */
+const MINOR_ROLLOVER = 9
+
+/** The label a board with no live or archived task yet allocates first. */
+const FIRST_LABEL: Label = { major: 1, minor: 0 }
+
+/**
+ * Matches a task filename stem's leading label. Anchored, so a sibling such as
+ * `TASK-ARCHIVE` fails it outright, and a reserved stem such as `index` or
+ * `priority` never reaches it at all, since `listTaskStems` already filters
+ * those out before this pattern sees a stem.
+ */
+export const LABEL_PATTERN = /^v(\d+)\.(\d+)-/
+
+interface Label {
+  readonly major: number
+  readonly minor: number
+}
+
+export interface NextLabel {
+  readonly ok: true
+  readonly label: string
+  /** The label this run was derived from, absent when neither folder holds one. */
+  readonly highest: string | undefined
+}
+
+export interface LabelRefused {
+  readonly ok: false
+  readonly reason: 'no-board'
+  readonly message: string
+}
+
+export type LabelOutcome = NextLabel | LabelRefused
+
+function parseLabel(stem: string): Label | undefined {
+  const match = LABEL_PATTERN.exec(stem)
+  if (!match) return undefined
+
+  return { major: Number(match[1]), minor: Number(match[2]) }
+}
+
+function isHigher(candidate: Label, current: Label): boolean {
+  return candidate.major !== current.major
+    ? candidate.major > current.major
+    : candidate.minor > current.minor
+}
+
+function formatLabel(label: Label): string {
+  return `v${String(label.major).padStart(2, '0')}.${label.minor}`
+}
+
+/**
+ * The label after the one given, rolling a minor of 9 to the next major rather
+ * than continuing to a second minor digit. Every one of the 587 labels measured
+ * across the live board and its archive on 2026-09-06 stops at a single digit,
+ * so this is the rollover the whole corpus already follows rather than a rule
+ * this verb introduces.
+ */
+function next(label: Label): Label {
+  return label.minor >= MINOR_ROLLOVER
+    ? { major: label.major + 1, minor: 0 }
+    : { major: label.major, minor: label.minor + 1 }
+}
+
+/**
+ * Reports the next unused phase label, read off the true maximum across
+ * `.canon/tasks/` and its `archive/` sibling together. A scan confined to the
+ * live board is blind to every label the archive already spent, which is what
+ * let two sessions hand out the same label within minutes of each other.
+ *
+ * It reports and never writes. Two sessions calling it in the same second can
+ * still take the same answer, since the board is gitignored files rather than
+ * a store with a lock, and `standards/versioning.md` permits free renumbering,
+ * so a collision costs a rename rather than anything worse. A duplicate label
+ * already sitting in the tree, and a gap left by a renumbering, both fold into
+ * the same max scan without needing a dedicated check.
+ */
+export async function nextLabel(root: string): Promise<LabelOutcome> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return {
+      ok: false,
+      reason: 'no-board',
+      message: `No task board at ${relative(root, dir)}.`,
+    }
+  }
+
+  const archive = archiveDir(root)
+  const dirs = existsSync(archive) ? [dir, archive] : [dir]
+  const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+
+  const highest = stems
+    .map(parseLabel)
+    .filter((label): label is Label => label !== undefined)
+    .reduce<Label | undefined>(
+      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
+      undefined,
+    )
+
+  return {
+    ok: true,
+    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
+    highest: highest === undefined ? undefined : formatLabel(highest),
+  }
+}

package/tooling/astro/reference.md

@@ -59,6 +59,12 @@ Append to the `## Scripts` table:
 
 In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
 
+## Gitignore (extend)
+
+`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+
+- `"# Astro" = [".astro/"]`
+
 ## Scenario switcher
 
 - `src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.

package/tooling/web/configs/e2e/screenshot.ts

@@ -9,11 +9,19 @@ interface CaptureCase {
   route: string
   width: number
   height: number
+  evidence?: boolean
   setup?: (page: Page) => Promise<void>
 }
 
 const CASES: CaptureCase[] = [
-  { section: 'home', theme: 'default', route: '/', width: 1280, height: 800 },
+  {
+    section: 'home',
+    theme: 'default',
+    route: '/',
+    width: 1280,
+    height: 800,
+    evidence: true,
+  },
   {
     section: 'home',
     theme: 'dark',
@@ -47,8 +55,12 @@ const OUT_DIR = path.join('screenshots', hostname)
 
 const browser = await chromium.launch()
 const consoleErrors: string[] = []
+let ranCases = 0
 
 for (const captureCase of CASES) {
+  if (captureCase.evidence && requireBaseUrl) continue
+
+  ranCases++
   const context = await browser.newContext({
     viewport: { width: captureCase.width, height: captureCase.height },
   })
@@ -76,11 +88,26 @@ for (const captureCase of CASES) {
   await page.screenshot({ path: file, fullPage: true })
   console.log(`captured ${file}`)
 
+  if (captureCase.evidence) {
+    const evidenceDir = path.join('evidence', captureCase.section)
+    await mkdir(evidenceDir, { recursive: true })
+    const evidenceFile = path.join(evidenceDir, `${captureCase.theme}.png`)
+    await page.screenshot({ path: evidenceFile, fullPage: true })
+    console.log(`captured ${evidenceFile}`)
+  }
+
   await context.close()
 }
 
 await browser.close()
 
+if (requireBaseUrl && ranCases === 0) {
+  console.error(
+    'every CASES entry is flagged evidence: true, so --require-base-url skipped all of them and checked nothing',
+  )
+  process.exit(1)
+}
+
 if (checkConsoleClean && consoleErrors.length > 0) {
   console.error('console errors detected:')
   for (const error of consoleErrors) console.error(`  ${error}`)

package/tooling/web/manifest.toml

@@ -57,4 +57,5 @@ packages = [
 "# Build" = ["dist/"]
 "# Coverage" = ["coverage/"]
 "# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]
+"# Screenshots" = ["screenshots/"]
 "# VSCode" = [".vscode/*", "!.vscode/extensions.json", "!.vscode/settings.json"]

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -112,13 +112,14 @@ Append rows:
 
 `governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a route changes. It fires on route and page files rather than on every component, so a shared component changing every screen fires nothing and the operator runs the capture by hand.
 
-The screenshot output now tracks in git rather than getting discarded, so the first capture a scaffolded target runs after this change is the baseline it commits.
+The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there.
 
 ## Gitignore (extend)
 
 `[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
 
 - `"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]`
+- `"# Screenshots" = ["screenshots/"]`
 
 ## Verify script