@attalabs/vinaya 0.19.0 → 0.19.1

package/README.md

@@ -23,6 +23,7 @@ npx @attalabs/vinaya init        # or: pnpm dlx / yarn dlx / bunx
 | `vinaya studio` | Launch Vinaya Studio. Inside a checkout that carries Studio's source (`apps/vinaya-studio/web` — it lives in the attalabs monorepo, not this repository) it runs the dev app; a published install runs its bundled standalone server instead, fetched from attalabs' published release artifact at publish time. `--port <n>` binds an exact port — see below. |
 | `vinaya milestone create --title <title> --body-file <path>` | Create a GitHub Milestone from a validated body. The title is free text, never parsed for a version — the description's optional `Release:` field is the sole authority for one. Refuses before any `gh` write when the goal is absent, `Release:` is present but malformed, or an `### Tranche intents` section (`- <slug>: <intent text>`) doesn't parse. `--validate-only` runs every check without writing; `--json` for the enveloped machine form. |
 | `vinaya milestone adopt --target <title> --slug <slug> [--slug <slug> ...]` | Move one or more existing tranches into a target Milestone: reattaches every Issue carrying each `vinaya/tranche:<slug>` label to `--target`, then closes (never deletes) each slug's old tranche-Milestone. Every fact is gathered and refused-or-passed as ONE batch before any write — an unknown slug, a slug whose label carries no Issues, a target that does not exist or is closed, or a slug already adopted into a different Milestone refuses the whole invocation, not just its own slug. `--validate-only` runs every check without writing; `--json` for the enveloped machine form. |
+| `vinaya quickstart [--yes] [--dry-run]` | Guided wizard that runs `init` → optional doc-owners bind → optional project registration → commit → `demo break` → `doctor` → `push` in sequence, prompting between steps. `--yes` forwards straight through to `init` and answers every one of quickstart's own prompts with its documented default (skip the two optional steps, run the refusal-then-fix proof, push) — no prompt is opened at all, so the command completes with no human at the keyboard rather than merely with stdin closed. `--dry-run` also forwards to `init` and stops immediately after its preview — nothing is installed, so no later step runs against an uninstalled repo. |
 
 ## Config
 
@@ -78,9 +79,25 @@ Two shapes deviate: a repo already using **husky** keeps its `.husky/` directory
 
 On that legacy `.git/hooks` layout, note where the hook actually lives: hooks are never per-worktree, so its real home is the main checkout's shared hooks directory (`git rev-parse --git-common-dir`), which from a linked worktree is outside that worktree's own root. `vinaya eject` follows the hook there and bounds the removal to that directory's `hooks/` subtree, rather than to the worktree root — so ejecting from a linked worktree strips the hook instead of leaving it armed. A canonically spelled block path resolving anywhere else is refused, and the refusal is whole-run: `eject` removes nothing at all rather than making a partial destructive pass. (The `.git/` test is byte-exact, so a non-canonical spelling takes the working-tree branch instead — nothing vinaya generates produces one.)
 
+## Agent-native entry points (`--agents`)
+
+`vinaya init` writes three agent-native entry points by default, one per vendor: `.agents/skills/vinaya-<role>/SKILL.md` (Agent skills, below), `.claude/commands/vinaya.md` (Claude Code command), and `.gemini/commands/vinaya.toml` (Gemini CLI command). Each one is a thin pointer that shells out to `vinaya doctrine --role <role>` at read time — there is exactly one source of role doctrine, never a copy baked into any of these files.
+
+`vinaya init --agents=<comma-list|all|none>` controls which of the three get written — `all` (the default) writes all three, `none` writes none, and a comma-separated list (e.g. `--agents=claude,gemini`) writes exactly the named vendors. There is no interactive prompt: `init` is scriptable/CI-safe today, and prompting would break that. The selection is persisted into `vinaya.config.json`'s `managed.agents` — `vinaya upgrade`/`vinaya doctor` read it back rather than re-deriving a default, so a repo initialized with a narrowed selection never has a later flagless `vinaya upgrade` silently add the other vendors' files, nor silently drop the recorded selection; a vendor left out is simply invisible to `vinaya doctor` rather than reported as "not installed". `vinaya eject` removes whichever of the three are actually owned, the same way it removes every other vinaya-managed artifact.
+
 ## Agent skills
 
-The emitter that will generate skill pointers under `.agents/skills/vinaya-<role>/SKILL.md`, for tools natively scanning `.agents/skills/` (Codex, Antigravity, Grok Build), is built — `vinaya init` does not call it yet. Each file, once wired, is a 3-line pointer delegating to `vinaya doctrine --role <role>` at read time. User-facing flag, `init`/`upgrade`/`eject`/`doctor` wiring, and the `--agents` selection flag land in #152.
+Generates skill pointers under `.agents/skills/vinaya-<role>/SKILL.md`, for tools natively scanning `.agents/skills/` (Codex, Antigravity, Grok Build) — one file per role discovered under `aeg-root/roles/*.md`, excluding `principal` (the one seat this doctrine never grants an agent). Each file is a 3-line pointer delegating to `vinaya doctrine --role <role>` at read time.
+
+## Gemini CLI command
+
+Generates `.gemini/commands/vinaya.toml`, Gemini CLI's own custom-command surface. It emits ONE parameterized command, invoked `/vinaya <role>`, whose `prompt` field embeds `!{vinaya doctrine --role {{args}}}`: Gemini CLI substitutes the typed role into `{{args}}`, shell-escaping it automatically, before running the shell block — and it always prompts the user to confirm the exact resolved command first, with no documented bypass. Role-argument validation stays in `vinaya doctrine --role` alone (`commands/doctrine.ts`), not duplicated here.
+
+## Claude Code command
+
+Generates a single parameterized `.claude/commands/vinaya.md`, invoked `/vinaya <role>`. The file uses Claude Code's `$ARGUMENTS` substitution to shell out to `vinaya doctrine --role "$ARGUMENTS"` at read time, scoped by `allowed-tools: Bash(vinaya doctrine *)` so it runs without a permission prompt.
+
+**Security note:** Claude Code substitutes `$ARGUMENTS` into the command as a raw, pre-shell text splice — the substitution happens before bash parses the line, so the role token can carry live shell syntax. Double-quoting (`"$ARGUMENTS"`) closes the `;`/`|`/`&&` class the substitution's own documented apostrophe bug demonstrates, but — verified empirically, not assumed — it does **not** close `$(...)`/backtick command substitution (still executes inside double quotes), and no quote character can be made airtight against this kind of splice at all: an attacker's token can always contain that same quote character, close it early, inject a command, then reopen a matching quote so the rest of the line still parses. `vinaya doctrine --role`'s own handling (`doctrine.ts`) validates whatever argument it actually receives against the exact set of role names live-discovered from `aeg-root/roles/*.md` and refuses anything else — that gate is real and load-bearing for its own scope, but an injected `$(...)` or quote-breakout command never reaches it as an argument; it runs at the shell level first. The actual remaining backstop is Claude Code's own `allowed-tools: Bash(vinaya doctrine *)` permission matcher refusing to auto-run a chained/injected command — a platform property outside this repo's control, unverified as of this writing. Do not describe this as fully closed in any future edit here or in the emitter; it is reduced, not closed.
 
 Custom checks register under `checks`, one entry per check. **Every key must be namespaced `<yourname>/<id>`** — exactly one `/`, both segments matching `[a-z0-9][a-z0-9-]*`, with `vinaya` reserved as a prefix:
 
@@ -101,6 +118,23 @@ The one exception is a key that exactly matches a **core** check id: that is an
 
 Glob scoping (`include`) is permitted; conditional logic (`if`/`unless`/`except`) is **never** part of this grammar — see the check-contract quick reference below for the full grammar and the error contract every registered `run` executable must honor.
 
+## Roles config
+
+Per-role override and additive-role registration works the same way `checks` does, under `vinaya.config.json`'s own `roles` key — one entry per role, each naming a `contract`: a markdown file, structurally validated against the same shape a bundled role doc carries (`role_id`, `description`, `actor`, `performs`, `refuses_when`, `summary` in frontmatter, plus `title` and `order`, plus a non-empty `## The short version` body section):
+
+```json
+{
+  "roles": {
+    "security": { "contract": "./roles/custom-security.md" },
+    "acme/qa-lead": { "contract": "./roles/qa-lead.md" }
+  }
+}
+```
+
+A key that exactly matches a **core** role id (`developer`, `security`, and the rest of the bundled doctrine roles) is an override — a **complete replacement**, never a frontmatter patch — whose contract's own `role_id` must equal that key exactly. Any other key must be namespaced `<yourname>/<id>`, same grammar as `checks`, and is additive — its contract's own `role_id` must equal the key's post-`/` segment exactly, and that render id must not collide with a core role id or another additive role's render id. Unlike `checks`, there is no grace period here: a malformed entry (a shape violation, a `role_id` mismatch, a collision, a bare unnamespaced key) fails closed immediately, since `roles` config has no legacy population a warn window would need to keep working. `contract` is a path, resolved relative to `vinaya.config.json`'s own directory — a bare filename with no `/` is rejected at load, the same discipline `checks.run`'s executable path does not need but a file **read** benefits from. Only registrable from a repo-local `vinaya.config.json`; a global `~/.vinaya/config.json`'s `roles` key is stripped at load time, since a role contract becomes agent-facing doctrine (`vinaya doctrine --role` hands it to a third-party agent tool as operating instructions).
+
+Run `vinaya check --plan` to see the resolved role registry before anything renders from it — a `RENDERS AS` column (the registry key and the role's own `role_id` differ once an additive entry is namespaced) and a `GATING` column (`core` for a `default`/`overridden` role, `inert` for an `additive` one — no core `ACTIONS` wiring exists for a render id core doctrine never declared).
+
 ## Check contract — quick reference
 
 Full field-by-field reference: [vinaya.attalabs.dev/docs/cli](https://vinaya.attalabs.dev/docs/cli). The short version — what an executable must do to be a valid check:

package/aeg-root/enforcement.md

@@ -117,12 +117,13 @@ Every pull request, on open and on every push, re-runs the same checks in CI:
 | G3 — no seventh way into GitHub | Ever discovered a backdoor that skipped all your checks? | ci | Re-checks that no route into GitHub exists beyond the ones the doctrine gates. | Every file making a GitHub-mutating call of the gated class (PR/Issue create, PR/Issue body/title edit, `gh api` create/edit, raw curl/wget writes) is named by some Ring-0 row's `implementation` — a mutating call outside that set would be an unguarded hole in the prevention model. (The class was originally defined by attalabs's `check-forge-gates.sh` tool-interception hook; this repo has no such hook — see the raw-API ring-0 row above — but the scan's definition of "mutating call" is unchanged.) | `packages/aeg-core/bin/verify-registry.ts` |
 | G4 — cited forge numbers resolve | Ever read a doc that cited a ticket number that didn't exist? | ci | Re-checks that every Issue and PR number cited in the docs resolves to a real one. | Every `#NNN` cited anywhere in this page's body is a real Issue or PR in the forge — a fabricated citation fails the build. **Currently scans nothing by design** (task 14): this page's body carries zero forge citations, since task 3 banned them from `aeg-root/**` as doctrine and the `reader-resolvable-prose` check (task 15) now enforces that ban directly. G4 is a standing guard against reintroduction, not a live proof of ongoing citation correctness — it fires the moment a `#NNN` reappears here and doesn't resolve, but has nothing to scan while the ban holds. Verified live: `packages/aeg-core/src/registry-checks.test.ts` appends a fabricated citation to this page's real content and asserts `checkG4` catches it. | `packages/aeg-core/bin/verify-registry.ts` |
 | G5 — role/contract integrity | Ever had a process doc reference a role that was never actually defined? | ci | Re-checks that every role and contract the doctrine references is really defined. | Every `aeg-root/contracts/*.md`'s `producer`/`consumer` names a real `role_id` from `aeg-root/roles/*.md`; every role's `performs`/`refuses_when` frontmatter is present and non-empty. | `packages/aeg-core/bin/verify-registry.ts` |
-| reader-resolvable-prose | Ever read a doc that assumed you already worked here? | ci | Re-checks that reader-facing doctrine and site pages don't cite a forge number/tranche slug the reader can't resolve, or use coined vocabulary without defining it. | Two mechanizable classes over every `aeg-root/**` doc and every public-site `(site)/**/page.tsx`, never `apps/*/specs/**` or a `CLAUDE.md` (this reader has this forge): unresolvable references (a bare forge number, or a `-vN`/legacy tranche slug — the same pattern shapes `retired-vocabulary.test.ts` proved, scoped wider here); and a coined term (`tranche`, `brief`, `forge`, `provenance`, `dispatch`, …) used with neither an inline definition nor a link to the glossary — the term list is derived live from `aeg-root/glossary.md`'s own entry headings, never hard-coded. NOT registered in `coreCheckRegistry()` — its scan hardcodes the attalabs monorepo's own doctrine layout and site paths, a scope-registration decision recorded in `apps/cli/src/checks/registry.ts` — so in this repo it runs only on direct invocation (`vinaya check reader-resolvable-prose`); it is part of neither the managed hooks nor `vinaya-checks.yml`. | `apps/cli/src/checks/bin/check-reader-resolvable-prose.ts` |
+| reader-resolvable-prose | Ever read a doc that assumed you already worked here? | ci | Re-checks that reader-facing doctrine and site pages don't cite a forge number/tranche slug the reader can't resolve, or use coined vocabulary without defining it. | Two mechanizable classes over every `<doctrineRoot>/**` doc and every configured reader-facing page, never `apps/*/specs/**` or a `CLAUDE.md` (this reader has this forge): unresolvable references (a bare forge number, or a `-vN`/legacy tranche slug — the same pattern shapes a sibling suite proved, scoped wider here); and a coined term (`tranche`, `brief`, `forge`, `provenance`, `dispatch`, …) used with neither an inline definition nor a link to the glossary — the term list is derived live from `<doctrineRoot>/glossary.md`'s own entry headings, never hard-coded. Registered in `coreCheckRegistry()` (task 7): its doctrine root, reader-facing globs, and legacy-slug corpus location are adopter-configurable via `vinaya.config.json`'s `proseGates` key, defaulting to this repo's own prior hardcoded shape (`doctrineRoot: "aeg-root"`, dormant reader-facing sweep) when unset. Part of `vinaya check --all` for every adopter; not part of the managed hooks. | `apps/cli/src/checks/bin/check-reader-resolvable-prose.ts` |
+| retired-vocabulary | Ever read a doc that described a mechanism as live after it was retired? | ci | Re-checks that no doctrine page claims a retired mechanism is still live. | The genuinely-retired half of a sibling suite's original scan — never the forge-number/tranche-slug citation half, which is `reader-resolvable-prose`'s own job and would double-report the identical match if duplicated here. Scoped to `<doctrineRoot>/**` only (the same `proseGates.doctrineRoot` key `reader-resolvable-prose` reads), not the whole adopter repo — this vocabulary means something only inside the shipped doctrine tree. Registered in `coreCheckRegistry()` (task 7), report-only like `reader-resolvable-prose`. | `apps/cli/src/checks/bin/check-retired-vocabulary.ts` |
 | No new on-disk state | Ever had a file and the forge disagree about the same fact? | ci | Blocks a diff that creates a new on-disk state file duplicating what the forge already derives. | No live per-tranche topology file appears under `aeg-root/tranches/` (a top-level file there fails on add or edit; under `completed/**` only genuinely NEW files are refused, so the legacy archives stay editable), and no new `*.tokens.md` appears anywhere — token figures live in the PR body, and the ledger row is appended post-merge. Status-aware (`git diff --name-status`), never fired by a deletion; a rename counts as an addition at its new path. The registered `no-disk-state` check runs the same `isNewDiskStateFile` predicate at ring 0 (the managed hooks) and here; this row names the standalone CLI shim of that gate. | `packages/aeg-core/bin/check-no-disk-state.ts` |
 
 **G-checks rollout (task 3):** G1/G2 ship report-only this tranche — they can only ever print an `info` finding, never fail CI, so pre-existing gaps (four orphan hooks, several orphan `bin/*.ts` CLIs found on first run) surface as visible debt without retroactively failing in-flight work. G3/G4/G5 are blocking from this tranche onward. G1 flips to blocking in a later, separately-dispatched task, once the report-only period has let the orphan backlog get cleaned up.
 
-**reader-resolvable-prose rollout (task 15):** ships report-only, same precedent as G1/G2 above — it can only ever print a `warning` finding, never fail CI (the check's own exit code always stays 0), so the real backlog this run surfaces (161 findings, all class 2, across `aeg-root` and the public site's `(site)` pages on the day this shipped) is visible debt rather than a wave of newly-red pull requests. A later, separately-dispatched task flips it to blocking once that backlog is cleared.
+**reader-resolvable-prose / retired-vocabulary rollout (task 15; task 7 registered both in `coreCheckRegistry()`):** both ship report-only, same precedent as G1/G2 above — each can only ever print a `warning` finding, never fail CI (the check's own exit code always stays `0`), so any real backlog surfaces as visible debt rather than a wave of newly-red pull requests (161 findings, all class 2, across `aeg-root` on the day `reader-resolvable-prose` first shipped). A later, separately-dispatched task flips either to blocking once its own backlog is cleared.
 
 Red CI is now unmergeable by any actor — the repository ruleset's `required_status_checks` rule carries `bypass_actors: []`, so the Principal has no ambient override either. The Principal's override paths are explicit and auditable instead: edit the ruleset itself, or apply an actor-verified `vinaya/waiver:review` label to skip the review gate specifically.
 

package/dist/checks/bin/check-body-bare-digits.js

@@ -566,6 +566,12 @@ function factsFromLegacyMilestone(milestone) {
     lifecycle: milestone.state === "closed" ? "complete" : "active"
   };
 }
+function resolveLegacyFacts(milestone, labelIssues) {
+  if (milestone.state === "closed" && labelIssues.length > 0) {
+    return { goal: milestone.description ?? "", lifecycle: lifecycleFromIssues(labelIssues) };
+  }
+  return factsFromLegacyMilestone(milestone);
+}
 function lifecycleFromIssues(issues) {
   if (issues.length === 0)
     return "planned";
@@ -582,9 +588,9 @@ function goalFromMilestones(milestones, slug) {
 function findMilestoneForSlug(owner, repo, slug) {
   const milestones = ghApiGet(`repos/${owner}/${repo}/milestones?state=all&per_page=100`);
   const legacy = matchesLegacyMilestone(milestones, slug);
-  if (legacy)
-    return factsFromLegacyMilestone(legacy);
   const issues = ghIssueListByLabel(owner, repo, trancheLabel(slug));
+  if (legacy)
+    return resolveLegacyFacts(legacy, issues);
   return { goal: goalFromMilestones(milestones, slug), lifecycle: lifecycleFromIssues(issues) };
 }
 
@@ -2771,16 +2777,18 @@ function checkDeadBranchPush(input) {
 }
 // ../../packages/aeg-core/src/reader-resolvable-prose.ts
 var SHIPS_PREFIX = "aeg-root/";
-var SHIPS_ARCHIVE_PREFIX = "aeg-root/tranches/completed/";
+function shipsArchivePrefix(shipsPrefix) {
+  return `${shipsPrefix}tranches/completed/`;
+}
 function isSpecFile2(path) {
   return path.startsWith("apps/") && path.includes("/specs/") && path.endsWith(".md");
 }
 function isClaudeMdFile(path) {
   return path === "CLAUDE.md" || path.endsWith("/CLAUDE.md");
 }
-function classifyProseFile(path, readerFacingPrefix, readerFacingSuffix) {
-  if (path.startsWith(SHIPS_PREFIX)) {
-    return path.startsWith(SHIPS_ARCHIVE_PREFIX) ? "internal" : "ships";
+function classifyProseFile(path, readerFacingPrefix, readerFacingSuffix, shipsPrefix = SHIPS_PREFIX) {
+  if (path.startsWith(shipsPrefix)) {
+    return path.startsWith(shipsArchivePrefix(shipsPrefix)) ? "internal" : "ships";
   }
   if (path.startsWith(readerFacingPrefix) && path.endsWith(readerFacingSuffix)) {
     return "reader-facing";
@@ -2815,7 +2823,7 @@ function legacySlugPattern(legacySlugs) {
   const alternation = legacySlugs.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
   return new RegExp(`(^|[^a-zA-Z0-9\\n-])(${alternation})([^a-zA-Z0-9\\n-]|$)`, "g");
 }
-function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs = []) {
+function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs = [], shipsPrefix = SHIPS_PREFIX) {
   const findings = [];
   const legacyPattern = legacySlugPattern(legacySlugs);
   const patterns = [
@@ -2824,7 +2832,7 @@ function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuff
     ...legacyPattern ? [{ pattern: legacyPattern, what: "an internal tranche slug", group: 2 }] : []
   ];
   for (const file of files) {
-    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix);
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix);
     if (!cls || !SWEPT_CLASSES.has(cls))
       continue;
     const scrubbed = stripNonProse(file.path, file.content);
@@ -2870,10 +2878,10 @@ function definesOrLinksGlossary(content, term) {
     return true;
   return /docs\/glossary|glossary\.md/i.test(content);
 }
-function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix) {
+function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, shipsPrefix = SHIPS_PREFIX) {
   const findings = [];
   for (const file of files) {
-    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix);
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix);
     if (!cls || !SWEPT_CLASSES.has(cls))
       continue;
     const scrubbed = stripNonProse(file.path, file.content);
@@ -2892,10 +2900,10 @@ function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, read
   }
   return findings;
 }
-function checkReaderResolvableProse(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, legacySlugs = []) {
+function checkReaderResolvableProse(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, legacySlugs = [], shipsPrefix = SHIPS_PREFIX) {
   return [
-    ...checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs),
-    ...checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix)
+    ...checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs, shipsPrefix),
+    ...checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
   ];
 }
 function parseGlossaryTerms(glossaryContent) {
@@ -2909,6 +2917,101 @@ function parseGlossaryTerms(glossaryContent) {
   }
   return terms;
 }
+// ../../packages/aeg-core/src/retired-vocabulary.ts
+var RETIRED_PATTERNS = [
+  String.raw`\bD-[0-9]{3}\b`,
+  "D-(###|NNN|nnn|xxx)",
+  "decision (entry|logged)",
+  "decision-log entry",
+  "decision log entry",
+  "decision log(s|ged|ging)?([^a-z]|$)",
+  "decision-log",
+  "decision entr",
+  "decisions? (are |is )?logged",
+  "log entries",
+  String.raw`decisions\.md`,
+  "decisions-legacy",
+  "CONTRADICTION",
+  "assumes Tier 3",
+  "Lock: ?YES",
+  "Lock: ?NO",
+  "lock approvals?",
+  "approves locks",
+  "Conforms to lock",
+  "Challenges lock",
+  "checkDecisionNumbersFresh",
+  String.raw`roles/team-leader\.md`,
+  String.raw`\(,`,
+  String.raw`,\)`,
+  String.raw`\(\.\)`
+];
+var RETIRED_EXEMPT_SUBSTRINGS = [
+  "docs/decisions-legacy.md",
+  "apps/herald-ai/docs/",
+  "apps/vada-ai/docs/",
+  "aeg-root/tranches/completed/",
+  "packages/aeg-core/src/docs/published-prose",
+  "packages/aeg-core/src/retired-vocabulary.test.ts",
+  "packages/aeg-core/src/retired-vocabulary.ts",
+  "/fixtures/",
+  "/node_modules/",
+  "/.next/",
+  "/.turbo/"
+];
+var PATTERN_EXEMPT = {
+  [String.raw`\bD-[0-9]{3}\b`]: ["./CLAUDE.md"],
+  [String.raw`decisions\.md`]: [
+    "docs-index.md",
+    "apps/vada-ai/specs/legacy/README.md",
+    "apps/vada-ai/specs/vada-product-spec.md",
+    "apps/vada-ai/web/CLAUDE.md",
+    "apps/vada-ai/CLAUDE.md"
+  ],
+  "decisions-legacy": [
+    "packages/aeg-core/src/file-classify.ts",
+    "packages/aeg-core/src/file-classify.test.ts",
+    "packages/aeg-core/src/pr-tier.test.ts",
+    "docs-index.md",
+    ".claude/skills/database/SKILL.md",
+    ".claude/skills/vada-architecture/SKILL.md",
+    "apps/vada-ai/specs/vada-byok-principles.md",
+    "apps/vada-ai/web/CLAUDE.md",
+    "apps/vada-ai/CLAUDE.md"
+  ],
+  CONTRADICTION: ["apps/vada-ai/specs/vada-reviewers-spec.md"]
+};
+function lineNumbers(content, pattern) {
+  const out = [];
+  const lines = content.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    if (pattern.test(lines[i] ?? ""))
+      out.push(i + 1);
+  }
+  return out;
+}
+function scanRetiredVocabulary(files) {
+  const findings = [];
+  for (const file of files) {
+    if (RETIRED_EXEMPT_SUBSTRINGS.some((e) => file.path.includes(e)))
+      continue;
+    for (const pattern of RETIRED_PATTERNS) {
+      const patternExempt = PATTERN_EXEMPT[pattern] ?? [];
+      if (patternExempt.some((e) => file.path.includes(e)))
+        continue;
+      const re = new RegExp(pattern);
+      for (const line of lineNumbers(file.content, re)) {
+        findings.push({
+          file: file.path,
+          line,
+          pattern,
+          message: `claims a retired AEG mechanism is still live (matches /${pattern}/)`
+        });
+      }
+    }
+  }
+  return findings;
+}
 // ../../packages/aeg-core/src/dispatch-gate.ts
 function isHandClosedByRecognizedPrincipal(dep, principalAllowlist) {
   return dep.issueState === "closed" && dep.stateReason === "completed" && isPrincipal(dep.closedByActor ?? null, principalAllowlist);
@@ -3164,9 +3267,15 @@ function evaluateTestPlanGate(body, branch) {
 }
 // src/lib/config.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
+
+// src/lib/agent-vendors.ts
+var AGENT_VENDORS = ["skills", "claude", "gemini"];
+
+// src/lib/config.ts
 var EnvEntrySchema = z.union([
   z.literal(true),
   z.object({ optional: z.literal(true) }),
@@ -3205,6 +3314,11 @@ var CheckEntrySchema = z.object({
     }
   }
 });
+var RoleEntrySchema = z.object({
+  contract: z.string().refine((p) => p.includes("/"), {
+    message: 'must be a path (contain at least one "/"), not a bare filename'
+  })
+});
 var BRIEF_BUILTINS = [
   "tier",
   "testPlan",
@@ -3253,7 +3367,8 @@ var ManagedManifestSchema = z.object({
   version: z.number().int().positive(),
   files: z.array(SafeRepoRelPath),
   blocks: z.array(ManagedBlockRecordSchema),
-  labels: z.array(z.string())
+  labels: z.array(z.string()),
+  agents: z.array(z.enum(AGENT_VENDORS)).optional()
 });
 var VinayaConfigSchema = z.object({
   rings: z.object({
@@ -3261,16 +3376,79 @@ var VinayaConfigSchema = z.object({
     ring2_asyncAudits: z.boolean()
   }).optional(),
   checks: z.record(z.string(), CheckEntrySchema).optional(),
+  roles: z.record(z.string(), RoleEntrySchema).optional(),
   briefSchema: BriefSchemaSchema.optional(),
   managed: ManagedManifestSchema.optional(),
   principals: z.array(z.string()).min(1).optional(),
   releaseActor: z.string().min(1).optional(),
   ci: z.object({ setup: z.string().min(1) }).optional(),
-  blastRadius: z.object({ extraDomains: z.array(z.string()).optional() }).optional()
+  blastRadius: z.object({ extraDomains: z.array(z.string()).optional() }).optional(),
+  proseGates: z.object({
+    doctrineRoot: z.string().min(1).optional(),
+    readerFacingPrefix: z.string().min(1).optional(),
+    readerFacingSuffix: z.string().min(1).optional(),
+    legacySlugDir: z.string().min(1).optional()
+  }).optional()
 });
 var GLOBAL_VINAYA_HOME = join(homedir(), ".vinaya");
 var GLOBAL_CONFIG_PATH = join(GLOBAL_VINAYA_HOME, "config.json");
 var LOCAL_CONFIG_FILENAME = "vinaya.config.json";
+function findLocalConfig() {
+  let dir = process.cwd();
+  while (true) {
+    const candidate = join(dir, LOCAL_CONFIG_FILENAME);
+    if (existsSync(candidate))
+      return candidate;
+    if (existsSync(join(dir, ".git")))
+      return null;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function configPath() {
+  const local = findLocalConfig();
+  if (local)
+    return local;
+  if (existsSync(GLOBAL_CONFIG_PATH))
+    return GLOBAL_CONFIG_PATH;
+  return null;
+}
+function globalChecksIgnoredWarning(path) {
+  return `${path}: "checks" registration in the global config is ignored — checks may only be registered from a repo-local vinaya.config.json.`;
+}
+function globalPrincipalsIgnoredWarning(path) {
+  return `${path}: "principals" in the global config is ignored — principals may only be declared from a repo-local vinaya.config.json.`;
+}
+function globalRolesIgnoredWarning(path) {
+  return `${path}: "roles" registration in the global config is ignored — roles may only be registered from a repo-local vinaya.config.json.`;
+}
+function globalReleaseActorIgnoredWarning(path) {
+  return `${path}: "releaseActor" in the global config is ignored — releaseActor may only be declared from a repo-local vinaya.config.json.`;
+}
+function stripGlobalOnlyKeys(config, path) {
+  if (path !== GLOBAL_CONFIG_PATH)
+    return config;
+  let result = config;
+  if (result.checks && Object.keys(result.checks).length > 0) {
+    console.error(`⚠ ${globalChecksIgnoredWarning(path)}`);
+    result = { ...result, checks: undefined };
+  }
+  if (result.roles && Object.keys(result.roles).length > 0) {
+    console.error(`⚠ ${globalRolesIgnoredWarning(path)}`);
+    result = { ...result, roles: undefined };
+  }
+  if (result.principals && result.principals.length > 0) {
+    console.error(`⚠ ${globalPrincipalsIgnoredWarning(path)}`);
+    result = { ...result, principals: undefined };
+  }
+  if (result.releaseActor) {
+    console.error(`⚠ ${globalReleaseActorIgnoredWarning(path)}`);
+    result = { ...result, releaseActor: undefined };
+  }
+  return result;
+}
 function resolvePrincipalAllowlist(config) {
   return config?.principals ?? PRINCIPAL_ALLOWLIST;
 }
@@ -3343,6 +3521,17 @@ function loadTrustAnchorConfig(fetcher = ghFetchTrustAnchorConfig) {
     return null;
   }
 }
+function loadConfig() {
+  const path = configPath();
+  if (!path)
+    return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    return stripGlobalOnlyKeys(VinayaConfigSchema.parse(raw), path);
+  } catch {
+    return null;
+  }
+}
 
 // src/checks/contract.ts
 var CHECK_SCHEMA_VERSION = 1;

package/dist/checks/bin/check-branch-topology.js

@@ -565,6 +565,12 @@ function factsFromLegacyMilestone(milestone) {
     lifecycle: milestone.state === "closed" ? "complete" : "active"
   };
 }
+function resolveLegacyFacts(milestone, labelIssues) {
+  if (milestone.state === "closed" && labelIssues.length > 0) {
+    return { goal: milestone.description ?? "", lifecycle: lifecycleFromIssues(labelIssues) };
+  }
+  return factsFromLegacyMilestone(milestone);
+}
 function lifecycleFromIssues(issues) {
   if (issues.length === 0)
     return "planned";
@@ -581,9 +587,9 @@ function goalFromMilestones(milestones, slug) {
 function findMilestoneForSlug(owner, repo, slug) {
   const milestones = ghApiGet(`repos/${owner}/${repo}/milestones?state=all&per_page=100`);
   const legacy = matchesLegacyMilestone(milestones, slug);
-  if (legacy)
-    return factsFromLegacyMilestone(legacy);
   const issues = ghIssueListByLabel(owner, repo, trancheLabel(slug));
+  if (legacy)
+    return resolveLegacyFacts(legacy, issues);
   return { goal: goalFromMilestones(milestones, slug), lifecycle: lifecycleFromIssues(issues) };
 }
 
@@ -2770,16 +2776,18 @@ function checkDeadBranchPush(input) {
 }
 // ../../packages/aeg-core/src/reader-resolvable-prose.ts
 var SHIPS_PREFIX = "aeg-root/";
-var SHIPS_ARCHIVE_PREFIX = "aeg-root/tranches/completed/";
+function shipsArchivePrefix(shipsPrefix) {
+  return `${shipsPrefix}tranches/completed/`;
+}
 function isSpecFile2(path) {
   return path.startsWith("apps/") && path.includes("/specs/") && path.endsWith(".md");
 }
 function isClaudeMdFile(path) {
   return path === "CLAUDE.md" || path.endsWith("/CLAUDE.md");
 }
-function classifyProseFile(path, readerFacingPrefix, readerFacingSuffix) {
-  if (path.startsWith(SHIPS_PREFIX)) {
-    return path.startsWith(SHIPS_ARCHIVE_PREFIX) ? "internal" : "ships";
+function classifyProseFile(path, readerFacingPrefix, readerFacingSuffix, shipsPrefix = SHIPS_PREFIX) {
+  if (path.startsWith(shipsPrefix)) {
+    return path.startsWith(shipsArchivePrefix(shipsPrefix)) ? "internal" : "ships";
   }
   if (path.startsWith(readerFacingPrefix) && path.endsWith(readerFacingSuffix)) {
     return "reader-facing";
@@ -2814,7 +2822,7 @@ function legacySlugPattern(legacySlugs) {
   const alternation = legacySlugs.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
   return new RegExp(`(^|[^a-zA-Z0-9\\n-])(${alternation})([^a-zA-Z0-9\\n-]|$)`, "g");
 }
-function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs = []) {
+function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs = [], shipsPrefix = SHIPS_PREFIX) {
   const findings = [];
   const legacyPattern = legacySlugPattern(legacySlugs);
   const patterns = [
@@ -2823,7 +2831,7 @@ function checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuff
     ...legacyPattern ? [{ pattern: legacyPattern, what: "an internal tranche slug", group: 2 }] : []
   ];
   for (const file of files) {
-    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix);
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix);
     if (!cls || !SWEPT_CLASSES.has(cls))
       continue;
     const scrubbed = stripNonProse(file.path, file.content);
@@ -2869,10 +2877,10 @@ function definesOrLinksGlossary(content, term) {
     return true;
   return /docs\/glossary|glossary\.md/i.test(content);
 }
-function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix) {
+function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, shipsPrefix = SHIPS_PREFIX) {
   const findings = [];
   for (const file of files) {
-    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix);
+    const cls = classifyProseFile(file.path, readerFacingPrefix, readerFacingSuffix, shipsPrefix);
     if (!cls || !SWEPT_CLASSES.has(cls))
       continue;
     const scrubbed = stripNonProse(file.path, file.content);
@@ -2891,10 +2899,10 @@ function checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, read
   }
   return findings;
 }
-function checkReaderResolvableProse(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, legacySlugs = []) {
+function checkReaderResolvableProse(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, legacySlugs = [], shipsPrefix = SHIPS_PREFIX) {
   return [
-    ...checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs),
-    ...checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix)
+    ...checkUnresolvableReferences(files, readerFacingPrefix, readerFacingSuffix, legacySlugs, shipsPrefix),
+    ...checkUndefinedVocabulary(files, glossaryTerms, readerFacingPrefix, readerFacingSuffix, shipsPrefix)
   ];
 }
 function parseGlossaryTerms(glossaryContent) {
@@ -2908,6 +2916,101 @@ function parseGlossaryTerms(glossaryContent) {
   }
   return terms;
 }
+// ../../packages/aeg-core/src/retired-vocabulary.ts
+var RETIRED_PATTERNS = [
+  String.raw`\bD-[0-9]{3}\b`,
+  "D-(###|NNN|nnn|xxx)",
+  "decision (entry|logged)",
+  "decision-log entry",
+  "decision log entry",
+  "decision log(s|ged|ging)?([^a-z]|$)",
+  "decision-log",
+  "decision entr",
+  "decisions? (are |is )?logged",
+  "log entries",
+  String.raw`decisions\.md`,
+  "decisions-legacy",
+  "CONTRADICTION",
+  "assumes Tier 3",
+  "Lock: ?YES",
+  "Lock: ?NO",
+  "lock approvals?",
+  "approves locks",
+  "Conforms to lock",
+  "Challenges lock",
+  "checkDecisionNumbersFresh",
+  String.raw`roles/team-leader\.md`,
+  String.raw`\(,`,
+  String.raw`,\)`,
+  String.raw`\(\.\)`
+];
+var RETIRED_EXEMPT_SUBSTRINGS = [
+  "docs/decisions-legacy.md",
+  "apps/herald-ai/docs/",
+  "apps/vada-ai/docs/",
+  "aeg-root/tranches/completed/",
+  "packages/aeg-core/src/docs/published-prose",
+  "packages/aeg-core/src/retired-vocabulary.test.ts",
+  "packages/aeg-core/src/retired-vocabulary.ts",
+  "/fixtures/",
+  "/node_modules/",
+  "/.next/",
+  "/.turbo/"
+];
+var PATTERN_EXEMPT = {
+  [String.raw`\bD-[0-9]{3}\b`]: ["./CLAUDE.md"],
+  [String.raw`decisions\.md`]: [
+    "docs-index.md",
+    "apps/vada-ai/specs/legacy/README.md",
+    "apps/vada-ai/specs/vada-product-spec.md",
+    "apps/vada-ai/web/CLAUDE.md",
+    "apps/vada-ai/CLAUDE.md"
+  ],
+  "decisions-legacy": [
+    "packages/aeg-core/src/file-classify.ts",
+    "packages/aeg-core/src/file-classify.test.ts",
+    "packages/aeg-core/src/pr-tier.test.ts",
+    "docs-index.md",
+    ".claude/skills/database/SKILL.md",
+    ".claude/skills/vada-architecture/SKILL.md",
+    "apps/vada-ai/specs/vada-byok-principles.md",
+    "apps/vada-ai/web/CLAUDE.md",
+    "apps/vada-ai/CLAUDE.md"
+  ],
+  CONTRADICTION: ["apps/vada-ai/specs/vada-reviewers-spec.md"]
+};
+function lineNumbers(content, pattern) {
+  const out = [];
+  const lines = content.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    if (pattern.test(lines[i] ?? ""))
+      out.push(i + 1);
+  }
+  return out;
+}
+function scanRetiredVocabulary(files) {
+  const findings = [];
+  for (const file of files) {
+    if (RETIRED_EXEMPT_SUBSTRINGS.some((e) => file.path.includes(e)))
+      continue;
+    for (const pattern of RETIRED_PATTERNS) {
+      const patternExempt = PATTERN_EXEMPT[pattern] ?? [];
+      if (patternExempt.some((e) => file.path.includes(e)))
+        continue;
+      const re = new RegExp(pattern);
+      for (const line of lineNumbers(file.content, re)) {
+        findings.push({
+          file: file.path,
+          line,
+          pattern,
+          message: `claims a retired AEG mechanism is still live (matches /${pattern}/)`
+        });
+      }
+    }
+  }
+  return findings;
+}
 // ../../packages/aeg-core/src/dispatch-gate.ts
 function isHandClosedByRecognizedPrincipal(dep, principalAllowlist) {
   return dep.issueState === "closed" && dep.stateReason === "completed" && isPrincipal(dep.closedByActor ?? null, principalAllowlist);