@erclx/canon 5.35.0 → 5.36.0

package/src/markdown/heading-case.ts

@@ -0,0 +1,74 @@
+import { bodyLines, maskDisplayed } from '@/markdown/scan'
+
+export interface HeadingCaseFinding {
+  readonly line: number
+  /** The heading or title as written, markers removed. */
+  readonly text: string
+  /** Every word after the first that opens on a capital. */
+  readonly words: readonly string[]
+}
+
+const HEADING = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/
+const TITLE = /^title:\s*(["']?)(.*?)\1\s*$/
+const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
+const CAPITALIZED = /^[A-Z][a-z]/
+
+/**
+ * The words of `text` that break sentence case.
+ *
+ * A code span stands for one lowercase word, so a heading opening on one
+ * counts that span as its first word. The first word with a letter in it is
+ * exempt, which keeps a leading numeral from promoting the next word.
+ */
+function capitalizedAfterFirst(text: string): string[] {
+  const masked = maskDisplayed(text.replace(CODE_SPAN, 'code'))
+    .replace(/\s+/g, ' ')
+    .trim()
+  const words = masked === '' ? [] : masked.split(' ')
+  const flagged: string[] = []
+  let seenFirst = false
+
+  for (const raw of words) {
+    const word = raw.replace(/^[^\p{L}]+/u, '')
+    if (!/\p{L}/u.test(raw)) continue
+    if (!seenFirst) {
+      seenFirst = true
+      continue
+    }
+    if (CAPITALIZED.test(word)) flagged.push(word)
+  }
+
+  return flagged
+}
+
+/**
+ * Finds a heading or a frontmatter `title` carrying a capitalized word after
+ * its first, outside code spans and all-caps tokens.
+ *
+ * A proper noun is the one case it cannot tell from title case, so the finding
+ * is a warning and no names list backs it.
+ */
+export function findHeadingCase(source: string): HeadingCaseFinding[] {
+  const found: HeadingCaseFinding[] = []
+  const check = (line: number, text: string): void => {
+    const words = capitalizedAfterFirst(text)
+    if (words.length > 0) found.push({ line, text, words })
+  }
+
+  const frontmatter = FRONTMATTER.exec(source)
+  if (frontmatter) {
+    for (const [index, text] of frontmatter[1].split('\n').entries()) {
+      const title = TITLE.exec(text)
+      if (title) check(index + 2, title[2])
+    }
+  }
+
+  for (const line of bodyLines(source)) {
+    if (line.fenced) continue
+    const heading = HEADING.exec(line.text)
+    if (heading) check(line.number, heading[1])
+  }
+
+  return found
+}

package/src/shipped/references.ts

@@ -54,7 +54,7 @@ export const REFERENCE_MARKER = 'canon-allow-reference'
  * already ships `anthropics/claude-code#58345` in exactly that form.
  *
  * The trailing boundary is what the first shape of this pattern lacked, and it
- * costs a live finding to omit. `governance/rules/framework/250-tailwind.md`
+ * costs a live finding to omit. `governance/rules/framework/tailwind.md`
  * writes `bg-[#316ff6]`, a Tailwind arbitrary hex color, which an unbounded
  * `#[0-9]+` reads as pull request 316. Requiring a non-word character after the
  * digits rejects it and rejects nothing real, since a citation is always
@@ -171,20 +171,20 @@ const STANDARDS_CALL = /\bcanon standards(?![\w-])/g
 const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
 
 /**
- * A `.claude/rules/<segments>/<nnn>-<slug>.md` citation from a body under
- * `claude/skills/`, the installed-path spelling `598-authoring-layout.md`
- * bans a shipped skill body from citing as authority for its own behavior.
+ * A `.claude/rules/<segments>/<slug>.md` citation from a body under
+ * `claude/skills/`, the installed-path spelling `authoring-layout.md` bans a
+ * shipped skill body from citing as authority for its own behavior.
  *
- * Anchored on the trailing `\d{3}-[\w-]+\.md` rather than on the bare
- * `.claude/rules/` prefix, which is what keeps a folder mention carrying no
- * number, such as `create-rule`, `target-check`, and `target-setup` already
- * write correctly, from matching. The segment group between `rules/` and the
- * numbered file admits both a governance-namespace path
- * (`canon/canon/604-scratch.md`) and a project-namespace one
- * (`project/<subdir>/<n>-<slug>.md`) without distinguishing them, since
- * either shape is the same broken citation.
+ * Anchored on a trailing `.md` file rather than on the bare `.claude/rules/`
+ * prefix, which is what keeps a folder mention, such as `create-rule`,
+ * `target-check`, and `target-setup` write, from matching: it ends in `/` or
+ * names no `.md`. The segments between `rules/` and the file admit both a
+ * governance-namespace path (`canon/canon/scratch.md`) and a
+ * project-namespace one (`project/<subdir>/<slug>.md`) without distinguishing
+ * them, since either shape is the same broken citation, and the placeholder
+ * check spares the bracketed illustration.
  */
-const RULE_PATH = /(?<![\w./-])\.claude\/rules\/[^\s`)\]]*\/\d{3}-[\w-]+\.md\b/g
+const RULE_PATH = /(?<![\w./-])\.claude\/rules\/[^\s`)\]]*?[\w-]+\.md\b/g
 
 export interface ShippedReference {
   readonly file: string
@@ -246,7 +246,7 @@ function isDocsPathReportable(
  * Whether `file` sits in the one corpus `RULE_PATH` gates: a shipped skill
  * body, minus its own `REQUIREMENT.md`.
  *
- * The ban lives in `598-authoring-layout.md`, stated for one reader: a
+ * The ban lives in `authoring-layout.md`, stated for one reader: a
  * session loading the `SKILL.md` body a target actually receives.
  * `REQUIREMENT.md` is excluded for the reason that file states there, since a
  * maintainer or an audit command reads it rather than a session loading it,

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/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

@@ -34,14 +34,6 @@ Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Pag
 
 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.
-
 ## Prettier (extend)
 
 Add `prettier-plugin-astro` first in plugins, then `prettier-plugin-tailwindcss` last (per its docs). Add a parser override for `.astro` files.

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

@@ -1,3 +1,3 @@
 {
-  "require": ["format", "check:format", "check:shell"]
+  "require": ["format", "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',
@@ -59,6 +63,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 +85,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(['format', '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 +238,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 +262,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 +273,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 +348,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, 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.
 
 ## 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`        | 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`                                                                               |
 
-`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` 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.
+
+`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.

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

@@ -22,11 +22,10 @@ Owns the GitHub Actions workflow that gates a merge: which events start a run, a
 
 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
 
-`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 plus auto-formats first. If CI fails on format, run `bun run check` locally and commit the diff.

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

@@ -24,7 +24,7 @@ Owns how the project runs on a developer machine: installing the toolchain, the
 | 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.                                        |
+| `bun run format` | Auto-fix prettier formatting.                                                  |
 
 ## Shell scripts
 
@@ -32,6 +32,6 @@ All `.sh` files live under `scripts/`. Do not place shell scripts outside `scrip
 
 ## 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.

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

@@ -57,5 +57,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

package/tooling/claude/seeds/canon/DESIGN.md

@@ -1,57 +1,44 @@
 # Design
 
-Authoring guidance: the design standard.
+Authoring guidance: the design standard. Values live in `<your stylesheet>`, such as `src/styles/tokens.css` or a Tailwind `@theme` block. A project with none writes them under `.claude/design/project/`, beside the installed base stylesheet.
 
-## Personality
+## Overview
 
 One paragraph. Voice, tone, and the feeling a user should have. The same content a design intake form asks for.
 
-## Color
+## Colors
 
-One row per role. Intent is a short phrase a human can picture. Value is a hex or a named system token.
+Up to three rules a developer could get wrong.
 
-| Role       | Intent                        | Value |
-| ---------- | ----------------------------- | ----- |
-| background | page canvas                   |       |
-| surface    | cards, panels, raised blocks  |       |
-| text       | primary body text             |       |
-| muted      | secondary text, captions      |       |
-| accent     | links, primary action         |       |
-| success    | confirmations, positive state |       |
-| warning    | cautions, pending state       |       |
-| error      | failures, destructive action  |       |
+One row per role, naming its custom property. Intent is a short phrase a human can picture.
 
-## Typography
+| Role       | Property             | Intent                        |
+| ---------- | -------------------- | ----------------------------- |
+| background | `--color-background` | page canvas                   |
+| surface    | `--color-surface`    | cards, panels, raised blocks  |
+| text       | `--color-text`       | primary body text             |
+| muted      | `--color-muted`      | secondary text, captions      |
+| accent     | `--color-accent`     | links, primary action         |
+| success    | `--color-success`    | confirmations, positive state |
+| warning    | `--color-warning`    | cautions, pending state       |
+| error      | `--color-error`      | failures, destructive action  |
 
-One row per role. Size and line height in pixels or rem. Family names use their product casing.
+## Typography
 
-| Role    | Family | Weight | Size | Line height |
-| ------- | ------ | ------ | ---- | ----------- |
-| display |        |        |      |             |
-| heading |        |        |      |             |
-| body    |        |        |      |             |
-| label   |        |        |      |             |
-| code    |        |        |      |             |
+Up to three rules. How the roles divide between families, and any role that breaks the pattern.
 
 ## Spacing
 
-Base unit and scale. The renderer draws a swatch per step.
+One line. The base unit and how the scale steps.
 
-| Step | Multiplier | Value |
-| ---- | ---------- | ----- |
-| xs   | 0.5        |       |
-| sm   | 1          |       |
-| md   | 2          |       |
-| lg   | 3          |       |
-| xl   | 5          |       |
+## Shapes
 
-## Borders
+One row per role, naming its radius property.
 
-| Role    | Radius | Width | When used             |
-| ------- | ------ | ----- | --------------------- |
-| default |        |       | cards, inputs         |
-| pill    |        |       | tags, status chips    |
-| none    | 0      | 0     | edge-to-edge surfaces |
+| Role    | Property           | When used          |
+| ------- | ------------------ | ------------------ |
+| default | `--radius-default` | cards, inputs      |
+| pill    | `--radius-pill`    | tags, status chips |
 
 ## Motion
 

package/tooling/shell/configs/.github/workflows/shell.yml

@@ -0,0 +1,30 @@
+name: Shell
+# canon-no-seed: an add-on stack's workflow with no root counterpart by design, since the toolkit checks its own shell inside verify.yml.
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  shell-checks:
+    name: 🐚 Shell Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Shell Tools
+        run: sudo apt-get install -y shfmt shellcheck
+
+      - name: Check Shell
+        run: bun run check:shell

package/tooling/shell/manifest.toml

@@ -0,0 +1,12 @@
+[stack]
+name = "shell"
+extends = ""
+runtime = "bun"
+scaffold = ""
+
+[sync]
+source = "configs"
+
+[scripts]
+"check:shell" = "find scripts -name '*.sh' -exec shfmt --diff --indent 2 {} + && find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
+"format:shell" = "find scripts -name '*.sh' -exec shfmt --write --indent 2 {} +"