@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/parse-tranche.ts

@@ -0,0 +1,183 @@
+import { readMarkdownTable } from './parse-registry'
+import type { Tranche, Lifecycle, Task } from './types'
+
+/**
+ * Parse `aeg-root/tranches/<name>.md` into a typed `Tranche`.
+ *
+ * Captures:
+ *   - the tranche's name (from `# Tranche: <name> — <timeframe>`; the
+ *     superseded `# Iteration:` spelling is still read, see `parseName`)
+ *   - the lifecycle marker (`Lifecycle: active|complete`, defaulting to
+ *     `'active'` when absent — pre-§11 files have no marker)
+ *   - the first goal paragraph
+ *   - the `## Tasks (topology)` table rows
+ *   - per-task rationale blocks (raw markdown, captured verbatim)
+ *   - an optional `## Backlog` section as bullets
+ *
+ * Real tranche files include narrative references to dropped task ids in
+ * prose (e.g. a "Task 3a — removed" note). The parser ignores those — only
+ * rows present in the topology table become tasks.
+ */
+export function parseTranche(md: string): Tranche {
+  return {
+    name: parseName(md),
+    lifecycle: parseLifecycle(md),
+    goal: parseGoal(md),
+    tasks: parseTasks(md),
+    backlog: parseBacklog(md)
+  }
+}
+
+function parseName(md: string): string {
+  // The H1 is `# Tranche: <slug> — <timeframe>`. The slug may contain
+  // hyphens (e.g. `some-tranche-name`, `another-v1`), so capture the first
+  // non-whitespace run — the space before the em-dash is the delimiter.
+  //
+  // `Iteration:` is accepted as the superseded spelling, permanently. This is
+  // a READER of files this repo does not necessarily own: content pulled out
+  // of git history predates the rename and cannot be rewritten, and an
+  // adopter's own topology files are theirs, not ours to migrate. Refusing
+  // the old marker would not fail loudly — `parseName` returns `''`, which
+  // reads downstream as a nameless tranche. The writer side is unaffected:
+  // every file this repo emits or archives carries `# Tranche:`.
+  const m = md.match(/^#\s+(?:Tranche|Iteration):\s+(\S+)/m)
+  return m?.[1] ? m[1].trim() : ''
+}
+
+function parseLifecycle(md: string): Lifecycle {
+  // `Lifecycle: active` or `Lifecycle: complete`. The label may be wrapped in
+  // bold (`**Lifecycle:** active`); the closing `**` sits after the colon.
+  const m = md.match(/^\s*(?:\*\*)?Lifecycle\s*:(?:\*\*)?\s*(active|complete)\b/im)
+  return m?.[1] ? (m[1].toLowerCase() as Lifecycle) : 'active'
+}
+
+function parseGoal(md: string): string {
+  // Match `Goal (…): <text>` to the end of the paragraph.
+  // The live files use various subtitles ("execution, not roadmap-why",
+  // "execution, not product-why"); strip everything up to the colon and
+  // capture the first paragraph that follows.
+  const lines = md.split(/\r?\n/)
+  const buf: string[] = []
+  let inGoal = false
+  for (const raw of lines) {
+    const line = stripBoldWrappers(raw)
+    if (!inGoal) {
+      const m = line.match(/^Goal\b[^:]*:\s*(.*)$/i)
+      if (m) {
+        inGoal = true
+        const rest = (m[1] ?? '').trim()
+        if (rest) buf.push(rest)
+      }
+    } else {
+      if (line.trim() === '') break
+      // Stop at the next markdown heading or HR.
+      if (/^#{1,6}\s/.test(line) || /^---+\s*$/.test(line)) break
+      buf.push(line.trim())
+    }
+  }
+  return buf.join(' ').trim()
+}
+
+function stripBoldWrappers(line: string): string {
+  // Remove bold markers around `Goal …:` or `Lifecycle:` style lines so the
+  // greedy regexes above work on either `**Goal:**` or plain `Goal:`.
+  return line.replace(/\*\*/g, '')
+}
+
+function parseTasks(md: string): Task[] {
+  const rows = readMarkdownTable(md, /^##\s+Tasks\b/i)
+  const rationales = extractRationales(md)
+  const tasks: Task[] = []
+  for (const row of rows) {
+    // Expected 6 columns: # | Task | Issue | Project(s) | Depends-on | Conflicts-with.
+    if (row.length < 6) continue
+    const id = (row[0] ?? '').trim()
+    if (!id) continue
+    tasks.push({
+      id,
+      title: (row[1] ?? '').trim(),
+      issue: parseIssueCell(row[2] ?? ''),
+      projects: parseCsvCell(row[3] ?? ''),
+      dependsOn: parseEdgeCell(row[4] ?? ''),
+      conflictsWith: parseEdgeCell(row[5] ?? ''),
+      rationaleMarkdown: rationales.get(id) ?? ''
+    })
+  }
+  return tasks
+}
+
+function parseIssueCell(cell: string): number | null {
+  const trimmed = stripBackticks(cell).trim()
+  if (!trimmed) return null
+  if (isEmDashOrDash(trimmed)) return null
+  const m = trimmed.match(/#?(\d+)/)
+  return m ? Number(m[1]) : null
+}
+
+function parseCsvCell(cell: string): string[] {
+  const cleaned = stripBackticks(cell).trim()
+  if (!cleaned || isEmDashOrDash(cleaned)) return []
+  return cleaned
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+function parseEdgeCell(cell: string): string[] {
+  return parseCsvCell(cell)
+}
+
+function isEmDashOrDash(s: string): boolean {
+  const t = s.trim()
+  return t === '—' || t === '-' || t === '–'
+}
+
+function stripBackticks(s: string): string {
+  return s.replace(/`/g, '')
+}
+
+/**
+ * Capture each `### Task <id> — …` block as raw markdown — from the heading
+ * through the line before the next `### ` / `## ` / `# ` / end-of-file.
+ * The id may be `1`, `7a`, `7b`, etc. Per-task rationale lives inline in the
+ * tranche file (see §4 template); the planner's rationale also lives in the
+ * Issue body, but the inline copy is what `parseTranche` exposes.
+ */
+function extractRationales(md: string): Map<string, string> {
+  const out = new Map<string, string>()
+  const lines = md.split(/\r?\n/)
+  let i = 0
+  while (i < lines.length) {
+    const m = (lines[i] ?? '').match(/^###\s+Task\s+(\S+)\s+—/)
+    if (!m?.[1]) {
+      i++
+      continue
+    }
+    const id = m[1]
+    const start = i
+    i++
+    while (i < lines.length && !/^#{1,3}\s/.test(lines[i] ?? '')) i++
+    out.set(id, lines.slice(start, i).join('\n').trimEnd())
+  }
+  return out
+}
+
+function parseBacklog(md: string): string[] {
+  const lines = md.split(/\r?\n/)
+  let i = 0
+  for (; i < lines.length; i++) {
+    if (/^##\s+Backlog\b/i.test(lines[i] ?? '')) {
+      i++
+      break
+    }
+  }
+  if (i >= lines.length) return []
+  const bullets: string[] = []
+  for (; i < lines.length; i++) {
+    const line = lines[i] ?? ''
+    if (/^#{1,3}\s/.test(line)) break
+    const m = line.match(/^\s*[-*+]\s+(.*)$/)
+    if (m?.[1]) bullets.push(m[1].trim())
+  }
+  return bullets
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/pr-tier.ts

@@ -0,0 +1,81 @@
+/**
+ * PR tier derivation and the docs-gate override check. Pure — takes the diff,
+ * PR body, and env-derived strings as explicit parameters. The original
+ * `scripts/verify-docs.ts` read `process.env.PR_BODY` / `OVERRIDE_DOCS` /
+ * `PR_LABELS` directly inside these functions; that hidden I/O is removed
+ * here — the caller (the CLI shim) reads env once and passes the values in.
+ */
+
+import { hasLabel, label } from '@attalabs/aeg-forge-state'
+import { anchoredRegion } from './anchored-region'
+import { isDocFile, isSpecFile } from './file-classify'
+
+/**
+ * Derive a tier from the changed-file list when no `Tier:` field is in the PR body.
+ *
+ * Rules (in priority order):
+ *   1. Spec or doc file in diff   → Tier 1
+ *   2. Otherwise (code/config…)   → Tier 0
+ *
+ * A frozen archive carries no tier signal: nothing reads it, so touching one
+ * says nothing about a change's impact.
+ */
+export function deriveTierFromDiff(changed: string[]): 0 | 1 {
+  if (changed.some((p) => isSpecFile(p) || isDocFile(p))) return 1
+  return 0
+}
+
+/**
+ * Read the `Tier:` field from the PR body.
+ *
+ * Tolerates the three markdown shapes the field appears in:
+ *   - plain:        `Tier: 3`
+ *   - bold colon:   `**Tier:** 3`   (the `**` wraps `Tier:` including the colon)
+ *   - bold label:   `**Tier**: 3`   (the `**` wraps only `Tier`)
+ *
+ * The field may appear inline in a metadata line (e.g.
+ * `Tranche: x · Task: 1 · **Tier:** 3 · Project: y`), so it is NOT anchored
+ * to line-start. Returns null when no Tier field is present at all — the caller
+ * decides what a missing tier means (PR mode treats it as an explicit error,
+ * NOT a silent default).
+ *
+ * When the body carries an `AEG:TIER` anchor pair (`anchored-region.ts`,
+ * task 30), the same regex runs exclusively inside that pair — a `Tier:`
+ * mention anywhere else (a pasted reference brief, a quoted example) is
+ * ignored. Bodies without the pair parse exactly as before.
+ */
+/**
+ * The exact `Tier:` field grammar, exported so a consumer that needs the
+ * MATCH itself (not just the parsed number) — `body-bare-digits`, which
+ * needs to know precisely which substring is the field's real value so it
+ * can exempt exactly that and nothing appended after it — reuses this one
+ * definition rather than a second regex that could silently drift from it.
+ * An optional bold-open, the word Tier, an optional bold-close, a colon, an
+ * optional bold-close (covers `**Tier:**`), optional space, then the digit.
+ */
+export const TIER_FIELD = /(\*\*)?\s*Tier\s*(\*\*)?\s*:\s*(\*\*)?\s*([013])\b/i
+
+export function readTierFromPrBody(prBody: string): 0 | 1 | 3 | null {
+  const searchIn = anchoredRegion(prBody, 'TIER') ?? prBody
+  const m = searchIn.match(TIER_FIELD)
+  if (!m) return null
+  const t = Number(m[4])
+  return t === 0 || t === 1 || t === 3 ? (t as 0 | 1 | 3) : null
+}
+
+/**
+ * The body token that activates the override — the label name in brackets, so
+ * the two spellings cannot drift. Built from the code-owned vocabulary rather
+ * than written as a literal (#614): `override:docs` was the one §14 system
+ * label the namespace migration missed, precisely because it lived here as a
+ * bare string that no label-family grep looked for.
+ */
+const OVERRIDE_BODY_TOKEN = `[${label('override-docs')}]`
+
+export function overrideActive(opts: { overrideDocsEnv?: string; prLabels?: string; prBody?: string }): boolean {
+  if (opts.overrideDocsEnv === '1') return true
+  const labels = (opts.prLabels || '').split(',').map((s) => s.trim())
+  if (hasLabel('override-docs', labels)) return true
+  if ((opts.prBody || '').includes(OVERRIDE_BODY_TOKEN)) return true
+  return false
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/premise-check.ts

@@ -0,0 +1,125 @@
+/**
+ * Premise-pinning grammar (aeg-governance-hardening task 11, #324). Pure —
+ * no `fs`; file content is injected via `fileReader` so the checker stays
+ * testable and CWD-independent.
+ *
+ * A brief/PR body's `Premise:` block pins concrete, checkable facts about the
+ * code surface at authoring time — e.g. "this function still exists", "this
+ * constant is still absent". `verify-dispatch --premise <body-file>`
+ * re-asserts every pin immediately before Step 0: a premise that no longer
+ * holds means the surface moved since the brief was written, and the
+ * Developer should stop and re-dig rather than execute against a stale
+ * mental model (the exact failure of aeg-governance-hardening's live-fire
+ * #3 — two briefs described a target architecture a later, uncited migration
+ * had already superseded).
+ *
+ * Deliberately minimal — exactly three assertion kinds. This is a pin
+ * format, not a DSL; resist adding more.
+ */
+
+import { createHash } from 'node:crypto'
+import { anchoredRegion } from './anchored-region'
+
+export type PremiseAssertion =
+  | { kind: 'contains'; path: string; value: string }
+  | { kind: 'absent'; path: string; value: string }
+  | { kind: 'sha256'; path: string; value: string }
+
+const ASSERTION_KINDS = new Set(['contains', 'absent', 'sha256'])
+
+/**
+ * True for the header line in either serialization the rest of the brief
+ * grammar uses (`brief-validation.ts`, `issue-validation.ts`): `**Premise:**`
+ * bold-inline or `### Premise` heading. Strips `*`/`#` markup first rather
+ * than trying to enumerate every marker placement — `**Premise:**` closes
+ * its bold markers *after* the colon, `**Premise**:` closes them *before*.
+ */
+function isPremiseHeader(line: string): boolean {
+  const stripped = line.replace(/[*#]/g, '').trim()
+  return /^premise\s*:?$/i.test(stripped)
+}
+
+/** Matches one bullet line: `- <path> <kind>: <value>`. */
+const PREMISE_LINE = /^[-*]\s*(\S+)\s+(contains|absent|sha256)\s*:\s*(.+)$/i
+
+/**
+ * Parse every `- <path> <kind>: <value>` bullet under the `Premise:` header.
+ * Malformed bullets (wrong kind, missing colon) are silently skipped — this
+ * mirrors `parsePremiseBlock`'s sibling parsers' presence-only philosophy;
+ * the caller decides whether zero assertions is itself a failure
+ * (`checkPremiseCoverage`). Stops the block at the first blank line or the
+ * first non-bullet line after the header.
+ *
+ * When the body carries an `AEG:PREMISE` anchor pair (`anchored-region.ts`,
+ * task 30), the block is parsed exclusively inside that pair — the pair must
+ * contain the `**Premise:**` header line and its bullets; a premise-shaped
+ * block anywhere else in the body is ignored. Bodies without the pair parse
+ * exactly as before.
+ */
+export function parsePremiseBlock(prBody: string): PremiseAssertion[] {
+  const searchIn = anchoredRegion(prBody, 'PREMISE') ?? prBody
+  const lines = searchIn.split(/\r?\n/)
+  const assertions: PremiseAssertion[] = []
+  let inBlock = false
+
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (!inBlock) {
+      if (isPremiseHeader(line)) inBlock = true
+      continue
+    }
+    if (line === '') break
+    const m = line.match(PREMISE_LINE)
+    if (!m) break
+    const [, path, kindRaw, value] = m
+    const kind = (kindRaw as string).toLowerCase()
+    if (!ASSERTION_KINDS.has(kind)) continue
+    assertions.push({ kind, path: path as string, value: (value as string).trim() } as PremiseAssertion)
+  }
+
+  return assertions
+}
+
+export type PremiseCheckResult = { pass: boolean; failures: string[] }
+
+/**
+ * Re-assert every parsed premise against the current file content, injected
+ * via `fileReader` (returns `null` when the path does not exist). One
+ * failure line per broken pin, naming the exact path/kind/value so the
+ * Developer can see precisely what moved.
+ */
+export function checkPremises(
+  assertions: PremiseAssertion[],
+  fileReader: (path: string) => string | null
+): PremiseCheckResult {
+  const failures: string[] = []
+
+  for (const a of assertions) {
+    const content = fileReader(a.path)
+    if (content === null) {
+      failures.push(
+        `premise-check: ${a.path} does not exist on disk (premise asserted \`${a.kind}: ${a.value}\`) — the surface moved since this brief was authored; re-dig before proceeding.`
+      )
+      continue
+    }
+
+    if (a.kind === 'contains' && !content.includes(a.value)) {
+      failures.push(
+        `premise-check: ${a.path} no longer contains "${a.value}" — the premise this brief pinned has moved; re-dig before proceeding.`
+      )
+    } else if (a.kind === 'absent' && content.includes(a.value)) {
+      failures.push(
+        `premise-check: ${a.path} now contains "${a.value}", but the brief pinned it absent — the premise has moved; re-dig before proceeding.`
+      )
+    } else if (a.kind === 'sha256') {
+      const actual = createHash('sha256').update(content).digest('hex')
+      if (actual !== a.value.toLowerCase()) {
+        failures.push(
+          `premise-check: ${a.path} sha256 mismatch (brief pinned ${a.value}, file is now ${actual}) — the file changed since this brief was authored; re-dig before proceeding.`
+        )
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures }
+}

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 six-field `AnchorField` grammar, which this
+// marker (a free-form cited-file path, not one of those six 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 six 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
+  )
+}