@erclx/canon 4.117.0 → 4.118.0

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/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,7 +2,6 @@ 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 { 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,14 +197,6 @@ 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
   /**
@@ -229,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
@@ -434,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.
  *
@@ -639,7 +501,6 @@ export function measureEntry(
   rel: string,
   source: string,
   governsContent = true,
-  terms?: NarrationTerms,
   siblings: readonly string[] = [],
   required: readonly string[] = governsContent ? REQUIRED_SECTIONS : [],
 ): EntryReport {
@@ -650,7 +511,6 @@ export function measureEntry(
     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),
@@ -714,7 +574,6 @@ function historyCause(entry: EntryReport): LengthCause {
 export async function measureFolders(
   root: string,
   folders: readonly AuditedFolder[],
-  terms?: NarrationTerms,
 ): Promise<EntryReport[]> {
   const reports: EntryReport[] = []
 
@@ -731,7 +590,6 @@ export async function measureFolders(
           relative(root, path),
           await readFile(path, 'utf8'),
           governsContent(folder),
-          terms,
           names.filter((name) => name !== self),
           requiredSections(folder),
         ),

package/src/gate/measures.ts

@@ -12,6 +12,7 @@ import {
   isOverLength,
   measureArchitecture,
 } from '@/context/architecture'
+import { auditSkills } from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
@@ -277,6 +278,42 @@ export const architectureRecord: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every skill body and reference against the no-dated-provenance rule, across
+ * both corpora `auditSkills` reads.
+ *
+ * Read in-process rather than through `claude skills audit`, whose exit code
+ * stays a missing requirement only, so a target running the verb is told about
+ * a date without failing on one. This repository holds the corpus at zero,
+ * which is what lets the same finding fail here.
+ */
+export const skillProvenance: Measure = async (ctx) => {
+  const report = await auditSkills(ctx.root)
+  if (report.corpora.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: 'no skill corpus resolved, so no body was read.',
+    }
+  }
+
+  const found = report.datedProvenance
+  if (found.length > 0) {
+    const where = found
+      .map((finding) => `${finding.rel} ${finding.detail}`)
+      .join(', ')
+    return {
+      emissions: [],
+      failure: `${plural(found.length, 'date')} in skill prose: ${where}. Move the incident to REQUIREMENT.md under Gap or leave it to git, or fence the date or put it in a code span when it is an example.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info(`No dated provenance across ${plural(report.skills, 'skill')}`),
+    ],
+  }
+}
+
 /**
  * Every tracked markdown document against the whole-document ceiling.
  *

package/src/gate/stages.ts

@@ -13,6 +13,7 @@ import {
   seedStandards,
   rawFieldFileReference,
   shippedReferences,
+  skillProvenance,
   standardCriteria,
   unreferencedRules,
   visualPathGlobs,
@@ -468,6 +469,14 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Skill requirements present',
   },
+  {
+    // The audit verb only reports a dated line, so a target is told without
+    // failing. This stage makes the same finding fail here, where the corpus is
+    // held at zero. Unscoped, since any branch can add a line to any body.
+    id: 'skill-provenance',
+    label: 'Skill provenance',
+    checks: [{ kind: 'measure', measure: skillProvenance }],
+  },
   {
     id: 'standard-criteria',
     label: 'Standard success criteria',

package/src/gov/adapter.ts

@@ -44,12 +44,13 @@ export function indexSourceRules(root: string): Map<string, string> {
  * path, so a rule that moved between subdirectories in the toolkit still
  * syncs into the subdirectory the target already uses.
  *
- * Declares no `projectSubdir`. That exemption existed to keep a project's
- * `.claude/rules/project/` folder out of the walk by location before any
- * name lookup ran, and `installedRoot` narrowing to `.claude/rules/canon/`
- * already leaves `project/` outside the walked root, so a second exemption
- * computing a stale `canon/project/` destination would be wrong rather than
- * merely redundant.
+ * Declares `ownsInstalledRoot` and no `projectSubdir`. A project keeps its own
+ * rules under `.claude/rules/project/`, which `installedRoot` narrowing to
+ * `.claude/rules/canon/` leaves outside the walk, so everything the walk does
+ * reach is the toolkit's. A rule there with no source is one the toolkit
+ * retired or renamed, and the sync deletes it rather than leaving it loaded.
+ * A `projectSubdir` would compute a stale `canon/project/` destination, which
+ * is wrong rather than merely redundant.
  */
 export function createGovAdapter(root: string): SyncAdapter {
   const index = indexSourceRules(root)
@@ -65,6 +66,7 @@ export function createGovAdapter(root: string): SyncAdapter {
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
     collectMissing: (target: string) => collectMissingGov(root, target),
+    ownsInstalledRoot: true,
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }

package/src/records/validate.ts

@@ -271,7 +271,9 @@ const PLAN_SECTIONS = [
   'Summary',
   'Constraints',
   'Files to touch',
+  'Verification',
   'Risks',
+  'Review focus',
   'Questions',
 ] as const
 
@@ -280,7 +282,9 @@ type PlanSection = (typeof PLAN_SECTIONS)[number]
 const PLAN_REQUIRED: readonly PlanSection[] = [
   'Summary',
   'Files to touch',
+  'Verification',
   'Risks',
+  'Review focus',
   'Questions',
 ]
 
@@ -293,7 +297,7 @@ const MARKER_LINE = /^(?:##[ \t]+(.+?)|\*\*(.+?):\*\*)[ \t]*$/
 
 /**
  * A section opens as a bold label or as an H2 and both count. The corpus writes
- * `Summary` as a heading and the other four as bold labels, and roughly a fifth
+ * `Summary` as a heading and the others as bold labels, and roughly a fifth
  * of it swaps one for the other. Reporting the variant would fail nearly every
  * plan present on the rule a reader is least served by, which is what teaches
  * them to skip the output.

package/src/sync/check.ts

@@ -79,6 +79,7 @@ export interface StateCounts {
   readonly orphaned: number
   readonly stranded: number
   readonly missing: number
+  readonly retired: number
 }
 
 export interface DomainReport {
@@ -314,6 +315,7 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
     orphaned: count(entries, 'orphaned'),
     stranded: count(entries, 'stranded'),
     missing: count(entries, 'missing'),
+    retired: count(entries, 'retired'),
   }
 }
 
@@ -342,6 +344,9 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * sync that adds a rule silently changes what a project is governed by, and
  * nobody chose that, so gating CI on the count would pressure a target into
  * adopting a rule nobody picked.
+ *
+ * `retired` counts, since a sync deletes it mechanically. A target's CI goes
+ * red the day a release retires a rule it holds, and one sync clears it.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -351,7 +356,8 @@ export function hasDrift(report: CheckReport): boolean {
       domain.counts.stale +
         domain.counts.customized +
         domain.counts.drifted +
-        domain.counts.stranded >
+        domain.counts.stranded +
+        domain.counts.retired >
       0,
   )
 }