@attalabs/vinaya 0.4.3 → 0.4.4

package/dist/index.js

@@ -532,6 +532,27 @@ function parsePremiseBlock(prBody) {
   return assertions;
 }
 
+// ../../../packages/aeg-core/src/test-plan-section.ts
+var HEADING_FORM_RE = /^#{1,4}[ \t]*(?:\d+[a-z]?\.[ \t]*)?\*{0,2}Test Plan\*{0,2}[ \t]*$/im;
+var INLINE_FORM_RE = /^[ \t]*\*{0,2}Test Plan:?\*{0,2}/im;
+var NEXT_SECTION_RE = /\n(?:#{1,3}[ \t]|\*\*[A-Z][^*\n]*:\*\*)/;
+function locateTestPlanSection(body) {
+  const region = anchoredRegion(body, "TEST-PLAN");
+  if (region !== null)
+    return { found: true, section: region };
+  const headingMatch = HEADING_FORM_RE.exec(body);
+  const match = headingMatch ?? INLINE_FORM_RE.exec(body);
+  if (!match || match.index === undefined)
+    return { found: false };
+  const sectionBody = body.slice(match.index);
+  const firstLineEnd = sectionBody.indexOf(`
+`);
+  const searchFrom = firstLineEnd === -1 ? sectionBody.length : firstLineEnd + 1;
+  const nextMatch = sectionBody.slice(searchFrom).match(NEXT_SECTION_RE);
+  const sectionEnd = nextMatch ? searchFrom + (nextMatch.index ?? 0) : sectionBody.length;
+  return { found: true, section: sectionBody.slice(0, sectionEnd) };
+}
+
 // ../../../packages/aeg-core/src/brief-validation.ts
 function headerRegion(prBody) {
   const m = prBody.match(/^##\s/m);
@@ -570,10 +591,15 @@ function checkTierField(prBody, readTier) {
   };
 }
 var TEST_PLAN_UNIT_TESTS_ONLY_RE = /(?:\*\*)?Test Plan(?:\*\*)?\s*:\s*(?:\*\*)?\s*unit-tests-only/i;
+function testPlanRegion(prBody) {
+  const located = locateTestPlanSection(prBody);
+  return located.found ? located.section : prBody;
+}
 function checkTestPlan(prBody) {
-  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/\*\*\[(?:agent|principal)\]\*\*/.test(prBody))
+  if (/\*\*\[(?:agent|principal)\]\*\*/.test(region))
     return { status: "pass", errors: [] };
   return {
     status: "fail",
@@ -583,9 +609,10 @@ function checkTestPlan(prBody) {
   };
 }
 function checkTestPlanExclusivity(prBody) {
-  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(prBody))
+  const region = testPlanRegion(prBody);
+  if (!TEST_PLAN_UNIT_TESTS_ONLY_RE.test(region))
     return { status: "pass", errors: [] };
-  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(prBody)) {
+  if (/^-\s*\[[ xX]\]\s*\*{2}\[(?:agent|principal)\]\*{2}/im.test(region)) {
     return {
       status: "fail",
       errors: [
@@ -596,8 +623,9 @@ function checkTestPlanExclusivity(prBody) {
   return { status: "pass", errors: [] };
 }
 function checkPrincipalPlaceholder(prBody) {
+  const region = testPlanRegion(prBody);
   const lineRe = /^-\s*\[[ xX]\]\s*\*{2}\[principal\]\*{2}(.*)$/gim;
-  for (const m of prBody.matchAll(lineRe)) {
+  for (const m of region.matchAll(lineRe)) {
     const content = m[1] ?? "";
     if (/^\s*None\b/i.test(content)) {
       return {
@@ -1543,7 +1571,10 @@ function coreCheckRegistry() {
         PR_BODY: { optional: true },
         PR_BODY_FILE: { optional: true },
         PR_LABELS: { optional: true },
-        WAIVER_LABEL_ACTOR: { optional: true }
+        WAIVER_LABEL_ACTOR: { optional: true },
+        GITHUB_REPOSITORY: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1575,6 +1606,7 @@ function coreCheckRegistry() {
       run: bin("check-closes-n"),
       scope: "diff",
       timeoutMs: 15000,
+      requiresOpenPr: true,
       env: {
         BRANCH: { optional: true },
         PR_BODY: { optional: true },
@@ -1600,6 +1632,7 @@ function coreCheckRegistry() {
       run: bin("check-test-plan"),
       scope: "diff",
       timeoutMs: 15000,
+      requiresOpenPr: true,
       env: {
         PR_BODY: { optional: true },
         BRANCH: { optional: true }
@@ -1631,6 +1664,7 @@ function coreCheckRegistry() {
       env: {
         BRANCH: { optional: true },
         PR_NUMBER: { optional: true },
+        GITHUB_REPOSITORY: { optional: true },
         GITHUB_TOKEN: { optional: true },
         GH_TOKEN: { optional: true }
       }
@@ -1681,7 +1715,10 @@ function coreCheckRegistry() {
         PR_BODY: { optional: true },
         PR_BODY_FILE: { optional: true },
         PR_LABELS: { optional: true },
-        WAIVER_LABEL_ACTOR: { optional: true }
+        WAIVER_LABEL_ACTOR: { optional: true },
+        GITHUB_REPOSITORY: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1760,6 +1797,8 @@ function isCheckError(value) {
   return v.schema === CHECK_SCHEMA_VERSION && typeof v.check === "string" && (v.severity === "error" || v.severity === "warning") && typeof v.message === "string" && typeof v.agent_recovery_prompt === "string";
 }
 function shouldSkip(spec, opts) {
+  if (opts.localOnly && spec.requiresOpenPr)
+    return true;
   if (spec.scope !== "diff")
     return false;
   if (!opts.diffOnly)
@@ -2020,7 +2059,8 @@ var CheckEntrySchema = z.object({
   include: z.array(z.string()).optional(),
   args: z.array(z.string()).optional(),
   timeoutMs: z.number().optional(),
-  env: z.record(z.string(), EnvEntrySchema).optional()
+  env: z.record(z.string(), EnvEntrySchema).optional(),
+  requiresOpenPr: z.boolean().optional()
 }).superRefine((entry2, ctx) => {
   if (!entry2.env)
     return;
@@ -2127,7 +2167,8 @@ var VinayaConfigSchema = z.object({
   }).optional(),
   checks: z.record(z.string(), CheckEntrySchema).optional(),
   briefSchema: BriefSchemaSchema.optional(),
-  managed: ManagedManifestSchema.optional()
+  managed: ManagedManifestSchema.optional(),
+  principals: z.array(z.string()).min(1).optional()
 });
 var GLOBAL_VINAYA_HOME = join4(homedir(), ".vinaya");
 var GLOBAL_CONFIG_PATH = join4(GLOBAL_VINAYA_HOME, "config.json");
@@ -2155,11 +2196,22 @@ function configPath() {
 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 stripGlobalChecks(config, path) {
-  if (path !== GLOBAL_CONFIG_PATH || !config.checks || Object.keys(config.checks).length === 0)
+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 stripGlobalOnlyKeys(config, path) {
+  if (path !== GLOBAL_CONFIG_PATH)
     return config;
-  console.error(`⚠ ${globalChecksIgnoredWarning(path)}`);
-  return { ...config, checks: undefined };
+  let result = config;
+  if (result.checks && Object.keys(result.checks).length > 0) {
+    console.error(`⚠ ${globalChecksIgnoredWarning(path)}`);
+    result = { ...result, checks: undefined };
+  }
+  if (result.principals && result.principals.length > 0) {
+    console.error(`⚠ ${globalPrincipalsIgnoredWarning(path)}`);
+    result = { ...result, principals: undefined };
+  }
+  return result;
 }
 function loadConfigChecked() {
   const path = configPath();
@@ -2176,7 +2228,7 @@ function loadConfigChecked() {
     const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
     return { ok: false, path, error: detail };
   }
-  return { ok: true, config: stripGlobalChecks(parsed.data, path) };
+  return { ok: true, config: stripGlobalOnlyKeys(parsed.data, path) };
 }
 
 // src/commands/check.ts
@@ -2301,6 +2353,7 @@ function printClassificationWarnings(configChecks) {
 async function checkCommand(args) {
   const jsonOutput = args.includes("--json");
   const diffOnly = args.includes("--diff-only");
+  const localOnly = args.includes("--local");
   const requestedParallel = parseParallel(args);
   const allRequested = args.includes("--all");
   const planRequested = args.includes("--plan");
@@ -2318,7 +2371,7 @@ async function checkCommand(args) {
     process.exit(result.failures.length > 0 ? 1 : 0);
   }
   if (!allRequested && !requestedName) {
-    console.error("Usage: vinaya check <name> | --all | --plan [--json] [--diff-only] [--parallel[=n]]");
+    console.error("Usage: vinaya check <name> | --all | --plan [--json] [--diff-only] [--local] [--parallel[=n]]");
     process.exit(2);
   }
   const { specs: customSpecs, errorOutcome, checks: configChecks } = customSpecsFromConfig();
@@ -2333,7 +2386,8 @@ async function checkCommand(args) {
     parallel: requestedParallel ?? defaultParallelism(),
     diffOnly,
     changedFiles: changed,
-    defaultTimeoutMs: 30000
+    defaultTimeoutMs: 30000,
+    localOnly
   }) : [];
   const allOutcomes = errorOutcome ? [...outcomes, errorOutcome] : outcomes;
   for (const o of allOutcomes) {
@@ -2566,8 +2620,9 @@ async function demoBreakCommand(args) {
 }
 
 // src/commands/doctor.ts
+import { execFileSync as execFileSync6 } from "node:child_process";
 import { existsSync as existsSync8, readFileSync as readFileSync6, statSync } from "node:fs";
-import { join as join8 } from "node:path";
+import { isAbsolute as isAbsolute2, join as join8 } from "node:path";
 
 // src/lib/artifacts.ts
 import { readFileSync as readFileSync3 } from "node:fs";
@@ -2629,6 +2684,11 @@ jobs:
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: \${{ github.event.pull_request.number }}
+          # PR_BODY is what makes test-plan/closes-n EVALUATE: neither check
+          # fetches the body itself (both read \`process.env.PR_BODY\` only) —
+          # without it they read "no body — nothing to check" and pass
+          # vacuously regardless of the PR's real content, on every run.
+          PR_BODY: \${{ github.event.pull_request.body }}
           BRANCH: \${{ github.head_ref }}
         run: npx --yes @attalabs/vinaya check --all --diff-only
 `;
@@ -2675,6 +2735,10 @@ jobs:
           # it the adapter reads "no PR yet — local dev" and exits 0, and
           # the gate is green regardless of review state.
           PR_NUMBER: \${{ github.event.pull_request.number }}
+          # Same PR_BODY gap as vinaya-checks.yml — this job also runs
+          # \`check --all\` (test-plan/closes-n included), so it needs the
+          # same wiring or those two checks pass vacuously here too.
+          PR_BODY: \${{ github.event.pull_request.body }}
           BRANCH: \${{ github.head_ref }}
         run: npx --yes @attalabs/vinaya check --all
 `;
@@ -2861,11 +2925,11 @@ function ownVersion() {
 function preCommitBody() {
   return `# Vinaya commit-time gate. Runs the deterministic checks over your staged
 # diff before the commit lands.
-npx --yes @attalabs/vinaya@${ownVersion()} check --all --diff-only || exit 1`;
+npx --yes @attalabs/vinaya@${ownVersion()} check --all --diff-only --local || exit 1`;
 }
 function prePushBody() {
   return `# Vinaya pre-push gate. Runs branch/dispatch checks before the push leaves.
-npx --yes @attalabs/vinaya@${ownVersion()} check --all || exit 1`;
+npx --yes @attalabs/vinaya@${ownVersion()} check --all --local || exit 1`;
 }
 function doctrinePointer() {
   const doctrineRoot = join6(packageRoot(import.meta.url), "aeg-root");
@@ -3446,6 +3510,19 @@ function labelForPath(path) {
     return "doctrine-pointer";
   return "workflows";
 }
+function resolveManagedBlockPath(repoRoot, opPath) {
+  if (!opPath.startsWith(".git/"))
+    return join8(repoRoot, opPath);
+  try {
+    const commonDir = execFileSync6("git", ["-C", repoRoot, "rev-parse", "--git-common-dir"], {
+      encoding: "utf8"
+    }).trim();
+    const gitDir = isAbsolute2(commonDir) ? commonDir : join8(repoRoot, commonDir);
+    return join8(gitDir, opPath.slice(".git/".length));
+  } catch {
+    return join8(repoRoot, opPath);
+  }
+}
 function diagnoseInstall(repoRoot, ctx, manifest) {
   const findings = [];
   let hasDrift = false;
@@ -3479,7 +3556,7 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
       }
     } else if (op.kind === "managed-block") {
       const check = "hooks";
-      const abs2 = join8(repoRoot, op.path);
+      const abs2 = resolveManagedBlockPath(repoRoot, op.path);
       const owned = ownedBlocks.has(blockKey(op.path, op.marker));
       if (!existsSync8(abs2)) {
         findings.push(owned ? error(check, `${op.path} is missing — likely a fresh clone (raw git hooks aren't tracked by git). Run \`vinaya upgrade\` to restore it.`) : info(check, `${op.path} is not installed.`));
@@ -4030,7 +4107,7 @@ async function initProductCommand(args) {
 }
 
 // src/commands/issue.ts
-import { execFileSync as execFileSync6 } from "node:child_process";
+import { execFileSync as execFileSync7 } from "node:child_process";
 
 // src/lib/forge-write.ts
 import { mkdtempSync, rmSync as rmSync3, writeFileSync as writeFileSync6 } from "node:fs";
@@ -4243,7 +4320,7 @@ function locateBodyOrRefuse(ghArgs, retryCommand) {
 function fetchForgeLabels(issueRef) {
   let out;
   try {
-    out = execFileSync6("gh", ["issue", "view", issueRef, "--json", "labels"], {
+    out = execFileSync7("gh", ["issue", "view", issueRef, "--json", "labels"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -4271,7 +4348,7 @@ function reportPass(json, command) {
 function runGhWrite(ghCmd, ghArgs, bodyResult, json) {
   const { finalArgs, cleanup: cleanup2 } = resolveShippableArgs(ghArgs, bodyResult);
   try {
-    const out = execFileSync6("gh", [...ghCmd, ...finalArgs], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
+    const out = execFileSync7("gh", [...ghCmd, ...finalArgs], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
     const url = out.trim();
     if (json)
       printJson({ validated: true, written: true, url });
@@ -4375,12 +4452,12 @@ ${registration}
 }
 
 // src/commands/pr.ts
-import { execFileSync as execFileSync7 } from "node:child_process";
+import { execFileSync as execFileSync8 } from "node:child_process";
 var RETRY_CREATE2 = "vinaya pr create --validate-only …";
 var RETRY_EDIT2 = "vinaya pr edit <n> --validate-only …";
 function git2(args) {
   try {
-    return execFileSync7("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return execFileSync8("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {
     return "";
   }
@@ -4414,7 +4491,7 @@ function reportPass2(json, command) {
 function runGhWrite2(ghCmd, ghArgs, bodyResult, json) {
   const { finalArgs, cleanup: cleanup2 } = resolveShippableArgs(ghArgs, bodyResult);
   try {
-    const out = execFileSync7("gh", [...ghCmd, ...finalArgs], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
+    const out = execFileSync8("gh", [...ghCmd, ...finalArgs], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
     const url = out.trim();
     if (json)
       printJson({ validated: true, written: true, url });
@@ -4428,7 +4505,7 @@ function runGhWrite2(ghCmd, ghArgs, bodyResult, json) {
 function fetchPrForgeContext(prRef) {
   let viewOut;
   try {
-    viewOut = execFileSync7("gh", ["pr", "view", prRef, "--json", "headRefName,files"], {
+    viewOut = execFileSync8("gh", ["pr", "view", prRef, "--json", "headRefName,files"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -4524,7 +4601,7 @@ function prEditCommand(args) {
 }
 
 // src/commands/quickstart.ts
-import { execFileSync as execFileSync8 } from "node:child_process";
+import { execFileSync as execFileSync9 } from "node:child_process";
 import { existsSync as existsSync14, readFileSync as readFileSync13 } from "node:fs";
 import { join as join15 } from "node:path";
 
@@ -4718,7 +4795,7 @@ function realDeps6() {
   };
 }
 function execGit(repoRoot, args) {
-  return execFileSync8("git", args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  return execFileSync9("git", args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 }
 function errorDetail(err) {
   const stderr = err.stderr;
@@ -5174,12 +5251,12 @@ async function upgradeCommand(args) {
 }
 
 // src/commands/waiver.ts
-import { execFileSync as execFileSync9 } from "node:child_process";
+import { execFileSync as execFileSync10 } from "node:child_process";
 function labelFor(kind) {
   return kind === "docs" ? WAIVER_LABEL : WAIVER_LABEL_REVIEW;
 }
 function gh(args) {
-  return execFileSync9("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: process.env }).trim();
+  return execFileSync10("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: process.env }).trim();
 }
 function detectPrNumber() {
   try {
@@ -5279,8 +5356,8 @@ Reason: ${reason}`];
   }
   process.stdout.write(`Applying \`${label2}\` to PR #${prNumber} under your authenticated \`gh\` identity — vinaya never fabricates an actor.
 `);
-  execFileSync9("gh", editArgs, { stdio: "inherit", env: process.env });
-  execFileSync9("gh", commentArgs, { stdio: "inherit", env: process.env });
+  execFileSync10("gh", editArgs, { stdio: "inherit", env: process.env });
+  execFileSync10("gh", commentArgs, { stdio: "inherit", env: process.env });
   process.stdout.write(`
 ✓ Label applied and reason posted as a PR comment.
 `);
@@ -5337,6 +5414,10 @@ var COMMANDS = [
       { flag: "--all", description: "Run every registered check instead of one named check" },
       { flag: "--json", description: "Enveloped JSON output (schema: 1)" },
       { flag: "--diff-only", description: "Scope diff-declared checks to changed files" },
+      {
+        flag: "--local",
+        description: "Skip every requiresOpenPr check (closes-n, test-plan) — set by the generated hooks, never by CI"
+      },
       { flag: "--parallel[=n]", description: "Concurrency cap (default: cpu-derived)" },
       {
         flag: "--plan",
@@ -5345,7 +5426,8 @@ var COMMANDS = [
     ],
     details: [
       "Each spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its `CheckSpec['env']` declaration explicitly forwards — never the full parent environment. A required (`true`) or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` before the check ever spawns. Declare `env` (a core check's own registration, or `vinaya.config.json`'s `checks.<name>.env` for a custom one) for any check that reads `process.env`/`Bun.env`/`Deno.env` directly — `vinaya doctor` carries the permanent diagnostic for one that doesn't.",
-      "`--plan` composes with `--json`. It requires zero env vars and never prints an env value — only how each one resolves (passthrough, optional, literal, or anyOf). A `FAIL_CLOSED` entry (a bare key with no namespace matching no core check) always renders inline rather than being dropped, and exits non-zero. `--plan` previews what the next minor's execution will enforce — `vinaya check` itself still runs the flat, unvalidated registry this release."
+      "`--plan` composes with `--json`. It requires zero env vars and never prints an env value — only how each one resolves (passthrough, optional, literal, or anyOf). A `FAIL_CLOSED` entry (a bare key with no namespace matching no core check) always renders inline rather than being dropped, and exits non-zero. `--plan` previews what the next minor's execution will enforce — `vinaya check` itself still runs the flat, unvalidated registry this release.",
+      "`--local` exists because a `requiresOpenPr` check (the core `closes-n`/`test-plan`, or a custom check declaring the same field) can only evaluate for real once a pull request exists — the generated `pre-commit`/`pre-push` hooks pass it so the first commit on a fresh task branch is never asked to satisfy a PR-body field before a PR can possibly exist. CI's `vinaya-checks.yml` omits it, so these checks always run for real once a PR is open."
     ],
     status: "shipped"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attalabs/vinaya",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Vinaya — Agentic Engineering Harness. Deterministic checks every AI coding agent must satisfy before merge.",
   "type": "module",
   "license": "Apache-2.0",

package/studio-standalone/.worktrees/fix/bump-0.4.4/.vinaya/projects.md

@@ -0,0 +1,63 @@
+---
+sidebar_title: Projects
+---
+# Projects in this repo
+
+**The project registry.** Declares the projects in this repo and where each one's specs and per-project state live. The `Project` field on a task (a forge Issue) resolves against this file: `Project: vada` → the Developer reads that project's specs, the Archivist updates its per-project state.
+
+## What a project is (and isn't)
+
+A project is **a `(name, folder)` pair the developer declared** — nothing more. Not derived from the folder tree, not required to match a `package.json` name, not required to be a single package. AEG does not define what a project "really" is; the developer does, by choosing a name and a home folder when registering it.
+
+The folder is simply **the home for that project's specs and status** (`<path>/specs/`, `<path>/aeg-project/`). A project may be one package, an app, or a grouping built from several packages.
+
+- **Identity = the registry row.** A project exists because it has a row here, not because a folder with some name exists somewhere. Nothing searches the tree; names are unique by this registry, paths are whatever the human gave.
+- **Path = declared, never derived.** `--path` is a required argument to `aeg add-project`; the tool stores it.
+
+**Presence of this file means this is a multi-project repo** — the `Project` field is required. A single-project repo has **no** `projects.md`; every task shares one project, so the field is omitted, and state lives in the root `aeg-project/`. The registry appears only when there is more than one project to disambiguate.
+
+## Registry
+
+| Project  | Path                  | Specs                       | Per-project state                    |
+|----------|-----------------------|-----------------------------|--------------------------------------|
+| admin    | `tools/admin`         | `tools/admin/specs/`        | (state tracked globally for now)     |
+| vada     | `apps/vada-ai`        | `apps/vada-ai/specs/`       | `apps/vada-ai/aeg-project/`   |
+| herald   | `apps/herald-ai`      | `apps/herald-ai/specs/`     | `apps/herald-ai/aeg-project/` |
+| aeg-core | `packages/aeg-core`   | `packages/aeg-core/specs/`  | (state tracked globally for now)     |
+| aeg-forge-state | `packages/aeg-forge-state` | `packages/aeg-forge-state/specs/` | (state tracked globally for now) |
+| attalabs | `apps/attalabs`       | `apps/attalabs/specs/`      | (state tracked globally for now)     |
+| vinaya   | `apps/vinaya`         | `apps/vinaya/specs/`        | Issue #768 (pinned)                  |
+
+> **admin** — `tools/admin`: the internal Sanity-backed admin tool for managing per-product theme/library config across every AttaLabs product (not a product itself, no `.attalabs.dev` domain). Had real code and a task PR (#557, the Library-picker feature) before ever getting a registry row — added retroactively once that gap was noticed. `tools/*` carries no `-ai` suffix (internal-tooling convention, like `apps/desktop`, `apps/attalabs`).
+
+> **vinaya** — Vinaya: the npm-distributed reference implementation of AEG, installed into any GitHub repository. One app folder, three workspaces: `apps/vinaya/cli` (the `vinaya` command — init/check/pr/issue/doctor/upgrade/eject/demo/waiver), `apps/vinaya/web` (**Vinaya Studio**, ported from the old AEG Studio app), and `apps/vinaya/sources` (the StateSource adapters — forge-backed primary, file-backed transitional). Imports `@atta/aeg-core` unchanged; the vinaya-namespace migration of shared code rides the later npm extraction, never a standalone rename. The registry row deliberately precedes the code. "Vinaya is the reference implementation of AEG": AEG stays the model's name (`aeg-root/` is untouched); Vinaya is the tool. Pāli name by elective aesthetic. `apps/vinaya` carries no `-ai` suffix (meta/infra convention).
+
+> **attalabs** — The AttaLabs ecosystem hub app (`@atta/attalabs-web`/`-mobile`/`-mcp-server`, serving `attalabs.dev`), distinct from **Atta** (the deep-thinking AI product — Vāda+Vitakka+Sati; its dedicated app scaffold, `apps/atta-ai`, was retired — Atta remains a real, code-less concept, not a registered project). Registered here because it has real code and its own `apps/attalabs/specs/`, but had no registry row until it was added retroactively (found while sizing an unrelated task's `Project(s)` field). `apps/attalabs` carries no `-ai` suffix (meta/infra-app convention, like `apps/desktop`).
+
+> **aeg-core** — `@atta/aeg-core` (`packages/aeg-core`): the pure, no-I/O package the AEG product runs on. Two capabilities: parse a repo's AEG artifacts (registry, tranche files) into a typed model, and `deriveTranche(tranche, forgeFacts)` → per-task derived status + the dependency/conflict graph + dispatch eligibility, mirroring `tranche-model.md` §3 exactly. Both **AEG Studio** (local, the first consumer) and the future **Portal** (hosted) read through this same substrate; they differ only in how they fetch the inputs. Registered as a project because a task declares `Project: aeg-core` — a package may be a project, per this file's framing above.
+
+> **aeg-forge-state** — `@atta/aeg-forge-state` (`packages/aeg-forge-state`): the one sanctioned adapter that reads live GitHub forge state (Milestone + labeled Issues) and derives the typed `Tranche`/`Task` shapes `aeg-core`'s pure evaluators consume — `gh`-CLI-only, read-only, zero topology file. Listed in `.aeg/packages` as its own collision domain (distinct from `aeg-core`) since before this row, but had no registry row of its own — any task editing its `src/**` had no `Project:` whose declared path actually covered it, forcing every prior task to fall back on a `blast-radius-ack:` line instead of a real ownership match. Registered retroactively (found while planning follow-on forge-adapter test-coverage and label-vocabulary work) for the same reason `attalabs` and `admin` were: real code, its own collision domain, no row.
+
+## How `Project` is validated
+
+This registry is the **authority for valid project names.** A `Project:` value is valid iff every name in it is a row above. The Planner and Developer resolve `Project:` against this file; an unmatched name (a typo like `vda`, or unregistered) makes the task malformed and the agent refuses rather than guessing — *"Project 'vda' isn't registered; did you mean 'vada', or run `aeg add-project` first?"* Can also run mechanically in `verify-docs`.
+
+## A task can span multiple projects — and that is normal
+
+`Project` is **multi-valued.** A task carries as many projects as it genuinely touches: usually one (`Project: vada`), sometimes several (`Project: engine, herald`, or more). Not an exception — cross-project PRs are an expected shape. The Planner decides split-vs-combine by **verification coupling** (see `tranche-model.md` §6): provable independently → separate tasks with a `depends-on` edge; provable only as a unit → one task / branch / PR / multiple projects. The same `Ticket:` rides on all resulting tasks, so work stays atomic in Jira however it's shaped in AEG.
+
+When a task lists multiple projects, every mechanism fans out: the Developer reads every listed project's specs; the PR is reviewed through each project's lens (more projects = more review lenses = proportionally more rigor, matching the wider blast radius); the Archivist updates every listed project's `state.md` (non-derivable operational facts; `now.md` is retired).
+
+## Routing vs. conflicts — two different granularities
+
+`Project` is the **coarse routing/ownership label** — "whose specs, whose state." It is **not** the conflict unit. Conflicts happen at the **package / collision-domain level**:
+
+- **Collision domains are packages**, listed in a rarely-changed static file, `.aeg/packages`. Known cross-cutting paths that couple tasks across package boundaries — **lockfiles, `migrations/`, codegen outputs (protobuf/GraphQL/OpenAPI), monorepo config (tsconfig/eslint/turbo)** — are declared as their own collision domains.
+- Two tasks conflict if they touch the same collision domain. The canonical case: a task generalizing `@atta/engine` (a package Vāda shares) conflicts with any in-flight Vāda task touching the engine — different projects, same package, real collision. So conflict detection keys on **packages, not projects**.
+- Conflicts are **declared by the Planner** (`conflicts-with` edges) and **static**. The gate is forge-answerable with zero stored state: "is a `conflicts-with` sibling's PR open?" There is **no dynamic path-overlap scanner** — that would need a live task→changed-files map, the mutable state AEG eliminates (forbidden; see `tranche-model.md` §9). When unsure two tasks collide, declare the conflict and serialize.
+
+Don't conflate them: `Project` = whose specs/state; `conflicts-with` (via collision domains) = whose files.
+
+---
+
+Project backlogs (held / future items, out of the AEG flow) live alongside each project's specs as `<path>/specs/<project>-backlog.md`. Cross-cutting / ecosystem items are cut as backlog Issues on the forge (the old `specs/ecosystem-backlog.md` was deleted).