@erclx/canon 5.73.0 → 5.75.0

package/src/gate/stages.ts

@@ -8,7 +8,6 @@ import {
 import {
   canonicalRecords,
   auditSet,
-  captureStamps,
   clientCommandCitations,
   designProse,
   documentCeiling,
@@ -45,6 +44,12 @@ export type Check =
   | {
       readonly kind: 'command'
       readonly argv: readonly string[]
+      /**
+       * Builds the argv from the changed set when scoping is on. `argv` runs
+       * where it is off, so `--all` and every widening fallback keep the full
+       * command.
+       */
+      readonly changedArgv?: (changed: readonly string[]) => readonly string[]
       readonly failure: string
     }
   /** This checkout's own CLI, so a worktree gate never reads the main tree. */
@@ -92,33 +97,36 @@ export interface Stage {
 }
 
 /**
- * Corpora a `src/` test asserts over from outside `src/`. Nothing compares
- * this list to the tests reading those paths, so a test that starts reading a
- * new corpus joins it here in the same change, or a branch touching only that
- * corpus skips the Tests stage. The first four are directory prefixes because
- * their tests walk the tree whole, which is what reaches a rule or a skill a
- * branch adds rather than edits.
+ * Files a scoped run hands to `vitest related`, which follows imports from
+ * them to the tests that reach them. A corpus a test reads from disk is not
+ * among them, so a Markdown-only push runs no tests locally and CI's full run
+ * is what catches a broken corpus reader.
  */
-export const TEST_CORPORA_PATTERNS = [
-  '^claude/skills/',
-  '^governance/rules/',
-  '^\\.claude/hooks/',
-  '^tooling/claude/seeds/\\.claude/hooks/',
-  '^tooling/base/reference\\.md$',
-  '^tooling/web/configs/scripts/worktree-port\\.sh$',
-]
+const RELATED_SOURCES = /\.tsx?$|^commitlint\.config\.js$/
+
+/** Files every test depends on without importing, so no related run sees them. */
+const FULL_SUITE_TRIGGERS =
+  /^vitest\.(config|setup|global-setup)\.ts$|^tsconfig\.json$|^package\.json$/
 
 const TESTS_SCOPE = new RegExp(
-  [
-    '^src/',
-    '^vitest\\.config\\.ts$',
-    '^tsconfig\\.json$',
-    '^package\\.json$',
-    '^commitlint\\.config\\.(js|test\\.ts)$',
-    ...TEST_CORPORA_PATTERNS,
-  ].join('|'),
+  `${RELATED_SOURCES.source}|${FULL_SUITE_TRIGGERS.source}`,
 )
 
+const FULL_SUITE = ['bun', 'run', 'test']
+
+function relatedTests(changed: readonly string[]): readonly string[] {
+  if (changed.some((file) => FULL_SUITE_TRIGGERS.test(file))) return FULL_SUITE
+  return [
+    'bun',
+    '--bun',
+    'vitest',
+    'related',
+    '--run',
+    '--passWithNoTests',
+    ...changed.filter((file) => RELATED_SOURCES.test(file)),
+  ]
+}
+
 /**
  * Every stage the gate runs, in the order it runs them.
  *
@@ -182,28 +190,6 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Consumed copies clean',
   },
-  {
-    // Only the markup is asserted for drift. The image beside it is a chromium
-    // render whose bytes move with the browser version, so a drift check over it
-    // would fail on a machine whose chromium differs rather than on a stale
-    // count. The stamp measure below is what covers the image instead.
-    //
-    // The stage covers every frame under `assets/captures/` and keeps the
-    // narrower name, because the label is spelled across the context entries and
-    // the CI table and renaming it buys nothing the pathspec below does not
-    // already say.
-    id: 'hero',
-    label: 'Hero',
-    checks: [
-      {
-        kind: 'command',
-        argv: ['bun', 'scripts/core/regen-hero.ts', '--check'],
-        failure: 'Hero regen health check failed',
-      },
-      { kind: 'measure', measure: captureStamps },
-    ],
-    success: 'Hero clean',
-  },
   {
     // `canon/DESIGN.md`, the web stylesheet, and the tab icon are written
     // from `src/design/tokens.ts`, and none is edited by hand. Three
@@ -590,14 +576,17 @@ export const STAGES: readonly Stage[] = [
     id: 'tests',
     label: 'Tests',
     scope: TESTS_SCOPE,
-    skipped: 'Skipped, no TypeScript or asserted-corpus changes',
+    skipped: 'Skipped, no TypeScript or test config changes',
     // Concurrent suites from a wave of worktrees starve each other's spawn
     // and browser tests past their timeouts, so the box runs one at a time.
+    // A related run can still reach a spawn or browser test, so it holds the
+    // lock too.
     lock: 'tests',
     checks: [
       {
         kind: 'command',
-        argv: ['bun', 'run', 'test'],
+        argv: FULL_SUITE,
+        changedArgv: relatedTests,
         failure: 'Tests failed',
       },
     ],

package/src/gov/audit.ts

@@ -72,6 +72,13 @@ export const CORE_FOLDERS: readonly string[] = [
 
 const SHIPPED_RULES = join('governance', 'rules')
 const LEDGERS = join('governance', 'ledger')
+const TARGET_RULES = join('.claude', 'rules', 'project')
+
+/**
+ * Where a target keeps the ledgers behind its own rules. It sits outside
+ * `.claude/rules/`, where every `.md` loads as a rule, and nothing loads it.
+ */
+export const TARGET_RULE_LEDGERS = join('canon', 'ledger', 'rules')
 
 /** Both corpora authored here, read when the tree is a canon checkout. */
 const CANON_CORPUS: readonly string[] = [
@@ -83,7 +90,7 @@ const CANON_CORPUS: readonly string[] = [
  * What a target authors. `.claude/rules/canon/` is installed from the toolkit
  * and fixed at its source, so a finding there is one the target cannot act on.
  */
-const TARGET_CORPUS: readonly string[] = [join('.claude', 'rules', 'project')]
+const TARGET_CORPUS: readonly string[] = [TARGET_RULES]
 
 export interface ShapeFinding {
   readonly limit: RuleLimit
@@ -135,10 +142,18 @@ export type RuleAuditRefusal = 'no-rules' | 'no-path' | 'outside-root'
 export type RuleAuditReport =
   | {
       readonly kind: 'measured'
-      /** `canon` reads both authored corpora and ledgers, `target` neither. */
+      /**
+       * `canon` reads both authored corpora and the toolkit's ledgers,
+       * `target` its project rules and any ledger the project wrote.
+       */
       readonly scope: 'canon' | 'target'
       readonly corpus: readonly string[]
       readonly rules: readonly RuleReading[]
+      /**
+       * Target ledgers whose rule is gone, read on a whole-corpus read alone,
+       * since a named path scopes the read to the files named.
+       */
+      readonly orphans: readonly string[]
     }
   | {
       readonly kind: 'unreadable'
@@ -336,7 +351,18 @@ export function compareLedger(
 function ledgerFor(
   file: string,
   touched: ReadonlySet<string>,
+  scope: 'canon' | 'target',
 ): { path: string; owed: boolean } | undefined {
+  // A project has no practice-folder list to owe a ledger against, so its
+  // ledger is checked where it exists and never owed.
+  if (scope === 'target') {
+    const prefix = `${TARGET_RULES}${sep}`
+    if (!file.startsWith(prefix)) return undefined
+    return {
+      path: join(TARGET_RULE_LEDGERS, file.slice(prefix.length)),
+      owed: false,
+    }
+  }
   const prefix = `${SHIPPED_RULES}${sep}`
   if (!file.startsWith(prefix)) return undefined
   const rest = file.slice(prefix.length)
@@ -352,8 +378,9 @@ async function readLedger(
   file: string,
   groups: readonly HeadingCount[],
   touched: ReadonlySet<string>,
+  scope: 'canon' | 'target',
 ): Promise<LedgerReading> {
-  const ledger = ledgerFor(file, touched)
+  const ledger = ledgerFor(file, touched, scope)
   if (ledger === undefined) return { status: 'not-required' }
   const { path } = ledger
 
@@ -373,14 +400,29 @@ async function readLedger(
   }
 }
 
+/**
+ * Target ledgers with no rule at the matching `.claude/rules/project/` path,
+ * so a rule moved or renamed away from its ledger is reported rather than
+ * dropping its check silently.
+ */
+function findOrphanLedgers(root: string): string[] {
+  const dir = resolve(root, TARGET_RULE_LEDGERS)
+  if (!existsSync(dir)) return []
+  return listRuleFiles(dir)
+    .map((abs) => relative(dir, abs))
+    .filter((rest) => !existsSync(resolve(root, TARGET_RULES, rest)))
+    .map((rest) => join(TARGET_RULE_LEDGERS, rest))
+}
+
 /**
  * Measures every rule this tree authors, or the files named.
  *
  * A tree holding `governance/rules/` is a canon checkout, read across both
  * authored corpora with a ledger asked of each outside-practice rule and of
  * each core rule in `touched`, and checked for any core rule carrying one.
- * Any other tree is a target, read at `.claude/rules/project/` alone with no
- * ledger asked, since ledgers never ship.
+ * Any other tree is a target, read at `.claude/rules/project/` alone, with
+ * each rule's ledger under `canon/ledger/rules/` checked where one exists and
+ * none owed, since the toolkit's ledgers never ship.
  *
  * `touched` holds paths relative to the root, and leaving it out reads no core
  * rule as touched.
@@ -457,11 +499,14 @@ export async function readRuleAudit(
     rules.push({
       file,
       ...shape,
-      ledger: await readLedger(root, file, groups, touched),
+      ledger: await readLedger(root, file, groups, touched, scope),
     })
   }
 
-  return { kind: 'measured', scope, corpus, rules }
+  const orphans =
+    scope === 'target' && paths.length === 0 ? findOrphanLedgers(root) : []
+
+  return { kind: 'measured', scope, corpus, rules, orphans }
 }
 
 export function hasFinding(reading: RuleReading): boolean {
@@ -487,12 +532,13 @@ export function auditExit(
     readonly exempt?: readonly string[]
   },
 ): number {
+  const counts = (file: string) =>
+    !options.gate ||
+    (options.gated.some((prefix) => file.startsWith(prefix)) &&
+      !options.exempt?.includes(file))
   const failing = report.rules.filter(
-    (reading) =>
-      hasFinding(reading) &&
-      (!options.gate ||
-        (options.gated.some((prefix) => reading.file.startsWith(prefix)) &&
-          !options.exempt?.includes(reading.file))),
+    (reading) => hasFinding(reading) && counts(reading.file),
   )
-  return failing.length > 0 ? 2 : 0
+  const orphaned = report.orphans.filter(counts)
+  return failing.length + orphaned.length > 0 ? 2 : 0
 }

package/src/markdown/scope.ts

@@ -158,6 +158,7 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/context-fold/references/unusable-baseline.md',
   'claude/skills/create-rule/REQUIREMENT.md',
   'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-rule/references/ledger.md',
   'claude/skills/create-rule/references/rule.md',
   'claude/skills/create-skill/REQUIREMENT.md',
   'claude/skills/create-skill/SKILL.md',
@@ -280,6 +281,9 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/pr-evidence/REQUIREMENT.md',
   'claude/skills/pr-evidence/SKILL.md',
   'claude/skills/pr-evidence/references/evidence.md',
+  'claude/skills/proposal-critique/REQUIREMENT.md',
+  'claude/skills/proposal-critique/SKILL.md',
+  'claude/skills/proposal-critique/references/adopted.md',
   'claude/skills/review-address/REQUIREMENT.md',
   'claude/skills/review-address/SKILL.md',
   'claude/skills/review-address/references/post-review-findings.md',

package/src/migrate/session-defaults.ts

@@ -1,7 +1,8 @@
 /**
  * Adds the session defaults the seeded `.claude/settings.json` carries to a
- * target that was seeded before them: the subagent deny, the memory default, and
- * the merge deny entries.
+ * target that was seeded before them: the subagent deny, the memory default,
+ * the merge deny entries, and the plan guard's PreToolUse wiring where the
+ * project holds the guard script.
  *
  * `canon claude init` copies a seed only when the file is absent, so a target
  * holding its own settings never sees a later seed change. This verb adds each
@@ -28,6 +29,26 @@ export const MERGE_DENIED: readonly string[] = [
   'Bash(gh pr merge:*)',
 ]
 
+/** The command the seed wires, as the seeded settings spell it. */
+export const PLAN_GUARD_COMMAND =
+  '"$CLAUDE_PROJECT_DIR"/.claude/hooks/plan-guard.sh'
+
+const PLAN_GUARD_SCRIPT = 'plan-guard.sh'
+
+/**
+ * Each tool the guard acts on, beside the seeded matcher that carries it. A
+ * guard wired by hand under any matcher covering the tool counts as wired.
+ */
+const PLAN_GUARD_WIRING: readonly { tool: string; matcher: string }[] = [
+  { tool: 'Bash', matcher: 'Bash' },
+  { tool: 'Write', matcher: 'Write|Edit' },
+]
+
+export interface SessionDefaultsOptions {
+  /** True when the project holds `.claude/hooks/plan-guard.sh` to wire. */
+  readonly planGuard?: boolean
+}
+
 export interface SessionDefaultsPlan {
   readonly keys: readonly SettingsKey[]
   readonly next: SettingsRecord
@@ -66,6 +87,7 @@ function isRecord(value: unknown): value is SettingsRecord {
  */
 export function planSessionDefaults(
   current: SettingsRecord,
+  { planGuard = false }: SessionDefaultsOptions = {},
 ): SessionDefaultsPlan {
   const next: SettingsRecord = { ...current }
   const permissions = isRecord(current.permissions) ? current.permissions : {}
@@ -81,9 +103,16 @@ export function planSessionDefaults(
   const memoryAbsent = !('autoMemoryEnabled' in current)
   if (memoryAbsent) next.autoMemoryEnabled = false
 
+  const preToolUse = planGuard ? wirePlanGuard(current.hooks) : undefined
+  if (preToolUse !== undefined) {
+    const hooks = isRecord(current.hooks) ? current.hooks : {}
+    next.hooks = { ...hooks, PreToolUse: preToolUse }
+  }
+
   const keys: SettingsKey[] = [
     { label: 'permissions.deny', changed: missing.length > 0 },
     { label: 'autoMemoryEnabled', changed: memoryAbsent },
+    { label: 'hooks.PreToolUse', changed: preToolUse !== undefined },
   ]
   return {
     keys,
@@ -97,10 +126,72 @@ export function planSessionDefaults(
   }
 }
 
+/**
+ * Claude Code reads an absent, empty, or `*` matcher as every tool, one of
+ * only name characters as exact names split on `|` or `,`, and any other as
+ * an unanchored regular expression, per its hooks reference.
+ */
+function matcherCovers(matcher: unknown, tool: string): boolean {
+  if (matcher === undefined || matcher === '' || matcher === '*') return true
+  if (typeof matcher !== 'string') return false
+  if (/^[\w\s,|-]+$/.test(matcher)) {
+    return matcher.split(/[|,]/).some((name) => name.trim() === tool)
+  }
+  try {
+    return new RegExp(matcher).test(tool)
+  } catch {
+    return false
+  }
+}
+
+function runsPlanGuard(group: unknown, tool: string): boolean {
+  if (!isRecord(group) || !Array.isArray(group.hooks)) return false
+  if (!matcherCovers(group.matcher, tool)) return false
+  return group.hooks.some(
+    (hook) =>
+      isRecord(hook) &&
+      typeof hook.command === 'string' &&
+      hook.command.includes(PLAN_GUARD_SCRIPT),
+  )
+}
+
+/**
+ * Returns the PreToolUse list with the guard appended to each seeded matcher
+ * lacking it, or undefined when every tool already runs it. An existing group
+ * under the seeded matcher takes the entry, keeping its own hooks first.
+ */
+function wirePlanGuard(hooks: unknown): unknown[] | undefined {
+  const current =
+    isRecord(hooks) && Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  const lacking = PLAN_GUARD_WIRING.filter(
+    ({ tool }) => !current.some((group) => runsPlanGuard(group, tool)),
+  )
+  if (lacking.length === 0) return undefined
+
+  const entry = { type: 'command', command: PLAN_GUARD_COMMAND }
+  const next = [...current]
+  for (const { matcher } of lacking) {
+    const at = next.findIndex(
+      (group) =>
+        isRecord(group) &&
+        group.matcher === matcher &&
+        Array.isArray(group.hooks),
+    )
+    const group = next[at]
+    if (isRecord(group) && Array.isArray(group.hooks)) {
+      next[at] = { ...group, hooks: [...group.hooks, entry] }
+    } else {
+      next.push({ matcher, hooks: [entry] })
+    }
+  }
+  return next
+}
+
 /**
  * Refuses rather than plans whenever a write could replace something the
  * person owns: the toolkit's own settings, a file `JSON.parse` cannot read,
- * or a `permissions` or `deny` value of an unexpected shape.
+ * or a `permissions`, `deny`, `hooks`, or `PreToolUse` value of an
+ * unexpected shape.
  */
 export async function readSessionDefaults(
   root: string,
@@ -138,11 +229,30 @@ export async function readSessionDefaults(
     }
   }
 
+  const planGuard = existsSync(
+    join(root, '.claude', 'hooks', PLAN_GUARD_SCRIPT),
+  )
+  const { hooks } = read.value
+  if (planGuard && hooks !== undefined && !isRecord(hooks)) {
+    return { kind: 'refused', reason: `${path}: hooks is not an object` }
+  }
+  if (
+    planGuard &&
+    isRecord(hooks) &&
+    hooks.PreToolUse !== undefined &&
+    !Array.isArray(hooks.PreToolUse)
+  ) {
+    return {
+      kind: 'refused',
+      reason: `${path}: hooks.PreToolUse is not a list`,
+    }
+  }
+
   return {
     kind: 'planned',
     path,
     indent: read.indent,
-    plan: planSessionDefaults(read.value),
+    plan: planSessionDefaults(read.value, { planGuard }),
   }
 }
 

package/src/pr/checks.ts

@@ -1,4 +1,8 @@
-import { type ChecksState, type RawCheck, rollup } from '@/targets/pulls'
+import {
+  type ChecksState,
+  type RawCheck,
+  rollupRequired,
+} from '@/targets/pulls'
 
 /** One row of `repos/{owner}/{repo}/commits/<sha>/check-runs`. */
 export interface RawCheckRun {
@@ -9,6 +13,12 @@ export interface RawCheckRun {
   readonly id?: number
 }
 
+/** One row of `repos/{owner}/{repo}/commits/<sha>/status`, newest per context already. */
+export interface RawStatus {
+  readonly context?: string
+  readonly state?: string
+}
+
 /** What that endpoint returns, count and rows apart. */
 export interface CheckRunListing {
   readonly total_count?: number
@@ -27,6 +37,41 @@ export interface ChecksReading {
   readonly reported: number
   /** Runs `matched` carried for a check name this reading already kept a newer run for. */
   readonly collapsed: number
+  /**
+   * Failing checks outside the required set, present only when a required set
+   * was read, so a reading over every check keeps its old shape.
+   */
+  readonly advisory?: readonly string[]
+}
+
+/**
+ * Reads the check names a base branch's rules require, from
+ * `repos/{owner}/{repo}/rules/branches/<base>`.
+ *
+ * Undefined when the answer is not a rule list, which a repository without
+ * rulesets or a refused read returns, so the caller falls back to every check.
+ * Classic branch protection is not read, and falls back the same way.
+ */
+export function requiredChecks(
+  rules: unknown,
+): ReadonlySet<string> | undefined {
+  if (!Array.isArray(rules)) return undefined
+
+  const names = new Set<string>()
+  for (const rule of rules as readonly RequiredRule[]) {
+    if (rule?.type !== 'required_status_checks') continue
+    for (const check of rule.parameters?.required_status_checks ?? []) {
+      if (typeof check.context === 'string') names.add(check.context)
+    }
+  }
+  return names
+}
+
+interface RequiredRule {
+  readonly type?: string
+  readonly parameters?: {
+    readonly required_status_checks?: readonly { readonly context?: unknown }[]
+  }
 }
 
 export interface ConflictedReading extends ChecksReading {
@@ -68,6 +113,7 @@ export function withMergeState(
  */
 function adapt(run: RawCheckRun): RawCheck {
   return {
+    ...(run.name !== undefined && { name: run.name }),
     ...(run.status !== undefined && { status: run.status.toUpperCase() }),
     ...(run.conclusion !== undefined &&
       run.conclusion !== null && {
@@ -125,10 +171,22 @@ function newestPerCheck(runs: readonly RawCheckRun[]): {
  * rolls up from `newestPerCheck`'s kept rows rather than from `matched`
  * directly, so a stale failing run left behind by a rerun no longer outvotes
  * the passing run beside it.
+ *
+ * A required set narrows only that last rollup. The foreign and partial
+ * listing guards still read every run, since either says the set in hand is
+ * incomplete whichever checks gate.
+ *
+ * A ruleset can require a commit status, which the check-run listing never
+ * carries, so the statuses join the rollup by `context` once a non-empty
+ * required set was read. An unread or empty set keeps them out, since the
+ * every-check fallback is the reading these verbs gave before rules were read
+ * and it saw no status.
  */
 export function collapseChecks(
   tip: string,
   listing: CheckRunListing,
+  required?: ReadonlySet<string>,
+  statuses: readonly RawStatus[] = [],
 ): ChecksReading {
   const runs = listing.check_runs ?? []
   const matched = runs.filter((run) => run.head_sha === tip)
@@ -139,6 +197,7 @@ export function collapseChecks(
     foreign: runs.length - matched.length,
     reported: listing.total_count ?? runs.length,
     collapsed,
+    ...(required !== undefined && { advisory: [] }),
   }
 
   if (reading.foreign > 0) return { ...reading, state: 'pending' }
@@ -149,7 +208,20 @@ export function collapseChecks(
   // sitting outside of, which is the false green keyed on a sha alone.
   if (reading.reported > runs.length) return { ...reading, state: 'pending' }
 
-  if (matched.length === 0) return { ...reading, state: 'pending' }
+  const statusRows: RawCheck[] =
+    required === undefined || required.size === 0
+      ? []
+      : statuses.map((status) => ({
+          ...(status.context !== undefined && { name: status.context }),
+          state: (status.state ?? '').toUpperCase(),
+        }))
+  const rows = [...kept.map(adapt), ...statusRows]
+  if (rows.length === 0) return { ...reading, state: 'pending' }
 
-  return { ...reading, state: rollup(kept.map(adapt)) ?? 'pending' }
+  const { state, advisory } = rollupRequired(rows, required)
+  return {
+    ...reading,
+    state: state ?? 'pending',
+    ...(required !== undefined && { advisory }),
+  }
 }

package/src/pr/evidence.ts

@@ -25,6 +25,12 @@ const REEL_PREFIX = '**Reel** filmed at'
 const REEL_LINE =
   /^\*\*Reel\*\* filmed at `([0-9a-f]{7,40})`:<br><img src="([^"]+)"/
 
+/** How the line naming why no local address was posted opens. */
+const LOCAL_SKIP_PREFIX = '**No local preview:**'
+
+/** How the line naming why no reel was filmed opens. */
+const REEL_SKIP_PREFIX = '**No reel:**'
+
 /** The width a reel is filmed at, which it asks for in the comment. */
 const REEL_WIDTH = 960
 
@@ -198,6 +204,15 @@ function escapeCell(text: string): string {
     .replaceAll('|', '&#124;')
 }
 
+function unescapeCell(text: string): string {
+  return text
+    .replaceAll('&#124;', '|')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&')
+}
+
 function evidenceImage(url: string, alt: string, width?: number): string {
   const shown = Math.min(width ?? IMAGE_WIDTH, IMAGE_WIDTH)
   return `<img src="${url}" width="${shown}" alt="${alt}">`
@@ -449,6 +464,18 @@ function reelLine(reel: EvidenceReel): string {
   return `${REEL_PREFIX} \`${head}\`:<br><img src="${escapeCell(reel.link)}" width="${REEL_WIDTH}" alt="reel filmed at ${head}">`
 }
 
+/** Why a render carries no local address or no reel, each a reason code and any one-line message the caller joined to it. */
+export interface EvidenceSkips {
+  readonly local?: string
+  readonly reel?: string
+}
+
+/** A skip line, or nothing for an empty reason. A reason is folded onto one line, since a line break would end the address region early. */
+function skipLines(prefix: string, reason: string | undefined): string[] {
+  const text = reason?.replace(/\s+/g, ' ').trim() ?? ''
+  return text === '' ? [] : [`${prefix} ${escapeCell(text)}`, '']
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
@@ -480,6 +507,10 @@ export function evidenceMarker(head: string): string {
  *
  * A reel sits on its own line under the addresses, labeled with the head it
  * was filmed at, so a reel carried past a later push never reads as current.
+ *
+ * A skip names why the local address or the reel is missing, on its own line
+ * where that address or reel would sit. Each is dropped whenever its address
+ * or reel renders, carried or passed, so a skip never outlives its cause.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -490,6 +521,7 @@ export function renderEvidenceBody(
   checklist?: string,
   local?: string,
   reel?: EvidenceReel,
+  skips: EvidenceSkips = {},
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -499,7 +531,10 @@ export function renderEvidenceBody(
     EVIDENCE_HEADING,
     '',
     ...(segments.length === 0 ? [] : [segments.join(ADDRESS_SEPARATOR), '']),
-    ...(reel === undefined ? [] : [reelLine(reel), '']),
+    ...(local === undefined ? skipLines(LOCAL_SKIP_PREFIX, skips.local) : []),
+    ...(reel === undefined
+      ? skipLines(REEL_SKIP_PREFIX, skips.reel)
+      : [reelLine(reel), '']),
   ]
   const closing =
     checklist === undefined
@@ -756,6 +791,32 @@ export function findEvidenceReel(
   return undefined
 }
 
+/**
+ * The skips the marked comment already carries, read from the address region
+ * only, so a line quoted in a checklist is never taken for one. A re-render
+ * passing no skip carries these forward the way it carries an address.
+ */
+export function findEvidenceSkips(
+  comments: readonly EvidenceComment[],
+): EvidenceSkips {
+  const marked = findMarked(comments)
+  if (marked === undefined) return {}
+  let local: string | undefined
+  let reel: string | undefined
+  for (const raw of marked.body.split('\n')) {
+    const line = raw.trim()
+    if (REGION_ENDS.some((end) => line.startsWith(end))) break
+    const ownSkip = readSegment(line, LOCAL_SKIP_PREFIX)
+    const reelSkip = readSegment(line, REEL_SKIP_PREFIX)
+    if (ownSkip !== undefined) local ??= unescapeCell(ownSkip)
+    if (reelSkip !== undefined) reel ??= unescapeCell(reelSkip)
+  }
+  return {
+    ...(local !== undefined && { local }),
+    ...(reel !== undefined && { reel }),
+  }
+}
+
 /**
  * The reel a render embeds: a passed link, filmed at this head, replaces
  * whatever the comment carries, and with none passed the posted reel carries