@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/registry-checks.ts

@@ -0,0 +1,255 @@
+/**
+ * registry-checks.ts — G1–G6, the deterministic coherence checks that make
+ * `aeg-root/enforcement.md`'s three ring tables (parsed by
+ * `registry-parse.ts`) load-bearing instead of decorative.
+ *
+ * Pure — no `fs`, no `git`/`gh` I/O, no `fetch`. All forge/filesystem facts
+ * are injected by the caller (`bin/verify-registry.ts` /
+ * `apps/cli/src/checks/bin/check-registry-gates.ts`, the I/O shims),
+ * mirroring `coherence-checks.ts`'s shape exactly (plain executables,
+ * deterministic pass/fail, no config conditionals).
+ *
+ * Rollout policy: G2 ships report-only — it can only ever report `'info'`,
+ * never `'fail'`, so it never affects CI's exit code (the accepted shape for
+ * G2's inverse sweep, unchanged by task 8). G1 was report-only through its
+ * own rollout window; task 8 flips it to blocking now that the orphan
+ * backlog it existed to surface is clean (0 findings against the real
+ * `enforcement.md` at the time of the flip). G3–G6 are blocking (`'fail'` on
+ * any violation).
+ */
+
+import { GATE_AUDIENCE, isShipped } from './gate-audience'
+import type { GateRow } from './registry-parse'
+
+export type RegistryCheckStatus = 'pass' | 'fail' | 'info'
+
+export type RegistryFinding = {
+  row?: string
+  path?: string
+  reason: string
+}
+
+export type RegistryCheckResult = {
+  check: 'G1' | 'G2' | 'G3' | 'G4' | 'G5' | 'G6'
+  status: RegistryCheckStatus
+  findings: RegistryFinding[]
+}
+
+/**
+ * G1 — every row's non-empty `implementation` resolves on disk. Blocking as
+ * of task 8 (re-graded from report-only: eleven permanent `info` findings on
+ * every run had become indistinguishable from silence, which is how the gap
+ * this tranche closes stayed invisible; the report-only window had already
+ * cleared the backlog it existed to surface).
+ */
+export function checkG1(rows: GateRow[], existsFn: (path: string) => boolean): RegistryCheckResult {
+  const findings: RegistryFinding[] = []
+  for (const row of rows) {
+    if (row.implementation === '') continue
+    if (!existsFn(row.implementation)) {
+      findings.push({
+        row: row.action,
+        path: row.implementation,
+        reason: `${row.ring} row "${row.action}" names implementation "${row.implementation}", which does not exist on disk`
+      })
+    }
+  }
+  return { check: 'G1', status: findings.length > 0 ? 'fail' : 'pass', findings }
+}
+
+/** The literal placeholder marker a registry-scaffold stub row's
+ * non-mechanical cells carry (`registry-scaffold.ts`'s `PLACEHOLDER`,
+ * duplicated here rather than imported to keep this module's zero-import
+ * shape — the two are asserted equal by `registry-checks.test.ts`). A stub
+ * that filled `implementation` alone would silence G2 outright (the whole
+ * defect Issue #104 exists to close): this marker is what keeps a row G2
+ * still flags loud until a human replaces it with the real "why". */
+const SCAFFOLD_PLACEHOLDER = '[undocumented — fill in why]'
+
+/**
+ * G2 — every candidate hook/CLI file is named by SOME row's `implementation`,
+ * AND no row still carries the scaffold's placeholder marker un-replaced.
+ * `candidateFiles` is already-globbed by the caller (`.husky/*`,
+ * `.claude/hooks/*.sh`, `packages/aeg-core/bin/*.ts`, excluding `.husky/_`).
+ * Report-only this tranche — same as G1, never `'fail'`.
+ *
+ * The second half (placeholder scan) is what keeps a registry-scaffold stub
+ * row visible: `implementation` presence alone would make a stub read as
+ * "documented" to the ORPHAN half above, which is precisely the trap the
+ * scaffold must not fall into. Scanned over `summary`/`description`/`spec`
+ * — every cell a stub can carry the marker in — never `implementation`,
+ * `action`, `category`, or `audience`, which the scaffold fills mechanically
+ * and are never expected to carry it.
+ */
+export function checkG2(rows: GateRow[], candidateFiles: string[]): RegistryCheckResult {
+  const implementations = new Set(rows.map((r) => r.implementation).filter((p) => p !== ''))
+  const findings: RegistryFinding[] = []
+  for (const path of candidateFiles) {
+    if (!implementations.has(path)) {
+      findings.push({
+        path,
+        reason: `"${path}" is not named as the implementation of any row in enforcement.md's ring tables`
+      })
+    }
+  }
+  for (const row of rows) {
+    const carriesPlaceholder = [row.summary, row.description, row.spec].some((cell) => cell === SCAFFOLD_PLACEHOLDER)
+    if (carriesPlaceholder) {
+      findings.push({
+        row: row.action,
+        path: row.implementation,
+        reason: `${row.ring} row "${row.action}" still carries the scaffold placeholder marker — the why is owed`
+      })
+    }
+  }
+  return { check: 'G2', status: findings.length > 0 ? 'info' : 'pass', findings }
+}
+
+/**
+ * G3 — every file that makes a GitHub-crossing call is named by SOME Ring-0
+ * row's `implementation` — "no seventh way into GitHub". `crossingFiles` is
+ * already-detected by the caller via a source-grep. Blocking.
+ */
+export function checkG3(ring0Rows: GateRow[], crossingFiles: string[]): RegistryCheckResult {
+  const ring0Implementations = new Set(ring0Rows.map((r) => r.implementation))
+  const findings: RegistryFinding[] = []
+  for (const path of crossingFiles) {
+    if (!ring0Implementations.has(path)) {
+      findings.push({
+        path,
+        reason: `"${path}" makes a GitHub-crossing call but is not named by any Ring-0 row's implementation — a seventh, unlisted way into GitHub`
+      })
+    }
+  }
+  return { check: 'G3', status: findings.length > 0 ? 'fail' : 'pass', findings }
+}
+
+/**
+ * G4 — every `#NNN` cited in enforcement.md's body resolves in the forge.
+ * `resolveFn` wraps `gh issue view`/`gh pr view` (caller injects). Blocking.
+ * Broad reading (brief): every `#`-prefixed 3-or-more-digit number
+ * occurring anywhere in the body is checked, not just ones near keywords
+ * like "incident" — an incomplete keyword net would create a
+ * false-negative gap. The current repo's real citations are all 3-4
+ * digits; the lower bound of 3 exists only to exclude unrelated short
+ * numerals (ring/tier numbers) that are never written with a `#` prefix
+ * anyway — there is deliberately no upper bound, so a longer fabricated
+ * number is still caught.
+ */
+export function checkG4(content: string, resolveFn: (n: number) => boolean): RegistryCheckResult {
+  const cited = new Set<number>()
+  for (const hit of content.matchAll(/#(\d{3,})\b/g)) {
+    cited.add(Number(hit[1]))
+  }
+  const findings: RegistryFinding[] = []
+  for (const n of cited) {
+    if (!resolveFn(n)) {
+      findings.push({
+        reason: `#${n} is cited in enforcement.md but does not resolve to a real Issue or PR in the forge`
+      })
+    }
+  }
+  return { check: 'G4', status: findings.length > 0 ? 'fail' : 'pass', findings }
+}
+
+/**
+ * G5 — every contract's producer/consumer is a real role_id; every role's
+ * `performs`/`refuses_when` is present and non-empty. Blocking.
+ *
+ * "The action exists" is satisfied by presence/well-formedness of the
+ * role's own frontmatter — there is no second, independent registry of
+ * valid actions to cross-reference `performs` entries against.
+ */
+export function checkG5(
+  roles: Array<{ file: string; role_id: string; performs: string[]; refuses_when: string }>,
+  contracts: Array<{ file: string; producer: string; consumer: string }>
+): RegistryCheckResult {
+  const roleIds = new Set(roles.map((r) => r.role_id))
+  const findings: RegistryFinding[] = []
+
+  for (const contract of contracts) {
+    if (!roleIds.has(contract.producer)) {
+      findings.push({
+        path: contract.file,
+        reason: `contract "${contract.file}" names producer "${contract.producer}", which is not a real role_id`
+      })
+    }
+    if (!roleIds.has(contract.consumer)) {
+      findings.push({
+        path: contract.file,
+        reason: `contract "${contract.file}" names consumer "${contract.consumer}", which is not a real role_id`
+      })
+    }
+  }
+
+  for (const role of roles) {
+    if (role.performs.length === 0) {
+      findings.push({ path: role.file, reason: `role "${role.role_id}" has an empty performs array` })
+    }
+    if (role.refuses_when.trim() === '') {
+      findings.push({ path: role.file, reason: `role "${role.role_id}" has an empty refuses_when` })
+    }
+  }
+
+  return { check: 'G5', status: findings.length > 0 ? 'fail' : 'pass', findings }
+}
+
+const SHIPPED_BIN_PATH_PREFIX = 'apps/cli/src/checks/bin/check-'
+const AEG_CORE_BIN_PATH_PREFIX = 'packages/aeg-core/bin/'
+
+function basenameNoExt(path: string): string {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  return base.replace(/\.ts$/, '')
+}
+
+/**
+ * Every `coreCheckRegistry()` name a `product`-audience row's implementation
+ * could resolve to. Two shapes: a path directly under the shipped bin
+ * directory names its own check 1:1 (`apps/cli/src/checks/bin/check-doc-
+ * coverage-push.ts` -> `doc-coverage-push`); a path under
+ * `packages/aeg-core/bin/` resolves through `GATE_AUDIENCE`, the same map
+ * `shipped-bin-audience.test.ts` (`apps/cli`) already asserts agrees with
+ * the registry — reused here rather than re-derived, so doctrine and code
+ * cannot silently disagree about what a bin ships as. Neither shape matches
+ * (e.g. a `.github/workflows/*.yml` path, `checks/runner.ts`, a forge-write
+ * command) resolves to no candidate at all — correct, since those are not
+ * `coreCheckRegistry()` checks by construction.
+ */
+function claimedCheckNames(implementation: string): string[] {
+  if (implementation.startsWith(SHIPPED_BIN_PATH_PREFIX) && implementation.endsWith('.ts')) {
+    return [implementation.slice(SHIPPED_BIN_PATH_PREFIX.length, -'.ts'.length)]
+  }
+  if (implementation.startsWith(AEG_CORE_BIN_PATH_PREFIX)) {
+    const audience = GATE_AUDIENCE[basenameNoExt(implementation)]
+    if (audience && isShipped(audience)) {
+      return Array.isArray(audience.shippedAs) ? audience.shippedAs : [audience.shippedAs]
+    }
+  }
+  return []
+}
+
+/**
+ * G6 — every row doctrine marks `product` must actually resolve to a
+ * `coreCheckRegistry()` entry ("claimed checks must ship" — the parity gate
+ * this task exists for). `registeredCheckNames` is caller-injected
+ * (`coreCheckRegistry().map(s => s.name)`, from `apps/cli`, which
+ * `aeg-core` cannot import without closing a dependency cycle — same
+ * reasoning `gate-audience.ts` documents for `GATE_AUDIENCE` itself).
+ * Blocking. A row left at the default `repo-own` audience makes no shipped
+ * claim and is never checked here.
+ */
+export function checkG6(rows: GateRow[], registeredCheckNames: Set<string>): RegistryCheckResult {
+  const findings: RegistryFinding[] = []
+  for (const row of rows) {
+    if (row.audience !== 'product') continue
+    const candidates = claimedCheckNames(row.implementation)
+    if (!candidates.some((name) => registeredCheckNames.has(name))) {
+      findings.push({
+        row: row.action,
+        path: row.implementation,
+        reason: `${row.ring} row "${row.action}" is marked \`product\` but its implementation "${row.implementation}" does not resolve to a coreCheckRegistry() entry`
+      })
+    }
+  }
+  return { check: 'G6', status: findings.length > 0 ? 'fail' : 'pass', findings }
+}

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

@@ -0,0 +1,164 @@
+/**
+ * registry-parse.ts — pure, no-I/O parser for `aeg-root/enforcement.md`'s
+ * three ring markdown tables (Ring 0/1/2). enforcement.md's tables ARE the
+ * gate registry (no live file duplicates forge state); this
+ * parses them rather than maintaining a second copy.
+ *
+ * The generic markdown-table extraction lives in `./markdown-table` — the one
+ * aeg-core-owned parser every doctrine consumer shares. This module
+ * imports `findTable`/`findHeadingLine` from there rather than re-deriving
+ * them; it adds only the enforcement-specific normalization on top (the
+ * ring-heading list, `stripBackticks`, and the last-two-columns rule).
+ *
+ * Each ring's table has a different header wording (Ring 0: Action/Gate/...;
+ * Ring 1: CI check/Re-verifies; Ring 2: Mechanism/Runs/Catches). The FIRST
+ * column is always the row's identifying label; `implementation` and
+ * `description` are resolved BY HEADER NAME, since those two are spelled
+ * identically in all three tables. Positional reads are used only where no
+ * shared header name exists.
+ *
+ * The one exception is `Description`, which IS looked up by header name: it is
+ * the only column spelled identically in all three tables, and the only one a
+ * table can legitimately lack. Position cannot express that difference (a
+ * 7-column table means two different shapes depending on the ring), so the
+ * name is the only honest key. See the lookup in `parseEnforcementRegistry`.
+ */
+
+import { findHeadingLine, findTable } from './markdown-table'
+
+export type GateRing = 'ring0' | 'ring1' | 'ring2'
+
+export type GateRow = {
+  ring: GateRing
+  action: string
+  summary: string
+  category: 'ci' | 'hook' | 'event'
+  /** One plain sentence: what this gate does, for a reader. Present in all
+   * three ring tables and resolved by header name (see the lookup below).
+   *
+   * The counterpart to `spec`, and not interchangeable with it — `spec` is
+   * written to ENFORCE: 17 of the 31 real rows cite an Issue number, a
+   * task number or a file path, and the longest runs 2708 chars. That is
+   * correct for a gate and unreadable on a page. This column is the same fact
+   * addressed to a person, and is what a row's `summary` question gets
+   * answered by. The same bar `roles/*.md`/`contracts/*.md` hold via
+   * `description:` frontmatter and `ACTIONS` holds via its `description`
+   * field, so a reader gets one register whatever they click.
+   *
+   * Optional on the type only so a malformed table degrades instead of
+   * throwing — every real row carries one, asserted against the live file. */
+  description?: string
+  /** The substantive middle column — "What must be true..." (ring0),
+   * "Re-verifies" (ring1), "Catches" (ring2) — always the column
+   * immediately before `implementation`. Each ring names it differently,
+   * but structurally it's always the same slot: the normative spec, written
+   * for enforcement. Distinct from `summary`'s rhetorical question and from
+   * `description`'s plain-language answer to it. Undefined when a table has
+   * no such column. */
+  spec?: string
+  implementation: string
+  /**
+   * `product` — this row's implementation is a check registered in
+   * `coreCheckRegistry()` (`apps/cli/src/checks/registry.ts`), so it ships to
+   * every adopter through `vinaya check`. `repo-own` — everything else: a
+   * mechanism specific to how this repository enforces itself on top of the
+   * product (a hand-written CI job, the check runner/resolver, a forge-write
+   * command, or a check this repo runs on its own doctrine but has not
+   * registered). Read from an `Audience` column, by header name like
+   * `description`. A table carrying no such column, or a cell holding
+   * anything other than the literal `product`, resolves to `repo-own` — the
+   * safe default, since it makes no shipped claim for G6 to verify.
+   */
+  audience: 'product' | 'repo-own'
+  line: number
+}
+
+const RING_HEADINGS: Array<{ ring: GateRing; pattern: RegExp }> = [
+  { ring: 'ring0', pattern: /^##\s+Ring 0\b/ },
+  { ring: 'ring1', pattern: /^##\s+Ring 1\b/ },
+  { ring: 'ring2', pattern: /^##\s+Ring 2\b/ }
+]
+
+function stripBackticks(cell: string): string {
+  const trimmed = cell.trim()
+  if (trimmed.length >= 2 && trimmed.startsWith('`') && trimmed.endsWith('`')) {
+    return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+/** Strips markdown `**bold**` markers from a gate/check row's own name.
+ * `action` is the one cell this parser has never sanitized — most rows are
+ * plain text, but a real row can legitimately bold its name for doctrine-
+ * prose emphasis, and that literal `**...**` was leaking straight through
+ * to `DiagramNode.label` (visible asterisks in the how-it-works UI; every
+ * label already renders bold via CSS where it matters, so the markdown
+ * marker carries zero information downstream). Root-cause fix, not a
+ * per-row doctrine patch — the next accidentally-bolded name is covered
+ * too, not just the ones caught so far. */
+function stripBold(cell: string): string {
+  return cell.trim().replace(/\*\*/g, '')
+}
+
+/**
+ * Parses the three ring tables out of `enforcement.md`'s raw content into a
+ * flat, normalized `GateRow[]`. Each row's `action` is its table's first
+ * column; `implementation` is resolved by header name, falling back to the
+ * last column.
+ */
+export function parseEnforcementRegistry(content: string): GateRow[] {
+  const lines = content.split('\n')
+  const result: GateRow[] = []
+
+  for (const { ring, pattern } of RING_HEADINGS) {
+    const headingLine = findHeadingLine(lines, pattern)
+    if (headingLine === null) continue
+    const table = findTable(lines, headingLine + 1)
+    if (!table) continue
+    // `description`/`Audience` are found BY HEADER NAME, never by position —
+    // the two columns here that can be. Every other column is positional out
+    // of necessity: the three ring tables name their first column
+    // differently ("Action"/"CI check"/"Mechanism") and their middle columns
+    // differently again ("Gate" + "What must be true" / "Re-verifies" /
+    // "Runs" + "Catches"), so only the ends are reliable. "Description" and
+    // "Audience" are spelled the same in all three, which makes a name
+    // lookup possible — and a name lookup is what keeps a table WITHOUT the
+    // column from having some other column silently read as its value. By
+    // index that is undetectable: a 7-column table means "has Description"
+    // in one ring and "has Gate" in another, and the parser cannot tell
+    // which. -1 here simply means the table doesn't have that column.
+    const descriptionIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'description')
+    const implementationIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'implementation')
+    const audienceIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'audience')
+    for (const row of table.rows) {
+      const cells = row.cells
+      if (cells.length < 3) continue
+      const action = stripBold(cells[0] ?? '')
+      const summary = stripBackticks(cells[1] ?? '')
+      const category = stripBackticks(cells[2] ?? '') as GateRow['category']
+      const implementation = stripBackticks(
+        (implementationIndex === -1 ? cells[cells.length - 1] : cells[implementationIndex]) ?? ''
+      )
+      const description =
+        descriptionIndex === -1 ? undefined : stripBackticks(cells[descriptionIndex] ?? '') || undefined
+      // `spec` is the ring-specific column immediately before `implementation`
+      // — normally the last cell, but `Audience`, when present, now sits
+      // between them. `specIndex` follows whichever of the two comes first:
+      // one before `Audience` if the table carries one, one before the last
+      // cell (`implementation`'s positional fallback) if it doesn't — so a
+      // table predating this column (a fixture, an un-upgraded adopter copy)
+      // still resolves `spec` exactly as it did before `Audience` existed.
+      const specIndex = (audienceIndex === -1 ? cells.length - 1 : audienceIndex) - 1
+      const spec = specIndex >= 3 ? stripBackticks(cells[specIndex] ?? '') || undefined : undefined
+      const audience: GateRow['audience'] =
+        audienceIndex === -1
+          ? 'repo-own'
+          : stripBackticks(cells[audienceIndex] ?? '') === 'product'
+            ? 'product'
+            : 'repo-own'
+      result.push({ ring, action, summary, category, description, spec, implementation, audience, line: row.line })
+    }
+  }
+
+  return result
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/registry-scaffold.ts

@@ -0,0 +1,216 @@
+/**
+ * registry-scaffold.ts — pure insertion logic that turns a G2 "orphan
+ * hook/CLI" finding into a stub row, instead of leaving it a drift warning a
+ * human has to notice and fix by hand.
+ *
+ * Purity contract identical to `registry-checks.ts`'s: no fs/git/gh here.
+ * The caller (`bin/verify-registry.ts`) supplies the parsed rows, the
+ * already-globbed candidate files, and the raw `enforcement.md` content to
+ * rewrite; this module only ever reads `GATE_AUDIENCE` (a same-package,
+ * aeg-core-local data table — see its own doc comment for why aeg-core
+ * cannot instead import `apps/cli`'s `CORE_CHECK_RING` directly).
+ *
+ * Three derivation classes, per Issue #104's Principal decision (extended
+ * by Issue #307 for the second registry-backed location):
+ *   - a `packages/aeg-core/bin/*.ts` candidate that IS a registered check
+ *     (its basename resolves in `GATE_AUDIENCE` to a `ShippedGate`) gets a
+ *     stub in the ring `GATE_AUDIENCE` names for it;
+ *   - an `apps/cli/src/checks/bin/*.ts` candidate that IS a registered check
+ *     (its `check-`-stripped basename resolves in `CLI_CHECK_RING`) gets a
+ *     stub in the ring `CLI_CHECK_RING` names for it — most core check bins
+ *     live here, not under `packages/aeg-core/bin/` (Issue #307: 22 of 27 at
+ *     the time it was filed);
+ *   - a `.husky/*` or `.claude/hooks/*.sh` candidate is a managed hook by
+ *     construction — ring 0, no registry lookup needed.
+ * Anything else (a bin with no registry entry — `internal`, `NON_GATE_BINS`,
+ * or simply undeclared) gets NO stub: ring is genuinely underivable there,
+ * and guessing is exactly what this task's Stop-and-escalate condition
+ * forbids. It stays a plain G2 finding, same as today.
+ *
+ * Never touches an existing row: stubs are computed only for candidates
+ * whose path is absent from every parsed row's `implementation` — the
+ * identical predicate `checkG2` itself uses — so a candidate already
+ * documented (including every row `#67` wrote by hand) is left alone, and
+ * running the scaffold twice inserts nothing the second time (the first
+ * run's own stubs are now present, so the same predicate excludes them).
+ *
+ * Only mechanical facts are filled: the check name / candidate path
+ * (`Action`/`CI check`/`Mechanism`), `Category` (fixed per ring — matches
+ * every existing row: ring 0 is `hook`, ring 1 is `ci`, ring 2 is `event`),
+ * `Audience` (`product` for a registered check, `repo-own` for a bare hook
+ * script), and `implementation` (the path itself). A ring-0 stub also gets a
+ * mechanical `Gate` cell naming the check/its invocation — never the
+ * substantive "what must be true"/"re-verifies"/"catches" reasoning, which
+ * (along with `Summary`/`Description`) is the placeholder marker, verbatim,
+ * on every stub this module ever produces.
+ */
+
+import { CLI_CHECK_RING, GATE_AUDIENCE, isShipped } from './gate-audience'
+import { findHeadingLine, findTable } from './markdown-table'
+import type { GateRing, GateRow } from './registry-parse'
+
+/** The literal marker a stub's every non-mechanical cell carries. Never
+ * synthesized reasoning — `checkG2`'s placeholder scan (registry-checks.ts)
+ * looks for this exact string. */
+export const PLACEHOLDER = '[undocumented — fill in why]'
+
+const HUSKY_PREFIX = '.husky/'
+const CLAUDE_HOOKS_PREFIX = '.claude/hooks/'
+const AEG_CORE_BIN_PREFIX = 'packages/aeg-core/bin/'
+const CLI_BIN_PREFIX = 'apps/cli/src/checks/bin/'
+
+const RING_CATEGORY: Record<GateRing, string> = { ring0: 'hook', ring1: 'ci', ring2: 'event' }
+
+const RING_HEADING_PATTERN: Record<GateRing, RegExp> = {
+  ring0: /^##\s+Ring 0\b/,
+  ring1: /^##\s+Ring 1\b/,
+  ring2: /^##\s+Ring 2\b/
+}
+
+export type ScaffoldStub = {
+  ring: GateRing
+  path: string
+  checkName?: string
+  /** Ordered cell values, matching that ring table's own column count/order. */
+  cells: string[]
+}
+
+export type ScaffoldSkip = { path: string; reason: string }
+
+export type ScaffoldPlan = {
+  stubs: ScaffoldStub[]
+  skipped: ScaffoldSkip[]
+}
+
+function ringFromNumber(n: 0 | 1 | 2): GateRing {
+  if (n === 0) return 'ring0'
+  if (n === 1) return 'ring1'
+  return 'ring2'
+}
+
+/** Classifies one G2-orphan candidate path. Returns null when no ring is
+ * derivable — the candidate must remain a plain G2 finding, never guessed. */
+function classify(path: string): { ring: GateRing; checkName?: string } | null {
+  if (path.startsWith(HUSKY_PREFIX) || path.startsWith(CLAUDE_HOOKS_PREFIX)) {
+    return { ring: 'ring0' }
+  }
+  if (path.startsWith(AEG_CORE_BIN_PREFIX) && path.endsWith('.ts')) {
+    const base = path.slice(AEG_CORE_BIN_PREFIX.length, -'.ts'.length)
+    const audience = GATE_AUDIENCE[base]
+    if (audience && isShipped(audience)) {
+      const checkName = Array.isArray(audience.shippedAs) ? audience.shippedAs[0] : audience.shippedAs
+      return { ring: ringFromNumber(audience.ring), checkName }
+    }
+    return null
+  }
+  if (path.startsWith(CLI_BIN_PREFIX) && path.endsWith('.ts')) {
+    const base = path.slice(CLI_BIN_PREFIX.length, -'.ts'.length)
+    if (!base.startsWith('check-')) return null
+    const checkName = base.slice('check-'.length)
+    const ring = CLI_CHECK_RING[checkName]
+    if (ring === undefined) return null
+    return { ring: ringFromNumber(ring), checkName }
+  }
+  return null
+}
+
+function gateCell(path: string, checkName: string | undefined): string {
+  if (checkName) return `\`${checkName}\` check (\`vinaya check ${checkName}\`)`
+  return `managed hook script (\`${path}\`)`
+}
+
+function buildCells(ring: GateRing, path: string, checkName: string | undefined): string[] {
+  const action = checkName ?? path
+  const category = RING_CATEGORY[ring]
+  const audience = checkName ? 'product' : 'repo-own'
+  const implementation = `\`${path}\``
+  if (ring === 'ring0') {
+    return [
+      action,
+      PLACEHOLDER,
+      category,
+      PLACEHOLDER,
+      gateCell(path, checkName),
+      PLACEHOLDER,
+      audience,
+      implementation
+    ]
+  }
+  if (ring === 'ring1') {
+    return [action, PLACEHOLDER, category, PLACEHOLDER, PLACEHOLDER, audience, implementation]
+  }
+  return [action, PLACEHOLDER, category, PLACEHOLDER, PLACEHOLDER, PLACEHOLDER, audience, implementation]
+}
+
+/** Computes which G2-orphan candidates get a stub row, and where. Pure: no
+ * I/O, deterministic over its inputs. Idempotent by construction — a
+ * candidate already present in `rows` (including one from a prior scaffold
+ * run) is excluded before classification ever runs. */
+export function computeScaffoldPlan(rows: GateRow[], candidateFiles: string[]): ScaffoldPlan {
+  const implementations = new Set(rows.map((r) => r.implementation).filter((p) => p !== ''))
+  const stubs: ScaffoldStub[] = []
+  const skipped: ScaffoldSkip[] = []
+  for (const path of candidateFiles) {
+    if (implementations.has(path)) continue
+    const classified = classify(path)
+    if (!classified) {
+      skipped.push({ path, reason: 'no derivable ring — remains a plain G2 finding' })
+      continue
+    }
+    stubs.push({
+      ring: classified.ring,
+      path,
+      checkName: classified.checkName,
+      cells: buildCells(classified.ring, path, classified.checkName)
+    })
+  }
+  return { stubs, skipped }
+}
+
+function formatRow(cells: string[]): string {
+  return `| ${cells.join(' | ')} |`
+}
+
+/**
+ * Rewrites `content` to append the plan's stub rows to their ring tables.
+ * Only ever APPENDS new lines after a ring table's last existing row —
+ * never edits, reorders, or removes an existing line, so a hand-written row
+ * (including every row task `#67` wrote) is untouched byte-for-byte.
+ *
+ * Rings are processed from the bottom of the file upward (ring 2 first,
+ * then ring 1, then ring 0) so an earlier insertion's line numbers, computed
+ * once up front from the ORIGINAL `rows`, stay valid throughout — a later
+ * ring's insertion never shifts an earlier ring's already-resolved splice
+ * point.
+ *
+ * Throws if a ring with stubs to insert has no existing table/rows to
+ * anchor on — the caller (`bin/verify-registry.ts`) must not write anything
+ * to disk when this throws; computing this in memory before any write is
+ * what keeps the round-trip guard restore-free (nothing is ever written
+ * badly in the first place).
+ */
+export function applyScaffoldPlan(content: string, plan: ScaffoldPlan): string {
+  if (plan.stubs.length === 0) return content
+  const lines = content.split('\n')
+
+  const byRing: Record<GateRing, ScaffoldStub[]> = { ring0: [], ring1: [], ring2: [] }
+  for (const stub of plan.stubs) byRing[stub.ring].push(stub)
+
+  for (const ring of ['ring2', 'ring1', 'ring0'] as const) {
+    const stubs = byRing[ring]
+    if (stubs.length === 0) continue
+    const headingLine = findHeadingLine(lines, RING_HEADING_PATTERN[ring])
+    if (headingLine === null) {
+      throw new Error(`registry-scaffold: no "${ring}" heading found in enforcement.md`)
+    }
+    const table = findTable(lines, headingLine + 1)
+    if (!table || table.rows.length === 0) {
+      throw new Error(`registry-scaffold: ${ring} table has no existing rows to insert after`)
+    }
+    const lastRowLine = table.rows[table.rows.length - 1]?.line ?? headingLine
+    const newLines = stubs.map((s) => formatRow(s.cells))
+    lines.splice(lastRowLine, 0, ...newLines)
+  }
+
+  return lines.join('\n')
+}