@attalabs/vinaya 0.3.0 → 0.4.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync12 } from "node:fs";
+import { readFileSync as readFileSync13 } from "node:fs";
 import { dirname as dirname5, join as join15 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -1334,7 +1334,9 @@ function coreCheckRegistry() {
       timeoutMs: 15000,
       env: {
         BASE_SHA: { optional: true },
-        PR_NUMBER: { optional: true }
+        PR_NUMBER: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1359,7 +1361,11 @@ function coreCheckRegistry() {
       run: bin("check-registry-gates"),
       scope: "full",
       timeoutMs: 30000,
-      env: { AEG_REPO: { optional: true } }
+      env: {
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "review-gate",
@@ -1368,7 +1374,9 @@ function coreCheckRegistry() {
       timeoutMs: 30000,
       env: {
         BRANCH: { optional: true },
-        PR_NUMBER: { optional: true }
+        PR_NUMBER: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1378,7 +1386,9 @@ function coreCheckRegistry() {
       timeoutMs: 30000,
       env: {
         BRANCH: { optional: true },
-        AEG_REPO: { optional: true }
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     },
     {
@@ -1386,7 +1396,11 @@ function coreCheckRegistry() {
       run: bin("check-dead-branch-push"),
       scope: "full",
       timeoutMs: 30000,
-      env: { BRANCH: { optional: true } }
+      env: {
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "first-push-dispatch",
@@ -1421,12 +1435,62 @@ function coreCheckRegistry() {
       timeoutMs: 30000,
       env: {
         AEG_REPO: { optional: true },
-        BRANCH: { optional: true }
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
       }
     }
   ];
 }
 
+// src/checks/resolver.ts
+var NAMESPACE_SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
+var RESERVED_PREFIX = "vinaya";
+function isValidNamespacedKey(key) {
+  const parts = key.split("/");
+  if (parts.length !== 2)
+    return false;
+  const [prefix, rest] = parts;
+  if (!prefix || !rest)
+    return false;
+  if (!NAMESPACE_SEGMENT.test(prefix) || !NAMESPACE_SEGMENT.test(rest))
+    return false;
+  if (prefix === RESERVED_PREFIX)
+    return false;
+  return true;
+}
+function resolveChecks(core, configChecks) {
+  const resolved = core.map((spec) => ({ name: spec.name, state: "default", source: "core", spec }));
+  const failures = [];
+  if (!configChecks)
+    return { resolved, failures };
+  const indexByName = new Map(resolved.map((entry2, index) => [entry2.name, index]));
+  for (const [key, entry2] of Object.entries(configChecks)) {
+    const coreIndex = indexByName.get(key);
+    if (coreIndex !== undefined) {
+      resolved[coreIndex] = {
+        name: key,
+        state: "overridden",
+        source: "config",
+        spec: { name: key, ...entry2 }
+      };
+      continue;
+    }
+    if (isValidNamespacedKey(key)) {
+      resolved.push({ name: key, state: "additive", source: "config", spec: { name: key, ...entry2 } });
+      continue;
+    }
+    failures.push({ key, reason: 'bare key has no "/" and matches no core check id' });
+  }
+  return { resolved, failures };
+}
+function overriddenNextMinorWarning(name) {
+  return `check "${name}" shares its name with a core check — it will replace the core check starting next minor (currently it runs alongside it under the flat registry).`;
+}
+function bareKeyNextMinorWarning(key) {
+  return `check "${key}" has no namespace and matches no core check — it will be rejected starting next minor. Rename it to "<yourname>/x".`;
+}
+
 // src/checks/runner.ts
 import { spawn } from "node:child_process";
 import { cpus } from "node:os";
@@ -1832,6 +1896,15 @@ function configPath() {
     return GLOBAL_CONFIG_PATH;
   return null;
 }
+function globalChecksIgnoredWarning(path) {
+  return `${path}: "checks" registration in the global config is ignored — checks may only be registered from a repo-local vinaya.config.json.`;
+}
+function stripGlobalChecks(config, path) {
+  if (path !== GLOBAL_CONFIG_PATH || !config.checks || Object.keys(config.checks).length === 0)
+    return config;
+  console.error(`⚠ ${globalChecksIgnoredWarning(path)}`);
+  return { ...config, checks: undefined };
+}
 function loadConfigChecked() {
   const path = configPath();
   if (!path)
@@ -1847,7 +1920,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: parsed.data };
+  return { ok: true, config: stripGlobalChecks(parsed.data, path) };
 }
 
 // src/commands/check.ts
@@ -1887,25 +1960,112 @@ function configErrorOutcome(path, error) {
 function customSpecsFromConfig() {
   const result = loadConfigChecked();
   if (!result.ok)
-    return { specs: [], errorOutcome: configErrorOutcome(result.path, result.error) };
+    return { specs: [], errorOutcome: configErrorOutcome(result.path, result.error), checks: undefined };
   const checks = result.config?.checks;
   if (!checks)
-    return { specs: [], errorOutcome: null };
+    return { specs: [], errorOutcome: null, checks: undefined };
   const specs = Object.entries(checks).map(([name, entry2]) => ({ name, ...entry2 }));
-  return { specs, errorOutcome: null };
+  return { specs, errorOutcome: null, checks };
+}
+function classifyEnvValue(value) {
+  if (value === true)
+    return "passthrough";
+  if (typeof value === "string")
+    return "literal";
+  if ("anyOf" in value)
+    return "anyOf";
+  return "optional";
+}
+function renderPlanJson(result) {
+  const checks = {};
+  for (const entry2 of result.resolved) {
+    const env = {};
+    let envAnyOf;
+    for (const [key, value] of Object.entries(entry2.spec.env ?? {})) {
+      env[key] = classifyEnvValue(value);
+      if (typeof value === "object" && value !== null && "anyOf" in value) {
+        envAnyOf ??= {};
+        envAnyOf[key] = value.anyOf;
+      }
+    }
+    checks[entry2.name] = { state: entry2.state, source: entry2.source, env, envAnyOf, scope: entry2.spec.scope };
+  }
+  return {
+    schema: 1,
+    checks,
+    roles: { available: false, reason: "role resolution not implemented yet — see task 6" },
+    errors: result.failures
+  };
+}
+function envCellFor(spec) {
+  const entries = Object.entries(spec.env ?? {});
+  if (entries.length === 0)
+    return "—";
+  return entries.map(([key, value]) => {
+    if (value === true)
+      return key;
+    if (typeof value === "string")
+      return `${key}=<redacted>`;
+    if ("anyOf" in value)
+      return value.anyOf.join("|");
+    return `${key}?`;
+  }).join(", ");
+}
+function renderPlanTable(result) {
+  const header = ["NAME", "STATE", "SOURCE", "ENV"];
+  const rows = result.resolved.map((entry2) => [entry2.name, entry2.state, entry2.source, envCellFor(entry2.spec)]);
+  const failureRows = result.failures.map((f) => [f.key, "FAILED", "—", f.reason]);
+  const table = [header, ...rows, ...failureRows];
+  const widths = header.map((_, col) => Math.max(...table.map((row) => row[col]?.length ?? 0)));
+  return table.map((row) => row.map((cell, col) => (cell ?? "").padEnd(widths[col] ?? 0)).join("  ")).join(`
+`);
+}
+function resolveForPlan(configResult) {
+  if (configResult.ok) {
+    return resolveChecks(coreCheckRegistry(), configResult.config?.checks);
+  }
+  const core = resolveChecks(coreCheckRegistry(), undefined);
+  return {
+    resolved: core.resolved,
+    failures: [{ key: configResult.path, reason: `invalid \`checks\` registration — ${configResult.error}` }]
+  };
+}
+function printClassificationWarnings(configChecks) {
+  const classification = resolveChecks(coreCheckRegistry(), configChecks);
+  for (const entry2 of classification.resolved) {
+    if (entry2.state === "overridden")
+      process.stdout.write(`${overriddenNextMinorWarning(entry2.name)}
+`);
+  }
+  for (const failure of classification.failures) {
+    process.stdout.write(`${bareKeyNextMinorWarning(failure.key)}
+`);
+  }
 }
 async function checkCommand(args) {
   const jsonOutput = args.includes("--json");
   const diffOnly = args.includes("--diff-only");
   const requestedParallel = parseParallel(args);
   const allRequested = args.includes("--all");
+  const planRequested = args.includes("--plan");
   const positional = args.filter((a) => !a.startsWith("--"));
   const requestedName = positional[0];
+  if (planRequested) {
+    const result = resolveForPlan(loadConfigChecked());
+    if (jsonOutput) {
+      process.stdout.write(`${JSON.stringify(renderPlanJson(result), null, 2)}
+`);
+    } else {
+      process.stdout.write(`${renderPlanTable(result)}
+`);
+    }
+    process.exit(result.failures.length > 0 ? 1 : 0);
+  }
   if (!allRequested && !requestedName) {
-    console.error("Usage: vinaya check <name> | --all [--json] [--diff-only] [--parallel[=n]]");
+    console.error("Usage: vinaya check <name> | --all | --plan [--json] [--diff-only] [--parallel[=n]]");
     process.exit(2);
   }
-  const { specs: customSpecs, errorOutcome } = customSpecsFromConfig();
+  const { specs: customSpecs, errorOutcome, checks: configChecks } = customSpecsFromConfig();
   const allSpecs = [...coreCheckRegistry(), ...customSpecs];
   const specsToRun = allRequested ? allSpecs : allSpecs.filter((s) => s.name === requestedName);
   if (!allRequested && specsToRun.length === 0) {
@@ -1935,6 +2095,7 @@ async function checkCommand(args) {
         process.stdout.write(`    ${e.severity}: ${e.message}
 `);
     }
+    printClassificationWarnings(configChecks);
   }
   const failed = allOutcomes.some((o) => o.status === "fail" || o.status === "error" || o.status === "timeout");
   process.exit(failed ? 1 : 0);
@@ -2149,15 +2310,17 @@ async function demoBreakCommand(args) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5, statSync } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync6, statSync } from "node:fs";
 import { join as join8 } from "node:path";
 
 // src/lib/artifacts.ts
+import { readFileSync as readFileSync3 } from "node:fs";
 import { join as join6 } from "node:path";
 var CONFIG_PATH = "vinaya.config.json";
 var DOCTRINE_POINTER_PATH = "VINAYA.md";
 var CHECKS_WORKFLOW_PATH = ".github/workflows/vinaya-checks.yml";
 var REVIEW_WORKFLOW_PATH = ".github/workflows/vinaya-review.yml";
+var REVIEW_VERDICT_WORKFLOW_PATH = ".github/workflows/vinaya-review-verdict.yml";
 var ARCHIVIST_WORKFLOW_PATH = ".github/workflows/vinaya-archivist.yml";
 var MANAGED_NOTE = "Managed by Vinaya — created by `vinaya init`. `vinaya upgrade` regenerates it; `vinaya eject` removes it.";
 function starterConfig() {
@@ -2197,6 +2360,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      pull-requests: read
+      issues: read
     steps:
       - uses: actions/checkout@v4
         with:
@@ -2205,36 +2370,94 @@ jobs:
         with:
           node-version: 20
       - name: Run checks
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: \${{ github.event.pull_request.number }}
+          BRANCH: \${{ github.head_ref }}
         run: npx --yes @attalabs/vinaya check --all --diff-only
 `;
 }
 function reviewWorkflow() {
   return `# ${MANAGED_NOTE}
 #
-# The review gate — split from the checks suite so a verdict *comment*
-# re-triggers it. GitHub fires \`issue_comment\` for a new PR comment, a
-# different event from \`pull_request\`; the checks workflow (pull_request only)
-# structurally cannot receive it. A cheap \`contains(..., 'VERDICT')\` guard
-# runs before any checkout cost, so ordinary PR chat spends no billed minute.
+# The required review gate — pull_request events only. The verdict-comment
+# half lives in its own workflow (vinaya-review-verdict.yml): a new PR
+# comment fires a different GitHub event that this pull_request-only
+# workflow structurally cannot receive — and keeping the comment path in a
+# separate FILE means this workflow's runs never list permanently-skipped
+# comment jobs on the PR's checks panel. When a clean final verdict lands,
+# the verdict workflow re-runs this one, so the required check below goes
+# green natively with no manual rerun.
 name: Vinaya Review Gate
 
 on:
   pull_request:
     types: [opened, synchronize, reopened, labeled, unlabeled]
-  issue_comment:
-    types: [created]
 
 jobs:
   vinaya-review:
     name: vinaya review gate
-    if: >
-      github.event_name == 'pull_request' ||
-      (github.event.issue.pull_request != null && contains(github.event.comment.body, 'VERDICT'))
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # This job executes repo content; don't leave the token in
+          # .git/config for scripts to read.
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Review gate
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          # PR_NUMBER is what makes the review-gate check EVALUATE: without
+          # 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 }}
+          BRANCH: \${{ github.head_ref }}
+        run: npx --yes @attalabs/vinaya check --all
+`;
+}
+function reviewVerdictWorkflow() {
+  return `# ${MANAGED_NOTE}
+#
+# The verdict-comment half of the review gate. A reviewer's verdict arrives
+# as a PR comment (\`VERDICT: APPROVE\` / \`VERDICT: PASS\`), which fires
+# GitHub's \`issue_comment\` event — an event the required pull_request
+# workflow cannot receive. This workflow evaluates the gate on that comment
+# and, when the evaluation is clean, RE-RUNS the required workflow so its
+# check goes green natively with no manual rerun. (Writing check-run
+# conclusions directly is no longer possible: GitHub's 2025-02-12 change
+# restricts check-run updates to the owning workflow — re-running is the
+# supported channel.)
+#
+# Privilege split, deliberate: \`evaluate\` checks out and executes repo
+# content and therefore holds NO write permission; \`retrigger\` holds
+# \`actions: write\` but checks out and executes nothing — its only inputs
+# are the evaluator's outputs, resolved via \`gh pr view\` before any repo
+# content ran. A malicious branch can at worst fail its own evaluation.
+name: Vinaya Review Gate (on verdict)
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  evaluate:
+    name: vinaya review gate (verdict check)
+    if: github.event.issue.pull_request != null && contains(github.event.comment.body, 'VERDICT')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+    outputs:
+      branch: \${{ steps.pr.outputs.branch }}
     steps:
       # issue_comment payloads carry no PR head SHA/branch — resolve them
       # before checkout, and check out that exact commit (the event's default
@@ -2244,24 +2467,54 @@ jobs:
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: |
-          if [ "\${{ github.event_name }}" = "pull_request" ]; then
-            NUMBER="\${{ github.event.pull_request.number }}"
-          else
-            NUMBER="\${{ github.event.issue.number }}"
-          fi
+          NUMBER="\${{ github.event.issue.number }}"
+          BRANCH=$(gh pr view "$NUMBER" --repo "\${{ github.repository }}" --json headRefName -q .headRefName)
           SHA=$(gh pr view "$NUMBER" --repo "\${{ github.repository }}" --json headRefOid -q .headRefOid)
+          echo "number=$NUMBER" >> "$GITHUB_OUTPUT"
+          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
           echo "sha=$SHA" >> "$GITHUB_OUTPUT"
       - uses: actions/checkout@v4
         with:
           ref: \${{ steps.pr.outputs.sha }}
+          persist-credentials: false
           fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-      - name: Review gate
+      - name: Review gate (verdict evaluation)
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
-        run: npx --yes @attalabs/vinaya check --all
+          # Same wiring as the required workflow: PR_NUMBER is what makes
+          # the adapter evaluate instead of no-op'ing as "local dev".
+          PR_NUMBER: \${{ steps.pr.outputs.number }}
+          BRANCH: \${{ steps.pr.outputs.branch }}
+        run: npx --yes @attalabs/vinaya check review-gate
+
+  # Executes nothing; consumes only the evaluator's outputs. Fires only on a
+  # clean evaluation — a failed one leaves the standing red untouched.
+  retrigger:
+    name: vinaya review gate (retrigger)
+    if: needs.evaluate.result == 'success'
+    needs: evaluate
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - name: Re-run the required review gate for this branch
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          BRANCH: \${{ needs.evaluate.outputs.branch }}
+        run: |
+          RUN_ID=$(gh run list --repo "\${{ github.repository }}" \\
+            --workflow vinaya-review.yml --branch "$BRANCH" \\
+            --status completed \\
+            --json databaseId,event \\
+            --jq '[.[] | select(.event=="pull_request")][0].databaseId // empty')
+          if [ -z "$RUN_ID" ]; then
+            echo "No completed pull_request run of vinaya-review.yml for branch $BRANCH - nothing to re-run."
+            exit 0
+          fi
+          gh run rerun "$RUN_ID" --repo "\${{ github.repository }}"
 `;
 }
 function archivistWorkflow() {
@@ -2345,14 +2598,18 @@ jobs:
 }
 var HOOK_PREAMBLE = `#!/usr/bin/env sh
 `;
+function ownVersion() {
+  const pkg = JSON.parse(readFileSync3(join6(packageRoot(import.meta.url), "package.json"), "utf-8"));
+  return pkg.version;
+}
 function preCommitBody() {
   return `# Vinaya commit-time gate. Runs the deterministic checks over your staged
 # diff before the commit lands.
-npx --no-install @attalabs/vinaya check --all --diff-only || exit 1`;
+npx --yes @attalabs/vinaya@${ownVersion()} check --all --diff-only || exit 1`;
 }
 function prePushBody() {
   return `# Vinaya pre-push gate. Runs branch/dispatch checks before the push leaves.
-npx --no-install @attalabs/vinaya check --all || exit 1`;
+npx --yes @attalabs/vinaya@${ownVersion()} check --all || exit 1`;
 }
 function doctrinePointer() {
   const doctrineRoot = join6(packageRoot(import.meta.url), "aeg-root");
@@ -2461,6 +2718,12 @@ function buildInitOps(ctx) {
   const hookMode = 493;
   ops.push({ kind: "create-file", path: CHECKS_WORKFLOW_PATH, content: checksWorkflow(), group: "CI workflows" });
   ops.push({ kind: "create-file", path: REVIEW_WORKFLOW_PATH, content: reviewWorkflow(), group: "CI workflows" });
+  ops.push({
+    kind: "create-file",
+    path: REVIEW_VERDICT_WORKFLOW_PATH,
+    content: reviewVerdictWorkflow(),
+    group: "CI workflows"
+  });
   ops.push({ kind: "create-file", path: ARCHIVIST_WORKFLOW_PATH, content: archivistWorkflow(), group: "CI workflows" });
   ops.push({
     kind: "managed-block",
@@ -2519,7 +2782,7 @@ function buildInitProductOps(name) {
 }
 
 // src/lib/env-lint.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
 var ENV_READ_PATTERN = /\b(?:process\.env|Bun\.env|Deno\.env)\b/;
 function checksMissingEnvDeclaration(specs) {
   const names = [];
@@ -2530,7 +2793,7 @@ function checksMissingEnvDeclaration(specs) {
       continue;
     let source;
     try {
-      source = readFileSync3(spec.run, "utf8");
+      source = readFileSync4(spec.run, "utf8");
     } catch {
       continue;
     }
@@ -2544,7 +2807,7 @@ function envDeclarationWarning(name) {
 }
 
 // src/lib/ops.ts
-import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync5, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3, join as join7, resolve, sep } from "node:path";
 var MARKER_NS = "vinaya:managed";
 function markerLines(marker, comment) {
@@ -2574,7 +2837,7 @@ function fileContains(repoRoot, relPath, needle) {
   const p = abs(repoRoot, relPath);
   if (!existsSync7(p))
     return false;
-  return readFileSync4(p, "utf-8").includes(needle);
+  return readFileSync5(p, "utf-8").includes(needle);
 }
 function planInstall(ops, repoRoot, ownedFiles = new Set) {
   const entries = [];
@@ -2684,7 +2947,7 @@ function writeFileWithDirs(target, content, mode) {
 }
 function appendBlock(repoRoot, op) {
   const target = abs(repoRoot, op.path);
-  const existing = readFileSync4(target, "utf-8");
+  const existing = readFileSync5(target, "utf-8");
   const sep2 = existing.endsWith(`
 `) ? `
 ` : `
@@ -2806,7 +3069,7 @@ function planEject(manifest, repoRoot) {
       });
       continue;
     }
-    const content = readFileSync4(p, "utf-8");
+    const content = readFileSync5(p, "utf-8");
     const stripped = stripBlockFromContent(content, b.marker, b.comment);
     const removesHost = stripped !== null && blockStripLeavesEmpty(stripped);
     actions.push({
@@ -2858,7 +3121,7 @@ function applyEject(plan, repoRoot) {
       const p = containedAbs(repoRoot, a.path);
       if (p === null)
         continue;
-      const content = readFileSync4(p, "utf-8");
+      const content = readFileSync5(p, "utf-8");
       const stripped = stripBlockFromContent(content, a.marker, a.comment);
       if (stripped === null)
         continue;
@@ -2881,7 +3144,7 @@ function applyEject(plan, repoRoot) {
 
 // src/commands/doctor.ts
 function readVersion() {
-  const pkg = JSON.parse(readFileSync5(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync6(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
   return pkg.version;
 }
 function realDeps3() {
@@ -2905,7 +3168,7 @@ function readConfig(repoRoot) {
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(p, "utf-8"));
+    raw = JSON.parse(readFileSync6(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -2941,7 +3204,7 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
         findings.push(owned ? error(check, `${op.path} is recorded as vinaya-managed but missing on disk — run \`vinaya upgrade\`.`) : error(check, `${op.path} is not installed — run \`vinaya init\`.`));
         continue;
       }
-      const content = readFileSync5(abs2, "utf-8");
+      const content = readFileSync6(abs2, "utf-8");
       if (!owned) {
         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;
@@ -2964,7 +3227,7 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
         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.`));
         continue;
       }
-      const content = readFileSync5(abs2, "utf-8");
+      const content = readFileSync6(abs2, "utf-8");
       const { begin, end } = markerLines(op.marker, op.comment);
       const hasMarkers = content.includes(begin) && content.includes(end);
       if (!hasMarkers) {
@@ -3007,6 +3270,34 @@ function diagnoseEnvDeclarations(repoRoot, config) {
   }
   return findings;
 }
+function diagnoseCheckClassification(config) {
+  const classification = resolveChecks(coreCheckRegistry(), config?.checks);
+  const findings = [];
+  for (const entry2 of classification.resolved) {
+    if (entry2.state === "overridden")
+      findings.push(warn("checks", overriddenNextMinorWarning(entry2.name)));
+  }
+  for (const failure of classification.failures) {
+    findings.push(warn("checks", bareKeyNextMinorWarning(failure.key)));
+  }
+  return findings;
+}
+function diagnoseGlobalConfigChecks() {
+  if (!existsSync8(GLOBAL_CONFIG_PATH))
+    return [];
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync6(GLOBAL_CONFIG_PATH, "utf-8"));
+  } catch (err) {
+    return [info("checks", `${GLOBAL_CONFIG_PATH} is invalid JSON — ${err.message}`)];
+  }
+  const parsed = VinayaConfigSchema.safeParse(raw);
+  if (!parsed.success)
+    return [];
+  if (!parsed.data.checks || Object.keys(parsed.data.checks).length === 0)
+    return [];
+  return [warn("checks", globalChecksIgnoredWarning(GLOBAL_CONFIG_PATH))];
+}
 async function diagnoseEnvironment(deps, hasDrift) {
   const findings = [];
   const auth = await deps.ghAuthStatus();
@@ -3077,6 +3368,8 @@ async function runDoctor(args, deps) {
     findings.push(...diagnoseCustomChecks(repo.repoRoot, configRead.config));
   }
   findings.push(...diagnoseEnvDeclarations(repo.repoRoot, configRead.kind === "ok" ? configRead.config : null));
+  findings.push(...diagnoseCheckClassification(configRead.kind === "ok" ? configRead.config : null));
+  findings.push(...diagnoseGlobalConfigChecks());
   findings.push(...await diagnoseEnvironment(deps, hasDrift));
   findings.push(await diagnoseBranchProtection(deps, repo.owner, repo.repo));
   const healthy = findings.every((f) => f.severity === "ok" || f.severity === "info");
@@ -3092,7 +3385,7 @@ async function doctorCommand(args) {
 }
 
 // src/commands/eject.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:fs";
 import { join as join9 } from "node:path";
 
 // src/lib/prompt.ts
@@ -3179,7 +3472,7 @@ function readManifest(repoRoot) {
     return { kind: "none" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync6(p, "utf-8"));
+    raw = JSON.parse(readFileSync7(p, "utf-8"));
   } catch (err) {
     return { kind: "orphan", reason: `vinaya.config.json is not valid JSON: ${err.message}` };
   }
@@ -3262,7 +3555,7 @@ async function ejectCommand(args) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join10 } from "node:path";
 function realDeps5() {
   return {
@@ -3287,14 +3580,14 @@ function readManifest2(repoRoot) {
   if (!existsSync10(p))
     return null;
   try {
-    return VinayaConfigSchema.parse(JSON.parse(readFileSync7(p, "utf-8"))).managed ?? null;
+    return VinayaConfigSchema.parse(JSON.parse(readFileSync8(p, "utf-8"))).managed ?? null;
   } catch {
     return null;
   }
 }
 function writeManifest(repoRoot, manifest) {
   const configAbs = join10(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync7(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync8(configAbs, "utf-8"));
   writeFileSync4(configAbs, `${JSON.stringify({ ...seed, managed: manifest }, null, 2)}
 `, "utf-8");
 }
@@ -3434,7 +3727,7 @@ import { execFileSync as execFileSync6 } from "node:child_process";
 
 // src/lib/forge-write.ts
 import { mkdtempSync, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "node:fs";
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as join11 } from "node:path";
 class ForgeArgError extends Error {
@@ -3446,13 +3739,13 @@ function locateBody(args) {
       const p = args[i + 1];
       if (!p)
         throw new ForgeArgError("`--body-file` was given with no path.");
-      return { body: readFileSync8(p, "utf8"), source: { kind: "file", argIndex: i + 1, inlineForm: false } };
+      return { body: readFileSync9(p, "utf8"), source: { kind: "file", argIndex: i + 1, inlineForm: false } };
     }
     if (a.startsWith("--body-file=")) {
       const p = a.slice("--body-file=".length);
       if (!p)
         throw new ForgeArgError("`--body-file=` was given with no path.");
-      return { body: readFileSync8(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
+      return { body: readFileSync9(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
     }
     if (a === "--body" || a === "-b") {
       const v = args[i + 1];
@@ -3742,7 +4035,7 @@ function issueEditCommand(args) {
 }
 
 // src/commands/new-check.ts
-import { chmodSync as chmodSync2, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join12 } from "node:path";
 var TEMPLATE_PATH = join12(packageRoot(import.meta.url), "templates", "custom-check.template.ts");
 var CHECKS_DIR = join12("scripts", "vinaya-checks");
@@ -3761,7 +4054,7 @@ function newCheckCommand(args) {
     console.error(`Error: ${targetPath} already exists.`);
     process.exit(1);
   }
-  const template = readFileSync9(TEMPLATE_PATH, "utf-8");
+  const template = readFileSync10(TEMPLATE_PATH, "utf-8");
   const contents = template.split("{{CHECK_NAME}}").join(name);
   writeFileSync6(targetPath, contents, "utf-8");
   chmodSync2(targetPath, 493);
@@ -3925,7 +4218,7 @@ function prEditCommand(args) {
 
 // src/commands/studio.ts
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync11 } from "node:fs";
 import { dirname as dirname4, join as join13 } from "node:path";
 function resolveStudioTarget(cwd) {
   let dir = cwd;
@@ -3934,7 +4227,7 @@ function resolveStudioTarget(cwd) {
     const pkgPath = join13(webDir, "package.json");
     if (existsSync12(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
         if (pkg.name === "@atta/vinaya-web") {
           return { kind: "workspace", webDir };
         }
@@ -3967,7 +4260,7 @@ async function runStudio(cwd, args) {
 }
 
 // src/commands/upgrade.ts
-import { existsSync as existsSync13, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join14 } from "node:path";
 function realDeps6() {
   return {
@@ -3989,7 +4282,7 @@ function readManifest3(repoRoot) {
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync11(p, "utf-8"));
+    raw = JSON.parse(readFileSync12(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -4006,7 +4299,7 @@ function readManifest3(repoRoot) {
 }
 function writeManifestVersion(repoRoot, manifest) {
   const configAbs = join14(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync11(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync12(configAbs, "utf-8"));
   const updated = { ...manifest, version: MANAGED_MANIFEST_VERSION };
   writeFileSync7(configAbs, `${JSON.stringify({ ...seed, managed: updated }, null, 2)}
 `, "utf-8");
@@ -4030,7 +4323,7 @@ function planUpgrade(ops, repoRoot, manifest) {
       } else if (!exists) {
         action = "recreate";
         hasChanges = true;
-      } else if (readFileSync11(abs2, "utf-8") !== op.content) {
+      } else if (readFileSync12(abs2, "utf-8") !== op.content) {
         action = "regenerate";
         hasChanges = true;
       } else {
@@ -4047,7 +4340,7 @@ function planUpgrade(ops, repoRoot, manifest) {
         action = "recreate-host";
         hasChanges = true;
       } else {
-        const content = readFileSync11(abs2, "utf-8");
+        const content = readFileSync12(abs2, "utf-8");
         const { begin, end } = markerLines(op.marker, op.comment);
         if (!(content.includes(begin) && content.includes(end))) {
           action = "recreate-append";
@@ -4124,7 +4417,7 @@ function renderUpgradeDiff(plan) {
 }
 function regenerateBlock(repoRoot, op) {
   const abs2 = join14(repoRoot, op.path);
-  const content = readFileSync11(abs2, "utf-8");
+  const content = readFileSync12(abs2, "utf-8");
   const stripped = stripBlockFromContent(content, op.marker, op.comment);
   if (stripped !== null) {
     writeFileSync7(abs2, stripped.endsWith(`
@@ -4363,10 +4656,15 @@ 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: "--parallel[=n]", description: "Concurrency cap (default: cpu-derived)" }
+      { flag: "--parallel[=n]", description: "Concurrency cap (default: cpu-derived)" },
+      {
+        flag: "--plan",
+        description: "Print the resolved check registry (default/overridden/additive) without running anything"
+      }
     ],
     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."
+      "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."
     ],
     status: "shipped"
   },
@@ -4544,7 +4842,7 @@ function printHelp() {
 // src/index.ts
 var PACKAGE_ROOT = join15(dirname5(fileURLToPath2(import.meta.url)), "..");
 function readVersion2() {
-  const pkg = JSON.parse(readFileSync12(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync13(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
   return pkg.version;
 }
 var [, , command, ...args] = process.argv;