@erclx/canon 5.38.0 → 5.39.0

package/src/markdown/gate.ts

@@ -1,10 +1,20 @@
 import type { ColonFinding } from '@/markdown/colons'
+import type { DensityFinding } from '@/markdown/density'
 import type { HeadingCaseFinding } from '@/markdown/heading-case'
 import type { LinkFinding } from '@/markdown/links'
+import type { ReferenceShapeFinding } from '@/markdown/reference-shape'
 import type { BanFinding } from '@/markdown/scan'
-import type { StackFinding } from '@/markdown/stacks'
+import { GATED_PATHS } from '@/markdown/scope'
 import type { StructureReport } from '@/markdown/structure'
 
+export interface GatedDensityFinding extends DensityFinding {
+  readonly gating: boolean
+}
+
+export interface GatedReferenceShapeFinding extends ReferenceShapeFinding {
+  readonly gating: boolean
+}
+
 export interface GateInput {
   /** Every ban hit across every file measured, flattened. */
   readonly bans: readonly BanFinding[]
@@ -13,10 +23,11 @@ export interface GateInput {
   /**
    * Every structural measure the run made, read by nothing here.
    *
-   * Naming it is what makes the split checkable: bullet, paragraph, and depth
-   * weight are judgments a reader settles, and a push failing on one teaches a
-   * contributor to route around the stage. A signature taking the ban list
-   * alone states the same rule and leaves no place to assert it.
+   * Naming it is what makes the split checkable: depth weight, cadence, and the
+   * sentence count are judgments a reader settles, and a push failing on one
+   * teaches a contributor to route around the stage. The bullet and paragraph
+   * weight a reader settles here are the advisory half, and the same numbers
+   * gate through `density` below, which knows the path each one sits on.
    */
   readonly structure: readonly StructureReport[]
   /**
@@ -33,25 +44,53 @@ export interface GateInput {
    */
   readonly headingCase: readonly HeadingCaseFinding[]
   /**
-   * Every run of plain bullets past the cap, read by nothing here.
+   * Every density finding, each marked with whether its path gates.
    *
-   * The stage that gates it is `bullet-stacks` in `src/gate/stages.ts`, which
-   * reads a scope of tracked files. This audit also runs on plans and
-   * groundwork records kept out of version control, where a long list is not
-   * a defect, which is the reason `documentCeiling` gates apart from it too.
+   * The mark is decided by the caller from `src/markdown/scope.ts`, since only
+   * the caller knows the path and whether the tree is a canon checkout. A plan,
+   * a groundwork record, and a rule carry no density finding at all, and an
+   * in-scope path under no gated prefix carries one marked `gating: false`.
+   */
+  readonly density: readonly GatedDensityFinding[]
+  /**
+   * Every reference shape finding, each marked with whether its path gates.
+   * Only a page whose frontmatter carries `kind: reference` has any.
    */
-  readonly bulletStacks: readonly StackFinding[]
+  readonly referenceShape: readonly GatedReferenceShapeFinding[]
 }
 
 /**
  * Whether the audit found something that should fail the caller.
  *
- * A banned character and a relative link resolving to
- * nothing on disk are both facts rather than a threshold, so either gates
- * unconditionally and there is no widened mode to reach for. The standards
- * decide what counts as banned, which keeps this answering how many rather
- * than which.
+ * A banned character and a relative link resolving to nothing on disk are both
+ * facts rather than a threshold, so either gates unconditionally and there is
+ * no widened mode to reach for. A density finding is a fact too, a count
+ * against a fixed number, and it gates wherever the caller marked its path as
+ * gated, and so does a reference shape finding. The standards decide what
+ * counts as banned, which keeps this answering how many rather than which.
+ */
+export function isGating({
+  bans,
+  links,
+  density,
+  referenceShape,
+}: GateInput): boolean {
+  return (
+    bans.length > 0 ||
+    links.length > 0 ||
+    density.some((finding) => finding.gating) ||
+    referenceShape.some((finding) => finding.gating)
+  )
+}
+
+/**
+ * Whether a reference shape finding on this path fails the run, under the
+ * prefixes density gates on. A page is opted in by its own marker, so the
+ * density scope and the always-gated bullet run have nothing to add here.
  */
-export function isGating({ bans, links }: GateInput): boolean {
-  return bans.length > 0 || links.length > 0
+export function referenceShapeGates(
+  rel: string,
+  gated: readonly string[] = GATED_PATHS,
+): boolean {
+  return gated.some((prefix) => rel.startsWith(prefix))
 }

package/src/markdown/reference-shape.ts

@@ -0,0 +1,103 @@
+import { bodyLines } from '@/markdown/scan'
+import { TABLE_ROW } from '@/markdown/structure'
+
+/** The H2 sections a reference page may hold below its opening. */
+export const REFERENCE_SECTIONS: readonly string[] = [
+  'Output',
+  'Refusals',
+  'See also',
+]
+
+export type ReferenceShapeKind =
+  | 'extra-section'
+  | 'section-order'
+  | 'subsection'
+  | 'flag-table'
+
+export interface ReferenceShapeFinding {
+  readonly kind: ReferenceShapeKind
+  readonly line: number
+  /** The heading text, or the first header cell of a flag table. */
+  readonly text: string
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/
+const MARKER = /^kind:\s*(["']?)reference\1\s*$/m
+const HEADING = /^(#{2,3})\s+(.*?)(?:\s+#+)?\s*$/
+const SEPARATOR_ROW = /^\s*\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*$/
+
+/**
+ * A first header cell naming flags or options, read with its code span and
+ * emphasis stripped. Only the first column is read, so a refusal table headed
+ * `Reason` stays out of reach whatever its later columns say.
+ */
+const FLAG_HEADER = /^(?:flags?|options?)$/i
+
+/** Whether the page's frontmatter opts it into the reference shape. */
+export function isReferencePage(source: string): boolean {
+  const frontmatter = FRONTMATTER.exec(source)
+  return frontmatter !== null && MARKER.test(frontmatter[1])
+}
+
+/**
+ * Every breach of the reference shape on a page marked `kind: reference`, in
+ * line order, and nothing on an unmarked page.
+ *
+ * The shape is an opening holding the command, then `## Output`,
+ * `## Refusals`, and `## See also`, each at most once and in that order, though
+ * a page may leave one out, with no H3 and no table of flags, since
+ * `--help` already prints them. The check reads headings and table headers
+ * outside fences and leaves the opening to a reader.
+ */
+export function referenceShapeFindings(
+  source: string,
+): ReferenceShapeFinding[] {
+  if (!isReferencePage(source)) return []
+
+  const found: ReferenceShapeFinding[] = []
+  const lines = bodyLines(source)
+  let lastSection = -1
+
+  for (const [index, line] of lines.entries()) {
+    if (line.fenced) continue
+
+    const heading = HEADING.exec(line.text)
+    if (heading) {
+      const [, marks, text] = heading
+      if (marks.length === 3) {
+        found.push({ kind: 'subsection', line: line.number, text })
+      } else {
+        const position = REFERENCE_SECTIONS.indexOf(text)
+        if (position === -1) {
+          found.push({ kind: 'extra-section', line: line.number, text })
+        } else if (position <= lastSection) {
+          found.push({ kind: 'section-order', line: line.number, text })
+        } else {
+          lastSection = position
+        }
+      }
+      continue
+    }
+
+    const previous = lines[index - 1]
+    const next = lines[index + 1]
+    const opensTable =
+      TABLE_ROW.test(line.text) &&
+      !(previous && !previous.fenced && TABLE_ROW.test(previous.text)) &&
+      next !== undefined &&
+      SEPARATOR_ROW.test(next.text)
+    if (!opensTable) continue
+
+    const first = firstCell(line.text)
+    if (FLAG_HEADER.test(first)) {
+      found.push({ kind: 'flag-table', line: line.number, text: first })
+    }
+  }
+
+  return found
+}
+
+function firstCell(row: string): string {
+  const cells = row.trim().replace(/^\|/, '').split('|')
+  return (cells[0] ?? '').replace(/[`*_]/g, '').trim()
+}

package/src/markdown/scope.ts

@@ -0,0 +1,174 @@
+import type { DensityKind } from '@/markdown/density'
+
+/** The surfaces the retired bullet-stacks stage held, per `ALWAYS_GATED`. */
+const BULLET_RUN_SCOPE = [
+  /^canon\/context\/.+\.md$/,
+  /^docs\/.+\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/SKILL\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/references\/.+\.md$/,
+]
+
+/**
+ * The tracked documents the density limits hold: the context entries, the docs
+ * pages, the skill bodies and references of both skill trees, the tooling
+ * seeds and stack references, the wiki, and the two root guides.
+ *
+ * Rules stay out, since a rule is one imperative per bullet. So do
+ * `CLAUDE.md`, the requirement and design records, a seed carrying one of
+ * those three names, the changelog, the examples, and every `.canon/` record,
+ * each with a shape and cap of its own. Named here and nowhere else, so the
+ * audit, the gate stage reading its exit, and their tests read one scope.
+ */
+const DENSITY_SCOPE = [
+  ...BULLET_RUN_SCOPE,
+  /^tooling\/[^/]+\/seeds\/(?:.+\/)?(?!(?:CLAUDE|REQUIREMENTS|DESIGN)\.md$)[^/]+\.md$/,
+  /^tooling\/[^/]+\/reference\.md$/,
+  /^wiki\/.+\.md$/,
+  /^(?:README|CONTRIBUTING)\.md$/,
+]
+
+/**
+ * The path prefixes whose density findings fail a run, each added by the
+ * rewrite batch that brought its folders to zero.
+ *
+ * It describes this repository's rewrite progress and nothing about a target's
+ * corpus, which is why the audit reads it only inside a canon checkout.
+ */
+export const GATED_PATHS: readonly string[] = [
+  'canon/context/claude-plugin/',
+  'canon/context/claude-internal/',
+  'canon/context/features/',
+  'canon/context/cli/',
+  'canon/context/sandbox/',
+  'canon/context/governance/',
+  'canon/context/tooling/',
+  'canon/context/web.md',
+  'canon/context/context-model.md',
+  'canon/context/design.md',
+  'canon/context/index.md',
+  'claude/skills/api-design/SKILL.md',
+  'claude/skills/auto-ship/SKILL.md',
+  'claude/skills/backlog-triage/SKILL.md',
+  'claude/skills/backlog-triage/references/apply.md',
+  'claude/skills/build-in-slices/SKILL.md',
+  'claude/skills/canon-cli/SKILL.md',
+  'claude/skills/canon-feedback-triage/SKILL.md',
+  'claude/skills/canon-feedback/SKILL.md',
+  'claude/skills/canvas-board/SKILL.md',
+  'claude/skills/ci-workflow/SKILL.md',
+  'claude/skills/code-craft/SKILL.md',
+  'claude/skills/codebase-layout/SKILL.md',
+  'claude/skills/context-fold/SKILL.md',
+  'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-skill/SKILL.md',
+  'claude/skills/decision-escalate/SKILL.md',
+  'claude/skills/deploy-app/SKILL.md',
+  'claude/skills/deprecation-migration/SKILL.md',
+  'claude/skills/design-taste/SKILL.md',
+  'claude/skills/docs-sync/SKILL.md',
+  'claude/skills/document-health/SKILL.md',
+  'claude/skills/draft-and-pick/SKILL.md',
+  'claude/skills/draft-doc/SKILL.md',
+  'claude/skills/draft-figure/SKILL.md',
+  'claude/skills/draft-identity/SKILL.md',
+  'claude/skills/draft-identity/references/card-route.md',
+  'claude/skills/draft-ready/SKILL.md',
+  'claude/skills/draft-screencast/SKILL.md',
+  'claude/skills/draft-screencast/references/beats-template.md',
+  'claude/skills/draft-slides/SKILL.md',
+  'claude/skills/git-branch/SKILL.md',
+  'claude/skills/git-commit/SKILL.md',
+  'claude/skills/git-followup/SKILL.md',
+  'claude/skills/git-issue/SKILL.md',
+  'claude/skills/git-pr/SKILL.md',
+  'claude/skills/git-ship/SKILL.md',
+  'claude/skills/git-ship/references/ci-watch.md',
+  'claude/skills/git-split/SKILL.md',
+  'claude/skills/git-split/references/independent.md',
+  'claude/skills/git-split/references/stacked.md',
+  'claude/skills/git-stage/SKILL.md',
+  'claude/skills/git-worktree/SKILL.md',
+  'claude/skills/git-worktree/references/cleanup.md',
+  'claude/skills/markdown-craft/SKILL.md',
+  'claude/skills/plan-feature/SKILL.md',
+  'claude/skills/plan-feature/references/batches.md',
+  'claude/skills/plan-groundwork/SKILL.md',
+  'claude/skills/plan-groundwork/references/output.md',
+  'claude/skills/plan-intake-answer/SKILL.md',
+  'claude/skills/plan-intake/SKILL.md',
+  'claude/skills/read-frames/SKILL.md',
+  'claude/skills/record-screencast/SKILL.md',
+  'claude/skills/review-address/SKILL.md',
+  'claude/skills/review-address/references/rebase-only.md',
+  'claude/skills/review-craft/SKILL.md',
+  'claude/skills/review-pr/SKILL.md',
+  'claude/skills/review-ui/SKILL.md',
+  'claude/skills/review-ui/references/hosted-preview.md',
+  'claude/skills/role-orchestrator/SKILL.md',
+  'claude/skills/role-orchestrator/references/orchestrator-filing.md',
+  'claude/skills/role-planner/SKILL.md',
+  'claude/skills/role-reviewer/SKILL.md',
+  'claude/skills/role-worker/SKILL.md',
+  'claude/skills/search-craft/SKILL.md',
+  'claude/skills/session-compact/SKILL.md',
+  'claude/skills/session-map/SKILL.md',
+  'claude/skills/session-relay/SKILL.md',
+  'claude/skills/session-resume/SKILL.md',
+  'claude/skills/session-worktree/SKILL.md',
+  'claude/skills/systematic-debugging/SKILL.md',
+  'claude/skills/target-check/SKILL.md',
+  'claude/skills/target-setup/SKILL.md',
+  'claude/skills/task-board/SKILL.md',
+  'claude/skills/task-board/references/create-report.md',
+  'claude/skills/task-complete/SKILL.md',
+  'claude/skills/teach-workspace/SKILL.md',
+  'claude/skills/test-craft/SKILL.md',
+  'claude/skills/test-first/SKILL.md',
+  'claude/skills/ui-checklist/SKILL.md',
+  'claude/skills/ux-audit/SKILL.md',
+  'claude/skills/ux-measure/SKILL.md',
+  'claude/skills/video-craft/SKILL.md',
+  'claude/skills/write-human/SKILL.md',
+  'claude/skills/youtube-transcripts/SKILL.md',
+  'docs/agents/indexes.md',
+  'docs/agents/install-and-sync.md',
+  'docs/agents/migrate.md',
+  'docs/agents/output-shape.md',
+  'docs/agents/overview.md',
+  'docs/agents/targets.md',
+  'canon/context/development/',
+  'canon/context/ci/',
+  'canon/context/scripts/',
+  '.claude/skills/internal-',
+]
+
+/**
+ * The limit that gates before any folder is listed, and the surfaces it gates
+ * on. A run of more than 5 plain bullets failed the push in the context
+ * entries, the docs pages, and the skill bodies and references through a stage
+ * of its own before this measure existed, and waiting on `GATED_PATHS` would
+ * reopen that hole. The seeds, the stack references, the wiki, and the root
+ * guides were never held to it, and seven runs in the stack references would
+ * fail the push on the day this lands, so those wait for their batch.
+ */
+const ALWAYS_GATED: readonly DensityKind[] = ['bullet-run']
+
+/** Whether a path takes density findings at all. */
+export function inDensityScope(rel: string): boolean {
+  return DENSITY_SCOPE.some((pattern) => pattern.test(rel))
+}
+
+/** Whether a density finding of this kind on this path fails the run. */
+export function densityGates(
+  rel: string,
+  kind: DensityKind,
+  gated: readonly string[] = GATED_PATHS,
+): boolean {
+  if (!inDensityScope(rel)) return false
+  if (
+    ALWAYS_GATED.includes(kind) &&
+    BULLET_RUN_SCOPE.some((pattern) => pattern.test(rel))
+  )
+    return true
+  return gated.some((prefix) => rel.startsWith(prefix))
+}

package/src/markdown/structure.ts

@@ -1,6 +1,6 @@
 import { type BodyLine, visibleText } from '@/markdown/scan'
 
-const HEADING = /^#{1,6}\s/
+export const HEADING = /^#{1,6}\s/
 
 /**
  * A section marker holding its line alone, which is the signpost a document
@@ -65,10 +65,10 @@ const BOLD_LINE = /^\*\*([^*]+)\*\*\s*$/
 const SPAN_LABEL = /^`[^`]+`$/
 const MARKER_WIDTH = 20
 
-const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
-const TABLE_ROW = /^\s*\|/
+export const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
+export const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
-const BLOCKQUOTE = /^\s*>/
+export const BLOCKQUOTE = /^\s*>/
 
 /**
  * A sentence ends on terminal punctuation followed by the start of another
@@ -109,8 +109,8 @@ const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“([]*[A-Z]|`)|\s*$)/g
 export const CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
-  bullet: 250,
-  paragraph: 700,
+  bullet: 200,
+  paragraph: 350,
   sentences: 4,
   renderWidth: 80,
   cadence: 3,
@@ -336,7 +336,7 @@ function isTableRun(run: readonly BodyLine[]): boolean {
  * what lets a linked path reach the span test at all, since the markup around
  * it would fail the pattern the destination is still attached.
  */
-function isSectionMarker(text: string): boolean {
+export function isSectionMarker(text: string): boolean {
   const marker = text.match(BOLD_LINE)
   if (!marker) return false
 
@@ -438,11 +438,7 @@ interface FoldedBullet extends BulletFinding {
   readonly text: string
 }
 
-/**
- * The walk `heavyBullets` reports from, keeping each past-checkpoint bullet's
- * text so `longBlocks` can ask whether a base copy of it exists. One walk
- * rather than two, for the reason `paragraphBlocks` is shared.
- */
+/** The walk `heavyBullets` reports from. */
 function foldBullets(
   lines: readonly BodyLine[],
   checkpoints: Checkpoints,
@@ -579,10 +575,7 @@ function paragraphText(block: readonly BodyLine[]): string {
  * paragraph rule whenever the bullet rule was changed, and an author reading
  * the sentence cap would find no weight rule to read at all.
  *
- * The two numbers coincide today because paragraph and bullet weight measure
- * one population, sharing a median near 170 characters with no gap behind
- * either candidate. They are separate checkpoints regardless, so either moves
- * without dragging the other.
+ * They are separate checkpoints, so either moves without dragging the other.
  */
 export function heavyParagraphs(
   lines: readonly BodyLine[],
@@ -606,49 +599,6 @@ export function heavyParagraphs(
   return findings
 }
 
-export interface LongBlock {
-  readonly kind: 'paragraph' | 'bullet'
-  readonly line: number
-  readonly characters: number
-  /** The block's source lines folded into one, as the paragraph and bullet folds read it. */
-  readonly text: string
-}
-
-/**
- * The paragraphs past the paragraph checkpoint and the top-level bullets past
- * the bullet checkpoint, each with its text.
- *
- * Weight alone, never the sentence cap, since the growth stage asks about the
- * two numbers the standard states in characters. The definitions are the
- * audit's own, so a block this names and a block the weight report names are
- * one set.
- */
-export function longBlocks(
-  lines: readonly BodyLine[],
-  checkpoints: Checkpoints,
-): LongBlock[] {
-  const blocks: LongBlock[] = []
-
-  for (const block of paragraphBlocks(lines)) {
-    const text = paragraphText(block)
-    const characters = visibleText(text).length
-    if (characters > checkpoints.paragraph) {
-      blocks.push({
-        kind: 'paragraph',
-        line: block[0].number,
-        characters,
-        text,
-      })
-    }
-  }
-
-  for (const bullet of foldBullets(lines, checkpoints)) {
-    blocks.push({ kind: 'bullet', ...bullet })
-  }
-
-  return blocks.sort((a, b) => a.line - b.line)
-}
-
 /** Punctuation either side of a word, so an opener is compared on its letters. */
 const WORD_EDGE = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu
 

package/src/shipped/references.ts

@@ -132,7 +132,7 @@ const SAME_REPOSITORY =
  * `canon/context/` carries no equivalent pattern. The same resolution test
  * cannot separate a path every scaffolded project holds, such as
  * `canon/context/index.md`, from this repository's own domain entry, such
- * as `canon/context/context-model/indexes.md`, since both resolve here and only the
+ * as `canon/context/context-model.md`, since both resolve here and only the
  * second is a defect. That is a semantic read no pattern makes, so it stays
  * with the rule and the review checklist rather than joining this reader.
  */

package/tooling/claude/seeds/.claude/hooks/reply-links.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+# A reply with no link is the ordinary turn, so it leaves before anything
+# spawns. The payload holds the reply JSON-escaped, and `](` survives the
+# escaping untouched, so a shell test on the raw payload is enough. This is the
+# one quiet exit: every later failure to measure reports instead.
+case "$input" in
+*']('*) ;;
+*) exit 0 ;;
+esac
+
+# A failure to measure exits 1 rather than 2. Exit 2 forces the session to
+# continue, and a hook that cannot read `stop_hook_active` would then block
+# every continuation too.
+unread() {
+  printf 'Reply-links: the final reply was not checked. %s\n' "$1" >&2
+  exit 1
+}
+
+command -v jq >/dev/null 2>&1 || unread 'Found no `jq` on PATH.'
+
+event=$(printf '%s' "$input" | jq -r '.hook_event_name // empty' 2>/dev/null)
+[ -n "$event" ] || unread 'The payload did not parse.'
+[ "$event" = "Stop" ] || exit 0
+
+# The forced continuation after a block fires this hook again with the field
+# true. Passing it is what makes the block fire once, so the corrected links
+# are not checked a second time.
+stop_hook_active=$(printf '%s' "$input" | jq -r '.stop_hook_active // false')
+[ "$stop_hook_active" = "true" ] && exit 0
+
+reply=$(printf '%s' "$input" | jq -r '.last_assistant_message // empty')
+case "$reply" in
+*']('*) ;;
+*) exit 0 ;;
+esac
+
+# The verb resolves a relative link against the main worktree root, read from
+# the directory the session stands in, so the payload's cwd is named rather than
+# inherited from wherever the hook was spawned.
+cwd=$(printf '%s' "$input" | jq -r '.cwd // empty')
+[ -n "$cwd" ] && [ -d "$cwd" ] || unread 'The payload carried no working directory that exists.'
+
+# A project has no checkout of the CLI, so this resolves the installed binary
+# alone, and a machine without it says so rather than passing the reply.
+if command -v canon >/dev/null 2>&1; then
+  record=$(cd "$cwd" && printf '%s' "$reply" | canon hooks reply-links --json 2>/dev/null)
+else
+  unread 'Found no `canon` binary on PATH. Install one with `bun add -g @erclx/canon`.'
+fi
+
+# The record decides rather than the exit code. A binary predating the verb
+# exits 1 on an unknown command, which is the code a finding also leaves, and
+# it writes no record.
+ok=$(printf '%s' "$record" | jq -r 'if .ok == true then "true" elif .ok == false then "false" else empty end' 2>/dev/null)
+case "$ok" in
+true) exit 0 ;;
+false)
+  printf '%s\n' "$(printf '%s' "$record" | jq -r '.message')" >&2
+  exit 2
+  ;;
+*) unread 'The link check returned no record. An installed `canon` that predates `canon hooks reply-links` does this.' ;;
+esac

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

@@ -77,13 +77,24 @@ headings=$(printf '%s' "$record" |
 colons=$(printf '%s' "$record" |
   jq -r --arg new "$new" '.entries[]?.colons[]? | (.lead // (.text[:.column] | sub("^.*\\s"; ""))) as $lead | select($new | contains($lead + ":")) | ":\(.line):\(.column + 1)  \(.text)"' 2>/dev/null)
 
+# Density findings are handed back whole, gating or not, since the verb only
+# returns them for a path in its scope and a finding the push does not fail on
+# yet is the one a rewrite has to clear before its folder is gated.
+density=$(printf '%s' "$record" |
+  jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
+
+# A page marked `kind: reference` carries reference shape findings, handed back
+# whole the same way, since a gated one fails the push like a density finding.
+shape=$(printf '%s' "$record" |
+  jq -r '.entries[]?.referenceShape[]? | ":\(.line)  \(.kind)  \(.text)" + (if .gating then "  gating" else "" end)' 2>/dev/null)
+
 # A set the verb shipped empty measures nothing and would report a clean file.
 # Reading the findings alone turns that narrowed check into a pass, so the field
 # is read beside them.
 empty=$(printf '%s' "$record" |
   jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
+[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
@@ -111,4 +122,14 @@ if [ -n "$colons" ]; then
   msg="${msg:+$msg$nl}$found"
 fi
 
+if [ -n "$density" ]; then
+  found=$(printf 'Standards-audit: %s breaks the markdown density limits, being a 350-character paragraph, 2 paragraphs in a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a paragraph or table opening every H3. Split each block at its seam rather than trimming words to pass. A finding marked gating fails the push.\n%s' "$file" "$density")
+  msg="${msg:+$msg$nl}$found"
+fi
+
+if [ -n "$shape" ]; then
+  found=$(printf 'Standards-audit: %s is marked kind: reference and breaks its shape, being an opening, then Output, Refusals, and See also, each at most once and in that order, no H3, and no flag table. Point at the command'"'"'s own --help for flags. A finding marked gating fails the push.\n%s' "$file" "$shape")
+  msg="${msg:+$msg$nl}$found"
+fi
+
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/settings.json

@@ -72,6 +72,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/silent-turn.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/reply-links.sh"
           }
         ]
       }