@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/dead-branch-push-audit.ts

@@ -0,0 +1,55 @@
+/**
+ * Dead-branch-push AUDIT (aeg-governance-hardening task 24, #364, Part 4 —
+ * item 2). Distinct from the ring-0 `dead-branch-push-guard.ts` (task 18):
+ * that predicate answers "should THIS push be allowed right now?" at push
+ * time; this one answers "did commits land on a branch AFTER its PR already
+ * resolved?" retrospectively, across every remote `task/*` branch — the
+ * ring-2 backstop for the class the ring-0 hook is fail-open/hook-dependent
+ * against (a writer without the hook installed, or a hook bypass). Pure —
+ * no `fs`, no `gh`/`git` shell-outs. The CLI shim (`bin/dead-branch-audit.ts`,
+ * joining task 23's `daily-drift` job) gathers each branch's most recent
+ * PR (any state) plus its resolution/latest-commit timestamps and passes
+ * them in here.
+ *
+ * Exists to catch the "six topology rows landed on a merged plan PR's
+ * branch" incident class (2026-07-03) server-side, within a day, instead of
+ * never — never-red discipline: `daily-drift` (the CI job that calls this)
+ * must never fail red.
+ */
+
+export type DeadBranchFact = {
+  branch: string
+  prNumber: number
+  prState: 'MERGED' | 'CLOSED'
+  /** ISO timestamp the branch's PR was merged (MERGED) or closed (CLOSED). */
+  resolvedAt: string
+  /** ISO commit date of the branch's current remote tip. */
+  latestCommitAt: string
+}
+
+export type DeadBranchPush = {
+  branch: string
+  prNumber: number
+  prState: 'MERGED' | 'CLOSED'
+  resolvedAt: string
+  latestCommitAt: string
+}
+
+/**
+ * Flags a branch whose current tip commit is strictly newer than its own
+ * PR's resolution time — i.e. commits kept landing on a branch after the
+ * forge already considered its work done. A branch whose tip predates (or
+ * exactly matches) its PR's resolution is normal: the branch simply hasn't
+ * been deleted yet, which is not itself a violation.
+ */
+export function findDeadBranchPushes(facts: DeadBranchFact[]): DeadBranchPush[] {
+  return facts
+    .filter((f) => new Date(f.latestCommitAt).getTime() > new Date(f.resolvedAt).getTime())
+    .map(({ branch, prNumber, prState, resolvedAt, latestCommitAt }) => ({
+      branch,
+      prNumber,
+      prState,
+      resolvedAt,
+      latestCommitAt
+    }))
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/dead-branch-push-guard.ts

@@ -0,0 +1,77 @@
+/**
+ * Dead-branch push guard (aeg-governance-hardening task 18, #335). Pure — no
+ * `fs`, no `gh`/`git` shell-outs. The CLI shim (`bin/check-push-target.ts`)
+ * makes the one batched forge call (`gh pr list --head <branch> --state all
+ * --json number,state --limit 1`), maps its result to a `PrStateFact`, and
+ * passes it in here.
+ *
+ * Exists to answer, deterministically, "is it safe to push more commits to
+ * this `task/<tranche>/<n>` branch?" — closing the live-fire incident
+ * class where stale local work landed on a branch whose PR had already
+ * merged, silently reopening/confusing forge state with no push-time signal.
+ *
+ * `UNKNOWN` (forge unreachable — network flake, auth issue, rate limit) maps
+ * to `allow`, the same as `NONE` (no PR exists yet — a brand-new branch
+ * legitimately has none). This is a deliberate fail-open choice: a guard
+ * that can block *all* pushes on a transient forge-reachability issue is
+ * worse than the bug it fixes. See `aeg-root/enforcement.md`.
+ */
+
+export type PrStateFact = 'MERGED' | 'CLOSED' | 'OPEN' | 'NONE' | 'UNKNOWN'
+
+export type DeadBranchPushInput = {
+  /** The `task/<tranche>/<n>` branch being pushed. */
+  branch: string
+  /** State of the branch's most recent PR (any state), or the fact that none/forge-unreachable applies. */
+  prState: PrStateFact
+  /** The PR number that `prState` refers to, or `null` when no PR exists / could not be determined. */
+  prNumber: number | null
+}
+
+export type DeadBranchPushVerdict = 'allow' | 'refuse'
+
+export type DeadBranchPushResult = { verdict: DeadBranchPushVerdict; reason: string }
+
+/**
+ * `allow`  — `OPEN`/`NONE`/`UNKNOWN`: an in-flight PR, no PR yet, or the
+ *            forge couldn't be reached — all legitimate reasons to push.
+ * `refuse` — `MERGED`/`CLOSED`: the branch's most recent PR is already
+ *            resolved. Pushing here would silently resurrect resolved forge
+ *            state instead of starting a fresh branch.
+ */
+export function checkDeadBranchPush(input: DeadBranchPushInput): DeadBranchPushResult {
+  const { branch, prState, prNumber } = input
+
+  if (prState === 'MERGED') {
+    return {
+      verdict: 'refuse',
+      reason: `Branch \`${branch}\` already has a MERGED PR (#${prNumber}) — this branch's work is done. Push a new task branch instead of pushing onto an already-resolved one.`
+    }
+  }
+
+  if (prState === 'CLOSED') {
+    return {
+      verdict: 'refuse',
+      reason: `Branch \`${branch}\` has a CLOSED PR (#${prNumber}) that was never merged — pushing here would resurrect abandoned/rejected work. Open a new task branch instead.`
+    }
+  }
+
+  if (prState === 'OPEN') {
+    return {
+      verdict: 'allow',
+      reason: `Branch \`${branch}\` has an OPEN PR (#${prNumber}) — pushing more commits to it is normal.`
+    }
+  }
+
+  if (prState === 'NONE') {
+    return {
+      verdict: 'allow',
+      reason: `Branch \`${branch}\` has no PR yet — a brand-new task branch legitimately has none.`
+    }
+  }
+
+  return {
+    verdict: 'allow',
+    reason: `Could not determine \`${branch}\`'s PR state (forge unreachable) — failing open rather than blocking the push on a transient issue.`
+  }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/derive-section7.ts

@@ -0,0 +1,66 @@
+/**
+ * Derive the floor of a task's §7 doc-update list by matching its intended
+ * surface globs against `.vinaya/doc-owners` bindings (state-machine.md
+ * Section 15). Pure — parses doc-owners content via `parseDocOwners` (no
+ * second parser) and does segment-wise glob overlap between each intended
+ * surface and each binding's code glob. A Planner/Brief-Author aid only —
+ * not wired into any CI gate.
+ */
+
+import { parseDocOwners } from './doc-owners'
+
+export type Section7Match = { surface: string; glob: string; pointer: string; lineNum: number }
+
+export function deriveSection7(
+  intendedSurfaces: string[],
+  docOwnersContent: string
+): { pointers: string[]; matches: Section7Match[]; errors: string[] } {
+  const { bindings, errors } = parseDocOwners(docOwnersContent)
+  const matches: Section7Match[] = []
+  for (const surface of intendedSurfaces) {
+    for (const binding of bindings) {
+      if (globsOverlap(binding.glob, surface)) {
+        matches.push({ surface, glob: binding.glob, pointer: binding.pointer, lineNum: binding.lineNum })
+      }
+    }
+  }
+
+  const pointers: string[] = []
+  for (const m of matches) {
+    if (!pointers.includes(m.pointer)) pointers.push(m.pointer)
+  }
+
+  return { pointers, matches, errors }
+}
+
+/**
+ * True if two doc-owners-grammar globs can match at least one common path,
+ * compared segment-by-segment (split on `/`). `**` absorbs zero or more
+ * remaining segments on either side — checked at each step, even once one
+ * side has run out of segments, so a trailing `**` still absorbs. `*`
+ * matches exactly one segment regardless of the other side's literal/`*`.
+ * Two literal segments must be byte-equal. If one side runs out of segments
+ * before the other and the next pending segment on either side isn't `**`,
+ * there is no overlap.
+ */
+export function globsOverlap(a: string, b: string): boolean {
+  const segsA = a.split('/')
+  const segsB = b.split('/')
+  let i = 0
+  let j = 0
+  while (i < segsA.length || j < segsB.length) {
+    const sa = i < segsA.length ? segsA[i] : undefined
+    const sb = j < segsB.length ? segsB[j] : undefined
+    if (sa === '**' || sb === '**') return true
+    if (sa === undefined || sb === undefined) return false
+    if (sa === '*' || sb === '*') {
+      i++
+      j++
+      continue
+    }
+    if (sa !== sb) return false
+    i++
+    j++
+  }
+  return true
+}

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

@@ -0,0 +1,94 @@
+import { deriveStatusFromModel } from './state-machine-model'
+import type { DerivedTranche, DerivedStatus, DerivedTask, ForgeFacts, Tranche, Task, UnknownEdge } from './types'
+
+/**
+ * Compute each task's derived status, the resolved depends-on / conflicts-with
+ * graph, and dispatch-eligibility per `tranche-model.md` §3 (status table)
+ * and §8 (dispatch gates).
+ *
+ * The function is pure: `tranche` + `forgeFacts` in, `DerivedTranche` out.
+ * Edges referencing task ids not present in this tranche's table are
+ * reported via `unknownEdges` rather than throwing — see §4 traps in the brief
+ * (real files reference dropped/prose-only ids in narrative).
+ */
+export function deriveTranche(tranche: Tranche, forgeFacts: Map<string, ForgeFacts>): DerivedTranche {
+  const byId = new Map<string, Task>()
+  for (const task of tranche.tasks) byId.set(task.id, task)
+
+  // First pass: derive each task's own status.
+  const statuses = new Map<string, DerivedStatus>()
+  for (const task of tranche.tasks) {
+    statuses.set(task.id, deriveStatus(forgeFacts.get(task.id)))
+  }
+
+  // Second pass: dispatch eligibility, which references siblings' derived
+  // statuses (so it must come after the first pass).
+  const unknownEdges: UnknownEdge[] = []
+  const derived: DerivedTask[] = []
+  for (const task of tranche.tasks) {
+    const status = statuses.get(task.id) ?? 'todo'
+    const dependsOnNotMerged: string[] = []
+    for (const dep of task.dependsOn) {
+      if (!byId.has(dep)) {
+        unknownEdges.push({ from: task.id, to: dep, kind: 'depends-on' })
+        continue
+      }
+      if (statuses.get(dep) !== 'merged') dependsOnNotMerged.push(dep)
+    }
+    const conflictsWithOpenOrInFlight: string[] = []
+    for (const sib of task.conflictsWith) {
+      if (!byId.has(sib)) {
+        unknownEdges.push({ from: task.id, to: sib, kind: 'conflicts-with' })
+        continue
+      }
+      const sibStatus = statuses.get(sib)
+      if (sibStatus === 'in-flight' || sibStatus === 'in-review' || sibStatus === 'changes-requested') {
+        conflictsWithOpenOrInFlight.push(sib)
+      }
+    }
+    derived.push({
+      task,
+      status,
+      dispatchable: dependsOnNotMerged.length === 0 && conflictsWithOpenOrInFlight.length === 0,
+      blockers: { dependsOnNotMerged, conflictsWithOpenOrInFlight }
+    })
+  }
+
+  return { tranche, tasks: derived, unknownEdges }
+}
+
+/**
+ * Map a single task's forge facts to its derived status. Mirrors the §3 table
+ *: `blocked` wins over everything else, then `merged`, then
+ * `changes-requested`, then `in-review`, then `in-flight`, then `todo` for the
+ * open-issue cases (assigned or not — both are `todo` inside a tranche per
+ *), then the honest terminal cases for a closed-without-merge Issue.
+ *
+ * Reopened-after-merge exception: a reopened Issue can carry a stale
+ * `prState: 'merged'` fact from a closing PR that predates the reopen —
+ * `issueState` and `prState` are independently sourced, and GitHub does not
+ * retract a PR's merge history just because the Issue reopened. Without this
+ * check, such a task would permanently display `merged` even though the work
+ * it names was never actually done. Checked before the `prState === 'merged'`
+ * branch below so a currently-open Issue always wins over a historical merge.
+ *
+ * Honest terminal derivation: a closed Issue with no merged PR must
+ * never resolve to `todo` (which would imply not-started — a lie). It reads
+ * GitHub's native `stateReason`: closed `NOT_PLANNED` → `dropped` (legitimately
+ * abandoned); anything else (closed `COMPLETED` or no reason recorded) →
+ * `incoherent` (genuinely done but unprovable, or a broken close that the
+ * `Closes #N` law was built to surface).
+ *
+ * A missing `forgeFacts` entry → `todo`. Tranche tasks are committed work;
+ * `backlog` is a project-level concept only and is never emitted here.
+ *
+ * The rules themselves are no longer written here. They live as an ordered,
+ * pure-data list in `state-machine-model.ts` (the `actions.ts`
+ * discipline): one list, executed by this function and rendered by the docs,
+ * so the two cannot drift. Each rule carries the prose and the reason its
+ * position matters — change the order there, and this function's behavior
+ * changes with it.
+ */
+function deriveStatus(facts: ForgeFacts | undefined): DerivedStatus {
+  return deriveStatusFromModel(facts)
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/diagram-model.ts

@@ -0,0 +1,372 @@
+/**
+ * diagram-model.ts — the pure derivation at the heart of one library
+ * turns doctrine (`enforcement.md` rings/gates/checks + role/contract
+ * frontmatter + the canonical `ACTIONS` set) plus declarative config plus
+ * live status into a renderer-agnostic `DiagramModel`. Every diagram consumer
+ * (Studio, the Vinaya portal, a CLI visualizer) reads THIS model; none
+ * re-implements the governance logic. Zero I/O, zero `fs`/`node:`
+ * imports — doctrine arrives already-read through `DoctrineContent`;
+ * the file reads live behind `DoctrineSource` in `@attalabs/vinaya-sources`.
+ *
+ * What is NOT here: geometry. Radius, angle, colour, coordinates are the
+ * renderer's job (a ring index and a render-state are structural facts; a
+ * pixel is not). Render-state is DERIVED, never authored: `disabled` when
+ * config disables it, else `active`.
+ */
+
+import matter from 'gray-matter'
+import { ACTIONS, CROSSING_KEYWORDS } from './actions'
+import type { DoctrineContent } from './doctrine-source'
+import { findHeadingLine, findTable } from './markdown-table'
+import { parseEnforcementRegistry } from './registry-parse'
+import type { Tranche } from './types'
+
+export type DiagramNodeKind = 'ring' | 'gate' | 'check' | 'action' | 'role' | 'contract'
+export type RenderState = 'active' | 'disabled'
+
+export type DiagramNode = {
+  id: string
+  kind: DiagramNodeKind
+  label: string
+  ringIndex?: 0 | 1 | 2
+  renderState: RenderState
+  sourceLine?: number
+  summary?: string
+  /** What this node actually does, in one plain sentence — every kind carries
+   * one, each from its own source's `description`: the enforcement table's
+   * Description column for `gate`/`check`, `description:` frontmatter for
+   * `role`/`contract`, the `ACTIONS` entry's field for `action`. One register
+   * for every kind, because a reader cannot see what kind of node they
+   * clicked. Never `GateRow.spec` — that column is written to enforce, not to
+   * read (38% of rows cite a decision id, an issue number or a file path;
+   * longest is 2650 chars), and rendering it here is the bug this field
+   * exists to prevent. `summary` asks the question, this answers it, and
+   * "Read more" carries the spec. Optional because a source may omit it,
+   * never because a kind structurally lacks one. */
+  detail?: string
+  category?: 'ci' | 'hook' | 'event'
+  actorType?: 'agent' | 'human' | 'either'
+  /** Whether this action reaches GitHub — `action` nodes only, straight from
+   * its `ACTIONS` entry (the canonical set). On the node because a
+   * renderer cannot get it any other way: `ACTIONS` is a value export, and
+   * importing it into a client component drags `@attalabs/aeg-forge-state`'s
+   * `node:child_process` into the browser bundle. The distinction is
+   * doctrine-load-bearing — ring-0 gates guard exactly the crossings, and
+   * G3 exists to prove there is no unguarded one — so it must survive to the
+   * render rather than being implied by which ring a node was filed under. */
+  crosses?: 'into-github' | 'none'
+  /** The node's name **for a reader**, when its `label` is an identifier rather
+   * than words. `role`/`contract` nodes label themselves with their doctrine id
+   * (`brief-author`, `archivist-tranche-archivist`) because that id is the
+   * node's identity — routes, doc paths and edge endpoints all key off it, so
+   * it cannot be prettified in place. This carries the doc's own `title:`
+   * frontmatter instead, and every renderer showing a name to a person prefers
+   * it, falling back to `label` when absent.
+   *
+   * Deliberately NOT `sidebar_title`: that field is the docs nav's own caption,
+   * and sourcing a doctrine node's name from a nav hint would let a caption
+   * edit silently rename the node. `title:` is the document's own name, which
+   * is what a display name should be. */
+  displayLabel?: string
+  /** Where this node sits in the process, from its doc's `order:` frontmatter
+   * — `role`/`contract` nodes only. Doctrine files are read in filename order,
+   * which is alphabetical and therefore meaningless to a reader; the process
+   * runs plan → brief → build → review → verify → merge → archive, and that is
+   * the order every surface listing these nodes should present them in. Kept on
+   * the node rather than re-derived per renderer so the docs nav and the map
+   * cannot disagree about the sequence. Absent means unordered — a renderer
+   * sorting by it must treat that as "last", never as zero. */
+  order?: number
+}
+
+export type DiagramEdge = {
+  id: string
+  kind: 'guards' | 'performs' | 'produces' | 'consumes'
+  from: string
+  to: string
+}
+
+export type DiagramFinding = { configKey?: string; reason: string }
+
+export type DiagramConfig = {
+  rings?: { ring1_forgeWriteInterception?: boolean; ring2_asyncAudits?: boolean }
+  gates?: Record<string, boolean>
+}
+
+export type DiagramModel = {
+  nodes: DiagramNode[]
+  edges: DiagramEdge[]
+  findings: DiagramFinding[]
+  tranche: Tranche | null
+}
+
+/** Deterministic slug from a table row's first cell: lowercase, drop
+ * backticks/bold/markdown-link chrome, collapse non-alphanumerics to `-`. */
+function slugify(cell: string): string {
+  return cell
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/\*\*/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** The three ring summary labels, keyed by ring index, from `enforcement.md`'s
+ * `## The model:` summary table (the same table `loadRings` reads). Throws on a
+ * malformed doctrine — same contract as `parseEnforcementRegistry`.
+ *
+ * Keyed by row POSITION (row 0 = ring 0, row 1 = ring 1, row 2 = ring 2),
+ * not by a "0 —"/"1 —"/"2 —" text prefix on the cell — the labels
+ * themselves carry no numeric prefix (round-3 fix: dropped per Issue #508),
+ * so a prefix match would no longer find anything. The 3-row length check
+ * above is what actually guarantees the ring-0/1/2 order; position is a
+ * reliable key once that's enforced. */
+function ringLabels(enforcement: string): Record<0 | 1 | 2, string> {
+  const lines = enforcement.split('\n')
+  const summaryHeadingLine = findHeadingLine(lines, /^##\s*The model:/)
+  if (!summaryHeadingLine) throw new Error('enforcement.md: could not find "## The model:" heading')
+  const summaryTable = findTable(lines, summaryHeadingLine, false)
+  if (summaryTable?.rows.length !== 3) {
+    throw new Error('enforcement.md: summary table does not have exactly 3 rows (Ring 0/1/2)')
+  }
+  const byRow = summaryTable.rows.map((row) => (row.cells[0] ?? '').replace(/\*\*/g, '').trim())
+  return { 0: byRow[0] ?? '', 1: byRow[1] ?? '', 2: byRow[2] ?? '' }
+}
+
+type RoleFrontmatter = {
+  roleId: string
+  title?: string
+  order?: number
+  description?: string
+  summary?: string
+  actorType?: 'agent' | 'human' | 'either'
+}
+
+function extractRole(content: string): RoleFrontmatter | null {
+  const { data } = matter(content)
+  if (typeof data.role_id !== 'string') return null
+  return {
+    roleId: data.role_id,
+    title: typeof data.title === 'string' ? data.title : undefined,
+    order: typeof data.order === 'number' ? data.order : undefined,
+    description: typeof data.description === 'string' ? data.description : undefined,
+    summary: typeof data.summary === 'string' ? data.summary : undefined,
+    actorType: data.actor === 'agent' || data.actor === 'human' || data.actor === 'either' ? data.actor : undefined
+  }
+}
+
+type ContractFrontmatter = {
+  contractId: string
+  title?: string
+  order?: number
+  description?: string
+  producer?: string
+  consumer?: string
+  summary?: string
+}
+
+function extractContract(content: string): ContractFrontmatter | null {
+  const { data } = matter(content)
+  if (typeof data.contract_id !== 'string') return null
+  return {
+    contractId: data.contract_id,
+    title: typeof data.title === 'string' ? data.title : undefined,
+    order: typeof data.order === 'number' ? data.order : undefined,
+    description: typeof data.description === 'string' ? data.description : undefined,
+    producer: typeof data.producer === 'string' ? data.producer : undefined,
+    consumer: typeof data.consumer === 'string' ? data.consumer : undefined,
+    summary: typeof data.summary === 'string' ? data.summary : undefined
+  }
+}
+
+/**
+ * The pure derivation. `doctrine` is already-read raw markdown; `config` is the
+ * declarative enable/disable input (null = nothing disabled); `tranche` is
+ * StateSource live context, passed through verbatim and never used to compute
+ * render-state.
+ */
+export function deriveDiagramModel(
+  doctrine: DoctrineContent,
+  config: DiagramConfig | null,
+  tranche: Tranche | null
+): DiagramModel {
+  const nodes: DiagramNode[] = []
+  const edges: DiagramEdge[] = []
+  const findings: DiagramFinding[] = []
+
+  const labels = ringLabels(doctrine.enforcement)
+  const ring1Disabled = config?.rings?.ring1_forgeWriteInterception === false
+  const ring2Disabled = config?.rings?.ring2_asyncAudits === false
+
+  // --- Ring nodes (Ring 0 has no ring-level switch) ---
+  nodes.push({ id: 'ring:0', kind: 'ring', label: labels[0], ringIndex: 0, renderState: 'active' })
+  nodes.push({
+    id: 'ring:1',
+    kind: 'ring',
+    label: labels[1],
+    ringIndex: 1,
+    renderState: ring1Disabled ? 'disabled' : 'active'
+  })
+  nodes.push({
+    id: 'ring:2',
+    kind: 'ring',
+    label: labels[2],
+    ringIndex: 2,
+    renderState: ring2Disabled ? 'disabled' : 'active'
+  })
+
+  // --- Gate (Ring 0) and check (Ring 1/2) nodes from the detail tables ---
+  const gateRows = parseEnforcementRegistry(doctrine.enforcement)
+  const usedSlugs = new Set<string>()
+  const gateCheckSlugs = new Set<string>()
+  // Track ring-0 gate nodes (label + id) for the `guards` keyword match.
+  const ring0Gates: Array<{ id: string; label: string }> = []
+
+  for (const row of gateRows) {
+    const ringIndex: 0 | 1 | 2 = row.ring === 'ring0' ? 0 : row.ring === 'ring1' ? 1 : 2
+    const kind: DiagramNodeKind = ringIndex === 0 ? 'gate' : 'check'
+    const base = slugify(row.action)
+    const slug = usedSlugs.has(base) ? `${base}-${row.line}` : base
+    usedSlugs.add(slug)
+    gateCheckSlugs.add(slug)
+    const id = `${kind}:${slug}`
+
+    let renderState: RenderState
+    if (config?.gates?.[slug] === false) {
+      renderState = 'disabled'
+    } else if (ringIndex === 1 && ring1Disabled) {
+      renderState = 'disabled'
+    } else if (ringIndex === 2 && ring2Disabled) {
+      renderState = 'disabled'
+    } else {
+      renderState = 'active'
+    }
+
+    nodes.push({
+      id,
+      kind,
+      label: row.action,
+      ringIndex,
+      renderState,
+      sourceLine: row.line,
+      summary: row.summary,
+      detail: row.description,
+      category: row.category
+    })
+    if (ringIndex === 0) ring0Gates.push({ id, label: row.action })
+  }
+
+  // --- Action nodes (always active in v1) ---
+  for (const action of ACTIONS) {
+    nodes.push({
+      id: `action:${action.id}`,
+      kind: 'action',
+      label: action.label,
+      renderState: 'active',
+      summary: action.summary,
+      detail: action.description,
+      crosses: action.crosses
+    })
+  }
+
+  // --- Role nodes from roles/*.md frontmatter (skip files without role_id) ---
+  const roleIds = new Set<string>()
+  for (const file of doctrine.roles) {
+    const role = extractRole(file.content)
+    if (role === null) continue
+    if (roleIds.has(role.roleId)) continue
+    roleIds.add(role.roleId)
+    nodes.push({
+      id: `role:${role.roleId}`,
+      kind: 'role',
+      label: role.roleId,
+      displayLabel: role.title,
+      order: role.order,
+      renderState: 'active',
+      summary: role.summary,
+      detail: role.description,
+      actorType: role.actorType
+    })
+  }
+
+  // --- Contract nodes from contracts/*.md frontmatter (skip without id) ---
+  const contracts: ContractFrontmatter[] = []
+  for (const file of doctrine.contracts) {
+    const contract = extractContract(file.content)
+    if (contract === null) continue
+    contracts.push(contract)
+    nodes.push({
+      id: `contract:${contract.contractId}`,
+      kind: 'contract',
+      label: contract.contractId,
+      displayLabel: contract.title,
+      order: contract.order,
+      renderState: 'active',
+      summary: contract.summary,
+      detail: contract.description
+    })
+  }
+
+  // --- Edges ---
+  // guards: ring-0 gate → into-github action, matched by CROSSING_KEYWORDS
+  // (case-insensitive substring on the gate row label; one edge per match).
+  for (const action of ACTIONS) {
+    if (action.crosses !== 'into-github') continue
+    const keyword = (CROSSING_KEYWORDS[action.id] ?? '').toLowerCase()
+    if (keyword === '') continue
+    for (const gate of ring0Gates) {
+      if (!gate.label.toLowerCase().includes(keyword)) continue
+      edges.push({
+        id: `guards:${gate.id}:action:${action.id}`,
+        kind: 'guards',
+        from: gate.id,
+        to: `action:${action.id}`
+      })
+    }
+  }
+
+  // performs: role → action for every ACTIONS.performedBy entry (the canonical
+  // single source — the role's own `performs` frontmatter is intentionally not
+  // re-read, so the two lists can never drift).
+  for (const action of ACTIONS) {
+    for (const roleId of action.performedBy) {
+      edges.push({
+        id: `performs:role:${roleId}:action:${action.id}`,
+        kind: 'performs',
+        from: `role:${roleId}`,
+        to: `action:${action.id}`
+      })
+    }
+  }
+
+  // produces / consumes: role → contract from each contract's producer/consumer.
+  for (const contract of contracts) {
+    if (contract.producer !== undefined) {
+      edges.push({
+        id: `produces:role:${contract.producer}:contract:${contract.contractId}`,
+        kind: 'produces',
+        from: `role:${contract.producer}`,
+        to: `contract:${contract.contractId}`
+      })
+    }
+    if (contract.consumer !== undefined) {
+      edges.push({
+        id: `consumes:role:${contract.consumer}:contract:${contract.contractId}`,
+        kind: 'consumes',
+        from: `role:${contract.consumer}`,
+        to: `contract:${contract.contractId}`
+      })
+    }
+  }
+
+  // --- Findings: config keys that reference no real gate/check slug. Config
+  // references, never invents — surface the drift, don't silently drop it. ---
+  for (const key of Object.keys(config?.gates ?? {})) {
+    if (!gateCheckSlugs.has(key)) {
+      findings.push({ configKey: key, reason: `config gates["${key}"] references no gate or check in doctrine` })
+    }
+  }
+
+  return { nodes, edges, findings, tranche }
+}