@erclx/canon 5.35.0 → 5.37.0

package/src/markdown/colons.ts

@@ -0,0 +1,86 @@
+import { type BodyLine, LINK, maskDisplayed } from '@/markdown/scan'
+
+export interface ColonFinding {
+  readonly line: number
+  /** Zero-based, the colon itself. */
+  readonly column: number
+  /** The whole source line, so a reader can match it against new text. */
+  readonly text: string
+  /**
+   * The run of non-space characters ending at the colon. A hook matches it
+   * against new text, since `column` is a UTF-16 offset that a reader counting
+   * code points would misplace after an emoji.
+   */
+  readonly lead: string
+}
+
+const HEADING = /^#{1,6}\s/
+const TABLE_ROW = /^\s*\|/
+const LIST_MARKER = /^\s*(?:[-*+]|\d+[.)])\s+/
+const QUOTE_MARKER = /^(?:\s*>\s?)+/
+
+/** A colon followed by whitespace and more text, ruling out `10:30` and a scheme. */
+const COLON = /:(?=\s+\S)/g
+
+const BOLD_LABEL = /^(\*\*|__)[^*_]+\1$/
+
+/** Blanks a span while holding its width, so a column stays where it was. */
+function blank(match: string): string {
+  return ' '.repeat(match.length)
+}
+
+/**
+ * Whether the text before a line's first colon is a label rather than a
+ * clause: the lead of a list item, or a prefix that is only emphasis and a
+ * masked code span.
+ */
+function isLabel(prefix: string, listItem: boolean): boolean {
+  if (BOLD_LABEL.test(prefix.trim())) return true
+
+  const words = prefix.replace(/[*_]/g, ' ').trim()
+  if (words === '') return true
+  return listItem && words.split(/\s+/).length <= 4
+}
+
+/**
+ * Finds a colon joining two clauses in the middle of a prose sentence.
+ *
+ * A heading, a table row, a fence, a code span, a link, and a line-final colon
+ * are left alone, and so is the first colon of a list item or of a line opening
+ * on a bold or code label. The measure is advisory, because a colon is
+ * sometimes right and the corpus count shows a gate would be a sweep nobody
+ * asked for.
+ */
+export function findColons(lines: readonly BodyLine[]): ColonFinding[] {
+  const found: ColonFinding[] = []
+
+  for (const line of lines) {
+    if (line.fenced || HEADING.test(line.text) || TABLE_ROW.test(line.text)) {
+      continue
+    }
+
+    const masked = maskDisplayed(line.text.replace(LINK, blank))
+    const quote = QUOTE_MARKER.exec(masked)?.[0] ?? ''
+    const marker = LIST_MARKER.exec(masked.slice(quote.length))?.[0] ?? ''
+    const start = quote.length + marker.length
+    let labelled = false
+
+    for (const match of masked.matchAll(COLON)) {
+      if (match.index < start) continue
+
+      if (!labelled) {
+        labelled = true
+        if (isLabel(masked.slice(start, match.index), marker !== '')) continue
+      }
+
+      found.push({
+        line: line.number,
+        column: match.index,
+        text: line.text,
+        lead: line.text.slice(0, match.index).replace(/^.*\s/, ''),
+      })
+    }
+  }
+
+  return found
+}

package/src/markdown/gate.ts

@@ -1,5 +1,8 @@
+import type { ColonFinding } from '@/markdown/colons'
+import type { HeadingCaseFinding } from '@/markdown/heading-case'
 import type { LinkFinding } from '@/markdown/links'
 import type { BanFinding } from '@/markdown/scan'
+import type { StackFinding } from '@/markdown/stacks'
 import type { StructureReport } from '@/markdown/structure'
 
 export interface GateInput {
@@ -16,6 +19,28 @@ export interface GateInput {
    * alone states the same rule and leaves no place to assert it.
    */
   readonly structure: readonly StructureReport[]
+  /**
+   * Every mid-sentence colon the run measured, read by nothing here.
+   *
+   * A colon is sometimes right and the corpus carries over a thousand
+   * candidates, so the measure warns and a push never fails on it.
+   */
+  readonly colons: readonly ColonFinding[]
+  /**
+   * Every heading or title with a capital after its first word, read by
+   * nothing here. A proper noun is the one case it cannot tell from title
+   * case, and gating it would need a names list and an escape marker.
+   */
+  readonly headingCase: readonly HeadingCaseFinding[]
+  /**
+   * Every run of plain bullets past the cap, read by nothing here.
+   *
+   * The stage that gates it is `bullet-stacks` in `src/gate/stages.ts`, which
+   * reads a scope of tracked files. This audit also runs on plans and
+   * groundwork records kept out of version control, where a long list is not
+   * a defect, which is the reason `documentCeiling` gates apart from it too.
+   */
+  readonly bulletStacks: readonly StackFinding[]
 }
 
 /**

package/src/markdown/growth.ts

@@ -0,0 +1,43 @@
+import { bodyLines } from '@/markdown/scan'
+import {
+  CHECKPOINTS,
+  type Checkpoints,
+  type LongBlock,
+  longBlocks,
+} from '@/markdown/structure'
+
+/**
+ * Reduces text to the words a reader meets, so a block reflowed, re-marked, or
+ * moved under another heading still matches the copy it came from.
+ *
+ * List markers and emphasis marks are dropped because turning a bullet into a
+ * labelled bullet or a paragraph changes the shape of a statement and none of
+ * its words, which is the edit the sweep makes. A word changed is a text
+ * changed, and that is what the growth stage exists to see.
+ */
+export function normalizeProse(text: string): string {
+  return text
+    .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
+    .replace(/[*_]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * The paragraphs and top-level bullets of `source` past their checkpoints whose
+ * text appears nowhere in `base`.
+ *
+ * Containment rather than line matching, so an unchanged long block passes
+ * wherever it sits and an edited or new one fails. `base` is every document the
+ * caller counts as the copy it may have come from, already normalized, since a
+ * block moved into a sibling entry is as unchanged as one left in place.
+ */
+export function grownBlocks(
+  source: string,
+  base: string,
+  checkpoints: Checkpoints = CHECKPOINTS,
+): LongBlock[] {
+  return longBlocks(bodyLines(source), checkpoints).filter(
+    (block) => !base.includes(normalizeProse(block.text)),
+  )
+}

package/src/markdown/heading-case.ts

@@ -0,0 +1,74 @@
+import { bodyLines, maskDisplayed } from '@/markdown/scan'
+
+export interface HeadingCaseFinding {
+  readonly line: number
+  /** The heading or title as written, markers removed. */
+  readonly text: string
+  /** Every word after the first that opens on a capital. */
+  readonly words: readonly string[]
+}
+
+const HEADING = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/
+const TITLE = /^title:\s*(["']?)(.*?)\1\s*$/
+const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
+const CAPITALIZED = /^[A-Z][a-z]/
+
+/**
+ * The words of `text` that break sentence case.
+ *
+ * A code span stands for one lowercase word, so a heading opening on one
+ * counts that span as its first word. The first word with a letter in it is
+ * exempt, which keeps a leading numeral from promoting the next word.
+ */
+function capitalizedAfterFirst(text: string): string[] {
+  const masked = maskDisplayed(text.replace(CODE_SPAN, 'code'))
+    .replace(/\s+/g, ' ')
+    .trim()
+  const words = masked === '' ? [] : masked.split(' ')
+  const flagged: string[] = []
+  let seenFirst = false
+
+  for (const raw of words) {
+    const word = raw.replace(/^[^\p{L}]+/u, '')
+    if (!/\p{L}/u.test(raw)) continue
+    if (!seenFirst) {
+      seenFirst = true
+      continue
+    }
+    if (CAPITALIZED.test(word)) flagged.push(word)
+  }
+
+  return flagged
+}
+
+/**
+ * Finds a heading or a frontmatter `title` carrying a capitalized word after
+ * its first, outside code spans and all-caps tokens.
+ *
+ * A proper noun is the one case it cannot tell from title case, so the finding
+ * is a warning and no names list backs it.
+ */
+export function findHeadingCase(source: string): HeadingCaseFinding[] {
+  const found: HeadingCaseFinding[] = []
+  const check = (line: number, text: string): void => {
+    const words = capitalizedAfterFirst(text)
+    if (words.length > 0) found.push({ line, text, words })
+  }
+
+  const frontmatter = FRONTMATTER.exec(source)
+  if (frontmatter) {
+    for (const [index, text] of frontmatter[1].split('\n').entries()) {
+      const title = TITLE.exec(text)
+      if (title) check(index + 2, title[2])
+    }
+  }
+
+  for (const line of bodyLines(source)) {
+    if (line.fenced) continue
+    const heading = HEADING.exec(line.text)
+    if (heading) check(line.number, heading[1])
+  }
+
+  return found
+}

package/src/markdown/stacks.ts

@@ -0,0 +1,74 @@
+import type { BodyLine } from '@/markdown/scan'
+
+/**
+ * The most plain bullets one run may carry. Past it a reader holds the list as
+ * a whole rather than item by item, and the shape wants prose, an H3 per item,
+ * or a split at the seam.
+ */
+export const CAP = 5
+
+/** A top-level bullet marker followed by its content, at column zero only. */
+const BULLET = /^[-*+][ \t]+(.*)$/
+
+/**
+ * An item opening with a bold label or a link names its own subject. A task
+ * box (`[ ]`, `[x]`) opens with a bracket too and is not a link, so a checklist
+ * counts as a plain run.
+ */
+const LABELED = /^(?:\*\*|__|\[(?![ xX]\]))/
+
+export interface StackFinding {
+  /** The line of the run's first item, as an editor numbers it. */
+  readonly line: number
+  readonly count: number
+}
+
+interface Run {
+  readonly line: number
+  count: number
+  labeled: number
+}
+
+/**
+ * Every run of top-level bullets past `CAP`, in document order.
+ *
+ * A run is consecutive column-zero `-`, `*`, or `+` items. A blank line, an
+ * indented continuation, and a nested item do not break it, and any other
+ * column-zero line does, since a paragraph or heading between two lists makes
+ * them two. Fenced lines are skipped rather than breaking the run, so a code
+ * block inside an item does not split it. A run whose every item opens with a
+ * bold label or a link is exempt, because each item carries its own subject
+ * and reads as a table of entries rather than a list to hold.
+ *
+ * Numbered items do not count: a numbered list states an order the reader
+ * follows one step at a time.
+ */
+export function bulletStacks(lines: readonly BodyLine[]): StackFinding[] {
+  const found: StackFinding[] = []
+  let run: Run | undefined
+
+  const close = (): void => {
+    if (run && run.count > CAP && run.labeled < run.count) {
+      found.push({ line: run.line, count: run.count })
+    }
+    run = undefined
+  }
+
+  for (const { number, text, fenced } of lines) {
+    if (fenced) continue
+    if (text.trim() === '' || /^\s/.test(text)) continue
+
+    const match = BULLET.exec(text)
+    if (!match) {
+      close()
+      continue
+    }
+
+    run ??= { line: number, count: 0, labeled: 0 }
+    run.count++
+    if (LABELED.test(match[1])) run.labeled++
+  }
+
+  close()
+  return found
+}

package/src/markdown/structure.ts

@@ -109,7 +109,7 @@ const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
 export const CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
-  bullet: 400,
+  bullet: 250,
   paragraph: 700,
   sentences: 4,
   renderWidth: 80,
@@ -427,8 +427,28 @@ export function heavyBullets(
   lines: readonly BodyLine[],
   checkpoints: Checkpoints,
 ): BulletFinding[] {
-  const findings: BulletFinding[] = []
-  let open: BulletFinding | null = null
+  return foldBullets(lines, checkpoints).map(({ line, characters }) => ({
+    line,
+    characters,
+  }))
+}
+
+interface FoldedBullet extends BulletFinding {
+  /** The bullet's source lines joined by the space a wrap would have carried. */
+  readonly text: string
+}
+
+/**
+ * The walk `heavyBullets` reports from, keeping each past-checkpoint bullet's
+ * text so `longBlocks` can ask whether a base copy of it exists. One walk
+ * rather than two, for the reason `paragraphBlocks` is shared.
+ */
+function foldBullets(
+  lines: readonly BodyLine[],
+  checkpoints: Checkpoints,
+): FoldedBullet[] {
+  const findings: FoldedBullet[] = []
+  let open: FoldedBullet | null = null
 
   const close = (): void => {
     if (open && open.characters > checkpoints.bullet) findings.push(open)
@@ -450,7 +470,11 @@ export function heavyBullets(
     if (item) {
       close()
       if (item[1].length === 0) {
-        open = { line: line.number, characters: visibleText(text).length }
+        open = {
+          line: line.number,
+          characters: visibleText(text).length,
+          text,
+        }
       }
       continue
     }
@@ -466,6 +490,7 @@ export function heavyBullets(
       open = {
         ...open,
         characters: open.characters + visibleText(text).length + 1,
+        text: `${open.text} ${text}`,
       }
   }
 
@@ -581,6 +606,49 @@ export function heavyParagraphs(
   return findings
 }
 
+export interface LongBlock {
+  readonly kind: 'paragraph' | 'bullet'
+  readonly line: number
+  readonly characters: number
+  /** The block's source lines folded into one, as the paragraph and bullet folds read it. */
+  readonly text: string
+}
+
+/**
+ * The paragraphs past the paragraph checkpoint and the top-level bullets past
+ * the bullet checkpoint, each with its text.
+ *
+ * Weight alone, never the sentence cap, since the growth stage asks about the
+ * two numbers the standard states in characters. The definitions are the
+ * audit's own, so a block this names and a block the weight report names are
+ * one set.
+ */
+export function longBlocks(
+  lines: readonly BodyLine[],
+  checkpoints: Checkpoints,
+): LongBlock[] {
+  const blocks: LongBlock[] = []
+
+  for (const block of paragraphBlocks(lines)) {
+    const text = paragraphText(block)
+    const characters = visibleText(text).length
+    if (characters > checkpoints.paragraph) {
+      blocks.push({
+        kind: 'paragraph',
+        line: block[0].number,
+        characters,
+        text,
+      })
+    }
+  }
+
+  for (const bullet of foldBullets(lines, checkpoints)) {
+    blocks.push({ kind: 'bullet', ...bullet })
+  }
+
+  return blocks.sort((a, b) => a.line - b.line)
+}
+
 /** Punctuation either side of a word, so an opener is compared on its letters. */
 const WORD_EDGE = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu
 

package/src/migrate/rule-layout.ts

@@ -34,12 +34,12 @@ export const RENUMBERED_RULES: Readonly<Record<string, string>> = {
 }
 
 /**
- * Band folders the walk skips by name rather than by content, so the
- * exclusion holds even for a band the toolkit has not shipped yet.
+ * Rule folders the walk skips by name rather than by content, so the
+ * exclusion holds even for a folder the toolkit has not shipped yet.
  * `canon/` and `internal/` are already-migrated destinations, and
  * `project/` is a target's own rules, which this verb never touches.
  */
-const EXCLUDED_BANDS: readonly string[] = ['project', 'canon', 'internal']
+const EXCLUDED_FOLDERS: readonly string[] = ['project', 'canon', 'internal']
 
 /** One flat rule file, before classification. */
 export interface FlatRuleFile {
@@ -57,9 +57,9 @@ export function flatRulesRoot(target: string): string {
 }
 
 /**
- * Every rule file sitting directly under a flat band folder. One level for
- * the band and one glob below it for `*.md`, since `governance/rules/` never
- * nests a rule deeper than its band, and the flat layout this verb migrates
+ * Every rule file sitting directly under a flat rule folder. One level for
+ * the folder and one glob below it for `*.md`, since `governance/rules/` never
+ * nests a rule deeper than its folder, and the flat layout this verb migrates
  * off of mirrors that depth.
  */
 export async function walkFlatRules(target: string): Promise<FlatRuleFile[]> {
@@ -69,20 +69,20 @@ export async function walkFlatRules(target: string): Promise<FlatRuleFile[]> {
   )
   if (entries === undefined) return []
 
-  const bands = entries.filter(
-    (entry) => entry.isDirectory() && !EXCLUDED_BANDS.includes(entry.name),
+  const folders = entries.filter(
+    (entry) => entry.isDirectory() && !EXCLUDED_FOLDERS.includes(entry.name),
   )
 
   const files: FlatRuleFile[] = []
-  for (const band of bands) {
+  for (const folder of folders) {
     const glob = new Bun.Glob('*.md')
     for (const name of glob.scanSync({
-      cwd: join(root, band.name),
+      cwd: join(root, folder.name),
       onlyFiles: true,
     })) {
       files.push({
-        rel: relPath('.claude', 'rules', band.name, name),
-        subdir: band.name,
+        rel: relPath('.claude', 'rules', folder.name, name),
+        subdir: folder.name,
         name: name.slice(0, -'.md'.length),
       })
     }

package/src/pr/frames.ts

@@ -1,7 +1,10 @@
 import { readFile } from 'node:fs/promises'
 
 /** The branch holding review frames. It never merges into a branch anyone checks out. */
-export const FRAMES_BRANCH = 'canon-frames'
+export const FRAMES_BRANCH = 'canon/frames'
+
+/** The branch frames lived on before the rename. A drop and a prune drain it and an add never writes it. */
+export const LEGACY_FRAMES_BRANCH = 'canon-frames'
 
 /** The eight bytes every PNG opens with. A frame that lacks them embeds as a broken image. */
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
@@ -94,6 +97,7 @@ export type DropResult =
       readonly removed: readonly number[]
       readonly commit?: string
       readonly deleted?: boolean
+      readonly legacy?: true
     }
   | { readonly kind: 'refused'; readonly reason: FramesRefusal }
 
@@ -105,6 +109,7 @@ export type PruneResult =
       readonly unread: readonly number[]
       readonly commit?: string
       readonly deleted?: boolean
+      readonly legacy?: true
     }
   | { readonly kind: 'refused'; readonly reason: FramesRefusal }
 
@@ -341,3 +346,63 @@ export async function pruneFrames(
     unread: unread.sort((a, b) => a - b),
   }
 }
+
+function mergeNumbers(
+  first: readonly number[],
+  second: readonly number[],
+): number[] {
+  return [...new Set([...first, ...second])].sort((a, b) => a - b)
+}
+
+/** Whether a drain pass changed the legacy ref, by removing a pull request or deleting it. */
+function touchedLegacy(result: DropResult): boolean {
+  return (
+    result.kind === 'dropped' &&
+    (result.removed.length > 0 || result.deleted === true)
+  )
+}
+
+/**
+ * Drops on the current branch, then on the legacy one. The legacy pass only
+ * removes, and a refusal there never fails a drop the current branch already
+ * finished, since a target that never held the legacy ref reads it as missing
+ * and a token may be unable to read it at all.
+ */
+export async function dropFramesWithLegacy(
+  api: FramesApi,
+  legacy: FramesApi,
+  numbers: readonly number[],
+): Promise<DropResult> {
+  const current = await dropFrames(api, numbers)
+  if (current.kind === 'refused') return current
+  const drained = await dropFrames(legacy, numbers)
+  if (drained.kind === 'refused' || !touchedLegacy(drained)) return current
+  return {
+    ...current,
+    removed: mergeNumbers(current.removed, drained.removed),
+    legacy: true,
+  }
+}
+
+/** The prune counterpart of `dropFramesWithLegacy`, with the same legacy semantics. */
+export async function pruneFramesWithLegacy(
+  api: FramesApi,
+  legacy: FramesApi,
+  days: number,
+  now: Date,
+): Promise<PruneResult> {
+  const current = await pruneFrames(api, days, now)
+  if (current.kind === 'refused') return current
+  const drained = await pruneFrames(legacy, days, now)
+  if (drained.kind === 'refused') return current
+  const touched = drained.removed.length > 0 || drained.deleted === true
+  const kept = mergeNumbers(current.kept, drained.kept)
+  const unread = mergeNumbers(current.unread, drained.unread)
+  return {
+    ...current,
+    removed: mergeNumbers(current.removed, drained.removed),
+    kept,
+    unread,
+    ...(touched && { legacy: true as const }),
+  }
+}

package/src/shipped/references.ts

@@ -54,7 +54,7 @@ export const REFERENCE_MARKER = 'canon-allow-reference'
  * already ships `anthropics/claude-code#58345` in exactly that form.
  *
  * The trailing boundary is what the first shape of this pattern lacked, and it
- * costs a live finding to omit. `governance/rules/framework/250-tailwind.md`
+ * costs a live finding to omit. `governance/rules/framework/tailwind.md`
  * writes `bg-[#316ff6]`, a Tailwind arbitrary hex color, which an unbounded
  * `#[0-9]+` reads as pull request 316. Requiring a non-word character after the
  * digits rejects it and rejects nothing real, since a citation is always
@@ -171,20 +171,20 @@ const STANDARDS_CALL = /\bcanon standards(?![\w-])/g
 const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
 
 /**
- * A `.claude/rules/<segments>/<nnn>-<slug>.md` citation from a body under
- * `claude/skills/`, the installed-path spelling `598-authoring-layout.md`
- * bans a shipped skill body from citing as authority for its own behavior.
+ * A `.claude/rules/<segments>/<slug>.md` citation from a body under
+ * `claude/skills/`, the installed-path spelling `authoring-layout.md` bans a
+ * shipped skill body from citing as authority for its own behavior.
  *
- * Anchored on the trailing `\d{3}-[\w-]+\.md` rather than on the bare
- * `.claude/rules/` prefix, which is what keeps a folder mention carrying no
- * number, such as `create-rule`, `target-check`, and `target-setup` already
- * write correctly, from matching. The segment group between `rules/` and the
- * numbered file admits both a governance-namespace path
- * (`canon/canon/604-scratch.md`) and a project-namespace one
- * (`project/<subdir>/<n>-<slug>.md`) without distinguishing them, since
- * either shape is the same broken citation.
+ * Anchored on a trailing `.md` file rather than on the bare `.claude/rules/`
+ * prefix, which is what keeps a folder mention, such as `create-rule`,
+ * `target-check`, and `target-setup` write, from matching: it ends in `/` or
+ * names no `.md`. The segments between `rules/` and the file admit both a
+ * governance-namespace path (`canon/canon/scratch.md`) and a
+ * project-namespace one (`project/<subdir>/<slug>.md`) without distinguishing
+ * them, since either shape is the same broken citation, and the placeholder
+ * check spares the bracketed illustration.
  */
-const RULE_PATH = /(?<![\w./-])\.claude\/rules\/[^\s`)\]]*\/\d{3}-[\w-]+\.md\b/g
+const RULE_PATH = /(?<![\w./-])\.claude\/rules\/[^\s`)\]]*?[\w-]+\.md\b/g
 
 export interface ShippedReference {
   readonly file: string
@@ -246,7 +246,7 @@ function isDocsPathReportable(
  * Whether `file` sits in the one corpus `RULE_PATH` gates: a shipped skill
  * body, minus its own `REQUIREMENT.md`.
  *
- * The ban lives in `598-authoring-layout.md`, stated for one reader: a
+ * The ban lives in `authoring-layout.md`, stated for one reader: a
  * session loading the `SKILL.md` body a target actually receives.
  * `REQUIREMENT.md` is excluded for the reason that file states there, since a
  * maintainer or an audit command reads it rather than a session loading it,