@attalabs/vinaya 0.22.0 → 0.23.0

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,224 @@
+/**
+ * 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[] }
+
+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) {
+    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 }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/doc-owners.ts

@@ -0,0 +1,314 @@
+/**
+ * The `.vinaya/doc-owners` manifest parser and the C5 code→doc
+ * coverage evaluator (state-machine.md Section 15). Pure — I/O (reading the
+ * manifest off disk, checking pointer existence) is injected by the caller.
+ */
+
+import { isCodeFile } from './file-classify'
+import { WAIVER_LABEL } from './waiver-label'
+
+export const DOC_OWNERS_PATH = '.vinaya/doc-owners'
+
+export type DocOwnersBinding = { glob: string; pointer: string; lineNum: number }
+
+/**
+ * What a caller found where the manifest should be.
+ *
+ * `absent` — a repo that never configured doc ownership. Legitimately dormant.
+ * `empty` — a manifest that exists but has nothing in it. This is the shape a
+ *   misresolved repo root produces, and reporting it as success is how a broken
+ *   derivation passes for a real one. It is a refusal, not a dormancy.
+ * `present` — parse it.
+ *
+ * Split out of `verify-dispatch --surfaces` so the three-way decision is
+ * testable: the CLI chdirs to the repo root before reading, so the branch is
+ * unreachable from a test as long as it lives inside the command.
+ */
+export type DocOwnersManifestState = 'absent' | 'empty' | 'present'
+
+export function classifyDocOwnersManifest(content: string | null): DocOwnersManifestState {
+  if (content === null) return 'absent'
+  return content.trim() === '' ? 'empty' : 'present'
+}
+
+export type C5Result = { errors: string[]; notes: string[] }
+
+/**
+ * Parse the doc-owners file. Each non-blank, non-comment line is
+ *   `<code-glob>  <doc-pointer>`
+ *
+ * Comments start with `#`. Pointer is in-repo path, path#anchor, or URL.
+ * Returns the parsed bindings + any malformed-line errors.
+ */
+export function parseDocOwners(content: string): { bindings: DocOwnersBinding[]; errors: string[] } {
+  const bindings: DocOwnersBinding[] = []
+  const errors: string[] = []
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? ''
+    const stripped = raw.replace(/#.*$/, '').trim()
+    if (!stripped) continue
+    const parts = stripped.split(/\s+/)
+    if (parts.length < 2) {
+      errors.push(
+        `C5 doc-owners-parse: ${DOC_OWNERS_PATH}:${i + 1} — malformed binding (expected "<glob>  <pointer>", got "${raw.trim()}").`
+      )
+      continue
+    }
+    const [glob, ...pointerParts] = parts
+    bindings.push({ glob: glob ?? '', pointer: pointerParts.join(' '), lineNum: i + 1 })
+  }
+  return { bindings, errors }
+}
+
+/**
+ * Translate a doc-owners glob to a RegExp. Deliberately simple — only `*` and
+ * `**` are special; every other character is literal so Next.js dynamic-route
+ * segments like `[username]` match without escaping.
+ */
+export function globToRegex(pat: string): RegExp {
+  let re = '^'
+  let i = 0
+  while (i < pat.length) {
+    const c = pat[i]
+    if (c === '*') {
+      if (pat[i + 1] === '*') {
+        re += '.*'
+        i += 2
+      } else {
+        re += '[^/]*'
+        i += 1
+      }
+    } else if (/[.+^$|(){}[\]\\?]/.test(c as string)) {
+      re += `\\${c}`
+      i += 1
+    } else {
+      re += c
+      i += 1
+    }
+  }
+  re += '$'
+  return new RegExp(re)
+}
+
+export function isUrlPointer(p: string): boolean {
+  return /^https?:\/\//.test(p)
+}
+
+export function pointerToPath(p: string): string {
+  const idx = p.indexOf('#')
+  return idx === -1 ? p : p.slice(0, idx)
+}
+
+export type DocAck = { surface: string; note: string }
+export type DocNeutral = { surface: string; note: string }
+
+// Separator between <pointer> and <note>. Tolerates em-dash (—),
+// en-dash (–), or a plain ASCII hyphen-minus (-) with REQUIRED surrounding
+// whitespace. Required whitespace around `-` disambiguates the separator
+// from hyphens that legitimately appear inside pointers (e.g. `aeg-root`,
+// `.claude/skills/ui-components/SKILL.md`). Non-greedy `(.+?)` for the
+// pointer plus this anchored separator means the pointer naturally stops
+// at the first valid separator without literally excluding `-` from
+// the pointer character set.
+const SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source
+
+/** Shared by `Doc-ack:` and `Doc-neutral:` — both are `<field>: <pointer> <sep> <note>` PR-body lines. */
+function readPointerNoteField(body: string, field: string): { surface: string; note: string }[] {
+  const out: { surface: string; note: string }[] = []
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, 'gim')
+  for (const m of body.matchAll(re)) {
+    out.push({ surface: (m[1] ?? '').trim(), note: (m[2] ?? '').trim() })
+  }
+  return out
+}
+
+export function readDocAcks(body: string): DocAck[] {
+  return readPointerNoteField(body, 'Doc-ack')
+}
+
+/**
+ * `Doc-neutral: <pointer> — <note>` — declares that the doc a fired binding
+ * would otherwise require is not owed because the matched code change is
+ * mechanically neutral (comment/whitespace-only). Mirrors `Doc-ack:`'s
+ * grammar deliberately, so it reads as the same PR-body-field family.
+ *
+ * The declaration alone is never sufficient — see `isMechanicallyNeutralDiff`
+ * below, which `evaluateC5` requires as corroborating evidence before this
+ * declaration satisfies a fired binding. An unevidenced declaration is a
+ * distinct failure (`C5 doc-neutral-unverified`), not a silent pass — that
+ * asymmetry is what keeps this from being a self-serve exemption.
+ */
+export function readDocNeutrals(body: string): DocNeutral[] {
+  return readPointerNoteField(body, 'Doc-neutral')
+}
+
+/**
+ * Full-line comment markers, scoped per source-language file extension. A
+ * marker is listed for a language ONLY if no legitimate code construct in
+ * that language can start a trimmed line with it — that constraint is what
+ * keeps this fail-closed rather than a bare per-line prefix table (review
+ * finding, task 4 code review): a flat asterisk/hash/double-dash/block-
+ * comment-delimiter table misclassifies real code as comment — a TS/JS
+ * generator method (`*gen() {`), a TS/JS private class field
+ * (`#count = 0`), SQL's `--` also being C-style pre-decrement (`--i;`), and
+ * a block-comment-close delimiter hiding trailing code on the same line are
+ * all real collisions, not hypothetical ones. `//` is the only marker kept
+ * for TS/JS/JSX because no such language construct starts a trimmed line
+ * with `//`. An unrecognized extension gets no safe marker at all, so
+ * `isMechanicallyNeutralDiff` can never classify it neutral — fail-closed
+ * under uncertainty, not an attempt at full per-language comment/string-
+ * region parsing (out of this task's bounded "comment/whitespace-only"
+ * scope).
+ */
+const LANGUAGE_COMMENT_PREFIXES: ReadonlyArray<{ test: RegExp; prefixes: readonly string[] }> = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ['//'] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ['#'] },
+  { test: /\.(sh|bash)$/, prefixes: ['#'] },
+  { test: /\.ya?ml$/, prefixes: ['#'] },
+  { test: /\.py$/, prefixes: ['#'] }
+]
+
+function commentPrefixesForPath(path: string): readonly string[] {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path)) return prefixes
+  }
+  return []
+}
+
+function isNeutralDiffContentLine(line: string, prefixes: readonly string[]): boolean {
+  const t = line.trim()
+  if (t === '') return true
+  // A shebang is comment-shaped but changes what interpreter runs the
+  // file — real behavior, never neutral, even though it starts with `#`.
+  if (t.startsWith('#!')) return false
+  return prefixes.some((p) => t.startsWith(p))
+}
+
+/**
+ * The evidence half of the neutral-edit path: given a unified diff for one
+ * file and that file's path (for language-scoped comment-marker selection),
+ * true only if every added/removed line is comment-only or whitespace-only.
+ * Context lines and the `+++`/`---`/`@@` headers are not evidence either
+ * way. A diff with zero +/- content lines is not "a change" at all, so it
+ * returns false rather than vacuously true — there must be at least one
+ * actual edited line for a neutrality claim to mean anything. An
+ * unrecognized file extension (`commentPrefixesForPath` returns `[]`)
+ * always returns false — no fired binding on an unrecognized language can
+ * take the Doc-neutral path.
+ */
+export function isMechanicallyNeutralDiff(diffText: string, path: string): boolean {
+  const prefixes = commentPrefixesForPath(path)
+  let sawChange = false
+  for (const raw of diffText.split('\n')) {
+    if (raw.startsWith('+++ ') || raw.startsWith('--- ') || raw.startsWith('@@')) continue
+    if (raw.startsWith('+') || raw.startsWith('-')) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes)) return false
+      sawChange = true
+    }
+  }
+  return sawChange
+}
+
+/**
+ * Pure evaluator for the C5 doc-coverage check. The runtime wrapper reads
+ * `.vinaya/doc-owners` from disk and `PR_BODY` from env; this
+ * function takes both as inputs and an injectable file-exists for unit tests.
+ *
+ * Dormancy: a null `docOwnersContent` (absent file) OR no glob matching any
+ * changed code file produces an empty result — no errors, no notes.
+ *
+ * `waiverActive` is a single PR-wide boolean, not a per-binding
+ * pointer/reason lookup — it's the caller-resolved result of
+ * `isWaiverLabelActorVerified`, itself a mechanized read of a forge fact.
+ * There is no agent-emittable `Doc-waiver:` string anymore; a waiver is
+ * either verified true PR-wide, or not.
+ *
+ * `getDiff` is optional and injectable (unit tests; also absent whenever a
+ * caller has no diff-content source) — it resolves the unified diff for one
+ * matched code file, feeding the `Doc-neutral:` evidence check below. Its
+ * absence never produces a pass: a declared-but-unevidenced neutral claim
+ * fails the same as if it evidence didn't check out, preserving silence =
+ * failure (state-machine.md Section 15).
+ */
+export function evaluateC5(
+  changed: string[],
+  docOwnersContent: string | null,
+  prBody: string,
+  fileExists: (p: string) => boolean,
+  waiverActive: boolean,
+  getDiff?: (p: string) => string | null
+): C5Result {
+  const out: C5Result = { errors: [], notes: [] }
+
+  if (docOwnersContent === null) return out
+
+  const { bindings, errors: parseErrors } = parseDocOwners(docOwnersContent)
+  for (const e of parseErrors) out.errors.push(e)
+  if (bindings.length === 0) return out
+
+  const codeFiles = changed.filter(isCodeFile)
+  const fired: { binding: DocOwnersBinding; matchedFiles: string[] }[] = []
+  for (const b of bindings) {
+    const re = globToRegex(b.glob)
+    const matchedFiles = codeFiles.filter((f) => re.test(f))
+    if (matchedFiles.length > 0) fired.push({ binding: b, matchedFiles })
+  }
+  if (fired.length === 0) return out
+
+  const acks = readDocAcks(prBody)
+  const neutrals = readDocNeutrals(prBody)
+
+  for (const { binding: b, matchedFiles } of fired) {
+    if (waiverActive) {
+      out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`)
+      continue
+    }
+
+    if (isUrlPointer(b.pointer)) {
+      const acked = acks.some((a) => a.surface === b.pointer)
+      if (!acked) {
+        out.errors.push(
+          `C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}). External pointer requires \`Doc-ack: ${b.pointer} — <note>\` in the PR body, or an actor-verified \`${WAIVER_LABEL}\` label to skip.`
+        )
+      }
+      continue
+    }
+
+    const pointerPath = pointerToPath(b.pointer)
+    if (!fileExists(pointerPath)) {
+      out.errors.push(
+        `C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`
+      )
+      continue
+    }
+
+    if (changed.includes(pointerPath)) continue
+
+    const declared = neutrals.find((n) => n.surface === b.pointer)
+    if (declared) {
+      const evidenced =
+        getDiff !== undefined &&
+        matchedFiles.every((f) => {
+          const diff = getDiff(f)
+          return diff !== null && isMechanicallyNeutralDiff(diff, f)
+        })
+      if (evidenced) {
+        out.notes.push(
+          `C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(', ')} confirmed comment/whitespace-only.`
+        )
+        continue
+      }
+      out.errors.push(
+        `C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(', ')} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`
+      )
+      continue
+    }
+
+    out.errors.push(
+      `C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`
+    )
+  }
+
+  return out
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/build-doc-nav.ts

@@ -0,0 +1,38 @@
+import type { Doc, DocNav, DocSection } from './types'
+
+export type BuildDocNavOptions = {
+  sectionOrder?: string[]
+}
+
+function sectionIdOf(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+export function buildDocNav(docs: Doc[], opts: BuildDocNavOptions = {}): DocNav {
+  const bySection = new Map<string, Doc[]>()
+  for (const doc of docs) {
+    const list = bySection.get(doc.section) ?? []
+    list.push(doc)
+    bySection.set(doc.section, list)
+  }
+
+  const ordered: string[] = []
+  if (opts.sectionOrder) {
+    for (const label of opts.sectionOrder) if (bySection.has(label)) ordered.push(label)
+  }
+  for (const label of bySection.keys()) if (!ordered.includes(label)) ordered.push(label)
+
+  const sections: DocSection[] = ordered.map((label) => {
+    const items = (bySection.get(label) ?? []).slice().sort((a, b) => {
+      if (a.order !== b.order) return a.order - b.order
+      return a.title.localeCompare(b.title)
+    })
+    return { id: sectionIdOf(label), label, docs: items }
+  })
+
+  const flat = sections.flatMap((s) => s.docs)
+  return { sections, flat }
+}