@erclx/canon 5.35.0 → 5.37.0

package/src/commands/init.ts

@@ -37,10 +37,19 @@ export function register(program: Command): void {
         '',
         'Passing any option skips the confirmation prompt.',
         '',
+        'Runs `canon tooling sync base --write` first, which replaces every',
+        'base golden config the target holds, then `canon claude init`,',
+        '`canon gov install`, and `canon wiki init`. Refuses a target that is',
+        'not a directory or is the toolkit root.',
+        '',
+        'Exit codes:',
+        '  0  every domain installed, or the prompt was cancelled',
+        '  1  the target was refused, or a domain failed, named on stderr',
+        '',
         'Examples:',
         '  canon init',
         '  canon init ../my-app',
-        '  canon init --stack node --add 210-astro,260-shadcn ../my-app',
+        '  canon init --stack node --add astro,shadcn ../my-app',
         '  canon init --skip governance ../my-app',
         '',
       ].join('\n'),

package/src/commands/markdown.ts

@@ -3,9 +3,14 @@ import { readFile } from 'node:fs/promises'
 import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
-import { lengthExemption } from '@/markdown/ceiling'
+import { isChangelog, lengthExemption } from '@/markdown/ceiling'
+import { type ColonFinding, findColons } from '@/markdown/colons'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
+import {
+  findHeadingCase,
+  type HeadingCaseFinding,
+} from '@/markdown/heading-case'
 import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
 import {
   type BanFinding,
@@ -13,6 +18,7 @@ import {
   bodyLines,
   scanBans,
 } from '@/markdown/scan'
+import { bulletStacks, CAP, type StackFinding } from '@/markdown/stacks'
 import {
   BASELINE,
   CHECKPOINTS,
@@ -52,6 +58,9 @@ interface FileReport {
   readonly rel: string
   readonly bans: readonly BanFinding[]
   readonly links: readonly LinkFinding[]
+  readonly colons: readonly ColonFinding[]
+  readonly headingCase: readonly HeadingCaseFinding[]
+  readonly bulletStacks: readonly StackFinding[]
   readonly structure: StructureReport
   readonly renderedLines: number
   /** The stated reason, or null where the document is not exempt. */
@@ -90,6 +99,14 @@ export function register(program: Command): void {
         'Bullet, paragraph, and depth weight are judgments a reader settles,',
         'so all three report and none of them fails a run.',
         '',
+        'A mid-sentence colon and a heading with a capital after its first word',
+        'report the same way. A proper noun is the one case the second cannot',
+        'tell from title case, and the first is sometimes right.',
+        '',
+        'Bullet stacks report a run of more than 5 plain bullets under one',
+        'heading and never exit 2. The Bullet stacks gate stage owns that',
+        'verdict, for the reason the length line below states.',
+        '',
         'Length reports a whole document past the ceiling and never exits 2.',
         'The Document ceiling gate stage owns that verdict, since this audit also',
         'runs on a record kept out of version control, where a long plan is not',
@@ -100,7 +117,7 @@ export function register(program: Command): void {
         'it correctly and a flat paragraph there is not a defect.',
         '',
         'Rewrite the sentence carrying a hit rather than swapping the token for',
-        'a near-synonym. A code span clears the report and is the answer only',
+        'a near-synonym or a colon or a comma. A code span clears the report and is the answer only',
         'where the token is genuinely an identifier under discussion, which is',
         'what markdown.md reserves the span for.',
         '',
@@ -160,9 +177,14 @@ async function runAudit(
       const abs = resolve(root, rel)
       const source = await readFile(abs, 'utf8')
       const lines = bodyLines(source)
+      // The release tool writes a changelog, so neither advisory reads it.
+      const advisory = !isChangelog(rel)
       return {
         rel,
         bans: scanBans(lines, bans),
+        colons: advisory ? findColons(lines) : [],
+        headingCase: advisory ? findHeadingCase(source) : [],
+        bulletStacks: advisory ? bulletStacks(lines) : [],
         links: findBrokenLinks(lines, (path) =>
           existsSync(resolve(dirname(abs), path)),
         ),
@@ -177,6 +199,9 @@ async function runAudit(
   reportScope(scope.files, scope.unmatched)
   reportBans(reports, bans, empty)
   reportLinks(reports, root)
+  reportColons(reports)
+  reportHeadingCase(reports)
+  reportStacks(reports)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -210,6 +235,9 @@ async function runAudit(
           path: report.rel,
           bans: report.bans,
           links: report.links,
+          colons: report.colons,
+          headingCase: report.headingCase,
+          bulletStacks: report.bulletStacks,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -230,6 +258,9 @@ async function runAudit(
     bans: reports.flatMap((report) => report.bans),
     links: reports.flatMap((report) => report.links),
     structure: reports.map((report) => report.structure),
+    colons: reports.flatMap((report) => report.colons),
+    headingCase: reports.flatMap((report) => report.headingCase),
+    bulletStacks: reports.flatMap((report) => report.bulletStacks),
   })
 
   return gating ? EXIT_GATE : 0
@@ -310,7 +341,7 @@ function reportBans(
   logWarn(`${plural(total, 'hit')} across ${plural(carrying.length, 'file')}`)
   logWarn('This fails the run. Every other check below reports.')
   logInfo(
-    'Rewrite the sentence rather than swapping the token for a near-synonym.',
+    "Rewrite the sentence rather than swapping the token for a near-synonym, or a colon or a comma in the dash's place. That is the same sentence.",
   )
   logInfo(
     'A code span clears the report and is the answer only where the token is genuinely an identifier under discussion, which is what markdown.md reserves the span for.',
@@ -383,6 +414,120 @@ function reportLinks(reports: readonly FileReport[], root: string): void {
   )
 }
 
+function reportStacks(reports: readonly FileReport[]): void {
+  logStep('Bullet stacks')
+  logInfo(
+    `A run of more than ${CAP} top-level bullets, with no paragraph or heading between them.`,
+  )
+  logInfo(
+    'A run whose every item opens with a bold label or a link is exempt. This never fails a run. The Bullet stacks gate stage owns that verdict.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.bulletStacks.length > 0)
+    .sort((a, b) => longestStack(b) - longestStack(a))
+
+  if (carrying.length === 0) {
+    logInfo(`No run past ${CAP} bullets.`)
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.bulletStacks.length,
+    0,
+  )
+  logWarn(`${plural(total, 'stack')} across ${plural(carrying.length, 'file')}`)
+  logInfo(
+    'Fold the run into prose, give each item an H3, or split the list at its seam.',
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.bulletStacks.length, 'stack')}\n${report.bulletStacks
+            .map((found) => `  :${found.line}  ${found.count} bullets`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+function longestStack(report: FileReport): number {
+  return Math.max(0, ...report.bulletStacks.map((found) => found.count))
+}
+
+function reportColons(reports: readonly FileReport[]): void {
+  logStep('Colons')
+  logInfo(
+    'A colon followed by more text in a prose line, outside a label, a code span, and a link.',
+  )
+  logInfo(
+    'A heading, a table row, a fenced block, and a line-final colon are excluded. This never fails a run.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.colons.length > 0)
+    .sort((a, b) => b.colons.length - a.colons.length)
+
+  if (carrying.length === 0) {
+    logInfo('No colon joining two clauses.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.colons.length, 0)
+  logWarn(`${plural(total, 'colon')} across ${plural(carrying.length, 'file')}`)
+  logInfo(
+    'Split the sentence or rewrite it. A colon belongs after a label or at the end of a line introducing a list.',
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.colons.length, 'colon')}\n${report.colons
+            .map((found) => `  :${found.line}:${found.column + 1}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+function reportHeadingCase(reports: readonly FileReport[]): void {
+  logStep('Heading case')
+  logInfo(
+    'A heading or frontmatter title with a capitalized word after its first, outside code spans and all-caps tokens.',
+  )
+  logInfo(
+    'A proper noun reports too and is left as it is. This never fails a run.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.headingCase.length > 0)
+    .sort((a, b) => b.headingCase.length - a.headingCase.length)
+
+  if (carrying.length === 0) {
+    logInfo('No heading carrying a capital after its first word.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.headingCase.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'heading')} across ${plural(carrying.length, 'file')}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.headingCase.length, 'heading')}\n${report.headingCase
+            .map((found) => `  :${found.line}  ${found.text}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportBullets(
   reports: readonly FileReport[],
   checkpoints: Checkpoints,

package/src/commands/pr.ts

@@ -44,7 +44,7 @@ import {
   settleChecklist,
 } from '@/pr/evidence'
 import {
-  dropFrames,
+  dropFramesWithLegacy,
   FRAMES_BRANCH,
   type FramesApi,
   type FramesRefusal,
@@ -53,7 +53,8 @@ import {
   isFrameHead,
   isFramePass,
   isFrameTheme,
-  pruneFrames,
+  LEGACY_FRAMES_BRANCH,
+  pruneFramesWithLegacy,
   pushFrame,
   readFrame,
   type TreeEntry,
@@ -933,7 +934,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        `Writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
+        `An add writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
         'with --theme, and `link` names that',
@@ -948,6 +949,11 @@ export function register(program: Command): void {
         'request still open, reopened, closed exactly the given days ago, or one',
         'whose state could not be read, listing that last kind under `unread`.',
         '',
+        `Both also drain the ${LEGACY_FRAMES_BRANCH} branch a rename left behind,`,
+        'removing only, and carry `legacy: true` when it changed. --prune empties',
+        'it as its pull requests expire, and --drop clears one pull request at',
+        'once. An add never writes it.',
+        '',
         'Read `reason` on the JSON record:',
         '  ok                an add pushed, or a drop or prune finished',
         '  bad-mode          not exactly one of --add, --drop, --prune',
@@ -2876,13 +2882,13 @@ function isTreeEntry(value: unknown): value is TreeEntry {
  * that already exists or no longer does, which is another writer's doing and
  * worth a re-read rather than a failure.
  */
-function ghFramesApi(call: ApiCaller): FramesApi {
-  const ref = `git/refs/heads/${FRAMES_BRANCH}`
+function ghFramesApi(call: ApiCaller, branch: string): FramesApi {
+  const ref = `git/refs/heads/${branch}`
   const refWrite = (result: ApiCall) =>
     result.ok ? 'ok' : result.status === 422 ? 'conflict' : 'failed'
   return {
     async readTip() {
-      const head = await call('GET', `git/ref/heads/${FRAMES_BRANCH}`)
+      const head = await call('GET', `git/ref/heads/${branch}`)
       if (!head.ok) {
         return head.status === 404
           ? { kind: 'missing' }
@@ -2937,7 +2943,7 @@ function ghFramesApi(call: ApiCaller): FramesApi {
     async createRef(commit) {
       return refWrite(
         await call('POST', 'git/refs', {
-          ref: `refs/heads/${FRAMES_BRANCH}`,
+          ref: `refs/heads/${branch}`,
           sha: commit,
         }),
       )
@@ -3034,7 +3040,8 @@ async function runFrames(
 
   if (Bun.which('gh') === null) return refuseFrames('gh-missing')
   const runner = ghApiRunner(root)
-  const api = ghFramesApi(runner.call)
+  const api = ghFramesApi(runner.call, FRAMES_BRANCH)
+  const legacyApi = ghFramesApi(runner.call, LEGACY_FRAMES_BRANCH)
   const refuseWrite = (reason: FramesRefusal) =>
     refuseFrames(
       reason === 'push-failed' && runner.refusedWrites.length > 0
@@ -3059,7 +3066,7 @@ async function runFrames(
 
   if (opts.prune !== undefined) {
     const days = Number(opts.prune)
-    const result = await pruneFrames(api, days, new Date())
+    const result = await pruneFramesWithLegacy(api, legacyApi, days, new Date())
     if (result.kind === 'refused') return refuseWrite(result.reason)
     const { kind: _kind, ...rest } = result
     return finish({ days, ...rest }, [
@@ -3072,7 +3079,7 @@ async function runFrames(
 
   const pull = Number(number)
   if (opts.drop === true) {
-    const result = await dropFrames(api, [pull])
+    const result = await dropFramesWithLegacy(api, legacyApi, [pull])
     if (result.kind === 'refused') return refuseWrite(result.reason)
     const { kind: _kind, ...rest } = result
     return finish({ number: pull, ...rest }, [

package/src/commands/records.ts

@@ -81,7 +81,7 @@ export function register(program: Command): void {
   const records = program
     .command('records')
     .description(
-      'Check a governed corpus against its standard, and back up the session records under .claude/',
+      'Check a governed corpus against its standard, and back up the session records under .canon/',
     )
     .helpOption('-h, --help', 'Show this help message')
 

package/src/commands/sync.ts

@@ -57,6 +57,17 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Runs `canon gov sync`, `canon design sync`, and `canon claude sync`',
+        'on each domain installed, so each carries its own replace behavior:',
+        'governance replaces an edited rule and deletes a retired one, design',
+        'replaces its shipped files, and claude writes .gitignore alone.',
+        'Tooling is not synced. Refuses a dirty working tree.',
+        '',
+        'Exit codes:',
+        '  0  synced, no domain installed, or --check without --exit-code',
+        '  1  the target or a dirty tree was refused, opening the pull request',
+        '     failed, or --check --exit-code found drift',
         '',
         'Examples:',
         '  canon sync',

package/src/commands/tooling.ts

@@ -106,6 +106,14 @@ export function register(program: Command): void {
         'what `canon sync --check --exit-code` spells with a flag. Pass --check',
         'to report the same list and always exit 0.',
         '',
+        '--write replaces every golden config that differs from the stack.',
+        'Seeds are copy-once, so a seed the target already holds is left alone.',
+        '',
+        'Exit codes:',
+        '  0  synced, up to date, cancelled, or run with --check',
+        '  1  refused, or run headlessly with neither flag while a file would',
+        '     be replaced',
+        '',
       ].join('\n'),
     )
     .action(

package/src/context/audit.ts

@@ -63,6 +63,22 @@ export const REQUIRED_SECTIONS_BY_FOLDER: Readonly<
   context: ['Overview', 'Layout'],
 }
 
+/**
+ * The closed set of H2 sections per audited folder name, which a required
+ * section belongs to. An entry carrying another H2 is a finding under
+ * `--gate`, since the set is what makes a context entry cheap to find a fact
+ * in: a domain's own topic names go one level down as H3 items under
+ * `Decisions` and `Gotchas`.
+ *
+ * Held beside the required lists for the same reason they are held here, and
+ * keyed on the folder whose standard states it.
+ */
+export const ALLOWED_SECTIONS_BY_FOLDER: Readonly<
+  Record<string, readonly string[]>
+> = {
+  context: ['Overview', 'Layout', 'Decisions', 'Gotchas'],
+}
+
 /**
  * The context standard's list, kept as its own export because the audit record
  * has published it flat under `checkpoints.requiredSections` since before any
@@ -225,6 +241,12 @@ export interface EntryReport {
    * is `missingSections`, since one entry answers for its siblings.
    */
   readonly sections: readonly string[]
+  /**
+   * H2 headings outside the folder's closed set, in document order, and empty
+   * outside a folder whose standard states one. What the folder carries in
+   * all is `extraSections`.
+   */
+  readonly otherSections: readonly string[]
   /**
    * Whether the file declares itself a skeleton, which excludes it from the
    * section check alone. Every other measure still reads it, since a stub is
@@ -281,6 +303,13 @@ export interface LengthFinding {
   readonly causes: readonly LengthCause[]
 }
 
+export interface ExtraSectionFinding {
+  /** Repo-relative path of the entry carrying the headings. */
+  readonly rel: string
+  /** H2 headings outside the closed set, never empty. */
+  readonly headings: readonly string[]
+}
+
 export interface SectionFinding {
   /**
    * Repo-relative path of whatever owes the sections: the entry itself in the
@@ -442,6 +471,33 @@ function declaredSections(
   return required.filter((section) => found.has(section))
 }
 
+const H2_TEXT = /^##\s+(.+?)\s*$/
+
+/**
+ * Finds the H2 headings outside the allowed set.
+ *
+ * H2 only, since the set closes the sections of an entry and says nothing of
+ * where its H3 items sit. Fenced blocks are skipped, so a template quoted
+ * inside an example declares nothing about the entry quoting it.
+ */
+function otherSections(
+  lines: readonly BodyLine[],
+  allowed: readonly string[],
+): string[] {
+  if (allowed.length === 0) return []
+
+  const found: string[] = []
+
+  for (const line of lines) {
+    if (line.fenced) continue
+
+    const match = line.text.match(H2_TEXT)
+    if (match && !allowed.includes(match[1])) found.push(match[1])
+  }
+
+  return found
+}
+
 /**
  * Finds the references naming a sibling entry by bare filename.
  *
@@ -500,6 +556,7 @@ export function measureEntry(
   governsContent = true,
   siblings: readonly string[] = [],
   required: readonly string[] = governsContent ? REQUIRED_SECTIONS : [],
+  allowed: readonly string[] = [],
 ): EntryReport {
   const lines = bodyLines(source)
 
@@ -510,6 +567,7 @@ export function measureEntry(
     provenance: governsContent ? provenance(lines) : [],
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
+    otherSections: otherSections(lines, allowed),
     stub: isStubSeed(source),
     governed: governsContent,
   }
@@ -589,6 +647,7 @@ export async function measureFolders(
           governsContent(folder),
           names.filter((name) => name !== self),
           requiredSections(folder),
+          allowedSections(folder),
         ),
       )
     }
@@ -609,6 +668,13 @@ export function requiredSections(folder: AuditedFolder): readonly string[] {
     : []
 }
 
+/** Names the H2 sections the folder's standard allows, empty where it states no set. */
+export function allowedSections(folder: AuditedFolder): readonly string[] {
+  return Object.hasOwn(ALLOWED_SECTIONS_BY_FOLDER, folder.name)
+    ? ALLOWED_SECTIONS_BY_FOLDER[folder.name]
+    : []
+}
+
 /**
  * Reports whether a bare sibling name here is a reference by construction.
  *
@@ -688,3 +754,20 @@ export function missingSections(
 
   return findings
 }
+
+/**
+ * Names each entry carrying an H2 outside its folder's closed set.
+ *
+ * Per entry rather than per folder, unlike `missingSections`: a split folder's
+ * entries each answer for their own headings, since an extra section is a fact
+ * about the file it sits in. A stub seed is dropped for the reason
+ * `missingSections` drops one, a skeleton being exempt from the shape rather
+ * than from being well formed.
+ */
+export function extraSections(
+  entries: readonly EntryReport[],
+): ExtraSectionFinding[] {
+  return entries
+    .filter((entry) => !entry.stub && entry.otherSections.length > 0)
+    .map((entry) => ({ rel: entry.rel, headings: entry.otherSections }))
+}

package/src/context/classify/prompts.ts

@@ -2,7 +2,10 @@
  * System prompts and user-message builders for the model layer, ported
  * verbatim as data from the groundwork spike at
  * `.canon/groundwork/93-canonical-doc-drift/scripts/prompts/v3.md` (diff
- * mode) and `sweep-v1.md` (sweep mode). Neither prompt text is invented here.
+ * mode) and `sweep-v1.md` (sweep mode). The diff prompt is verbatim. The sweep
+ * prompt was tuned past `sweep-v1.md` with one decision check, measured
+ * against the groundwork's labelled set in
+ * `canon/context/context-model/overview.md`.
  *
  * Each prompt already states its own rules per canonical doc type inside one
  * string, which is the shape the spike measured, so there is one prompt per
@@ -45,6 +48,8 @@ Decision checks, in order:
 1. Judge what the text says, not how long it is. A long section that states current design once is KEEP.
 2. A trailing "Measured at <sha> on <date>" does not make a paragraph current if another paragraph in the section states an older value on the same subject.
 3. Short rationale for a current rule ("the form checks length itself because...") is KEEP. A story of the rounds that produced the rule is REWRITE.
+4. Rationale is KEEP even when it is told in the past tense. A reason naming why an alternative was left out, what an earlier approach got wrong, what a measurement caught, or what a past run cost is the evidence for the current rule, so a sentence such as "the first form timed out" or "two runs took 1281s and 1924s" or "reading figures from real data caught three wrong claims" supports a rule that stands and stays KEEP. Past tense alone is never the test.
+5. REWRITE needs the section to restate its own subject as a sequence: a superseded figure kept beside its replacement, "now" or "no longer" marking a change, branch or PR narration, or rounds of candidates. A maintenance step or an operator decision stated as a rule is current, not history.
 
 Return only JSON: {"verdict": "...", "quotes": ["<up to three short phrases copied from the section that decided it>"], "reason": "<one sentence>"}
 `

package/src/context/gate.ts

@@ -1,4 +1,4 @@
-import type { SectionFinding } from '@/context/audit'
+import type { ExtraSectionFinding, SectionFinding } from '@/context/audit'
 import type { FolderDrift } from '@/context/index-drift'
 
 export interface GateInput {
@@ -13,6 +13,8 @@ export interface GateInput {
    */
   readonly requirementsOverWords: boolean
   readonly sections: readonly SectionFinding[]
+  /** H2 headings outside a folder's closed set, gating under `--gate` alone. */
+  readonly extraSections: readonly ExtraSectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
@@ -36,7 +38,7 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
  * does a requirements record past its own word cap: the record states its rule
  * for itself, which makes it a fact rather than a threshold a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
- * declare, and an index disagreeing with its folder. Entry length, depth, bullet,
+ * declare, an H2 outside the closed set, and an index disagreeing with its folder. Entry length, depth, bullet,
  * table, provenance, and the record's claim coverage are judgments, so they
  * stay out under both modes.
  */
@@ -44,6 +46,7 @@ export function isGating({
   unresolvedCitations,
   requirementsOverWords,
   sections,
+  extraSections,
   drift,
   widened,
 }: GateInput): boolean {
@@ -51,5 +54,5 @@ export function isGating({
   if (requirementsOverWords) return true
   if (!widened) return false
 
-  return sections.length > 0 || hasDrift(drift)
+  return sections.length > 0 || extraSections.length > 0 || hasDrift(drift)
 }

package/src/design/budget.ts

@@ -1,3 +1,5 @@
+import { canonicalHeading } from '@/design/parse'
+
 /**
  * The prose budget `claude/skills/canvas-board/references/design.md` sets for a design record, and the
  * counter the `design` gate stage reads it through.
@@ -11,21 +13,23 @@
  * `<` is dropped the way `prose()` drops it, and so is a fenced block or an
  * HTML comment spanning several lines, which `prose()` would read in part. A
  * `###` subsection counts toward the `##` section holding it, since the
- * standard fixes the sections and a subheading is no way past the cap.
+ * standard fixes the sections and a subheading is no way past the cap. A
+ * legacy `## Personality` takes the Overview cap through the parser's alias,
+ * and a finding names the heading as the record wrote it.
  */
 export const DESIGN_BUDGET = {
   /** Words before the first `##` section, the title excluded. */
   leadWords: 40,
-  /** Words in `## Personality`, held to one paragraph. */
-  personalityWords: 60,
-  personalityParagraphs: 1,
+  /** Words in `## Overview`, held to one paragraph. */
+  overviewWords: 60,
+  overviewParagraphs: 1,
   /** Bullets or paragraphs in any other section, beside its table. */
   rules: 3,
   /** Words in one of those rules, the proxy for one line. */
   ruleWords: 25,
 } as const
 
-const PERSONALITY = 'Personality'
+const OVERVIEW = 'Overview'
 
 /** A list item at any depth, which starts a rule of its own. */
 const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/
@@ -52,15 +56,15 @@ export function measureDesignProse(source: string): string[] {
           `The lead holds ${total} words against a cap of ${DESIGN_BUDGET.leadWords}`,
         )
       }
-    } else if (section.heading === PERSONALITY) {
-      if (rules.length > DESIGN_BUDGET.personalityParagraphs) {
+    } else if (canonicalHeading(section.heading) === OVERVIEW) {
+      if (rules.length > DESIGN_BUDGET.overviewParagraphs) {
         findings.push(
-          `${PERSONALITY} holds ${rules.length} paragraphs against a cap of ${DESIGN_BUDGET.personalityParagraphs}`,
+          `${section.heading} holds ${rules.length} paragraphs against a cap of ${DESIGN_BUDGET.overviewParagraphs}`,
         )
       }
-      if (total > DESIGN_BUDGET.personalityWords) {
+      if (total > DESIGN_BUDGET.overviewWords) {
         findings.push(
-          `${PERSONALITY} holds ${total} words against a cap of ${DESIGN_BUDGET.personalityWords}`,
+          `${section.heading} holds ${total} words against a cap of ${DESIGN_BUDGET.overviewWords}`,
         )
       }
     } else {

package/src/design/document.ts

@@ -114,10 +114,10 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
     '',
     LEAD,
     '',
-    section('Personality', tokens.personality),
+    section('Overview', tokens.personality),
     '',
     section(
-      'Color',
+      'Colors',
       bullets(tokens.colorRules),
       formatTable(['Role', 'Intent', 'Value'], colorRows(tokens.color)),
     ),
@@ -137,8 +137,10 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       formatTable(['Step', 'Multiplier', 'Value'], spaceRows(tokens.spacing)),
     ),
     '',
+    section('Layout', bullets(tokens.layout)),
+    '',
     section(
-      'Borders',
+      'Shapes',
       bullets(tokens.bordersRules),
       formatTable(
         ['Role', 'Radius', 'Width', 'When used'],
@@ -146,8 +148,6 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       ),
     ),
     '',
-    section('Layout', bullets(tokens.layout)),
-    '',
     section('Motion', bullets(tokens.motion)),
     '',
     section('Iconography', bullets(tokens.iconography)),