vigiles 33.3.0 → 35.0.0

package/action.yml

@@ -19,9 +19,15 @@ inputs:
     required: false
     default: ""
   version:
-    description: "Version of the vigiles npm package to run (e.g. '1', '1.2.3', 'latest'). Use 'local' to run the action's own checkout — for dogfooding via `uses: ./` in this repo's CI."
+    description: >
+      Version of the vigiles npm package to run (e.g. '34', '34.1.2', 'latest').
+      Empty (the default) runs the vigiles THIS repo declares in package.json:
+      the installed copy when node_modules has it, else the version in
+      package-lock.json, else the declared range — and 'latest' only when the
+      repo does not declare vigiles. Use 'local' to run the action's own
+      checkout — for dogfooding via `uses: ./` in this repo's CI.
     required: false
-    default: "latest"
+    default: ""
   max-rules:
     description: "Maximum number of rules per spec file (maps to the CLI's --max-rules)."
     required: false
@@ -109,17 +115,48 @@ runs:
         fi
 
         # Resolve the runner. 'local' runs the action's own build (CI
-        # dogfood via `uses: ./`); any other value runs the published npm
-        # package at that version, so the Action reuses the same tested
-        # artifact users get from `npx vigiles`.
-        version="${VIGILES_VERSION:-latest}"
+        # dogfood via `uses: ./`); an explicit version runs the published npm
+        # package at that version. EMPTY (the default) runs the vigiles this
+        # repo declares, so CI and a local `npx vigiles` are the same version
+        # rather than two pins that drift: the installed copy, else the
+        # lockfile's version, else the declared range; `latest` only when the
+        # repo does not declare vigiles at all.
+        version="${VIGILES_VERSION:-}"
         if [[ "$version" == "local" ]]; then
           runner=(node "${VIGILES_ACTION_PATH}/dist/cli.js")
-        else
+          from="the action's own checkout"
+        elif [[ -n "$version" ]]; then
           runner=(npx --yes "vigiles@${version}")
+          from="the version input"
+        else
+          declared="$(node -e '
+            const fs = require("fs");
+            const read = (f) => { try { return JSON.parse(fs.readFileSync(f, "utf8")); } catch { return null; } };
+            const pkg = read("package.json") ?? {};
+            const spec = pkg.devDependencies?.vigiles ?? pkg.dependencies?.vigiles;
+            if (typeof spec !== "string") { console.log("none"); process.exit(0); }
+            if (fs.existsSync("node_modules/.bin/vigiles")) { console.log("installed"); process.exit(0); }
+            const lock = read("package-lock.json") ?? {};
+            const locked = lock.packages?.["node_modules/vigiles"]?.version ?? lock.dependencies?.vigiles?.version;
+            console.log(typeof locked === "string" ? "lock " + locked : "range " + spec);
+          ' 2>/dev/null || echo none)"
+          case "$declared" in
+            installed)
+              runner=(npx --no-install vigiles)
+              from="this repo's installed vigiles" ;;
+            "lock "*)
+              runner=(npx --yes "vigiles@${declared#lock }")
+              from="package-lock.json" ;;
+            "range "*)
+              runner=(npx --yes "vigiles@${declared#range }")
+              from="the range package.json declares" ;;
+            *)
+              runner=(npx --yes "vigiles@latest")
+              from="latest (this repo does not declare vigiles)" ;;
+          esac
         fi
 
-        echo "vigiles: ${runner[*]} ${args[*]}"
+        echo "vigiles: ${runner[*]} ${args[*]}  (version from ${from})"
 
         # Run, streaming to the log AND capturing for the summary/comment.
         out="$(mktemp)"

package/dist/adapters/codex/driver.js

@@ -75,7 +75,8 @@ async function startCodexMockHandle(script) {
             }));
         },
         get count() {
-            return mock.requests.length;
+            // Turns SERVED: a request past the end of the script gets a 400.
+            return Math.min(mock.requests.length, script.length);
         },
         close: () => mock.close(),
     };

package/dist/adapters/codex/mock-model.d.ts

@@ -42,8 +42,9 @@ export declare function parseResponsesRequest(body: string): {
 };
 /**
  * Start the scripted Codex Responses mock on a free port. Each
- * `POST /v1/responses` consumes the next scripted turn (the last turn repeats if
- * codex asks for more); HEAD and any other path get `{}`. Resolves to a handle
+ * `POST /v1/responses` consumes the next scripted turn; one past the end of the
+ * script is a 400, never a copy of the last turn (#340); HEAD and any other path
+ * get `{}`. Resolves to a handle
  * with the base `url`, the `port`, the recorded `requests`, and `close()`.
  */
 export declare function startCodexMock(script: readonly CodexTurn[], opts?: {

package/dist/adapters/codex/mock-model.js

@@ -22,6 +22,7 @@ exports.startCodexMock = startCodexMock;
  * `src/adapters/codex/runtime.ts` (`codexMockArgs`/`codexMockEnv`).
  */
 const node_http_1 = __importDefault(require("node:http"));
+const script_overrun_js_1 = require("../../core/script-overrun.js");
 const MSG_ID = "msg_mock_1";
 const RESP_ID = "resp_mock_1";
 /**
@@ -183,8 +184,9 @@ function parseResponsesRequest(body) {
 }
 /**
  * Start the scripted Codex Responses mock on a free port. Each
- * `POST /v1/responses` consumes the next scripted turn (the last turn repeats if
- * codex asks for more); HEAD and any other path get `{}`. Resolves to a handle
+ * `POST /v1/responses` consumes the next scripted turn; one past the end of the
+ * script is a 400, never a copy of the last turn (#340); HEAD and any other path
+ * get `{}`. Resolves to a handle
  * with the base `url`, the `port`, the recorded `requests`, and `close()`.
  */
 function startCodexMock(script, opts = {}) {
@@ -204,7 +206,17 @@ function startCodexMock(script, opts = {}) {
             const parsed = parseResponsesRequest(body);
             requests.push(parsed);
             opts.onRequest?.(parsed);
-            const turn = script[Math.min(i, script.length - 1)] ?? { text: "" };
+            const turn = script[i];
+            if (turn === undefined) {
+                const message = (0, script_overrun_js_1.scriptOverrunMessage)({
+                    scripted: script.length,
+                    request: script.length + 1,
+                    lastMessage: parsed.prompt,
+                });
+                res.writeHead(400, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: { type: "invalid_request_error", message } }));
+                return;
+            }
             i++;
             const model = parsed.model || "gpt-5-codex";
             res.writeHead(200, {

package/dist/cli-flag-check.js

@@ -75,6 +75,7 @@ exports.COMMAND_FLAGS = {
         "--no-gha",
         "--no-plugin",
         "--ci-only",
+        "--full",
     ],
     compile: [],
     eject: ["--keep-spec"],

package/dist/cli-main.js

@@ -27,6 +27,7 @@ const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
 const eval_lock_js_1 = require("./eval-lock.js");
+const zod_1 = require("zod");
 const cli_flags_js_1 = require("./cli-flags.js");
 const cli_commands_js_1 = require("./cli-commands.js");
 const cli_flag_check_js_1 = require("./cli-flag-check.js");
@@ -2636,6 +2637,9 @@ function vigilesWorkflow(plan, harnesses, hasPackageJson) {
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+      # No \`version:\` on purpose: the Action runs the vigiles your
+      # package.json declares, so CI and a local \`npx vigiles\` cannot
+      # drift onto two different pins.
       - uses: zernie/vigiles@v1
 `
         : "";
@@ -2667,17 +2671,21 @@ function vigilesWorkflow(plan, harnesses, hasPackageJson) {
   eval-check:
     # Eval staleness gate — real-model evals run LOCALLY on your subscription
     # (\`npx vigiles eval --update\`, which commits a lock); this job VERIFIES those
-    # committed results against the current inputs with NO model call. It stays a
-    # green no-op until you commit your first lock. See docs/harness-testing.md.
+    # committed results against the current inputs with NO model call.
+    # \`--min=0\` is deliberate: a repo with no eval file yet matches nothing, and
+    # \`vigiles eval --check\` fails on an empty match by default (a gate that
+    # verified nothing must not read as a pass). With \`--min=0\` this job is green
+    # until the first \`*.eval.*\` file exists; from then on it is red until that
+    # eval's lock is committed. Raise the floor (\`--min=N\`) once you want
+    # a vanished eval file to fail it. See docs/harness-testing.md.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
-      - uses: zernie/vigiles@v1
-        with:
-          command: eval-check
+      - run: npm install
+      - run: npx vigiles eval --check --min=0
 `
         : "";
     // No selectable jobs (e.g. `--no-lint --no-test`, or `--test` on a repo with no
@@ -3036,6 +3044,9 @@ function redirectSyncToolTargets(cwd, targets) {
         `staling the integrity hash.`);
     return out;
 }
+/** The two files `init`'s lint layer generates under `.vigiles/`. */
+const GENERATED_TYPES = ".vigiles/generated.d.ts";
+const GENERATED_SCHEMA = ".vigiles/schema.json";
 /** Pillar 1 — specs + types + schema + compile. Scaffolds a spec for every
  * instruction file (so `--lint` always delivers a spec), but never compiles
  * OVER a hand-written file — that is left to the adopt-spec skill. */
@@ -3081,7 +3092,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
     const outDir = (0, node_path_1.resolve)(cwd, ".vigiles");
     if (!(0, node_fs_1.existsSync)(outDir))
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/generated.d.ts"), typesResult.dts);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, GENERATED_TYPES), typesResult.dts);
     for (const l of typesResult.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
     }
@@ -3089,14 +3100,14 @@ async function setupPillar1(detected, targetValue, harnesses) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
     console.log("✓ Generated .vigiles/generated.d.ts");
-    written.push(".vigiles/generated.d.ts");
+    written.push(GENERATED_TYPES);
     const schemaResult = (0, generate_schema_js_1.generateSchema)({
         basePath: cwd,
         linters: (0, validate_js_1.loadConfig)().linters,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/schema.json"), schemaResult.json);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, GENERATED_SCHEMA), schemaResult.json);
     console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
-    written.push(".vigiles/schema.json");
+    written.push(GENERATED_SCHEMA);
     // Compile — but NEVER overwrite an existing hand-written file during `init`:
     // we compile only GREENFIELD targets (the file doesn't exist yet) and targets
     // we already manage (carry our hash). An ADOPTED file is left untouched — the
@@ -3609,8 +3620,24 @@ function printSetupSummary(opts) {
         console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
     }
 }
+/** The project config file `init` reads and writes. */
+const VIGILESRC = ".vigilesrc.json";
 async function setup(args) {
     const parsed = (0, setup_plan_js_1.parseSetupArgs)(args);
+    // An already-adopted repo gets the MINIMAL re-run unless a flag asks for more
+    // (#338): re-running `init` to pick up one new piece must not also wire CI,
+    // widen the rules, scaffold files or rewrite a pin. Decided from disk, before
+    // any prompt — the minimal run asks nothing.
+    const state = (0, setup_plan_js_1.adoptionState)({
+        hasConfig: (0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), VIGILESRC)),
+        specs: detectProject()
+            .instructionFiles.filter((f) => f.hasSpec)
+            .map((f) => `${f.path}.spec.ts`),
+    });
+    if ((0, setup_plan_js_1.rerunScope)(parsed, state) === "minimal" && state.kind === "adopted") {
+        minimalRerun(parsed, state);
+        return;
+    }
     // Plan: defaults → flags → interactive prompts (only a human at a TTY).
     let plan = (0, setup_plan_js_1.resolvePlan)(parsed);
     const prompted = (0, setup_plan_js_1.shouldPrompt)(parsed, process.stdin.isTTY ?? false);
@@ -3707,6 +3734,152 @@ async function setup(args) {
         console.log("\nℹ Ran the standard setup. Already have a harness, or not a JS/Python repo, and want only the CI integrity gate (nothing installed)? Re-run `npx vigiles init --ci-only`.");
     }
 }
+/**
+ * The minimal re-run on an adopted repo (#338): add what is missing AND safe and
+ * local — the skill links and a missing devDependency — then say what a full
+ * setup would add and the flag that does it. It writes NOTHING else: no CI
+ * workflow, no `.vigilesrc.json` edit, no harness/schema scaffold, no spec for a
+ * hand-written file, no edit to an existing version pin, no global install.
+ * The decisions are pure (`setup-plan.ts`); this is the IO.
+ */
+function minimalRerun(parsed, state) {
+    const plan = (0, setup_plan_js_1.resolvePlan)(parsed);
+    const detected = detectProject();
+    const harnesses = resolveHarnesses(parsed, detected, (0, adapter_registry_js_1.declaredHarnessNames)((0, validate_js_1.loadConfig)().harnesses));
+    console.log(`vigiles is already set up here (found ${state.evidence}) — adding only what is missing.\n`);
+    printDetection(detected, harnesses);
+    const links = plan.plugin ? linkSkillsOnly(harnesses) : [];
+    const devDep = plan.lint || plan.test ? addMissingVigilesDevDep() : [];
+    const written = [...links, ...devDep];
+    if (written.length === 0)
+        console.log("\nNothing was missing.");
+    const followUps = (0, setup_plan_js_1.fullSetupFollowUps)(fullSetupGap(plan, detected, harnesses));
+    if (followUps.length > 0)
+        console.log(`\n${followUps.join("\n")}`);
+    if (written.length > 0)
+        console.log(`\n  Commit:\n    git add ${written.join(" ")} && git commit -m "Update vigiles"`);
+}
+/**
+ * Link the shipped skills for each harness that links them — the safe, local
+ * half of `installPlugins`, without the global install or config wiring.
+ * Returns the links created or rewritten.
+ */
+function linkSkillsOnly(harnesses) {
+    return (0, setup_plan_js_1.planPluginInstall)(harnesses, { hasClaude: false }).flatMap((plan) => {
+        const home = plan.linkSkills ? harnessSkillsHome(plan.harness) : null;
+        if (home === null)
+            return [];
+        const outcome = linkVigilesSkills(home, process.cwd());
+        console.log("");
+        (0, skill_links_js_1.formatSkillLinks)(outcome).forEach((l) => {
+            console.log(l);
+        });
+        return changedLinks(outcome);
+    });
+}
+/** Add vigiles to `devDependencies` only when nothing declares it. */
+function addMissingVigilesDevDep() {
+    const pkgPath = (0, node_path_1.resolve)(process.cwd(), PACKAGE_JSON);
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return [];
+    const pkg = readPackageJson(pkgPath);
+    if (pkg === null || pkg.name === "vigiles")
+        return [];
+    const spec = vigilesDepSpec();
+    const devDependencies = (0, setup_plan_js_1.missingVigilesDevDep)(pkg, spec);
+    if (devDependencies === null)
+        return [];
+    (0, node_fs_1.writeFileSync)(pkgPath, JSON.stringify({ ...pkg, devDependencies }, null, 2) + "\n");
+    console.log(`\n✓ Added vigiles@${spec} to devDependencies — run \`npm install\` to fetch it`);
+    return [PACKAGE_JSON];
+}
+/**
+ * The fields of package.json the dependency decisions read. LOOSE on purpose:
+ * every other key is carried through untouched, because the result is written
+ * back and a re-run must not drop a field it never looked at.
+ */
+const packageDepsSchema = zod_1.z.looseObject({
+    name: zod_1.z.string().optional(),
+    dependencies: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    devDependencies: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+});
+/** package.json parsed for its dependency fields; null when unreadable. */
+function readPackageJson(path) {
+    try {
+        const parsed = packageDepsSchema.safeParse(JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a full setup would add here, read from disk — the input to the
+ * follow-up lines. It mirrors the full path's own conditions (the plan's
+ * layers, the existence checks those steps make), so the list names what
+ * `--full` would actually do rather than everything it could.
+ */
+function fullSetupGap(plan, detected, harnesses) {
+    const cwd = process.cwd();
+    const has = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel));
+    const config = readProjectConfig((0, node_path_1.resolve)(cwd, VIGILESRC));
+    const pillar1 = plan.lint && plan.scaffoldSpecs;
+    const unspecced = pillar1
+        ? [
+            ...determineTargets(detected, undefined, [...harnesses]),
+            ...discoverAdoptableSurfaces(cwd),
+        ].filter((t, i, all) => all.indexOf(t) === i && !has(`${t}.spec.ts`))
+        : [];
+    const pkg = has(PACKAGE_JSON)
+        ? readPackageJson((0, node_path_1.resolve)(cwd, PACKAGE_JSON))
+        : null;
+    const declared = pkg?.devDependencies?.vigiles ?? pkg?.dependencies?.vigiles ?? null;
+    const spec = vigilesDepSpec();
+    return {
+        workflow: plan.gha && !has(".github/workflows/vigiles.yml"),
+        config: configGap(config, plan.lint),
+        harnessTest: plan.test && !has("vigiles.harness.mjs"),
+        unspecced,
+        generated: pillar1 && !(has(GENERATED_TYPES) && has(GENERATED_SCHEMA)),
+        installs: plan.plugin ? fullInstallLines(harnesses) : [],
+        devDep: declared !== null && declared !== spec && pkg?.name !== "vigiles"
+            ? { from: declared, to: spec }
+            : null,
+    };
+}
+/** Where `.vigilesrc.json` stands against the preset a full setup writes. */
+function configGap(config, lint) {
+    if (config === null)
+        return "missing";
+    return config.extends === undefined && lint ? "no-preset" : "has-preset";
+}
+/** `.vigilesrc.json` as a plain object, or null when absent or unreadable. */
+function readProjectConfig(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+        return typeof raw === "object" && raw !== null && !Array.isArray(raw)
+            ? { ...raw }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The per-machine installs and config wiring the full plugin step would run. */
+function fullInstallLines(harnesses) {
+    return (0, setup_plan_js_1.planPluginInstall)(harnesses, { hasClaude: true }).flatMap((plan) => [
+        ...(plan.globalInstallCarriesHooks && plan.commands.length > 0
+            ? [
+                `install the ${plan.harness} plugin for this machine (${plan.commands.join(" && ")}) and declare it in the project settings`,
+            ]
+            : []),
+        ...(plan.vendors
+            ? [`wire vigiles's nudge hooks into the ${plan.harness} config`]
+            : []),
+    ]);
+}
 /** Canonical, de-duplicated harness names — the keys `harnesses` gets. */
 function harnessConfigKeys(harnesses) {
     return [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
@@ -5026,10 +5199,11 @@ async function promptYesNo(question) {
  * Resolve the eval LOCK env from the `eval` flags. `--update` records each named
  * eval's report to a committed `.vigiles/eval-locks/<name>.lock.json` (run locally
  * on your subscription); `--check` (CI) verifies the committed result against the
- * current inputs WITHOUT a model call. `--check` is a green NO-OP until the first
- * lock is committed (smooth adoption). Returns the env to thread, or `"skip"` to
- * exit green now. `--check`+`--update` together is a usage error (exit 2). The
- * behavior epoch comes from `.vigilesrc.json` `eval.apiVersion` (committed).
+ * current inputs WITHOUT a model call. `--check` with no lock committed at all is
+ * a FAILURE, not a green no-op ({@link refuseEvalCheckWithoutLocks}, #197): a gate
+ * that has verified nothing must not read as one that passed.
+ * `--check`+`--update` together is a usage error (exit 2). The behavior epoch
+ * comes from `.vigilesrc.json` `eval.apiVersion` (committed).
  */
 function resolveEvalLockEnv(args) {
     const wantCheck = args.includes("--check");
@@ -5038,13 +5212,6 @@ function resolveEvalLockEnv(args) {
         console.error("vigiles eval: --check and --update are mutually exclusive (one verifies, one records).");
         process.exit(2);
     }
-    if (wantCheck &&
-        !(0, eval_lock_js_1.anyLocksCommitted)((0, node_path_1.resolve)(process.cwd(), eval_lock_js_1.DEFAULT_LOCK_DIR))) {
-        console.log("ℹ vigiles eval --check: no committed eval locks found — nothing to verify.\n" +
-            "  Run `vigiles eval --update` locally (on your subscription) and commit the\n" +
-            "  lock to enable the CI staleness gate.");
-        return "skip";
-    }
     const env = {};
     if (wantCheck)
         env.VIGILES_EVAL_LOCK = "check";
@@ -5057,6 +5224,22 @@ function resolveEvalLockEnv(args) {
     }
     return env;
 }
+/**
+ * `eval --check` over eval files when no lock is committed anywhere: every one of
+ * them has no recorded result to compare the current inputs against, so the gate
+ * would verify nothing and pass. It used to return green BEFORE discovery, which
+ * also bypassed the empty-match failure. Once any lock exists, a file without one
+ * already fails as "lock missing" in the eval itself. Exits 1; returns otherwise.
+ */
+function refuseEvalCheckWithoutLocks(args, evalCount) {
+    if (!args.includes("--check"))
+        return;
+    if ((0, eval_lock_js_1.anyLocksCommitted)((0, node_path_1.resolve)(process.cwd(), eval_lock_js_1.DEFAULT_LOCK_DIR)))
+        return;
+    console.error(`✗ vigiles eval --check: ${String(evalCount)} eval file(s) have no recorded result — no eval lock is committed, so there is nothing to verify the current inputs against.\n` +
+        "  Run `vigiles eval --update` locally (on your subscription) and commit the lock(s).");
+    process.exit(1);
+}
 /**
  * Turn a completed run into `.vigiles/coverage.json` — the composition root for
  * the execution tier of coverage (`coverage-artifact.ts`).
@@ -5231,6 +5414,31 @@ function gitHead(cwd) {
         return "";
     }
 }
+/**
+ * Why a `vigiles test` / `vigiles eval` run matched no file — the message names
+ * what was looked for, so a stale path, a wrong glob and an empty default
+ * discovery each say so. A DIRECTORY is the one stale-looking target whose cause
+ * we actually know, so it is said instead of the three guesses: `vigiles test .`
+ * used to reach `spawn("node", ["."])` and surface Node's module-resolution stack.
+ */
+function emptyMatchMessage(kind, targets, defaultGlob) {
+    const dirs = targets.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
+    if (dirs.length > 0) {
+        return (`✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
+            `pass a file, or a glob like "${defaultGlob}".\n` +
+            `  A directory is not a script; nothing ran.`);
+    }
+    const expected = `  If an empty match is expected here, say so with --min=0.`;
+    if (targets.length === 0) {
+        return (`✗ vigiles ${kind}: NOTHING matched the default glob ${defaultGlob}\n` +
+            `  Nothing ran. An empty run is not a pass: a renamed or moved file looks like this.\n` +
+            expected);
+    }
+    return (`✗ vigiles ${kind}: ${String(targets.length)} target(s) given and NOTHING matched — ` +
+        `${targets.join(", ")}\n` +
+        `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
+        expected);
+}
 async function handleRunScripts(kind, args, restArgs, excludes) {
     const cwd = process.cwd();
     // The ignore file keeps NEW copies of `.vigiles/` local files out of git, but
@@ -5251,14 +5459,10 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
     // The eval LOCK flags (`--check`/`--update`) are resolved BEFORE file discovery
-    // so mutual-exclusion + the cold-start no-op are honored regardless of file
-    // count. Returns the env to thread to scripts, or `"skip"` to exit green now.
+    // so mutual-exclusion (exit 2) is honored regardless of file count.
     let lockEnv = {};
     if (kind === "eval") {
-        const r = resolveEvalLockEnv(args);
-        if (r === "skip")
-            return;
-        lockEnv = r;
+        lockEnv = resolveEvalLockEnv(args);
     }
     // A script under an excluded path is not DISCOVERED (a vendored corpus's own
     // harness must not run as ours), but a script you NAME still runs (#192).
@@ -5280,44 +5484,33 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         process.exit(1);
     }
     if (files.length === 0) {
-        // 🔴 ASKING FOR SOMETHING AND GETTING NOTHING IS A FAILURE; FINDING NOTHING IS NOT.
-        // The two cases were collapsed into one silent exit 0, and the collapse cost a real
-        // repository three days of green CI verifying zero files: a named step ran
+        // 🔴 A RUN THAT MATCHES NO FILE IS A FAILURE, NAMED OR NOT.
+        // An empty match used to be one silent exit 0, and it cost a real repository three
+        // days of green CI verifying zero files: a named step ran
         // `vigiles test .claude/pipeline/skills.harness.mjs` after that file had been split
         // into one-per-skill, printed "No **/*.harness.* files found" and passed, right next
-        // to a step that was red for the same root cause.
-        //
-        // They are different states. A POSITIONAL argument is a claim that something is there —
-        // when nothing matches it, the path is stale, the glob is wrong, or the run never
-        // reached its target, and every one of those is a defect. Bare discovery finding
-        // nothing is just an empty repository, which is a legitimate place to stand and must
-        // stay quiet.
+        // to a step that was red for the same root cause. The first repair failed only the
+        // NAMED case and kept bare discovery quiet ("an empty repository is a legitimate
+        // place to stand") — and bare `vigiles test` is the line `init` writes into CI, so
+        // the same green no-op was one rename away from the default setup (#197).
         //
-        // This is the default the field settled on: Jest and Vitest FAIL on no tests found and
-        // make you opt in with `--passWithNoTests`; pytest exits 5. `--min=0` remains the
-        // explicit opt-out here, so no new flag is introduced by this change.
-        // `minFlag`, not `minRequired`: 0 is both the DEFAULT and the explicit opt-out, so the
-        // VALUE cannot tell them apart — only the flag's presence can. (Caught by a control:
-        // the first version read `minRequired === 0` and made `--min=0` do nothing.)
-        if (restArgs.length > 0 && minFlag === undefined) {
-            // A DIRECTORY is the one stale-looking target whose cause we actually know,
-            // so say it instead of listing the three guesses. `vigiles test .` used to
-            // reach `spawn("node", ["."])` and surface Node's module-resolution stack;
-            // the generic message above would now be true but unhelpful.
-            const dirs = restArgs.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
-            console.error(dirs.length > 0
-                ? `✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
-                    `pass a file, or a glob like "${defaultGlob}".\n` +
-                    `  A directory is not a script; nothing ran.`
-                : `✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
-                    `${restArgs.join(", ")}\n` +
-                    `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
-                    `  If an empty match is expected here, say so with --min=0.`);
+        // This is the default the field settled on: Jest and Vitest FAIL on no tests found
+        // and make you opt in with `--passWithNoTests`; pytest exits 5. Here there is no
+        // such flag (a person who wants an empty run does not call the command), and
+        // `--min=0` — the existing floor, spelled as zero — is the only way to say an empty
+        // match is expected. `minFlag`, not `minRequired`: 0 is both the DEFAULT and that
+        // explicit opt-out, so the VALUE cannot tell them apart — only the flag's presence
+        // can. (Caught by a control: the first version read `minRequired === 0` and made
+        // `--min=0` do nothing.)
+        if (minFlag === undefined) {
+            console.error(emptyMatchMessage(kind, restArgs, defaultGlob));
             process.exit(1);
         }
         console.log(`No ${defaultGlob} files found.`);
         return;
     }
+    if (kind === "eval")
+        refuseEvalCheckWithoutLocks(args, files.length);
     // Consent gate for a bare `vigiles eval`: it runs the REAL model on your
     // subscription, and a no-target run discovered the whole tree — so never fan out
     // over an unbounded glob without explicit intent. Mirrors audit's read-vs-run
@@ -5446,6 +5639,10 @@ function capabilitiesOfReport(report, dialect) {
 const COMMAND_HELP = {
     init: {
         usage: "  vigiles init [flags]       Set up this repo — specs, plugin, and CI.",
+        detail: [
+            "  Already set up? A re-run only adds what is missing (skill links, the devDependency);",
+            "  --full                     run the whole setup again",
+        ],
     },
     compile: { usage: "  vigiles compile [files...] Compile .spec.ts → .md" },
     eject: {