@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/published-prose.ts

@@ -0,0 +1,306 @@
+/**
+ * C7 — the published-prose check. Pure and zero-I/O, shaped like
+ * `docs-coherence.ts` (parsed entries plus the model-backed surfaced-path
+ * allowlist in, `{ errors, notes }` out).
+ *
+ * A role or contract doc is read by two audiences with opposite needs: an
+ * agent taking the role reads it end to end as its operating instruction, and
+ * a person landing on `/docs/roles/<id>` reads the same file cold. The answer
+ * is one short, binding section at the top of every role and contract — `##
+ * The short version` — which is what publishes; everything under `##
+ * Reference` explains it and stays in the repo. This check enforces two
+ * properties of that section, over the published set only:
+ *
+ *   1. **Structure** — every surfaced `roles/*.md` and `contracts/*.md` opens
+ *      with a `## The short version` section carrying all four bold-led
+ *      blocks, in order, inside the word band. The blocks answer the same four
+ *      questions for a role and for a seam (what it owns/carries, when it
+ *      refuses, what it never does, how it physically runs), which is why the
+ *      lead-ins differ by kind but the count and order never do.
+ *   2. **Readability** — the text that actually reaches a reader carries no
+ *      token a stranger cannot resolve from the page: no decision id, no
+ *      section sign, no forge number, no retired public name, no tranche
+ *      slug, no repo-internal path, and no label vocabulary (namespaced or
+ *      retired alike — a published page should name neither, and flagging only
+ *      the current grammar would leave every retired mention invisible).
+ *
+ * **What "published" means here is deliberately narrow.** For a role or
+ * contract it is the short version, not the file. For `enforcement.md` it is
+ * the introduction plus the four columns the page renders — the row's own
+ * name, `Summary`, `Category`, `Description`. The enforcing columns (`Gate`,
+ * `What must be true…`, `Re-verifies`, `Runs`, `Catches`, `implementation`,
+ * `lock`) are never scanned: they never reach a page, and flagging them would
+ * demand rewriting the gate registry to suit a website. Columns resolve by
+ * HEADER NAME, never by index — the three ring tables have different shapes,
+ * and `Summary`/`Category`/`Description` are the ones spelled identically in
+ * all three, the same property `registry-parse.ts` relies on for
+ * `Description`.
+ *
+ * **Protocol mechanics are published on purpose.** `.worktrees/task/<tranche>/<n>`
+ * and the `task/<tranche>/<n>` branch convention are the method an adopter
+ * must learn, not this repo's internals — they are masked out before scanning
+ * so a path rule can never eat them, and that exemption is tested rather than
+ * incidental.
+ */
+
+import { findHeadingLine, findTable } from '../markdown-table'
+import { isSurfacedDoc } from './surfaced-manifest'
+import type { DocFrontmatter } from './types'
+
+export const SHORT_VERSION_HEADING = 'The short version'
+export const REFERENCE_HEADING = 'Reference'
+
+/** Words. Under the floor means something was dropped; over the ceiling means
+ * the reference is being summarised instead of the rule being stated. */
+export const SHORT_VERSION_MIN_WORDS = 150
+export const SHORT_VERSION_MAX_WORDS = 450
+
+/** The four blocks, in order, as a role answers them. */
+export const ROLE_BLOCKS = ['You own', 'You refuse', 'You never', 'How it physically runs'] as const
+
+/** The same four blocks, as a seam answers them. */
+export const CONTRACT_BLOCKS = [
+  'What crosses',
+  'The hand-off is malformed',
+  'What it does not carry',
+  'How it physically runs'
+] as const
+
+/**
+ * Protocol facts that must survive every readability rule. Masked out of the
+ * text before scanning, longest first, so a repo-internal-path rule can never
+ * claim the branch convention.
+ */
+export const ALLOWED_MECHANICS: readonly string[] = [
+  '.worktrees/task/<tranche>/<n>',
+  'task/<tranche>/<n>',
+  '.worktrees/'
+]
+
+export type PublishedProseEntry = {
+  /** Path relative to `aeg-root/`, e.g. `roles/developer.md`. */
+  relPath: string
+  frontmatter: Pick<DocFrontmatter, 'surfaced' | 'title' | 'description'>
+  body: string
+}
+
+export type PublishedProseResult = { errors: string[]; notes: string[] }
+
+type ProseRule = { id: string; what: string; pattern: RegExp }
+
+/**
+ * Every rule is case-sensitive on purpose where the token itself is: forge
+ * labels are lower-case, so a lower-case-only match keeps a capitalized
+ * English word ("Project:", the PR-body field) from being read as the deleted
+ * `project:*` label family.
+ */
+const PROSE_RULES: ProseRule[] = [
+  { id: 'decision-id', what: 'a decision id', pattern: /\bD-\d{3,}\b/ },
+  { id: 'section-ref', what: 'a section reference', pattern: /§/ },
+  { id: 'forge-number', what: 'a forge number', pattern: /#\d+/ },
+  { id: 'retired-name', what: 'the retired public name', pattern: /\bAEG\b/ },
+  { id: 'tranche-slug', what: 'a tranche slug', pattern: /\b[a-z][a-z0-9]*(?:-[a-z0-9]+)+-v\d+\b/ },
+  {
+    id: 'label-vocabulary',
+    what: 'forge label vocabulary',
+    // Every entry here is CUMULATIVE — a retired namespace stays banned after
+    // the objects carrying it are gone, because a published page naming it is
+    // just as unreadable to a stranger as one naming the current grammar (see
+    // the module header). `aeg:` is retired and still listed for that reason,
+    // and `iteration:` joins it: the rename to `tranche:` ADDS an alternative,
+    // it does not substitute one. Substituting is how a rename silently
+    // narrows this gate — the forge still carried `vinaya/iteration:*` labels
+    // when the rename landed, and a page naming one would have passed.
+    pattern: /(?:vinaya\/)?\b(?:tranche|iteration|tier|needs|waiver|project|aeg):(?![/\s]|$)/
+  },
+  { id: 'internal-path', what: 'a repo-internal path', pattern: /\b(?:packages|apps|aeg-root|tools|scripts)\// },
+  { id: 'internal-path', what: 'a repo-internal path', pattern: /\.(?:claude|husky|github)\// },
+  {
+    id: 'internal-path',
+    what: 'a repo-internal file',
+    pattern: /(?:^|[\s(`"'[])[\w.-]+(?:\/[\w.-]+)*\.(?:ts|tsx|js|jsx|mjs|cjs|sh|ya?ml|json|md)\b/
+  }
+]
+
+/** The doc kinds this check governs, and the block set each answers with. */
+function blocksFor(relPath: string): readonly string[] | null {
+  if (relPath.startsWith('roles/')) return ROLE_BLOCKS
+  if (relPath.startsWith('contracts/')) return CONTRACT_BLOCKS
+  return null
+}
+
+function sectionBody(body: string, heading: string): string | null {
+  const lines = body.split('\n')
+  const start = lines.findIndex((line) => line.trim() === `## ${heading}`)
+  if (start === -1) return null
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s/.test(line))
+  return (end === -1 ? rest : rest.slice(0, end)).join('\n').trim()
+}
+
+/**
+ * The section a role/contract page publishes, or null when the doc carries
+ * none. The single extraction both the gate and Vinaya's `/docs` renderer
+ * read, so the page and the check can never disagree about what "published"
+ * means.
+ */
+export function extractShortVersion(body: string): string | null {
+  return sectionBody(body, SHORT_VERSION_HEADING)
+}
+
+/**
+ * What a role/contract page renders, with a degradation ladder that never
+ * leaks the reference: the short version when present; otherwise the body
+ * above `## Reference`; otherwise the whole body (a doc with neither heading
+ * is not governed by C7's structure rule and has no reference to hide).
+ */
+export function publishedDoctrineBody(body: string): string {
+  const short = extractShortVersion(body)
+  if (short !== null) return short
+  const lines = body.split('\n')
+  const referenceAt = lines.findIndex((line) => line.trim() === `## ${REFERENCE_HEADING}`)
+  return referenceAt === -1 ? body : lines.slice(0, referenceAt).join('\n').trim()
+}
+
+export function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length
+}
+
+function maskAllowedMechanics(text: string): string {
+  let masked = text
+  for (const literal of ALLOWED_MECHANICS) {
+    masked = masked.split(literal).join(' ')
+  }
+  return masked
+}
+
+/**
+ * The four columns `enforcement.md` actually renders — the row's own name plus
+ * `Summary`, `Category`, `Description` — and the introduction above the first
+ * ring. Everything else in those tables is enforcing text that never reaches a
+ * page.
+ */
+export function enforcementPublishedText(content: string): string[] {
+  const lines = content.split('\n')
+  const out: string[] = []
+
+  const firstRing = lines.findIndex((line) => /^##\s+Ring 0\b/.test(line))
+  out.push((firstRing === -1 ? lines : lines.slice(0, firstRing)).join('\n'))
+
+  const publishedHeaders = ['summary', 'category', 'description']
+  for (const ring of [0, 1, 2]) {
+    const headingLine = findHeadingLine(lines, new RegExp(`^##\\s+Ring ${ring}\\b`))
+    if (headingLine === null) continue
+    const table = findTable(lines, headingLine + 1)
+    if (!table) continue
+    const indices = publishedHeaders
+      .map((name) => table.headers.findIndex((h) => h.trim().toLowerCase() === name))
+      .filter((i) => i !== -1)
+    for (const row of table.rows) {
+      out.push(row.cells[0] ?? '')
+      for (const i of indices) out.push(row.cells[i] ?? '')
+    }
+  }
+
+  return out.filter((text) => text.trim().length > 0)
+}
+
+/**
+ * The readability rules, callable on any published text — not just a doc body.
+ *
+ * Exported because `/docs/actions` renders prose that lives in TypeScript
+ * (`ACTIONS` in `actions.ts`), not in a markdown file, so `evaluatePublishedProse`
+ * never sees it. A whole published page was unguarded on that technicality;
+ * `actions.test.ts` closes it by running this over every entry.
+ */
+export function readabilityErrors(where: string, texts: string[]): string[] {
+  const errors: string[] = []
+  checkReadability(where, texts, errors)
+  return errors
+}
+
+function checkReadability(where: string, texts: string[], errors: string[]): void {
+  const seen = new Set<string>()
+  for (const raw of texts) {
+    const text = maskAllowedMechanics(raw)
+    for (const rule of PROSE_RULES) {
+      const match = text.match(rule.pattern)
+      if (!match) continue
+      const token = (match[0] ?? '').trim()
+      const key = `${rule.id}:${token}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      errors.push(`C7: published text in "${where}" contains ${rule.what} a reader cannot resolve: "${token}"`)
+    }
+  }
+}
+
+function checkStructure(relPath: string, body: string, blocks: readonly string[], errors: string[]): void {
+  const short = extractShortVersion(body)
+  if (short === null) {
+    errors.push(
+      `C7: surfaced doc "${relPath}" has no "## ${SHORT_VERSION_HEADING}" section — the published page would have nothing binding to show a reader`
+    )
+    return
+  }
+
+  let cursor = 0
+  for (const block of blocks) {
+    const at = short.indexOf(`**${block}`, cursor)
+    if (at === -1) {
+      errors.push(`C7: "${relPath}" short version is missing the "${block}" block (all four blocks always appear)`)
+      continue
+    }
+    cursor = at + block.length
+  }
+
+  const words = countWords(short)
+  if (words < SHORT_VERSION_MIN_WORDS) {
+    errors.push(
+      `C7: "${relPath}" short version is ${words} words, under the ${SHORT_VERSION_MIN_WORDS}-word floor — something was dropped`
+    )
+  } else if (words > SHORT_VERSION_MAX_WORDS) {
+    errors.push(
+      `C7: "${relPath}" short version is ${words} words, over the ${SHORT_VERSION_MAX_WORDS}-word ceiling — state the rule, don't summarise the reference`
+    )
+  }
+}
+
+/**
+ * Runs both checks over the published set only. `entries` may hold every doc
+ * under `aeg-root/`; `surfacedPaths` (the model-backed allowlist) is what
+ * narrows it, so this check can never publish-check a doc the site does not
+ * publish, nor miss one it does.
+ */
+export function evaluatePublishedProse(
+  entries: PublishedProseEntry[],
+  surfacedPaths: ReadonlySet<string> = new Set()
+): PublishedProseResult {
+  const errors: string[] = []
+  const notes: string[] = []
+
+  const surfaced = entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths))
+
+  for (const entry of surfaced) {
+    // Frontmatter renders too: `title` is the page heading and the sidebar
+    // entry, `description` is the page metadata. Checking only the body left
+    // both unguarded — a citation in a title reaches a reader exactly as
+    // surely as one in a paragraph.
+    checkReadability(entry.relPath, [entry.frontmatter.title ?? '', entry.frontmatter.description ?? ''], errors)
+
+    const blocks = blocksFor(entry.relPath)
+    if (blocks) {
+      checkStructure(entry.relPath, entry.body, blocks, errors)
+      const short = extractShortVersion(entry.body)
+      if (short !== null) checkReadability(entry.relPath, [short], errors)
+      continue
+    }
+    if (entry.relPath === 'enforcement.md') {
+      checkReadability(entry.relPath, enforcementPublishedText(entry.body), errors)
+    }
+  }
+
+  if (surfaced.length === 0) notes.push('C7: no surfaced docs to check.')
+
+  return { errors, notes }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/surfaced-manifest.ts

@@ -0,0 +1,89 @@
+/**
+ * The canonical "surfaced doc" manifest for `aeg-root/`. Defines, as
+ * data, which docs a public AEG page shows. The rule is **model-backed**: a
+ * doc is surfaced if and only if a `DiagramModel` node points at it.
+ * The same `DiagramModel` that `/docs/harness` renders is the allowlist for
+ * `/docs/reference` — the two surfaces are two renderers of one model, and the doc that
+ * backs no reachable node stops being public, every build.
+ *
+ * The node→doc mapping (`modelBackedDocPaths`) is the same one `read-more.ts`
+ * uses to resolve a node's "Read more" target: gate/check nodes back
+ * `enforcement.md`; a role node backs `roles/<id>.md`; a contract node backs
+ * `contracts/<id>.md`. `action`/`ring` nodes back no `aeg-root/**` document
+ * (an action's source is `packages/aeg-core/src/actions.ts`, a ring is a
+ * summary label), so they add nothing to the set. Today that is 16 files —
+ * `enforcement.md` + the 9 `roles/*.md` + the 6 `contracts/*.md`.
+ *
+ * This is the single source of truth the C6 docs-coherence check
+ * (`docs-coherence.ts`) and Vinaya's `/docs` loader both consume. There is
+ * **no second, path-based exclusion rule** — a competing rule is the failure
+ * mode this manifest exists to prevent, and the model-backed set replaced the
+ * old path-exclusion rules outright rather than sitting beside them. The only
+ * escape hatch is the per-doc `surfaced` frontmatter override, which wins in
+ * both directions.
+ *
+ * Purity: this module imports only the `DiagramModel` **type** from the
+ * diagram layer — no runtime coupling, no I/O. The doctrine is read (and the
+ * model derived) by the caller, which passes the derived path set in; aeg-core
+ * stays zero-I/O (#372/#382/#506).
+ *
+ * Paths are relative to `aeg-root/` (e.g. `roles/developer.md`), matching
+ * `DocFrontmatter`'s existing convention.
+ */
+
+import type { DiagramModel } from '../diagram-model'
+import type { DocFrontmatter } from './types'
+
+/**
+ * The set of `aeg-root/`-relative doc paths a `DiagramModel` points at — the
+ * allowlist. Mirrors `read-more.ts`'s `docRoute` resolution exactly, so
+ * `/docs/reference`'s surfaced set and `/docs/harness`'s "Read more" targets can never
+ * name different files: gate/check → `enforcement.md`, role → `roles/<id>.md`,
+ * contract → `contracts/<id>.md`. A node's `label` is its doctrine id
+ * (`role.roleId` / `contract.contractId`), and every `roles/*.md` /
+ * `contracts/*.md` file is named `<id>.md` — one convention backs both the
+ * GitHub path and the docs route.
+ */
+export function modelBackedDocPaths(model: DiagramModel): Set<string> {
+  const paths = new Set<string>()
+  for (const node of model.nodes) {
+    if (node.kind === 'gate' || node.kind === 'check') paths.add('enforcement.md')
+    else if (node.kind === 'role') paths.add(`roles/${node.label}.md`)
+    else if (node.kind === 'contract') paths.add(`contracts/${node.label}.md`)
+  }
+  return paths
+}
+
+const NO_MODEL_BACKED_PATHS: ReadonlySet<string> = new Set()
+
+/**
+ * Whether `relPath` (relative to `aeg-root/`) is a surfaced doc. A boolean
+ * `surfaced` frontmatter field always wins over the model — the escape hatch
+ * in both directions. Otherwise the doc is surfaced iff it is in
+ * `surfacedPaths` (the model-backed allowlist from `modelBackedDocPaths`).
+ *
+ * `surfacedPaths` is optional so a caller that has no model surfaces nothing
+ * by default rather than everything — the safe direction for a rule whose
+ * whole point is that a doc publishes only when a node points at it.
+ */
+export function isSurfacedDoc(
+  relPath: string,
+  frontmatter: Pick<DocFrontmatter, 'surfaced'>,
+  surfacedPaths: ReadonlySet<string> = NO_MODEL_BACKED_PATHS
+): boolean {
+  if (typeof frontmatter.surfaced === 'boolean') return frontmatter.surfaced
+  return surfacedPaths.has(relPath)
+}
+
+export type SurfacedManifestEntry = {
+  relPath: string
+  frontmatter: Pick<DocFrontmatter, 'surfaced'>
+}
+
+/** Filters a list of parsed doc entries down to the surfaced subset. */
+export function surfacedDocs(
+  entries: SurfacedManifestEntry[],
+  surfacedPaths: ReadonlySet<string> = NO_MODEL_BACKED_PATHS
+): string[] {
+  return entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths)).map((e) => e.relPath)
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/types.ts

@@ -0,0 +1,33 @@
+export type DocFrontmatter = {
+  title?: string
+  sidebarTitle?: string
+  description?: string
+  section?: string
+  order?: number
+  parent?: string
+  surfaced?: boolean
+}
+
+export type Doc = {
+  slug: string
+  title: string
+  sidebarTitle?: string
+  description?: string
+  section: string
+  order: number
+  href: string
+  filePath: string
+  children?: Doc[]
+  parentSlug?: string
+}
+
+export type DocSection = {
+  id: string
+  label: string
+  docs: Doc[]
+}
+
+export type DocNav = {
+  sections: DocSection[]
+  flat: Doc[]
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/doctrine-portability.ts

@@ -0,0 +1,170 @@
+/**
+ * Doctrine portability — the class `check-reader-resolvable-prose` sweeps
+ * but cannot see (task 234, Issue #234). That check's own module header
+ * declares zero I/O, so it never resolves a cited path against a
+ * filesystem — and if it tried, it would resolve against the authoring
+ * repo, the one environment where every author-repo-internal path in
+ * `aeg-root/**` happens to exist.
+ *
+ * The reframe that makes this decidable with no I/O at all: the rule is not
+ * "this path does not resolve in the adopter" (which needs a filesystem to
+ * even ask) but **"portable doctrine names a non-portable path."** A cited
+ * path is judged purely by its own shape — its top path segment — against a
+ * fixed allow-list of prefixes known to be doctrine-relative or
+ * adopter-owned. Everything else is a finding, including a prefix nobody
+ * has classified yet: an allow-list fails closed on an unknown prefix (a
+ * build artifact is exactly as non-portable as the source it was built
+ * from), where a deny-list of "known author-repo prefixes" would fail open
+ * on the next unlisted one instead.
+ *
+ * Zero I/O: every input (file paths + contents) is read by the adapter and
+ * passed in.
+ */
+
+export type PortabilitySourceFile = { path: string; content: string }
+
+export type PortabilityFinding = {
+  file: string
+  line: number
+  cited: string
+  message: string
+}
+
+/** `aeg-root/**` by default — what this repo's own package ships and every adopter installs read-only. */
+const DEFAULT_SHIPS_PREFIX = 'aeg-root/'
+
+/**
+ * Doctrine-relative (`roles/`, `contracts/`, `skills/`) and adopter-owned
+ * (`.github/`, `.vinaya/`, `.claude/`) top segments — the two portable
+ * classes measured in the task-234 corpus scan. `aeg-root/` itself is
+ * deliberately NOT a static entry here: it is always the CALLER-supplied
+ * `shipsPrefix`, checked dynamically in `isPortable` below, so an adopter
+ * who configures a non-default `doctrineRoot` gets that root treated as
+ * portable too — a static `'aeg-root/'` entry would falsely flag every one
+ * of that adopter's own self-citations as non-portable. A citation whose
+ * top segment falls outside this list (and isn't the ships prefix) is
+ * never assumed portable, however plausible it looks; it is a finding, and
+ * someone extends this list deliberately once its side of the
+ * classification is decided.
+ */
+const STATIC_PORTABLE_PREFIXES: readonly string[] = [
+  'roles/',
+  'contracts/',
+  'skills/',
+  '.github/',
+  '.vinaya/',
+  '.claude/',
+  // Not in the task-234 corpus-scan table, but verified while reading the
+  // corpus: `.git/hooks/*` and `.husky/*` are cited only as the pre-commit/
+  // pre-push hook locations every git repo (and every husky-adopting repo)
+  // genuinely has — adopter-owned by construction, the same class as
+  // `.github/`/`.vinaya/`/`.claude/` above.
+  '.git/',
+  '.husky/'
+]
+
+/**
+ * The three illustrative placeholders measured in the corpus — a
+ * `[path/inside/the/...]`-shaped fill-in-the-blank in a template, never a
+ * real citation. Exempted by literal, not by pattern, so a real path that
+ * happens to share a prefix with one of these is never accidentally waved
+ * through.
+ */
+const EXEMPT_LITERALS: ReadonlySet<string> = new Set([
+  'path/inside/the/shipped/diff.ts',
+  'path/inside/the/surface.ts',
+  'apps/x/specs/...'
+])
+
+/**
+ * A cited path, inline-backtick-delimited, shaped like a repo-relative
+ * path: starts with a word/dot/dash character (never `/` — that shape is a
+ * web route, e.g. `` `/docs/state-machine` ``, not a repo path), contains at
+ * least one `/`, and carries no character a URL or a prose fragment would
+ * (no `:`, no whitespace, no parens) — which also excludes a link like
+ * `` `https://vinaya.dev` `` without a separate URL-shaped exclusion.
+ */
+const CITED_PATH_PATTERN = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]*)+$/
+
+/**
+ * Top segments that are never a repo path, verified against every one of
+ * their occurrences in the real corpus rather than assumed: `origin/`/`refs/`
+ * are git-ref namespace (`origin/main`, `refs/pull/N/merge`), and `vinaya/`/
+ * `fix/` are this doctrine's own GitHub-label and branch-name-example
+ * conventions (`vinaya/blocked`, `fix/brief-gate-nontask`) — a citation kind
+ * this check does not judge at all, portable or not, the same way it never
+ * tries to also judge a forge number or a tranche slug.
+ *
+ * **A closed, tested set, not a growable escape hatch.** Excluding a top
+ * segment here means every citation under it is invisible to this check —
+ * never flagged, however non-portable it would otherwise be — so this set
+ * carries exactly the corpus-verified exceptions above and nothing else.
+ * `doctrine-portability.test.ts` locks its exact membership; an addition
+ * that doesn't also update that lock is a bug, not a silent expansion.
+ * Exported for that lock, not for callers to extend at runtime.
+ */
+export const NON_PATH_TOP_SEGMENTS: ReadonlySet<string> = new Set(['origin', 'refs', 'HEAD', 'vinaya', 'fix'])
+
+/** Every inline-backtick span in `content`, tested against `CITED_PATH_PATTERN`. */
+function extractCitedPaths(content: string): { cited: string; index: number }[] {
+  const found: { cited: string; index: number }[] = []
+  const spanPattern = /`([^`\n]+)`/g
+  let match: RegExpExecArray | null = spanPattern.exec(content)
+  while (match !== null) {
+    const cited = match[1] ?? ''
+    const topSegment = cited.slice(0, cited.indexOf('/'))
+    if (CITED_PATH_PATTERN.test(cited) && !NON_PATH_TOP_SEGMENTS.has(topSegment)) {
+      found.push({ cited, index: match.index })
+    }
+    match = spanPattern.exec(content)
+  }
+  return found
+}
+
+function lineAtIndex(content: string, index: number): number {
+  let line = 1
+  for (let i = 0; i < index; i++) {
+    if (content.charCodeAt(i) === 10) line++
+  }
+  return line
+}
+
+/**
+ * True iff `cited`'s top segment is portable: the caller-supplied
+ * `shipsPrefix` itself (doctrine citing its own tree, wherever that tree
+ * actually lives for this caller), or one of the static portable prefixes.
+ */
+function isPortable(cited: string, shipsPrefix: string): boolean {
+  if (cited.startsWith(shipsPrefix)) return true
+  return STATIC_PORTABLE_PREFIXES.some((prefix) => cited.startsWith(prefix))
+}
+
+/**
+ * Sweeps every file under `shipsPrefix` for a cited path whose top segment
+ * is not allow-listed portable. Files outside `shipsPrefix` are out of
+ * scope entirely — this check only judges what the shipped doctrine tree
+ * itself cites, never a repo's other source.
+ */
+export function checkDoctrinePortability(
+  files: readonly PortabilitySourceFile[],
+  shipsPrefix: string = DEFAULT_SHIPS_PREFIX
+): PortabilityFinding[] {
+  const findings: PortabilityFinding[] = []
+
+  for (const file of files) {
+    if (!file.path.startsWith(shipsPrefix)) continue
+
+    for (const { cited, index } of extractCitedPaths(file.content)) {
+      if (EXEMPT_LITERALS.has(cited)) continue
+      if (isPortable(cited, shipsPrefix)) continue
+      findings.push({
+        file: file.path,
+        line: lineAtIndex(file.content, index),
+        cited,
+        message: `cites "${cited}", a path that only exists in the authoring repository — not portable doctrine`
+      })
+    }
+  }
+
+  return findings
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/doctrine-source.ts

@@ -0,0 +1,23 @@
+/**
+ * The seam the pure derivation (`deriveDiagramModel`) consumes doctrine
+ * through, instead of reading `aeg-root/` paths directly. Doctrine is the raw
+ * markdown that governs the methodology — `enforcement.md`, the role files,
+ * the contract files. Implementations (file-backed today, package-bundled for
+ * adopters tomorrow) perform I/O and therefore live outside `aeg-core`
+ * (`apps/vinaya/sources`) — this package only defines the contract, so the
+ * library can be packaged for repos that have no `aeg-root/` of their own
+ *. Same discipline as `state-source.ts`: zero I/O here, async on the
+ * adapter so callers get one uniform type regardless of the backing store.
+ */
+export type DoctrineContent = {
+  /** Raw `enforcement.md` content. */
+  enforcement: string
+  /** Raw `roles/*.md` files (path + content). */
+  roles: Array<{ path: string; content: string }>
+  /** Raw `contracts/*.md` files (path + content). */
+  contracts: Array<{ path: string; content: string }>
+}
+
+export type DoctrineSource = {
+  getDoctrine(): Promise<DoctrineContent>
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/ensure-label.ts

@@ -0,0 +1,28 @@
+/**
+ * Idempotent label-minting (vinaya-label-hygiene-v1 task 1, #243) — the
+ * decision logic three call sites (`apps/cli/src/commands/audit.ts`,
+ * `bin/check-direct-main-push.ts`, `bin/dead-branch-audit.ts`) each
+ * reimplemented: does this label already exist on the forge, and if not,
+ * create it. Pure — no `gh` shell-outs here; each call site injects its own
+ * `listLabelNames`/`createLabel`, so this module stays agnostic to how a
+ * caller shells out (array-arg `execFileSync` vs. string `execSync`) and to
+ * whether a caller lets `gh` failures throw or swallows them — those are
+ * call-site error-handling policies this extraction does not change.
+ *
+ * Mints lazily, on first use, by design — never called to bootstrap the
+ * full label vocabulary (`@attalabs/aeg-forge-state`'s `labels.ts`) ahead of
+ * need.
+ */
+
+export type LabelExistenceIo = {
+  listLabelNames: (repoFlag: string) => string[]
+  createLabel: (repoFlag: string, name: string, description: string, color: string) => void
+}
+
+export const LABEL_COLOR = 'B60205'
+
+export function ensureLabelExists(repoFlag: string, name: string, description: string, io: LabelExistenceIo): void {
+  const existing = io.listLabelNames(repoFlag)
+  if (existing.includes(name)) return
+  io.createLabel(repoFlag, name, description, LABEL_COLOR)
+}