@attalabs/vinaya 0.1.2 → 0.2.0

package/aeg-root/enforcement.md

@@ -44,6 +44,7 @@ The same check implementations run at ring 0 and ring 1 — one codebase, two en
 | Starting the Dig (before authoring a brief) / starting Step 0 (before executing one) / **every push on a task branch before its PR exists** | Ever started work only to find out halfway it was blocked on something else? | hook | Refuses to start work until every precondition for the task is checked live and found clear. | **`verify-dispatch` CLI** (`packages/aeg-core/bin/verify-dispatch.ts` — mandated by `roles/developer.md` and `skills/brief-authoring/SKILL.md`; **now also hook-automated** — task 25) | Every dispatch precondition is re-checked live against the forge (the task's row/Issue are derived directly from a Milestone + `vinaya/tranche:<slug>`-labeled Issues as of the forge-native migration — no `origin/main` file read involved; leftover-branch detection still fetches `origin/main` for its own commit-count comparison): the task's row and Issue exist; the Issue passes the rationale gate; every `depends-on` PR is merged and no `conflicts-with` PR is open/in-flight; every named project's prior tranche is archived. (2026-07-13: the immediately-prior task's three-predicate archival bar — the row-adjacency predicate — was removed once the provenance-posting signal it existed to protect became automated.) A `NOT READY` result is a stop condition. Every `gh` call this script makes carries an explicit `-R <owner>/<repo>` (task 23) — from a linked `git worktree add` checkout, an untargeted `gh issue list`/`gh issue view`/`gh pr list` silently scopes to the wrong repo (or returns nothing), which previously produced false prior-tranche-archival blockers. **`.husky/pre-push`** now runs this gate itself on a `task/*/*` branch's first push (before a PR exists), refusing on genuine `NOT READY` and failing OPEN — loudly — when a `gh auth status` reachability probe fails or `verify-dispatch`'s own repo/token resolution fails (task 18's fail-open precedent). The gate reads only the `dispatch-readiness:` predicate, not verify-dispatch's combined exit code, which also folds in `leftover-detection` (a pre-Step-0 "safe to branch fresh" advisory that would otherwise false-block every push after the first on a task legitimately mid-flight — discovered live while building this gate). Once a PR exists, later pushes skip the gate: dispatch was already validated once. | `packages/aeg-core/bin/verify-dispatch.ts` |
 | Opening a task PR whose surface includes real code | Ever had a PR's description quietly stop matching what the code does? | event | Refuses a code-carrying pull request whose description no longer matches what it changes. | **Brief Validation — `checkPremiseCoverage`** | The PR body carries a `Premise:` block with at least one assertion (`contains`/`absent`/`sha256`) whose path falls inside the task's surface map — re-assertable at any point via `verify-dispatch --premise` or `verify-task`. | `packages/aeg-core/src/brief-validation.ts` |
 | Opening a task PR (final self-check before creation) | Ever opened a PR and only then discovered the tests were failing? | event | Runs the whole exit check before a pull request is created, so failures surface first. | **`verify-task` CLI** (`packages/aeg-core/bin/verify-task.ts` — mandated by `roles/developer.md`; **now also hook-automated** — task 25) | Typecheck, lint, tests, build, `verify-docs --pr`, and the premise coverage/recheck pair all pass, as one summary, against the PR's actual diff, before `open-pr.ts` is invoked. **`open-pr.ts` now runs this composite itself** for task branches (via `gatePlanForBranch`), invoked wholesale rather than partially re-implemented — non-task branches are unaffected (byte-identical gate set). `verify-docs --pr` runs twice on a task-branch PR-open as an accepted, measured overlap (~4s with a warm turbo cache). | `packages/aeg-core/bin/verify-task.ts` |
+| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **Warn status today (task 2):** the grammar (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) and the construction function exist and are unit-tested, but `runOne`'s `spawn()` call still passes no `env` override — every check still inherits the full parent environment, unchanged. `vinaya check` prints one warning line per check whose bin reads `process.env`/`Bun.env`/`Deno.env` with no `env` declared (fires identically at the ring-0 pre-push hook and ring-1 CI, since both invoke the same `vinaya check --all`); `vinaya doctor` carries the same diagnostic permanently. All 15 core checks in `registry.ts` carry an audited declaration. **Once flipped (task 3, a later minor):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration explicitly forwards — an undeclared variable a check's own code reads becomes genuinely invisible to it, not merely warned about. | `apps/vinaya/cli/src/checks/runner.ts` |
 
 **Documentation coverage, specifically** (a historical pain point): the code→document ownership rule is enforced at *two* prevention chokepoints — at every push (over the branch's cumulative change set) and again at pull-request creation and editing. A change to owned code cannot be published, let alone turned into a pull request, without its owning document.
 

package/dist/checks/bin/check-coherence.js

@@ -2773,7 +2773,7 @@ var CHECK_NAME = "coherence";
 var execFileAsync4 = promisify4(execFile4);
 function git(args) {
   try {
-    return execFileSync2("git", args, { encoding: "utf8" }).trim();
+    return execFileSync2("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch {
     return "";
   }

package/dist/checks/bin/check-dispatch-readiness.js

@@ -2773,7 +2773,7 @@ var CHECK_NAME = "dispatch-readiness";
 var execFileAsync4 = promisify4(execFile4);
 function git(args) {
   try {
-    return execFileSync2("git", args, { encoding: "utf8" }).trim();
+    return execFileSync2("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch {
     return "";
   }

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync11 } from "node:fs";
+import { readFileSync as readFileSync12 } from "node:fs";
 import { dirname as dirname5, join as join15 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -1276,91 +1276,153 @@ function coreCheckRegistry() {
       name: "brief-shape",
       run: bin("check-brief-shape"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: { PR_BODY: { optional: true } }
     },
     {
       name: "doc-coverage",
       run: bin("check-doc-coverage"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BASE_SHA: { optional: true },
+        PR_BODY: { optional: true },
+        PR_BODY_FILE: { optional: true },
+        PR_LABELS: { optional: true },
+        WAIVER_LABEL_ACTOR: { optional: true }
+      }
     },
     {
       name: "coherence",
       run: bin("check-coherence"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "dispatch-readiness",
       run: bin("check-dispatch-readiness"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "closes-n",
       run: bin("check-closes-n"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BRANCH: { optional: true },
+        PR_BODY: { optional: true },
+        AEG_REPO: { optional: true }
+      }
     },
     {
       name: "single-plan-pr",
       run: bin("check-single-plan-pr"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BASE_SHA: { optional: true },
+        PR_NUMBER: { optional: true }
+      }
     },
     {
       name: "test-plan",
       run: bin("check-test-plan"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        PR_BODY: { optional: true },
+        BRANCH: { optional: true }
+      }
     },
     {
       name: "no-disk-state",
       run: bin("check-no-disk-state"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: { BASE_SHA: { optional: true } }
     },
     {
       name: "registry-gates",
       run: bin("check-registry-gates"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: { AEG_REPO: { optional: true } }
     },
     {
       name: "review-gate",
       run: bin("check-review-gate"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        PR_NUMBER: { optional: true }
+      }
     },
     {
       name: "branch-topology",
       run: bin("check-branch-topology"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        AEG_REPO: { optional: true }
+      }
     },
     {
       name: "dead-branch-push",
       run: bin("check-dead-branch-push"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: { BRANCH: { optional: true } }
     },
     {
       name: "first-push-dispatch",
       run: bin("check-first-push-dispatch"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "doc-coverage-push",
       run: bin("check-doc-coverage-push"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        OVERRIDE_DOCS: { optional: true },
+        BASE_SHA: { optional: true },
+        PR_BODY: { optional: true },
+        PR_BODY_FILE: { optional: true },
+        PR_LABELS: { optional: true },
+        WAIVER_LABEL_ACTOR: { optional: true }
+      }
     },
     {
       name: "issue-assignment",
       run: bin("check-issue-assignment"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true }
+      }
     }
   ];
 }
@@ -1390,17 +1452,70 @@ function shouldSkip(spec, opts) {
   return !opts.changedFiles.some((f) => regexes.some((re) => re.test(f)));
 }
 var KILL_GRACE_MS = 2000;
+var activeKillers = new Set;
+var signalForwardingInstalled = false;
+function installSignalForwarding() {
+  if (signalForwardingInstalled)
+    return;
+  signalForwardingInstalled = true;
+  const forward = (_signal, exitCode) => {
+    for (const kill of activeKillers)
+      kill("SIGTERM");
+    setTimeout(() => {
+      for (const kill of activeKillers)
+        kill("SIGKILL");
+      process.exit(exitCode);
+    }, KILL_GRACE_MS);
+  };
+  process.on("SIGINT", () => forward("SIGINT", 130));
+  process.on("SIGTERM", () => forward("SIGTERM", 143));
+}
 async function runOne(spec, timeoutMs) {
   const start = performance.now();
   const proc = spawn(spec.run, spec.args ?? [], {
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true
   });
+  function killTree(signal) {
+    const pid = proc.pid;
+    if (pid === undefined)
+      return;
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      try {
+        proc.kill(signal);
+      } catch {}
+    }
+  }
+  installSignalForwarding();
+  activeKillers.add(killTree);
+  function groupStillAlive(pid) {
+    try {
+      process.kill(-pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   let timedOut = false;
-  let killTimer;
+  let escalationDone = Promise.resolve();
+  let cancelEscalation;
   const timer = setTimeout(() => {
     timedOut = true;
-    proc.kill("SIGTERM");
-    killTimer = setTimeout(() => proc.kill("SIGKILL"), KILL_GRACE_MS);
+    killTree("SIGTERM");
+    escalationDone = new Promise((resolve) => {
+      const graceTimer = setTimeout(() => {
+        const pid = proc.pid;
+        if (pid !== undefined && groupStillAlive(pid))
+          killTree("SIGKILL");
+        resolve();
+      }, KILL_GRACE_MS);
+      cancelEscalation = () => {
+        clearTimeout(graceTimer);
+        resolve();
+      };
+    });
   }, timeoutMs);
   let stderrText = "";
   proc.stderr.setEncoding("utf-8");
@@ -1417,7 +1532,13 @@ async function runOne(spec, timeoutMs) {
     });
   });
   clearTimeout(timer);
-  clearTimeout(killTimer);
+  if (timedOut) {
+    const pid = proc.pid;
+    if (pid === undefined || !groupStillAlive(pid))
+      cancelEscalation?.();
+    await escalationDone;
+  }
+  activeKillers.delete(killTree);
   const durationMs = performance.now() - start;
   if (timedOut) {
     return { name: spec.name, status: "timeout", exitCode: null, errors: [], durationMs };
@@ -1498,13 +1619,70 @@ import { existsSync as existsSync4, mkdirSync, readFileSync, writeFileSync } fro
 import { homedir } from "node:os";
 import { dirname as dirname2, join as join4 } from "node:path";
 import { z } from "zod";
+var EnvEntrySchema = z.union([
+  z.literal(true),
+  z.object({ optional: z.literal(true) }),
+  z.object({ anyOf: z.array(z.string()).min(2) }),
+  z.string()
+]);
 var CheckEntrySchema = z.object({
   run: z.string(),
   scope: z.enum(["diff", "full"]),
   include: z.array(z.string()).optional(),
   args: z.array(z.string()).optional(),
-  timeoutMs: z.number().optional()
+  timeoutMs: z.number().optional(),
+  env: z.record(z.string(), EnvEntrySchema).optional()
+}).superRefine((entry2, ctx) => {
+  if (!entry2.env)
+    return;
+  for (const [key, value] of Object.entries(entry2.env)) {
+    if (typeof value !== "object" || value === null || !("anyOf" in value))
+      continue;
+    const members = value.anyOf;
+    if (new Set(members).size !== members.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `env.${key}.anyOf has duplicate members`,
+        path: ["env", key, "anyOf"]
+      });
+    }
+    if (!members.includes(key)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `env.${key}.anyOf must include "${key}" itself as a member`,
+        path: ["env", key, "anyOf"]
+      });
+    }
+  }
 });
+var HIGH_ENTROPY_MIN_LENGTH = 20;
+function looksHighEntropy(value) {
+  if (value.length < HIGH_ENTROPY_MIN_LENGTH)
+    return false;
+  if (/\s/.test(value))
+    return false;
+  const classes = [/[a-z]/.test(value), /[A-Z]/.test(value), /[0-9]/.test(value)].filter(Boolean).length;
+  return classes >= 2;
+}
+function lintEnvDeclarations(checks) {
+  const warnings = [];
+  if (!checks)
+    return warnings;
+  for (const [checkName, entry2] of Object.entries(checks)) {
+    if (!entry2.env)
+      continue;
+    for (const [key, value] of Object.entries(entry2.env)) {
+      if (typeof value !== "string")
+        continue;
+      if (value === "true" || value === "false") {
+        warnings.push(`check "${checkName}" env.${key} is the literal string "${value}" — did you mean the boolean form \`${key}: true\` (forward the caller's value) rather than a hardcoded literal?`);
+      } else if (looksHighEntropy(value)) {
+        warnings.push(`check "${checkName}" env.${key} looks like a high-entropy literal (possible secret committed to config) — env declarations should reference variable NAMES the caller sets, not literal secret values.`);
+      }
+    }
+  }
+  return warnings;
+}
 var BRIEF_BUILTINS = [
   "tier",
   "testPlan",
@@ -1603,6 +1781,31 @@ function loadConfigChecked() {
   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).`;
+}
+
 // src/commands/check.ts
 function git(args) {
   try {
@@ -1665,6 +1868,9 @@ async function checkCommand(args) {
     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(),
@@ -1695,7 +1901,7 @@ async function checkCommand(args) {
 
 // src/commands/demo.ts
 import { execFileSync as execFileSync5, spawnSync } from "node:child_process";
-import { existsSync as existsSync5, readFileSync as readFileSync2, rmSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync3, 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";
@@ -1738,9 +1944,9 @@ function gitDirAbs(repoRoot) {
 function recoverFromCrash(repoRoot, statePath) {
   const currentBranch = currentBranchName(repoRoot);
   let state = null;
-  if (existsSync5(statePath)) {
+  if (existsSync6(statePath)) {
     try {
-      state = JSON.parse(readFileSync2(statePath, "utf-8"));
+      state = JSON.parse(readFileSync3(statePath, "utf-8"));
     } catch {
       state = null;
     }
@@ -1810,14 +2016,14 @@ function cleanup(repoRoot, originalBranch, demoBranch, statePath) {
   gitCapture(repoRoot, ["clean", "-fd"]);
   gitCapture(repoRoot, ["checkout", originalBranch]);
   gitCapture(repoRoot, ["branch", "-D", demoBranch]);
-  if (existsSync5(statePath))
+  if (existsSync6(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 (!existsSync5(hookPath)) {
+  if (!existsSync6(hookPath)) {
     console.error("Vinaya hooks are not installed in this repo. Run `vinaya init` first.");
     return 1;
   }
@@ -1875,7 +2081,7 @@ Attempting to commit…
   process.stdout.write(`✓ Commit passed — the fix worked.
 `);
   if (keep) {
-    if (existsSync5(statePath))
+    if (existsSync6(statePath))
       unlinkSync(statePath);
     process.stdout.write(`
 --keep: leaving \`${demoBranch}\` checked out for you to inspect. Clean up with:
@@ -1902,7 +2108,7 @@ async function demoBreakCommand(args) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync7, readFileSync as readFileSync4, statSync } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync5, statSync } from "node:fs";
 import { join as join8 } from "node:path";
 
 // src/lib/artifacts.ts
@@ -2272,7 +2478,7 @@ function buildInitProductOps(name) {
 }
 
 // src/lib/ops.ts
-import { chmodSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
+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";
 var MARKER_NS = "vinaya:managed";
 function markerLines(marker, comment) {
@@ -2300,9 +2506,9 @@ function containedAbs(repoRoot, relPath) {
 }
 function fileContains(repoRoot, relPath, needle) {
   const p = abs(repoRoot, relPath);
-  if (!existsSync6(p))
+  if (!existsSync7(p))
     return false;
-  return readFileSync3(p, "utf-8").includes(needle);
+  return readFileSync4(p, "utf-8").includes(needle);
 }
 function planInstall(ops, repoRoot, ownedFiles = new Set) {
   const entries = [];
@@ -2310,7 +2516,7 @@ function planInstall(ops, repoRoot, ownedFiles = new Set) {
   for (const op of ops) {
     switch (op.kind) {
       case "create-file": {
-        const exists = existsSync6(abs(repoRoot, op.path));
+        const exists = existsSync7(abs(repoRoot, op.path));
         let action;
         if (!exists)
           action = "create";
@@ -2328,7 +2534,7 @@ function planInstall(ops, repoRoot, ownedFiles = new Set) {
         let action;
         if (fileContains(repoRoot, op.path, begin))
           action = "skip-present";
-        else if (existsSync6(abs(repoRoot, op.path)))
+        else if (existsSync7(abs(repoRoot, op.path)))
           action = "append";
         else
           action = "create-host";
@@ -2412,7 +2618,7 @@ function writeFileWithDirs(target, content, mode) {
 }
 function appendBlock(repoRoot, op) {
   const target = abs(repoRoot, op.path);
-  const existing = readFileSync3(target, "utf-8");
+  const existing = readFileSync4(target, "utf-8");
   const sep2 = existing.endsWith(`
 `) ? `
 ` : `
@@ -2523,7 +2729,7 @@ function planEject(manifest, repoRoot) {
       escapes.push(b.path);
       continue;
     }
-    if (!existsSync6(p)) {
+    if (!existsSync7(p)) {
       actions.push({
         kind: "strip-block",
         path: b.path,
@@ -2534,7 +2740,7 @@ function planEject(manifest, repoRoot) {
       });
       continue;
     }
-    const content = readFileSync3(p, "utf-8");
+    const content = readFileSync4(p, "utf-8");
     const stripped = stripBlockFromContent(content, b.marker, b.comment);
     const removesHost = stripped !== null && blockStripLeavesEmpty(stripped);
     actions.push({
@@ -2552,7 +2758,7 @@ function planEject(manifest, repoRoot) {
       escapes.push(f);
       continue;
     }
-    actions.push({ kind: "delete-file", path: f, present: existsSync6(p) });
+    actions.push({ kind: "delete-file", path: f, present: existsSync7(p) });
   }
   for (const name of manifest.labels) {
     actions.push({ kind: "report-label", name });
@@ -2586,7 +2792,7 @@ function applyEject(plan, repoRoot) {
       const p = containedAbs(repoRoot, a.path);
       if (p === null)
         continue;
-      const content = readFileSync3(p, "utf-8");
+      const content = readFileSync4(p, "utf-8");
       const stripped = stripBlockFromContent(content, a.marker, a.comment);
       if (stripped === null)
         continue;
@@ -2609,7 +2815,7 @@ function applyEject(plan, repoRoot) {
 
 // src/commands/doctor.ts
 function readVersion() {
-  const pkg = JSON.parse(readFileSync4(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync5(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
   return pkg.version;
 }
 function realDeps3() {
@@ -2629,11 +2835,11 @@ var warn = (check, message) => ({ check, severity: "warn", message });
 var error = (check, message) => ({ check, severity: "error", message });
 function readConfig(repoRoot) {
   const p = join8(repoRoot, CONFIG_PATH);
-  if (!existsSync7(p))
+  if (!existsSync8(p))
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync4(p, "utf-8"));
+    raw = JSON.parse(readFileSync5(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -2663,13 +2869,13 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
     if (op.kind === "create-file") {
       const check = labelForPath(op.path);
       const abs2 = join8(repoRoot, op.path);
-      const exists = existsSync7(abs2);
+      const exists = existsSync8(abs2);
       const owned = ownedFiles.has(op.path);
       if (!exists) {
         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 = readFileSync4(abs2, "utf-8");
+      const content = readFileSync5(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;
@@ -2688,11 +2894,11 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
       const check = "hooks";
       const abs2 = join8(repoRoot, op.path);
       const owned = ownedBlocks.has(blockKey(op.path, op.marker));
-      if (!existsSync7(abs2)) {
+      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.`));
         continue;
       }
-      const content = readFileSync4(abs2, "utf-8");
+      const content = readFileSync5(abs2, "utf-8");
       const { begin, end } = markerLines(op.marker, op.comment);
       const hasMarkers = content.includes(begin) && content.includes(end);
       if (!hasMarkers) {
@@ -2718,7 +2924,20 @@ function diagnoseCustomChecks(repoRoot, config) {
   const findings = [];
   for (const [name, entry2] of Object.entries(config.checks ?? {})) {
     const scriptAbs = join8(repoRoot, entry2.run);
-    findings.push(existsSync7(scriptAbs) ? ok("checks", `custom check '${name}' → ${entry2.run}`) : error("checks", `custom check '${name}' points at a missing script: ${entry2.run}`));
+    findings.push(existsSync8(scriptAbs) ? ok("checks", `custom check '${name}' → ${entry2.run}`) : error("checks", `custom check '${name}' points at a missing script: ${entry2.run}`));
+  }
+  return findings;
+}
+function diagnoseEnvDeclarations(repoRoot, config) {
+  const customSpecs = Object.entries(config?.checks ?? {}).map(([name, entry2]) => ({
+    name,
+    ...entry2,
+    run: join8(repoRoot, entry2.run)
+  }));
+  const missing = checksMissingEnvDeclaration([...coreCheckRegistry(), ...customSpecs]);
+  const findings = missing.map((name) => info("env", envDeclarationWarning(name)));
+  for (const message of lintEnvDeclarations(config?.checks)) {
+    findings.push(warn("env", message));
   }
   return findings;
 }
@@ -2791,6 +3010,7 @@ async function runDoctor(args, deps) {
     hasDrift = install.hasDrift;
     findings.push(...diagnoseCustomChecks(repo.repoRoot, configRead.config));
   }
+  findings.push(...diagnoseEnvDeclarations(repo.repoRoot, configRead.kind === "ok" ? configRead.config : null));
   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");
@@ -2806,7 +3026,7 @@ async function doctorCommand(args) {
 }
 
 // src/commands/eject.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
 import { join as join9 } from "node:path";
 
 // src/lib/prompt.ts
@@ -2889,11 +3109,11 @@ function parse(args) {
 }
 function readManifest(repoRoot) {
   const p = join9(repoRoot, CONFIG_PATH);
-  if (!existsSync8(p))
+  if (!existsSync9(p))
     return { kind: "none" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(p, "utf-8"));
+    raw = JSON.parse(readFileSync6(p, "utf-8"));
   } catch (err) {
     return { kind: "orphan", reason: `vinaya.config.json is not valid JSON: ${err.message}` };
   }
@@ -2976,7 +3196,7 @@ async function ejectCommand(args) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join10 } from "node:path";
 function realDeps5() {
   return {
@@ -2998,17 +3218,17 @@ function flags(args) {
 var PRODUCT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 function readManifest2(repoRoot) {
   const p = join10(repoRoot, CONFIG_PATH);
-  if (!existsSync9(p))
+  if (!existsSync10(p))
     return null;
   try {
-    return VinayaConfigSchema.parse(JSON.parse(readFileSync6(p, "utf-8"))).managed ?? null;
+    return VinayaConfigSchema.parse(JSON.parse(readFileSync7(p, "utf-8"))).managed ?? null;
   } catch {
     return null;
   }
 }
 function writeManifest(repoRoot, manifest) {
   const configAbs = join10(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync6(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync7(configAbs, "utf-8"));
   writeFileSync4(configAbs, `${JSON.stringify({ ...seed, managed: manifest }, null, 2)}
 `, "utf-8");
 }
@@ -3148,7 +3368,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 readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as join11 } from "node:path";
 class ForgeArgError extends Error {
@@ -3160,13 +3380,13 @@ function locateBody(args) {
       const p = args[i + 1];
       if (!p)
         throw new ForgeArgError("`--body-file` was given with no path.");
-      return { body: readFileSync7(p, "utf8"), source: { kind: "file", argIndex: i + 1, inlineForm: false } };
+      return { body: readFileSync8(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: readFileSync7(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
+      return { body: readFileSync8(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
     }
     if (a === "--body" || a === "-b") {
       const v = args[i + 1];
@@ -3456,7 +3676,7 @@ function issueEditCommand(args) {
 }
 
 // src/commands/new-check.ts
-import { chmodSync as chmodSync2, existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync9, 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");
@@ -3468,14 +3688,14 @@ function newCheckCommand(args) {
     process.exit(2);
   }
   const scriptsDir = join12(process.cwd(), CHECKS_DIR);
-  if (!existsSync10(scriptsDir))
+  if (!existsSync11(scriptsDir))
     mkdirSync3(scriptsDir, { recursive: true });
   const targetPath = join12(scriptsDir, `${name}.ts`);
-  if (existsSync10(targetPath)) {
+  if (existsSync11(targetPath)) {
     console.error(`Error: ${targetPath} already exists.`);
     process.exit(1);
   }
-  const template = readFileSync8(TEMPLATE_PATH, "utf-8");
+  const template = readFileSync9(TEMPLATE_PATH, "utf-8");
   const contents = template.split("{{CHECK_NAME}}").join(name);
   writeFileSync6(targetPath, contents, "utf-8");
   chmodSync2(targetPath, 493);
@@ -3639,16 +3859,16 @@ function prEditCommand(args) {
 
 // src/commands/studio.ts
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
 import { dirname as dirname4, join as join13 } from "node:path";
 function resolveStudioTarget(cwd) {
   let dir = cwd;
   for (;; ) {
     const webDir = join13(dir, "apps", "vinaya", "web");
     const pkgPath = join13(webDir, "package.json");
-    if (existsSync11(pkgPath)) {
+    if (existsSync12(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
         if (pkg.name === "@atta/vinaya-web") {
           return { kind: "workspace", webDir };
         }
@@ -3681,7 +3901,7 @@ async function runStudio(cwd, args) {
 }
 
 // src/commands/upgrade.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join14 } from "node:path";
 function realDeps6() {
   return {
@@ -3699,11 +3919,11 @@ function flags2(args) {
 }
 function readManifest3(repoRoot) {
   const p = join14(repoRoot, CONFIG_PATH);
-  if (!existsSync12(p))
+  if (!existsSync13(p))
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync10(p, "utf-8"));
+    raw = JSON.parse(readFileSync11(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -3720,7 +3940,7 @@ function readManifest3(repoRoot) {
 }
 function writeManifestVersion(repoRoot, manifest) {
   const configAbs = join14(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync10(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync11(configAbs, "utf-8"));
   const updated = { ...manifest, version: MANAGED_MANIFEST_VERSION };
   writeFileSync7(configAbs, `${JSON.stringify({ ...seed, managed: updated }, null, 2)}
 `, "utf-8");
@@ -3734,7 +3954,7 @@ function planUpgrade(ops, repoRoot, manifest) {
   for (const op of ops) {
     if (op.kind === "create-file") {
       const abs2 = join14(repoRoot, op.path);
-      const exists = existsSync12(abs2);
+      const exists = existsSync13(abs2);
       const owned = ownedFiles.has(op.path);
       let action;
       if (op.path === CONFIG_PATH) {
@@ -3744,7 +3964,7 @@ function planUpgrade(ops, repoRoot, manifest) {
       } else if (!exists) {
         action = "recreate";
         hasChanges = true;
-      } else if (readFileSync10(abs2, "utf-8") !== op.content) {
+      } else if (readFileSync11(abs2, "utf-8") !== op.content) {
         action = "regenerate";
         hasChanges = true;
       } else {
@@ -3757,11 +3977,11 @@ function planUpgrade(ops, repoRoot, manifest) {
       let action;
       if (!owned) {
         action = "not-installed";
-      } else if (!existsSync12(abs2)) {
+      } else if (!existsSync13(abs2)) {
         action = "recreate-host";
         hasChanges = true;
       } else {
-        const content = readFileSync10(abs2, "utf-8");
+        const content = readFileSync11(abs2, "utf-8");
         const { begin, end } = markerLines(op.marker, op.comment);
         if (!(content.includes(begin) && content.includes(end))) {
           action = "recreate-append";
@@ -3838,7 +4058,7 @@ function renderUpgradeDiff(plan) {
 }
 function regenerateBlock(repoRoot, op) {
   const abs2 = join14(repoRoot, op.path);
-  const content = readFileSync10(abs2, "utf-8");
+  const content = readFileSync11(abs2, "utf-8");
   const stripped = stripBlockFromContent(content, op.marker, op.comment);
   if (stripped !== null) {
     writeFileSync7(abs2, stripped.endsWith(`
@@ -4079,6 +4299,9 @@ var COMMANDS = [
       { flag: "--diff-only", description: "Scope diff-declared checks to changed files" },
       { flag: "--parallel[=n]", description: "Concurrency cap (default: cpu-derived)" }
     ],
+    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."
+    ],
     status: "shipped"
   },
   {
@@ -4148,6 +4371,9 @@ var COMMANDS = [
     name: "doctor",
     description: "Diagnose hook, workflow, and config health — report only, never mutates",
     flags: [{ flag: "--json", description: "Enveloped JSON output (schema: 1)" }],
+    details: [
+      'Carries the same env-declaration diagnostic `vinaya check` warns with — permanently, at `info` severity, not just ahead of the spawn-default flip — plus a `warn`-severity lint over suspicious `env` literal forms (a stray `"true"`/`"false"` string, or a high-entropy literal that reads like a leaked secret committed to config).'
+    ],
     status: "shipped"
   },
   {
@@ -4252,7 +4478,7 @@ function printHelp() {
 // src/index.ts
 var PACKAGE_ROOT = join15(dirname5(fileURLToPath2(import.meta.url)), "..");
 function readVersion2() {
-  const pkg = JSON.parse(readFileSync11(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync12(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
   return pkg.version;
 }
 var [, , command, ...args] = process.argv;

package/package.json

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

package/templates/custom-check.template.ts

@@ -7,6 +7,16 @@
  * never sleep past it inside this file. This file is standalone (no import
  * from the vinaya CLI's own source tree) because it lives in YOUR repo, not
  * inside `@attalabs/vinaya`.
+ *
+ * If this check reads `process.env` directly, declare which variables it
+ * needs on its REGISTRATION in `vinaya.config.json` (not in this file —
+ * there is no CheckSpec type to attach it to here) via `checks.{{CHECK_NAME}}.env`.
+ * Four forms: `"MY_VAR": true` forwards your value verbatim; `{ "optional":
+ * true }` forwards it if set, tolerating absence; `{ "anyOf": ["A", "B"] }`
+ * forwards whichever of those you've set, each under its own name; a
+ * literal string sets the key to that exact value. Example:
+ *   { "checks": { "{{CHECK_NAME}}": { "run": "...", "scope": "diff",
+ *       "env": { "MY_TOKEN": { "optional": true } } } } }
  */
 
 type CheckError = {