@erclx/canon 4.116.0 → 4.118.0

package/src/commands/claude.ts

@@ -1397,6 +1397,7 @@ async function runSkillsAudit(
     reportFrontmatter(report)
     reportFolder(report)
     reportRequirementShape(report)
+    reportProvenance(report)
     reportUnmeasured()
     outro()
   }
@@ -1418,6 +1419,7 @@ async function runSkillsAudit(
           readme: report.readme,
           folderName: report.folderName,
           requirementSections: report.requirementSections,
+          datedProvenance: report.datedProvenance,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
@@ -1588,6 +1590,31 @@ function reportRequirementShape(report: SkillsAudit): void {
   reportFindings(report.requirementSections)
 }
 
+/**
+ * Names where the date belongs, since the finding is a date to move rather
+ * than one to delete, and reports without failing the run for the same reason
+ * the frontmatter measures do.
+ */
+function reportProvenance(report: SkillsAudit): void {
+  logStep('Provenance')
+  logInfo(
+    'A SKILL.md and its references state the current rule, with no ISO date outside a fence or code span.',
+  )
+  logInfo(
+    'The incident and date that earned a rule go in REQUIREMENT.md under Gap, or stay in git.',
+  )
+
+  if (report.datedProvenance.length === 0) {
+    logInfo('No body or reference carries a date.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.datedProvenance.length, 'date')} in a body or reference`,
+  )
+  reportFindings(report.datedProvenance)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard
@@ -1604,4 +1631,7 @@ function reportUnmeasured(): void {
   logInfo(
     'The 150-line body checkpoint is mechanical and still absent here, and it would print a count rather than a defect.',
   )
+  logInfo(
+    'Undated provenance, such as "a pull request dropped...", and a date written in words or without its day are not read.',
+  )
 }

package/src/commands/context.ts

@@ -56,12 +56,6 @@ import {
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
-import {
-  loadNarration,
-  type Narration,
-  PRONOUN_HEADING,
-  VERB_HEADING,
-} from '@/context/narration'
 import {
   measureWireframeFolder,
   type WireframeStatesReport,
@@ -101,7 +95,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record against its own ceiling, its own entry cap, and its word weight, and wireframe states against their evidence folders',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, index drift, the architecture record against its own ceiling, its own entry cap, and its word weight, and wireframe states against their evidence folders',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -133,8 +127,8 @@ export function register(program: Command): void {
         'findings that are facts rather than judgments: a missing required',
         'section and index drift. A context entry requires Overview and',
         'Layout, and a wireframe requires Regions, States, Copy, and Not on',
-        'this surface. Entry length, reference form, table, provenance, narration,',
-        'and the record claim classification are judgments under both.',
+        'this surface. Entry length, reference form, table, provenance, and the',
+        'record claim classification are judgments under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `canon markdown audit` measures them.',
@@ -653,24 +647,13 @@ async function runAudit(
     )
   }
 
-  const narration: Narration = gateOnly
-    ? { kind: 'absent' }
-    : await loadNarration(root)
-  const entries = gateOnly
-    ? []
-    : await measureFolders(
-        root,
-        folders,
-        narration.kind === 'loaded' ? narration : undefined,
-      )
+  const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
   const length = gateOnly ? undefined : lengthFindings(entries)
   // Absent under `--citations-only` and null when the project carries no
-  // record, for the reason `checkpoints.narration` states about its own two
-  // absences. A run that never looked and a project with nothing to look at
-  // are different answers, and one value for both reports the second as the
-  // first.
+  // record. A run that never looked and a project with nothing to look at are
+  // different answers, and one value for both reports the second as the first.
   const record = gateOnly ? undefined : await measureArchitecture(root)
   const wireframes = gateOnly
     ? []
@@ -693,7 +676,6 @@ async function runAudit(
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
-    reportNarration(entries, folders, narration)
     reportDrift(drift)
     reportRecord(record, root)
     reportWireframeStates(wireframes)
@@ -722,10 +704,11 @@ async function runAudit(
         // answers, and one wrong restatement is a cause reported against the
         // wrong entry.
         //
-        // Absent rather than empty under `--citations-only`, for the reason
-        // `checkpoints.narration` below carries. That mode measures no entry,
-        // so an empty array here reads as a corpus with nothing past the
-        // checkpoint rather than as a run that never looked.
+        // Absent rather than empty under `--citations-only`. That mode
+        // measures no entry, so an empty array here reads as a corpus with
+        // nothing past the checkpoint rather than as a run that never looked,
+        // and collapsing the two reports a measured answer for a run that
+        // never opened an entry.
         length,
         missingSections: sections,
         indexDrift: drift,
@@ -747,20 +730,6 @@ async function runAudit(
           // caller that read it before wireframes owed a section, since turning
           // it into this map would break that caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
-          // Three states rather than two, so a record showing no finding says
-          // which terms were looked for. The key is absent when the run never
-          // scanned, which is `--citations-only`, and null when it scanned and
-          // no rule published both headings. Collapsing the first into null
-          // reports an absent rule against a run that never opened one.
-          narration: gateOnly
-            ? undefined
-            : narration.kind === 'loaded'
-              ? {
-                  source: narration.source,
-                  pronouns: narration.pronouns,
-                  verbs: narration.verbs,
-                }
-              : null,
         },
       })}\n`,
     )
@@ -1144,75 +1113,6 @@ function reportProvenance(
   )
 }
 
-/**
- * Reports the bullets narrating a decision the bullet above them replaced.
- *
- * The reach line names the rule the sets were read from, since the check is
- * silent when no rule publishes them and a run that scanned nothing otherwise
- * prints the same clean line as a run that scanned everything.
- *
- * The legitimate-hit line is here for the same reason the provenance section
- * says a marker is a judgment. The standard keeps a rejected alternative and
- * why it lost, which is a back-reference in the past tense by construction, and
- * no measure separates one from the shape the rule bans.
- */
-function reportNarration(
-  entries: readonly EntryReport[],
-  folders: readonly AuditedFolder[],
-  narration: Narration,
-): void {
-  logStep('Narration')
-
-  const governed = folders.filter(governsContent)
-  if (governed.length === 0) {
-    logInfo(
-      `Out of scope. The rule is stated in the standard governing canon/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
-    )
-    return
-  }
-
-  if (narration.kind === 'absent') {
-    logWarn(
-      `Not scanned. No rule under .claude/rules/ or governance/rules/ publishes both ${PRONOUN_HEADING} and ${VERB_HEADING}.`,
-    )
-    return
-  }
-
-  logInfo(
-    `Covers canon/${PROVENANCE_FOLDER}/ alone, reading ${plural(narration.pronouns.length, 'pronoun')} and ${plural(narration.verbs.length, 'verb')} from ${narration.source}.`,
-  )
-  logInfo(
-    'A rejected alternative is a legitimate hit, since the standard keeps what was tried and why it lost.',
-  )
-
-  const carrying = entries
-    .filter((entry) => entry.narration.length > 0)
-    .sort((a, b) => b.narration.length - a.narration.length)
-
-  if (carrying.length === 0) {
-    logInfo('No bullet narrates a decision the bullet above it replaced.')
-    return
-  }
-
-  const total = carrying.reduce((sum, entry) => sum + entry.narration.length, 0)
-  logWarn(
-    `${plural(total, 'bullet')} to read across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
-  )
-  pipeOutput(
-    carrying
-      .map(
-        (entry) =>
-          `${entry.rel}  ${plural(entry.narration.length, 'bullet')}\n${entry.narration
-            .map(
-              (found) =>
-                `  :${found.line}  ${found.pronoun} with ${found.verb}`,
-            )
-            .join('\n')}`,
-      )
-      .join('\n'),
-  )
-}
-
 /** How each classification reads in the report. */
 const CLAIM_LABEL: Record<string, string> = {
   countable: 'countable claim',

package/src/commands/markdown.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
+import { lengthExemption } from '@/markdown/ceiling'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
 import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
@@ -16,6 +17,7 @@ import {
   BASELINE,
   CHECKPOINTS,
   type Checkpoints,
+  documentHeight,
   measureStructure,
   type StructureReport,
 } from '@/markdown/structure'
@@ -51,6 +53,9 @@ interface FileReport {
   readonly bans: readonly BanFinding[]
   readonly links: readonly LinkFinding[]
   readonly structure: StructureReport
+  readonly renderedLines: number
+  /** The stated reason, or null where the document is not exempt. */
+  readonly exempt: string | null
 }
 
 export function register(program: Command): void {
@@ -62,7 +67,7 @@ export function register(program: Command): void {
   markdown
     .command('audit')
     .description(
-      'Fail on a banned character, word, or spelling, and report bullet, paragraph, cadence, and depth',
+      'Fail on a banned character, word, or spelling, and report bullet, paragraph, cadence, depth, and length',
     )
     .argument(
       '[path...]',
@@ -85,6 +90,11 @@ export function register(program: Command): void {
         'Bullet, paragraph, and depth weight are judgments a reader settles,',
         'so all three report and none of them fails a run.',
         '',
+        'Length reports a whole document past the ceiling and never exits 2.',
+        'The Document ceiling gate stage owns that verdict, since this audit also',
+        'runs on a record kept out of version control, where a long plan is not',
+        'a defect.',
+        '',
         'Cadence reports the same way and carries one more caveat. Its range is',
         'drawn from prose a person reads, so terse reference prose sits below',
         'it correctly and a flat paragraph there is not a defect.',
@@ -148,7 +158,8 @@ async function runAudit(
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
       const abs = resolve(root, rel)
-      const lines = bodyLines(await readFile(abs, 'utf8'))
+      const source = await readFile(abs, 'utf8')
+      const lines = bodyLines(source)
       return {
         rel,
         bans: scanBans(lines, bans),
@@ -156,6 +167,8 @@ async function runAudit(
           existsSync(resolve(dirname(abs), path)),
         ),
         structure: measureStructure(rel, lines, checkpoints),
+        renderedLines: documentHeight(source, checkpoints.renderWidth),
+        exempt: lengthExemption(rel, source),
       }
     }),
   )
@@ -168,6 +181,7 @@ async function runAudit(
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
   reportDepth(reports, checkpoints)
+  reportLength(reports, checkpoints)
   outro()
 
   if (opts.json) {
@@ -192,6 +206,7 @@ async function runAudit(
           cadence: checkpoints.cadence,
           spread: checkpoints.spread,
           opener: checkpoints.opener,
+          ceiling: checkpoints.ceiling,
         },
         entries: reports.map((report) => ({
           path: report.rel,
@@ -202,6 +217,8 @@ async function runAudit(
           heavyBullets: report.structure.heavyBullets,
           heavyParagraphs: report.structure.heavyParagraphs,
           cadence: report.structure.cadence,
+          renderedLines: report.renderedLines,
+          exempt: report.exempt,
         })),
       })}\n`,
     )
@@ -606,3 +623,47 @@ function reportDepth(
       .join('\n'),
   )
 }
+
+/**
+ * Lists every document past the ceiling and counts the exempt ones rather than
+ * naming them, since an exemption is settled where its marker sits.
+ */
+function reportLength(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Length')
+  logInfo(
+    `Whole documents measure rendered lines at ${checkpoints.renderWidth} columns, frontmatter and fenced blocks included.`,
+  )
+  logInfo(
+    'A changelog is exempt by name, and so is a document carrying a canon-length-exempt marker that names a reason.',
+  )
+
+  const past = reports.filter(
+    (report) => report.renderedLines > checkpoints.ceiling,
+  )
+  const over = past
+    .filter((report) => report.exempt === null)
+    .sort((a, b) => b.renderedLines - a.renderedLines)
+  const exempt = past.length - over.length
+
+  if (over.length === 0) {
+    logInfo(`No document past the ${checkpoints.ceiling}-line ceiling.`)
+  } else {
+    logWarn(
+      `${plural(over.length, 'document')} past the ${checkpoints.ceiling}-line ceiling`,
+    )
+    pipeOutput(
+      over
+        .map(
+          (report) => `${report.rel}  ${report.renderedLines} rendered lines`,
+        )
+        .join('\n'),
+    )
+  }
+
+  if (exempt > 0) {
+    logInfo(`${plural(exempt, 'exempt document')} past the ceiling.`)
+  }
+}

package/src/commands/sync.ts

@@ -133,9 +133,9 @@ function renderCheck(report: CheckReport): void {
       logWarn(entry.notice ?? `${entry.rel} (${entry.state})`)
     }
 
-    const { stale, customized, drifted, stranded, orphaned, missing } =
+    const { stale, customized, drifted, stranded, retired, orphaned, missing } =
       domain.counts
-    if (stale + customized + drifted + stranded === 0) {
+    if (stale + customized + drifted + stranded + retired === 0) {
       logInfo(orphaned === 0 ? 'up to date' : `up to date (${orphaned} local)`)
     }
     // A local file is not a deficiency and a missing rule is, so this never

package/src/context/audit.ts

@@ -2,9 +2,8 @@ import { readFile } from 'node:fs/promises'
 import { basename, relative } from 'node:path'
 import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
 import type { AuditedFolder } from '@/context/folders'
-import type { NarrationTerms } from '@/context/narration'
 import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
-import { renderedHeight } from '@/markdown/structure'
+import { documentHeight } from '@/markdown/structure'
 import { isStubSeed } from '@/seed-marker'
 
 /**
@@ -80,10 +79,6 @@ const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/
 
-const TOP_BULLET = /^-\s+(.+)$/
-/** Any indented line, which is a nested bullet or a wrapped continuation. */
-const INSIDE_LIST = /^\s+\S/
-
 /**
  * Spellings of how the domain reached its shape rather than what it is now.
  *
@@ -156,9 +151,9 @@ const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/
 /**
  * The folder whose standard carries the exclusion above.
  *
- * Three measures narrow here rather than one: provenance, the required
- * sections, and the superseded-decision narration. The name is the first of
- * them because it was the first, and it stays because renaming a constant the
+ * Two measures narrow here rather than one: provenance and the required
+ * sections. The name is the first of them because it was the first, and it
+ * stays because renaming a constant the
  * JSON record publishes as `checkpoints.provenanceFolder` breaks every consumer
  * reading that field for a gain of one word.
  *
@@ -202,21 +197,14 @@ export interface BareReferenceFinding {
   readonly name: string
 }
 
-export interface NarrationFinding {
-  readonly line: number
-  /** The opening that points back at the bullet above. */
-  readonly pronoun: string
-  /** The past-tense verb that turns the back-reference into a narration. */
-  readonly verb: string
-}
-
 export interface EntryReport {
   readonly rel: string
   /**
    * Rendered lines across the whole file, counting frontmatter and fenced
-   * blocks. It shares `renderedHeight` with the depth checkpoint in
-   * `src/markdown/structure.ts`, since the two sit in one section of the
-   * standard and a reader compares them.
+   * blocks. It counts through `documentHeight` in `src/markdown/structure.ts`,
+   * which shares `renderedHeight` with the depth checkpoint and with the
+   * document ceiling, since all three sit beside each other in the standard
+   * and a reader compares them.
    *
    * Fences are counted here and excluded there. The depth measure skips one so
    * an example cannot break the run around it, and a file measure has no run to
@@ -228,12 +216,6 @@ export interface EntryReport {
   readonly catalogTables: readonly TableFinding[]
   /** Empty for an entry no standard bans a change narrative in. */
   readonly provenance: readonly ProvenanceFinding[]
-  /**
-   * Empty outside the governed folder, and empty on a run whose caller loaded
-   * no term sets. The report distinguishes the two from the vocabulary itself,
-   * since an empty list here is silent about which one produced it.
-   */
-  readonly narration: readonly NarrationFinding[]
   /**
    * References naming a sibling entry by bare filename, and empty for a caller
    * that passed no sibling names. Which entries have siblings worth matching is
@@ -433,125 +415,6 @@ function stampsMeasurement(text: string, index: number): boolean {
   return STAMPING.test(clause) || STAMPING_RUN.test(clause)
 }
 
-function escape(term: string): string {
-  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-/**
- * Copulas that turn the verb behind them into a present-tense passive.
- *
- * `used to` is the term this exists for, since `is used to resolve the folder`
- * is the passive of `use` rather than the past habitual the set means. This
- * list is English grammar rather than corpus vocabulary, so it stays in code
- * while the two tunable sets stay in the rule, and a rule publishing two of
- * three headings would be a fourth absent state to carry for no tuning anyone
- * wants.
- *
- * What it costs is the perfect passive. `has been superseded` narrates a
- * supersession and is rejected with the rest, which is a recall gap taken
- * knowingly on the trade this check already makes everywhere else.
- */
-const COPULA = ['is', 'are', 'be', 'been', 'being', 'was', 'were']
-
-/**
- * Finds the bullets narrating a decision the bullet above them replaced.
- *
- * The signal is structural rather than lexical, and the corpus is what decides
- * that. The terms carrying clean signal for a supersession are too rare to
- * catch anything, and the one term that would have caught the known case is
- * `now`, which appears 57 times across 24 entries in correct present-tense
- * prose. What separates the shape instead is a bullet pointing back at its
- * sibling and putting the sibling's design in the past: an opening pronoun with
- * no antecedent of its own, plus a past-tense verb, plus a bullet above it to
- * refer to. Precision is the whole value, so recall is the accepted exposure
- * and a narration written as a single bullet is not reached.
- *
- * The pronoun is matched cased and anchored, since a mid-sentence `this` is a
- * determiner rather than a back-reference. The verb is matched uncased anywhere
- * in the bullet, since the tense is what carries the signal wherever it sits,
- * and rejected behind a `COPULA` for the reason stated there. Displayed spans
- * are masked so a term quoted in backticks is not read as prose the entry
- * writes, and fenced blocks are skipped for the reason the scans above skip
- * them.
- *
- * A blank line does not end the run. Markdown reads two bullets around one as a
- * single loose list, so breaking there would leave the shape reachable by
- * anyone who spaced their bullets out. What ends a run is content that is
- * neither a bullet nor indented under one, which the fenced branch below has to
- * answer for itself because a fenced line is skipped before that test.
- */
-function narration(
-  lines: readonly BodyLine[],
-  terms: NarrationTerms,
-): NarrationFinding[] {
-  if (terms.pronouns.length === 0 || terms.verbs.length === 0) return []
-
-  const findings: NarrationFinding[] = []
-  let following = false
-  let fenceBlock: number | undefined
-  let fenceInsideList = false
-
-  for (const line of lines) {
-    // A fenced line is never a bullet, but an unindented block still ends the
-    // run. CommonMark reads a fence at column zero as interrupting the list, so
-    // the bullets around it are two lists and the second has no antecedent
-    // above it. A block indented under its bullet stays inside the item.
-    //
-    // The opening delimiter decides for every line of its own block. Reading
-    // each line instead ends the run on a blank line inside an indented fence,
-    // which has no indentation to read, and on a content line at column zero,
-    // which CommonMark permits since only the fence's own indent is stripped.
-    //
-    // The block index is what re-opens that decision, so two blocks written
-    // with nothing between them are answered separately rather than the second
-    // inheriting the first. Indentation stays the test here because what
-    // interrupts a list is this check's own judgment, and the walker only says
-    // which lines share a block.
-    if (line.fenced) {
-      if (line.fenceBlock !== fenceBlock) {
-        fenceBlock = line.fenceBlock
-        fenceInsideList = INSIDE_LIST.test(line.text)
-      }
-      if (!fenceInsideList) following = false
-      continue
-    }
-
-    if (line.text.trim() === '') continue
-
-    const bullet = line.text.match(TOP_BULLET)
-    if (!bullet) {
-      // A nested bullet and a wrapped continuation both sit inside the list, so
-      // neither ends the run. Anything else does, which is what keeps a bullet
-      // opening the list under a heading from reading as a reply to the last
-      // bullet of the list before it.
-      if (!INSIDE_LIST.test(line.text)) following = false
-      continue
-    }
-
-    const text = maskDisplayed(bullet[1])
-
-    if (following) {
-      const pronoun = terms.pronouns.find((term) =>
-        new RegExp(`^${escape(term)}\\b`).test(text),
-      )
-      const verb = pronoun
-        ? terms.verbs.find((term) =>
-            new RegExp(
-              `(?<!\\b(?:${COPULA.join('|')})\\s+)\\b${escape(term)}\\b`,
-              'i',
-            ).test(text),
-          )
-        : undefined
-
-      if (pronoun && verb) findings.push({ line: line.number, pronoun, verb })
-    }
-
-    following = true
-  }
-
-  return findings
-}
-
 /**
  * Finds which required sections the entry declares.
  *
@@ -638,7 +501,6 @@ export function measureEntry(
   rel: string,
   source: string,
   governsContent = true,
-  terms?: NarrationTerms,
   siblings: readonly string[] = [],
   required: readonly string[] = governsContent ? REQUIRED_SECTIONS : [],
 ): EntryReport {
@@ -646,13 +508,9 @@ export function measureEntry(
 
   return {
     rel,
-    lines: source
-      .replace(/\n$/, '')
-      .split('\n')
-      .reduce((sum, text) => sum + renderedHeight(text), 0),
+    lines: documentHeight(source),
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
-    narration: governsContent && terms ? narration(lines, terms) : [],
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
     stub: isStubSeed(source),
@@ -716,7 +574,6 @@ function historyCause(entry: EntryReport): LengthCause {
 export async function measureFolders(
   root: string,
   folders: readonly AuditedFolder[],
-  terms?: NarrationTerms,
 ): Promise<EntryReport[]> {
   const reports: EntryReport[] = []
 
@@ -733,7 +590,6 @@ export async function measureFolders(
           relative(root, path),
           await readFile(path, 'utf8'),
           governsContent(folder),
-          terms,
           names.filter((name) => name !== self),
           requiredSections(folder),
         ),