@erclx/canon 5.35.0 → 5.37.0

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/src/sync/copy.ts

@@ -4,11 +4,10 @@ import { dirname } from 'node:path'
 /**
  * Copies with `cp` semantics. Two behaviors matter and neither is the default
  * in the obvious alternatives. `Bun.write` drops the executable bit, which
- * would land husky hooks and `scripts/verify.sh` non-executable. Plain
- * `copyFile` imposes the source mode on an existing destination, so a file the
- * target deliberately restricted to 600, or an earlier stack set executable,
- * comes back at the source's mode. `cp` leaves an existing destination's mode
- * alone.
+ * would land husky hooks non-executable. Plain `copyFile` imposes the source
+ * mode on an existing destination, so a file the target deliberately
+ * restricted to 600, or an earlier stack set executable, comes back at the
+ * source's mode. `cp` leaves an existing destination's mode alone.
  *
  * Every domain that writes into a target routes through here. The tooling
  * inject path found the trap first, and the sync engine inherits it for every

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/manifest.toml

@@ -20,7 +20,6 @@ packages = [
 "preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 "astro" = "astro"
 "typecheck" = "astro check"
-"setup" = "./scripts/setup.sh"
 "card:dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev --config card.config.mjs"
 "card:check" = "bash scripts/check-card-exclusion.sh"
 

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,15 +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).
-
-## Setup script
-
-- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
-- Prompt for project name, normalize to kebab-case, derive title-cased display name.
-- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
-- Update `astro.config.mjs`: set `site` if provided.
-- Update `<title>` and `<meta name="description">` in the default layout.
+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", "check:shell"]
+  "require": ["check:format"]
 }

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

@@ -27,8 +27,12 @@ interface Phase {
   readonly title: string
   readonly failed: string
   readonly passed: string
+  readonly tools?: readonly Tool[]
 }
 
+const SHELL_TOOLS_HINT =
+  "Install it with 'sudo apt-get install shfmt shellcheck' or 'brew install shfmt shellcheck'"
+
 const PHASES: readonly Phase[] = [
   {
     script: 'typecheck',
@@ -42,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',
   },
   {
@@ -59,6 +57,10 @@ const PHASES: readonly Phase[] = [
     title: 'Shell',
     failed: 'Shell check failed',
     passed: 'Shell check passed',
+    tools: [
+      { name: 'shfmt', hint: SHELL_TOOLS_HINT },
+      { name: 'shellcheck', hint: SHELL_TOOLS_HINT },
+    ],
   },
   {
     script: 'test:run',
@@ -77,7 +79,11 @@ 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', 'check:shell'])
+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.
+const ADD_ON_PHASES = new Map([['check:shell', 'shell']])
 
 const PHASE_LIST = 'scripts/verify.json'
 const CARD_EXCLUSION = 'scripts/check-card-exclusion.sh'
@@ -226,8 +232,8 @@ function readDeclaredScripts(): Set<string> {
   )
 }
 
-function checkTools(list: PhaseList): void {
-  for (const tool of list.tools) {
+function checkTools(tools: readonly Tool[]): void {
+  for (const tool of tools) {
     if (onPath(tool.name)) continue
     fail(
       tool.hint === undefined
@@ -250,7 +256,8 @@ function runPhase(
   declared: Set<string>,
 ): void {
   const isBase = BASE_PHASES.has(phase.script)
-  if (!required && !isBase) return
+  const addOn = ADD_ON_PHASES.get(phase.script)
+  if (!required && !isBase && addOn === undefined) return
 
   logStep(phase.title)
   if (!declared.has(phase.script)) {
@@ -260,10 +267,13 @@ function runPhase(
       )
     }
     logSkip(
-      `Skipped: ${phase.script} is not declared here, so the repository root runs it`,
+      addOn === undefined
+        ? `Skipped: ${phase.script} is not declared here, so the repository root runs it`
+        : `Skipped: ${phase.script} is not declared here. Run 'canon tooling sync ${addOn} . --write' to add it`,
     )
     return
   }
+  checkTools(phase.tools ?? [])
   runCheck(`bun run ${phase.script}`, phase.failed)
   logInfo(phase.passed)
 }
@@ -332,7 +342,7 @@ function checkMarkdownBans(): void {
 function main(): void {
   const declared = readDeclaredScripts()
   const list = readPhaseList()
-  checkTools(list)
+  checkTools(list.tools)
   checkPreconditions(list)
 
   if (!isNested) print(`${GREY}┌${NC}`)

package/tooling/base/manifest.toml

@@ -6,7 +6,7 @@ scaffold = ""
 
 [sync]
 source = "configs"
-per_root = ["scripts/verify.sh", "scripts/verify.ts", "scripts/verify.json"]
+per_root = ["scripts/verify.ts", "scripts/verify.json"]
 
 [dependencies.dev]
 packages = [
@@ -17,11 +17,12 @@ packages = [
 ]
 
 [scripts]
-"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --diff --indent 2 {} +"
-"check:shell" = "find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
-"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --write --indent 2 {} +"
+"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore ."
+"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore ."
 "prepare" = "husky"
-"check" = "./scripts/verify.sh"
+
+[scripts.override]
+"check" = "bun scripts/verify.ts"
 
 [gitignore]
 "# System" = [".DS_Store"]

package/tooling/base/reference.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
+The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, conventional commits, git hooks, CI, and the verify runner. Every other stack extends it, so a decision made here is one every stack inherits. Shell formatting and linting live in the `shell` add-on stack, which a project syncs once it writes shell.
 
 A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs scenarios` carries the recipe.
 
@@ -11,13 +11,10 @@ A repository with several language roots layers this stack once at the root and
 Golden config files live in `tooling/base/configs/` and are copied into the target on `canon tooling sync base . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
 - `.prettierrc`: `semi: false`, `singleQuote: true`, plus a parser override per non-standard extension (`.mdx` to `markdown`).
-- `.shellcheckrc`: `external-sources=true`. Required for shellcheck to follow `source` directives.
-- `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
 - `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.sh`: the maintenance entry point behind `check`, a wrapper that hands off to `scripts/verify.ts`.
-- `scripts/verify.ts`: the one verify runner every stack shares. 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 three phases, so a base-only target still fails on a missing one. These three 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
 
@@ -32,14 +29,12 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 ## Tool pairing
 
 - Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
-- Formatting: Prettier for what it parses, shfmt for shell. Two formatters because Prettier has no shell parser.
-- Shell: shfmt formats and shellcheck lints at warning severity. Both take their files from `find scripts -name '*.sh'`, since `scripts/` can mix shell with TypeScript and shellcheck has no directory mode. A shell script with a shebang and no `.sh` extension is covered by neither, so give it the extension.
+- Formatting: Prettier for what it parses. Prettier has no shell parser, so shell formatting is the `shell` stack's.
 - Commits: commitlint against conventional commits, wired through the husky `commit-msg` hook. Format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
 - Dev dependencies: `prettier`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
 
 ## File layout
 
-- All shell scripts live in `scripts/`. Do not place a `.sh` file outside it.
 - Hooks live in `.husky/`, seeded context docs in `canon/context/`.
 - The `canon/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md` and `canon/REQUIREMENTS.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `canon/context/`. Indexes stay opt-in.
 
@@ -57,11 +52,10 @@ Seeded baseline globs:
 
 - `**/*.{json,md,mdc}` runs `prettier --write --ignore-path .gitignore --ignore-path .prettierignore`
 - `**/*.md` runs `canon indexes regen`
-- `**/*.sh` runs `shfmt --write --indent 2` then `shellcheck --severity=warning`
 
 ## CI
 
-- Steps: checkout, setup Bun at latest, `bun install --frozen-lockfile`, install `shfmt` and `shellcheck` via apt, then `check:format` and `check:shell`.
+- Steps: checkout, setup Bun at latest, `bun install --frozen-lockfile`, then `check:format`.
 - CI asserts and never writes. Format must be clean before push.
 
 ## Gitignore
@@ -78,19 +72,18 @@ Sticky negative knowledge. Do not relearn.
 - Do NOT invoke prettier without both `--ignore-path .gitignore --ignore-path .prettierignore`. Passing one drops the other, since the flag replaces the default rather than adding to it.
 - Do NOT omit `--log-level warn` from a prettier invocation. The default prints a line per unchanged file.
 - Do NOT put logic in a husky hook and expect its shebang to hold. Husky runs hooks as `sh -e`, so a hook carrying logic is POSIX sh under errexit whatever the first line says.
-- Do NOT drop the `[*.sh]` block from `.editorconfig` because shfmt already sets indentation. The editor and shfmt then disagree and produce spurious git diffs.
-- Do NOT copy lint-staged's `**/*.sh` glob into a package.json script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Repairs a checkout via `scripts/verify.ts`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
-| `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                 |
-| `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                   |
-| `bun run format`       | Writes prettier and shfmt 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`                                                                                                |
 
-`bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format` and `check:shell` directly, and those two are the gate.
+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.
 
-`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 two checks above.
+`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 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/.github/workflows/verify.yml

@@ -22,11 +22,5 @@ jobs:
       - name: Install Dependencies
         run: bun install --frozen-lockfile
 
-      - name: Install Shell Tools
-        run: sudo apt-get install -y shfmt shellcheck
-
       - name: Check Formatting
         run: bun run check:format
-
-      - name: Check Shell
-        run: bun run check:shell

package/tooling/base/seeds/.lintstagedrc

@@ -2,6 +2,5 @@
   "**/*.{json,md,mdc}": [
     "prettier --write --ignore-path .gitignore --ignore-path .prettierignore"
   ],
-  "**/*.md": ["canon indexes regen"],
-  "**/*.sh": ["shfmt --write --indent 2", "shellcheck --severity=warning"]
+  "**/*.md": ["canon indexes regen"]
 }

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

@@ -13,20 +13,19 @@ 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.
 
-| Check  | Command                | What it asserts                    |
-| ------ | ---------------------- | ---------------------------------- |
-| Format | `bun run check:format` | prettier and shfmt are clean       |
-| Shell  | `bun run check:shell`  | shellcheck passes at warning level |
+| Check  | Command                | What it asserts   |
+| ------ | ---------------------- | ----------------- |
+| Format | `bun run check:format` | prettier is clean |
 
-## Running CI locally
+### Running CI locally
 
-`bun run check` runs the same three asserts 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 and shfmt 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, shfmt, shellcheck on staged files).
+- `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
@@ -57,5 +65,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
+msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, not system temp. See the Scratch rule (scratch.md, under canon/ in your installed governance rules).'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -62,13 +62,28 @@ fi
 hits=$(printf '%s' "$record" |
   jq -r '.entries[]?.bans[]? | ":\(.line):\(.column + 1)  \(.kind)  \(.term)"' 2>/dev/null)
 
+# Two advisory measures ride in the same record and never gate. A heading's
+# case is read for the whole file, since it is cheap to fix where it stands. A
+# colon is kept only where the word before it and the colon appear in the text
+# this write carried, since an edit often rewrites part of a line and a
+# whole-line match would drop exactly that case. The verb names that word as
+# `lead`, since slicing `text` at `column` miscounts after an emoji, and a
+# binary predating the field falls back to the slice. A file holds colons nobody is
+# asking this edit to answer for.
+new=$(printf '%s' "$input" |
+  jq -r '[.tool_input.new_string?, .tool_input.content?, (.tool_input.edits[]?.new_string?)] | map(select(. != null)) | join("\n")' 2>/dev/null)
+headings=$(printf '%s' "$record" |
+  jq -r '.entries[]?.headingCase[]? | ":\(.line)  \(.text)"' 2>/dev/null)
+colons=$(printf '%s' "$record" |
+  jq -r --arg new "$new" '.entries[]?.colons[]? | (.lead // (.text[:.column] | sub("^.*\\s"; ""))) as $lead | select($new | contains($lead + ":")) | ":\(.line):\(.column + 1)  \(.text)"' 2>/dev/null)
+
 # A set the verb shipped empty measures nothing and would report a clean file.
 # Reading the findings alone turns that narrowed check into a pass, so the field
 # is read beside them.
 empty=$(printf '%s' "$record" |
   jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
+[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
@@ -82,7 +97,17 @@ elif [ -n "$empty" ]; then
 fi
 
 if [ -n "$hits" ]; then
-  found=$(printf 'Standards-audit: markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
+  found=$(printf 'Standards-audit: markdown.md violations in %s. Split the sentence or rewrite it. A colon or a comma standing where the em dash was is the same sentence. A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
+  msg="${msg:+$msg$nl}$found"
+fi
+
+if [ -n "$headings" ]; then
+  found=$(printf 'Standards-audit: headings in %s are not sentence case. Lowercase every word after the first unless it is a proper noun, and leave a proper noun as it is.\n%s' "$file" "$headings")
+  msg="${msg:+$msg$nl}$found"
+fi
+
+if [ -n "$colons" ]; then
+  found=$(printf 'Standards-audit: this write added a colon in the middle of a sentence in %s. A colon belongs after a label or at the end of a line introducing a list. Split the sentence or rewrite it.\n%s' "$file" "$colons")
   msg="${msg:+$msg$nl}$found"
 fi
 

package/tooling/claude/seeds/CLAUDE.md

@@ -16,4 +16,4 @@
 ## Key paths
 
 - `src/`: [description]
-- `canon/DESIGN.md`: design tokens and the visual system
+- `canon/DESIGN.md`: visual intent, pointing at the stylesheet that holds the values