@erclx/canon 5.36.0 → 5.37.0

package/src/migrate/rule-layout.ts

@@ -34,12 +34,12 @@ export const RENUMBERED_RULES: Readonly<Record<string, string>> = {
 }
 
 /**
- * Band folders the walk skips by name rather than by content, so the
- * exclusion holds even for a band the toolkit has not shipped yet.
+ * Rule folders the walk skips by name rather than by content, so the
+ * exclusion holds even for a folder the toolkit has not shipped yet.
  * `canon/` and `internal/` are already-migrated destinations, and
  * `project/` is a target's own rules, which this verb never touches.
  */
-const EXCLUDED_BANDS: readonly string[] = ['project', 'canon', 'internal']
+const EXCLUDED_FOLDERS: readonly string[] = ['project', 'canon', 'internal']
 
 /** One flat rule file, before classification. */
 export interface FlatRuleFile {
@@ -57,9 +57,9 @@ export function flatRulesRoot(target: string): string {
 }
 
 /**
- * Every rule file sitting directly under a flat band folder. One level for
- * the band and one glob below it for `*.md`, since `governance/rules/` never
- * nests a rule deeper than its band, and the flat layout this verb migrates
+ * Every rule file sitting directly under a flat rule folder. One level for
+ * the folder and one glob below it for `*.md`, since `governance/rules/` never
+ * nests a rule deeper than its folder, and the flat layout this verb migrates
  * off of mirrors that depth.
  */
 export async function walkFlatRules(target: string): Promise<FlatRuleFile[]> {
@@ -69,20 +69,20 @@ export async function walkFlatRules(target: string): Promise<FlatRuleFile[]> {
   )
   if (entries === undefined) return []
 
-  const bands = entries.filter(
-    (entry) => entry.isDirectory() && !EXCLUDED_BANDS.includes(entry.name),
+  const folders = entries.filter(
+    (entry) => entry.isDirectory() && !EXCLUDED_FOLDERS.includes(entry.name),
   )
 
   const files: FlatRuleFile[] = []
-  for (const band of bands) {
+  for (const folder of folders) {
     const glob = new Bun.Glob('*.md')
     for (const name of glob.scanSync({
-      cwd: join(root, band.name),
+      cwd: join(root, folder.name),
       onlyFiles: true,
     })) {
       files.push({
-        rel: relPath('.claude', 'rules', band.name, name),
-        subdir: band.name,
+        rel: relPath('.claude', 'rules', folder.name, name),
+        subdir: folder.name,
         name: name.slice(0, -'.md'.length),
       })
     }

package/src/pr/frames.ts

@@ -1,7 +1,10 @@
 import { readFile } from 'node:fs/promises'
 
 /** The branch holding review frames. It never merges into a branch anyone checks out. */
-export const FRAMES_BRANCH = 'canon-frames'
+export const FRAMES_BRANCH = 'canon/frames'
+
+/** The branch frames lived on before the rename. A drop and a prune drain it and an add never writes it. */
+export const LEGACY_FRAMES_BRANCH = 'canon-frames'
 
 /** The eight bytes every PNG opens with. A frame that lacks them embeds as a broken image. */
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
@@ -94,6 +97,7 @@ export type DropResult =
       readonly removed: readonly number[]
       readonly commit?: string
       readonly deleted?: boolean
+      readonly legacy?: true
     }
   | { readonly kind: 'refused'; readonly reason: FramesRefusal }
 
@@ -105,6 +109,7 @@ export type PruneResult =
       readonly unread: readonly number[]
       readonly commit?: string
       readonly deleted?: boolean
+      readonly legacy?: true
     }
   | { readonly kind: 'refused'; readonly reason: FramesRefusal }
 
@@ -341,3 +346,63 @@ export async function pruneFrames(
     unread: unread.sort((a, b) => a - b),
   }
 }
+
+function mergeNumbers(
+  first: readonly number[],
+  second: readonly number[],
+): number[] {
+  return [...new Set([...first, ...second])].sort((a, b) => a - b)
+}
+
+/** Whether a drain pass changed the legacy ref, by removing a pull request or deleting it. */
+function touchedLegacy(result: DropResult): boolean {
+  return (
+    result.kind === 'dropped' &&
+    (result.removed.length > 0 || result.deleted === true)
+  )
+}
+
+/**
+ * Drops on the current branch, then on the legacy one. The legacy pass only
+ * removes, and a refusal there never fails a drop the current branch already
+ * finished, since a target that never held the legacy ref reads it as missing
+ * and a token may be unable to read it at all.
+ */
+export async function dropFramesWithLegacy(
+  api: FramesApi,
+  legacy: FramesApi,
+  numbers: readonly number[],
+): Promise<DropResult> {
+  const current = await dropFrames(api, numbers)
+  if (current.kind === 'refused') return current
+  const drained = await dropFrames(legacy, numbers)
+  if (drained.kind === 'refused' || !touchedLegacy(drained)) return current
+  return {
+    ...current,
+    removed: mergeNumbers(current.removed, drained.removed),
+    legacy: true,
+  }
+}
+
+/** The prune counterpart of `dropFramesWithLegacy`, with the same legacy semantics. */
+export async function pruneFramesWithLegacy(
+  api: FramesApi,
+  legacy: FramesApi,
+  days: number,
+  now: Date,
+): Promise<PruneResult> {
+  const current = await pruneFrames(api, days, now)
+  if (current.kind === 'refused') return current
+  const drained = await pruneFrames(legacy, days, now)
+  if (drained.kind === 'refused') return current
+  const touched = drained.removed.length > 0 || drained.deleted === true
+  const kept = mergeNumbers(current.kept, drained.kept)
+  const unread = mergeNumbers(current.unread, drained.unread)
+  return {
+    ...current,
+    removed: mergeNumbers(current.removed, drained.removed),
+    kept,
+    unread,
+    ...(touched && { legacy: true as const }),
+  }
+}

package/src/sync/check.ts

@@ -531,12 +531,12 @@ export function parseNewSkills(paths: string): string[] {
 
 /**
  * What the target's `.claude/rules/` proves about its entitlement. `held` is
- * every rule name it carries and `bands` every band folder those names sit in.
+ * every rule name it carries and `folders` every rule folder those names sit in.
  *
  * Read off the installed tree rather than off a stack name, because
  * `gov install` records file hashes and never the stack it resolved, so the
  * chain a target consumed survives nowhere else. `installRules` copies each
- * rule into the subdirectory it was authored in, which is what makes the band
+ * rule into the subdirectory it was authored in, which is what makes the folder
  * folders legible as evidence.
  *
  * `successorOf` adds the name a held rule was renamed to, which the next sync
@@ -547,12 +547,12 @@ export function readInstalledRules(
   successorOf?: (name: string) => string | undefined,
 ): {
   held: Set<string>
-  bands: Set<string>
+  folders: Set<string>
 } {
   const dir = join(target, ...INSTALL_MARKERS.governance)
   const held = new Set<string>()
-  const bands = new Set<string>()
-  if (!isDirectory(dir)) return { held, bands }
+  const folders = new Set<string>()
+  if (!isDirectory(dir)) return { held, folders }
 
   for (const rel of new Bun.Glob('**/*.md').scanSync({
     cwd: dir,
@@ -566,34 +566,34 @@ export function readInstalledRules(
     held.add(name)
     const successor = successorOf?.(name)
     if (successor !== undefined) held.add(successor)
-    if (boundary > 0) bands.add(posix.slice(0, boundary))
+    if (boundary > 0) folders.add(posix.slice(0, boundary))
   }
 
-  return { held, bands }
+  return { held, folders }
 }
 
 /**
  * Narrows rules added upstream to the ones this target could receive and does
  * not already hold.
  *
- * The band test is the entitlement filter, and `bands` carries two sources: the
+ * The folder test is the entitlement filter, and `folders` carries two sources: the
  * folders the target already holds, and the folders holding a rule the base
  * stack resolves to.
  * A rule authored under `lang/` or `ui/` is named by an individual stack, so it
  * belongs to some targets and not others, and listing every added file would
  * tell a base consumer about rules it was never entitled to. The test
- * over-reports inside a band a target already carries, since one folder can be
+ * over-reports inside a folder a target already carries, since one folder can be
  * reached by more than one stack, and that costs a line where under-reporting
  * would cost the whole point of the section.
  *
- * The `held` test is what keeps a rule that moved bands upstream out. A rename
+ * The `held` test is what keeps a rule that moved folders upstream out. A rename
  * reaches this diff as an addition, and the target already has the file under
  * its old folder, so matching by name is what tells the two apart.
  */
 export function selectNewRules(
   paths: string,
   held: ReadonlySet<string>,
-  bands: ReadonlySet<string>,
+  folders: ReadonlySet<string>,
 ): string[] {
   const prefix = 'governance/rules/'
   const names = new Set<string>()
@@ -604,11 +604,11 @@ export function selectNewRules(
 
     const rel = trimmed.slice(prefix.length)
     const boundary = rel.indexOf('/')
-    const band = boundary === -1 ? '' : rel.slice(0, boundary)
+    const folder = boundary === -1 ? '' : rel.slice(0, boundary)
     const name = basename(rel, '.md')
 
     if (held.has(name)) continue
-    if (band !== '' && !bands.has(band)) continue
+    if (folder !== '' && !folders.has(folder)) continue
 
     names.add(name)
   }
@@ -617,29 +617,29 @@ export function selectNewRules(
 }
 
 /**
- * Band folders holding a rule the base stack resolves to. Every governance
+ * Rule folders holding a rule the base stack resolves to. Every governance
  * stack extends base, so a new rule authored beside one of base's rules is
  * reported to every target the fallback below reads.
  *
- * This is what covers a band no target can carry yet. Entitlement is otherwise
- * read off folders the target already holds, and a band base reaches later
+ * This is what covers a folder no target can carry yet. Entitlement is otherwise
+ * read off folders the target already holds, and a folder base reaches later
  * exists in no installed tree, so without this the rules inside it would reach
  * nobody. Read through `resolveRules` rather than off the stack's entries,
  * since base names its rules one by one and an entry is a slug rather than a
  * folder.
  *
  * A folder only a leaf stack reaches is deliberately absent. It is entitled to
- * some targets and not others, which is the distinction the band test makes and
+ * some targets and not others, which is the distinction the folder test makes and
  * the installed tree is the only evidence of.
  */
-export function baseBands(root: string): Set<string> {
+export function baseFolders(root: string): Set<string> {
   const resolution = resolveRules(root, 'base')
   if (!resolution.ok) return new Set()
 
   return new Set(
     lookupRules(root, resolution.rules)
       .found.map((source) => source.subdir.split(sep)[0] ?? '')
-      .filter((band) => band !== ''),
+      .filter((folder) => folder !== ''),
   )
 }
 
@@ -651,7 +651,7 @@ export function baseBands(root: string): Set<string> {
  * `collectMissing` reports per file through the domain scan, so a rule the
  * chain names and the target lacks reaches both surfaces the same way.
  *
- * The diff-and-bands path stays as the fallback for a target stamped before
+ * The diff-and-folder path stays as the fallback for a target stamped before
  * governance recorded a chain. Rules are domain-scoped there too, so it
  * measures from governance's own anchor rather than from the oldest anchor
  * across domains the way `readNewSkills` does. A shared anchor would let
@@ -670,7 +670,7 @@ export function baseBands(root: string): Set<string> {
  * unmeasured result from a clean one.
  *
  * A recorded chain naming a stack the toolkit no longer ships falls through to
- * the band-based path below rather than reporting the empty list an
+ * the folder-based path below rather than reporting the empty list an
  * unresolved chain would otherwise produce. That empty list reads exactly
  * like a target holding everything, which is the same failure this function
  * exists to close, so a retired stack name is read the same as no chain at
@@ -702,8 +702,8 @@ export async function readNewRules(
     'governance/rules/',
   ])
 
-  const { held, bands } = readInstalledRules(target, successorResolver(root))
-  return selectNewRules(paths, held, bands.union(baseBands(root)))
+  const { held, folders } = readInstalledRules(target, successorResolver(root))
+  return selectNewRules(paths, held, folders.union(baseFolders(root)))
 }
 
 async function readUpstream(

package/tooling/astro/configs/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "skipLibCheck": true,
-    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "types": ["vitest/globals", "@testing-library/jest-dom/vitest"],
     "paths": {
       "@/*": ["./src/*"]
     }

package/tooling/astro/reference.md

@@ -20,7 +20,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
-- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
+- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, `@/` paths.
 - `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
 - `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling/stacks.md` for the measurement.
 
@@ -32,7 +32,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Page-level behavior is verified by Playwright against rendered output.
 
-Vitest is pinned to `^3` in the web manifest. Vitest `^4` bundles rolldown-vite (vite@8), which ignores the esbuild JSX config in `@vitejs/plugin-react` and breaks `.tsx` tests, plus emits deprecation warnings. Unpin once `@astrojs/react` ships a rolldown-aware plugin (or astro's bundled vite reaches 8).
+Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin avoided `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro now bundles Vite 8 itself, so that conflict no longer applies.
 
 ## Prettier (extend)
 

package/tooling/base/configs/scripts/verify.json

@@ -1,3 +1,3 @@
 {
-  "require": ["format", "check:format"]
+  "require": ["check:format"]
 }

package/tooling/base/configs/scripts/verify.ts

@@ -46,16 +46,10 @@ const PHASES: readonly Phase[] = [
     failed: 'Lint failed',
     passed: 'Lint passed',
   },
-  {
-    script: 'format',
-    title: 'Formatting',
-    failed: 'Format failed',
-    passed: 'Format applied',
-  },
   {
     script: 'check:format',
     title: 'Format check',
-    failed: 'Format check failed',
+    failed: "Format check failed. Run 'bun run format' to fix it",
     passed: 'Format check passed',
   },
   {
@@ -85,7 +79,7 @@ const PHASES: readonly Phase[] = [
 // A subfolder synced with --skip base declares none of these, since the
 // repository root owns them, so a list that does not require one runs it only
 // where the folder declares it.
-const BASE_PHASES = new Set(['format', 'check:format'])
+const BASE_PHASES = new Set(['check:format'])
 
 // An add-on stack declares these, keyed to the stack that ships each, so a
 // folder that never synced the add-on skips the phase rather than failing it.

package/tooling/base/reference.md

@@ -13,8 +13,8 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `.prettierrc`: `semi: false`, `singleQuote: true`, plus a parser override per non-standard extension (`.mdx` to `markdown`).
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, `subject-case` disabled, and a local `no-claude-co-author` rule refusing a `Co-authored-by` trailer that names Claude or Anthropic.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `scripts/verify.ts`: the one verify runner every stack shares, and the command behind `check`. It runs typecheck, lint, format, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
-- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires its two phases, so a base-only target still fails on a missing one. The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first. These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
+- `scripts/verify.ts`: the one verify runner every stack shares, and the command behind `check`. It runs typecheck, lint, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
+- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires `check:format`, so a base-only target still fails on a missing one. The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first. These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
 
 ## What ships as user-owned seeds
 
@@ -75,15 +75,15 @@ Sticky negative knowledge. Do not relearn.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Repairs a checkout through `scripts/verify.ts`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
-| `bun run check:format` | Asserts prettier formatting without writing                                                                                               |
-| `bun run format`       | Writes prettier formatting in place                                                                                                       |
-| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                               |
+| Script                 | What it does                                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bun run check`        | Gates a checkout through `scripts/verify.ts` and writes nothing. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check:format` | Asserts prettier formatting without writing                                                                                                                |
+| `bun run format`       | Writes prettier formatting in place                                                                                                                        |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                                                |
 
 Base writes `check` as a `[scripts.override]`, so a sync replaces whatever `check` a target declared, including one that chained further checks after the runner. Re-add a chained check as its own script after a sync.
 
-`bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatter could not fix. The pull request workflow calls `check:format` directly, and that is the gate.
+`bun run check` gates a checkout and writes nothing. Formatting drift fails it at `check:format`, and the failure line names `bun run format`, the one command that writes. It once ran `format` first to auto-fix drift, which rewrote files in a checkout several sessions share on every push and left a gate that could not fail. That was rejected, so the writing pass stays in `bun run format` and a push fails until it runs. The pull request workflow calls `check:format` directly as well.
 
-`scripts/verify.ts`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the format check above.
+`scripts/verify.ts`'s `Markdown bans` stage gates on banned characters. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the format check above.

package/tooling/base/seeds/canon/context/ci.md

@@ -13,12 +13,12 @@ Owns the GitHub Actions workflow that gates a merge: which events start a run, a
 
 - `.github/workflows/` owns the workflow definitions a trigger below starts
 
-## Triggers
+### Triggers
 
 - Pull requests targeting `main`
 - `workflow_dispatch` (manual run from the Actions tab)
 
-## Checks
+### Checks
 
 Defined in `.github/workflows/verify.yml`. All jobs must pass before merge.
 
@@ -26,6 +26,6 @@ Defined in `.github/workflows/verify.yml`. All jobs must pass before merge.
 | ------ | ---------------------- | ----------------- |
 | Format | `bun run check:format` | prettier is clean |
 
-## Running CI locally
+### Running CI locally
 
-`bun run check` runs the same assert plus auto-formats first. If CI fails on format, run `bun run check` locally and commit the diff.
+`bun run check` runs the same assert and writes nothing. If CI fails on format, run `bun run format` locally and commit the diff.

package/tooling/base/seeds/canon/context/development.md

@@ -14,24 +14,24 @@ Owns how the project runs on a developer machine: installing the toolchain, the
 - `scripts/` owns the shell scripts the package scripts below call
 - `.husky/` owns the git hooks
 
-## Setup
+### Setup
 
 - Install [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
 - Install dependencies: `bun install`
 
-## Scripts
+### Scripts
 
-| Command          | Purpose                                                                        |
-| ---------------- | ------------------------------------------------------------------------------ |
-| `bun run check`  | Repairs locally. Auto-formats, then asserts what the formatters could not fix. |
-| `bun run format` | Auto-fix prettier formatting.                                                  |
+| Command          | Purpose                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `bun run check`  | Gates locally and writes nothing. Fails on formatting drift until `bun run format` runs. |
+| `bun run format` | Auto-fix prettier formatting.                                                            |
 
-## Shell scripts
+### Shell scripts
 
 All `.sh` files live under `scripts/`. Do not place shell scripts outside `scripts/`.
 
-## Husky hooks
+### Husky hooks
 
 - `pre-commit` runs `lint-staged` (prettier on staged files).
 - `commit-msg` runs `commitlint` against the conventional commit format.
-- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters across every tracked markdown file except `CHANGELOG.md`. After pushing, run `git status`. If files changed, commit the diff as `style(<scope>):` and push again.
+- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters across every tracked markdown file except `CHANGELOG.md`. A push fails on formatting drift until `bun run format` runs, since the hook writes nothing.

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -26,6 +26,14 @@ case "$file_path" in
 */.claude/.tmp/* | */.canon/tmp/*) exit 0 ;;
 esac
 
+# A background session's temp folder is the harness's own, told to the session
+# and located under the home folder, outside every project. Matching its shape
+# rather than reading CLAUDE_JOB_DIR holds whether or not this hook's
+# environment carries the variable.
+case "$file_path" in
+*/.claude/jobs/*/tmp/*) exit 0 ;;
+esac
+
 # A project whose own root sits under a path carrying a tmp segment is not
 # writing to system temp, and the bare pattern below would trip on every source
 # file it holds. The project root is stripped before the match rather than

package/tooling/vite-react/configs/tsconfig.json

@@ -18,7 +18,7 @@
     "types": [
       "vite/client",
       "vitest/globals",
-      "@testing-library/jest-dom",
+      "@testing-library/jest-dom/vitest",
       "node"
     ],
     "paths": {

package/tooling/vite-react/configs/vitest.config.ts

@@ -1,6 +1,6 @@
 import { defineConfig, mergeConfig } from 'vitest/config'
 
-import viteConfig from './vite.config'
+import viteConfig from './vite.config.ts'
 
 export default mergeConfig(
   viteConfig,

package/tooling/vite-react/reference.md

@@ -17,9 +17,9 @@ The vite-react stack covers Vite + React + TypeScript projects: web apps and Chr
 ## What ships as golden configs
 
 - `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path. Dev port `5173` and preview port `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
-- `vitest.config.ts`: merges from `vite.config.ts`, jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
+- `vitest.config.ts`: merges from `vite.config.ts` (imported with its `.ts` extension, which Vite 8 requires), jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
 - `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, trace under `use`.
-- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom` in types.
+- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
 
 ## Chrome extension variant
 

package/tooling/web/configs/src/test/setup.ts

@@ -1,4 +1,4 @@
-import '@testing-library/jest-dom'
+import '@testing-library/jest-dom/vitest'
 
 import { cleanup } from '@testing-library/react'
 import { afterEach } from 'vitest'

package/tooling/web/manifest.toml

@@ -22,9 +22,9 @@ packages = [
   "@types/react",
   "@types/react-dom",
   "@types/node",
-  "vitest@^3",
-  "@vitest/coverage-v8@^3",
-  "@vitest/ui@^3",
+  "vitest@^5",
+  "@vitest/coverage-v8@^5",
+  "@vitest/ui@^5",
   "jsdom",
   "@testing-library/react",
   "@testing-library/jest-dom",

package/tooling/web/reference.md

@@ -11,7 +11,7 @@ The web layer covers web-universal tooling shared across Vite + React, Astro, an
 Golden config files live in `tooling/web/configs/` and are copied into the target on `canon tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
 - `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.
+- `src/test/setup.ts`: `@testing-library/jest-dom/vitest` 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, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--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 widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--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`.
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
 - `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.