@attalabs/vinaya 0.2.0 → 0.4.0

package/dist/index.js

@@ -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";
@@ -1470,11 +1534,79 @@ function installSignalForwarding() {
   process.on("SIGINT", () => forward("SIGINT", 130));
   process.on("SIGTERM", () => forward("SIGTERM", 143));
 }
-async function runOne(spec, timeoutMs) {
+var ENV_BASELINE_KEYS = ["PATH", "LANG", "HOME", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "TMPDIR"];
+function buildCheckEnv(env, callerEnv = process.env) {
+  const out = {};
+  for (const key of ENV_BASELINE_KEYS) {
+    const value = callerEnv[key];
+    if (value !== undefined)
+      out[key] = value;
+  }
+  if (!env)
+    return out;
+  for (const [key, decl] of Object.entries(env)) {
+    if (decl === true || typeof decl === "object" && "optional" in decl) {
+      const value = callerEnv[key];
+      if (value !== undefined)
+        out[key] = value;
+    } else if (typeof decl === "object" && "anyOf" in decl) {
+      for (const member of decl.anyOf) {
+        const value = callerEnv[member];
+        if (value !== undefined)
+          out[member] = value;
+      }
+    } else if (typeof decl === "string") {
+      out[key] = decl;
+    }
+  }
+  return out;
+}
+function missingEnvErrors(spec, callerEnv) {
+  if (!spec.env)
+    return [];
+  const errors = [];
+  for (const [key, decl] of Object.entries(spec.env)) {
+    if (decl === true) {
+      if (callerEnv[key] === undefined) {
+        errors.push({
+          schema: CHECK_SCHEMA_VERSION,
+          check: spec.name,
+          severity: "error",
+          message: `Could not run check "${spec.name}": required environment variable \`${key}\` is not set.`,
+          agent_recovery_prompt: `Set \`${key}\` in the environment before re-running \`vinaya check ${spec.name}\`, or relax its declaration to \`{ optional: true }\` in its \`env\` registration if the check can tolerate absence.`
+        });
+      }
+    } else if (typeof decl === "object" && decl !== null && "anyOf" in decl) {
+      const satisfied = decl.anyOf.some((member) => callerEnv[member] !== undefined);
+      if (!satisfied) {
+        errors.push({
+          schema: CHECK_SCHEMA_VERSION,
+          check: spec.name,
+          severity: "error",
+          message: `Could not run check "${spec.name}": none of its required environment variables (${decl.anyOf.join(", ")}) are set.`,
+          agent_recovery_prompt: `Set one of ${decl.anyOf.join(", ")} in the environment before re-running \`vinaya check ${spec.name}\`.`
+        });
+      }
+    }
+  }
+  return errors;
+}
+async function runOne(spec, timeoutMs, callerEnv) {
   const start = performance.now();
+  const envErrors = missingEnvErrors(spec, callerEnv);
+  if (envErrors.length > 0) {
+    return {
+      name: spec.name,
+      status: "error",
+      exitCode: null,
+      errors: envErrors,
+      durationMs: performance.now() - start
+    };
+  }
   const proc = spawn(spec.run, spec.args ?? [], {
     stdio: ["ignore", "pipe", "pipe"],
-    detached: true
+    detached: true,
+    env: buildCheckEnv(spec.env, callerEnv)
   });
   function killTree(signal) {
     const pid = proc.pid;
@@ -1590,6 +1722,7 @@ async function runOne(spec, timeoutMs) {
   return { name: spec.name, status, exitCode, errors, durationMs };
 }
 async function runChecks(specs, opts) {
+  const callerEnv = opts.callerEnv ?? process.env;
   const results = new Array(specs.length);
   const toRun = [];
   for (let i = 0;i < specs.length; i++) {
@@ -1606,7 +1739,7 @@ async function runChecks(specs, opts) {
       const idx = toRun[cursor];
       cursor += 1;
       const spec = specs[idx];
-      results[idx] = await runOne(spec, spec.timeoutMs ?? opts.defaultTimeoutMs);
+      results[idx] = await runOne(spec, spec.timeoutMs ?? opts.defaultTimeoutMs, callerEnv);
     }
   };
   const workerCount = Math.max(1, Math.min(opts.parallel, toRun.length));
@@ -1763,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)
@@ -1778,32 +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 };
-}
-
-// src/lib/env-lint.ts
-import { existsSync as existsSync5, readFileSync as readFileSync2 } from "node:fs";
-var ENV_READ_PATTERN = /\b(?:process\.env|Bun\.env|Deno\.env)\b/;
-function checksMissingEnvDeclaration(specs) {
-  const names = [];
-  for (const spec of specs) {
-    if (spec.env)
-      continue;
-    if (!existsSync5(spec.run))
-      continue;
-    let source;
-    try {
-      source = readFileSync2(spec.run, "utf8");
-    } catch {
-      continue;
-    }
-    if (ENV_READ_PATTERN.test(source))
-      names.push(spec.name);
-  }
-  return names;
-}
-function envDeclarationWarning(name) {
-  return `check "${name}" reads environment variables directly but declares no \`env\` — it will lose environment access at the next minor. Declare \`env\` for it (CheckSpec['env'] in src/checks/contract.ts, or vinaya.config.json's checks.<name>.env).`;
+  return { ok: true, config: stripGlobalChecks(parsed.data, path) };
 }
 
 // src/commands/check.ts
@@ -1843,34 +1960,118 @@ 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) {
     console.error(`Unknown check: ${requestedName}`);
     process.exit(2);
   }
-  for (const name of checksMissingEnvDeclaration(specsToRun)) {
-    console.error(`⚠ ${envDeclarationWarning(name)}`);
-  }
   const changed = diffOnly ? changedFiles() : null;
   const outcomes = specsToRun.length > 0 ? await runChecks(specsToRun, {
     parallel: requestedParallel ?? defaultParallelism(),
@@ -1894,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);
@@ -1901,7 +2103,7 @@ async function checkCommand(args) {
 
 // src/commands/demo.ts
 import { execFileSync as execFileSync5, spawnSync } from "node:child_process";
-import { existsSync as existsSync6, readFileSync as readFileSync3, rmSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync2, rmSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { isAbsolute, join as join5 } from "node:path";
 var DEMO_BRANCH_PREFIX = "vinaya/demo-break-";
 var FIXTURE_PATH = ".vinaya-demo-brief.md";
@@ -1944,9 +2146,9 @@ function gitDirAbs(repoRoot) {
 function recoverFromCrash(repoRoot, statePath) {
   const currentBranch = currentBranchName(repoRoot);
   let state = null;
-  if (existsSync6(statePath)) {
+  if (existsSync5(statePath)) {
     try {
-      state = JSON.parse(readFileSync3(statePath, "utf-8"));
+      state = JSON.parse(readFileSync2(statePath, "utf-8"));
     } catch {
       state = null;
     }
@@ -2016,14 +2218,14 @@ function cleanup(repoRoot, originalBranch, demoBranch, statePath) {
   gitCapture(repoRoot, ["clean", "-fd"]);
   gitCapture(repoRoot, ["checkout", originalBranch]);
   gitCapture(repoRoot, ["branch", "-D", demoBranch]);
-  if (existsSync6(statePath))
+  if (existsSync5(statePath))
     rmSync(statePath, { force: true });
 }
 async function runDemoBreak(repoRoot, args) {
   const keep = args.includes("--keep");
   const hookDir = resolveHookDir(repoRoot);
   const hookPath = join5(repoRoot, hookDir, "pre-commit");
-  if (!existsSync6(hookPath)) {
+  if (!existsSync5(hookPath)) {
     console.error("Vinaya hooks are not installed in this repo. Run `vinaya init` first.");
     return 1;
   }
@@ -2081,7 +2283,7 @@ Attempting to commit…
   process.stdout.write(`✓ Commit passed — the fix worked.
 `);
   if (keep) {
-    if (existsSync6(statePath))
+    if (existsSync5(statePath))
       unlinkSync(statePath);
     process.stdout.write(`
 --keep: leaving \`${demoBranch}\` checked out for you to inspect. Clean up with:
@@ -2117,6 +2319,7 @@ 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() {
@@ -2156,6 +2359,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      pull-requests: read
+      issues: read
     steps:
       - uses: actions/checkout@v4
         with:
@@ -2164,36 +2369,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
@@ -2203,24 +2466,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() {
@@ -2420,6 +2713,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",
@@ -2477,6 +2776,31 @@ function buildInitProductOps(name) {
   ];
 }
 
+// src/lib/env-lint.ts
+import { existsSync as existsSync6, readFileSync as readFileSync3 } from "node:fs";
+var ENV_READ_PATTERN = /\b(?:process\.env|Bun\.env|Deno\.env)\b/;
+function checksMissingEnvDeclaration(specs) {
+  const names = [];
+  for (const spec of specs) {
+    if (spec.env)
+      continue;
+    if (!existsSync6(spec.run))
+      continue;
+    let source;
+    try {
+      source = readFileSync3(spec.run, "utf8");
+    } catch {
+      continue;
+    }
+    if (ENV_READ_PATTERN.test(source))
+      names.push(spec.name);
+  }
+  return names;
+}
+function envDeclarationWarning(name) {
+  return `check "${name}" reads environment variables directly but declares no \`env\` — it will lose environment access at the next minor. Declare \`env\` for it (CheckSpec['env'] in src/checks/contract.ts, or vinaya.config.json's checks.<name>.env).`;
+}
+
 // 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 { dirname as dirname3, join as join7, resolve, sep } from "node:path";
@@ -2941,6 +3265,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(readFileSync5(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();
@@ -3011,6 +3363,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");
@@ -4297,10 +4651,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: [
-      "Warns (stderr, every output mode, never affecting the exit code) for any check whose executable reads `process.env`/`Bun.env`/`Deno.env` directly with no `env` declared on its `CheckSpec` — those checks will lose environment access once the env allowlist is wired as the spawn default in a later minor. Declare `env` (a core check's own registration, or `vinaya.config.json`'s `checks.<name>.env` for a custom one) to silence the warning ahead of that flip."
+      "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"
   },