@erclx/canon 5.38.0 → 5.39.0

package/src/gate/measures.ts

@@ -18,18 +18,9 @@ import {
 import { familyKeys } from '@/claude/skills-families'
 import { measureDesignProse } from '@/design/budget'
 import { DESIGN_DOCUMENT } from '@/design/regen'
-import {
-  listChangedFiles,
-  listFilesAtRef,
-  listRepositoryFiles,
-  readFileAtRef,
-  resolveBaseRef,
-} from '@/git/files'
+import { listRepositoryFiles } 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,
@@ -510,182 +501,6 @@ 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.
@@ -693,8 +508,12 @@ export const paragraphGrowth: Measure = async (ctx) => {
  * Exact rather than singular-aware, so `skills/skill.md` passes. A false
  * positive on a gate stage teaches a contributor to route around it, and a
  * widened match is cheap to add once a real echo slips through.
+ *
+ * `canon/context/context-model.md` is exempt, since "context model" is the
+ * domain's own name and the entry reads as nothing else without the prefix.
  */
 export function isFolderEchoedName(path: string): boolean {
+  if (path === 'canon/context/context-model.md') return false
   const segments = path.split('/')
   if (segments.length < 2) return false
   const folder = segments[segments.length - 2] ?? ''
@@ -806,8 +625,10 @@ export const recordIdempotence: Measure = async (ctx) => {
 }
 
 /**
- * A banned character is a fact rather than a threshold, so it fails the push
- * while bullet, paragraph, and depth weight stay advisory.
+ * A banned character, a dead link, and a density finding on a gated path are
+ * each a fact rather than a threshold, so any one fails the push while depth
+ * weight and cadence stay advisory. The audit decides which density findings
+ * gate, from `src/markdown/scope.ts`, so this stage reads its exit alone.
  *
  * The whole corpus is measured rather than the changed files, because a
  * `Do not use` bullet added to a standard bans a token retroactively and no
@@ -821,7 +642,11 @@ export const markdownBans: Measure = async (ctx) => {
   const { exitCode } = await ctx.cli(['markdown', 'audit', '--json'])
 
   if (exitCode === 0) {
-    return { emissions: [info('No banned character')] }
+    return {
+      emissions: [
+        info('No banned character, dead link, or gated density finding'),
+      ],
+    }
   }
 
   if (exitCode === 1) {
@@ -844,7 +669,7 @@ export const markdownBans: Measure = async (ctx) => {
     return {
       emissions: [output(frame.all)],
       failure:
-        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk. Rewrite the sentence, since a colon or a comma standing where the em dash was is the same sentence, or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
+        'Markdown prose carries a banned character, a relative link resolves to nothing on disk, or a gated path breaks a density limit. Rewrite the sentence, since a colon or a comma standing where the em dash was is the same sentence, fix the link, or split the block the Density section names, and reach for a code span only where the token is genuinely an identifier under discussion.',
     }
   }
 

package/src/gate/stages.ts

@@ -11,12 +11,10 @@ import {
   captureStamps,
   clientCommandCitations,
   designProse,
-  bulletStacks,
   documentCeiling,
   folderEchoedNames,
   markdownBans,
   type Measure,
-  paragraphGrowth,
   pluginManifests,
   readmeCitations,
   recordIdempotence,
@@ -321,7 +319,8 @@ export const STAGES: readonly Stage[] = [
   {
     // 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.
+    // outside the closed set of three, a shape break in an entry under a
+    // shape-gated folder, 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
@@ -335,7 +334,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'cli',
         argv: ['context', 'audit', '--gate'],
         failure:
-          '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.',
+          'A cited context path does not resolve, an entry lacks a required section or carries an H2 outside Overview, Layout, and Gotchas, an entry under a shape-gated folder breaks the section shape, or an index disagrees with its folder. Run bun src/cli.ts context audit --gate.',
       },
     ],
     success: 'Context citations resolve',
@@ -354,23 +353,6 @@ 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
@@ -410,8 +392,10 @@ export const STAGES: readonly Stage[] = [
     checks: [{ kind: 'measure', measure: recordIdempotence }],
   },
   {
-    id: 'markdown-bans',
-    label: 'Markdown bans',
+    // Bans and dead links in every file, and a density finding on a path the
+    // audit gates, all read off one exit code.
+    id: 'markdown',
+    label: 'Markdown',
     checks: [{ kind: 'measure', measure: markdownBans }],
   },
   {

package/src/hooks/reply-links.ts

@@ -0,0 +1,110 @@
+import { isAbsolute, join } from 'node:path'
+import { decodePath } from '@/markdown/links'
+import { LINK, linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
+
+export interface MissingLink {
+  /** The destination as the reply wrote it. */
+  readonly destination: string
+  /** The path the check looked for. */
+  readonly path: string
+  /** Where the file is instead, for a records link written under a worktree. */
+  readonly suggestion?: string
+}
+
+// A bare filename followed by a line tail reads as a scheme, so a colon that
+// opens nothing but a position (`README.md:12`) is not one.
+const SCHEME = /^[a-z][a-z0-9+.-]*:(?!\d+(?:-\d+)?(?::\d+)?$)/i
+const POSITION_TAIL = /(?::\d+){1,2}(?:-\d+)?$/
+const WORKTREE_RECORDS = /\/\.claude\/worktrees\/[^/]+\/(\.canon\/.*)$/
+
+function isSkipped(destination: string): boolean {
+  return (
+    destination === '' ||
+    SCHEME.test(destination) ||
+    destination.startsWith('#') ||
+    /[<*{]/.test(destination)
+  )
+}
+
+/**
+ * The path a destination names, or undefined when it is not one to check.
+ *
+ * A chat link is resolved from the editor root and not from a file's own
+ * folder, which is why `findBrokenLinks` cannot serve here: it skips every
+ * absolute destination and resolves the rest beside the file holding them.
+ * A malformed percent escape is skipped, since the reply is text a model
+ * typed and the hook has no business throwing on it.
+ */
+function linkedPath(destination: string): string | undefined {
+  if (isSkipped(destination)) return undefined
+  const decoded = decodePath(destination)
+  if (decoded === undefined) return undefined
+  const path = decoded.replace(POSITION_TAIL, '')
+  return path === '' ? undefined : path
+}
+
+/**
+ * Markdown link targets in a reply that name nothing on disk.
+ *
+ * A relative target resolves against `root`, the main worktree root, since the
+ * editor is rooted there. A relative link to a file that exists only inside a
+ * linked worktree therefore reads as missing, which is the report the output
+ * rule asks for. `exists` stays injected so a test asserts against a fake disk.
+ */
+export function findMissingReplyLinks(
+  reply: string,
+  root: string,
+  exists: (path: string) => boolean,
+): MissingLink[] {
+  const checked = new Map<string, MissingLink | undefined>()
+
+  for (const line of linesOutsideFences(reply)) {
+    for (const match of maskCodeSpans(line).matchAll(LINK)) {
+      const destination = match[0].slice(match[0].indexOf('](') + 2, -1)
+      const target = linkedPath(destination)
+      if (target === undefined) continue
+
+      const path = isAbsolute(target) ? target : join(root, target)
+      if (checked.has(path)) continue
+
+      checked.set(
+        path,
+        exists(path) ? undefined : missing(destination, path, root, exists),
+      )
+    }
+  }
+
+  return [...checked.values()].filter((entry) => entry !== undefined)
+}
+
+/**
+ * The block reason the wrapper hands back to the session. The closing line
+ * covers the one miss that is not a typo: a relative link to a file living only
+ * inside a linked worktree, which the editor, rooted at the main checkout,
+ * cannot open.
+ */
+export function formatMissing(found: readonly MissingLink[]): string {
+  return [
+    'The final reply links to paths that do not exist on disk:',
+    ...found.map((entry) =>
+      entry.suggestion === undefined
+        ? `- ${entry.destination}`
+        : `- ${entry.destination} (the file is at ${entry.suggestion})`,
+    ),
+    '',
+    'Post the corrected links in a short follow-up. Use the full path from the project root, and the absolute path for a file inside a linked worktree.',
+  ].join('\n')
+}
+
+function missing(
+  destination: string,
+  path: string,
+  root: string,
+  exists: (path: string) => boolean,
+): MissingLink {
+  const records = WORKTREE_RECORDS.exec(path)?.[1]
+  const relocated = records === undefined ? undefined : join(root, records)
+  return relocated !== undefined && exists(relocated)
+    ? { destination, path, suggestion: relocated }
+    : { destination, path }
+}

package/src/markdown/density.ts

@@ -0,0 +1,258 @@
+import { type BodyLine, visibleText } from '@/markdown/scan'
+import { bulletStacks, CAP } from '@/markdown/stacks'
+import {
+  BLOCKQUOTE,
+  CHECKPOINTS,
+  HEADING,
+  isSectionMarker,
+  LIST_ITEM,
+  TABLE_ROW,
+} from '@/markdown/structure'
+
+/** The most prose paragraphs one stretch may carry before a list, table, or heading breaks it. */
+export const PARAGRAPH_RUN = 2
+
+/** The deepest heading level a document may use. */
+export const HEADING_DEPTH = 3
+
+export type DensityKind =
+  | 'paragraph-length'
+  | 'paragraph-run'
+  | 'bullet-length'
+  | 'bullet-run'
+  | 'heading-depth'
+  | 'h3-opening'
+
+export interface DensityFinding {
+  readonly kind: DensityKind
+  /** The line of the block that breaches, or of a run's first block. */
+  readonly line: number
+  /** What was measured, or null for the H3 opening, which is a shape rather than a count. */
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+/**
+ * A block as a reader meets it. `other` is everything that is neither prose,
+ * a list item, nor a heading, being a table, a fence, a blockquote, a section
+ * marker, and raw HTML, and each one breaks a paragraph run.
+ */
+type Block =
+  | { readonly kind: 'heading'; readonly line: number; readonly level: number }
+  | { readonly kind: 'paragraph'; readonly line: number; readonly text: string }
+  | { readonly kind: 'item'; readonly line: number; readonly text: string }
+  | { readonly kind: 'other'; readonly line: number; readonly table: boolean }
+
+/**
+ * Splits the body into the blocks the six limits read.
+ *
+ * Its own walk rather than `paragraphBlocks` in `src/markdown/structure.ts`,
+ * because the two disagree on one construct and the disagreement is the point.
+ * That walk reads an indented paragraph under a list item as a paragraph, and
+ * here it belongs to the item: it counts toward the bullet's length and never
+ * toward a paragraph run, since a reader sees it inside the list.
+ *
+ * A nested item is left out of its parent, as `heavyBullets` leaves it, and so
+ * is everything indented under the nested item. An indented fence inside an
+ * item stays with the item, and a column-zero one ends it.
+ */
+function blocksOf(lines: readonly BodyLine[]): Block[] {
+  const blocks: Block[] = []
+  let paragraph: { line: number; parts: string[] } | undefined
+  let item: { line: number; parts: string[]; nested: boolean } | undefined
+  let inFence = false
+  let afterBlank = false
+
+  const closeParagraph = (): void => {
+    if (paragraph) {
+      blocks.push({
+        kind: 'paragraph',
+        line: paragraph.line,
+        text: paragraph.parts.join(' '),
+      })
+    }
+    paragraph = undefined
+  }
+
+  const closeItem = (): void => {
+    if (item) {
+      blocks.push({ kind: 'item', line: item.line, text: item.parts.join(' ') })
+    }
+    item = undefined
+  }
+
+  const closeAll = (): void => {
+    closeParagraph()
+    closeItem()
+  }
+
+  for (const line of lines) {
+    const raw = line.text
+    const text = raw.trim()
+    const indented = /^\s/.test(raw)
+
+    if (line.fenced) {
+      // The opening delimiter decides who owns the block. `bodyLines` marks a
+      // delimiter and the body alike, so the opener is the first fenced line.
+      if (!inFence) {
+        if (!(item && indented)) {
+          closeAll()
+          blocks.push({ kind: 'other', line: line.number, table: false })
+        }
+      }
+      inFence = true
+      afterBlank = false
+      continue
+    }
+    inFence = false
+
+    if (text === '') {
+      closeParagraph()
+      afterBlank = true
+      continue
+    }
+
+    if (indented && item) {
+      if (LIST_ITEM.test(raw)) item.nested = true
+      else if (!item.nested && !TABLE_ROW.test(raw)) item.parts.push(text)
+      afterBlank = false
+      continue
+    }
+
+    if (HEADING.test(raw)) {
+      closeAll()
+      blocks.push({
+        kind: 'heading',
+        line: line.number,
+        level: (raw.match(/^#+/)?.[0] ?? '').length,
+      })
+    } else if (!indented && LIST_ITEM.test(raw)) {
+      closeAll()
+      item = {
+        line: line.number,
+        parts: [text.replace(LIST_ITEM, '')],
+        nested: false,
+      }
+    } else if (
+      TABLE_ROW.test(raw) ||
+      BLOCKQUOTE.test(raw) ||
+      isSectionMarker(raw) ||
+      text.startsWith('<')
+    ) {
+      closeAll()
+      blocks.push({
+        kind: 'other',
+        line: line.number,
+        table: TABLE_ROW.test(raw),
+      })
+    } else if (paragraph) {
+      paragraph.parts.push(text)
+    } else if (item && !afterBlank) {
+      // A lazy continuation, which renders inside the item above it.
+      item.parts.push(text)
+    } else {
+      closeItem()
+      paragraph = { line: line.number, parts: [text] }
+    }
+
+    afterBlank = false
+  }
+
+  closeAll()
+
+  return blocks
+}
+
+/**
+ * Every breach of the six density limits, in line order.
+ *
+ * Each limit is a count rather than a judgment, so a finding is a fact a scan
+ * settles and the caller decides whether it gates. The limits are a 350-character
+ * paragraph, 2 paragraphs in a row, a 200-character bullet, 5 plain bullets in
+ * a row, no heading past H3, and a paragraph or a table as the first block
+ * under every H3. The two length numbers are `CHECKPOINTS`, so the advisory
+ * Bullets and Paragraphs sections and this measure read one number, and the
+ * bullet run is `bulletStacks`, so a bold-labeled run stays exempt here too.
+ */
+export function densityFindings(lines: readonly BodyLine[]): DensityFinding[] {
+  const found: DensityFinding[] = []
+  const blocks = blocksOf(lines)
+  let run: { line: number; count: number } | undefined
+
+  const closeRun = (): void => {
+    if (run && run.count > PARAGRAPH_RUN) {
+      found.push({
+        kind: 'paragraph-run',
+        line: run.line,
+        value: run.count,
+        limit: PARAGRAPH_RUN,
+      })
+    }
+    run = undefined
+  }
+
+  for (const [index, block] of blocks.entries()) {
+    if (block.kind !== 'paragraph') closeRun()
+
+    if (block.kind === 'paragraph') {
+      run ??= { line: block.line, count: 0 }
+      run.count++
+      const length = visibleText(block.text).length
+      if (length > CHECKPOINTS.paragraph) {
+        found.push({
+          kind: 'paragraph-length',
+          line: block.line,
+          value: length,
+          limit: CHECKPOINTS.paragraph,
+        })
+      }
+    } else if (block.kind === 'item') {
+      const length = visibleText(block.text).length
+      if (length > CHECKPOINTS.bullet) {
+        found.push({
+          kind: 'bullet-length',
+          line: block.line,
+          value: length,
+          limit: CHECKPOINTS.bullet,
+        })
+      }
+    } else if (block.kind === 'heading') {
+      if (block.level > HEADING_DEPTH) {
+        found.push({
+          kind: 'heading-depth',
+          line: block.line,
+          value: block.level,
+          limit: HEADING_DEPTH,
+        })
+      }
+      if (block.level === 3 && !opensWithLead(blocks[index + 1])) {
+        found.push({
+          kind: 'h3-opening',
+          line: block.line,
+          value: null,
+          limit: null,
+        })
+      }
+    }
+  }
+
+  closeRun()
+
+  for (const stack of bulletStacks(lines)) {
+    found.push({
+      kind: 'bullet-run',
+      line: stack.line,
+      value: stack.count,
+      limit: CAP,
+    })
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/** Whether the block under an H3 is the paragraph or table the limit asks for. */
+function opensWithLead(next: Block | undefined): boolean {
+  if (next === undefined) return false
+  if (next.kind === 'paragraph') return true
+  return next.kind === 'other' && next.table
+}