@erclx/canon 5.37.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 }],
   },
   {
@@ -544,6 +528,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/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 }
+}