@erclx/canon 5.49.0 → 5.51.0

package/src/hooks/post-merge.ts

@@ -39,6 +39,7 @@ export interface PostMergeInput {
 export const STEP_VERBS = {
   archive: ['tasks', 'archive'],
   push: ['records', 'push'],
+  members: ['worktrees', 'retire-members'],
   reclaim: ['worktrees', 'reclaim'],
   upgrade: ['upgrade'],
   pluginUpdate: ['claude', 'plugin-update'],
@@ -225,6 +226,33 @@ function reclaimLines(fields: Fields): string | undefined {
   return lines.length > 0 ? lines : undefined
 }
 
+/**
+ * Keyed on the fields, like the reclaim, since a run that retires one member
+ * and fails on another exits 1 with a branch already deleted. A body naming no
+ * members is every merge but an integrator's, so it stays quiet.
+ */
+function memberLines(number: number, fields: Fields): string | undefined {
+  let lines = ''
+  const retired = count(fields, 'retired')
+  if (retired > 0) {
+    lines += `\n🌿 Retired ${retired} fan-in member(s) of #${number}.\n\n`
+  }
+
+  const hint = `Run canon worktrees retire-members --pull-request ${number} --dry-run to read why.\n\n`
+  const reason = text(fields, 'reason')
+  const unfinished = count(fields, 'kept') + count(fields, 'failed')
+  if (
+    reason !== undefined &&
+    reason !== 'no-members' &&
+    reason !== 'gh-missing'
+  ) {
+    lines += `\n🌿 Fan-in members of #${number} not retired: ${reason}\n${hint}`
+  } else if (unfinished > 0) {
+    lines += `\n🌿 ${unfinished} fan-in member(s) of #${number} kept or not fully deleted.\n${hint}`
+  }
+  return lines.length > 0 ? lines : undefined
+}
+
 /**
  * Shared by the binary reinstall and the plugin update. `current` is the
  * ordinary outcome on most merges and stays quiet, and `quiet` names the
@@ -271,8 +299,10 @@ async function step(
 }
 
 /**
- * Runs the five post-merge steps in order: archive, records push, reclaim,
- * upgrade, plugin update. The reclaim sits before the upgrade, since the
+ * Runs the six post-merge steps in order: archive, records push, member
+ * retirement, reclaim, upgrade, plugin update. The member retirement sits
+ * before the reclaim, so the reclaim reads a retired member's worktree as
+ * gone rather than racing it. Both sit before the upgrade, since the
  * upgrade reinstalls the binary every later child runs under, and the two
  * network-bound moves sit last so a slow registry delays nothing else.
  *
@@ -309,11 +339,20 @@ export async function runPostMerge(input: PostMergeInput): Promise<void> {
     pushLines,
   )
 
-  // No `--root` here, and that is load-bearing. The verb reads its own working
-  // directory to refuse the worktree it stands in, so a root would turn the
-  // running worktree into an ordinary candidate and let a pull inside a
-  // linked worktree delete the ground under itself.
+  // No `--root` on either worktree step, and that is load-bearing. Each verb
+  // reads its own working directory to refuse the worktree it stands in, so a
+  // root would turn the running worktree into an ordinary candidate and let a
+  // pull inside a linked worktree delete the ground under itself. One switch
+  // covers both, since both remove worktrees.
   if (!isSkipped('CANON_SKIP_RECLAIM')) {
+    for (const number of pullRequestNumbers(input.subjects)) {
+      await step(
+        input,
+        at([...STEP_VERBS.members, '--pull-request', String(number), '--json']),
+        (_, fields) => memberLines(number, fields),
+      )
+    }
+
     await step(input, at([...STEP_VERBS.reclaim, '--json']), (_, fields) =>
       reclaimLines(fields),
     )

package/src/markdown/gated.ts

@@ -9,7 +9,7 @@ import {
 import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { listRepositoryFiles } from '@/git/files'
-import { densityFindings, type DensityKind } from '@/markdown/density'
+import type { DensityKind } from '@/markdown/density'
 import { referenceShapeGates } from '@/markdown/gate'
 import {
   type ReferenceShapeKind,
@@ -20,7 +20,7 @@ import {
   densityGates,
   GATED_PATHS,
   GATED_SCOPE_ROOTS,
-  inDensityScope,
+  scopedDensityFindings,
 } from '@/markdown/scope'
 import { isOwnCheckout } from '@/roots/project'
 
@@ -198,11 +198,9 @@ export async function findingsUnder(
   const found = await Promise.all(
     under.map(async (rel) => {
       const source = await readFile(join(root, rel), 'utf8')
-      const density = inDensityScope(rel)
-        ? densityFindings(bodyLines(source)).filter((finding) =>
-            densityGates(rel, finding.kind, [prefix], false),
-          )
-        : []
+      const density = scopedDensityFindings(rel, bodyLines(source)).filter(
+        (finding) => densityGates(rel, finding.kind, [prefix], false),
+      )
       const shape = referenceShapeGates(rel, [prefix])
         ? referenceShapeFindings(source)
         : []

package/src/markdown/scope.ts

@@ -1,4 +1,9 @@
-import type { DensityKind } from '@/markdown/density'
+import {
+  type DensityFinding,
+  type DensityKind,
+  densityFindings,
+} from '@/markdown/density'
+import type { BodyLine } from '@/markdown/scan'
 
 /** The surfaces the retired bullet-stacks stage held, per `ALWAYS_GATED`. */
 const BULLET_RUN_SCOPE = [
@@ -21,11 +26,12 @@ const REQUIREMENT_SCOPE =
  * pages, the skill bodies, references, and requirements 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 project 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.
+ * Rules stay out, since a rule is one imperative per bullet, and so does every
+ * `CLAUDE.md` section but Key paths, which `KEY_PATHS_SCOPE` holds. So do the
+ * project 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,
@@ -36,10 +42,49 @@ const DENSITY_SCOPE = [
   /^(?:README|CONTRIBUTING)\.md$/,
 ]
 
+/**
+ * The root `CLAUDE.md` and its seed, measured inside `## Key paths` alone. That
+ * section is a catalog rather than rules, so it takes the run limit and the H3
+ * opening a grouped catalog needs, and nothing else a rule would breach.
+ */
+const KEY_PATHS_SCOPE = /^(?:tooling\/claude\/seeds\/)?CLAUDE\.md$/
+const KEY_PATHS_HEADING = /^## Key paths\s*$/
+const KEY_PATHS_KINDS: readonly DensityKind[] = ['bullet-run', 'h3-opening']
+
+/** The lines under `## Key paths` up to the next H1 or H2, keeping their numbers. */
+function keyPathsSection(lines: readonly BodyLine[]): readonly BodyLine[] {
+  const start = lines.findIndex(
+    (line) => !line.fenced && KEY_PATHS_HEADING.test(line.text),
+  )
+  if (start === -1) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex(
+    (line) => !line.fenced && /^#{1,2}\s/.test(line.text),
+  )
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/**
+ * The density findings a path takes, being every finding on a density-scope
+ * file and the Key paths findings on a `CLAUDE.md`. The audit, the init probe,
+ * and `canon claude sync` all read this, so the three agree on what counts.
+ */
+export function scopedDensityFindings(
+  rel: string,
+  lines: readonly BodyLine[],
+): DensityFinding[] {
+  if (inDensityScope(rel)) return densityFindings(lines)
+  if (!KEY_PATHS_SCOPE.test(rel)) return []
+  return densityFindings(keyPathsSection(lines)).filter((finding) =>
+    KEY_PATHS_KINDS.includes(finding.kind),
+  )
+}
+
 /**
  * The roots `canon init` gates in a new project when each passes at init time:
- * every density surface a target authors itself, leaving out the toolkit's own
- * `claude/skills/` and `tooling/` trees.
+ * every density surface a target authors itself and the Key paths of its
+ * `CLAUDE.md`, leaving out the toolkit's own `claude/skills/` and `tooling/`
+ * trees.
  */
 export const GATED_SCOPE_ROOTS: readonly string[] = [
   'canon/context/',
@@ -48,6 +93,7 @@ export const GATED_SCOPE_ROOTS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -93,7 +139,6 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/canvas-board/REQUIREMENT.md',
   'claude/skills/canvas-board/SKILL.md',
   'claude/skills/canvas-board/references/canvas.md',
-  'claude/skills/canvas-board/references/design.md',
   'claude/skills/ci-workflow/REQUIREMENT.md',
   'claude/skills/ci-workflow/SKILL.md',
   'claude/skills/ci-workflow/references/workflows.md',
@@ -133,6 +178,10 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/deprecation-migration/REQUIREMENT.md',
   'claude/skills/deprecation-migration/SKILL.md',
   'claude/skills/deprecation-migration/references/adopted.md',
+  'claude/skills/design-record/REQUIREMENT.md',
+  'claude/skills/design-record/SKILL.md',
+  'claude/skills/design-record/references/design.md',
+  'claude/skills/design-record/references/folder.md',
   'claude/skills/design-taste/REQUIREMENT.md',
   'claude/skills/design-taste/SKILL.md',
   'claude/skills/design-taste/references/adopted.md',
@@ -394,6 +443,7 @@ export const GATED_PATHS: readonly string[] = [
   'wiki/',
   'README.md',
   'CONTRIBUTING.md',
+  'CLAUDE.md',
 ]
 
 /**
@@ -425,7 +475,7 @@ export function densityGates(
   gated: readonly string[] = GATED_PATHS,
   alwaysGated = true,
 ): boolean {
-  if (!inDensityScope(rel)) return false
+  if (!inDensityScope(rel) && !KEY_PATHS_SCOPE.test(rel)) return false
   if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
     alwaysGated &&

package/src/markdown/structure.ts

@@ -67,7 +67,7 @@ const MARKER_WIDTH = 20
 
 export const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 export const TABLE_ROW = /^\s*\|/
-const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+export const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 export const BLOCKQUOTE = /^\s*>/
 
 /**

package/src/markdown/tables.ts

@@ -0,0 +1,150 @@
+import { type BodyLine, visibleText } from '@/markdown/scan'
+import { LIST_ITEM, TABLE_ROW, TABLE_SEPARATOR } from '@/markdown/structure'
+
+/** The most visible characters one table cell may hold. */
+export const TABLE_CELL = 120
+
+/** The most body rows a table may carry before it splits into groups. */
+export const TABLE_ROWS = 8
+
+/** The longest unbroken run a code span in a table cell may carry. */
+export const TABLE_TOKEN = 30
+
+export type TableKind =
+  | 'table-cell'
+  | 'table-rows'
+  | 'table-then-list'
+  | 'table-token'
+
+export interface TableFinding {
+  readonly kind: TableKind
+  /** The row holding the cell or span, the header for a row count, or the list's first item. */
+  readonly line: number
+  /** What was measured, or null for a trailing list, which is a shape rather than a count. */
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+/**
+ * The body of every code span in a cell, read after link destinations are
+ * dropped, since only a link's label renders.
+ */
+export function codeSpans(cell: string): string[] {
+  return (cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []).map(
+    (span) => span.slice(1, -1),
+  )
+}
+
+/**
+ * The longest whitespace-free run in a code span. A preview also breaks a span
+ * after a hyphen or a slash, but a run this long still splits mid-token or
+ * widens its column, so whitespace is the break this counts.
+ */
+export function unbrokenRun(span: string): number {
+  return Math.max(...span.split(/\s+/).map((part) => part.length))
+}
+
+/** Splits a row on its unescaped pipes, dropping the outer two. */
+function cellsOf(row: string): string[] {
+  return row
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/(?<!\\)\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.trim().replaceAll('\\|', '|'))
+}
+
+/**
+ * Every breach of the four table limits, in line order.
+ *
+ * A table is a run of pipe rows whose second row is a delimiter, the shape a
+ * renderer draws. Pipe lines with no delimiter render as paragraph text, and a
+ * fenced line is an example, so neither is measured. The limits are a
+ * 120-character cell, 8 body rows, a list as the next block, and a code span
+ * holding a run past 30 characters. Every finding reports and none gates.
+ */
+export function tableFindings(lines: readonly BodyLine[]): TableFinding[] {
+  const found: TableFinding[] = []
+  let index = 0
+
+  while (index < lines.length) {
+    const header = lines[index]
+    const delimiter = lines[index + 1]
+    if (
+      header.fenced ||
+      !TABLE_ROW.test(header.text) ||
+      delimiter === undefined ||
+      delimiter.fenced ||
+      !TABLE_SEPARATOR.test(delimiter.text)
+    ) {
+      index++
+      continue
+    }
+
+    const tableRows = [header]
+    let end = index + 2
+    while (
+      end < lines.length &&
+      !lines[end].fenced &&
+      TABLE_ROW.test(lines[end].text)
+    ) {
+      tableRows.push(lines[end])
+      end++
+    }
+
+    for (const row of tableRows) {
+      for (const cell of cellsOf(row.text)) {
+        const length = visibleText(cell).length
+        if (length > TABLE_CELL) {
+          found.push({
+            kind: 'table-cell',
+            line: row.number,
+            value: length,
+            limit: TABLE_CELL,
+          })
+        }
+        for (const span of codeSpans(cell)) {
+          const run = unbrokenRun(span)
+          if (run > TABLE_TOKEN) {
+            found.push({
+              kind: 'table-token',
+              line: row.number,
+              value: run,
+              limit: TABLE_TOKEN,
+            })
+          }
+        }
+      }
+    }
+
+    const bodyRows = tableRows.length - 1
+    if (bodyRows > TABLE_ROWS) {
+      found.push({
+        kind: 'table-rows',
+        line: header.number,
+        value: bodyRows,
+        limit: TABLE_ROWS,
+      })
+    }
+
+    let next = end
+    while (next < lines.length && lines[next].text.trim() === '') next++
+    const following = lines[next]
+    if (
+      following !== undefined &&
+      !following.fenced &&
+      LIST_ITEM.test(following.text)
+    ) {
+      found.push({
+        kind: 'table-then-list',
+        line: following.number,
+        value: null,
+        limit: null,
+      })
+    }
+
+    index = end
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}

package/src/migrate/status.ts

@@ -0,0 +1,128 @@
+import type { RunCommand } from '@/gate/measures'
+
+interface Migration {
+  readonly name: string
+  readonly flags: readonly string[]
+}
+
+/**
+ * Every `canon migrate` subcommand in the order a project runs them, records
+ * first. This is the source for that order, and `docs/target/migrations.md`
+ * cites the verb rather than keeping a second list. A new migration joins by
+ * one line here.
+ */
+export const MIGRATIONS: readonly Migration[] = [
+  { name: 'records', flags: [] },
+  { name: 'record-tree', flags: [] },
+  { name: 'scratch-evidence', flags: [] },
+  { name: 'record-layout', flags: [] },
+  { name: 'rule-layout', flags: [] },
+  { name: 'rename', flags: ['--scope', 'target'] },
+  { name: 'skill-names', flags: [] },
+  { name: 'surface-roots', flags: [] },
+  { name: 'session-defaults', flags: [] },
+]
+
+export type MigrationState = 'pending' | 'clean' | 'refused'
+
+export interface MigrationStatus {
+  readonly name: string
+  readonly verb: string
+  readonly state: MigrationState
+  /** The subcommand's own `--json` record, carried through unread. */
+  readonly record?: unknown
+  readonly reason?: string
+}
+
+export interface StatusReport {
+  readonly migrations: readonly MigrationStatus[]
+  readonly pending: number
+  readonly refused: number
+}
+
+function parseRecord(stdout: string): unknown {
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    return undefined
+  }
+}
+
+const FRAME = /^[\s│├┌└]+/
+
+/**
+ * A refusing subcommand writes its stderr inside the CLI's frame, so the raw
+ * text would carry the glyphs into a record a skill reads as data. The error
+ * lines are the reason, and a stderr without a marker keeps every line.
+ */
+function refusalReason(stderr: string): string {
+  const lines = stderr.split('\n').map((line) => line.replace(FRAME, '').trim())
+  const errors = lines
+    .filter((line) => line.startsWith('✗'))
+    .map((line) => line.replace(/^✗\s*/, ''))
+  const kept = errors.length > 0 ? errors : lines.filter(Boolean)
+  return kept.map((line) => line.replace(/\.+$/, '')).join('. ')
+}
+
+async function readOne(
+  run: RunCommand,
+  migration: Migration,
+): Promise<MigrationStatus> {
+  const verb = `canon migrate ${migration.name}`
+  const result = await run([
+    'migrate',
+    migration.name,
+    ...migration.flags,
+    '--json',
+  ])
+
+  if (result.exitCode === 0) {
+    return { name: migration.name, verb, state: 'clean' }
+  }
+
+  if (result.exitCode === 2) {
+    return {
+      name: migration.name,
+      verb,
+      state: 'pending',
+      record: parseRecord(result.stdout),
+    }
+  }
+
+  const reason =
+    result.spawnError ??
+    (refusalReason(result.stderr) ||
+      `exited ${result.exitCode} with no message`)
+  return {
+    name: migration.name,
+    verb,
+    state: 'refused',
+    record: parseRecord(result.stdout),
+    reason,
+  }
+}
+
+/**
+ * Runs each migration's own dry run and sorts it by the exit contract every
+ * subcommand shares: 0 with nothing to move, 2 with a plan and no `--write`,
+ * anything else a refusal. It never passes `--write`, and it reads no count,
+ * since the records share no field to count from.
+ */
+export async function readMigrationStatus(
+  run: RunCommand,
+): Promise<StatusReport> {
+  const migrations = await Promise.all(
+    MIGRATIONS.map((migration) => readOne(run, migration)),
+  )
+  return {
+    migrations,
+    pending: migrations.filter((m) => m.state === 'pending').length,
+    refused: migrations.filter((m) => m.state === 'refused').length,
+  }
+}
+
+/** A refusal outranks a pending plan, since a refused read measured nothing. */
+export function statusExitCode(report: StatusReport): 0 | 1 | 2 {
+  if (report.refused > 0) return 1
+  return report.pending > 0 ? 2 : 0
+}

package/src/tasks/validate.ts

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import { codeSpans, unbrokenRun } from '@/markdown/tables'
 import {
   archiveDir,
   declinedDir,
@@ -1084,28 +1085,30 @@ function checkFolderClaims(
 /**
  * The widest the longest unbroken run in a code span may be before a table
  * scrolls in the preview pane. A 57-character span fit and a 78-character one
- * did not, so the limit sits at the nearest round number above the first.
+ * did not, so the limit sits at the nearest round number above the first. It
+ * is still too high: a 36-character path with no hyphen widened a board column
+ * until the next one ran off the pane, which is why a table cell reads the same
+ * measure at 30. The board keeps 60 until its own report is revisited.
  */
 const WIDE_LIMIT = 60
 
 /**
- * Reports a code span a table cell cannot wrap. A span breaks only at
- * whitespace, so the longest whitespace-free run is what is measured, and a
- * link target is stripped first because only its label renders. Every group is
- * scanned, since the overflow this exists for happened under `## Up next`,
- * where the folder-claim scan would not have looked. Prose breaks at spaces
- * and bare words at hyphens, so only a span is read.
+ * Reports a code span a table cell cannot wrap, measured by `unbrokenRun`,
+ * which `canon markdown audit` reads for a table too. A rendered preview breaks
+ * a span at whitespace and after a hyphen or a slash, so a long run either
+ * widens its column or splits mid-token. Every group is scanned, since the
+ * overflow this exists for happened under `## Up next`, where the folder-claim
+ * scan would not have looked. Prose breaks at spaces and bare words at hyphens,
+ * so only a span is read.
  */
 function checkWideTokens(rows: readonly BoardRow[]): WideToken[] {
   const wide: WideToken[] = []
 
   for (const row of rows) {
     for (const cell of row.cells) {
-      const spans = cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []
-
-      for (const span of spans) {
-        const text = span.slice(1, -1)
-        const run = Math.max(...text.split(/\s+/).map((part) => part.length))
+      for (const text of codeSpans(cell)) {
+        const span = `\`${text}\``
+        const run = unbrokenRun(text)
 
         if (/\{[^}]*,[^}]*\}/.test(text)) {
           wide.push({