@erclx/aitk 0.64.0 → 0.65.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -9,33 +9,33 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 ## Project-level
 
-| Command                    | Purpose                                                                                        |
-| -------------------------- | ---------------------------------------------------------------------------------------------- |
-| `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                              |
-| `aitk sync [path]`         | Sync all installed domains in a target project                                                 |
-| `aitk sync --check`        | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
-| `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
-| `aitk sandbox reset`       | Reset sandbox to baseline                                                                      |
-| `aitk sandbox clean`       | Wipe the sandbox                                                                               |
-| `aitk sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
-| `aitk sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                 |
-| `aitk indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                           |
-| `aitk docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                       |
-| `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                              |
-| `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                     |
-| `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                    |
-| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github` |
-| `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
-| `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
-| `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)       |
-| `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                      |
-| `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
-| `aitk records validate`    | Report a session record against the standard governing it, per kind (`--json`)                 |
-| `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`       | Report required sections, length, cited paths, catalog tables, provenance, and index drift     |
-| `aitk markdown audit`      | Report any markdown path against the character bans, word bans, and structural checkpoints     |
-| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                 |
-| `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
+| Command                    | Purpose                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                                                         |
+| `aitk sync [path]`         | Sync all installed domains in a target project                                                                            |
+| `aitk sync --check`        | Report toolkit drift without writing (`--json`, `--exit-code`)                                                            |
+| `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                        |
+| `aitk sandbox reset`       | Reset sandbox to baseline                                                                                                 |
+| `aitk sandbox clean`       | Wipe the sandbox                                                                                                          |
+| `aitk sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                     |
+| `aitk sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                            |
+| `aitk indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                                                      |
+| `aitk docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                                                  |
+| `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                         |
+| `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                                                |
+| `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                                               |
+| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github`                            |
+| `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                     |
+| `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                       |
+| `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                  |
+| `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                 |
+| `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)                                      |
+| `aitk records validate`    | Report a session record against the standard governing it, per kind (`--json`)                                            |
+| `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                    |
+| `aitk context audit`       | Report required sections, length, cited paths, catalog tables, provenance, superseded-decision narration, and index drift |
+| `aitk markdown audit`      | Report any markdown path against the character bans, word bans, and structural checkpoints                                |
+| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                            |
+| `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                     |
 
 ## Domain commands
 

package/docs/agents/context-audit-checks.md

@@ -19,7 +19,7 @@ It reports rather than gates by default, the closer call because a missing secti
 
 ## Length
 
-Length quotes its checkpoint from `.claude/standards/context.md`: roughly 150 rendered lines for an entry. It counts rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. The measure counts fenced blocks and frontmatter, so a reference-heavy entry ranks by its examples, which the legend states on every run alongside the width, since a number in rendered lines cannot be reproduced without it.
+Length quotes its checkpoint from `.claude/standards/context.md`: roughly 150 rendered lines for an entry. It counts rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. A line is wrapped at the width it renders at, so a link counts as its anchor text and a backticked path counts whole. That moves 2 of the 48 entries measured, `extensions.md` by 2 lines and `governance.md` by 1, because an entry cites a path in backticks rather than as a link. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. The measure counts fenced blocks and frontmatter, so a reference-heavy entry ranks by its examples, which the legend states on every run alongside the width, since a number in rendered lines cannot be reproduced without it.
 
 Depth and bullet weight are quoted from `.claude/standards/markdown.md`, which states both over every markdown file rather than over a context entry, so `aitk markdown audit` measures them and this command no longer does. They share `renderedHeight` with the length measure, since the two checkpoints sit in one section of that standard and a reader compares them. What the split costs is that a session wanting both numbers for one entry runs two commands, and what it buys is that either number can be had for a file in a folder this audit refuses to resolve.
 
@@ -31,9 +31,27 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
 
+## Narration
+
+The narration check reports a bullet that states the design a sibling bullet replaced instead of rewriting it. `.claude/standards/context.md` asks for the rewrite because the subject is still live and two bullets on one subject leave a reader to work out which of them is current, and no other measure sees that shape.
+
+It reads structure rather than words, which the corpus decided. Measured across the 39 entries this toolkit held the day it shipped, the terms carrying clean signal for a supersession are too rare to catch anything: `superseded` appears twice, `previously` three times, and `formerly`, `originally`, and `at first` never. The one term that would have caught the case a review caught by hand is `now`, which appears 57 times across 24 entries in correct present-tense prose. A list including it reports 57 lines to catch one, and a list excluding it reports nothing.
+
+What it matches instead is a bullet doing three things at once: opening with a pronoun whose antecedent is the bullet above it, carrying a past-tense verb, and following another top-level bullet. All three are required. Eight bullets in the corpus open with a back-reference, and the verb set narrows those to one. The pronoun is matched cased and anchored to the opening, since a mid-sentence `this` is a determiner rather than a reference back. The verb is matched uncased anywhere in the bullet, and rejected when a copula sits in front of it, since `is used to resolve the folder` is the passive of `use` rather than the past habitual the set means. Both sets are published under `## Narration pronouns` and `## Narration verbs` in a governance rule and read at run time, so widening either costs a rule edit rather than a TypeScript change. The copula list stays in code, because it is English grammar rather than corpus vocabulary and a rule publishing two of three headings would be another absent state to carry. Discovery keys on the headings rather than the filename, because rules are numbered and a renumber would empty the sets while the check kept reporting clean. A run finding no rule that publishes both says it scanned nothing rather than reporting clean.
+
+A blank line does not end the run. Markdown reads the bullets around one as a single loose list, so a walker that broke 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 is what keeps the first bullet under a heading from reading as a reply to the last bullet above it.
+
+A fence answers that test for itself, because every scan here skips a fenced line before reaching it. An unindented fence ends the run, since CommonMark reads one at column zero as interrupting the list and the bullets around it are then two lists with no antecedent crossing between them. A fence indented under its bullet stays inside the item and leaves the run intact.
+
+The opening delimiter decides that for the whole block rather than each line deciding for itself. A blank line inside an indented fence carries no indentation to read, and a content line may sit at column zero inside one because CommonMark strips the fence's own indent and nothing further. Reading either as unindented ends a run that should have continued, which costs findings rather than inventing them, so no corpus count moves when it is wrong.
+
+Two fenced blocks with nothing between them read as one, so the second takes the first's answer. An unindented block written directly behind an indented one therefore leaves a run standing that it should have ended, which is a false positive rather than a missed finding. Separating the two needs the closing delimiter, which the line walker does not report, and no entry writes adjacent fences today.
+
+Precision is the whole value, so recall is the accepted exposure, and two shapes are knowingly out of reach. A narration written as one bullet carrying its own before and after slips through, and nothing else sees it either. So does the perfect passive, since `has been superseded` narrates a supersession and the copula guard rejects it with the passives it exists for. A rejected alternative is a back-reference in the past tense by construction, and the standard keeps what was tried and why it lost, so a legitimate hit exists and no measure separates it from a violation. The report states that on every run, which is why the finding names a line to read rather than a line to delete. The JSON record carries the findings per entry as `entries[].narration` and the sets as `checkpoints.narration`, which is absent under `--citations-only` where the run never loads them and null where no rule publishes both.
+
 ## Which folders each check reaches
 
-The provenance and required-section checks cover `.claude/context/` alone, while length and the table finding reach every audited folder. What narrows the two is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures. Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all.
+The provenance, required-section, and narration checks cover `.claude/context/` alone, while length and the table finding reach every audited folder. What narrows the three is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere, and a diagram entry carries a heading per kind rather than a run of bullets deciding anything. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures. Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all.
 
 The same test is what moved depth and bullet weight out of this command entirely. A rule stated at the attribute tier reaches every markdown file, and a check reaching every markdown file has no reason to require a folder that resolves. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
 

package/docs/agents/context-audit.md

@@ -37,7 +37,7 @@ A run where no requested name resolves refuses, whichever list it read. Naming t
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. Length, table, and provenance findings print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. Length, table, provenance, and narration findings print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around. Narration is the weakest of the four, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
 
 Required-section and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 

package/docs/agents/markdown-audit.md

@@ -41,13 +41,21 @@ Deriving the spellings rather than pattern-matching a suffix is what keeps `exer
 
 Frontmatter, fenced blocks, inline code spans, and link destinations are excluded. Without the code-span exclusion each standard would report its own backticked examples, and without the link exclusion a semicolon in a query string would report as prose no rewrite can fix.
 
+A banned word is bounded on a word character or a hyphen either side. A plain word boundary sits after a hyphen, so a banned word ending a hyphenated compound reported from inside one, and a compound is a single word to the reader who wrote it.
+
+A banned spelling keeps the plain word boundary, hyphens included. The two bans target different things: a word ban targets the word, so reading a compound as one word is correct, while a spelling ban targets the orthography inside it, which sits in `behaviour-driven` as plainly as it sits alone.
+
 Two ban shapes stay unmeasured and the report says so on every run. A phrase ban carries a placeholder standing in for the rest of the sentence, so no literal match reaches it, and every rule under `## Voice` is a judgment. A report listing hits without naming those would read as a verdict on the whole standard.
 
 ### Bullets, paragraphs, and depth
 
 Bullet weight and depth are the checks that moved off `aitk context audit`, unchanged in what they measure. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run of lines no heading breaks reports past roughly 40 rendered lines, measured at 80 columns, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows.
 
-The paragraph check is new and measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: measured across 2906 paragraphs, 344 sit inside four sentences and past 400 characters, and the heaviest runs 1159 characters in two. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan above: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
+
+A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
+
+The paragraph check is new and measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: measured across 3374 paragraphs, 486 sit inside four sentences and past 400 characters, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
 
 The paragraph weight and the bullet weight are the same number today because the two shapes measure one population, sharing a median near 170 characters with no gap behind either candidate. They are separate checkpoints in the standard and separate patterns in the parser, so retuning one leaves the other where it is.
 
@@ -59,7 +67,9 @@ Exit codes are `0` for a completed run and `1` for a refusal. Every finding repo
 
 A banned character is a fact rather than a judgment, which is the test that would ordinarily make it gate. What holds it back is that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order is to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change. Bullet, paragraph, and depth weight are judgments and stay advisory under any later gate.
 
-Measured across 443 files on the day this shipped: 9 word hits, no character or spelling hits, 109 heavy bullets, 610 heavy paragraphs, and 42 files carrying a run past the depth checkpoint. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+Measured across 444 files once the weight measures moved to visible text: 8 word hits, no character or spelling hits, 119 heavy bullets, 615 heavy paragraphs, and 40 files carrying a run past the depth checkpoint. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+
+Masking took 7 of the 493 weight-only paragraphs and 4 of the 44 files under their checkpoints, and no bullet at all. The first corpus triage put those at 31 paragraphs and 2 bullets, and neither reproduces: a code span is walked around, so a backticked path holding an angle-bracket placeholder keeps the width the page gives it, and both bullets the triage counted were that shape.
 
 ## What it does not cover
 

package/governance/rules/claude/510-context.md

@@ -12,6 +12,18 @@ paths:
 - Leave the entry conforming when work in its domain changes what it describes.
 - Rewrite the decision a change supersedes rather than appending a second one narrating the transition.
 
+## Narration pronouns
+
+Do not open a bullet with one of these where the antecedent is the bullet above it.
+
+- `It`, `That`, `This`, `These`, `Those`, `They`
+
+## Narration verbs
+
+Do not put a sibling bullet's design in the past with one of these.
+
+- `was`, `were`, `became`, `replaced`, `superseded`, `used to`
+
 ## Authority
 
 - Follow `.claude/standards/context.md` for entry shape: frontmatter, sections, length, and what goes in. It is the single source.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/context.ts

@@ -19,6 +19,12 @@ 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 { RENDER_WIDTH } from '@/markdown/structure'
 import {
   frameError,
@@ -54,7 +60,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, catalog tables, provenance, and index drift',
+      'Report required sections, entry length, citations, catalog tables, provenance, superseded-decision narration, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -79,8 +85,8 @@ export function register(program: Command): void {
         '',
         'An unresolved citation always gates. --gate widens the gate to the',
         'other two findings that are facts rather than judgments: a missing',
-        'required section and index drift. Length, table, and provenance',
-        'findings are thresholds and stay advisory under both.',
+        'required section and index drift. Length, table, provenance, and',
+        'narration findings are judgments and stay advisory under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `aitk markdown audit` measures them.',
@@ -180,7 +186,16 @@ async function runAudit(
     )
   }
 
-  const entries = gateOnly ? [] : await measureFolders(root, folders)
+  const narration: Narration = gateOnly
+    ? { kind: 'absent' }
+    : await loadNarration(root)
+  const entries = gateOnly
+    ? []
+    : await measureFolders(
+        root,
+        folders,
+        narration.kind === 'loaded' ? narration : undefined,
+      )
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
 
@@ -194,6 +209,7 @@ async function runAudit(
     reportLength(entries)
     reportTables(entries)
     reportProvenance(entries, folders)
+    reportNarration(entries, folders, narration)
     reportDrift(drift)
     outro()
   }
@@ -222,6 +238,20 @@ async function runAudit(
           renderWidth: RENDER_WIDTH,
           provenanceFolder: PROVENANCE_FOLDER,
           requiredSections: REQUIRED_SECTIONS,
+          // 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`,
     )
@@ -486,6 +516,75 @@ 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 .claude/${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 .claude/${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'),
+  )
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

package/src/context/audit.ts

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import type { AuditedFolder } from '@/context/folders'
-import { type BodyLine, bodyLines } from '@/markdown/scan'
+import type { NarrationTerms } from '@/context/narration'
+import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
 import { renderedHeight } from '@/markdown/structure'
 import { isStubSeed } from '@/seed-marker'
 
@@ -46,6 +47,10 @@ 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.
  *
@@ -64,6 +69,12 @@ const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
 /**
  * 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
+ * JSON record publishes as `checkpoints.provenanceFolder` breaks every consumer
+ * reading that field for a gain of one word.
+ *
  * `standards/context.md` opens its scope by handing diagrams and wireframes to
  * `diagrams.md` and `wireframes.md`, so a marker reported in either would cite
  * a rule that entry's own standard routes elsewhere. The length and table
@@ -98,6 +109,14 @@ export interface ProvenanceFinding {
   readonly text: 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
   /**
@@ -116,6 +135,12 @@ 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[]
   /**
    * Required sections this entry declares, in the standard's order, and empty
    * outside the folder whose standard names them. What the folder is short of
@@ -226,6 +251,128 @@ function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
     .map((each) => each.finding)
 }
 
+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 fenceInsideList: boolean | undefined
+
+  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 first delimiter of a contiguous fenced run decides for every line of
+    // it. 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.
+    //
+    // Two blocks with nothing between them are one such run, so the second
+    // inherits the first's answer and an unindented block behind an indented
+    // one leaves a run standing that should have ended. Telling them apart
+    // needs the closing delimiter, which `BodyLine` does not carry, and parsing
+    // one here would be the second fence walker this repository consolidated
+    // away after its first pair disagreed. That fix belongs in
+    // `src/markdown/scan.ts` rather than in a copy of it.
+    if (line.fenced) {
+      if (fenceInsideList === undefined) {
+        fenceInsideList = INSIDE_LIST.test(line.text)
+      }
+      if (!fenceInsideList) following = false
+      continue
+    }
+
+    fenceInsideList = undefined
+
+    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.
  *
@@ -264,6 +411,7 @@ export function measureEntry(
   rel: string,
   source: string,
   governsContent = true,
+  terms?: NarrationTerms,
 ): EntryReport {
   const lines = bodyLines(source)
 
@@ -275,6 +423,7 @@ export function measureEntry(
       .reduce((sum, text) => sum + renderedHeight(text), 0),
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
+    narration: governsContent && terms ? narration(lines, terms) : [],
     sections: governsContent ? declaredSections(lines) : [],
     stub: isStubSeed(source),
   }
@@ -291,6 +440,7 @@ export function measureEntry(
 export async function measureFolders(
   root: string,
   folders: readonly AuditedFolder[],
+  terms?: NarrationTerms,
 ): Promise<EntryReport[]> {
   const reports: EntryReport[] = []
 
@@ -301,6 +451,7 @@ export async function measureFolders(
           relative(root, path),
           await readFile(path, 'utf8'),
           governsContent(folder),
+          terms,
         ),
       )
     }

package/src/context/narration.ts

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/**
+ * The headings a rule carries to publish the two sets.
+ *
+ * Discovery is anchored on these rather than on a filename for the reason
+ * `src/comments/vocabulary.ts` anchors its own: governance rules are numbered,
+ * and a renumber would empty the sets while the check kept reporting clean.
+ * Both open with `Narration` so neither loader can read the other's list.
+ */
+export const PRONOUN_HEADING = '## Narration pronouns'
+export const VERB_HEADING = '## Narration verbs'
+
+/**
+ * Roots searched in order. The installed copy wins over the toolkit source, so
+ * a target project measures against the rule it actually has rather than one
+ * only the toolkit carries.
+ */
+const RULE_ROOTS = ['.claude/rules', 'governance/rules']
+
+export interface NarrationTerms {
+  /** Back-reference openings, matched at the start of a bullet and cased. */
+  readonly pronouns: readonly string[]
+  /** Past-tense verbs, matched anywhere in the bullet and uncased. */
+  readonly verbs: readonly string[]
+}
+
+/**
+ * Absent is a distinct state from empty, the split the comment vocabulary
+ * draws for the same reason: a scan with no terms finds nothing, and reporting
+ * that as zero findings claims the corpus is clean when nothing was looked for.
+ */
+export type Narration =
+  | ({ readonly kind: 'loaded'; readonly source: string } & NarrationTerms)
+  | { readonly kind: 'absent' }
+
+/** Pulls the backticked terms out of the bullets under one heading. */
+export function parseTerms(
+  markdown: string,
+  heading: string,
+): string[] | undefined {
+  const lines = markdown.split('\n')
+  const start = lines.findIndex((line) => line.trim() === heading)
+  if (start === -1) return undefined
+
+  const terms: string[] = []
+
+  for (const line of lines.slice(start + 1)) {
+    if (line.startsWith('## ')) break
+    for (const match of line.matchAll(/`([^`]+)`/g)) {
+      const term = match[1].trim()
+      if (term && !terms.includes(term)) terms.push(term)
+    }
+  }
+
+  return terms
+}
+
+/**
+ * Finds the rule publishing both sets under `root`.
+ *
+ * Both come from one file rather than from whichever rule carries each. A
+ * pronoun set and a verb set are halves of one signal, and pairing them across
+ * files would let a renumber recombine them into a signal nobody wrote.
+ */
+export async function loadNarration(root: string): Promise<Narration> {
+  for (const ruleRoot of RULE_ROOTS) {
+    const dir = resolve(root, ruleRoot)
+    if (!existsSync(dir)) continue
+
+    const paths: string[] = []
+    for await (const rel of new Bun.Glob('**/*.md').scan({
+      cwd: dir,
+      onlyFiles: true,
+    })) {
+      paths.push(rel)
+    }
+    paths.sort()
+
+    for (const rel of paths) {
+      const source = await readFile(resolve(dir, rel), 'utf8')
+      const pronouns = parseTerms(source, PRONOUN_HEADING)
+      const verbs = parseTerms(source, VERB_HEADING)
+
+      if (pronouns && verbs && pronouns.length > 0 && verbs.length > 0) {
+        return {
+          kind: 'loaded',
+          source: `${ruleRoot}/${rel}`,
+          pronouns,
+          verbs,
+        }
+      }
+    }
+  }
+
+  return { kind: 'absent' }
+}

package/src/markdown/scan.ts

@@ -23,6 +23,17 @@ const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
 const LINK_DESTINATION = /\]\([^)]*\)/g
 const AUTOLINK = /<[^>\s]+>/g
 
+/**
+ * A whole inline link, capturing the anchor text a reader is shown.
+ *
+ * `LINK_DESTINATION` covers the span both measures drop and this covers the
+ * brackets only the weight measure drops, which a reader is no more shown than
+ * the destination. The narrower pattern still runs after this one, since a link
+ * wrapped across two source lines puts its opening bracket on a line this one
+ * never matches.
+ */
+const LINK = /\[([^\]]*)\]\([^)]*\)/g
+
 export interface BodyLine {
   readonly number: number
   readonly text: string
@@ -128,16 +139,81 @@ export function maskDisplayed(text: string): string {
     .replace(AUTOLINK, blank)
 }
 
+/**
+ * Drops the spans a reader is never shown, returning the text they read.
+ *
+ * This is what a weight measure counts, and it is deliberately not
+ * `maskDisplayed`. That one holds each span's width so a ban finding can name a
+ * column, which leaves behind the very characters a weight measure exists to
+ * discount. The two also disagree on the span set: a backticked path is text a
+ * reader reads and stays counted here, while the ban scan blanks it so a
+ * standard quoting its own banned character does not report itself. One file
+ * therefore holds two answers to what a reader sees, each correct for its own
+ * measure, and collapsing them into one helper breaks whichever loses.
+ *
+ * A code span is walked around rather than through, since keeping it counted
+ * and then dropping spans from inside it takes back the decision. The
+ * placeholders this repository writes are the case: a reader is shown all of
+ * `.claude/context/<domain>.md` and the autolink pattern reaches the angle
+ * brackets in the middle of it.
+ */
+export function visibleText(text: string): string {
+  const drop = (segment: string): string =>
+    segment
+      .replace(LINK, '$1')
+      .replace(LINK_DESTINATION, '')
+      .replace(AUTOLINK, '')
+
+  let visible = ''
+  let read = 0
+
+  for (const span of text.matchAll(CODE_SPAN)) {
+    visible += drop(text.slice(read, span.index)) + span[0]
+    read = span.index + span[0].length
+  }
+
+  return visible + drop(text.slice(read))
+}
+
 function escape(term: string): string {
   return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+/**
+ * Bounds a banned word on a word character or a hyphen either side.
+ *
+ * `\b` sits after a hyphen, so a banned word ending a hyphenated compound
+ * reports from inside it: `allows` came back out of `auto-allows`. A compound
+ * is one word to a reader, and the ban is on the word rather than on a morpheme
+ * of it. Stripping hyphens before matching was the alternative and it joins the
+ * compound into a token neither half reaches.
+ *
+ * A spelling ban takes `wordBoundary` instead. This is not that rule with a
+ * wider fence, since the two bans target different things.
+ */
+function bannedWord(term: string): RegExp {
+  return new RegExp(`(?<![\\w-])${escape(term)}(?![\\w-])`, 'gi')
+}
+
+/**
+ * Bounds a banned spelling on a word character alone, hyphens included.
+ *
+ * A word ban targets the word, so a compound reading as one word is correct.
+ * A spelling ban targets the orthography inside it, and a compound is exactly
+ * where the orthography still sits: `behaviour-driven` carries the banned
+ * spelling as plainly as `behaviour` does, and rejecting a hyphen here would
+ * leave the usual spelling of that phrase unreported.
+ */
+function bannedSpelling(term: string): RegExp {
+  return new RegExp(`\\b${escape(term)}\\b`, 'gi')
+}
+
 /**
  * Finds every banned term outside a fence, a code span, and a link.
  *
- * A word ban matches on word boundaries and either casing, since the standard
- * states each in lowercase and bans the word rather than a spelling of it. This
- * is what separates the check from the pattern that produced most of the
+ * A word ban matches in either casing, since the standard states each in
+ * lowercase and bans the word rather than a spelling of it. A closed set of
+ * whole words separates the check from the pattern that produced most of the
  * intake's false positives: `exercises` and `promises` end in the banned
  * suffix and are not the banned words, and a closed set never reaches them.
  */
@@ -151,12 +227,12 @@ export function scanBans(
     ...bans.words.map((term) => ({
       kind: 'word' as const,
       term,
-      pattern: new RegExp(`\\b${escape(term)}\\b`, 'gi'),
+      pattern: bannedWord(term),
     })),
     ...bans.spellings.map((term) => ({
       kind: 'spelling' as const,
       term,
-      pattern: new RegExp(`\\b${escape(term)}\\b`, 'gi'),
+      pattern: bannedSpelling(term),
     })),
   ]
 

package/src/markdown/structure.ts

@@ -1,4 +1,4 @@
-import type { BodyLine } from '@/markdown/scan'
+import { type BodyLine, visibleText } from '@/markdown/scan'
 
 const HEADING = /^#{1,6}\s/
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
@@ -143,9 +143,13 @@ export function parseCheckpoints(markdown: string): Checkpoints {
  *
  * A blank line renders as the gap it is rather than as nothing, which keeps it
  * the distance the source measure already counted it as.
+ *
+ * The width is measured against what renders, since a rendered line shows a
+ * link's anchor text rather than its destination and a source measure
+ * over-counts exactly where this rule cares how far a reader travels.
  */
 export function renderedHeight(text: string, width = RENDER_WIDTH): number {
-  return Math.max(1, Math.ceil(text.length / width))
+  return Math.max(1, Math.ceil(visibleText(text).length / width))
 }
 
 /**
@@ -173,7 +177,7 @@ function isScannablePeerList(
     if (!match) return false
     indents.add(match[1].length)
     items++
-    characters += text.length
+    characters += visibleText(text).length
   }
 
   if (indents.size !== 1) return false
@@ -297,10 +301,13 @@ export function heavyBullets(
     const item = line.text.match(LIST_ITEM)
     const text = line.text.trim()
 
+    // Structure is read off the raw line and only the weight is masked. A line
+    // carrying nothing but an autolink has no visible text at all, and reading
+    // its masked form as blank would close the bullet it continues.
     if (item) {
       close()
       if (item[1].length === 0) {
-        open = { line: line.number, characters: text.length }
+        open = { line: line.number, characters: visibleText(text).length }
       }
       continue
     }
@@ -312,7 +319,11 @@ export function heavyBullets(
 
     // The joining space a wrapped line would have carried, so folding two
     // source lines measures what one unwrapped line would have.
-    if (open) open = { ...open, characters: open.characters + text.length + 1 }
+    if (open)
+      open = {
+        ...open,
+        characters: open.characters + visibleText(text).length + 1,
+      }
   }
 
   close()
@@ -353,16 +364,13 @@ export function heavyParagraphs(
     if (block.length > 0) {
       const text = block.map((line) => line.text.trim()).join(' ')
       const sentences = countSentences(text)
+      const characters = visibleText(text).length
 
       if (
         sentences > checkpoints.sentences ||
-        text.length > checkpoints.paragraph
+        characters > checkpoints.paragraph
       ) {
-        findings.push({
-          line: block[0].number,
-          sentences,
-          characters: text.length,
-        })
+        findings.push({ line: block[0].number, sentences, characters })
       }
     }
     block = []