@erclx/canon 5.2.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.2.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/claude/skills/teach-workspace/REQUIREMENT.md

@@ -7,7 +7,9 @@ description: Scope boundary for learning a subject across sessions, and the spli
 
 ## Gap
 
-Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
+Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. When it does read, it takes whatever a search returned first, so a course rests on a few thin sources, and it cites the learner's own projects or an employer's material as proof of a general concept.
+
+It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
 
 It also produces one output where two are needed. A page written to be worked through once and a page written to be looked up later have different lifetimes and different readers, and merging them yields material that is disposable and gets kept, or durable and carries a quiz nobody can promote. Writing the durable half in a format the authoring gates do not read costs a conversion at the moment it matters most, which is the moment someone tries to promote it.
 
@@ -25,7 +27,7 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - Name the write route for a main-root path from a linked worktree, since a body naming only the destination reports a success that did not happen
 - Route every edit inside a workspace file that already exists through a verb resolving the root in-process, since a heredoc reaches a whole-file create alone and the stream editors that would reach the rest are banned
 - Settle the learner's starting point by asking, so difficulty sits above a measured floor
-- Research the subject from sources before teaching it, and record what was read and what was found and not opened
+- Research the subject from sources before teaching it, choosing them by the teach standard's ladder, and record what was read and what was found and not opened
 - Place each lesson from the learning records rather than from the subject's order, and open with retrieval on the last wrong answer
 - Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
 - Record the wrong answer itself rather than the count, since that is what the next session places the learner from

package/claude/skills/teach-workspace/SKILL.md

@@ -61,7 +61,7 @@ Repeat `--success` and `--out-of-scope` per line. The verb refuses a topic anoth
 
 ## Step 2: research before teaching
 
-Read the subject from sources rather than from recall. Record what was read and what was only found through the verb that owns the file:
+Read the subject from sources rather than from recall, chosen by the standard's `### Choosing sources` ladder, with a third-rung source's reason in its title. Record what was read and what was only found through the verb that owns the file:
 
 ```bash
 canon teach resource <topic> --json \
@@ -83,7 +83,7 @@ Open on what `due` reports as overdue, oldest date first, before anything new. W
 
 Two outputs with two lifetimes, and the split decides the format.
 
-- A lesson is a self-contained page carrying its own quiz, a teach-back block, and the feedback for each question. It embeds one shared stylesheet rather than restating styles, and it is disposable and never promoted.
+- A lesson is a self-contained page carrying its own quiz, a teach-back block, and the feedback for each question. It embeds one shared stylesheet rather than restating styles, and it is disposable and never promoted. Its `refs` pass the source ladder, and a learner's or organization's file goes in the body, labeled.
 - A reference page goes to `reference/<slug>.md`, written for a reader with no learner in it. This is the half that survives the workspace, so it is written in markdown to pass the authoring gates a promotion would put it through. `canon teach nav` renders it to a `reference/<slug>.html` sibling, and a lesson links that sibling, since a served `.md` opens as plain text.
 
 Resolve the lesson before writing it, rather than composing its name or its quiz order by hand:

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -74,14 +74,17 @@ The stepper hides and shows and sets nothing else, so how a selected option look
 
 ## The block list
 
-`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Five types, and every structural body composes from them:
+`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Six types, and every structural body composes from them:
 
 - `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
 - `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the dek that opens the lesson. `cites` adds a footnote marker per reference number after the text, and a lede takes none.
 - `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
 - `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the lesson's one reference list, numbered from 1 in item order. `url` and `note` are optional, and a `url` must be http or https.
+- `{"type":"code","lang":"ts","text":"<source>"}`: a code sample, highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias. One the renderer does not register renders as plain escaped code.
 - `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
 
+Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a lesson body, so a sample written that way stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
+
 The quiz and the teach-back block above are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, rather than reaching for `raw` anywhere the other types could carry the content instead.
 
 A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than into the sentence. Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened. Render refuses a cite no reference resolves, so number the list before citing into it.

package/claude/skills/teach-workspace/references/pedagogy.md

@@ -75,3 +75,4 @@ Parametric recall is confident where it is wrong, and a learner cannot audit it.
 - Read the subject from sources before teaching, and record each one with its link
 - Mark any claim resting on recall as resting on recall, in the lesson itself
 - List a source found and not opened as a lead, and never cite it
+- Choose which sources to read by the ladder under `### Choosing sources` in the teach standard, which also rules out the learner's own work as proof of a general claim

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/agents/teach-authoring.md

@@ -38,7 +38,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the four lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the five lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
 
 ```bash
 echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json
@@ -48,7 +48,13 @@ echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach re
 | -------- | ---------------------------------------- |
 | `--json` | Emit a machine-readable record on stdout |
 
-It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, `code`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+
+A `code` block carries `text` and an optional `lang`, a highlight.js name or alias. The source is highlighted at render time into `hljs-*` class spans the workspace stylesheet colors in both themes, so the page carries no script. A `lang` the renderer does not register renders as plain escaped code, and one that does not match `^[a-z0-9+#-]+$` is refused. A workspace seeded before the syntax colors existed shows the spans uncolored until `canon teach stylesheet <topic>` rewrites its base stylesheet.
+
+```json
+[{ "type": "code", "lang": "ts", "text": "const a: number = 1" }]
+```
 
 A citation takes two shapes. A `paragraph` carries an optional `cites` array of reference numbers, rendered as `sup.cite` markers after its text. The one `refs` block carries `items` of `{ title, url?, note? }`, rendered as `ol.refs` and numbered from 1, so cite `1` links to the first item.
 
@@ -107,6 +113,6 @@ Splicing the stepper into a lesson of either shape was measured against a browse
 
 ### Reference pages
 
-Each reference page is rendered to a `reference/<slug>.html` sibling carrying the same chrome, and the contents page links that sibling rather than the markdown, which `canon serve` hands over as plain text. The render drops the frontmatter, turns tables into `<table>` markup, and escapes raw HTML written in the markdown rather than passing it through. A body with no H1 gets one from the frontmatter `title`. A relative link to another reference page's markdown points at that page's `.html` sibling, and one to the workspace `GLOSSARY.md` points at the glossary on the contents page, `../index.html#gloss`. Every other link, such as `../RESOURCES.md`, stays as written. The markdown file is never touched.
+Each reference page is rendered to a `reference/<slug>.html` sibling carrying the same chrome, and the contents page links that sibling rather than the markdown, which `canon serve` hands over as plain text. The render drops the frontmatter, turns tables into `<table>` markup, and escapes raw HTML written in the markdown rather than passing it through. A fenced code block in a language the highlighter registers is highlighted the same way a `code` block is, and one in any other language stays plain. A hand-written code block in a lesson body is never highlighted. A body with no H1 gets one from the frontmatter `title`. A relative link to another reference page's markdown points at that page's `.html` sibling, and one to the workspace `GLOSSARY.md` points at the glossary on the contents page, `../index.html#gloss`. Every other link, such as `../RESOURCES.md`, stays as written. The markdown file is never touched.
 
 Every rendered page carries a `<meta name="generator" content="canon teach nav">` tag. A `.html` file under `reference/` whose markdown is gone is deleted when it carries that tag, and a hand-written HTML file there, carrying none, is left alone. The record's `reference` field counts the pages rendered. On a Bun with no `Bun.markdown`, each reference page lands in `skipped` with `Bun.markdown` as what is missing, and the rest of the run goes on.

package/docs/agents/teach.md

@@ -81,7 +81,7 @@ canon teach resource regular-expressions \
 | `--json`             | Emit a machine-readable record on stdout           |
 | `--root <path>`      | Teach root, defaulting to the main worktree        |
 
-The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from.
+The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from. Which sources qualify is the source ladder in `canon standards teach`, and a source below its first two rungs also names why no higher one covers the claim.
 
 A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer.
 

package/docs/workflow/operating-model.md

@@ -232,5 +232,5 @@ port-collision detail.
 ## Related
 
 - [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the isolation and fan-out mechanics
-- [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees
+- [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees, and [blocking subagents](../../wiki/claude/permissions.md#blocking-subagents) for the `permissions.deny` rule that stops every spawn
 - `canon/context/claude-plugin/skill-strategy/overview.md` for how the skills in the loop are categorized

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.2.0",
+  "version": "5.4.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -56,6 +56,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "execa": "^9.5.2",
+    "highlight.js": "^11.12.0",
     "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1"
   },

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/src/commands/teach.ts

@@ -2,7 +2,7 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavOutcome, generateNav } from '@/teach/nav'
-import { type RenderOutcome, renderLessonBody } from '@/teach/render'
+import type { RenderOutcome } from '@/teach/render'
 import {
   defineTerms,
   type ListOutcome,
@@ -393,10 +393,14 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Reads a JSON array of blocks from stdin, each a heading, paragraph,',
-        'list, refs, or raw block, and renders it through the same components',
-        'the fixture lesson is generated from. Content the structured blocks',
-        'cannot express takes type raw, carrying its own html verbatim,',
-        'unescaped.',
+        'list, refs, code, or raw block, and renders it through the same',
+        'components the fixture lesson is generated from. Content the',
+        'structured blocks cannot express takes type raw, carrying its own',
+        'html verbatim, unescaped.',
+        '',
+        'A code block takes text and an optional lang, a highlight.js name or',
+        'alias matching ^[a-z0-9+#-]+$, and renders highlighted at build time',
+        'with no script. An unregistered lang renders as plain escaped code.',
         '',
         'A paragraph takes an optional cites array of reference numbers,',
         'rendered as footnote markers after its text. The one refs block',
@@ -752,6 +756,9 @@ async function runRender(opts: RenderCommandOptions): Promise<number> {
     )
   }
 
+  // Loaded here rather than at the top, since the renderer pulls in the
+  // highlighter and every other verb would pay for its grammars at startup.
+  const { renderLessonBody } = await import('@/teach/render')
   return reportRender(renderLessonBody(parsed), emitJson)
 }
 

package/src/design/components.ts

@@ -210,6 +210,39 @@ export const COMPONENTS: readonly Component[] = [
  */
 export const TEACH_SIDEBAR_BREAKPOINT = 1100
 
+/**
+ * The colors highlighted code renders in, one per token class the teach
+ * article maps highlight.js spans onto. Hex rather than `color-mix` so the
+ * contrast test can measure each against the code surface, and dark by default
+ * with a light override, following the same `data-theme` switch as the ground
+ * they sit on. Teach-local until a second surface renders highlighted code.
+ * `keyword`, `comment` and `meta` repeat the accent, muted and secondary
+ * values, so code reads in the page's own palette.
+ */
+export const TEACH_SYNTAX: readonly {
+  readonly name: string
+  readonly dark: string
+  readonly light: string
+}[] = [
+  { name: 'keyword', dark: '#c76b5f', light: '#ad4a4b' },
+  { name: 'string', dark: '#8dbb6c', light: '#2d6b22' },
+  { name: 'number', dark: '#d4a15a', light: '#8a5300' },
+  { name: 'title', dark: '#b99ad8', light: '#72489a' },
+  { name: 'attr', dark: '#6fb3c4', light: '#1e6478' },
+  { name: 'comment', dark: '#7f7f7c', light: '#6e6d6c' },
+  { name: 'meta', dark: '#8c8b86', light: '#666561' },
+]
+
+const syntaxProperty = (name: string): string => `--teach-syntax-${name}`
+
+const TEACH_SYNTAX_DARK = TEACH_SYNTAX.map(
+  ({ name, dark }) => `  ${syntaxProperty(name)}: ${dark};`,
+).join('\n')
+
+const TEACH_SYNTAX_LIGHT = TEACH_SYNTAX.map(
+  ({ name, light }) => `  ${syntaxProperty(name)}: ${light};`,
+).join('\n')
+
 const TEACH_CHROME: Component = {
   name: 'teach-chrome',
   note: [
@@ -263,6 +296,12 @@ const TEACH_CHROME: Component = {
   --ink-faint: var(--color-muted);
   --accent: var(--color-accent);
   --accent-bg: var(--color-teach-accent-bg);
+
+${TEACH_SYNTAX_DARK}
+}
+
+[data-theme='light'] {
+${TEACH_SYNTAX_LIGHT}
 }
 
 @media (prefers-color-scheme: dark) {
@@ -1007,6 +1046,7 @@ const TEACH_ARTICLE: Component = {
     '--color-accent',
     '--teach-hand',
     '--teach-mono',
+    ...TEACH_SYNTAX.map(({ name }) => syntaxProperty(name)),
     '--t1',
     '--t2',
     '--t3',
@@ -1092,6 +1132,18 @@ pre {
 
 pre code { background: none; padding: 0; font-size: 1em; }
 
+/* Build-time highlight.js spans. Every class reads a --teach-syntax-* token,
+   so the dark and light values switch with the ground rather than per rule. */
+.hljs-keyword, .hljs-selector-tag, .hljs-literal, .hljs-built_in, .hljs-doctag { color: var(--teach-syntax-keyword); }
+.hljs-string, .hljs-regexp, .hljs-addition, .hljs-template-tag, .hljs-symbol { color: var(--teach-syntax-string); }
+.hljs-number, .hljs-type, .hljs-selector-class, .hljs-selector-id { color: var(--teach-syntax-number); }
+.hljs-title, .hljs-section, .hljs-name, .hljs-bullet { color: var(--teach-syntax-title); }
+.hljs-attr, .hljs-attribute, .hljs-variable, .hljs-template-variable, .hljs-property { color: var(--teach-syntax-attr); }
+.hljs-comment, .hljs-quote { color: var(--teach-syntax-comment); font-style: italic; }
+.hljs-meta, .hljs-deletion, .hljs-subst { color: var(--teach-syntax-meta); }
+.hljs-emphasis { font-style: italic; }
+.hljs-strong { font-weight: 700; }
+
 /* ---- Callout ---- */
 
 .hard {

package/src/teach/components/code.tsx

@@ -0,0 +1,24 @@
+/** @jsxImportSource ../html */
+import { highlight } from '@/teach/highlight'
+import type { Element } from '@/teach/html/jsx-runtime'
+import { raw } from '@/teach/html/raw'
+
+export interface CodeProps {
+  /** A highlight.js language name or alias. Unregistered ones render plain. */
+  readonly lang?: string
+  readonly text: string
+}
+
+/**
+ * The one way code reaches a lesson body. The highlighter escapes every source
+ * character before wrapping tokens in spans, which is what makes passing its
+ * output through `raw` safe.
+ */
+export function Code({ lang, text }: CodeProps): Element {
+  const className = lang === undefined ? 'hljs' : `hljs language-${lang}`
+  return (
+    <pre>
+      <code class={className}>{raw(highlight(text, lang).html)}</code>
+    </pre>
+  )
+}

package/src/teach/highlight.ts

@@ -0,0 +1,71 @@
+import hljs from 'highlight.js/lib/core'
+import bash from 'highlight.js/lib/languages/bash'
+import css from 'highlight.js/lib/languages/css'
+import diff from 'highlight.js/lib/languages/diff'
+import dockerfile from 'highlight.js/lib/languages/dockerfile'
+import go from 'highlight.js/lib/languages/go'
+import javascript from 'highlight.js/lib/languages/javascript'
+import json from 'highlight.js/lib/languages/json'
+import markdown from 'highlight.js/lib/languages/markdown'
+import python from 'highlight.js/lib/languages/python'
+import shell from 'highlight.js/lib/languages/shell'
+import sql from 'highlight.js/lib/languages/sql'
+import typescript from 'highlight.js/lib/languages/typescript'
+import xml from 'highlight.js/lib/languages/xml'
+import yaml from 'highlight.js/lib/languages/yaml'
+
+/**
+ * A fixed set rather than all of highlight.js, since each grammar costs load
+ * time and a workspace rarely reaches past these. An unlisted language renders
+ * plain rather than refusing, so adding one here is the whole change.
+ */
+const LANGUAGES = {
+  bash,
+  css,
+  diff,
+  dockerfile,
+  go,
+  javascript,
+  json,
+  markdown,
+  python,
+  shell,
+  sql,
+  typescript,
+  xml,
+  yaml,
+}
+
+for (const [name, grammar] of Object.entries(LANGUAGES)) {
+  hljs.registerLanguage(name, grammar)
+}
+
+export interface Highlighted {
+  /** Markup safe to embed inside `<code>`: every source character escaped. */
+  readonly html: string
+  /** The language as asked for, or `undefined` when it rendered plain. */
+  readonly language: string | undefined
+}
+
+function escapeCode(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}
+
+/**
+ * Highlights code at build time into `hljs-*` class spans the teach
+ * stylesheet colors, so an emitted page needs no script. An absent or
+ * unregistered language falls back to escaped plain text rather than
+ * throwing or guessing.
+ */
+export function highlight(text: string, lang?: string): Highlighted {
+  if (lang === undefined || hljs.getLanguage(lang) === undefined) {
+    return { html: escapeCode(text), language: undefined }
+  }
+  return {
+    html: hljs.highlight(text, { language: lang, ignoreIllegals: true }).value,
+    language: lang,
+  }
+}

package/src/teach/nav.ts

@@ -1170,6 +1170,35 @@ function retargetReferenceLinks(
   )
 }
 
+const FENCED_CODE =
+  /<pre><code class="language-([^"]+)">([\s\S]*?)<\/code><\/pre>/g
+
+function decodeHtml(html: string): string {
+  return html
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&#39;', "'")
+    .replaceAll('&amp;', '&')
+}
+
+/**
+ * Highlights the fenced blocks `Bun.markdown` emitted, decoding each once
+ * since the renderer already escaped it. A fence in a language the highlighter
+ * does not register is left exactly as the markdown rendered it. The module is
+ * imported here rather than at the top so a verb that never reaches a
+ * reference page does not load its grammars.
+ */
+async function highlightFences(html: string): Promise<string> {
+  if (!html.includes('<pre><code class="language-')) return html
+  const { highlight } = await import('@/teach/highlight')
+  return html.replace(FENCED_CODE, (match, lang: string, escaped: string) => {
+    const result = highlight(decodeHtml(escaped), lang)
+    if (result.language === undefined) return match
+    return `<pre><code class="hljs language-${lang}">${result.html}</code></pre>`
+  })
+}
+
 /**
  * One reference page as a styled page carrying the workspace chrome. The
  * markdown beside it stays the durable, promotable half, and this file is
@@ -1191,10 +1220,12 @@ async function renderReferencePage(
     readField(parseFrontmatter(source), 'title') ?? referenceFallbackTitle(file)
 
   const rendered = retargetReferenceLinks(
-    Bun.markdown.html(stripFrontmatter(source), {
-      noHtmlBlocks: true,
-      noHtmlSpans: true,
-    }),
+    await highlightFences(
+      Bun.markdown.html(stripFrontmatter(source), {
+        noHtmlBlocks: true,
+        noHtmlSpans: true,
+      }),
+    ),
     new Set(detail.referenceFiles),
   )
   const body = /<h1[\s>]/.test(rendered)

package/src/teach/render.ts

@@ -1,3 +1,4 @@
+import { Code } from '@/teach/components/code'
 import { Heading } from '@/teach/components/heading'
 import { List } from '@/teach/components/list'
 import { Paragraph } from '@/teach/components/paragraph'
@@ -19,6 +20,7 @@ export type LessonBlock =
       readonly ordered?: boolean
     }
   | { readonly type: 'refs'; readonly items: readonly Reference[] }
+  | { readonly type: 'code'; readonly text: string; readonly lang?: string }
   | { readonly type: 'raw'; readonly html: string }
 
 export interface RenderRendered {
@@ -28,7 +30,17 @@ export interface RenderRendered {
 
 export type RenderOutcome = RenderRendered | TeachRefused
 
-const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'refs', 'raw'] as const
+const BLOCK_TYPES = [
+  'heading',
+  'paragraph',
+  'list',
+  'refs',
+  'code',
+  'raw',
+] as const
+
+/** Bounds a lang to what a class name can carry, so it never injects. */
+const CODE_LANG = /^[a-z0-9+#-]+$/
 
 const LINK_PROTOCOLS = new Set(['http:', 'https:'])
 
@@ -170,6 +182,20 @@ function renderBlock(
         referenceCount: items.length,
       }
     }
+    case 'code': {
+      if (!isString(fields.text)) {
+        return badBlock(index, 'code needs a string text')
+      }
+      if (
+        fields.lang !== undefined &&
+        !(isString(fields.lang) && CODE_LANG.test(fields.lang))
+      ) {
+        return badBlock(index, `code lang must match ${CODE_LANG.source}`)
+      }
+      return {
+        html: render(Code({ lang: fields.lang, text: fields.text })),
+      }
+    }
     case 'raw': {
       if (!isString(fields.html)) {
         return badBlock(index, 'raw needs a string html')

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/standards/teach.md

@@ -128,6 +128,20 @@ Splits what was read from what was found.
 
 A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
 
+### Choosing sources
+
+Rest each general claim on the highest rung that covers it:
+
+1. Documentation or a specification published by whoever owns the subject
+2. A canonical work on the subject, such as the standard text, a reference book, or a primary paper
+3. Other material, such as a tutorial, a course, or a post, and only for a claim the first two rungs do not cover
+
+A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second and is not missing anything. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.
+
+The learner's own projects and material specific to one employer or organization are never a source for a general claim. Either may appear in the workspace as a worked application labeled with whose it is, and neither stands in `RESOURCES.md` as proof of what the subject says.
+
+A source reachable only through a paywall or a summary stays a lead until it is opened. A review or summary of a book is a different source from the book, so list the summary as read on its own rung and the book as a lead.
+
 ## Conventions
 
 - Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
@@ -141,6 +155,7 @@ A source found and not read is listed as a lead because a link attached to a pag
 - **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
 - **The revisit note with no date.** A line naming what to come back to and not when is read by nothing and schedules nothing, so the next session picks from the last record alone, which is the state the section exists to end.
 - **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+- **The first search result as the source list.** A workspace resting on whatever a search returned first teaches the weakest account of the subject, and nothing in the folder says a stronger one was never looked for.
 - **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
 
 ## Template

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.