@erclx/canon 5.36.0 → 5.38.0

package/src/gate/stages.ts

@@ -11,10 +11,12 @@ import {
   captureStamps,
   clientCommandCitations,
   designProse,
+  bulletStacks,
   documentCeiling,
   folderEchoedNames,
   markdownBans,
   type Measure,
+  paragraphGrowth,
   pluginManifests,
   readmeCitations,
   recordIdempotence,
@@ -81,11 +83,6 @@ export interface Stage {
   readonly scope?: RegExp
   /** What a scoped-out stage says, so a skip never reads as a pass. */
   readonly skipped?: string
-  /**
-   * Whether this stage belongs in the run at all, read off the write grant
-   * rather than the changed set. Absent means it always belongs.
-   */
-  readonly when?: (options: { readonly write: boolean }) => boolean
   readonly checks: readonly Check[]
   /**
    * The machine lock this stage holds while its checks run, so one box runs it
@@ -144,28 +141,15 @@ const script = (name: string, failure: string): Check => ({
  * whole set at once.
  */
 export const STAGES: readonly Stage[] = [
-  {
-    id: 'format',
-    label: 'Formatting',
-    when: ({ write }) => write,
-    checks: [
-      {
-        kind: 'command',
-        argv: ['bun', 'run', 'format'],
-        failure: 'Format failed',
-      },
-    ],
-    success: 'Format applied',
-  },
   {
     id: 'format-check',
     label: 'Format check',
-    when: ({ write }) => !write,
     checks: [
       {
         kind: 'command',
         argv: ['bun', 'run', 'check:format'],
-        failure: 'Format check failed',
+        failure:
+          'Format check failed. Run bun run format and commit the result.',
       },
     ],
     success: 'Format check passed',
@@ -335,19 +319,23 @@ export const STAGES: readonly Stage[] = [
     checks: [{ kind: 'measure', measure: unreferencedRules }],
   },
   {
-    // Only the citation half of the audit gates. Its length, depth, table, and
-    // index findings are judgment thresholds, and failing a push on one would
-    // make the stage something to route around. The one length reading that
-    // gates is the whole-document ceiling, which the Document ceiling stage
-    // below owns rather than this audit.
+    // The facts the audit can answer from the files gate: a cited path that
+    // does not resolve, a required section an entry does not declare, an H2
+    // outside the closed set of four, and an index disagreeing with its folder.
+    // Its length, depth, bullet, table, and provenance findings are judgment
+    // thresholds, and failing a push on one would make the stage something to
+    // route around. The length readings that gate sit in their own stages
+    // below, apart from the audit's exit code: the whole-document ceiling, the
+    // bullet cap, and the growth of a paragraph or a bullet past its
+    // checkpoint.
     id: 'context-citations',
     label: 'Context citations',
     checks: [
       {
         kind: 'cli',
-        argv: ['context', 'audit', '--citations-only'],
+        argv: ['context', 'audit', '--gate'],
         failure:
-          'A cited context path does not resolve. Run bun src/cli.ts context audit.',
+          'A cited context path does not resolve, an entry lacks a required section or carries an H2 outside Overview, Layout, Decisions, and Gotchas, or an index disagrees with its folder. Run bun src/cli.ts context audit --gate.',
       },
     ],
     success: 'Context citations resolve',
@@ -366,6 +354,23 @@ export const STAGES: readonly Stage[] = [
     label: 'Document ceiling',
     checks: [{ kind: 'measure', measure: documentCeiling }],
   },
+  {
+    // Unscoped, since any branch can add a bullet to any entry. A run of more
+    // than 5 plain bullets fails the push in the context entries, the docs
+    // pages, and the skill bodies and references. Apart from the audit's exit
+    // code for the reason the Document ceiling stage above states.
+    id: 'bullet-stacks',
+    label: 'Bullet stacks',
+    checks: [{ kind: 'measure', measure: bulletStacks }],
+  },
+  {
+    // Context entries only, where length drifts. A paragraph past 700
+    // characters or a top-level bullet past 250 fails when this branch added or
+    // changed it, and an unchanged one passes until it is edited.
+    id: 'paragraph-growth',
+    label: 'Paragraph growth',
+    checks: [{ kind: 'measure', measure: paragraphGrowth }],
+  },
   {
     // Unscoped, since any branch can add a file anywhere and one git ls-files
     // costs nothing. Reads paths rather than markdown, so it sits here rather
@@ -539,6 +544,20 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Shell check passed',
   },
+  {
+    id: 'lint',
+    label: 'Lint',
+    // Unscoped, since a full run costs less than spawning the process and a
+    // scope is one more pattern to fall behind the extensions oxlint reads.
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:lint'],
+        failure: 'Lint failed',
+      },
+    ],
+    success: 'Lint passed',
+  },
   {
     id: 'types',
     label: 'Types',

package/src/git/files.ts

@@ -165,3 +165,33 @@ export async function listRepositoryFiles(
 
   return [...new Set([...tracked, ...untracked])].sort()
 }
+
+/**
+ * A file as `ref` holds it, or undefined where the ref holds no such path or
+ * git cannot answer. A path absent at the ref and a failed read are the same
+ * answer for a caller asking what the copy before this branch said.
+ */
+export async function readFileAtRef(
+  root: string,
+  ref: string,
+  rel: string,
+): Promise<string | undefined> {
+  return git(root, ['show', `${ref}:${rel}`])
+}
+
+/** Every path under `prefix` that `ref` holds, or undefined where git cannot answer. */
+export async function listFilesAtRef(
+  root: string,
+  ref: string,
+  prefix: string,
+): Promise<string[] | undefined> {
+  const listed = await git(root, [
+    'ls-tree',
+    '-r',
+    '--name-only',
+    ref,
+    '--',
+    prefix,
+  ])
+  return listed === undefined ? undefined : listed.split('\n').filter(Boolean)
+}

package/src/gov/adapter.ts

@@ -98,8 +98,8 @@ export function createGovAdapter(root: string): SyncAdapter {
 }
 
 /**
- * Where the target already holds a rule, in whichever band folder. A
- * successor held outside the source's band stays where it is, the same way
+ * Where the target already holds a rule, in whichever rule folder. A
+ * successor held outside the source's folder stays where it is, the same way
  * `locateSource` syncs a moved rule in place, rather than gaining a second copy.
  *
  * Holding the predecessor is the whole entitlement test, so no stamped chain

package/src/gov/install.ts

@@ -28,7 +28,7 @@ export function canonRulesDir(target: string): string {
 
 /**
  * This repository's own toolkit-only rules, installed beside `canon/` rather
- * than interleaved into its bands. No target ever holds this folder.
+ * than interleaved into its folders. No target ever holds this folder.
  */
 export function installedInternalRulesDir(target: string): string {
   return join(installedRulesDir(target), 'internal')
@@ -134,7 +134,7 @@ export function lookupRules(
 
 /**
  * Copies each rule into the subdirectory it was authored in, so the installed
- * tree keeps the band structure `governance/rules/` carries. Returns the
+ * tree keeps the rule folder structure `governance/rules/` carries. Returns the
  * target-relative paths the timeline prints.
  *
  * `destSubdir` picks which wrapper the rule lands under: `canon` for every

package/src/gov/list.ts

@@ -74,7 +74,7 @@ export function buildStackEntries(root: string): StackEntry[] {
 
 /**
  * Reads the catalog straight off the source tree. A rule's domain is the
- * subdirectory it sits in, which is the band grouping install preserves, and
+ * subdirectory it sits in, which is the rule folder grouping install preserves, and
  * its `detect` entry is the evidence that proposes it, null for a rule
  * `detect.toml` does not name.
  */

package/src/gov/payload.ts

@@ -5,7 +5,7 @@ import { stripFrontmatter } from '@/markdown/frontmatter'
 /**
  * Lists installed rules in the order the payload concatenates them. Sorting by
  * path keeps the numeric filename prefixes ordered inside each subdirectory,
- * which is how the rule bands are meant to read.
+ * which is how the rule folders are meant to read.
  */
 export function listRuleFiles(rulesDir: string): string[] {
   return [

package/src/gov/stacks.ts

@@ -163,7 +163,7 @@ export function unreferencedRules(root: string): string[] {
  * does not hold. `resolveRules` already walks a stack's `extends` ancestors,
  * so reading its leaf entry is enough; no second walk resolves the chain
  * itself. A stack the toolkit no longer ships resolves to nothing rather than
- * throwing, the same way `readNewRules`'s band fallback already treats it.
+ * throwing, the same way `readNewRules`'s folder fallback already treats it.
  *
  * A held rule's declared successor counts as held, since the sync that
  * renames the old file installs it.

package/src/markdown/gate.ts

@@ -2,6 +2,7 @@ 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 {
@@ -31,6 +32,15 @@ export interface GateInput {
    * 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/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

@@ -86,7 +86,7 @@ const BLOCKQUOTE = /^\s*>/
  * follows, and the price is that a span opening a fragment mid-paragraph reads
  * as a sentence start.
  */
-const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
+const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“([]*[A-Z]|`)|\s*$)/g
 
 /**
  * Checkpoints the structural measures run against.
@@ -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/sandbox/equivalence.ts

@@ -674,7 +674,7 @@ async function pool<T, R>(
   size: number,
   work: (item: T, index: number) => Promise<R>,
 ): Promise<R[]> {
-  const results: R[] = new Array(items.length)
+  const results: R[] = Array.from({ length: items.length })
   let next = 0
 
   async function lane(): Promise<void> {
@@ -827,14 +827,12 @@ export async function runEquivalence(
     const records: ArmRecord[] = [
       ...offline,
       ...anchored,
-      ...skipped.map(
-        (arm): ArmRecord => ({
-          arm: armKey(arm),
-          state: 'skipped-anchor',
-          differs: [],
-          masked: [],
-        }),
-      ),
+      ...skipped.map((arm): ArmRecord => ({
+        arm: armKey(arm),
+        state: 'skipped-anchor',
+        differs: [],
+        masked: [],
+      })),
     ].sort((x, y) => x.arm.localeCompare(y.arm))
 
     const counts: Record<ArmState, number> = {