@erclx/canon 5.3.0 → 5.4.0

package/README.md

@@ -94,6 +94,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
+- [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
 - [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes

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

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

package/claude/skills/plan-groundwork/SKILL.md

@@ -91,7 +91,7 @@ The standard sets the open question format and requires it inside a topic file a
 
 ## Close mode
 
-1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped.
+1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped. Carry the "Overturned by" line of each lean that became the decision into a `## Revisit when` section, and carry none from a lean the decision did not take.
 2. Write `07-next-session.md` self-contained, so it survives a compaction that loses the conversation.
 3. Update the file map in `README.md`.
 4. Write one task file in `.canon/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter. Place the row through `task-board` Step 4, which checks the roster for a live orchestrator before writing `priority.md` or `backlog.md` directly. Aside from an experiment fixture, this and the routing in Step 5 are the only ways close mode reaches outside the folder.

package/docs/agents/markdown-audit.md

@@ -87,7 +87,7 @@ A hit the closed set could not separate from correct prose was the case with no
 
 ### Where the rules are enforced
 
-Five surfaces apply the ban set 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.
+Five surfaces apply the ban set 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 every stack's `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.
 

package/docs/agents/pr-evidence.md

@@ -64,6 +64,23 @@ carries no evidence path, such as `base` or `python`, hits this reason on
 every pull request and posts nothing, which is the correct behavior rather
 than a gap.
 
+Both `ok` and `no-evidence` also report what the marked comment already
+shows a reviewer, each field present only when that comment holds it:
+
+| Field       | What it carries                                                   |
+| ----------- | ----------------------------------------------------------------- |
+| `preview`   | The hosted `**Preview:**` address the comment opens with.         |
+| `local`     | The `**Local preview:**` address under it.                        |
+| `checklist` | The checklist between its delimiters, with any ticked boxes kept. |
+
+These come from the comment already posted, never from the flags the call
+passed, so a skill driving a review reads which address and which checklist a
+reviewer has without parsing the comment itself. A checklist posted on its own
+carries no marker, so the record reports none of the three for it. Reading
+them means the thread is read before the `no-evidence` answer too, so an
+unreadable thread refuses as `gh-failed` on both reasons rather than
+reporting the fields absent.
+
 ## What `[number]` selects, and what it does not
 
 Naming a number picks which pull request the rendered body claims to

package/docs/workflow/skill-map.md

@@ -12,14 +12,15 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Set up a project
 
-| Skill                  | When to use                                                                                            |
-| ---------------------- | ------------------------------------------------------------------------------------------------------ |
-| `canon:target-setup`   | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone  |
-| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                  |
-| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs   |
-| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                |
-| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                   |
-| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README |
+| Skill                     | When to use                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:target-setup`      | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone       |
+| `canon:canon-operator`    | On a project that already exists, to read what it carries before an install is picked                       |
+| `canon:sketch-design`     | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs        |
+| `canon:design-extract`    | Before the first UI feature, to draft `canon/DESIGN.md`                                                     |
+| `canon:draft-diagram`     | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                        |
+| `canon:deploy-cloudflare` | Once a project is ready to publish, to set up its Cloudflare Pages deploy and stop for the token and domain |
+| `canon:repo-metadata`     | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README      |
 
 ## Decide what to build
 
@@ -46,6 +47,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
 | `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
 | `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
 | `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
 
 ## Check the work before it leaves the branch

package/package.json

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

package/src/commands/pr.ts

@@ -462,6 +462,16 @@ export function register(program: Command): void {
         'comment. Together with --checklist it does, so the checklist and the',
         'link land in one comment.',
         '',
+        'Both reasons carry what the marked comment already posted, each field',
+        'present only when that comment holds it:',
+        '  preview    the hosted **Preview:** address the comment opens with',
+        '  local      the **Local preview:** address under it',
+        '  checklist  the checklist between its delimiters, ticks included',
+        'These come from the comment already posted, never from the flags this',
+        'call passed. A checklist posted on its own carries no marker, so the',
+        'record reports none of the three for it. An unread thread refuses as',
+        'gh-failed on both reasons rather than reporting the fields absent.',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body or reported no-evidence',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -1424,47 +1434,6 @@ async function runEvidence(
     baseTree.has(path),
   )
 
-  // A local address rides on a checklist or a hosted preview and never opens
-  // a comment alone, so a docs-only branch with a server up posts nothing.
-  const hasChecklistAndLocal =
-    suppliedChecklist !== undefined && opts.local !== undefined
-  if (
-    grouped.kind === 'refused' &&
-    opts.preview === undefined &&
-    !hasChecklistAndLocal
-  ) {
-    logStep('Skipped')
-    logInfo(
-      'No changed path carries an evidence/ segment, so there is nothing to post.',
-    )
-    outro()
-    if (emitJson) {
-      process.stdout.write(
-        `${JSON.stringify({
-          root,
-          ...(identity.number !== undefined && { number: identity.number }),
-          reason: 'no-evidence',
-        })}\n`,
-      )
-    }
-    return 0
-  }
-
-  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
-  const repo =
-    repoRow === null
-      ? undefined
-      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
-
-  if (repo === undefined) {
-    return refuseWith(
-      'gh-failed',
-      EVIDENCE_REFUSALS['gh-failed'],
-      emitJson,
-      root,
-    )
-  }
-
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
@@ -1480,6 +1449,8 @@ async function runEvidence(
     // An unread thread refuses rather than rendering, since a body built
     // without it knows neither the comment to edit nor the preview address
     // to carry, and posting it would duplicate the comment and drop the link.
+    // It refuses ahead of no-evidence too, so that record never reports an
+    // absent field it did not read.
     let comments: readonly { url?: string; body: string }[] | undefined
     if (commentsRow !== null) {
       try {
@@ -1506,6 +1477,56 @@ async function runEvidence(
     carriedLocal = findEvidenceLocal(comments)
   }
 
+  // What the marked comment already shows a reviewer, kept apart from the
+  // flags this call passed so a reader learns what is posted.
+  const carried = {
+    ...(carriedPreview !== undefined && { preview: carriedPreview }),
+    ...(carriedLocal !== undefined && { local: carriedLocal }),
+    ...(carriedChecklist !== undefined && { checklist: carriedChecklist }),
+  }
+
+  // A local address rides on a checklist or a hosted preview and never opens
+  // a comment alone, so a docs-only branch with a server up posts nothing.
+  const hasChecklistAndLocal =
+    suppliedChecklist !== undefined && opts.local !== undefined
+  if (
+    grouped.kind === 'refused' &&
+    opts.preview === undefined &&
+    !hasChecklistAndLocal
+  ) {
+    logStep('Skipped')
+    logInfo(
+      'No changed path carries an evidence/ segment, so there is nothing to post.',
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          ...(identity.number !== undefined && { number: identity.number }),
+          reason: 'no-evidence',
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  const repo =
+    repoRow === null
+      ? undefined
+      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
+
+  if (repo === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
   const preview = opts.preview ?? carriedPreview
   const local = opts.local ?? carriedLocal
   const checklist = suppliedChecklist ?? carriedChecklist
@@ -1548,6 +1569,7 @@ async function runEvidence(
         head: identity.head,
         body,
         ...(commentId !== undefined && { commentId }),
+        ...carried,
       })}\n`,
     )
   }

package/standards/context.md

@@ -56,7 +56,7 @@ Both fields feed `canon/context/index.md` when regenerated.
 
 Include whenever the domain has content for them. Never pad an entry with an empty heading.
 
-- `## Decisions`: non-obvious choices and the reasoning behind them. The highest-value section in the folder and the one most often missing.
+- `## Decisions`: non-obvious choices and the reasoning behind them. The highest-value section in the folder and the one most often missing. A decision resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence naming the harm the decision prevents, and a decision resting on the project's own code takes none.
 - `## Gotchas`: workarounds, things tried and rejected, scar tissue worth preserving.
 
 ## Optional sections

package/standards/decisions.md

@@ -45,11 +45,12 @@ A record failing these is non-conforming even when it satisfies every shape rule
 
 ## Sections
 
-Use `## Context`, `## Decision`, `## Alternatives`, and `## Measurements`.
+Use `## Context`, `## Decision`, `## Alternatives`, `## Revisit when`, and `## Measurements`.
 
 - `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
 - `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
 - `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
+- `## Revisit when`: one bullet per finding that would reopen the decision. Required when the record came from a groundwork track whose deciding leans carried "Overturned by" lines, which carry over as written. It is optional otherwise, for a decision resting on how an outside tool, an installer, or the model behaves. Skip it for a decision resting on the project's own code.
 - `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
 
 ## Verification anchors
@@ -94,6 +95,10 @@ description: <one line naming what was decided>
 - **<Alternative>.** <Why it lost.>
 - **<Alternative>.** <Why it lost.>
 
+## Revisit when
+
+- <The finding that would reopen the decision.>
+
 ## Measurements
 
 <The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.

package/standards/groundwork.md

@@ -102,6 +102,7 @@ Closes the folder. Everything above it is input.
 - The goal
 - The items to do
 - What was considered and dropped
+- `## Revisit when`: the "Overturned by" line of each lean that became the decision, carried over as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
 
 The dropped list is what stops a future session re-proposing something already rejected.
 

package/standards/requirements.md

@@ -21,7 +21,7 @@ Does not govern:
 
 - The problem being solved and for whom
 - User-facing goals stated as outcomes, not implementation
-- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded.
+- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded. A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence, and a non-goal resting on scope alone takes none.
 - MVP features as a numbered list: feature name and one-line description
 - Tech stack as a plain list of tools
 - Hard constraints that shape every decision

package/standards/rule.md

@@ -79,6 +79,7 @@ paths:
 - Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
 - State one rule per bullet as a single directive line
 - State what to do and what not to do. Do not explain the reasoning behind a rule.
+- End the directive line of a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, which states a condition rather than the reasoning. A style, safety, or consistency ban takes none.
 - Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
 - Keep the file to one topic. A second topic is a second rule file.

package/standards/skill.md

@@ -105,7 +105,7 @@ allowed-tools: <tools required>
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
-- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences.
+- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences. Revisit when removing a line of general knowledge from a skill is shown to change what the agent does.
 
 ### Progressive disclosure
 

package/standards/standard.md

@@ -79,6 +79,7 @@ A standard failing these questions is non-conforming even when it satisfies ever
 - State the forbidden shape rather than enumerating allowed options, so a rule survives new categories
 - Cut any rule that resists a crisp one-line phrasing
 - Do not pad with filler prose. Every line earns its place as a usable reference entry.
+- Close a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, since that claim can stop holding while the ban reads the same. A style, safety, or consistency ban takes none, and filling one with a condition is padding.
 
 ## Success criterion
 

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

@@ -52,6 +52,50 @@ run_base_phase() {
   log_info "$pass_msg"
 }
 
+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"
+    ;;
+  1)
+    log_info "Skipped: canon markdown audit refused and measured nothing."
+    ;;
+  2)
+    echo "$output" | pipe_output
+    log_error "Markdown prose carries a banned character, 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
@@ -86,6 +130,9 @@ main() {
   run_check "bun run test:run" "Unit tests failed"
   log_info "Unit tests 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/go/reference.md

@@ -28,7 +28,7 @@ The go stack also ships `smoke_test.go` at the module root as a copy-once seed.
 
 ## verify.sh
 
-- Run Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`), plus the four base phases wherever the folder declares their scripts.
+- Run Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`), plus the four base phases wherever the folder declares their scripts, then the markdown bans stage base ships.
 - Keep `build` out of `verify.sh`. `go build ./...` exits 1 with `no packages to build` on a module holding only a test file, and a seeded `main.go` would assume every module is a binary rather than a library.
 - Keep `-race` out of `test:run`. The race detector needs cgo and a C toolchain, so it belongs in CI rather than in a local `bun run check`.
 

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

@@ -56,6 +56,50 @@ run_base_phase() {
   log_info "$pass_msg"
 }
 
+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"
+    ;;
+  1)
+    log_info "Skipped: canon markdown audit refused and measured nothing."
+    ;;
+  2)
+    echo "$output" | pipe_output
+    log_error "Markdown prose carries a banned character, 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
@@ -91,6 +135,9 @@ main() {
   run_check "bun run test:run" "Unit tests failed"
   log_info "Unit tests 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/php/reference.md

@@ -42,7 +42,7 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 ## verify.sh
 
 - Stop and name `composer install` when `vendor/bin/phpunit` is missing.
-- Run Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`), plus the four base phases wherever the folder declares their scripts.
+- Run Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`), plus the four base phases wherever the folder declares their scripts, then the markdown bans stage base ships.
 
 ## Gitignore
 

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

@@ -51,6 +51,50 @@ run_base_phase() {
   log_info "$pass_msg"
 }
 
+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"
+    ;;
+  1)
+    log_info "Skipped: canon markdown audit refused and measured nothing."
+    ;;
+  2)
+    echo "$output" | pipe_output
+    log_error "Markdown prose carries a banned character, 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
@@ -85,6 +129,9 @@ main() {
   run_check "bun run test:run" "Unit tests failed"
   log_info "Unit tests 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/python/reference.md

@@ -27,7 +27,7 @@ The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest`
 - `pytest.ini`: tests live under `tests/`, source under `src/`.
 - `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
 - `.python-version`: pinned to `3.14` to match `uv init` defaults.
-- `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases.
+- `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases, then the same markdown bans phase base ships.
 
 ## Hybrid project shape
 

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

@@ -50,6 +50,50 @@ run_base_phase() {
   log_info "$pass_msg"
 }
 
+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"
+    ;;
+  1)
+    log_info "Skipped: canon markdown audit refused and measured nothing."
+    ;;
+  2)
+    echo "$output" | pipe_output
+    log_error "Markdown prose carries a banned character, 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
@@ -88,6 +132,9 @@ main() {
   run_check "bun run build" "Build failed"
   log_info "Build passed"
 
+  log_step "Markdown bans"
+  check_markdown_bans
+
   # Runs whenever the stack shipped a card exclusion check, which keeps the
   # stage stack-agnostic here and the check itself in the stack that owns the
   # card route's shape. It reads the build above, so it sits after it.

package/tooling/web/reference.md

@@ -128,6 +128,6 @@ The sweep under `screenshots/` is ignored again, and only a flagged case's `evid
 
 ## Verify script
 
-The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build, then the card exclusion check where one is installed. Stack adapters may override if their typecheck or build differs.
+The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build, markdown bans, then the card exclusion check where one is installed. Stack adapters may override if their typecheck or build differs.
 
 The card stage is conditional on `scripts/check-card-exclusion.sh` existing rather than on the stack, so a project with no card route runs one less stage and needs no override to skip it. A stack that ships a card route ships that script, and the check reads the build the stage before it produced.