@erclx/canon 4.36.1 → 4.37.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.36.1",
+  "version": "4.37.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/markdown-audit.md

@@ -154,11 +154,15 @@ A hit the closed set cannot separate from correct prose is the case with no thir
 
 ### Where the rules are enforced
 
-Four surfaces apply the ban sets and three of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, and the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before a push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
+Five surfaces apply the ban sets and four of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in `tooling/base/configs/scripts/verify.sh` runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
 
 The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. `scripts/core/check-seed-independence.sh` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
 
-The fourth surface reads the standards directly and is not a consolidation left half done. `claude/skills/claude-standards-audit/SKILL.md` greps the banned tokens agent-side, which is a session reading prose rather than a process it can shell out to, and it ships to every target. It is the likeliest place for the next drift, since nothing compares it against the verb.
+The target push stage reads the same exit codes `canon gate run`'s own stage reads: 0 passes, 1 is a refusal logged as a skip, 2 is a finding, and 3 is a shipped-empty ban set. It skips and logs rather than failing when no `canon` binary is on the machine's PATH, since a scaffolded project is not guaranteed the toolkit is installed, and its skip line names the install command.
+
+The target push stage excludes `CHANGELOG.md`, unlike every other surface here. A changelog a generator builds from commit subjects carries prose nobody wrote against the ban set, where this repository's own passes only because `release-please` builds it from subjects sessions already wrote to the rule. The stage passes an explicit file list rather than the bare invocation the other surfaces use, so a corpus with no file left once the changelog is set aside reads as a pass rather than falling back to the whole tree.
+
+The fifth surface reads the standards directly and is not a consolidation left half done. `claude/skills/claude-standards-audit/SKILL.md` greps the banned tokens agent-side, which is a session reading prose rather than a process it can shell out to, and it ships to every target. It is the likeliest place for the next drift, since nothing compares it against the verb.
 
 The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.emptySets` out of the same record, so a set the verb shipped empty reaches the author as a check narrowed to what it could measure rather than as a clean pass.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.36.1",
+  "version": "4.37.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/migrate/plan.ts

@@ -43,6 +43,7 @@ export interface RenamePlan {
 const TOOLKIT_OWNED: readonly string[] = [
   '.claude/aitk/',
   '.claude/canon/',
+  '.claude/hooks/',
   '.claude/rules/',
   '.claude/tooling/',
 ]

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

@@ -23,6 +23,50 @@ check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
 
+check_markdown_bans() {
+  if ! command -v canon >/dev/null 2>&1; then
+    log_info "Skipped: no canon binary on PATH. Install with \`bun install --global @erclx/canon\`."
+    return 0
+  fi
+
+  local files=()
+  while IFS= read -r file; do
+    files+=("$file")
+  done < <(git ls-files --cached --others --exclude-standard -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)**/CHANGELOG.md')
+
+  if [ ${#files[@]} -eq 0 ]; then
+    log_info "No markdown file to check outside the exclusion set."
+    return 0
+  fi
+
+  local output code
+  if output=$(canon markdown audit "${files[@]}" 2>&1); then
+    code=0
+  else
+    code=$?
+  fi
+
+  case "$code" in
+  0)
+    log_info "No banned character, word, or spelling"
+    ;;
+  1)
+    log_info "Skipped: canon markdown audit refused and measured nothing."
+    ;;
+  2)
+    echo "$output" | pipe_output
+    log_error "Markdown prose carries a banned character, word, or spelling, or a relative link resolves to nothing on disk"
+    ;;
+  3)
+    echo "$output" | pipe_output
+    log_error "The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for"
+    ;;
+  *)
+    log_error "canon markdown audit exited $code, which is neither a pass nor a finding"
+    ;;
+  esac
+}
+
 run_check() {
   local cmd=$1
   local err_msg=$2
@@ -55,6 +99,9 @@ main() {
   run_check "bun run check:shell" "Shell check failed"
   log_info "Shell check passed"
 
+  log_step "Markdown bans"
+  check_markdown_bans
+
   if [ "$NESTED" = false ]; then
     echo -e "${GREY}└${NC}\n"
     echo -e "${GREEN}✓ Verification passed${NC}"

package/tooling/base/reference.md

@@ -96,3 +96,5 @@ Sticky negative knowledge. Do not relearn.
 | `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`, `check:spell`, and `check:shell` directly, and those three are the gate.
+
+`scripts/verify.sh`'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. `docs/target-projects.md` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.

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

@@ -34,4 +34,4 @@ All `.sh` files live under `scripts/`. Do not place shell scripts outside `scrip
 
 - `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.
+- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters, words, and spellings 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.