@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/quoted-command.ts

@@ -0,0 +1,275 @@
+/**
+ * Quoted-command staleness (Issue #128). Pure — no `fs`, no `git`/`gh`.
+ *
+ * **The defect this closes.** A doc quotes a command, config line, or file
+ * content verbatim, in backticks, as a statement of present fact — "what
+ * runs today: `X`". When a diff changes the thing being quoted, the
+ * quotation goes stale and nothing notices: the doc changed nothing, the
+ * code is correct, every existing gate passes. Measured, live: a CI
+ * invocation was pinned to a version in one PR; `aeg-root/enforcement.md`
+ * quoted the pre-pin form verbatim as "what runs today"; all 17 registered
+ * checks passed, `doctor` reported healthy, security passed. A code-review
+ * agent found it after roughly half an hour of independent re-derivation.
+ * The fix was one line — the detection took a review round.
+ *
+ * **Marker-based, not inferred — the Principal's explicit decision
+ * (2026-08-30).** The Issue leaves the claim-vs-instruction distinction
+ * open and calls it "the real work"; it is now settled: a doc opts a span
+ * in with a citation marker naming the file it quotes. An adopter-facing
+ * `npx @attalabs/vinaya init` in a README is instruction, correctly
+ * unpinned — inferring over command-looking spans would flag it, which is
+ * the exact false-positive that gets a gate disabled. This module
+ * implements NO inference and NO heuristic fallback for an unmarked span;
+ * only annotated quotes are ever evaluated. Coverage grows only as docs
+ * adopt the marker — that cost is understood and accepted.
+ *
+ * **The marker grammar.** Two-line (or inline) HTML-comment pair, the same
+ * invisible-on-render, code-blind idiom `anchored-region.ts` uses for the
+ * six PR/Issue-body gate-read fields — reused for its masking discipline
+ * (`maskCode`, imported below) rather than re-implemented, though this is a
+ * DIFFERENT field kind from `anchored-region.ts`'s closed `AnchorField`
+ * union: `anchoredRegionBounds` parses one of six fixed field names inside a
+ * forge body; this marker instead carries a free-form cited-file path
+ * inline in its own START tag, inside an arbitrary doc file, so it cannot
+ * reuse that function directly without widening a closed, PR-body-specific
+ * type for a doc-authoring concern outside this task's surface. The shape:
+ *
+ *     <!-- AEG:QUOTES-FILE:START:<repo-relative-path> -->
+ *     `<quoted text>`
+ *     <!-- AEG:QUOTES-FILE:END -->
+ *
+ * Both markers may sit on their own lines or inline within a prose
+ * sentence (the real annotation this task ships wraps an inline backtick
+ * span mid-paragraph). Recognition rules mirror `anchored-region.ts`
+ * exactly: markers inside a fenced/indented code block or inline code span
+ * do not count (an authoring example showing the marker syntax itself,
+ * fenced, is never mistaken for a real one); a `START` with no following
+ * `END` is not an anchor at all; multiple pairs in one file are scanned
+ * left to right, each `START` paired with the next `END` after it.
+ *
+ * **The quoted text.** The content between the markers, trimmed, with one
+ * layer of wrapping stripped: a single-backtick inline span, a fenced block
+ * (backtick or tilde), or neither (bare text) — whichever the author used.
+ * That literal string is the predicate's subject: it either occurs verbatim
+ * in the cited file's content, or it does not. No normalization beyond
+ * that — a doc that means to tolerate whitespace/formatting drift is not
+ * this check's problem to solve.
+ *
+ * **The predicate.** Decidable, per the Issue: a quoted command either
+ * appears in the file it claims to quote, or it does not. `findCitedQuotes`
+ * discovers every marked span in the governed-doc corpus (the same
+ * `classifyProseFile` scoping `reader-resolvable-prose.ts` sweeps —
+ * `ships`/`reader-facing`, never `internal` — reused rather than a second
+ * notion of "governed doc"); `evaluateCitedQuotes` then checks each against
+ * the cited file's actual content, which the caller supplies (the bin reads
+ * it — this module never touches disk). A finding names both sides: what
+ * the doc claims (the quoted text) and which file it cited that no longer
+ * (or never did) contain it verbatim.
+ */
+
+import { maskCode } from '@attalabs/aeg-forge-state/strip-code'
+import { classifyProseFile, type ProseFileClass } from './reader-resolvable-prose'
+
+// `maskCode` (index-preserving) is imported directly from the `./strip-code`
+// subpath — the same narrow front door `anchored-region.ts` uses, per that
+// package's own barrel comment ("reachable through the `./strip-code`
+// subpath for the two callers that need them"). Not through
+// `anchored-region.ts`'s re-export: that file's own `anchoredRegionBounds`
+// is scoped to its closed seven-field `AnchorField` grammar, which this
+// marker (a free-form cited-file path, not one of those seven names) cannot
+// use without widening a PR-body-specific type for a doc-authoring concern
+// outside this task's surface. Reusing `maskCode` itself — rather than
+// writing a second masker — is the actual "do not write a second anchor
+// parser" discipline this module honors.
+
+export type QuotedCommandSourceFile = { path: string; content: string }
+
+/** One marked span: the doc that carries it, where, what it claims, and which file it cites. */
+export type CitedQuote = {
+  file: string
+  line: number
+  quotedText: string
+  citedFile: string
+}
+
+export type QuotedCommandFinding = {
+  file: string
+  line: number
+  citedFile: string
+  quotedText: string
+  message: string
+}
+
+/** `aeg-root/**` by default — same default `reader-resolvable-prose.ts` uses, so a caller that doesn't override either stays consistent. */
+const QUOTED_COMMAND_SHIPS_PREFIX = 'aeg-root/'
+
+/** The two classes this check sweeps for markers — `internal` never is, matching `reader-resolvable-prose.ts`'s own (identically-valued, differently-named to avoid `symbol-collisions.test.ts`) `SWEPT_CLASSES`. */
+const QUOTED_COMMAND_SWEPT_CLASSES: ReadonlySet<ProseFileClass> = new Set(['ships', 'reader-facing'])
+
+const START_PATTERN = /<!--\s*AEG:QUOTES-FILE:START:(\S+?)\s*-->/g
+const END_PATTERN = /<!--\s*AEG:QUOTES-FILE:END\s*-->/
+
+/**
+ * A marker's `citedFile` must be a plain repo-root-relative path — never
+ * absolute, never carrying a `..` traversal segment. Security finding
+ * (this check's own PR, round 2): an unvalidated `citedFile` turns this
+ * check into a file-content oracle any doc author can drive — a crafted
+ * marker naming `../../../../etc/hosts` (or any path outside the repo the
+ * check process can reach) gets its content read and compared against
+ * attacker-chosen `quotedText`, and the three distinguishable outcomes
+ * (silent pass on an exact match, a "no longer contains" finding on a
+ * miss, a "could not be read" finding when the target is absent) form a
+ * working binary-search oracle over that file's real content — reproduced
+ * live, three ways, including a working read of `/etc/hosts`. A path
+ * failing this check is not a valid citation at all: the marker is treated
+ * exactly like an unterminated START/END pair (silently not an anchor),
+ * never reaching the file-read stage, so there is no signal difference
+ * between "malformed marker" and "no marker" for an attacker to probe.
+ */
+export function isValidCitedFilePath(path: string): boolean {
+  if (path.length === 0) return false
+  if (path.startsWith('/') || path.startsWith('\\')) return false
+  if (/^[A-Za-z]:[\\/]/.test(path)) return false
+  return !path.split(/[\\/]+/).includes('..')
+}
+
+function quotedCommandLineAt(content: string, index: number): number {
+  let line = 1
+  for (let i = 0; i < index; i++) {
+    if (content.charCodeAt(i) === 10) line++
+  }
+  return line
+}
+
+/**
+ * Strips exactly one layer of wrapping from the marker's inner text: a
+ * single-backtick inline span, a fenced block (backtick or tilde, with or
+ * without an info string), or neither. Returns the trimmed bare text in
+ * every case — this is deliberately not CommonMark-general, only the two
+ * shapes an author actually writes a quoted command in.
+ */
+function extractQuotedText(raw: string): string {
+  const trimmed = raw.trim()
+  const fenced = /^(?:`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n?(?:`{3,}|~{3,})$/.exec(trimmed)
+  if (fenced) return (fenced[1] ?? '').trim()
+  const inline = /^`([^`]+)`$/.exec(trimmed)
+  if (inline) return (inline[1] ?? '').trim()
+  return trimmed
+}
+
+/**
+ * Scans one file's content for `AEG:QUOTES-FILE` marker pairs. Searches
+ * position-only over `stripCode`'s masked-but-length-altering output is
+ * unsafe (indices would no longer map back) — so this uses `maskCode`
+ * (index-preserving, same primitive `anchored-region.ts` uses) to find
+ * marker positions code-blind, then slices the real inner text from the
+ * original `content` at those same indices, exactly as `anchoredRegionBounds`
+ * does for its own seven fields.
+ */
+function findQuotesInFile(path: string, content: string): CitedQuote[] {
+  const masked = maskCode(content)
+  const quotes: CitedQuote[] = []
+
+  START_PATTERN.lastIndex = 0
+  let start: RegExpExecArray | null = START_PATTERN.exec(masked)
+  while (start !== null) {
+    const citedFile = start[1] as string
+    const innerStart = start.index + start[0].length
+    const end = END_PATTERN.exec(masked.slice(innerStart))
+    if (end === null) {
+      // A START with no following END is not an anchor at all (mirrors
+      // anchored-region.ts's identical rule) — resume scanning right after
+      // this unterminated START rather than treating the rest of the file
+      // as consumed by it.
+      START_PATTERN.lastIndex = innerStart
+      start = START_PATTERN.exec(masked)
+      continue
+    }
+    const innerEnd = innerStart + end.index
+    if (isValidCitedFilePath(citedFile)) {
+      const quotedText = extractQuotedText(content.slice(innerStart, innerEnd))
+      if (quotedText.length > 0) {
+        quotes.push({ file: path, line: quotedCommandLineAt(content, innerStart), quotedText, citedFile })
+      }
+    }
+    START_PATTERN.lastIndex = innerEnd + end[0].length
+    start = START_PATTERN.exec(masked)
+  }
+  return quotes
+}
+
+/**
+ * Every marked span across the governed-doc corpus — `files` scoped to the
+ * same `ships`/`reader-facing` classes `reader-resolvable-prose.ts` sweeps
+ * (never `internal`), via the identical `classifyProseFile` call, not a
+ * second notion of "governed doc". Zero I/O: `files` is read by the caller.
+ */
+export function findCitedQuotes(
+  files: readonly QuotedCommandSourceFile[],
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  shipsPrefix: string = QUOTED_COMMAND_SHIPS_PREFIX
+): CitedQuote[] {
+  const quotes: CitedQuote[] = []
+  for (const file of files) {
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
+    if (!cls || !QUOTED_COMMAND_SWEPT_CLASSES.has(cls)) continue
+    quotes.push(...findQuotesInFile(file.path, file.content))
+  }
+  return quotes
+}
+
+/**
+ * The predicate itself: does each cited quote still appear verbatim in the
+ * file it claims to quote? `citedFileContents` is supplied by the caller —
+ * this function does no I/O and does not care whether a cited path lies
+ * inside or outside the governed-doc corpus (a workflow YAML a doc quotes
+ * is neither `ships` nor `reader-facing`, and must still be checkable). A
+ * cited path absent from `citedFileContents` is itself a finding (the file
+ * could not be read/found), not a silent pass — collapsing "unreadable"
+ * into "verified" would be the same fail-open class other checks in this
+ * package document as a real, reproduced incident.
+ */
+export function evaluateCitedQuotes(
+  citedQuotes: readonly CitedQuote[],
+  citedFileContents: ReadonlyMap<string, string>
+): QuotedCommandFinding[] {
+  const findings: QuotedCommandFinding[] = []
+  for (const quote of citedQuotes) {
+    const content = citedFileContents.get(quote.citedFile)
+    if (content === undefined) {
+      findings.push({
+        file: quote.file,
+        line: quote.line,
+        citedFile: quote.citedFile,
+        quotedText: quote.quotedText,
+        message: `${quote.file}:${quote.line} quotes "${quote.quotedText}" as citing \`${quote.citedFile}\`, but that file could not be read`
+      })
+      continue
+    }
+    if (!content.includes(quote.quotedText)) {
+      findings.push({
+        file: quote.file,
+        line: quote.line,
+        citedFile: quote.citedFile,
+        quotedText: quote.quotedText,
+        message: `${quote.file}:${quote.line} quotes "${quote.quotedText}" as citing \`${quote.citedFile}\`, but \`${quote.citedFile}\` no longer contains that text verbatim`
+      })
+    }
+  }
+  return findings
+}
+
+/** Runs both phases in one call: discover markers, then evaluate them against the supplied cited-file contents. */
+export function checkQuotedCommandStaleness(
+  files: readonly QuotedCommandSourceFile[],
+  citedFileContents: ReadonlyMap<string, string>,
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  shipsPrefix: string = QUOTED_COMMAND_SHIPS_PREFIX
+): QuotedCommandFinding[] {
+  return evaluateCitedQuotes(
+    findCitedQuotes(files, readerFacingPrefix, readerFacingSuffix, shipsPrefix),
+    citedFileContents
+  )
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/reader-resolvable-prose.ts

@@ -0,0 +1,320 @@
+/**
+ * Reader-resolvable prose — classes 1 and 2 of the three-class analysis in
+ * Issue #694: the two mechanizable classes of "words a reader cannot
+ * resolve." Class 3 (register/slop — padding adjectives, first person,
+ * narrating the work episode) is NOT here; it stays with the review role,
+ * per the measurement below.
+ *
+ * **The measurement that disqualifies a phrase blacklist.** A phrase
+ * blacklist tested against the real corpus (all of `aeg-root` plus 1,157
+ * TypeScript files) scored 14 hits, 14 false positives, 0 true positives —
+ * "a review was *requested*"; "could *this change* leak a secret"; "*I have*
+ * X, Y, Z" inside a quoted example. The fix is not tuning the word list; it
+ * is asking a different question:
+ *
+ *   - Class 1 (references): not "does this phrase appear" but "does this
+ *     doctrine cite a forge number or tranche slug the reader has no forge to
+ *     resolve." Reuses the same two pattern shapes proven in
+ *     `retired-vocabulary.test.ts` (`FORGE_NUMBER_PATTERN`,
+ *     `TRANCHE_SLUG_VN_PATTERN`, and the legacy-slug list derived — not
+ *     guessed — from `aeg-root/tranches/completed/*.md` filenames), scoped to
+ *     the reader-facing surfaces instead of banned repo-wide (the same digit
+ *     shape is this product's own live `Closes #N`/PR-number grammar
+ *     elsewhere, so a repo-wide ban would flag the mechanism, not the
+ *     citation habit).
+ *   - Class 2 (vocabulary): not "is this word forbidden" but "does this
+ *     reader-facing file use a coined term while neither defining it inline
+ *     nor linking a definition." The term list is derived from
+ *     `aeg-root/glossary.md`'s own entry headings — never hard-coded — so it
+ *     cannot drift the first time an entry is added.
+ *
+ * Zero I/O: every input (file paths + contents, the glossary's term list, the
+ * legacy-slug list) is read by the adapter and passed in. POSIX-ERE-safe
+ * patterns only — no `\d`/`\w`/`\s`/lookaheads, and no `\b` relied on after a
+ * non-word character (the exact regression class `retired-vocabulary.test.ts`
+ * already paid for) — even though these patterns run through native
+ * `RegExp`, not `grep -E`, keeping them portable to either.
+ */
+
+export type ProseFileClass = 'ships' | 'reader-facing' | 'internal'
+
+export type ProseSourceFile = { path: string; content: string }
+
+export type ProseFinding = {
+  file: string
+  line: number
+  message: string
+}
+
+/**
+ * `aeg-root/**` by default — what this repo's own package carries and
+ * `/docs` publishes. Every caller below takes `shipsPrefix` as its LAST,
+ * defaulted parameter so an adopter whose installed doctrine tree lives
+ * somewhere else (task 7, Issue #56 — de-hardcoding `doctrineRoot`) can
+ * override it without breaking any existing positional call.
+ */
+const SHIPS_PREFIX = 'aeg-root/'
+
+/** `<shipsPrefix>tranches/completed/` — history, never rewritten. Same exemption `retired-vocabulary.test.ts` already carries for the identical reason: an archived tranche legitimately cites the forge numbers and slugs it closed. */
+function shipsArchivePrefix(shipsPrefix: string): string {
+  return `${shipsPrefix}tranches/completed/`
+}
+
+/** A per-product specs file (`apps/<product>/specs/**`) — this reader has this forge; references are legitimate here. */
+function isSpecFile(path: string): boolean {
+  return path.startsWith('apps/') && path.includes('/specs/') && path.endsWith('.md')
+}
+
+/** Any `CLAUDE.md`, at any depth — same reasoning as specs: this reader has this forge. */
+function isClaudeMdFile(path: string): boolean {
+  return path === 'CLAUDE.md' || path.endsWith('/CLAUDE.md')
+}
+
+/**
+ * The file-class map, encoded as data (not a rule buried in control flow).
+ * Returns `null` for anything outside all three classes — out of this
+ * check's scope entirely, not merely exempt.
+ *
+ * `readerFacingPrefix`/`readerFacingSuffix` scope the "reader-facing" class
+ * to a consumer's own reader-facing surface — this package stays generic and
+ * has no attalabs-specific path baked in. The caller-supplied shape mirrors
+ * the vinaya adopter's product site: a page's own body is where
+ * reader-visible prose lives (JSX text, step copy); sibling component
+ * directories include non-textual/decorative surfaces (e.g. canvas
+ * illustrations using fictional PR numbers as flavor text) that are not
+ * prose in the sense this check means, hence a suffix-scoped match rather
+ * than a bare prefix.
+ */
+export function classifyProseFile(
+  path: string,
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  shipsPrefix: string = SHIPS_PREFIX
+): ProseFileClass | null {
+  if (path.startsWith(shipsPrefix)) {
+    return path.startsWith(shipsArchivePrefix(shipsPrefix)) ? 'internal' : 'ships'
+  }
+  if (path.startsWith(readerFacingPrefix) && path.endsWith(readerFacingSuffix)) {
+    return 'reader-facing'
+  }
+  if (isSpecFile(path) || isClaudeMdFile(path)) return 'internal'
+  return null
+}
+
+/** The two classes this check actually sweeps — `internal` never is. */
+const SWEPT_CLASSES: ReadonlySet<ProseFileClass> = new Set(['ships', 'reader-facing'])
+
+/**
+ * Strips the parts of a file that are never reader prose, per file kind — a
+ * fenced/inline code example in a markdown doc, or a source comment in a
+ * `.tsx` page (a page's own developer-facing comments, e.g. "same reasoning
+ * as `/roadmap`", are not what a site visitor reads). Line count is
+ * preserved (replacements keep their newlines) so reported line numbers stay
+ * accurate against the original file.
+ *
+ * The `//` line-comment cut requires the marker not be immediately preceded
+ * by `:` — without that, `https://vinaya.dev` on a reader-facing line reads
+ * as a comment starting at its own `//`, silently blanking every word of
+ * real prose that follows it on the line. No boundary check is needed on
+ * the far side: unlike `//`, the character before it is never itself part
+ * of the marker, so a plain capturing group (not a lookbehind) is enough.
+ */
+export function stripNonProse(path: string, content: string): string {
+  if (path.endsWith('.md')) {
+    return content
+      .replace(/```.*?```/gs, (m) => m.replace(/[^\n]/g, ''))
+      .replace(/`[^`\n]*`/g, (m) => m.replace(/[^\n]/g, ''))
+  }
+  if (path.endsWith('.tsx') || path.endsWith('.ts')) {
+    return content
+      .replace(/\/\*.*?\*\//gs, (m) => m.replace(/[^\n]/g, ''))
+      .replace(/(^|[^:])\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, ''))
+  }
+  return content
+}
+
+function lineAt(content: string, index: number): number {
+  let line = 1
+  for (let i = 0; i < index; i++) {
+    if (content.charCodeAt(i) === 10) line++
+  }
+  return line
+}
+
+/** `#294`-shaped — a PR/Issue number cited bare, resolvable only inside this repo's own tracker. */
+export const FORGE_NUMBER_PATTERN = /#[0-9]{2,4}/g
+
+/** `aeg-forge-state-v1`-shaped — an internal tranche slug ending `-vN`. */
+export const TRANCHE_SLUG_VN_PATTERN = /[a-z][a-z-]+-v[0-9]/g
+
+/**
+ * Builds the legacy-slug pattern from the real archived-tranche filenames
+ * the adapter reads (mirrors `retired-vocabulary.test.ts`'s `legacySlugs()` —
+ * derived from `aeg-root/tranches/completed/*.md`, never a shape guess).
+ * Returns `null` when there is nothing left for it to catch (every archived
+ * slug now ends `-vN`), matching that file's "no pattern with zero positive
+ * samples" rule.
+ *
+ * Boundary-checked like `containsWholeWord` below (character class, not
+ * `\b`) so a real slug cannot match as a bare substring inside a longer,
+ * unrelated token. `retired-vocabulary.test.ts`'s own copy of this pattern
+ * has no such boundary; this one adds it rather than copying the gap.
+ * Group 1 is the leading boundary char (or start-of-string), group 2 is the
+ * slug itself, group 3 the trailing boundary char (or end-of-string) — the
+ * caller reports group 2, not the whole match, so the boundary chars never
+ * leak into a finding's message.
+ */
+export function legacySlugPattern(legacySlugs: readonly string[]): RegExp | null {
+  if (legacySlugs.length === 0) return null
+  const alternation = legacySlugs.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  return new RegExp(`(^|[^a-zA-Z0-9\\n-])(${alternation})([^a-zA-Z0-9\\n-]|$)`, 'g')
+}
+
+/**
+ * Class 1 — unresolvable references. Runs the reference patterns over every
+ * swept file (`ships`/`reader-facing`), skipping code-fenced/commented-out
+ * non-prose first.
+ */
+export function checkUnresolvableReferences(
+  files: readonly ProseSourceFile[],
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  legacySlugs: readonly string[] = [],
+  shipsPrefix: string = SHIPS_PREFIX
+): ProseFinding[] {
+  const findings: ProseFinding[] = []
+  const legacyPattern = legacySlugPattern(legacySlugs)
+  // `group` names the capture holding the actual cited text — the plain
+  // patterns have none (report the whole match), the boundary-checked
+  // legacy-slug pattern reports its group 2 so the boundary chars around it
+  // never leak into the finding's message.
+  const patterns: { pattern: RegExp; what: string; group?: number }[] = [
+    { pattern: FORGE_NUMBER_PATTERN, what: 'a forge number' },
+    { pattern: TRANCHE_SLUG_VN_PATTERN, what: 'an internal tranche slug' },
+    ...(legacyPattern ? [{ pattern: legacyPattern, what: 'an internal tranche slug', group: 2 }] : [])
+  ]
+
+  for (const file of files) {
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
+    if (!cls || !SWEPT_CLASSES.has(cls)) continue
+    const scrubbed = stripNonProse(file.path, file.content)
+    for (const { pattern, what, group } of patterns) {
+      pattern.lastIndex = 0
+      let match: RegExpExecArray | null = pattern.exec(scrubbed)
+      while (match !== null) {
+        const cited = group !== undefined ? (match[group] ?? match[0]) : match[0]
+        findings.push({
+          file: file.path,
+          line: lineAt(scrubbed, match.index),
+          message: `references ${what} ("${cited}") a reader outside this repo's tracker cannot resolve`
+        })
+        match = pattern.exec(scrubbed)
+      }
+    }
+  }
+  return findings
+}
+
+/** Escapes a glossary term for use inside a hand-built, boundary-checked pattern. */
+function escapeTerm(term: string): string {
+  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Whole-word (or whole-phrase), case-insensitive occurrence of `term` in
+ * `text` — boundaries checked by character class rather than `\b`, per the
+ * "do not rely on `\b` after a non-word character" lesson. Matches the exact
+ * glossary heading only (no inflections): "briefly" must never match
+ * "brief" the way a prefix match would — that exact shape (`let's` matching
+ * `bullet's`) is what the disqualifying measurement caught.
+ */
+function containsWholeWord(text: string, term: string): boolean {
+  const escaped = escapeTerm(term)
+  const re = new RegExp(`(^|[^a-zA-Z])${escaped}([^a-zA-Z]|$)`, 'i')
+  return re.test(text)
+}
+
+function findWholeWordLine(content: string, term: string): number | null {
+  const lines = content.split('\n')
+  let lineNo = 0
+  for (const line of lines) {
+    lineNo++
+    if (containsWholeWord(line, term)) return lineNo
+  }
+  return null
+}
+
+/**
+ * A file "defines" a term inline when it carries the same
+ * `Term — definition` shape the glossary itself uses (an em-dash right after
+ * the term), or links the glossary page/file directly.
+ */
+function definesOrLinksGlossary(content: string, term: string): boolean {
+  const escaped = escapeTerm(term)
+  const definesInline = new RegExp(`(^|[^a-zA-Z])${escaped}([^a-zA-Z]|$)[^\\n]{0,3}—`, 'i').test(content)
+  if (definesInline) return true
+  return /docs\/glossary|glossary\.md/i.test(content)
+}
+
+/**
+ * Class 2 — undefined coined vocabulary. Not "is this word forbidden" — it
+ * is "does this reader-facing file use a coined term while neither defining
+ * it inline nor linking a definition." `glossaryTerms` is read by the
+ * adapter from `aeg-root/glossary.md`'s own entry headings — never
+ * hard-coded here, so the check cannot silently rot the first time an entry
+ * is added.
+ */
+export function checkUndefinedVocabulary(
+  files: readonly ProseSourceFile[],
+  glossaryTerms: readonly string[],
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  shipsPrefix: string = SHIPS_PREFIX
+): ProseFinding[] {
+  const findings: ProseFinding[] = []
+
+  for (const file of files) {
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
+    if (!cls || !SWEPT_CLASSES.has(cls)) continue
+    const scrubbed = stripNonProse(file.path, file.content)
+
+    for (const term of glossaryTerms) {
+      const line = findWholeWordLine(scrubbed, term)
+      if (line === null) continue
+      if (definesOrLinksGlossary(scrubbed, term)) continue
+      findings.push({
+        file: file.path,
+        line,
+        message: `uses coined term "${term}" without defining it inline or linking the glossary`
+      })
+    }
+  }
+  return findings
+}
+
+/** Runs both mechanizable classes over the given files in one pass. */
+export function checkReaderResolvableProse(
+  files: readonly ProseSourceFile[],
+  glossaryTerms: readonly string[],
+  readerFacingPrefix: string,
+  readerFacingSuffix: string,
+  legacySlugs: readonly string[] = [],
+  shipsPrefix: string = SHIPS_PREFIX
+): ProseFinding[] {
+  return [
+    ...checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs, shipsPrefix),
+    ...checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
+  ]
+}
+
+/** Parses `aeg-root/glossary.md`'s `**Term** — definition` entry headings into a bare term list. */
+export function parseGlossaryTerms(glossaryContent: string): string[] {
+  const terms: string[] = []
+  const re = /^\*\*(.+?)\*\* —/gm
+  let match: RegExpExecArray | null = re.exec(glossaryContent)
+  while (match !== null) {
+    if (match[1] !== undefined) terms.push(match[1])
+    match = re.exec(glossaryContent)
+  }
+  return terms
+}