@erclx/canon 4.30.2 → 4.31.1

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

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

package/docs/agents/audits.md

@@ -32,9 +32,9 @@ Each is invoked as the CLI the caller is running rather than as a global `canon`
 
 ## What gates and what reports
 
-Four findings fail the run: an unresolved context citation, a banned character, word, or spelling, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
+Five findings fail the run: an unresolved context citation, a banned character, word, or spelling, a relative link resolving to nothing on disk, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
 
-Three of the four are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
+Four of the five are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
 
 Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
 

package/docs/agents/commands.md

@@ -54,7 +54,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon worktrees reclaim`     | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                                                                                  |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                                                                             |
 | `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                                                                                          |
-| `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                                                                             |
+| `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, or a dead relative link, and report the structural checkpoints                                                                                                    |
 | `canon claude skills audit`   | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                                                                                     |
 | `canon standards audit`       | Report the corpus against the success-criterion gate `standards/standard.md` states, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                                                    |
 | `canon claude skills drift`   | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                                                                                          |

package/docs/agents/markdown-audit.md

@@ -59,6 +59,12 @@ A banned spelling keeps the plain word boundary, hyphens included. The two bans
 
 Two ban shapes stay unmeasured and the report says so on every run. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim sit in the first group by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole standard.
 
+### Links
+
+A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination is skipped rather than resolved when it is empty, opens with a URL scheme, opens with `#` as a same-file anchor, opens with `/` as a root-absolute reference, or carries `<` as a template placeholder such as `<slug>` or `<name>`. What remains is split on its first `#`, decoded, and resolved against the linking file's own folder, and a destination resolving to nothing on disk reports.
+
+The placeholder exemption is the one live case the corpus needs. Every current instance is a genuine illustration rather than a literal path, and a marker-based override is available for the day a real one needs an exception instead.
+
 ### Bullets, paragraphs, and depth
 
 Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
@@ -124,7 +130,7 @@ The condition on that was something identifying a finite verb rather than guessi
 
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling fails the run. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 

package/package.json

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

package/scripts/core/check-capability-seeding.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+shopt -s nullglob
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TOOLING_ROOT="$PROJECT_ROOT/tooling"
+MARKER="canon-no-seed:"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports every capability seeded having never read one.
+if [ ! -d "$TOOLING_ROOT" ]; then
+  echo "No tooling root at ${TOOLING_ROOT#"$PROJECT_ROOT/"}, capability seeding unverifiable." >&2
+  exit 1
+fi
+
+failures=""
+
+# A comment naming the marker anywhere in the source file is the recorded
+# reason a capability withholds itself from every destination it was compared
+# against. The reason's own prose is free-form, so only the marker is tested.
+has_reason() {
+  grep -q "$MARKER" "$1"
+}
+
+# Compares one source directory's files against the basenames already
+# expanded from a set of destination paths. Presence on either side clears a
+# name; a source file reaching neither the destination nor a marked reason is
+# a capability answered on one side of the seed or config boundary and not
+# the other.
+check_capability() {
+  local label="$1" src_dir="$2"
+  shift 2
+
+  [ -d "$src_dir" ] || return 0
+
+  local dest_names=" "
+  local dest
+  for dest in "$@"; do
+    [ -f "$dest" ] || continue
+    dest_names="$dest_names$(basename "$dest") "
+  done
+
+  local src_file name
+  for src_file in "$src_dir"/*; do
+    [ -f "$src_file" ] || continue
+    name=$(basename "$src_file")
+    case "$dest_names" in
+    *" $name "*) continue ;;
+    esac
+    has_reason "$src_file" && continue
+    failures="$failures  $label: ${src_file#"$PROJECT_ROOT/"} reaches no seed or config and carries no $MARKER reason"$'\n'
+  done
+}
+
+check_capability "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT"/tooling/claude/seeds/.claude/hooks/*
+
+check_capability "Workflows" "$PROJECT_ROOT/.github/workflows" \
+  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/*
+
+check_capability "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT"/tooling/base/configs/.husky/*
+
+# The reverse direction: a destination file whose source here is gone reaches
+# neither check_capability above nor the wiring pass below, both of which read
+# forward from the source, and it ships a target a hook, workflow, or husky
+# script this repository has already deleted. A destination carrying the same
+# marker clears just as a source does, which is the escape hatch a target-only
+# capability needs, such as a stack-specific workflow with no root counterpart
+# by design.
+check_orphans() {
+  local label="$1" src_dir="$2" dest_dir="$3"
+
+  [ -d "$dest_dir" ] || return 0
+
+  local dest_file name
+  for dest_file in "$dest_dir"/*; do
+    [ -f "$dest_file" ] || continue
+    name=$(basename "$dest_file")
+    [ -f "$src_dir/$name" ] && continue
+    has_reason "$dest_file" && continue
+    failures="$failures  $label: ${dest_file#"$PROJECT_ROOT/"} is seeded or configured with no source at ${src_dir#"$PROJECT_ROOT/"}/$name"$'\n'
+  done
+}
+
+check_orphans "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+
+for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows; do
+  check_orphans "Workflows" "$PROJECT_ROOT/.github/workflows" "$dir"
+done
+
+check_orphans "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT/tooling/base/configs/.husky"
+
+# A hook that reached the seed tree with no wiring in the seeded settings.json
+# is installed dead, which fails the same way an unseeded hook does.
+SEED_HOOKS_DIR="$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+SEED_SETTINGS="$PROJECT_ROOT/tooling/claude/seeds/.claude/settings.json"
+
+if [ -d "$SEED_HOOKS_DIR" ]; then
+  if [ ! -f "$SEED_SETTINGS" ]; then
+    failures="$failures  Seed settings: no settings.json at ${SEED_SETTINGS#"$PROJECT_ROOT/"} to confirm a seeded hook is wired"$'\n'
+  elif ! command -v jq >/dev/null 2>&1; then
+    failures="$failures  Seed settings: jq is not installed, seeded-hook wiring unverifiable"$'\n'
+  else
+    # Every wired command as its own path segment set, rather than a substring
+    # search over the raw file, so a hook name that is a substring of another
+    # hook's filename (`log.sh` inside `pr-create-log.sh`) cannot pass on a
+    # neighbor's wiring.
+    wired=" $(jq -r '.. | .command? // empty' "$SEED_SETTINGS" | tr '/\n' '  ') "
+    for hook_file in "$SEED_HOOKS_DIR"/*.sh; do
+      [ -f "$hook_file" ] || continue
+      name=$(basename "$hook_file")
+      case "$wired" in
+      *" $name "*) continue ;;
+      esac
+      failures="$failures  Seed settings: $name is seeded and wired into no command in ${SEED_SETTINGS#"$PROJECT_ROOT/"}"$'\n'
+    done
+  fi
+fi
+
+if [ -n "$failures" ]; then
+  echo "A capability reaches one side of the seed or config boundary and not the other:" >&2
+  printf '%s' "$failures" >&2
+  echo "Seed or configure the capability, or mark the source line with # $MARKER <reason>." >&2
+  exit 1
+fi

package/scripts/lib/sandbox-git.sh

@@ -112,6 +112,14 @@ ensure_sandbox_anchor_repo() {
   log_info "Created ${GITHUB_ORG}/${repo_name} as a private repository."
 }
 
+# Mirrors the merge-base resolution the diff-baseline port already carries
+# across five skill bodies, so a checkout whose local main trails origin/main
+# does not pull in skill bodies other merged branches changed.
+resolve_sandbox_skill_diff_base() {
+  git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null ||
+    git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null
+}
+
 # A remote is useless without an author, so the scenarios that reach one always
 # configure both. configure_sandbox_git_identity stays callable on its own for
 # the scenarios that never push. The probe runs first so an absent remote is

package/scripts/manage-sandbox.sh

@@ -283,8 +283,12 @@ tag_sandbox_baseline() {
 }
 
 inject_changed_skills() {
+  local base
+  base=$(resolve_sandbox_skill_diff_base)
+  base="${base:-main}"
+
   local changed untracked
-  changed=$(git -C "$PROJECT_ROOT" diff main --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
+  changed=$(git -C "$PROJECT_ROOT" diff "$base" --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
   untracked=$(git -C "$PROJECT_ROOT" ls-files --others --exclude-standard -- 'claude/skills/**/SKILL.md' 2>/dev/null)
 
   local combined
@@ -293,8 +297,8 @@ inject_changed_skills() {
   [ -z "$combined" ] && return
 
   while IFS= read -r skill_path; do
-    # The diff against main lists a deleted skill alongside a changed one, and
-    # there is nothing left to inject for a name this branch removed.
+    # The diff against the base lists a deleted skill alongside a changed one,
+    # and there is nothing left to inject for a name this branch removed.
     [ -f "$PROJECT_ROOT/$skill_path" ] || continue
 
     local skill_name
@@ -302,6 +306,9 @@ inject_changed_skills() {
     local target_dir="$SANDBOX/.claude/skills/$skill_name"
     mkdir -p "$target_dir"
     cp "$PROJECT_ROOT/$skill_path" "$target_dir/SKILL.md"
+    if [ -n "$SANDBOX_SKIP_AUTO_COMMIT" ]; then
+      echo ".claude/skills/$skill_name/SKILL.md" >>"$SANDBOX/.git/info/exclude"
+    fi
     log_info "Injected dev skill: $skill_name"
   done <<<"$combined"
 }

package/src/commands/markdown.ts

@@ -1,9 +1,11 @@
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
+import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
 import {
   type BanFinding,
   type BanSets,
@@ -47,6 +49,7 @@ interface AuditCommandOptions {
 interface FileReport {
   readonly rel: string
   readonly bans: readonly BanFinding[]
+  readonly links: readonly LinkFinding[]
   readonly structure: StructureReport
 }
 
@@ -74,12 +77,13 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
-        '  2  a banned character, word, or spelling is present',
+        '  2  a banned character, word, or spelling is present, or a relative',
+        '     link resolves to nothing on disk',
         '  3  a shipped ban set is empty, so the run measured nothing',
         '',
-        'A ban hit is a fact and gates unconditionally. Bullet, paragraph, and',
-        'depth weight are judgments a reader settles, so all three report and',
-        'none of them fails a run.',
+        'A ban hit and a dead link are each a fact and gate unconditionally.',
+        'Bullet, paragraph, and depth weight are judgments a reader settles,',
+        'so all three report and none of them fails a run.',
         '',
         'Cadence reports the same way and carries one more caveat. Its range is',
         'drawn from prose a person reads, so terse reference prose sits below',
@@ -143,10 +147,14 @@ async function runAudit(
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
-      const lines = bodyLines(await readFile(resolve(root, rel), 'utf8'))
+      const abs = resolve(root, rel)
+      const lines = bodyLines(await readFile(abs, 'utf8'))
       return {
         rel,
         bans: scanBans(lines, bans),
+        links: findBrokenLinks(lines, (path) =>
+          existsSync(resolve(dirname(abs), path)),
+        ),
         structure: measureStructure(rel, lines, checkpoints),
       }
     }),
@@ -155,6 +163,7 @@ async function runAudit(
   intro('canon markdown audit')
   reportScope(scope.files, scope.unmatched)
   reportBans(reports, bans, empty)
+  reportLinks(reports, root)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -187,6 +196,7 @@ async function runAudit(
         entries: reports.map((report) => ({
           path: report.rel,
           bans: report.bans,
+          links: report.links,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -203,6 +213,7 @@ async function runAudit(
 
   const gating = isGating({
     bans: reports.flatMap((report) => report.bans),
+    links: reports.flatMap((report) => report.links),
     structure: reports.map((report) => report.structure),
   })
 
@@ -304,6 +315,59 @@ function reportBans(
   )
 }
 
+/**
+ * Names both the destination as written and the path it resolved to, since
+ * the second is what an editor can go check and the first is what a fix
+ * touches.
+ */
+function resolvedLinkPath(
+  root: string,
+  rel: string,
+  destination: string,
+): string {
+  const path = decodePath(destination)
+  if (path === undefined) return '(destination carries a malformed encoding)'
+  return relative(root, resolve(dirname(resolve(root, rel)), path))
+}
+
+function reportLinks(reports: readonly FileReport[], root: string): void {
+  logStep('Links')
+  logInfo(
+    "A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads.",
+  )
+  logInfo(
+    'A destination carrying a template placeholder in angle brackets reads as an illustration rather than a literal path.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.links.length > 0)
+    .sort((a, b) => b.links.length - a.links.length)
+
+  if (carrying.length === 0) {
+    logInfo('No relative link resolving to nothing on disk.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.links.length, 0)
+  logWarn(
+    `${plural(total, 'dead link')} across ${plural(carrying.length, 'file')}`,
+  )
+  logWarn('This fails the run. Every other check below reports.')
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.links.length, 'link')}\n${report.links
+            .map(
+              (found) =>
+                `  :${found.line}:${found.column + 1}  ${found.destination}  -> ${resolvedLinkPath(root, report.rel, found.destination)}`,
+            )
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportBullets(
   reports: readonly FileReport[],
   checkpoints: Checkpoints,

package/src/gate/measures.ts

@@ -297,7 +297,7 @@ export const markdownBans: Measure = async (ctx) => {
     return {
       emissions: [output(frame.all)],
       failure:
-        'Markdown prose carries a banned character, word, or spelling. Rewrite the sentence, and reach for a code span only where the token is genuinely an identifier under discussion.',
+        'Markdown prose carries a banned character, word, or spelling, or a relative link resolves to nothing on disk. Rewrite the sentence or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
     }
   }
 

package/src/gate/stages.ts

@@ -296,6 +296,20 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Seed prose cites no toolkit CLI',
   },
+  {
+    // A hook, a workflow, or a husky script reaching one side of the seed or
+    // config boundary and not the other is a capability withheld with no
+    // recorded reason, per the criterion in .claude/ARCHITECTURE.md.
+    id: 'capability-seeding',
+    label: 'Capability seeding',
+    checks: [
+      script(
+        'check-capability-seeding.sh',
+        'A capability reaches one side of the seed or config boundary and not the other.',
+      ),
+    ],
+    success: 'Capability seeding clean',
+  },
   {
     // A stack entry naming a rule folder takes every rule in it, which is what
     // stops a new rule from needing a second edit to reach a target. The

package/src/markdown/gate.ts

@@ -1,9 +1,12 @@
+import type { LinkFinding } from '@/markdown/links'
 import type { BanFinding } from '@/markdown/scan'
 import type { StructureReport } from '@/markdown/structure'
 
 export interface GateInput {
   /** Every ban hit across every file measured, flattened. */
   readonly bans: readonly BanFinding[]
+  /** Every dead relative link across every file measured, flattened. */
+  readonly links: readonly LinkFinding[]
   /**
    * Every structural measure the run made, read by nothing here.
    *
@@ -18,11 +21,12 @@ export interface GateInput {
 /**
  * Whether the audit found something that should fail the caller.
  *
- * A banned character, word, or spelling is a fact rather than a threshold, so
- * it 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, word, or spelling 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.
  */
-export function isGating({ bans }: GateInput): boolean {
-  return bans.length > 0
+export function isGating({ bans, links }: GateInput): boolean {
+  return bans.length > 0 || links.length > 0
 }

package/src/markdown/links.ts

@@ -0,0 +1,73 @@
+import { type BodyLine, LINK, maskCodeSpans } from '@/markdown/scan'
+
+export interface LinkFinding {
+  readonly line: number
+  readonly column: number
+  readonly destination: string
+}
+
+const SCHEME = /^[a-z][a-z0-9+.-]*:/
+
+function isSkipped(destination: string): boolean {
+  return (
+    destination === '' ||
+    SCHEME.test(destination) ||
+    destination.startsWith('#') ||
+    destination.startsWith('/') ||
+    destination.includes('<')
+  )
+}
+
+/**
+ * The path half of a destination, decoded, or undefined on a malformed
+ * percent-encoding.
+ *
+ * `decodeURIComponent` throws on a stray `%` not followed by two hex digits,
+ * and a destination is text an author typed rather than a value this command
+ * controls, so a throw here is reachable from any markdown file in the
+ * corpus. Exported so `src/commands/markdown.ts` decodes a destination for
+ * display the same way this decodes one for resolution, rather than a second
+ * definition of the same fallible call.
+ */
+export function decodePath(destination: string): string | undefined {
+  try {
+    return decodeURIComponent(destination.split('#')[0] ?? '')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reports a relative link whose destination resolves to nothing on disk.
+ *
+ * `exists` stays injected rather than calling `existsSync` here, so a test
+ * asserts against a fake corpus rather than real paths on disk.
+ */
+export function findBrokenLinks(
+  lines: readonly BodyLine[],
+  exists: (path: string) => boolean,
+): LinkFinding[] {
+  const found: LinkFinding[] = []
+
+  for (const line of lines) {
+    if (line.fenced) continue
+    const text = maskCodeSpans(line.text)
+
+    for (const match of text.matchAll(LINK)) {
+      const open = match[0].indexOf('](')
+      const destination = match[0].slice(open + 2, -1)
+      if (isSkipped(destination)) continue
+
+      const path = decodePath(destination)
+      if (path !== undefined && exists(path)) continue
+
+      found.push({
+        line: line.number,
+        column: (match.index ?? 0) + open + 2,
+        destination,
+      })
+    }
+  }
+
+  return found
+}

package/src/markdown/scan.ts

@@ -20,7 +20,17 @@ const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
  * rewrite of the sentence can remove.
  */
 const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
-const LINK_DESTINATION = /\]\([^)]*\)/g
+
+/**
+ * A destination body, reaching one level of balanced parentheses so
+ * `file(1).md` is not truncated at its first close paren. A plain `[^)]*`
+ * ends the whole match there, which reads a legitimate destination as
+ * unterminated and, in `src/markdown/links.ts`, reports it broken. CommonMark
+ * permits an unescaped destination to carry matched parentheses, and one
+ * level is what every destination measured in this corpus needs.
+ */
+const LINK_TARGET = String.raw`(?:[^()]|\([^()]*\))*`
+const LINK_DESTINATION = new RegExp(String.raw`\]\(${LINK_TARGET}\)`, 'g')
 const AUTOLINK = /<[^>\s]+>/g
 
 /**
@@ -31,8 +41,14 @@ const AUTOLINK = /<[^>\s]+>/g
  * the destination. The narrower pattern still runs after this one, since a link
  * wrapped across two source lines puts its opening bracket on a line this one
  * never matches.
+ *
+ * Exported so `src/markdown/links.ts` matches a destination against the same
+ * pattern rather than a second definition of the same shape. Take it through
+ * `replace` or `matchAll` alone. Both clone the pattern before reading
+ * `lastIndex`, where `test` or `exec` would mutate the shared instance and
+ * leave the other module's next match starting from a nonzero offset.
  */
-const LINK = /\[([^\]]*)\]\([^)]*\)/g
+export const LINK = new RegExp(String.raw`\[([^\]]*)\]\(${LINK_TARGET}\)`, 'g')
 
 export interface BodyLine {
   readonly number: number

package/standards/markdown.md

@@ -101,6 +101,7 @@ When frontmatter carries a short `title` or `description` used for catalog displ
 
 - Use descriptive anchor text for links. Avoid `click here` or `read more`.
 - Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed. Never repeat the path verbatim as the label.
+- A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination carrying a template placeholder in angle brackets, such as `<slug>` or `<name>`, reads as an illustration rather than a literal path and is exempt.
 
 ## Examples
 

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# Reminds a worker session of the pull-request announcement it owes and logs
+# the creation as a denominator for the miss rate `claude-worker` cannot
+# measure on its own. Follows path-form.sh's precedent: a PostToolUse hook
+# returning hookSpecificOutput.additionalContext is the shipped route back
+# into a session's own turn.
+#
+# The hook cannot know whether the announcement went out, only that a pull
+# request now exists to announce. It states the obligation and counts the
+# creation, and claims nothing about the send.
+
+# 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
+}
+
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+case "$command" in
+*"gh pr create"*) ;;
+*) exit 0 ;;
+esac
+
+# gh pr create prints the new pull request's URL to stdout on success, so
+# matching it is what tells a creation apart from a failed or refused call.
+stdout=$(printf '%s' "$input" | jq -r '.tool_response.stdout // empty')
+url=$(printf '%s' "$stdout" | grep -Eo 'https://github\.com/[^[:space:]]+/pull/[0-9]+' | tail -1)
+[ -n "$url" ] || exit 0
+
+# CLAUDE_PROJECT_DIR is the session's own worktree rather than the main root,
+# so a worker building in a linked worktree would log into a folder that dies
+# with the worktree. The log is a denominator across a wave rather than a
+# per-session record, so strip back to the main root the way tasks-index.sh
+# and memory-index.sh already derive theirs, off a path suffix.
+root="${CLAUDE_PROJECT_DIR:-.}"
+case "$root" in
+*/.claude/worktrees/*) root="${root%/.claude/worktrees/*}" ;;
+esac
+# The log is scratch, so it follows the scratch folder to whichever record root
+# the project carries rather than creating a second one beside it.
+if [ -d "$root/.canon" ]; then
+  log_dir="$root/.canon/tmp/pr-create-log"
+else
+  log_dir="$root/.claude/.tmp/pr-create-log"
+fi
+mkdir -p "$log_dir"
+session=$(printf '%s' "$input" | jq -r '.session_id // "unknown"')
+printf -- '- %s session=%s pr=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session" "$url" >>"$log_dir/log.md"
+
+msg="Pull request $url just opened. If this session holds a worker's channel obligation, announce it to the controller now, per claude-worker."
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

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

@@ -41,6 +41,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-form.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pr-create-log.sh"
+          }
+        ]
       }
     ]
   }