@erclx/canon 5.3.0 → 5.5.0

package/src/context/architecture.ts

@@ -63,6 +63,12 @@ export interface DecisionReport {
    * it. Never gates, per `standards/architecture.md`'s `## Length` section.
    */
   readonly words: number
+  /**
+   * Whether a sentence outside code opens with `Revisit when`. Read on every
+   * record and required only by one stating the clause, so a project that
+   * never adopted it sees the reading without failing on it.
+   */
+  readonly revisit: boolean
 }
 
 export interface ArchitectureReport {
@@ -86,6 +92,12 @@ export interface ArchitectureReport {
    * project that never adopted a cap is measured and never gated.
    */
   readonly entryCap?: number
+  /**
+   * Whether the record states that every decision closes with a revisit
+   * sentence. Declared by the record for the reason the cap is, so a record
+   * that never wrote the clause is reported and never gated.
+   */
+  readonly revisitRequired: boolean
   readonly decisions: readonly DecisionReport[]
 }
 
@@ -214,6 +226,8 @@ interface RawDecision {
   readonly heading: string
   readonly line: number
   readonly body: string
+  /** The body with its fenced lines dropped, which is where prose is read. */
+  readonly prose: string
 }
 
 /**
@@ -230,7 +244,19 @@ interface RawDecision {
 export function splitDecisions(source: string): RawDecision[] {
   const lines = bodyLines(source)
   const decisions: RawDecision[] = []
-  let open: { heading: string; line: number; body: string[] } | undefined
+  let open:
+    | { heading: string; line: number; body: string[]; prose: string[] }
+    | undefined
+
+  const close = (): void => {
+    if (!open) return
+    decisions.push({
+      heading: open.heading,
+      line: open.line,
+      body: open.body.join('\n'),
+      prose: open.prose.join('\n'),
+    })
+  }
 
   for (const line of lines) {
     if (line.fenced) {
@@ -240,23 +266,24 @@ export function splitDecisions(source: string): RawDecision[] {
 
     const heading = line.text.match(DECISION_HEADING)?.[1]
     if (heading !== undefined) {
-      if (open) decisions.push({ ...open, body: open.body.join('\n') })
-      open = { heading, line: line.number, body: [] }
+      close()
+      open = { heading, line: line.number, body: [], prose: [] }
       continue
     }
 
     // A decision runs to the next `###` or to the section that follows the
     // decision list, so the risks below never read as the last entry's body.
     if (SECTION_HEADING.test(line.text)) {
-      if (open) decisions.push({ ...open, body: open.body.join('\n') })
+      close()
       open = undefined
       continue
     }
 
     open?.body.push(line.text)
+    open?.prose.push(line.text)
   }
 
-  if (open) decisions.push({ ...open, body: open.body.join('\n') })
+  close()
   return decisions
 }
 
@@ -383,6 +410,41 @@ export function readEntryCap(source: string): number | undefined {
   return readCardinal(source.match(ENTRY_CAP_CLAUSE)?.[1])
 }
 
+const REVISIT_CLAUSE =
+  /\bevery\s+decision\s+closes\s+with\s+a\s+revisit\s+sentence\b/i
+/**
+ * `Revisit when` opening a sentence: at the start of the text, after a line
+ * break, or after a sentence's closing stop. Mid-sentence it is not the
+ * sentence the standard asks for.
+ */
+const REVISIT_SENTENCE = /(?:^|\n|[.!?]\s+)\s*(?:[-*]\s+)?Revisit when\b/
+
+/**
+ * Whether the record states the revisit clause for itself, read off its prose
+ * alone so a template quoting the clause inside a fence does not adopt it.
+ *
+ * The clause is the record's own, like the cap, so wording that drifts past it
+ * falls back to reporting rather than to a requirement held here.
+ */
+export function readRevisitRule(source: string): boolean {
+  const prose = bodyLines(source)
+    .filter((line) => !line.fenced)
+    .map((line) => line.text)
+    .join('\n')
+    .replace(CODE_SPAN, ' ')
+  return REVISIT_CLAUSE.test(prose)
+}
+
+/**
+ * Whether a decision's prose carries a sentence opening `Revisit when`.
+ *
+ * Presence only, never content, so a vacuous sentence passes. A code span is
+ * dropped first, since a standard quoting the form is not stating one.
+ */
+export function hasRevisitSentence(prose: string): boolean {
+  return REVISIT_SENTENCE.test(prose.replace(CODE_SPAN, ' '))
+}
+
 /** Whether a read failed because nothing sits at the path. */
 function isMissing(error: unknown): boolean {
   const code = (error as { code?: unknown }).code
@@ -421,6 +483,7 @@ export async function measureArchitecture(
 
   const allowances = readAllowances(source)
   const entryCap = readEntryCap(source)
+  const revisitRequired = readRevisitRule(source)
   const raw = splitDecisions(source)
   const decisions = await Promise.all(
     raw.map(async (entry) => {
@@ -433,6 +496,7 @@ export async function measureArchitecture(
         ...(quantified !== undefined && { quantified }),
         checks: await namedChecks(root, entry.body),
         words: wordCount(entry.body),
+        revisit: hasRevisitSentence(entry.prose),
       }
     }),
   )
@@ -453,6 +517,7 @@ export async function measureArchitecture(
       ceiling: ceilingFor(allowances, raw.length),
     }),
     ...(entryCap !== undefined && { entryCap }),
+    revisitRequired,
     decisions,
   }
 }
@@ -470,6 +535,18 @@ export function isOverCount(report: ArchitectureReport): boolean {
   )
 }
 
+/**
+ * The headings of decisions lacking a revisit sentence the record requires.
+ *
+ * Empty for a record stating no clause, for the reason `isOverCount` gives.
+ */
+export function missingRevisit(report: ArchitectureReport): string[] {
+  if (!report.revisitRequired) return []
+  return report.decisions
+    .filter((entry) => !entry.revisit)
+    .map((entry) => entry.heading)
+}
+
 /**
  * Whether the record is longer than the ceiling it derives for itself.
  *

package/src/context/gate.ts

@@ -19,6 +19,12 @@ export interface GateInput {
    * gates under the same two modes and is false in the same two cases.
    */
   readonly recordOverCount: boolean
+  /**
+   * Whether a decision lacks the revisit sentence the record requires of
+   * every decision, which gates under the same two modes and is false in the
+   * same two cases, plus a record stating no such clause.
+   */
+  readonly recordMissingRevisit: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
@@ -73,8 +79,8 @@ export function hasSketchWithEvidence(
  * Whether the audit found something that should fail the caller.
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
- * does a record past its own ceiling or its own entry cap: the record states
- * each limit for itself, which makes those the measures here that are facts
+ * does a record past its own ceiling or its own entry cap, or missing a
+ * revisit sentence it requires: the record states each rule for itself, which makes those the measures here that are facts
  * rather than thresholds a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
  * declare, an index disagreeing with its folder, and a wireframe's States
@@ -88,13 +94,14 @@ export function isGating({
   unresolvedCitations,
   recordOverLength,
   recordOverCount,
+  recordMissingRevisit,
   sections,
   drift,
   wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
-  if (recordOverLength || recordOverCount) return true
+  if (recordOverLength || recordOverCount || recordMissingRevisit) return true
   if (!widened) return false
 
   return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)

package/src/gate/measures.ts

@@ -11,6 +11,7 @@ import {
   isOverCount,
   isOverLength,
   measureArchitecture,
+  missingRevisit,
 } from '@/context/architecture'
 import { auditSkills } from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
@@ -239,14 +240,15 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
 }
 
 /**
- * The architecture record against the two limits it states for itself: the
- * line ceiling its allowances derive and the entry cap.
+ * The architecture record against the three rules it states for itself: the
+ * line ceiling its allowances derive, the entry cap, and the revisit sentence
+ * closing each decision.
  *
  * Read in-process rather than through `context audit`, whose one gating stage
  * here runs `--citations-only` and never opens the record, which is why the
  * line ceiling went unenforced by `bun run check` until this stage. A project
- * carrying no record, or a record stating neither limit, passes, since both
- * limits belong to the record rather than to the toolkit.
+ * carrying no record, or a record stating none of the three, passes, since
+ * each rule belongs to the record rather than to the toolkit.
  */
 export const architectureRecord: Measure = async (ctx) => {
   const report = await measureArchitecture(ctx.root)
@@ -255,11 +257,14 @@ export const architectureRecord: Measure = async (ctx) => {
   }
 
   const decisions = report.decisions.length
+  const lackingRevisit = missingRevisit(report)
   const failures = [
     isOverCount(report) &&
       `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
     isOverLength(report) &&
       `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+    lackingRevisit.length > 0 &&
+      `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
   ].filter((failure): failure is string => typeof failure === 'string')
 
   if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }

package/src/gate/stages.ts

@@ -354,7 +354,7 @@ export const STAGES: readonly Stage[] = [
     success: 'Context citations resolve',
   },
   {
-    // The record's two limits are facts it states about itself, unlike the
+    // The record's three rules are facts it states about itself, unlike the
     // judgment thresholds the stage above leaves out, so they gate here.
     id: 'architecture-record',
     label: 'Architecture record',

package/src/serve/report.ts

@@ -0,0 +1,110 @@
+import { relative } from 'node:path'
+import {
+  DEFAULT_PORT,
+  type ServeOutcome,
+  type ServeStarted,
+} from '@/serve/static'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+/**
+ * The relative path where it stays inside the working directory, and the
+ * absolute one where it climbs out. A run from a linked worktree serving the
+ * main root reports `../../teach`, which names the directory without giving a
+ * reader anything they can open.
+ */
+export function displayPath(root: string): string {
+  const near = relative(process.cwd(), root)
+  if (near === '') return '.'
+  return near.startsWith('..') ? root : near
+}
+
+/**
+ * Undefined for a value that is not a port, distinct from an absent flag,
+ * which takes the default. A `Number` of a typo is `NaN`, and passing that on
+ * asks the runtime to bind a port nobody named.
+ */
+export function parsePort(raw: string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_PORT
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0 || value > 65535) return undefined
+  return value
+}
+
+/** The fields a started server reports, shared by every command that serves. */
+export function serveFields(outcome: ServeStarted): {
+  readonly host: string
+  readonly port: number
+  readonly entry: string
+  readonly url: string
+  readonly entryExists: boolean
+} {
+  return {
+    host: outcome.host,
+    port: outcome.port,
+    entry: outcome.entry,
+    url: outcome.url,
+    entryExists: outcome.entryExists,
+  }
+}
+
+/** The steps a framed report prints for a running server, inside its frame. */
+export function logServing(outcome: ServeStarted): void {
+  logStep('Serving')
+  logInfo(displayPath(outcome.root))
+  logStep('Open')
+  logInfo(outcome.url)
+
+  if (!outcome.entryExists) {
+    logStep('No entry page')
+    logWarn(
+      `${outcome.entry} is not in that directory, so the link opens a 404`,
+    )
+  }
+
+  logStep('Stop')
+  logInfo('Ctrl-C')
+}
+
+export function report(outcome: ServeOutcome, emitJson: boolean): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, detail: outcome.detail })}\n`,
+      )
+      return 1
+    }
+    intro('canon serve')
+    logError(outcome.detail)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root: outcome.root, ...serveFields(outcome) })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon serve')
+  logServing(outcome)
+  return 0
+}
+
+/**
+ * Resolves when the process is asked to stop. The frame is closed here rather
+ * than in the reporter, because the run is the serving rather than the start,
+ * and closing at start would print the frame's end while the server ran on.
+ */
+export function waitForInterrupt(stop: () => Promise<void>): Promise<void> {
+  return new Promise((settle) => {
+    const finish = () => {
+      void stop().then(() => {
+        outro()
+        settle()
+      })
+    }
+    process.once('SIGINT', finish)
+    process.once('SIGTERM', finish)
+  })
+}

package/src/teach/nav.ts

@@ -1613,8 +1613,19 @@ export async function generateNav(
     const detail = found.workspace
     const metas = await readLessonMetas(root, detail)
 
+    // The generated base sheet is rewritten on every run so a CLI upgrade
+    // reaches it, while a legacy workspace holding only a hand-authored
+    // course.css is never handed a base sheet its lessons do not link.
     const cssPath = join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET)
-    if (!existsSync(cssPath)) await writeStylesheet(root, detail.slug)
+    const basePath = join(
+      root,
+      detail.path,
+      TEACH_ASSETS,
+      TEACH_STYLESHEET_BASE,
+    )
+    if (existsSync(basePath) || !existsSync(cssPath)) {
+      await writeStylesheet(root, detail.slug)
+    }
 
     const contentsPath = join(root, detail.path, 'index.html')
     await writeFile(

package/standards/architecture.md

@@ -65,6 +65,17 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 - Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
 - Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
 
+## Revisit condition
+
+A decision says why it won and rarely says when that reason stops holding, so an entry can go stale while every word in it stays true. The revisit sentence names the finding that would show the harm the decision prevents has gone or moved.
+
+- Close each decision with one sentence of the form `Revisit when <finding>.` Name something a reader could notice, such as a platform release, a measured count crossing a line, or a dependency dropping a behavior.
+- Draft it from the harm the decision prevents, never from the mechanism it uses. A mechanism can keep working long after the reason for choosing it is gone, so re-checking it confirms the wrong fact.
+- Place the sentence after the reasoning and before any verification anchor, so the anchor stays the entry's last sentence.
+- Give a heading holding several principles one sentence, for the premise they share, rather than one per principle.
+- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the cap, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
+- A checker reads presence alone. A vacuous sentence passes it, so the sentence is only as useful as the finding it names.
+
 ## Entry cap
 
 Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
@@ -78,20 +89,20 @@ Every session pays for this file before any work starts, so a heavy read is a re
 
 ## Template
 
-The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
+The revisit sentence closes the reasoning of every decision. The anchor sentence follows it on a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
 
 ```markdown
 # Architecture
 
 ## Overview
 
-This record holds at most 12 decisions.
+This record holds at most 12 decisions. Every decision closes with a revisit sentence.
 
 ## Key technical decisions
 
 ### Stack and runtime
 
-What was chosen, the alternative that lost, and why. Measured at <short-sha> on <YYYY-MM-DD>.
+What was chosen, the alternative that lost, and why. Revisit when <finding>. Measured at <short-sha> on <YYYY-MM-DD>.
 
 ### Delivery
 

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