@erclx/canon 5.49.0 → 5.51.0

package/src/claude/cases/misc.ts

@@ -39,6 +39,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Draw the signup screen as a frame on the canvas, then restyle the element I just selected there.',
     expect: 'canvas-board',
   },
+  {
+    prompt:
+      'The operator picked the new settings panel, so land it in canon/design with an index row for it.',
+    expect: 'design-record',
+  },
   {
     prompt:
       "We're about to hit the context limit, write the handoff before we lose state.",

package/src/cli/help.ts

@@ -20,6 +20,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['sync [path]', 'Sync all installed domains in a project'],
       ['upgrade', 'Reinstall the CLI with the manager that installed it'],
       ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['changelog', 'Read the releases between a stamp and this binary'],
       ['targets [cmd]', 'Projects this toolkit installed into'],
     ],
   },

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as census } from '@/commands/census'
 import { register as upstream } from '@/commands/upstream'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
+import { register as changelog } from '@/commands/changelog'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
 import { renderAll, routeHelp } from '@/cli/help-all'
@@ -100,6 +101,7 @@ upstream(program)
 audits(program)
 gate(program)
 upgrade(program)
+changelog(program)
 
 const route = routeHelp(program, process.argv.slice(2))
 if (route.kind === 'top') showHelp()

package/src/commands/changelog.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { PROJECT_ROOT } from '@/roots/project'
+import { readStamp } from '@/sync/stamp'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/cli/ui'
+import { type ChangelogReport, resolveChangelog } from '@/version/changelog'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+
+interface ChangelogOptions {
+  readonly since?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+const REFUSALS = {
+  'no-stamp':
+    'the target carries no stamped version and --since named none, so there is no start to range from',
+  'no-changelog':
+    'the installed package carries no CHANGELOG.md with release entries to read',
+  'unknown-version':
+    'the changelog lists no such release, so the range would be a guess',
+} as const
+
+const HELP = [
+  '',
+  'Prints the release entries after a version, up to the running one, from the',
+  'CHANGELOG.md the installed package ships. It reads no registry and needs no',
+  '`gh`, so it answers offline.',
+  '',
+  'The start defaults to the oldest `version` across the target stamp domains,',
+  'since the oldest domain is the one furthest behind. --since overrides it.',
+  '',
+  'Exit codes:',
+  '  0  the range was read, empty when the target is already current',
+  '  1  refused, with the reason on stderr',
+  '',
+  'A refusal names a "reason" rather than printing an empty range. no-stamp',
+  'means no start was recorded or given, no-changelog means the file or its',
+  'release headings are missing, and unknown-version means the start or the',
+  'running version is absent from the file, which covers a pre-release and a',
+  'start newer than the binary.',
+  '',
+  'The JSON carries "since", "running", and "entries", each an object with the',
+  'release "version" and its raw "markdown". Read the record rather than the',
+  'exit when a skill consumes this, since a shell function wrapping the binary',
+  'may flatten the status.',
+  '',
+  'Examples:',
+  '  canon changelog',
+  '  canon changelog --since 5.47.0 --json',
+  '  canon changelog --root ../frameboard',
+  '',
+].join('\n')
+
+export function register(program: Command): void {
+  program
+    .command('changelog')
+    .description(
+      'Print the release entries after a version up to the running one',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--since <version>',
+      'Start after this version instead of the stamp',
+    )
+    .option('--root <path>', 'Target whose stamp sets the start', '.')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText('after', HELP)
+    .action((opts: ChangelogOptions) => {
+      process.exitCode = runChangelog(opts)
+    })
+}
+
+function readChangelogText(): string | undefined {
+  const path = join(PROJECT_ROOT, 'CHANGELOG.md')
+
+  return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+}
+
+function stampedVersions(root: string): string[] {
+  const stamp = readStamp(root)
+  if (stamp === undefined) return []
+
+  return Object.values(stamp.domains)
+    .map((domain) => domain?.version)
+    .filter((version): version is string => version !== undefined)
+}
+
+function runChangelog(opts: ChangelogOptions): number {
+  intro('canon changelog')
+
+  const root = resolve(opts.root ?? '.')
+  const report = resolveChangelog({
+    text: readChangelogText(),
+    running: readInstalled().version ?? UNKNOWN_LABEL,
+    since: opts.since,
+    stamped: stampedVersions(root),
+  })
+
+  if (report.kind === 'range') {
+    reportRange(report)
+  } else {
+    reportRefusal(report)
+  }
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`)
+  }
+
+  return report.kind === 'range' ? 0 : 1
+}
+
+function reportRange(
+  report: Extract<ChangelogReport, { kind: 'range' }>,
+): void {
+  logStep('Range')
+  logInfo(`${report.since} to ${report.running}`)
+
+  if (report.entries.length === 0) {
+    logInfo('No release after the start, so nothing is pending')
+    return
+  }
+
+  logStep(plural(report.entries.length, 'release'))
+  for (const entry of report.entries) {
+    pipeOutput(entry.markdown)
+  }
+}
+
+function reportRefusal(
+  report: Extract<ChangelogReport, { kind: 'refused' }>,
+): void {
+  logStep('Refused')
+  const version = report.version === undefined ? '' : ` (${report.version})`
+  logWarn(`${report.reason}${version}: ${REFUSALS[report.reason]}`)
+}

package/src/commands/claude.ts

@@ -71,6 +71,9 @@ import {
   serializeSettings,
   writeSettings,
 } from '@/claude/settings'
+import { bodyLines } from '@/markdown/scan'
+import { scopedDensityFindings } from '@/markdown/scope'
+import { CAP } from '@/markdown/stacks'
 import { readSessionDefaults } from '@/migrate/session-defaults'
 import { copyPreservingMode } from '@/sync/copy'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
@@ -176,6 +179,22 @@ export function seededDirPath(resolved: string, name: string): string {
     ? surfaceDir(resolved, name)
     : recordDir(resolved, name)
 }
+
+/**
+ * Each bullet run past the limit in the target's `CLAUDE.md` Key paths, read
+ * through the scope the audit gates on. Sync warns rather than gates, since a
+ * target gates only the prefixes its own config lists.
+ */
+export async function longKeyPathsRuns(
+  resolved: string,
+): Promise<{ line: number; count: number }[]> {
+  const path = join(resolved, 'CLAUDE.md')
+  if (!existsSync(path)) return []
+  const lines = bodyLines(await readFile(path, 'utf8'))
+  return scopedDensityFindings('CLAUDE.md', lines)
+    .filter((finding) => finding.kind === 'bullet-run')
+    .map((finding) => ({ line: finding.line, count: finding.value ?? 0 }))
+}
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
 const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
@@ -244,7 +263,8 @@ export function register(program: Command): void {
         'Writes .gitignore alone: adds the entries the claude manifest lists',
         'and drops ones under its headers that the manifest no longer lists.',
         'A seeded file is reported, never rewritten, and a missing one points',
-        'at `canon claude init`.',
+        'at `canon claude init`. A CLAUDE.md Key paths running past 5 bullets',
+        'is reported with the H3 grouping that fixes it.',
         '',
         'Exit codes:',
         '  0  synced, already up to date, or the prompt was cancelled',
@@ -665,6 +685,11 @@ async function runSync(target: string): Promise<number> {
     if (isDirectory(seededDirPath(resolved, name))) logInfo(`${name}/`)
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
+  for (const run of await longKeyPathsRuns(resolved)) {
+    logWarn(
+      `CLAUDE.md:${run.line} runs ${run.count} Key paths bullets past ${CAP}. Group them under H3s, each opening on a lead sentence`,
+    )
+  }
 
   // Sync never rewrites an existing settings file, so a target seeded before
   // the session defaults learns of them only here.

package/src/commands/gate.ts

@@ -130,22 +130,9 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
       process.stderr.write(`${failed.label}: ${failed.failure}\n`)
     }
     process.stdout.write(
-      `${JSON.stringify({
-        ok: code === 0,
-        root,
-        scoped: changed.scoped,
-        changed: changed.files.length,
-        summary,
-        ms: results.reduce((total, result) => total + result.ms, 0),
-        stages: results.map(({ id, label, status, failure, ms, queuedMs }) => ({
-          id,
-          label,
-          status,
-          failure,
-          ms,
-          queuedMs,
-        })),
-      })}\n`,
+      `${JSON.stringify(
+        gateRecord({ ok: code === 0, root, changed, summary, results }),
+      )}\n`,
     )
     return code
   }
@@ -154,6 +141,60 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
   return code
 }
 
+/** Lines of a failed stage's output the record keeps, counted from the end. */
+const OUTPUT_TAIL_LINES = 200
+
+interface GateRecordInput {
+  readonly ok: boolean
+  readonly root: string
+  readonly changed: {
+    readonly scoped: boolean
+    readonly files: readonly string[]
+  }
+  readonly summary: Summary
+  readonly results: readonly StageResult[]
+}
+
+/**
+ * The `--json` record. A failed stage carries the tail of the output its
+ * checks printed, since a caller reading the record alone otherwise reruns
+ * the stage by hand to learn which test failed. The tail rather than a parse
+ * of the `FAIL` lines, so a generic stage stays free of one runner's format,
+ * and a dot-reporter run prints its failures and summary last.
+ */
+export function gateRecord(input: GateRecordInput) {
+  const { ok, root, changed, summary, results } = input
+  return {
+    ok,
+    root,
+    scoped: changed.scoped,
+    changed: changed.files.length,
+    summary,
+    ms: results.reduce((total, result) => total + result.ms, 0),
+    stages: results.map(
+      ({ id, label, status, failure, ms, queuedMs, emissions }) => ({
+        id,
+        label,
+        status,
+        failure,
+        ms,
+        queuedMs,
+        output: status === 'failed' ? outputTail(emissions) : undefined,
+      }),
+    ),
+  }
+}
+
+function outputTail(emissions: StageResult['emissions']): string {
+  const lines = emissions
+    .filter((emission) => emission.kind === 'output')
+    .map((emission) => emission.text.trimEnd())
+    .filter((text) => text !== '')
+    .join('\n')
+    .split('\n')
+  return lines.slice(-OUTPUT_TAIL_LINES).join('\n')
+}
+
 function report(result: StageResult): void {
   logStep(result.label)
   for (const emission of result.emissions) {

package/src/commands/hooks.ts

@@ -39,14 +39,16 @@ export function register(program: Command): void {
         'Runs these steps in order, each a child call reading its --json record:',
         ...Object.values(STEP_VERBS).map((verb) => `  canon ${verb.join(' ')}`),
         '',
-        'The archive runs once per pull request number the merge brought in.',
-        'Lines go to stderr, and an ordinary merge prints nothing.',
+        'The archive and the member retirement run once per pull request',
+        'number the merge brought in. Lines go to stderr, and an ordinary merge',
+        'prints nothing.',
         '',
-        'The reclaim runs from the working directory with no root, so a pull',
-        'inside a linked worktree never removes the worktree it stands in.',
+        'The member retirement and the reclaim run from the working directory',
+        'with no root, so a pull inside a linked worktree never removes the',
+        'worktree it stands in.',
         '',
         'Environment:',
-        '  CANON_SKIP_RECLAIM=1        skip the worktree reclaim',
+        '  CANON_SKIP_RECLAIM=1        skip the member retirement and the reclaim',
         '  CANON_SKIP_UPGRADE=1        skip the CLI reinstall',
         '  CANON_SKIP_PLUGIN_UPDATE=1  skip the plugin update',
         '',

package/src/commands/markdown.ts

@@ -6,7 +6,7 @@ import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { isChangelog, lengthExemption } from '@/markdown/ceiling'
 import { type ColonFinding, findColons } from '@/markdown/colons'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
-import { densityFindings, type DensityKind } from '@/markdown/density'
+import type { DensityKind } from '@/markdown/density'
 import {
   type GatedDensityFinding,
   type GatedReferenceShapeFinding,
@@ -38,7 +38,19 @@ import {
   readGatedConfig,
   resolveGatedList,
 } from '@/markdown/gated'
-import { densityGates, inDensityScope } from '@/markdown/scope'
+import {
+  densityGates,
+  inDensityScope,
+  scopedDensityFindings,
+} from '@/markdown/scope'
+import {
+  TABLE_CELL,
+  TABLE_ROWS,
+  TABLE_TOKEN,
+  type TableFinding,
+  tableFindings,
+  type TableKind,
+} from '@/markdown/tables'
 import {
   BASELINE,
   CHECKPOINTS,
@@ -86,6 +98,8 @@ interface FileReport {
   readonly headingCase: readonly HeadingCaseFinding[]
   /** Empty on a path outside the density scope, so a plan never carries one. */
   readonly density: readonly GatedDensityFinding[]
+  /** Empty outside the density scope, and never gating anywhere. */
+  readonly tables: readonly TableFinding[]
   /** Empty on a page whose frontmatter does not carry `kind: reference`. */
   readonly referenceShape: readonly GatedReferenceShapeFinding[]
   readonly structure: StructureReport
@@ -131,13 +145,20 @@ export function register(program: Command): void {
         'a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a',
         'paragraph or table opening every H3. Only context, docs, skills, tooling',
         'seeds and references, the wiki, README.md, and CONTRIBUTING.md take a',
-        'finding. In a canon checkout one gates under a prefix in GATED_PATHS in',
-        'src/markdown/scope.ts, and a bullet run gates in context, docs, and',
-        'skills from the start. Elsewhere one gates only under a prefix',
-        'canon/config/markdown.toml lists, which canon markdown gated add writes,',
-        'and with no such file every density finding reports and none gates.',
+        'finding. CLAUDE.md and its seed take only the bullet run and the H3',
+        'opening, inside Key paths. In a canon checkout one gates under a',
+        'prefix in GATED_PATHS in src/markdown/scope.ts, and a bullet run gates',
+        'in context, docs, and skills from the start. Elsewhere one gates only',
+        'under a prefix canon/config/markdown.toml lists, which canon markdown',
+        'gated add writes, and with no such file every density finding reports',
+        'and none gates.',
         'A config that does not parse refuses with its path named.',
         '',
+        'Tables take four limits on the same paths, CLAUDE.md aside: a',
+        '120-character cell, 8 body rows, a list as the next block, and a code',
+        'span with a run past 30 characters. A table finding reports and never',
+        'fails a run.',
+        '',
         'A page whose frontmatter carries kind: reference takes the reference',
         'shape: no H2 beyond Output, Refusals, and See also, each at most once',
         'and in that order, no H3, and no table whose first header cell names',
@@ -361,17 +382,16 @@ async function runAudit(
         bans: scanBans(lines, bans),
         colons: advisory ? findColons(lines) : [],
         headingCase: advisory ? findHeadingCase(source) : [],
-        density: inDensityScope(rel)
-          ? densityFindings(lines).map((finding) => ({
-              ...finding,
-              gating: densityGates(
-                rel,
-                finding.kind,
-                gated.prefixes,
-                gated.alwaysGated,
-              ),
-            }))
-          : [],
+        density: scopedDensityFindings(rel, lines).map((finding) => ({
+          ...finding,
+          gating: densityGates(
+            rel,
+            finding.kind,
+            gated.prefixes,
+            gated.alwaysGated,
+          ),
+        })),
+        tables: inDensityScope(rel) ? tableFindings(lines) : [],
         referenceShape: referenceShapeFindings(source).map((finding) => ({
           ...finding,
           gating: referenceShapeGates(rel, gated.prefixes),
@@ -393,6 +413,7 @@ async function runAudit(
   reportColons(reports)
   reportHeadingCase(reports)
   reportDensity(reports, gated, resolution.source)
+  reportTables(reports)
   reportReferenceShape(reports, gated)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
@@ -430,6 +451,7 @@ async function runAudit(
           colons: report.colons,
           headingCase: report.headingCase,
           density: report.density,
+          tables: report.tables,
           referenceShape: report.referenceShape,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
@@ -643,7 +665,7 @@ function reportDensity(
     `Paragraphs past ${CHECKPOINTS.paragraph} characters, more than 2 paragraphs in a row, bullets past ${CHECKPOINTS.bullet} characters, more than 5 plain bullets in a row, a heading past H3, and an H3 opening with neither a paragraph nor a table.`,
   )
   logInfo(
-    'Measured on context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. Every other path takes no density finding.',
+    'Measured on context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. CLAUDE.md and its seed take the bullet run and the H3 opening inside Key paths alone. Every other path takes no density finding.',
   )
   logInfo(densityGatingLine(gated, source))
 
@@ -695,6 +717,63 @@ function densityGatingLine(
     : `A finding gates under a prefix ${GATED_CONFIG_REL} lists (${listed}). Every other finding reports.`
 }
 
+const TABLE_LABELS: Record<TableKind, string> = {
+  'table-cell': 'cell length',
+  'table-rows': 'rows',
+  'table-then-list': 'list after table',
+  'table-token': 'wide token',
+}
+
+function describeTable(finding: TableFinding): string {
+  const measured =
+    finding.kind === 'table-then-list'
+      ? 'follows the table with no lead sentence'
+      : `${finding.value} past ${finding.limit}`
+  return `  :${finding.line}  ${TABLE_LABELS[finding.kind]}  ${measured}`
+}
+
+/**
+ * Lists every table finding on the density scope's paths. None gates yet,
+ * since a gate is decided per path rather than per kind, and a new density
+ * kind would fail every gated folder carrying a table hit at once.
+ */
+function reportTables(reports: readonly FileReport[]): void {
+  logStep('Tables')
+  logInfo(
+    `Cells past ${TABLE_CELL} characters, tables past ${TABLE_ROWS} body rows, a list directly after a table, and a code span in a cell holding a run past ${TABLE_TOKEN} characters.`,
+  )
+  logInfo(
+    'Measured on the paths density measures in full, so never on CLAUDE.md, outside fenced blocks. This never fails a run.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.tables.length > 0)
+    .sort((a, b) => b.tables.length - a.tables.length)
+
+  if (carrying.length === 0) {
+    logInfo('No table finding.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.tables.length, 0)
+  logWarn(
+    `${plural(total, 'finding')} across ${plural(carrying.length, 'file')}`,
+  )
+  logInfo(
+    'Move a long cell into a bullet under the lead, split a long table into groups each under a lead sentence, give a trailing list its own lead, and move a wide token out of the table.',
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.tables.length, 'finding')}\n${report.tables
+            .map(describeTable)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 const REFERENCE_SHAPE_LABELS: Record<ReferenceShapeKind, string> = {
   'extra-section': 'section outside the shape',
   'section-order': 'section out of order or repeated',

package/src/commands/migrate.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { cliRunner } from '@/gate/sequencer'
 import { listRepositoryFiles } from '@/git/files'
 import { indexSourceRules } from '@/gov/adapter'
 import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
@@ -35,6 +36,7 @@ import {
   SKILL_NAME_MAP,
   SKILL_NAME_RULES,
 } from '@/migrate/skill-names'
+import { readMigrationStatus, statusExitCode } from '@/migrate/status'
 import {
   planSurfaceRootsMove,
   type SurfaceRootsPlan,
@@ -1039,6 +1041,43 @@ function toSessionDefaultsRecord(
   }
 }
 
+interface StatusOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
+/**
+ * Lists every migration a project still needs by running each subcommand's own
+ * dry run, so it reads the contract they share and writes nothing.
+ */
+async function runStatus(opts: StatusOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const report = await readMigrationStatus(cliRunner(root))
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: report.refused === 0, ...report })}\n`,
+    )
+  }
+
+  for (const entry of report.migrations) {
+    if (entry.state === 'pending') logInfo(`Pending: ${entry.verb}`)
+    if (entry.state === 'refused') {
+      logError(`Refused: ${entry.verb}: ${entry.reason ?? 'no reason given'}`)
+    }
+  }
+
+  if (report.pending === 0 && report.refused === 0) {
+    logInfo('No migration is pending.')
+  }
+
+  return statusExitCode(report)
+}
+
 export function register(program: Command): void {
   const migrate = program
     .command('migrate')
@@ -1446,4 +1485,42 @@ export function register(program: Command): void {
     .action(async (opts: SessionDefaultsOptions) => {
       process.exitCode = await runSessionDefaults(opts)
     })
+
+  migrate
+    .command('status')
+    .description('List every migration a project still needs, in run order')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Runs each migrate subcommand as a dry run and sorts it by its exit',
+        'code, in the order a project runs them, records first. It passes',
+        'no --write and writes nothing. A migration is pending or not, with',
+        "the subcommand's own record attached, since the records share no",
+        'count field.',
+        '',
+        "Each dry run reads today's tree, so a clean entry can turn pending",
+        'once an earlier one is applied. Run status again after each --write.',
+        '',
+        'Exit codes:',
+        '  0  no migration is pending',
+        '  1  a subcommand refused, which outranks a pending plan',
+        '  2  at least one migration is pending',
+        '',
+        'Examples:',
+        '  canon migrate status',
+        '  canon migrate status --json',
+        '  canon migrate status --root ../project',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: StatusOptions) => {
+      process.exitCode = await runStatus(opts)
+    })
 }