@erclx/canon 5.32.0 → 5.34.0

package/src/gov/list.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
+import { loadDetectEntries, staleDetectKeys } from '@/gov/detect'
 import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
 import {
   expandStackEntry,
@@ -15,17 +16,26 @@ export interface StackEntry {
   readonly rules: string[]
 }
 
+/** The evidence `governance/detect.toml` records for one opt-in rule. */
+export interface RuleDetect {
+  readonly deps: readonly string[]
+  readonly files: readonly string[]
+}
+
 export interface RuleEntry {
   readonly name: string
   readonly domain: string
   readonly description: string
   readonly paths: string[] | null
+  readonly detect: RuleDetect | null
 }
 
 export interface GovCatalog {
   readonly stacks: StackEntry[]
   readonly rules: RuleEntry[]
   readonly unreferenced: string[]
+  /** `detect.toml` keys naming no live rule, which the gate fails on. */
+  readonly staleDetect: string[]
 }
 
 /**
@@ -64,24 +74,34 @@ export function buildStackEntries(root: string): StackEntry[] {
 
 /**
  * Reads the catalog straight off the source tree. A rule's domain is the
- * subdirectory it sits in, which is the band grouping install preserves.
+ * subdirectory it sits in, which is the band grouping install preserves, and
+ * its `detect` entry is the evidence that proposes it, null for a rule
+ * `detect.toml` does not name.
  */
 export function buildRuleEntries(root: string): RuleEntry[] {
   const rulesRoot = rulesSourceDir(root)
+  const detect = new Map(
+    loadDetectEntries(root).map((entry) => [
+      entry.rule,
+      { deps: entry.deps, files: entry.files },
+    ]),
+  )
 
   return listRuleSourcePaths(root).map((rel) => {
     const frontmatter = parseFrontmatter(
       readFileSync(join(rulesRoot, rel), 'utf8'),
     )
     const paths = frontmatter?.fields.paths
+    const name = basename(rel, '.md')
 
     return {
-      name: basename(rel, '.md'),
+      name,
       domain: rel.includes('/') ? rel.slice(0, rel.indexOf('/')) : '',
       description: readField(frontmatter, 'description') ?? '',
       paths: Array.isArray(paths)
         ? paths.filter((entry): entry is string => typeof entry === 'string')
         : null,
+      detect: detect.get(name) ?? null,
     }
   })
 }
@@ -91,6 +111,7 @@ export function buildGovCatalog(root: string): GovCatalog {
     stacks: buildStackEntries(root),
     rules: buildRuleEntries(root),
     unreferenced: unreferencedRules(root),
+    staleDetect: staleDetectKeys(root),
   }
 }
 

package/src/gov/stacks.ts

@@ -79,7 +79,7 @@ export function loadGovStack(
  * shape rather than two the caller has to tell apart.
  *
  * The directory wins over a rule file of the same name. They cannot collide
- * while `standards/rule.md` requires a numeric prefix on a rule slug, since a
+ * while `claude/skills/create-rule/references/rule.md` requires a numeric prefix on a rule slug, since a
  * band folder carries none.
  */
 export function expandStackEntry(root: string, entry: string): string[] {
@@ -207,3 +207,12 @@ export function mergeExtraRules(
 
   return merged
 }
+
+/**
+ * Resolves `--add` names with no stack under them. It runs the same merge as
+ * the stack path against an empty list, so an add with no stack and a layered one
+ * split and dedupe their names identically.
+ */
+export function resolveExtraRules(add: string): string[] {
+  return mergeExtraRules([], add)
+}

package/src/hooks/post-merge.ts

@@ -163,7 +163,7 @@ function archiveLines(
   }
   return (
     `\n📋 Task not archived for #${number}: ${text(fields, 'message') ?? reason}\n` +
-    'Run /task-board to resolve it by hand.\n\n'
+    `Run /task-complete archive #${number} to resolve it by hand.\n\n`
   )
 }
 

package/src/labels/apply.ts

@@ -0,0 +1,39 @@
+/** What a label apply decided to do, before any write. */
+export interface LabelDiff {
+  /** Earned labels the pull request lacks and the remote carries, so addable. */
+  readonly toAdd: readonly string[]
+  /** Every earned label the pull request lacks, whether or not it is addable. */
+  readonly owed: readonly string[]
+  /** Owed labels the remote does not carry, which are reported and never created. */
+  readonly missingOnRemote: readonly string[]
+}
+
+/**
+ * Diffs what a branch earns against what its pull request already carries and
+ * what the remote can attach.
+ *
+ * The diff only adds. A label on the pull request that the map does not earn
+ * is a person's decision and never appears here, so nothing in the result can
+ * be turned into a removal. Order follows `earned`, which the map declares, so
+ * two runs over one branch produce one list.
+ *
+ * A label the remote lacks is separated from the addable set rather than
+ * dropped, because the REST add endpoint creates any label it is handed and
+ * that write to the repository settings is not the map's call.
+ */
+export function diffLabels(
+  earned: readonly string[],
+  present: readonly string[],
+  remote: readonly string[],
+): LabelDiff {
+  const has = new Set(present)
+  const carried = new Set(remote)
+
+  const owed = earned.filter((label) => !has.has(label))
+
+  return {
+    owed,
+    toAdd: owed.filter((label) => carried.has(label)),
+    missingOnRemote: owed.filter((label) => !carried.has(label)),
+  }
+}

package/src/labels/format.ts

@@ -1,5 +1,5 @@
 /**
- * Which rule in `standards/pr.md`'s `## Title` section a title breaks.
+ * Which rule in `claude/skills/git-pr/references/pr.md`'s `## Title` section a title breaks.
  *
  * `structure` stands alone rather than beside the other three, because a
  * title failing the shape match has no parsed `<type>`, `<scope>`, or
@@ -28,9 +28,9 @@ const LEADING_LETTERS = /^[A-Za-z]+/
 
 /**
  * Grades a pull request title, or a commit subject sharing the same form,
- * against `standards/pr.md`'s structure, casing, and length rules.
+ * against `claude/skills/git-pr/references/pr.md`'s structure, casing, and length rules.
  *
- * Does not check `<type>` against `standards/commit.md`'s fixed enum.
+ * Does not check `<type>` against `claude/skills/git-commit/references/commit.md`'s fixed enum.
  * `pr.md`'s own `## Title` section states format, casing, and length only,
  * and names no type list of its own to check against.
  */

package/src/labels/phase.ts

@@ -3,7 +3,7 @@ import { RECORD_ENTRIES, RECORD_ROOTS } from '@/roots/record'
 import type { RecordRoot } from '@/roots/record'
 
 /**
- * The two version namespaces `standards/versioning.md` keeps apart, and why a
+ * The two version namespaces `claude/skills/git-commit/references/versioning.md` keeps apart, and why a
  * pull request cannot be sorted between them by pattern alone.
  *
  * A phase label (`v68.5`) and a semver reference (`v3.44`) both match
@@ -186,7 +186,7 @@ const RELEASE_TITLE_PREFIX = 'chore(main): release '
  * phase label past this check. Together they name release-please's own act of
  * opening the pull request, which nothing else on the remote can perform.
  */
-function isReleasePullRequest(input: PhaseScanInput): boolean {
+export function isReleasePullRequest(input: PhaseScanInput): boolean {
   return (
     input.headRefName.startsWith(RELEASE_HEAD_PREFIX) &&
     input.title.startsWith(RELEASE_TITLE_PREFIX)
@@ -265,7 +265,7 @@ function sessionLinks(text: string): string[] {
  * The split runs on the pull request rather than on each token. A release
  * pull request's tokens are read as the semver references its generated body
  * legitimately carries, and every other pull request's tokens are read as
- * leaked phase labels, which is what `standards/versioning.md` names the
+ * leaked phase labels, which is what `claude/skills/git-commit/references/versioning.md` names the
  * defect this exists to catch.
  *
  * A release pull request reports no board reference either, and the ground is

package/src/labels/sections.ts

@@ -0,0 +1,43 @@
+import { linesOutsideFences } from '@/markdown/scan'
+
+/**
+ * The closed list of section headings a pull request body may carry, in the
+ * sentence case `claude/skills/git-pr/references/pr.md` states.
+ */
+const ALLOWED_HEADINGS: readonly string[] = [
+  '## Summary',
+  '## Key changes',
+  '## Technical context',
+  '## Testing',
+  '## For the reviewer',
+]
+
+const REQUIRED_HEADINGS: readonly string[] = ['## Summary', '## Key changes']
+
+const H2 = /^##\s/
+
+export interface SectionsCheck {
+  /** Level-two headings the closed list does not hold, as written. */
+  readonly outside: readonly string[]
+  /** Required headings the body never carries. */
+  readonly missing: readonly string[]
+}
+
+/**
+ * Grades the level-two headings of a pull request body against the closed list.
+ *
+ * The comparison is exact, so `## Key Changes` fails. `canon pr key-changes`
+ * reads its section case-insensitively, which keeps a body posted before the
+ * rename parsing while the scan holds new text to one spelling. Subheadings and
+ * fenced lines are not headings, so the list governs level two alone.
+ */
+export function checkSections(body: string): SectionsCheck {
+  const headings = linesOutsideFences(body)
+    .map((line) => line.trim())
+    .filter((line) => H2.test(line))
+
+  return {
+    outside: headings.filter((heading) => !ALLOWED_HEADINGS.includes(heading)),
+    missing: REQUIRED_HEADINGS.filter((heading) => !headings.includes(heading)),
+  }
+}

package/src/migrate/skill-names.ts

@@ -99,6 +99,25 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'draft-diagram': 'draft-figure',
 }
 
+/**
+ * The skills that took a two-word name from a single word, which the map above
+ * may not carry as a bare key.
+ *
+ * `canvas` became `canvas-board`, and a bare `canvas` key would rewrite every
+ * unrelated use of the word: `canon canvas serve`, `src/canvas/`,
+ * `.canon/canvas/`, and the `internal-canvas` skill. So each row keys on a form
+ * only the skill spells, a plugin invocation or a skill folder path. The tail
+ * guard rejects a following `-`, so a rewritten `canon:canvas-board` is not
+ * matched again.
+ *
+ * What this leaves behind is a prose mention of the skill by its bare name,
+ * which has no token for a sweep to find and is fixed by hand.
+ */
+export const SKILL_CITATION_MAP: Readonly<Record<string, string>> = {
+  'canon:canvas': 'canon:canvas-board',
+  'skills/canvas': 'skills/canvas-board',
+}
+
 /**
  * The skill rename.
  *
@@ -132,7 +151,7 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * listing every sweep reads never reaches them.
  */
 export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
-  replacements: SKILL_NAME_MAP,
+  replacements: { ...SKILL_NAME_MAP, ...SKILL_CITATION_MAP },
   keepMarker: 'canon-keep-retired',
   wholeToken: true,
   excludedPrefixes: ['scripts/eval/result-'],

package/src/pr/evidence.ts

@@ -188,23 +188,218 @@ function evidenceImage(url: string, alt: string, width?: number): string {
 
 const EVIDENCE_IMAGE = String.raw`(?:!\[\]\([^)]*\)|<img [^>]*>)`
 
-/** A case row in any shape a render has posted: a Base cell before the head image, or the head image alone. */
-const EVIDENCE_ROW_PATTERN = new RegExp(
+/** A case row in a shape before the head image carried an alt: a Base cell before the head image, or the head image alone. */
+const LEGACY_ROW_PATTERN = new RegExp(
   String.raw`^\| .+ \| (?:(?:\*\(new\)\*|${EVIDENCE_IMAGE}) \| )?${EVIDENCE_IMAGE} \|$`,
-  'gm',
 )
 
+/** A head image, which every render since the alt text was added names with a trailing `head`. A row carries one per case it holds. */
+const HEAD_IMAGE_PATTERN = /<img [^>]*alt="[^"]* head">/g
+
+/** The form a case name takes when it names a view, a theme, and a width. Anchored on the right, since a view may carry hyphens. */
+const CASE_NAME = /^(.+)-(dark|light)-(\d+)$/
+
+const THEMES = ['dark', 'light'] as const
+
+type Theme = (typeof THEMES)[number]
+
+interface ViewCase {
+  readonly item: EvidenceItem
+  readonly theme: Theme
+  readonly width: string
+}
+
+function isTheme(value: string): value is Theme {
+  return value === 'dark' || value === 'light'
+}
+
+function readCaseName(stem: string):
+  | {
+      readonly view: string
+      readonly theme: Theme
+      readonly width: string
+    }
+  | undefined {
+  const match = CASE_NAME.exec(stem)
+  const view = match?.[1]
+  const theme = match?.[2]
+  const width = match?.[3]
+  if (view === undefined || theme === undefined || width === undefined) {
+    return undefined
+  }
+  return isTheme(theme) ? { view, theme, width } : undefined
+}
+
+function compareWidths(a: string, b: string): number {
+  return Number(a) - Number(b) || a.localeCompare(b)
+}
+
+function commitLink(repo: string, sha: string): string {
+  return `[\`${sha.slice(0, SHORT_SHA_LENGTH)}\`](https://github.com/${repo}/commit/${sha})`
+}
+
+function baseImage(item: EvidenceItem, repo: string, base: string): string {
+  return item.added
+    ? '*(new)*'
+    : evidenceImage(
+        rawUrl(repo, base, item.path),
+        `${escapeCell(item.stem)} base`,
+        item.baseWidth,
+      )
+}
+
+function headImage(item: EvidenceItem, repo: string, head: string): string {
+  return evidenceImage(
+    rawUrl(repo, head, item.path),
+    `${escapeCell(item.stem)} head`,
+    item.width,
+  )
+}
+
+function block(
+  opener: string,
+  summary: string,
+  header: readonly string[],
+  rows: readonly string[],
+): string {
+  return [
+    opener,
+    `<summary>${summary}</summary>`,
+    '',
+    `| ${header.join(' | ')} |`,
+    `| ${header.map(() => '---').join(' | ')} |`,
+    ...rows,
+    '',
+    '</details>',
+  ].join('\n')
+}
+
+/** One block for the cases of a state that did not name a view, one case per row. */
+function renderFlat(
+  label: string,
+  items: readonly EvidenceItem[],
+  repo: string,
+  base: string,
+  head: string,
+  opener: string,
+): string {
+  const hasBase = items.some((item) => !item.added)
+  const rows = items.map((item) => {
+    const stem = escapeCell(item.stem)
+    const after = headImage(item, repo, head)
+    return hasBase
+      ? `| ${stem} | ${baseImage(item, repo, base)} | ${after} |`
+      : `| ${stem} | ${after} |`
+  })
+  return block(
+    opener,
+    `${label} (${items.length})`,
+    hasBase ? ['Case', 'Base', 'Head'] : ['Case', 'Head'],
+    rows,
+  )
+}
+
+/** One block for a view, a width per row and a theme per column, each theme taking a base column when the view already exists at the base. */
+function renderView(
+  label: string,
+  cases: readonly ViewCase[],
+  repo: string,
+  base: string,
+  head: string,
+  opener: string,
+): string {
+  const themes = THEMES.filter((theme) =>
+    cases.some((entry) => entry.theme === theme),
+  )
+  const hasBase = cases.some((entry) => !entry.item.added)
+  const widths = [...new Set(cases.map((entry) => entry.width))].sort(
+    compareWidths,
+  )
+  const header = [
+    'Width',
+    ...themes.flatMap((theme) => {
+      const name = theme === 'dark' ? 'Dark' : 'Light'
+      return hasBase ? [`${name} base`, `${name} head`] : [name]
+    }),
+  ]
+  const rows = widths.map((width) => {
+    const cells = themes.flatMap((theme) => {
+      const found = cases.find(
+        (entry) => entry.theme === theme && entry.width === width,
+      )
+      if (found === undefined) return hasBase ? ['', ''] : ['']
+      const after = headImage(found.item, repo, head)
+      return hasBase ? [baseImage(found.item, repo, base), after] : [after]
+    })
+    return `| ${[width, ...cells].join(' | ')} |`
+  })
+  return block(opener, `${label} (${cases.length})`, header, rows)
+}
+
+/**
+ * Renders the blocks of one state: a block per view the case names split
+ * into, then one flat block for the names that did not. Nothing is dropped,
+ * so a state of unparsed names reads as the flat table it always was.
+ */
+function renderState(
+  entry: EvidenceState,
+  repo: string,
+  base: string,
+  head: string,
+  opener: string,
+): string[] {
+  const views = new Map<string, ViewCase[]>()
+  const flat: EvidenceItem[] = []
+  const taken = new Set<string>()
+  for (const item of entry.items) {
+    const name = readCaseName(item.stem)
+    // Two files can share a stem across extensions, and a view cell holds one.
+    const cell =
+      name === undefined ? '' : `${name.view}|${name.theme}|${name.width}`
+    if (name === undefined || taken.has(cell)) {
+      flat.push(item)
+      continue
+    }
+    taken.add(cell)
+    const cases = views.get(name.view)
+    const viewCase = { item, theme: name.theme, width: name.width }
+    if (cases === undefined) views.set(name.view, [viewCase])
+    else cases.push(viewCase)
+  }
+
+  const prefix = entry.state === '' ? '' : `${escapeCell(entry.state)} / `
+  const blocks = [...views.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([view, cases]) =>
+      renderView(
+        `${prefix}${escapeCell(view)}`,
+        cases,
+        repo,
+        base,
+        head,
+        opener,
+      ),
+    )
+  if (flat.length > 0) {
+    const label = entry.state === '' ? 'evidence' : escapeCell(entry.state)
+    blocks.push(renderFlat(label, flat, repo, base, head, opener))
+  }
+  return blocks
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
 
 /**
- * Renders the whole comment body: one `<details>` block per state, a Base/Head
- * row per case, and the trailing marker naming the head this body describes.
+ * Renders the whole comment body: one `<details>` block per view within each
+ * state, a width per row with a column per theme, a flat Base/Head table for
+ * the case names that do not split into a view, and the trailing marker naming
+ * the head this body describes.
  * Every state opens while the comment carries at most `EVIDENCE_OPEN_LIMIT`
  * images, one per row for the head plus one per row not added, and every state
  * closes past it, so a comment is never half open. A visible line under
- * `## Evidence` names the base and head as short shas. Every image URL is
+ * `## Evidence` names the base and head as short shas, each linking its commit. Every image URL is
  * pinned to a commit sha rather than a branch, so the comment keeps showing
  * what it claimed even after the branch moves.
  *
@@ -252,42 +447,13 @@ export function renderEvidenceBody(
   const opener =
     imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
 
-  const sections = states.map((entry) => {
-    const hasBase = entry.items.some((item) => !item.added)
-    const rows = entry.items.map((item) => {
-      const stem = escapeCell(item.stem)
-      const before = item.added
-        ? '*(new)*'
-        : evidenceImage(
-            rawUrl(repo, base, item.path),
-            `${stem} base`,
-            item.baseWidth,
-          )
-      const after = evidenceImage(
-        rawUrl(repo, head, item.path),
-        `${stem} head`,
-        item.width,
-      )
-      return hasBase
-        ? `| ${stem} | ${before} | ${after} |`
-        : `| ${stem} | ${after} |`
-    })
-
-    return [
-      opener,
-      `<summary>${entry.state === '' ? 'evidence' : entry.state} (${entry.items.length})</summary>`,
-      '',
-      hasBase ? '| Case | Base | Head |' : '| Case | Head |',
-      hasBase ? '| --- | --- | --- |' : '| --- | --- |',
-      ...rows,
-      '',
-      '</details>',
-    ].join('\n')
-  })
+  const sections = states.flatMap((entry) =>
+    renderState(entry, repo, base, head, opener),
+  )
 
   return [
     ...opening,
-    `${BASE_PREFIX} \`${base.slice(0, SHORT_SHA_LENGTH)}\` · **Head:** \`${head.slice(0, SHORT_SHA_LENGTH)}\``,
+    `${BASE_PREFIX} ${commitLink(repo, base)} · **Head:** ${commitLink(repo, head)}`,
     '',
     ...sections,
     '',
@@ -297,14 +463,21 @@ export function renderEvidenceBody(
 }
 
 /**
- * How many case rows a rendered body carries, read off the row shapes
- * `renderEvidenceBody` writes. A row always ends in a head image, which a
- * checklist line or a preview address never does. The pattern also reads the
- * `![](url)` three-column shape an earlier render posted, so a comment posted
- * before the change still counts its cases and the `would-empty` guard holds.
+ * How many cases a rendered body carries. Every case has exactly one head
+ * image, so a row counts the head images it holds, which is one in the flat
+ * table and up to two in a view's row. A row from before the alt text named
+ * its head image counts as one case when it matches the old row shape, so a
+ * comment posted before the change still counts its cases and the
+ * `would-empty` guard holds.
  */
 export function countEvidenceCases(body: string): number {
-  return body.match(EVIDENCE_ROW_PATTERN)?.length ?? 0
+  let total = 0
+  for (const line of body.split('\n')) {
+    if (!line.startsWith('| ')) continue
+    const heads = line.match(HEAD_IMAGE_PATTERN)?.length ?? 0
+    total += heads > 0 ? heads : LEGACY_ROW_PATTERN.test(line) ? 1 : 0
+  }
+  return total
 }
 
 export interface EvidenceComment {

package/src/pr/frames.ts

@@ -20,6 +20,10 @@ const FOLDER_PATTERN = /^pr-(\d+)$/
 
 const DAY_MS = 86_400_000
 
+const THEMES = ['dark', 'light'] as const
+
+export type FrameTheme = (typeof THEMES)[number]
+
 export interface TreeEntry {
   readonly path: string
   readonly mode: string
@@ -71,6 +75,7 @@ export interface FrameInput {
   readonly head: string
   readonly pass: string
   readonly box: number
+  readonly theme?: FrameTheme
   readonly bytes: Uint8Array
 }
 
@@ -113,18 +118,27 @@ export function isFramePass(pass: string): boolean {
   return PASS_PATTERN.test(pass)
 }
 
+/** Whether a value names a theme a box can be shot at, the only theme segment the path takes. */
+export function isFrameTheme(theme: string): theme is FrameTheme {
+  return (THEMES as readonly string[]).includes(theme)
+}
+
 /**
  * Where a frame lands. The pass segment keeps a second pass at the same head
  * and box from replacing the image an earlier review comment shows, since a
- * branch-path link reads whatever the path holds now.
+ * branch-path link reads whatever the path holds now. The theme segment keeps
+ * two shots of one box in one pass apart, and a frame without one keeps the
+ * plain `box-<n>.png` form.
  */
 export function framePath(
   number: number,
   head: string,
   pass: string,
   box: number,
+  theme?: FrameTheme,
 ): string {
-  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/box-${box}.png`
+  const name = theme === undefined ? `box-${box}` : `box-${box}-${theme}`
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/${name}.png`
 }
 
 /**
@@ -160,7 +174,13 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path = framePath(input.number, input.head, input.pass, input.box)
+  const path = framePath(
+    input.number,
+    input.head,
+    input.pass,
+    input.box,
+    input.theme,
+  )
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }