@erclx/canon 5.36.0 → 5.37.0

package/src/gate/measures.ts

@@ -18,9 +18,18 @@ import {
 import { familyKeys } from '@/claude/skills-families'
 import { measureDesignProse } from '@/design/budget'
 import { DESIGN_DOCUMENT } from '@/design/regen'
-import { listRepositoryFiles } from '@/git/files'
+import {
+  listChangedFiles,
+  listFilesAtRef,
+  listRepositoryFiles,
+  readFileAtRef,
+  resolveBaseRef,
+} from '@/git/files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
+import { grownBlocks, normalizeProse } from '@/markdown/growth'
+import { bodyLines } from '@/markdown/scan'
+import { bulletStacks as findBulletStacks } from '@/markdown/stacks'
 import { CHECKPOINTS } from '@/markdown/structure'
 import {
   isShippedCorpus,
@@ -501,6 +510,182 @@ export const documentCeiling: Measure = async (ctx) => {
   }
 }
 
+/**
+ * The tracked documents a bullet run is held against: the context entries, the
+ * docs pages, and the skill bodies and references of both skill trees.
+ *
+ * Rules and the requirement records stay out, since a rule is one imperative
+ * per bullet and a requirement is a record of its own. Named here and nowhere
+ * else, so the stage and its tests read one scope.
+ */
+const STACK_SCOPE = [
+  /^canon\/context\/.+\.md$/,
+  /^docs\/.+\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/SKILL\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/references\/.+\.md$/,
+]
+
+/** Whether a path is one the bullet cap holds. */
+export function inStackScope(rel: string): boolean {
+  return STACK_SCOPE.some((pattern) => pattern.test(rel))
+}
+
+/** The context entries alone, where length drifts because `context-fold` appends after every merge. */
+const GROWTH_SCOPE = /^canon\/context\/.+\.md$/
+
+/** Whether a path is one the growth check reads. */
+export function inGrowthScope(rel: string): boolean {
+  return GROWTH_SCOPE.test(rel)
+}
+
+/**
+ * Every in-scope document against the five-bullet cap.
+ *
+ * The failure names each file with its longest run and where it opens. Read
+ * in-process rather than through `canon markdown audit`, whose exit code stays
+ * bans and dead links only, for the reason `documentCeiling` gives: the plan
+ * and groundwork skills run that audit on gitignored records, where a long
+ * list is not a defect.
+ */
+export const bulletStacks: Measure = async (ctx) => {
+  const files = await listRepositoryFiles(ctx.root)
+  if (files === undefined) {
+    return {
+      emissions: [],
+      unmeasured: 'git could not list the tree, so no bullet run was measured.',
+    }
+  }
+
+  const scoped = files.filter(inStackScope)
+  const failing: { rel: string; count: number; line: number }[] = []
+
+  for (const rel of scoped) {
+    let source: string
+    try {
+      source = readFileSync(join(ctx.root, rel), 'utf8')
+    } catch {
+      continue
+    }
+    const runs = findBulletStacks(bodyLines(source))
+    if (runs.length === 0) continue
+    const longest = runs.reduce((a, b) => (b.count > a.count ? b : a))
+    failing.push({ rel, count: longest.count, line: longest.line })
+  }
+
+  if (failing.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No run of more than 5 plain bullets across ${plural(scoped.length, 'document')}`,
+        ),
+      ],
+    }
+  }
+
+  const where = failing
+    .sort((a, b) => b.count - a.count)
+    .map((f) => `${f.rel}:${f.line} ${f.count} bullets`)
+    .join(', ')
+  return {
+    emissions: [],
+    failure: `${plural(failing.length, 'document')} carrying a run of more than 5 plain bullets: ${where}. Split each run under H3 headings with a few bullets or prose beneath, or open every item with a bold label or a link.`,
+  }
+}
+
+/**
+ * A context entry's paragraph or top-level bullet past its checkpoint that
+ * this branch added or changed.
+ *
+ * A block fails when its text is absent from every context entry the merge
+ * base held, so an unchanged long block passes wherever it now sits and an
+ * edited or new one fails. Reading the whole base folder rather than the same
+ * path is what lets a block move into a sibling entry. No resolvable base
+ * reports unmeasured rather than a pass, since a missing base would otherwise
+ * read every block as new or none as new.
+ *
+ * Only context entries are held to it. Length drifts there because
+ * `context-fold` appends after every merge, and in docs and skills it stays the
+ * audit's advisory warning.
+ */
+export const paragraphGrowth: Measure = async (ctx) => {
+  const base = await resolveBaseRef(ctx.root)
+  if (base === undefined) {
+    return {
+      emissions: [],
+      unmeasured:
+        'no merge base resolved, so no paragraph or bullet was compared against it.',
+    }
+  }
+
+  const changed = await listChangedFiles(ctx.root, base)
+  if (changed === undefined) {
+    return {
+      emissions: [],
+      unmeasured:
+        'git could not list the branch range, so no block was compared.',
+    }
+  }
+
+  const grown: {
+    rel: string
+    kind: string
+    line: number
+    characters: number
+  }[] = []
+  let corpus: string | undefined
+
+  for (const rel of changed.filter(inGrowthScope)) {
+    let source: string
+    try {
+      source = readFileSync(join(ctx.root, rel), 'utf8')
+    } catch {
+      continue
+    }
+
+    const own = normalizeProse((await readFileAtRef(ctx.root, base, rel)) ?? '')
+    const first = grownBlocks(source, own)
+    if (first.length === 0) continue
+
+    if (corpus === undefined) {
+      const paths =
+        (await listFilesAtRef(ctx.root, base, 'canon/context')) ?? []
+      const texts = await Promise.all(
+        paths
+          .filter(inGrowthScope)
+          .map((path) => readFileAtRef(ctx.root, base, path)),
+      )
+      corpus = normalizeProse(texts.filter((t) => t !== undefined).join('\n'))
+    }
+
+    for (const block of grownBlocks(source, corpus)) {
+      grown.push({
+        rel,
+        kind: block.kind,
+        line: block.line,
+        characters: block.characters,
+      })
+    }
+  }
+
+  if (grown.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No paragraph past ${CHECKPOINTS.paragraph} characters and no bullet past ${CHECKPOINTS.bullet} grew in a context entry`,
+        ),
+      ],
+    }
+  }
+
+  const where = grown
+    .map((g) => `${g.rel}:${g.line} ${g.kind} ${g.characters} characters`)
+    .join(', ')
+  return {
+    emissions: [],
+    failure: `${plural(grown.length, 'block')} past the checkpoint added or changed on this branch: ${where}. Split each at a seam, or cut it under ${CHECKPOINTS.paragraph} characters for a paragraph and ${CHECKPOINTS.bullet} for a bullet.`,
+  }
+}
+
 /**
  * Whether a path's stem, its basename up to the first `.`, repeats its
  * immediate parent folder, either whole or as a `<folder>-` prefix.

package/src/gate/sequencer.ts

@@ -113,8 +113,6 @@ export function readProcLoad(): LoadReading | undefined {
 }
 
 export interface GateContext extends MeasureContext {
-  /** Whether the format stage writes or checks. */
-  readonly write: boolean
   /**
    * The changed set a scoped stage is read against, or `undefined` where
    * scoping is off and every stage runs.
@@ -444,8 +442,6 @@ export async function runStages(
   const results: StageResult[] = []
 
   for (const stage of stages) {
-    if (stage.when !== undefined && !stage.when({ write: ctx.write })) continue
-
     const result = await runStage(stage, ctx)
     results.push(result)
     onResult?.(result)

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

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

@@ -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