@attalabs/vinaya 0.4.2 → 0.4.3

package/aeg-root/enforcement.md

@@ -44,7 +44,7 @@ The same check implementations run at ring 0 and ring 1 — one codebase, two en
 | Starting the Dig (before authoring a brief) / starting Step 0 (before executing one) / **every push on a task branch before its PR exists** | Ever started work only to find out halfway it was blocked on something else? | hook | Refuses to start work until every precondition for the task is checked live and found clear. | **`verify-dispatch` CLI** (`packages/aeg-core/bin/verify-dispatch.ts` — mandated by `roles/developer.md` and `skills/brief-authoring/SKILL.md`; **now also hook-automated** — task 25) | Every dispatch precondition is re-checked live against the forge (the task's row/Issue are derived directly from a Milestone + `vinaya/tranche:<slug>`-labeled Issues as of the forge-native migration — no `origin/main` file read involved; leftover-branch detection still fetches `origin/main` for its own commit-count comparison): the task's row and Issue exist; the Issue passes the rationale gate; every `depends-on` PR is merged and no `conflicts-with` PR is open/in-flight; every named project's prior tranche is archived. (2026-07-13: the immediately-prior task's three-predicate archival bar — the row-adjacency predicate — was removed once the provenance-posting signal it existed to protect became automated.) A `NOT READY` result is a stop condition. Every `gh` call this script makes carries an explicit `-R <owner>/<repo>` (task 23) — from a linked `git worktree add` checkout, an untargeted `gh issue list`/`gh issue view`/`gh pr list` silently scopes to the wrong repo (or returns nothing), which previously produced false prior-tranche-archival blockers. **`.husky/pre-push`** now runs this gate itself on a `task/*/*` branch's first push (before a PR exists), refusing on genuine `NOT READY` and failing OPEN — loudly — when a `gh auth status` reachability probe fails or `verify-dispatch`'s own repo/token resolution fails (task 18's fail-open precedent). The gate reads only the `dispatch-readiness:` predicate, not verify-dispatch's combined exit code, which also folds in `leftover-detection` (a pre-Step-0 "safe to branch fresh" advisory that would otherwise false-block every push after the first on a task legitimately mid-flight — discovered live while building this gate). Once a PR exists, later pushes skip the gate: dispatch was already validated once. | `packages/aeg-core/bin/verify-dispatch.ts` |
 | Opening a task PR whose surface includes real code | Ever had a PR's description quietly stop matching what the code does? | event | Refuses a code-carrying pull request whose description no longer matches what it changes. | **Brief Validation — `checkPremiseCoverage`** | The PR body carries a `Premise:` block with at least one assertion (`contains`/`absent`/`sha256`) whose path falls inside the task's surface map — re-assertable at any point via `verify-dispatch --premise` or `verify-task`. | `packages/aeg-core/src/brief-validation.ts` |
 | Opening a task PR (final self-check before creation) | Ever opened a PR and only then discovered the tests were failing? | event | Runs the whole exit check before a pull request is created, so failures surface first. | **`verify-task` CLI** (`packages/aeg-core/bin/verify-task.ts` — mandated by `roles/developer.md`; **now also hook-automated** — task 25) | Typecheck, lint, tests, build, `verify-docs --pr`, and the premise coverage/recheck pair all pass, as one summary, against the PR's actual diff, before `open-pr.ts` is invoked. **`open-pr.ts` now runs this composite itself** for task branches (via `gatePlanForBranch`), invoked wholesale rather than partially re-implemented — non-task branches are unaffected (byte-identical gate set). `verify-docs --pr` runs twice on a task-branch PR-open as an accepted, measured overlap (~4s with a warm turbo cache). | `packages/aeg-core/bin/verify-task.ts` |
-| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **⚠️ BREAKING, live (task 3):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) explicitly forwards — **no longer the full parent environment.** An undeclared variable a check's own code reads is now genuinely invisible to it, not merely warned about; a `true` or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` and the check never spawns at all. All 15 core checks in `registry.ts` carry an audited declaration, and every core check that spawns `gh` or reaches the forge through the token-resolution chain additionally forwards `GITHUB_TOKEN`/`GH_TOKEN` as `{ optional: true }` — on a CI runner those env vars are `gh`'s only authentication path, so a check that shells out without forwarding them runs unauthenticated there (hard-failing or silently degrading, depending on the bin's failure mode) while passing locally on `gh`'s keyring; the pairing is coupling-tested (`apps/vinaya/cli/tests/checks/registry-env.test.ts` detects `gh` invocations in any call shape — array-form, string-form, and template-literal — and demands both declarations). This repo's own core checks are therefore unaffected — an adopter's **custom** check that reads `process.env` directly with no `env` declared will lose that access at this minor; declare `env` on it (`vinaya.config.json`'s `checks.<name>.env`) before upgrading. `vinaya check`'s prior warn-phase print (task 2) is retired now that the behavior it warned about is live; `vinaya doctor` still carries the same missing-declaration diagnostic permanently, at `info` severity, so a custom check's gap remains visible after upgrade even though `vinaya check` no longer prints it inline. | `apps/vinaya/cli/src/checks/runner.ts` |
+| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **⚠️ BREAKING, live (task 3):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) explicitly forwards — **no longer the full parent environment.** An undeclared variable a check's own code reads is now genuinely invisible to it, not merely warned about; a `true` or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` and the check never spawns at all. All 15 core checks in `registry.ts` carry an audited declaration, and every core check that spawns `gh` or reaches the forge through the token-resolution chain additionally forwards `GITHUB_TOKEN`/`GH_TOKEN` as `{ optional: true }` — on a CI runner those env vars are `gh`'s only authentication path, so a check that shells out without forwarding them runs unauthenticated there (hard-failing or silently degrading, depending on the bin's failure mode) while passing locally on `gh`'s keyring; the pairing is coupling-tested (`apps/vinaya/cli/tests/checks/registry-env.test.ts` detects `gh` invocations in any call shape — array-form, string-form, and template-literal — and demands both declarations); that detection is source-text pattern matching, so it does not yet catch a check that reaches the forge indirectly through `createForgeSource` (`@atta/vinaya-sources`) with no literal `gh` call of its own — found live: `closes-n` reaches the forge this way and had shipped without either token declared, passing locally under a developer's own `gh` keyring and failing unauthenticated on every CI runner, a known gap in the coupling test's own coverage rather than in the rule it's checking. This repo's own core checks are therefore unaffected — an adopter's **custom** check that reads `process.env` directly with no `env` declared will lose that access at this minor; declare `env` on it (`vinaya.config.json`'s `checks.<name>.env`) before upgrading. `vinaya check`'s prior warn-phase print (task 2) is retired now that the behavior it warned about is live; `vinaya doctor` still carries the same missing-declaration diagnostic permanently, at `info` severity, so a custom check's gap remains visible after upgrade even though `vinaya check` no longer prints it inline. | `apps/vinaya/cli/src/checks/runner.ts` |
 | `vinaya check` / `vinaya check --plan` (a CLI mechanism, not a git hook — this row is `.husky`-free) | Ever had a config entry silently double-run alongside the core check it was meant to replace, with no way to see that from the outside? | event | Resolves core-registered and config-registered checks into one deterministic table before anything runs, instead of letting a config entry run alongside the core check it collides with, unannounced. | **Checks-side resolver** (`resolveChecks`/`isValidNamespacedKey`, `apps/vinaya/cli/src/checks/resolver.ts`) | An exact-key match against a core check ID is an **override** — a complete replacement of the spec, never a merge. A key containing exactly one `/`, both segments matching `[a-z0-9][a-z0-9-]*` and the `vinaya` prefix rejected as an exact segment match, is **additive**. Anything else — a bare key with no `/` matching no core ID — is a loud `FAIL_CLOSED` refusal: never silently dropped, never defaulted, never last-wins. `--plan` never resolves or prints an env *value*, only how each one resolves. **This release feeds `vinaya check --plan` / `--plan --json` only** — `vinaya check`'s real execution (`check.ts`'s flat `[...coreCheckRegistry(), ...customSpecs]` concat) is unaffected until a later task wires it in. | `apps/vinaya/cli/src/checks/resolver.ts` |
 
 **Documentation coverage, specifically** (a historical pain point): the code→document ownership rule is enforced at *two* prevention chokepoints — at every push (over the branch's cumulative change set) and again at pull-request creation and editing. A change to owned code cannot be published, let alone turned into a pull request, without its owning document.

package/dist/index.js

@@ -1578,7 +1578,9 @@ function coreCheckRegistry() {
       env: {
         BRANCH: { optional: true },
         PR_BODY: { optional: true },
-        AEG_REPO: { optional: true }
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -3465,7 +3467,7 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
         findings.push(content === op.content ? warn(check, `${op.path} has vinaya's own content but isn't recorded in the manifest.`) : info(check, `${op.path} exists but is foreign content — not vinaya-managed, left untouched.`));
         continue;
       }
-      if (op.path === CONFIG_PATH) {
+      if (op.path === CONFIG_PATH || op.path === DOC_OWNERS_PATH) {
         findings.push(ok(check, `${op.path} present and vinaya-managed.`));
         continue;
       }
@@ -4523,7 +4525,7 @@ function prEditCommand(args) {
 
 // src/commands/quickstart.ts
 import { execFileSync as execFileSync8 } from "node:child_process";
-import { readFileSync as readFileSync13 } from "node:fs";
+import { existsSync as existsSync14, readFileSync as readFileSync13 } from "node:fs";
 import { join as join15 } from "node:path";
 
 // src/lib/doc-owners-write.ts
@@ -4574,10 +4576,118 @@ function renderDocOwnersBindingDiffLine(plan) {
 }
 
 // src/commands/quickstart.ts
+var useColor = process.stdout.isTTY === true;
+function paint(code, s) {
+  return useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+}
+var bold = (s) => paint("1", s);
+var cyan = (s) => paint("36", s);
+var green = (s) => paint("32", s);
+var red = (s) => paint("31", s);
+var BLOCK_FONT = {
+  V: ["█   █", "█   █", "█   █", " █ █ ", "  █  "],
+  I: ["█████", "  █  ", "  █  ", "  █  ", "█████"],
+  N: ["█   █", "██  █", "█ █ █", "█  ██", "█   █"],
+  A: [" ███ ", "█   █", "█████", "█   █", "█   █"],
+  Y: ["█   █", " █ █ ", "  █  ", "  █  ", "  █  "],
+  H: ["█   █", "█   █", "█████", "█   █", "█   █"],
+  R: ["████ ", "█   █", "████ ", "█ █  ", "█  █ "],
+  E: ["█████", "█    ", "████ ", "█    ", "█████"],
+  S: [" ████", "█    ", " ███ ", "    █", "████ "]
+};
+var BLANK_GLYPH = ["   ", "   ", "   ", "   ", "   "];
+function blockBanner(text) {
+  const glyphs = text.toUpperCase().split("").map((ch) => ch === " " ? BLANK_GLYPH : BLOCK_FONT[ch] ?? ["     ", "     ", "     ", "     ", "     "]);
+  const rows = [];
+  for (let r = 0;r < 5; r++)
+    rows.push(glyphs.map((g) => g[r]).join(" "));
+  return rows.join(`
+`);
+}
+var TOTAL_STEPS = 7;
+function stepHeader(n, title, caption) {
+  const rule = cyan("━".repeat(56));
+  return `
+${rule}
+${bold(cyan(`STEP ${n} of ${TOTAL_STEPS}`))} — ${bold(title)}
+${rule}
+${caption}
+`;
+}
 var GLOB_INJECTION_RE = /[\s\r\n]/;
 var POINTER_INJECTION_RE = /[\r\n]/;
 var NAME_INJECTION_RE = /[\s|\r\n]/;
 var PATH_INJECTION_RE2 = /[|\r\n]/;
+function pointerIsMissingLocalFile(repoRoot, pointer) {
+  if (/^https?:\/\//i.test(pointer))
+    return false;
+  const path = pointer.split("#")[0] ?? pointer;
+  return !existsSync14(join15(repoRoot, path));
+}
+async function bindDocOwnerLoop(deps, repoRoot) {
+  let any = false;
+  for (;; ) {
+    if (any && !await deps.confirm("Bind another doc→code pair?", false))
+      return;
+    const glob = (await deps.ask("Code glob to bind (e.g. apps/foo/src/**): ")).trim();
+    const pointer = (await deps.ask("Doc pointer (in-repo path, path#anchor, or URL): ")).trim();
+    if (!glob || !pointer) {
+      if (!any)
+        process.stdout.write(red(`✗ Skipped — no glob/pointer provided, no doc-owners binding created.
+`));
+      return;
+    }
+    if (GLOB_INJECTION_RE.test(glob) || POINTER_INJECTION_RE.test(pointer)) {
+      console.error(red("Error: glob must not contain whitespace, and the pointer must not contain a newline."));
+    } else if (pointerIsMissingLocalFile(repoRoot, pointer)) {
+      console.error(red(`✗ "${pointer}" does not exist in this repo (and isn't a URL).`));
+    } else {
+      const plan = planDocOwnersBinding(repoRoot, glob, pointer);
+      applyDocOwnersBinding(repoRoot, plan, glob, pointer);
+      process.stdout.write(`${green(renderDocOwnersBindingDiffLine(plan))}
+`);
+      any = true;
+      continue;
+    }
+    if (!await deps.confirm("Try again?", true)) {
+      if (!any)
+        process.stdout.write(red(`✗ Skipped — no doc-owners binding created.
+`));
+      return;
+    }
+  }
+}
+async function registerProjectLoop(deps) {
+  let any = false;
+  for (;; ) {
+    if (any && !await deps.confirm("Register another project?", false))
+      return;
+    const name = (await deps.ask("Project name (lower-case slug): ")).trim();
+    const rawPath = (await deps.ask("Project path (relative to repo root) [.]: ")).trim();
+    const path = rawPath || ".";
+    if (!name) {
+      if (!any)
+        process.stdout.write(red(`✗ Skipped — no project name provided, no project registered.
+`));
+      return;
+    }
+    if (NAME_INJECTION_RE.test(name) || PATH_INJECTION_RE2.test(path)) {
+      console.error(red("Error: project name must not contain whitespace or a pipe, and the path must not contain a pipe or a newline."));
+    } else {
+      const rc = await runInitProduct([name, "--path", path, "--yes"], deps.initDeps);
+      if (rc !== 0)
+        console.error(red(`\`vinaya init product\` exited with code ${rc}.`));
+      any = true;
+      continue;
+    }
+    if (!await deps.confirm("Try again?", true)) {
+      if (!any)
+        process.stdout.write(red(`✗ Skipped — no project registered.
+`));
+      return;
+    }
+  }
+}
 function readPackageVersion() {
   const pkg = JSON.parse(readFileSync13(join15(packageRoot(import.meta.url), "package.json"), "utf-8"));
   return pkg.version;
@@ -4653,77 +4763,59 @@ async function runQuickstart(_args, deps) {
     return 1;
   }
   try {
-    process.stdout.write(`vinaya quickstart — guided install
+    process.stdout.write(`${cyan(blockBanner("VINAYA HARNESS"))}
 
+${bold("Quickstart")} — guided install
 `);
+    process.stdout.write(stepHeader(1, "Install", "Runs `vinaya init` — shows the full diff of what would be installed (config, workflows, git hooks, doctrine pointer), then asks you to confirm before writing anything."));
+    await deps.ask("Press Enter to see the diff and continue: ");
     const initRc = await runInit([], deps.initDeps);
     if (initRc !== 0) {
-      console.error(`
-\`vinaya init\` exited with code ${initRc} — quickstart cannot continue.`);
+      console.error(red(`
+\`vinaya init\` exited with code ${initRc} — quickstart cannot continue.`));
       return initRc;
     }
+    process.stdout.write(stepHeader(2, "Bind a doc → code pair", "Optional. Tells Vinaya which code maps to which doc, so the doc-coverage check can enforce it later. Skip with N — you'll be asked to bind another after each one."));
     const bindDoc = await deps.confirm("Bind a doc→code pair now?", false);
-    if (bindDoc) {
-      const glob = (await deps.ask("Code glob to bind (e.g. apps/foo/src/**): ")).trim();
-      const pointer = (await deps.ask("Doc pointer (in-repo path, path#anchor, or URL): ")).trim();
-      if (!glob || !pointer) {
-        process.stdout.write(`No glob/pointer provided — skipping the doc-owners binding.
-`);
-      } else if (GLOB_INJECTION_RE.test(glob) || POINTER_INJECTION_RE.test(pointer)) {
-        console.error("Error: glob must not contain whitespace, and the pointer must not contain a newline — skipping.");
-      } else {
-        const plan = planDocOwnersBinding(repo.repoRoot, glob, pointer);
-        applyDocOwnersBinding(repo.repoRoot, plan, glob, pointer);
-        process.stdout.write(`${renderDocOwnersBindingDiffLine(plan)}
-`);
-      }
-    }
+    if (bindDoc)
+      await bindDocOwnerLoop(deps, repo.repoRoot);
+    process.stdout.write(stepHeader(3, "Register a project", "Optional. Writes `.vinaya/projects.md` so Studio's board can resolve this project. Skip with N — you'll be asked to register another after each one."));
     const registerProject = await deps.confirm("Register this as a tracked project?", false);
-    if (registerProject) {
-      const name = (await deps.ask("Project name (lower-case slug): ")).trim();
-      const rawPath = (await deps.ask("Project path (relative to repo root) [.]: ")).trim();
-      const path = rawPath || ".";
-      if (!name) {
-        process.stdout.write(`No project name provided — skipping project registration.
-`);
-      } else if (NAME_INJECTION_RE.test(name) || PATH_INJECTION_RE2.test(path)) {
-        console.error("Error: project name must not contain whitespace or a pipe, and the path must not contain a pipe or a newline — skipping.");
-      } else {
-        const rc = await runInitProduct([name, "--path", path, "--yes"], deps.initDeps);
-        if (rc !== 0)
-          console.error(`\`vinaya init product\` exited with code ${rc}.`);
-      }
-    }
+    if (registerProject)
+      await registerProjectLoop(deps);
+    process.stdout.write(stepHeader(4, "Review and commit", "Shows `git status` for the full working tree, then commits everything as one `Chore: install Vinaya` commit. Not gated by a prompt — always runs, no-ops if there is genuinely nothing to commit."));
     const status = gitStatusShort(repo.repoRoot);
-    process.stdout.write("\nWorking tree before commit (review before it lands — `git add -A` runs next):\n");
+    process.stdout.write("Working tree before commit (review before it lands — `git add -A` runs next):\n");
     process.stdout.write(status ? `${status}
 ` : `(clean)
 `);
     process.stdout.write(`
-→ Committing the install…
+${bold("→ Committing the install…")}
 `);
     const commitResult = commitInstall(repo.repoRoot);
-    process.stdout.write(`${commitResult.message}
+    process.stdout.write(`${commitResult.committed ? green(commitResult.message) : commitResult.message}
 `);
+    process.stdout.write(stepHeader(5, "Refusal-then-fix proof", "Runs a real broken commit through the hook just installed, shows it get refused, fixes it, and cleans up — proves the install actually works. Recommended, defaults to Y."));
     const ranDemoBreak = await deps.confirm("Run the refusal-then-fix proof now? (recommended — proves the install actually works)", true);
     if (ranDemoBreak) {
       const rc = await runDemoBreak(repo.repoRoot, []);
       if (rc !== 0)
-        console.error(`\`vinaya demo break\` exited with code ${rc}.`);
+        console.error(red(`\`vinaya demo break\` exited with code ${rc}.`));
     }
-    process.stdout.write("\n→ Running `vinaya doctor`…\n");
+    process.stdout.write(stepHeader(6, "Doctor", "Runs `vinaya doctor` — confirms every installed artifact matches what should be there. Read-only, mutates nothing."));
     await runDoctor([], deps.doctorDeps);
+    process.stdout.write(stepHeader(7, "Push", "Pushes the install commit to your remote, if you have one. Recommended, defaults to Y."));
     let pushed = false;
     const wantsPush = await deps.confirm("Push to the remote now?", true);
     if (wantsPush) {
       const pushResult = pushInstall(repo.repoRoot);
       process.stdout.write(`
-${pushResult.message}
+${pushResult.pushed ? green(pushResult.message) : red(pushResult.message)}
 `);
       pushed = pushResult.pushed;
     }
     process.stdout.write(`
-Next steps:
+${bold("Next steps:")}
 `);
     process.stdout.write(`  vinaya studio
 `);
@@ -4746,7 +4838,7 @@ async function quickstartCommand(args) {
 
 // src/commands/studio.ts
 import { execFile as execFile5, spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync14, renameSync } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync14, renameSync } from "node:fs";
 import net from "node:net";
 import { dirname as dirname6, join as join16 } from "node:path";
 import { promisify as promisify5 } from "node:util";
@@ -4766,7 +4858,7 @@ function resolveStudioTarget(cwd, moduleUrl = import.meta.url) {
   for (;; ) {
     const webDir = join16(dir, "apps", "vinaya", "web");
     const pkgPath = join16(webDir, "package.json");
-    if (existsSync14(pkgPath)) {
+    if (existsSync15(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync14(pkgPath, "utf-8"));
         if (pkg.name === "@atta/vinaya-web") {
@@ -4780,7 +4872,7 @@ function resolveStudioTarget(cwd, moduleUrl = import.meta.url) {
     dir = parent;
   }
   const standaloneWebDir = join16(packageRoot(moduleUrl), "studio-standalone", "apps", "vinaya", "web");
-  if (existsSync14(join16(standaloneWebDir, "server.js"))) {
+  if (existsSync15(join16(standaloneWebDir, "server.js"))) {
     return { kind: "package", packageDir: standaloneWebDir };
   }
   return { kind: "missing" };
@@ -4802,7 +4894,7 @@ function isPortFree(port) {
 function ensureStudioNodeModules(bundleRoot) {
   const real = join16(bundleRoot, "node_modules");
   const packed = join16(bundleRoot, STUDIO_NODE_MODULES_PACKED_DIRNAME);
-  if (!existsSync14(real) && existsSync14(packed)) {
+  if (!existsSync15(real) && existsSync15(packed)) {
     renameSync(packed, real);
   }
 }
@@ -4814,7 +4906,7 @@ async function spawnStandalone(cwd, serverPath, bundleRoot) {
   if (!primaryFree) {
     console.info(`[studio] port ${PRIMARY_PORT} is taken — falling back to ${FALLBACK_PORT}`);
   }
-  const env = { HOSTNAME: "127.0.0.1", ...process.env, PORT: String(port) };
+  const env = { HOSTNAME: "127.0.0.1", ...process.env, PORT: String(port), VINAYA_REPO_ROOT: cwd };
   if (repo)
     env.AEG_REPO = `${repo.owner}/${repo.repo}`;
   return new Promise((resolve2) => {
@@ -4838,7 +4930,7 @@ async function runStudio(cwd, args, moduleUrl = import.meta.url) {
 }
 
 // src/commands/upgrade.ts
-import { existsSync as existsSync15, readFileSync as readFileSync15, writeFileSync as writeFileSync9 } from "node:fs";
+import { existsSync as existsSync16, readFileSync as readFileSync15, writeFileSync as writeFileSync9 } from "node:fs";
 import { join as join17 } from "node:path";
 function realDeps7() {
   return {
@@ -4856,7 +4948,7 @@ function flags2(args) {
 }
 function readManifest3(repoRoot) {
   const p = join17(repoRoot, CONFIG_PATH);
-  if (!existsSync15(p))
+  if (!existsSync16(p))
     return { kind: "missing" };
   let raw;
   try {
@@ -4891,10 +4983,10 @@ function planUpgrade(ops, repoRoot, manifest) {
   for (const op of ops) {
     if (op.kind === "create-file") {
       const abs2 = join17(repoRoot, op.path);
-      const exists = existsSync15(abs2);
+      const exists = existsSync16(abs2);
       const owned = ownedFiles.has(op.path);
       let action;
-      if (op.path === CONFIG_PATH) {
+      if (op.path === CONFIG_PATH || op.path === DOC_OWNERS_PATH) {
         action = "keep";
       } else if (!owned) {
         action = exists ? "refuse-foreign" : "not-installed";
@@ -4914,7 +5006,7 @@ function planUpgrade(ops, repoRoot, manifest) {
       let action;
       if (!owned) {
         action = "not-installed";
-      } else if (!existsSync15(abs2)) {
+      } else if (!existsSync16(abs2)) {
         action = "recreate-host";
         hasChanges = true;
       } else {
@@ -5413,7 +5505,7 @@ var COMMANDS = [
     name: "quickstart",
     description: "Guided wizard: init, doc-owners, project, commit, demo break, doctor, push — one command",
     details: [
-      "Calls `init`'s own diff-and-confirm flow unchanged, then Y/n-prompts through the workarounds a guest used to run by hand: binding a `.vinaya/doc-owners` pair, registering a tracked project (`init product`), committing the install, running `demo break` as proof the gates actually work (default yes — the one step this wizard makes hardest to skip), running `doctor`, and pushing. Each declined prompt skips only that step; the install commit itself is never prompt-gated — it just no-ops when there is genuinely nothing to commit.",
+      "Calls `init`'s own diff-and-confirm flow unchanged (pausing on Enter before the diff prints, so its own step header isn't scrolled off by a long diff), then Y/n-prompts through the workarounds a guest used to run by hand: binding `.vinaya/doc-owners` pairs (bad input offers a retry instead of silently skipping, and a pointer that doesn't exist on disk is refused outright — both loop across as many pairs as the guest wants, not just one), registering tracked projects (`init product`, same retry/loop shape), committing the install, running `demo break` as proof the gates actually work (default yes — the one step this wizard makes hardest to skip), running `doctor`, and pushing. Each declined prompt skips only that step; the install commit itself is never prompt-gated — it just no-ops when there is genuinely nothing to commit.",
       "Never reimplements or edits `init`/`init product`/`demo break`/`doctor` — it only calls their existing, unmodified entry points in sequence."
     ],
     status: "shipped"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attalabs/vinaya",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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.3/.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).