@attalabs/vinaya 0.22.0 → 0.24.0

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 }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/direct-main-push.ts

@@ -0,0 +1,39 @@
+/**
+ * Direct-main-push detection (aeg-governance-hardening task 24, #364,
+ * Part 3 — item 1). Pure — no `fs`, no `gh`/`git` shell-outs. The CLI shim
+ * (`bin/check-direct-main-push.ts`) makes the one forge call (the
+ * commits→pulls association API: `GET /repos/{owner}/{repo}/commits/{sha}/pulls`,
+ * which GitHub documents as returning "the merged Pull Request that
+ * introduced the commit to the repository" for a commit on the default
+ * branch) and passes the result in here.
+ *
+ * Detection only, never prevention here: prevention lives at
+ * `.husky/pre-push` (ring 0) and the repository ruleset (ring 1). This
+ * predicate only decides whether the pushed commit is
+ * legitimate (associated with a merged PR) — the CLI shim opens an
+ * incident Issue and fails the run loudly on a violation; it never reverts
+ * or mutates anything (Principal decision, brief §11).
+ */
+
+export type DirectMainPushFact = {
+  sha: string
+  /** PR numbers the commits→pulls association API reports as MERGED for this commit. Empty when the commit has no associated merged PR — i.e. it was pushed directly. */
+  associatedMergedPrNumbers: number[]
+}
+
+export type DirectMainPushResult =
+  | { verdict: 'legitimate'; mergedPrNumber: number }
+  | { verdict: 'direct-push'; sha: string }
+
+/**
+ * `legitimate` — at least one merged PR is associated with this commit (the
+ *   normal case: a squash-merge or merge commit that landed via a PR).
+ * `direct-push` — no associated merged PR at all. This is the violation:
+ *   either a genuine direct push, or (equivalently suspicious) a commit the
+ *   association API cannot explain.
+ */
+export function checkDirectMainPush(fact: DirectMainPushFact): DirectMainPushResult {
+  const [first] = fact.associatedMergedPrNumbers
+  if (first !== undefined) return { verdict: 'legitimate', mergedPrNumber: first }
+  return { verdict: 'direct-push', sha: fact.sha }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/dispatch-gate.ts

@@ -0,0 +1,268 @@
+/**
+ * Dispatch-readiness composition (aeg-governance-hardening task 11, #324).
+ * Pure — no `fs`, no `fetch`. Composes the forge/rationale/provenance/
+ * archival facts the CLI shim (`bin/verify-dispatch.ts`) gathers (reusing
+ * `parseTranche`, `hasProvenance`, `taskRefFromBranch`,
+ * `checkIssueRationale`, `fetchProvenance` — never re-implementing any of
+ * them) into one `{ ready, blockers }` verdict, one blocker string per
+ * failing predicate.
+ *
+ * Every predicate here mechanizes a prose precondition that `roles/
+ * developer.md`'s entry gate and `contracts/brief-developer.md` currently
+ * state as something the Developer must re-derive by hand — the exact gap
+ * this task exists to close: four Developer agents independently re-derived
+ * (and stopped on) the same archival fact from scratch, at real token cost,
+ * hours after it first became true (aeg-governance-hardening's 2026-07-02/03
+ * live-fire wave).
+ *
+ * Message style mirrors `coherence-checks.ts`'s A1/A2/T2/etc. family: one
+ * line per failure, naming the exact task/Issue/PR involved.
+ */
+
+import type { Task } from './types'
+import { isPrincipal, PRINCIPAL_ALLOWLIST } from './waiver-label'
+
+export type DispatchIssueFact = { number: number; state: 'open' | 'closed' } | null
+
+export type DispatchEdgeFact = {
+  /** The edge's target task id, as written in the topology's depends-on/conflicts-with cell. */
+  id: string
+  /** The target task's Issue number, if known — for message readability only. */
+  issue: number | null
+}
+
+export type DispatchDependsOnFact = DispatchEdgeFact & {
+  merged: boolean
+  /**
+   * `false` when the resolver could not find any tranche/task/Issue matching
+   * this edge at all — a fact distinct from `merged: false`, which means the
+   * edge resolved to a real target that just hasn't merged yet. Conflating
+   * the two produced a false "not merged yet" claim for #193's
+   * `vinaya-milestone-model-v1 2` edge, which had genuinely already merged
+   * (#196) — the message this distinction exists to correct. Absent or
+   * `true` for every edge the resolver actually matched to a target,
+   * including one whose target lookup itself then failed (an outage), which
+   * stays under the existing conservative `merged: false` default rather
+   * than this one.
+   */
+  resolved?: boolean
+  /**
+   * Hand-close recognition facts (task `vinaya-engine-v1` 21, #99) — a
+   * second, narrower path alongside `merged` for a dependency Issue closed
+   * directly by a recognized Principal, with a stated `COMPLETED` reason,
+   * rather than via a merged PR. All three are `null`/absent when the edge
+   * is unresolvable or the target issue is open/has no close event — in
+   * which case this path never fires and only `merged` matters, same as
+   * before this task.
+   */
+  issueState?: 'open' | 'closed' | null
+  stateReason?: 'completed' | 'not_planned' | null
+  closedByActor?: string | null
+}
+
+/**
+ * True when a dependency Issue was closed directly by a recognized Principal
+ * with a stated `COMPLETED` reason — the second, narrower "done" path this
+ * task adds alongside `merged`. Deliberately conjunctive and centralized
+ * here (not duplicated per caller): the trap this task exists to avoid is
+ * "any closed Issue with a comment counts," so every condition below is a
+ * real forge fact, not a prose claim —
+ *   - `issueState === 'closed'`: the Issue is actually closed.
+ *   - `stateReason === 'completed'`: GitHub's own close reason says resolved,
+ *     not `not_planned` (abandoned — the opposite of resolved).
+ *   - `closedByActor` is the GitHub login that performed the CLOSED_EVENT
+ *     (not a claim in a comment body) and is a member of the recognized
+ *     Principal allowlist.
+ */
+function isHandClosedByRecognizedPrincipal(
+  dep: Pick<DispatchDependsOnFact, 'issueState' | 'stateReason' | 'closedByActor'>,
+  principalAllowlist: string[]
+): boolean {
+  return (
+    dep.issueState === 'closed' &&
+    dep.stateReason === 'completed' &&
+    isPrincipal(dep.closedByActor ?? null, principalAllowlist)
+  )
+}
+
+export type DispatchConflictsWithFact = DispatchEdgeFact & { openOrInFlight: boolean }
+
+/**
+ * Removed the predicate that consumed this fact
+ * (`checkDispatchReadiness` no longer blocks on it) — automated the
+ * signal (per-task provenance posting) this predicate existed to protect,
+ * making the row-adjacency gate itself the stale part, not the automation.
+ * Kept, dormant, rather than deleted: several callers (`bin/verify-dispatch.ts`,
+ * both Studio/Vinaya `map-dispatch-input.ts` mappers) still assemble this
+ * fact as harmless dead plumbing, and `DispatchGateInput.priorTask` below
+ * remains the exact shape needed to test the predicate's absence.
+ */
+export type DispatchPriorTaskFact = {
+  id: string
+  issue: number | null
+  issueClosed: boolean
+  prMerged: boolean
+  hasProvenance: boolean
+}
+
+export type DispatchPriorTrancheFact = {
+  project: string
+  /** null when this project has no prior tranche at all — the gate passes trivially for it. */
+  priorTrancheSlug: string | null
+  archived: boolean
+}
+
+export type DispatchGateInput = {
+  trancheSlug: string
+  /** The topology row for this task, as parsed by `parseTranche`. */
+  task: Task
+  /** null when the task has no Issue (#TBD/blank) OR the Issue number doesn't resolve on the forge (phantom ref). */
+  issue: DispatchIssueFact
+  /** `checkIssueRationale` result for this task's Issue — irrelevant (treated as passing) when `issue` is null. */
+  issueRationalePass: boolean
+  dependsOn: DispatchDependsOnFact[]
+  conflictsWith: DispatchConflictsWithFact[]
+  /**
+   * The immediately-prior task in this same tranche's topology, or null
+   * when this is the first task. no longer read by
+   * `checkDispatchReadiness` — dormant field, kept for caller compatibility.
+   */
+  priorTask: DispatchPriorTaskFact | null
+  /** One entry per project named in `task.projects`. */
+  priorTrancheArchival: DispatchPriorTrancheFact[]
+  /**
+   * Overrides `PRINCIPAL_ALLOWLIST` for hand-close recognition when
+   * provided — an adopter repo's own `vinaya.config.json` `principals`
+   * field, resolved by the CLI bin before calling in (never read from here;
+   * this stays pure). Defaults to `PRINCIPAL_ALLOWLIST` when omitted, same
+   * pattern as `checkReviewGate`'s `principalAllowlist` (`review-gate.ts`) —
+   * hardcoding this repo's own principal made that gate unpassable on any
+   * adopter repo; the same mistake here would silently do the same to the
+   * hand-close path.
+   */
+  principalAllowlist?: string[]
+}
+
+export type DispatchResult = { ready: boolean; blockers: string[] }
+
+/**
+ * True when a parsed `depends-on` edge points back at its own host task.
+ *
+ * A self-dependency is unsatisfiable by construction, so it is never a real
+ * gate state — its presence is proof of a defect in the edge text or in its
+ * resolution. `parseRationaleDeps` (`@attalabs/aeg-forge-state`) reads only
+ * a labeled `Depends-on:`/`Conflicts-with:` field's own comma-separated,
+ * id-shaped tokens; since Issue #347 an unlabeled/bare span elsewhere in the
+ * "Dependency rationale" section is never read as an edge, whatever its
+ * shape (`parse-rationale-deps.ts`'s own module comment states the rule). A
+ * slug-qualified token in that list (`aeg-governance-hardening #368`) still
+ * resolves its trailing bare number against the NAMED tranche, not the host
+ * — a resolver bug there is what would land a task depending on itself, on
+ * that tranche's own task `1`.
+ *
+ * Reported as an INTERNAL error rather than through the ordinary
+ * "not merged yet" branch below, because that message reads as a legitimate
+ * serialization and invites the reader to route around it: two Developer
+ * agents faced with exactly this gate concluded it was a false positive and
+ * committed with `--no-verify` to get past their hooks. Naming it a tool bug
+ * converts "agent improvises around a nonsense gate" into "agent escalates,"
+ * which is the behavior the gate architecture assumes.
+ *
+ * Two arms, because the edge can carry either shape: a resolved Issue number
+ * equal to this task's own, or — the live case — a bare same-tranche id equal
+ * to this task's own id.
+ */
+function isSelfDependency(dep: DispatchDependsOnFact, task: Task, issue: DispatchIssueFact): boolean {
+  if (dep.issue !== null && issue !== null && dep.issue === issue.number) return true
+  const bare = dep.id.trim().replace(/^#/, '')
+  return bare.toLowerCase() === task.id.trim().toLowerCase()
+}
+
+export function checkDispatchReadiness(input: DispatchGateInput): DispatchResult {
+  const { trancheSlug, task } = input
+  const taskLabel = `task ${task.id} (tranche ${trancheSlug})`
+  const principalAllowlist = input.principalAllowlist ?? PRINCIPAL_ALLOWLIST
+  const blockers: string[] = []
+
+  // Issue-existence — the topology row itself has no Issue number.
+  if (task.issue === null) {
+    blockers.push(
+      `dispatch-gate issue-existence: ${taskLabel} has no Issue (#TBD or blank) in the topology — not dispatchable until the Planner cuts the Issue.`
+    )
+  } else if (input.issue === null) {
+    // Row names an Issue number, but it doesn't resolve on the forge — phantom ref (T1's fail class).
+    blockers.push(
+      `dispatch-gate issue-existence: ${taskLabel} names Issue #${task.issue}, but it does not resolve to a real GitHub Issue (phantom reference).`
+    )
+  }
+
+  // Planner-rationale completeness — only evaluable when the Issue itself resolved.
+  if (input.issue !== null && !input.issueRationalePass) {
+    blockers.push(
+      `dispatch-gate rationale: Issue #${input.issue.number} for ${taskLabel} fails the rationale gate (checkIssueRationale) — the Planner must complete the eight-field rationale before this task is dispatchable.`
+    )
+  }
+
+  // Depends-on merged — OR hand-closed by a recognized Principal (task
+  // `vinaya-engine-v1` 21, #99): a second, narrower path for a dependency
+  // Issue closed directly rather than via a merged PR.
+  for (const dep of input.dependsOn) {
+    // Evaluated BEFORE the unresolvable branch: a self-reference that also
+    // failed to resolve is still a parser bug, and reporting it as an
+    // unresolvable edge would send the reader to correct edge text that is
+    // not actually the fault.
+    if (isSelfDependency(dep, task, input.issue)) {
+      const issueStr = input.issue !== null ? `#${input.issue.number}` : '?'
+      blockers.push(
+        `dispatch-gate INTERNAL: parsed a self-dependency for task ${task.id} (${issueStr}) — this is a parser bug in parseRationaleDeps, not a real dependency. Please report it upstream. Re-run once the rationale is corrected or the fix ships.`
+      )
+      continue
+    }
+    if (dep.resolved === false) {
+      // Distinct from the "not merged yet" branch below (#196): this edge
+      // never resolved to any tranche/task/Issue at all, so a "not merged"
+      // claim would misattribute the failure to the forge rather than to
+      // the edge text. Still blocks — the conservative default is correct
+      // for a genuinely unresolvable edge — but says so honestly.
+      blockers.push(
+        `dispatch-gate depends-on: ${taskLabel} depends on "${dep.id}", which is UNRESOLVABLE — the resolver could not find a matching tranche/task/Issue for this edge (not a claim about merge status). Not dispatchable until the edge is corrected.`
+      )
+      continue
+    }
+    if (!dep.merged && !isHandClosedByRecognizedPrincipal(dep, principalAllowlist)) {
+      const issueStr = dep.issue !== null ? ` (#${dep.issue})` : ''
+      blockers.push(
+        `dispatch-gate depends-on: ${taskLabel} depends on ${dep.id}${issueStr}, whose PR is not merged yet — not dispatchable, it serializes behind it.`
+      )
+    }
+  }
+
+  // Conflicts-with not open/in-flight.
+  for (const c of input.conflictsWith) {
+    if (c.openOrInFlight) {
+      const issueStr = c.issue !== null ? ` (#${c.issue})` : ''
+      blockers.push(
+        `dispatch-gate conflicts-with: ${taskLabel} conflicts with ${c.id}${issueStr}, whose PR is open or in-flight — not dispatchable until it merges.`
+      )
+    }
+  }
+
+  // Prior-task archival / row-adjacency predicate REMOVED (2026-07-13).
+  // The retired predicate required every earlier table row's full archival (Issue
+  // closed, PR merged, provenance posted) regardless of whether that row was
+  // a declared dependency automated the provenance-posting signal
+  // this existed to protect, so the blanket row-order block outlived its
+  // justification. `input.priorTask` is still accepted (dormant) for caller
+  // compatibility; see the type's doc comment above.
+
+  // Prior-tranche archival, per project named in Project(s).
+  for (const proj of input.priorTrancheArchival) {
+    if (proj.priorTrancheSlug !== null && !proj.archived) {
+      blockers.push(
+        `dispatch-gate prior-tranche-archival: project \`${proj.project}\`'s previous tranche \`${proj.priorTrancheSlug}\` is not archived — the Tranche Archivist must run before new work on this product.`
+      )
+    }
+  }
+
+  return { ready: blockers.length === 0, blockers }
+}