@erclx/canon 5.38.0 → 5.40.0

package/src/context/audit.ts

@@ -67,8 +67,7 @@ export const REQUIRED_SECTIONS_BY_FOLDER: Readonly<
  * The closed set of H2 sections per audited folder name, which a required
  * section belongs to. An entry carrying another H2 is a finding under
  * `--gate`, since the set is what makes a context entry cheap to find a fact
- * in: a domain's own topic names go one level down as H3 items under
- * `Decisions` and `Gotchas`.
+ * in: a domain's folders go one level down as H3 items under `Layout`.
  *
  * Held beside the required lists for the same reason they are held here, and
  * keyed on the folder whose standard states it.
@@ -76,7 +75,46 @@ export const REQUIRED_SECTIONS_BY_FOLDER: Readonly<
 export const ALLOWED_SECTIONS_BY_FOLDER: Readonly<
   Record<string, readonly string[]>
 > = {
-  context: ['Overview', 'Layout', 'Decisions', 'Gotchas'],
+  context: ['Overview', 'Layout', 'Gotchas'],
+}
+
+/**
+ * H2 sections the standard once allowed and now forbids, per audited folder.
+ *
+ * Kept apart from the extra sections because every unrebuilt entry still
+ * carries one, and an extra section gates under `--gate` everywhere. A retired
+ * section is a shape finding instead, which gates only where the folder was
+ * rebuilt, per `SHAPE_GATED_FOLDERS`.
+ */
+export const RETIRED_SECTIONS_BY_FOLDER: Readonly<
+  Record<string, readonly string[]>
+> = {
+  context: ['Decisions'],
+}
+
+/** Bullets a `Gotchas` section may hold, counted at any indent. */
+export const GOTCHA_CAP = 5
+
+/** Bullets a folder H3 under `Layout` may hold, counted at any indent. */
+export const LAYOUT_BULLET_CAP = 5
+
+/** Paragraphs a folder H3 under `Layout` may hold, being its one lead. */
+export const LAYOUT_PARAGRAPH_CAP = 1
+
+/** The one Layout H3 not titled with a path, holding the trivial folders. */
+export const OTHER_FOLDERS = 'Other folders'
+
+/** The run-command table H3 only the development entry carries under `Layout`. */
+export const SCRIPTS_HEADING = 'Scripts'
+
+/**
+ * Whether an entry path is the development entry, being the flat entry, the
+ * overview of a split one a target may still carry, or this repository's
+ * `local-loop` entry. The standard exempts the
+ * `Scripts` H3 for that entry alone, so the path is what tells.
+ */
+function isDevelopmentEntry(rel: string): boolean {
+  return /(?:^|\/)development(?:\/(?:overview|local-loop))?\.md$/.test(rel)
 }
 
 /**
@@ -210,6 +248,34 @@ export interface BareReferenceFinding {
   readonly name: string
 }
 
+/**
+ * Each way an entry breaks the section shape the context standard states.
+ *
+ * `retired-section` is a `Decisions` H2. The three `gotcha-*` kinds are a
+ * `Gotchas` section past its bullet cap, holding a heading, or holding a
+ * paragraph. The three `layout-*` kinds are a Layout H3 titled neither a path
+ * nor `Other folders`, a folder H3 past its bullet or paragraph cap, and a
+ * heading below H3 under `Layout`.
+ */
+export type ShapeKind =
+  | 'retired-section'
+  | 'gotcha-count'
+  | 'gotcha-heading'
+  | 'gotcha-paragraph'
+  | 'layout-heading'
+  | 'layout-bullets'
+  | 'layout-paragraphs'
+  | 'layout-depth'
+
+export interface ShapeIssue {
+  readonly line: number
+  readonly kind: ShapeKind
+  /** The heading or line as written, so a report names where to look. */
+  readonly text: string
+  /** Bullets or paragraphs counted, on the two cap kinds alone. */
+  readonly count?: number
+}
+
 export interface EntryReport {
   readonly rel: string
   /**
@@ -247,6 +313,12 @@ export interface EntryReport {
    * all is `extraSections`.
    */
   readonly otherSections: readonly string[]
+  /**
+   * Breaks of the section shape, in document order, and empty outside the
+   * governed folder. Whether one gates depends on where the entry sits, which
+   * `shapeFindings` decides rather than the measure.
+   */
+  readonly shape: readonly ShapeIssue[]
   /**
    * Whether the file declares itself a skeleton, which excludes it from the
    * section check alone. Every other measure still reads it, since a stub is
@@ -483,6 +555,7 @@ const H2_TEXT = /^##\s+(.+?)\s*$/
 function otherSections(
   lines: readonly BodyLine[],
   allowed: readonly string[],
+  retired: readonly string[],
 ): string[] {
   if (allowed.length === 0) return []
 
@@ -492,12 +565,166 @@ function otherSections(
     if (line.fenced) continue
 
     const match = line.text.match(H2_TEXT)
-    if (match && !allowed.includes(match[1])) found.push(match[1])
+    if (match && !allowed.includes(match[1]) && !retired.includes(match[1])) {
+      found.push(match[1])
+    }
   }
 
   return found
 }
 
+const HEADING_LEVEL = /^(#{1,6})\s+(.+?)\s*$/
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/
+const INDENTED = /^\s+\S/
+const FOLDER_TITLE = /^`[^`]+`$/
+
+interface FolderHeading {
+  readonly line: number
+  readonly text: string
+  bullets: number
+  paragraphs: number
+}
+
+/**
+ * Finds where the entry breaks the section shape.
+ *
+ * Bullets are counted at any indent and across any paragraph, so a list split
+ * by a bold label or nested one level down still counts against the cap it
+ * would otherwise slip under. A line continuing a list item, lazily or
+ * indented after a blank, belongs to the item rather than opening a paragraph,
+ * which is what keeps a wrapped bullet from reading as prose.
+ *
+ * A cap reports once per section or folder heading however far past it the
+ * count runs, since the fix is one cut either way. `Other folders` is exempt
+ * from both folder caps, its one-line bullets being held by the bullet run
+ * limit `canon markdown audit` already gates. The development entry's `Scripts`
+ * H3 is exempt from the heading rule and both caps the same way, its table
+ * being a run-command surface rather than a folder.
+ */
+function shapeIssues(
+  rel: string,
+  lines: readonly BodyLine[],
+  retired: readonly string[],
+): ShapeIssue[] {
+  const issues: ShapeIssue[] = []
+  const exempt = new Set([OTHER_FOLDERS])
+  if (isDevelopmentEntry(rel)) exempt.add(SCRIPTS_HEADING)
+  let section: string | undefined
+  let gotchas: { line: number; bullets: number } | undefined
+  let folder: FolderHeading | undefined
+  let inItem = false
+  let inParagraph = false
+  let afterBlank = false
+
+  const closeFolder = (): void => {
+    if (folder && !exempt.has(folder.text)) {
+      if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
+        issues.push({
+          line: folder.line,
+          kind: 'layout-paragraphs',
+          text: folder.text,
+          count: folder.paragraphs,
+        })
+      }
+      if (folder.bullets > LAYOUT_BULLET_CAP) {
+        issues.push({
+          line: folder.line,
+          kind: 'layout-bullets',
+          text: folder.text,
+          count: folder.bullets,
+        })
+      }
+    }
+    folder = undefined
+  }
+
+  const closeGotchas = (): void => {
+    if (gotchas && gotchas.bullets > GOTCHA_CAP) {
+      issues.push({
+        line: gotchas.line,
+        kind: 'gotcha-count',
+        text: 'Gotchas',
+        count: gotchas.bullets,
+      })
+    }
+    gotchas = undefined
+  }
+
+  for (const line of lines) {
+    if (line.fenced) continue
+
+    const heading = line.text.match(HEADING_LEVEL)
+    if (heading) {
+      const level = heading[1].length
+      const text = heading[2]
+      inItem = false
+      inParagraph = false
+      afterBlank = false
+
+      if (level <= 2) {
+        closeFolder()
+        closeGotchas()
+        section = level === 2 ? text : undefined
+        if (level === 2 && retired.includes(text)) {
+          issues.push({ line: line.number, kind: 'retired-section', text })
+        }
+        if (section === 'Gotchas') gotchas = { line: line.number, bullets: 0 }
+        continue
+      }
+
+      if (section === 'Gotchas') {
+        issues.push({ line: line.number, kind: 'gotcha-heading', text })
+      } else if (section === 'Layout' && level === 3) {
+        closeFolder()
+        folder = { line: line.number, text, bullets: 0, paragraphs: 0 }
+        if (!FOLDER_TITLE.test(text) && !exempt.has(text)) {
+          issues.push({ line: line.number, kind: 'layout-heading', text })
+        }
+      } else if (section === 'Layout') {
+        issues.push({ line: line.number, kind: 'layout-depth', text })
+      }
+      continue
+    }
+
+    if (line.text.trim() === '') {
+      inParagraph = false
+      afterBlank = true
+      continue
+    }
+
+    if (LIST_ITEM.test(line.text)) {
+      inItem = true
+      inParagraph = false
+      afterBlank = false
+      if (gotchas) gotchas.bullets++
+      if (folder) folder.bullets++
+      continue
+    }
+
+    const continues = inItem && (!afterBlank || INDENTED.test(line.text))
+    afterBlank = false
+    if (continues) continue
+
+    inItem = false
+    if (inParagraph) continue
+    inParagraph = true
+
+    if (gotchas) {
+      issues.push({
+        line: line.number,
+        kind: 'gotcha-paragraph',
+        text: line.text.trim(),
+      })
+    }
+    if (folder) folder.paragraphs++
+  }
+
+  closeFolder()
+  closeGotchas()
+
+  return issues.sort((a, b) => a.line - b.line)
+}
+
 /**
  * Finds the references naming a sibling entry by bare filename.
  *
@@ -557,6 +784,9 @@ export function measureEntry(
   siblings: readonly string[] = [],
   required: readonly string[] = governsContent ? REQUIRED_SECTIONS : [],
   allowed: readonly string[] = [],
+  retired: readonly string[] = governsContent
+    ? RETIRED_SECTIONS_BY_FOLDER.context
+    : [],
 ): EntryReport {
   const lines = bodyLines(source)
 
@@ -567,7 +797,8 @@ export function measureEntry(
     provenance: governsContent ? provenance(lines) : [],
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
-    otherSections: otherSections(lines, allowed),
+    otherSections: otherSections(lines, allowed, retired),
+    shape: governsContent ? shapeIssues(rel, lines, retired) : [],
     stub: isStubSeed(source),
     governed: governsContent,
   }
@@ -648,6 +879,7 @@ export async function measureFolders(
           names.filter((name) => name !== self),
           requiredSections(folder),
           allowedSections(folder),
+          retiredSections(folder),
         ),
       )
     }
@@ -675,6 +907,13 @@ export function allowedSections(folder: AuditedFolder): readonly string[] {
     : []
 }
 
+/** Names the H2 sections the folder's standard retired, empty where it retired none. */
+export function retiredSections(folder: AuditedFolder): readonly string[] {
+  return Object.hasOwn(RETIRED_SECTIONS_BY_FOLDER, folder.name)
+    ? RETIRED_SECTIONS_BY_FOLDER[folder.name]
+    : []
+}
+
 /**
  * Reports whether a bare sibling name here is a reference by construction.
  *
@@ -771,3 +1010,33 @@ export function extraSections(
     .filter((entry) => !entry.stub && entry.otherSections.length > 0)
     .map((entry) => ({ rel: entry.rel, headings: entry.otherSections }))
 }
+
+export interface ShapeFinding {
+  /** Repo-relative path of the entry breaking the shape. */
+  readonly rel: string
+  /** Whether the entry sits where the shape gates under `--gate`. */
+  readonly gated: boolean
+  /** Every break in the entry, never empty. */
+  readonly issues: readonly ShapeIssue[]
+}
+
+/**
+ * Names each entry breaking the section shape, and whether it gates.
+ *
+ * Where it gates is the caller's predicate rather than a list read here, since
+ * the folders rebuilt to the shape are named by path from the repository root
+ * and `measureFolders` holds only paths from the audit root. A stub seed is
+ * dropped for the reason `extraSections` drops one.
+ */
+export function shapeFindings(
+  entries: readonly EntryReport[],
+  isGated: (rel: string) => boolean,
+): ShapeFinding[] {
+  return entries
+    .filter((entry) => !entry.stub && entry.shape.length > 0)
+    .map((entry) => ({
+      rel: entry.rel,
+      gated: isGated(entry.rel),
+      issues: entry.shape,
+    }))
+}

package/src/context/classify/prompts.ts

@@ -5,7 +5,7 @@
  * mode) and `sweep-v1.md` (sweep mode). The diff prompt is verbatim. The sweep
  * prompt was tuned past `sweep-v1.md` with one decision check, measured
  * against the groundwork's labelled set in
- * `canon/context/context-model/overview.md`.
+ * `canon/context/context-model.md`.
  *
  * Each prompt already states its own rules per canonical doc type inside one
  * string, which is the shape the spike measured, so there is one prompt per

package/src/context/folders.ts

@@ -56,7 +56,7 @@ export interface AuditedFolder {
    * The requested folder name this was resolved under, which is what says
    * which standard governs the entries. A nested split folder carries the name
    * of the folder it sits beneath rather than its own, so
-   * `canon/context/claude-plugin` is governed as `context`.
+   * `canon/context/<domain>` is governed as `context`.
    */
   readonly name: string
   /**

package/src/context/gate.ts

@@ -1,4 +1,8 @@
-import type { ExtraSectionFinding, SectionFinding } from '@/context/audit'
+import type {
+  ExtraSectionFinding,
+  SectionFinding,
+  ShapeFinding,
+} from '@/context/audit'
 import type { FolderDrift } from '@/context/index-drift'
 
 export interface GateInput {
@@ -15,6 +19,11 @@ export interface GateInput {
   readonly sections: readonly SectionFinding[]
   /** H2 headings outside a folder's closed set, gating under `--gate` alone. */
   readonly extraSections: readonly ExtraSectionFinding[]
+  /**
+   * Section shape breaks, gating under `--gate` only where the finding is
+   * marked gated, so an unrebuilt entry reports and never fails a push.
+   */
+  readonly shape: readonly ShapeFinding[]
   readonly drift: readonly FolderDrift[]
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
@@ -36,17 +45,19 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
  * does a requirements record past its own word cap: the record states its rule
- * for itself, which makes it a fact rather than a threshold a reader weighs. The findings `--gate` adds are
- * the ones answerable from the file itself: a required section it does not
- * declare, an H2 outside the closed set, and an index disagreeing with its folder. Entry length, depth, bullet,
- * table, provenance, and the record's claim coverage are judgments, so they
- * stay out under both modes.
+ * for itself, which makes it a fact rather than a threshold a reader weighs.
+ * The findings `--gate` adds are the ones answerable from the file itself: a
+ * required section it does not declare, an H2 outside the closed set, a shape
+ * break in a folder rebuilt to the shape, and an index disagreeing with its
+ * folder. Entry length, depth, bullet, table, provenance, and the record's
+ * claim coverage are judgments, so they stay out under both modes.
  */
 export function isGating({
   unresolvedCitations,
   requirementsOverWords,
   sections,
   extraSections,
+  shape,
   drift,
   widened,
 }: GateInput): boolean {
@@ -54,5 +65,10 @@ export function isGating({
   if (requirementsOverWords) return true
   if (!widened) return false
 
-  return sections.length > 0 || extraSections.length > 0 || hasDrift(drift)
+  return (
+    sections.length > 0 ||
+    extraSections.length > 0 ||
+    shape.some((finding) => finding.gated) ||
+    hasDrift(drift)
+  )
 }

package/src/context/shape-gated.ts

@@ -0,0 +1,30 @@
+/**
+ * Path prefixes, from the repository root, whose context entries gate on the
+ * section shape under `--gate`.
+ *
+ * Every other entry still reports its shape findings and never fails a push,
+ * since the entries are rebuilt to the shape a batch at a time and an unrebuilt
+ * one carries `## Decisions` by construction. A batch rebuilding a folder adds
+ * its prefix here in the same change, which is what holds the folder to the
+ * shape from then on.
+ *
+ * Read against the repository root rather than the audit root, so a seed tree
+ * audited at its own root is listed by its path in the toolkit, such as
+ * `tooling/base/seeds/`, and never collides with the entry a target installs
+ * from it.
+ */
+export const SHAPE_GATED_FOLDERS: readonly string[] = [
+  'canon/context/context-model.md',
+  'canon/context/development/',
+  'canon/context/features/',
+  'canon/context/surfaces/',
+  'canon/context/workflow/',
+]
+
+/** Whether a repository-relative entry path sits under a gated prefix. */
+export function isShapeGated(
+  rel: string,
+  prefixes: readonly string[] = SHAPE_GATED_FOLDERS,
+): boolean {
+  return prefixes.some((prefix) => rel.startsWith(prefix))
+}

package/src/counts/scan.ts

@@ -80,7 +80,7 @@ function sentencesOf(line: string): string[] {
  * the 290 showed removing all of them while keeping that one.
  *
  * `authors` joined the list on a corpus measurement rather than on the shape
- * argument above. `canon/context/development/regeneration.md` states `the
+ * argument above. A context entry asserting `the
  * toolkit authors 69 rules under governance/rules/`, which is the assertion
  * shape this list was built for with a verb the list did not carry, and the
  * word costs one further sentence across the whole corpus and no finding.

package/src/design/components.ts

@@ -250,7 +250,7 @@ const TEACH_CHROME: Component = {
     'navigation shared by every teach page. Recovered from two gitignored',
     'course.css files that predate a regression that dropped this layer from the',
     "generator, and rewritten onto this module's tokens rather than the",
-    'incompatible palette they carried. See canon/context/features/teach/chrome.md',
+    'incompatible palette they carried. See canon/context/features/teach.md',
     'for the shape.',
   ].join('\n   '),
   reads: [

package/src/design/document.ts

@@ -95,7 +95,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  */
 const LEAD = [
   'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
-  'Why each value was chosen lives in `canon/context/design/tokens.md`.',
+  'Why each value was chosen lives in `canon/context/features/design.md`.',
 ].join(' ')
 
 function bullets(rules: readonly string[]): string {

package/src/design/tokens.ts

@@ -59,7 +59,7 @@ export interface BorderToken {
 /**
  * Every prose slot is a list of one-line rules rather than a string, so a
  * bullet is the unit the renderer emits and the prose budget counts, and a
- * value needing a paragraph of why goes to `canon/context/design/tokens.md`.
+ * value needing a paragraph of why goes to `canon/context/features/design.md`.
  */
 export interface DesignTokens {
   readonly personality: string

package/src/gate/boundaries.ts

@@ -211,7 +211,7 @@ function collectCommands(value: unknown, into: string[] = []): string[] {
 /**
  * A hook, a workflow, or a husky script reaching one side of the seed or config
  * boundary and not the other is a capability withheld with no recorded reason,
- * per the criterion in `canon/context/tooling/seeds.md`.
+ * per the criterion in `canon/context/surfaces/tooling.md`.
  *
  * Presence on either side clears a name, and a `canon-no-seed:` comment in the
  * file is the recorded reason. The same marker on a destination clears a
@@ -434,6 +434,9 @@ function grepLines(
  * seed itself installs, so every other spelling reports. No seed root, or roots
  * carrying no markdown, is unmeasured rather than a pass, which agrees with
  * `seedStandards` on the no-root case.
+ *
+ * The token matches as a substring, so `canonical` reports as `canon` does. The
+ * walk covers the seed roots alone, so a shipped rule citing the CLI passes.
  */
 export const seedIndependence: Measure = async (ctx) => {
   if (!isDirectory(join(ctx.root, 'tooling'))) {