@erclx/canon 4.0.0

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

@@ -0,0 +1,33 @@
+---
+title: CI
+description: GitHub Actions workflow triggers and checks
+---
+
+# CI
+
+## Overview
+
+Owns the GitHub Actions workflow that gates a merge: which events start a run, and which checks have to pass before the branch can land. The checks call package scripts rather than defining commands of their own, so what each one runs is the development entry's subject.
+
+## Layout
+
+- `.github/workflows/` owns the workflow definitions a trigger below starts
+
+## Triggers
+
+- Pull requests targeting `main`
+- `workflow_dispatch` (manual run from the Actions tab)
+
+## 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       |
+| Spell  | `bun run check:spell`  | cspell passes against dictionaries |
+| Shell  | `bun run check:shell`  | shellcheck passes at warning level |
+
+## 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.

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

@@ -0,0 +1,37 @@
+---
+title: Development
+description: Local dev workflow, scripts, and husky hooks
+---
+
+# Development
+
+## Overview
+
+Owns how the project runs on a developer machine: installing the toolchain, the scripts that verify a change, and the git hooks that run them before a commit or a push leaves. CI calls the same scripts from a workflow, which is the CI entry's subject.
+
+## Layout
+
+- `scripts/` owns the shell scripts the package scripts below call
+- `.husky/` owns the git hooks
+
+## Setup
+
+- Install [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
+- Install dependencies: `bun install`
+
+## 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.                                        |
+
+## Shell scripts
+
+All `.sh` files live under `scripts/`. Do not place shell scripts outside `scripts/`.
+
+## Husky hooks
+
+- `pre-commit` runs `lint-staged` (prettier, cspell, shfmt, shellcheck on staged files).
+- `commit-msg` runs `commitlint` against the conventional commit format.
+- `pre-push` runs `bun run check`. After pushing, run `git status`. If files changed, commit the diff as `style(<scope>):` and push again.

package/tooling/base/seeds/.claude/context/index.md

@@ -0,0 +1,11 @@
+---
+title: Context
+subtitle: Per-domain narrative loaded on demand
+---
+
+# Context
+
+Per-domain narrative loaded on demand
+
+- [CI](ci.md): GitHub Actions workflow triggers and checks
+- [Development](development.md): Local dev workflow, scripts, and husky hooks

package/tooling/base/seeds/.cspell/tech-stack.txt

@@ -0,0 +1,19 @@
+canon
+bradlc
+bunx
+commitlint
+dbaeumer
+dotfolders
+esbenp
+frontmatter
+lintstagedrc
+mkhl
+parallelizable
+scannability
+shellcheck
+shfmt
+timonwong
+wireframe
+wireframes
+worktree
+worktrees

package/tooling/base/seeds/.lintstagedrc

@@ -0,0 +1,8 @@
+{
+  "**/*.{json,md,mdc}": [
+    "prettier --write --ignore-path .gitignore --ignore-path .prettierignore",
+    "cspell --no-must-find-files"
+  ],
+  "**/*.md": ["canon indexes regen"],
+  "**/*.sh": ["shfmt --write --indent 2", "shellcheck --severity=warning"]
+}

package/tooling/base/seeds/cspell.json

@@ -0,0 +1,20 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "useGitignore": true,
+  "gitignoreRoot": ["."],
+  "dictionaryDefinitions": [
+    {
+      "name": "project-terms",
+      "path": ".cspell/project-terms.txt",
+      "addWords": true
+    },
+    {
+      "name": "tech-stack",
+      "path": ".cspell/tech-stack.txt",
+      "addWords": true
+    }
+  ],
+  "dictionaries": ["project-terms", "tech-stack"],
+  "ignorePaths": [".cspell/**", ".git/**"]
+}

package/tooling/claude/manifest.toml

@@ -0,0 +1,14 @@
+# Consumed only by `canon claude init`. Claude is not a discoverable tooling stack
+# and is excluded from `canon tooling` discovery via scripts/lib/tooling.sh.
+
+[stack]
+name = "claude"
+extends = ""
+runtime = ""
+scaffold = ""
+
+# Checked against this repository's own `.gitignore` by
+# scripts/core/check-ignore-parity.sh, which also holds the two `.claude/` paths
+# this array deliberately omits and the reason each stays out.
+[gitignore]
+"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/proposals/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]

package/tooling/claude/reference.md

@@ -0,0 +1,79 @@
+# Tooling Claude reference
+
+## Overview
+
+The claude stack installs the `.claude/` workflow directory into a project. State docs are seeds, written once and never overwritten by tooling. `CLAUDE.md` is a seed, filled in per project after init.
+
+## Structure
+
+```plaintext
+.claude/
+├── CLAUDE.md          ← seeded. Project context and rules, auto-loaded by Claude Code each session
+├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
+├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
+├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
+├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
+├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
+├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
+├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install
+├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `canon claude setup`.
+├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs into `archive/`.
+├── review/            ← gitignored, one subfolder per producer. `branch/` for claude-review, `feedback/` for canon feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for canon design render.
+├── .tmp/              ← ephemeral scratch space, gitignored
+└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
+```
+
+## Upgrading from a single-file board
+
+A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.claude/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
+
+Convert by hand, once per project:
+
+1. Split each `###` block into `.claude/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `canon standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
+2. Run `canon indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
+3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
+
+## Upgrading a hand-appended memory index
+
+A project installed before the memory folder gained a generated index still holds `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
+
+Convert by hand, once per project:
+
+1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
+2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
+3. Run `canon indexes regen --no-stage --root . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
+
+## Upgrading from a single-file diagram set
+
+A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
+
+## Gitignore
+
+- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
+
+Each entry is a top-level record folder, and an archive sits inside the folder it archives, so one line covers a record and everything it retires.
+
+## CLI
+
+| Command              | What it does                                                                                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                                                                                                 |
+| `canon claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status.                                                                            |
+| `canon claude setup` | Installs user-level config to `~/.claude/`: statusline, attribution, and the `permissions.allow` and `permissions.deny` lists. Run once per machine. |
+
+## CLAUDE.md
+
+- Ships as a seed with placeholder project name, description, and key paths. Fill these in after init.
+- Section layout: `Context`, `Indexes`, `Markdown`, `Key paths`, `Spelling`, `Snippets`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
+- The memory rules favor signal over volume. Saving only after a second occurrence or an explicit user correction keeps entries focused on patterns worth preventing, not first-occurrence slips. The 3-line cap stops the built-in auto-memory from drifting into narrative writeups that bury the rule underneath the recovery story.
+- The `Context` section points at `.claude/` state docs one line. `claude-feature` does the parallel read when invoked. The seed intentionally does not re-list every file.
+
+## Seed docs
+
+- Seed docs ship with a guidelines preamble above the first H2. These are instructions Claude internalizes before filling in the sections below. They are not sections to populate.
+
+## settings.json
+
+- Project seed at `tooling/claude/seeds/.claude/settings.json` ships two PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh` and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
+- User-level template at `tooling/claude/user/settings.template.json` carries `attribution.commit` and `attribution.pr` (empty strings to suppress co-author tags), `permissions.allow` with `Bash(bun run *)`, and `permissions.deny` with `Read(**/.env)` and `Read(**/.env.*)` to block accidental secret exposure across any project. Installed once per machine via `canon claude setup`.
+- The deprecated `includeCoAuthoredBy` key is not used.

package/tooling/claude/seeds/.claude/ARCHITECTURE.md

@@ -0,0 +1,13 @@
+# Architecture
+
+Authoring guidance: the architecture standard.
+
+## Overview
+
+## Key technical decisions
+
+### Decision name
+
+Reasoning and tradeoffs.
+
+## Risks / open questions

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

@@ -0,0 +1,62 @@
+# Design
+
+Authoring guidance: the design standard.
+
+## Personality
+
+One paragraph. Voice, tone, and the feeling a user should have. The same content a design intake form asks for.
+
+## Color
+
+One row per role. Intent is a short phrase a human can picture. Value is a hex or a named system token.
+
+| 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  |       |
+
+## Typography
+
+One row per role. Size and line height in pixels or rem. Family names use their product casing.
+
+| Role    | Family | Weight | Size | Line height |
+| ------- | ------ | ------ | ---- | ----------- |
+| display |        |        |      |             |
+| heading |        |        |      |             |
+| body    |        |        |      |             |
+| label   |        |        |      |             |
+| code    |        |        |      |             |
+
+## Spacing
+
+Base unit and scale. The renderer draws a swatch per step.
+
+| Step | Multiplier | Value |
+| ---- | ---------- | ----- |
+| xs   | 0.5        |       |
+| sm   | 1          |       |
+| md   | 2          |       |
+| lg   | 3          |       |
+| xl   | 5          |       |
+
+## Borders
+
+| Role    | Radius | Width | When used             |
+| ------- | ------ | ----- | --------------------- |
+| default |        |       | cards, inputs         |
+| pill    |        |       | tags, status chips    |
+| none    | 0      | 0     | edge-to-edge surfaces |
+
+## Motion
+
+One line. State whether motion is used at all, and if so, the default duration and easing.
+
+## Iconography
+
+One line. Style (outline, filled, duotone), source library, and whether custom icons are allowed.

package/tooling/claude/seeds/.claude/REQUIREMENTS.md

@@ -0,0 +1,18 @@
+# Requirements
+
+Authoring guidance: the requirements standard.
+
+## Problem
+
+## Goals
+
+## Non-goals
+
+## MVP features
+
+1. Feature: description
+2. Feature: description
+
+## Tech stack
+
+## Constraints

package/tooling/claude/seeds/.claude/diagrams/index.md

@@ -0,0 +1,8 @@
+---
+title: Diagrams
+subtitle: Per-kind Mermaid views loaded on demand. Start with system context.
+---
+
+# Diagrams
+
+Per-kind Mermaid views loaded on demand. Start with system context.

package/tooling/claude/seeds/.claude/hooks/index-reminder.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Grep | Glob) ;;
+*) exit 0 ;;
+esac
+
+path=$(printf '%s' "$input" | jq -r '.tool_input.path // empty')
+[ -n "$path" ] || exit 0
+
+if [ -f "$path" ]; then
+  dir=$(dirname "$path")
+else
+  dir="$path"
+fi
+
+index=""
+cur="$dir"
+while :; do
+  if [ -f "$cur/index.md" ]; then
+    index="$cur/index.md"
+    break
+  fi
+  parent=$(dirname "$cur")
+  [ "$parent" = "$cur" ] && break
+  cur="$parent"
+done
+
+[ -n "$index" ] || exit 0
+
+session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
+key=$(printf '%s__%s' "$session" "$index" | tr -c 'A-Za-z0-9' '_')
+marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/index-reminder"
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search.' "$index")
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/hooks/memory-index.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+# Regenerates .claude/memory/index.md after a memory file changes.
+#
+# The memory folder is gitignored, so the whole-repo walk in `bun run check`
+# drops it and never regenerates this index. Naming the file as a positional
+# argument to `canon indexes regen` below bypasses that filter, which makes this
+# hook the only trigger that reaches the folder.
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit | MultiEdit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/memory/*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file_path" in
+*/.claude/memory/index.md) exit 0 ;;
+esac
+
+# Report a missing CLI rather than exiting quietly. The path guard above already
+# scopes this to a memory-file edit, so the message only fires where the stale
+# index it warns about is the actual outcome.
+if ! command -v canon >/dev/null 2>&1; then
+  jq -nc --arg msg 'canon is not on PATH, so .claude/memory/index.md was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand.' \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+  exit 0
+fi
+
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+root="${file_path%/.claude/memory/*}"
+[ -n "$root" ] || exit 0
+
+# `--no-stage` because a hook has no business touching the index. On a project
+# whose memory folder is not gitignored, the default auto-stage would silently
+# add memory files to whatever commit is being assembled.
+output=$(canon indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
+
+# Regen failed, which on this folder means a memory file is missing `title` or
+# `description`. Report it. Nothing else can: the folder is gitignored, so the
+# whole-repo walk never reaches it and no gate stage will ever fail on a stale
+# index. Staying quiet here is what makes the drift permanent.
+errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
+[ -n "$errors" ] || errors="$output"
+
+msg="Memory index regen failed, so .claude/memory/index.md is now stale. Fix the frontmatter and save again. $errors"
+jq -nc --arg msg "$msg" \
+  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+exit 0

package/tooling/claude/seeds/.claude/hooks/path-form.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+# Hands back the absolute path form for a write made from a linked worktree.
+#
+# A relative path emitted from a linked worktree resolves against that
+# worktree rather than the editor root, so the terminal's path detection and
+# the desktop app's link both fail silently: nothing happens on the click
+# and no error appears. This computes the fact a session was asking itself
+# to infer on every response and hands the answer back instead.
+#
+# The entrypoint branch (bare vs. `file://` link) stays prose in
+# governance/rules/core/015-output.md. CLAUDE_CODE_ENTRYPOINT is not among
+# the environment variables Claude Code documents as passed to a hook
+# subprocess, unlike CLAUDE_PROJECT_DIR, so a hook cannot read it reliably.
+#
+# The worktree branch comes from the path rather than from `git rev-parse`,
+# the way `tasks-index.sh` and `memory-index.sh` already derive their main
+# root from a path suffix instead of the session. A git call would answer for
+# whatever directory the hook's own process happens to run in, which is not
+# necessarily the worktree the write came from.
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing
+# feeding it blocks forever and holds the session open, so the read is
+# bounded. `read` rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit | MultiEdit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+# A path with no worktree segment is either the main worktree, where a
+# relative path already resolves against the editor root, or a path this
+# hook cannot place. Either way there is nothing to hand back.
+case "$file_path" in
+*/.claude/worktrees/*) ;;
+*) exit 0 ;;
+esac
+
+abs_path=$(realpath -- "$file_path" 2>/dev/null)
+if [ -z "$abs_path" ]; then
+  jq -nc --arg msg "path-form.sh could not resolve an absolute form for $file_path from this linked worktree. Report the path per the worktree branch in the output rule instead of guessing." \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+  exit 0
+fi
+
+jq -nc --arg path "$abs_path" \
+  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:("This write is from a linked worktree. When reporting this path in your response, use its absolute form: " + $path)}}'
+exit 0

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/.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 trips the guard on every
+# source file it holds. Anchor on the project root before the pattern match.
+#
+# This gives up one case on purpose: a write to <project>/tmp/ is a genuine
+# scratch violation that no longer warns. The false positive fires on every
+# source write in an affected project, so the trade favors the anchor.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  case "$file_path" in
+  "$CLAUDE_PROJECT_DIR"/*) exit 0 ;;
+  esac
+fi
+
+case "$file_path" in
+*/tmp/* | *\\tmp\\* | */Temp/* | *\\Temp\\* | */var/folders/*) ;;
+*) exit 0 ;;
+esac
+
+session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
+key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
+marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/scratch-guard"
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg='Temporary file write outside .claude/.tmp/. Write temp files to .claude/.tmp/<slug>/ in the project root, not system temp. See the Scratch rule in CLAUDE.md.'
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+
+file="${file//\\//}"
+
+case "$file" in
+*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file" in
+*.claude/.tmp/* | *.claude/memory/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
+esac
+
+[ -f "$file" ] || exit 0
+
+# The audit verb owns the ban sets, so this hook carries no copy of them. The
+# awk this replaces parsed the word bans out of the project's own standards,
+# hardcoded the em-dash and semicolon, and reached none of the spellings, so a
+# British spelling passed at edit time and a corpus check caught it later with
+# nothing in between explaining the difference. A ban class added to the verb
+# now reaches this hook without an edit here.
+#
+# The verb resolves its own paths under the cwd, so the project root is named
+# rather than inherited. The payload carries an absolute file path, which is
+# what lets the runner move without taking the argument out of reach.
+root="${CLAUDE_PROJECT_DIR:-.}"
+
+# A machine without the binary reports that nothing ran rather than exiting
+# clean. An edit nobody checked and an edit carrying no violation are the same
+# silence to a reader, so the enforcement a machine lacks is reported.
+#
+# A completed run always writes the record, and a refusal writes nothing, so an
+# empty one means the verb declined to measure rather than measured and found
+# nothing. It refuses outside a git repository, which is a project this hook can
+# be installed into, and reading the findings alone reports that as a clean file.
+unread=""
+record=""
+if command -v canon >/dev/null 2>&1; then
+  record=$(cd "$root" 2>/dev/null && canon markdown audit "$file" --json 2>/dev/null) || true
+  [ -n "$record" ] || unread="record"
+else
+  unread="runner"
+fi
+
+# The record decides rather than the exit code, so a binary predating a ban
+# class still reports what it does measure. A refusal and an unparseable payload
+# both yield nothing, which is the same silence a clean file produces.
+hits=$(printf '%s' "$record" |
+  jq -r '.entries[]?.bans[]? | ":\(.line):\(.column + 1)  \(.kind)  \(.term)"' 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
+
+nl=$'\n'
+msg=""
+
+if [ "$unread" = "runner" ]; then
+  msg=$(printf 'Standards-audit: nothing checked in %s. Found no `canon` binary on PATH. Install one with `bun add -g @erclx/canon`.' "$file")
+elif [ "$unread" = "record" ]; then
+  msg=$(printf 'Standards-audit: nothing checked in %s. `canon markdown audit` returned no record, which it does when it declines to measure. It needs a git repository to build its corpus.' "$file")
+elif [ -n "$empty" ]; then
+  msg=$(printf 'Standards-audit: the shipped ban set is empty for %s, so %s was checked against a narrowed set. Reinstall the toolkit with `bun add -g @erclx/canon`.' "$empty" "$file")
+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")
+  msg="${msg:+$msg$nl}$found"
+fi
+
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'