@attalabs/vinaya 0.4.2 → 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,10 +1606,13 @@ function coreCheckRegistry() {
       run: bin("check-closes-n"),
       scope: "diff",
       timeoutMs: 15000,
+      requiresOpenPr: true,
       env: {
         BRANCH: { optional: true },
         PR_BODY: { optional: true },
-        AEG_REPO: { optional: true }
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1598,6 +1632,7 @@ function coreCheckRegistry() {
       run: bin("check-test-plan"),
       scope: "diff",
       timeoutMs: 15000,
+      requiresOpenPr: true,
       env: {
         PR_BODY: { optional: true },
         BRANCH: { optional: true }
@@ -1629,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 }
       }
@@ -1679,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 }
       }
     },
     {
@@ -1758,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)
@@ -2018,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;
@@ -2125,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");
@@ -2153,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();
@@ -2174,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
@@ -2299,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");
@@ -2316,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();
@@ -2331,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) {
@@ -2564,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";
@@ -2627,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
 `;
@@ -2673,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
 `;
@@ -2859,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");
@@ -3444,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;
@@ -3465,7 +3544,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;
       }
@@ -3477,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.`));
@@ -4028,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";
@@ -4241,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"]
     });
@@ -4269,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 });
@@ -4373,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 "";
   }
@@ -4412,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 });
@@ -4426,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"]
     });
@@ -4522,8 +4601,8 @@ function prEditCommand(args) {
 }
 
 // src/commands/quickstart.ts
-import { execFileSync as execFileSync8 } from "node:child_process";
-import { readFileSync as readFileSync13 } from "node:fs";
+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";
 
 // src/lib/doc-owners-write.ts
@@ -4574,10 +4653,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;
@@ -4608,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;
@@ -4653,77 +4840,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 +4915,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 +4935,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 +4949,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 +4971,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 +4983,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 +5007,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 +5025,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 +5060,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 +5083,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 {
@@ -5082,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 {
@@ -5187,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.
 `);
@@ -5245,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",
@@ -5253,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"
   },
@@ -5413,7 +5587,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"