@erclx/canon 4.60.0 → 4.62.0

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