vigiles 2.1.1 → 2.3.0

package/dist/frontmatter.js

@@ -56,11 +56,11 @@ function findLine(lines, needle, fromIndex) {
     return fromIndex + 1;
 }
 /**
- * Navigate a parsed frontmatter document to its `vigiles.enforce` list.
- * Returns "none" when there's nothing for vigiles to check, "error" when a
- * `vigiles`/`enforce` key is present but the wrong shape, or the list.
+ * Navigate a parsed frontmatter document to its `vigiles` mapping. Returns
+ * "none" when there's nothing for vigiles to check, "error" when the
+ * `vigiles` key is present but not a mapping, or the mapping itself.
  */
-function lookupEnforce(doc, lines, startLine) {
+function getVigiles(doc, lines, startLine) {
     if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
         return { kind: "none" };
     }
@@ -78,6 +78,13 @@ function lookupEnforce(doc, lines, startLine) {
             },
         };
     }
+    return { kind: "map", vigiles: vigiles };
+}
+/**
+ * Locate the `vigiles.enforce` list. Returns "none" when absent, "error" when
+ * present but not a list, or the list with its source line.
+ */
+function lookupEnforce(vigiles, lines, startLine) {
     const enforce = vigiles.enforce;
     if (enforce === undefined)
         return { kind: "none" };
@@ -93,6 +100,45 @@ function lookupEnforce(doc, lines, startLine) {
     }
     return { kind: "list", enforce, enforceLine };
 }
+/**
+ * Parse a `vigiles.<key>` list of plain strings (used for `files` and
+ * `commands`). Returns located items plus error findings for the wrong shape
+ * or non-string entries; an absent key yields empty results.
+ */
+function parseStringList(vigiles, key, lines, startLine) {
+    const raw = vigiles[key];
+    if (raw === undefined)
+        return { items: [], errors: [] };
+    const keyLine = findLine(lines, `${key}:`, startLine - 1);
+    if (!Array.isArray(raw)) {
+        return {
+            items: [],
+            errors: [
+                {
+                    line: keyLine,
+                    message: `\`vigiles.${key}\` must be a list of strings.`,
+                },
+            ],
+        };
+    }
+    const items = [];
+    const errors = [];
+    let cursor = keyLine;
+    for (let i = 0; i < raw.length; i++) {
+        const v = raw[i];
+        if (typeof v !== "string" || v.trim() === "") {
+            errors.push({
+                line: keyLine,
+                message: `vigiles.${key}[${String(i)}] must be a non-empty string.`,
+            });
+            continue;
+        }
+        const line = findLine(lines, v, cursor);
+        cursor = line;
+        items.push({ value: v, line });
+    }
+    return { items, errors };
+}
 /** Parse one `vigiles.enforce` entry into a rule or an error finding. */
 function parseEntry(entry, index, ctx) {
     if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
@@ -126,10 +172,15 @@ function parseEntry(entry, index, ctx) {
     }
     return { rule: { linterRule: rule, why, line }, nextCursor: line };
 }
+/** Fresh empty result — callers may push into the arrays, so never shared. */
+function emptyResult() {
+    return { rules: [], files: [], commands: [], errors: [] };
+}
 /**
- * Parse `vigiles.enforce` rules out of a markdown file's YAML frontmatter.
- * Does not touch the filesystem and does not verify rules against any
- * linter — callers feed the returned rules into `checkLinterRule`.
+ * Parse `vigiles.enforce` rules, `vigiles.files`, and `vigiles.commands` out
+ * of a markdown file's YAML frontmatter. Does not touch the filesystem and
+ * does not verify references — callers feed rules into `checkLinterRule` and
+ * file/command refs into `validateFileRef` / `validateCommandRef`.
  *
  * A file with no frontmatter, or frontmatter with no `vigiles` key, yields
  * empty results with no errors. Malformed YAML or a malformed `vigiles`
@@ -138,7 +189,7 @@ function parseEntry(entry, index, ctx) {
 function parseFrontmatterRules(content) {
     const fm = extractFrontmatter(content);
     if (!fm)
-        return { rules: [], errors: [] };
+        return emptyResult();
     const lines = content.split("\n");
     let doc;
     try {
@@ -149,6 +200,8 @@ function parseFrontmatterRules(content) {
         const line = (err.mark?.line ?? 0) + fm.startLine;
         return {
             rules: [],
+            files: [],
+            commands: [],
             errors: [
                 {
                     line,
@@ -157,34 +210,54 @@ function parseFrontmatterRules(content) {
             ],
         };
     }
-    const lookup = lookupEnforce(doc, lines, fm.startLine);
-    if (lookup.kind === "none")
-        return { rules: [], errors: [] };
-    if (lookup.kind === "error")
-        return { rules: [], errors: [lookup.error] };
+    const vig = getVigiles(doc, lines, fm.startLine);
+    if (vig.kind === "none")
+        return emptyResult();
+    if (vig.kind === "error")
+        return { rules: [], files: [], commands: [], errors: [vig.error] };
     const rules = [];
     const errors = [];
-    let cursor = lookup.enforceLine; // search start: line after `enforce:`
-    for (let i = 0; i < lookup.enforce.length; i++) {
-        const r = parseEntry(lookup.enforce[i], i, {
-            lines,
-            enforceLine: lookup.enforceLine,
-            cursor,
-        });
-        cursor = r.nextCursor;
-        if (r.rule)
-            rules.push(r.rule);
-        if (r.error)
-            errors.push(r.error);
+    const enforceLookup = lookupEnforce(vig.vigiles, lines, fm.startLine);
+    if (enforceLookup.kind === "error") {
+        errors.push(enforceLookup.error);
+    }
+    else if (enforceLookup.kind === "list") {
+        let cursor = enforceLookup.enforceLine; // search start: line after `enforce:`
+        for (let i = 0; i < enforceLookup.enforce.length; i++) {
+            const r = parseEntry(enforceLookup.enforce[i], i, {
+                lines,
+                enforceLine: enforceLookup.enforceLine,
+                cursor,
+            });
+            cursor = r.nextCursor;
+            if (r.rule)
+                rules.push(r.rule);
+            if (r.error)
+                errors.push(r.error);
+        }
     }
-    return { rules, errors };
+    const fileList = parseStringList(vig.vigiles, "files", lines, fm.startLine);
+    errors.push(...fileList.errors);
+    const files = fileList.items.map((it) => ({
+        path: it.value,
+        line: it.line,
+    }));
+    const cmdList = parseStringList(vig.vigiles, "commands", lines, fm.startLine);
+    errors.push(...cmdList.errors);
+    const commands = cmdList.items.map((it) => ({
+        command: it.value,
+        line: it.line,
+    }));
+    return { rules, files, commands, errors };
 }
 /**
- * True if the content has at least one parseable `vigiles.enforce` rule in
- * its frontmatter. Used by `require-spec` validation to treat frontmatter
- * mode as spec-equivalent, mirroring `hasInlineRules`.
+ * True if the content has at least one parseable `vigiles` reference in its
+ * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry.
+ * Used by `require-spec` validation to treat frontmatter mode as
+ * spec-equivalent, mirroring `hasInlineRules`.
  */
 function hasFrontmatterRules(content) {
-    return parseFrontmatterRules(content).rules.length > 0;
+    const r = parseFrontmatterRules(content);
+    return r.rules.length + r.files.length + r.commands.length > 0;
 }
 //# sourceMappingURL=frontmatter.js.map

package/dist/generate-schema.js

@@ -101,6 +101,16 @@ function generateSchema(options = {}) {
                             },
                         },
                     },
+                    files: {
+                        type: "array",
+                        description: "File paths referenced by this instruction file, verified to exist by `vigiles audit`.",
+                        items: { type: "string" },
+                    },
+                    commands: {
+                        type: "array",
+                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles audit`.",
+                        items: { type: "string" },
+                    },
                 },
             },
         },

package/dist/harness-assert.d.ts

@@ -0,0 +1,68 @@
+/**
+ * vigiles — runner-agnostic helpers for harness tests / evals.
+ *
+ * `runHarnessTest` and `runEval` are plain async functions that return data, so
+ * they already work inside any runner (node:test, vitest, jest, mocha). These
+ * helpers remove the last bit of boilerplate without coupling to a runner:
+ *
+ *   - `withHarness` — run a harness test and auto-clean the sandbox (try/finally),
+ *     so you don't leak temp dirs in `afterEach`.
+ *   - plain `assert*` helpers that throw — usable in every runner, including
+ *     node:test which has no `expect.extend`.
+ *   - `vigilesMatchers` — register with `expect.extend(vigilesMatchers)` for
+ *     `expect(...).toHaveCreated(...)` sugar. The signature is identical for
+ *     vitest and jest, so the same object supports both.
+ */
+import { type HarnessTestSpec, type HarnessTestResult } from "./harness-test.js";
+import type { EvalReport } from "./eval.js";
+import type { HookRunResult } from "./run-hook.js";
+/**
+ * Run a harness test, hand the result to `fn`, and always clean up the sandbox.
+ * Returns whatever `fn` returns. Use this instead of calling `cleanup()` by
+ * hand — it survives assertion failures.
+ */
+export declare function withHarness<T>(spec: HarnessTestSpec, fn: (r: HarnessTestResult) => T | Promise<T>): Promise<T>;
+/** Assert the sandbox contains `path` (a hook/agent side-effect file). */
+export declare function assertCreated(r: HarnessTestResult, path: string): void;
+/** Assert the sandbox does NOT contain `path` (e.g. a blocked action's output). */
+export declare function assertNotCreated(r: HarnessTestResult, path: string): void;
+/** Assert the scripted model served at least `n` turns (e.g. a Stop hook forced more). */
+export declare function assertServedTurns(r: HarnessTestResult, n: number): void;
+/** Assert a `runHook` result blocked (exit 2 / decision:block / permission:deny). */
+export declare function assertHookBlocked(r: HookRunResult): void;
+/** Assert a `runHook` result allowed (did not block). */
+export declare function assertHookAllowed(r: HookRunResult): void;
+/** The gap on `metric` between two arms (arm − baseline). */
+export declare function improvement(report: EvalReport, baseline: string, arm: string, metric: string): number;
+/**
+ * Assert `arm` beats `baseline` on `metric` by more than `by`. With `by` left at
+ * 0 this just asserts a positive gap; pass the combined se to demand the gap
+ * clear the noise floor.
+ */
+export declare function assertImproves(report: EvalReport, opts: {
+    baseline: string;
+    arm: string;
+    metric: string;
+    by?: number;
+}): void;
+interface MatcherOutput {
+    pass: boolean;
+    message: () => string;
+}
+/**
+ * Custom matchers compatible with both vitest and jest. Register once:
+ *
+ *   import { expect } from "vitest"; // or "@jest/globals"
+ *   import { vigilesMatchers } from "vigiles/harness-assert";
+ *   expect.extend(vigilesMatchers);
+ *
+ *   expect(result).toHaveCreated("RESULT");
+ *   expect(report).toBeatBaseline("vanilla", "gated", "caught");
+ */
+export declare const vigilesMatchers: {
+    toHaveCreated(received: HarnessTestResult, path: string): MatcherOutput;
+    toBlock(received: HookRunResult): MatcherOutput;
+    toBeatBaseline(received: EvalReport, baseline: string, arm: string, metric: string, by?: number): MatcherOutput;
+};
+export {};
+//# sourceMappingURL=harness-assert.d.ts.map

package/dist/harness-assert.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vigilesMatchers = void 0;
+exports.withHarness = withHarness;
+exports.assertCreated = assertCreated;
+exports.assertNotCreated = assertNotCreated;
+exports.assertServedTurns = assertServedTurns;
+exports.assertHookBlocked = assertHookBlocked;
+exports.assertHookAllowed = assertHookAllowed;
+exports.improvement = improvement;
+exports.assertImproves = assertImproves;
+/**
+ * vigiles — runner-agnostic helpers for harness tests / evals.
+ *
+ * `runHarnessTest` and `runEval` are plain async functions that return data, so
+ * they already work inside any runner (node:test, vitest, jest, mocha). These
+ * helpers remove the last bit of boilerplate without coupling to a runner:
+ *
+ *   - `withHarness` — run a harness test and auto-clean the sandbox (try/finally),
+ *     so you don't leak temp dirs in `afterEach`.
+ *   - plain `assert*` helpers that throw — usable in every runner, including
+ *     node:test which has no `expect.extend`.
+ *   - `vigilesMatchers` — register with `expect.extend(vigilesMatchers)` for
+ *     `expect(...).toHaveCreated(...)` sugar. The signature is identical for
+ *     vitest and jest, so the same object supports both.
+ */
+const harness_test_js_1 = require("./harness-test.js");
+/**
+ * Run a harness test, hand the result to `fn`, and always clean up the sandbox.
+ * Returns whatever `fn` returns. Use this instead of calling `cleanup()` by
+ * hand — it survives assertion failures.
+ */
+async function withHarness(spec, fn) {
+    const r = await (0, harness_test_js_1.runHarnessTest)(spec);
+    try {
+        return await fn(r);
+    }
+    finally {
+        r.cleanup();
+    }
+}
+// --- Plain throwing assertions (any runner) --------------------------------
+function fail(message) {
+    throw new Error(message);
+}
+/** Assert the sandbox contains `path` (a hook/agent side-effect file). */
+function assertCreated(r, path) {
+    if (r.file(path) === null)
+        fail(`expected the run to create ${path}`);
+}
+/** Assert the sandbox does NOT contain `path` (e.g. a blocked action's output). */
+function assertNotCreated(r, path) {
+    if (r.file(path) !== null)
+        fail(`expected the run NOT to create ${path}`);
+}
+/** Assert the scripted model served at least `n` turns (e.g. a Stop hook forced more). */
+function assertServedTurns(r, n) {
+    if (r.turns < n) {
+        fail(`expected ≥ ${String(n)} model turns, got ${String(r.turns)}`);
+    }
+}
+/** Assert a `runHook` result blocked (exit 2 / decision:block / permission:deny). */
+function assertHookBlocked(r) {
+    if (!r.blocked) {
+        fail(`expected the hook to block, but it allowed (exit ${String(r.exitCode)})`);
+    }
+}
+/** Assert a `runHook` result allowed (did not block). */
+function assertHookAllowed(r) {
+    if (r.blocked) {
+        fail(`expected the hook to allow, but it blocked (exit ${String(r.exitCode)}, decision ${String(r.decision)})`);
+    }
+}
+/** The gap on `metric` between two arms (arm − baseline). */
+function improvement(report, baseline, arm, metric) {
+    const a = report.arms[arm]?.metrics[metric] ?? 0;
+    const b = report.arms[baseline]?.metrics[metric] ?? 0;
+    return a - b;
+}
+/**
+ * Assert `arm` beats `baseline` on `metric` by more than `by`. With `by` left at
+ * 0 this just asserts a positive gap; pass the combined se to demand the gap
+ * clear the noise floor.
+ */
+function assertImproves(report, opts) {
+    const by = opts.by ?? 0;
+    const delta = improvement(report, opts.baseline, opts.arm, opts.metric);
+    if (delta <= by) {
+        fail(`expected ${opts.arm} to beat ${opts.baseline} on ${opts.metric} by > ${String(by)}, got ${delta.toFixed(3)}`);
+    }
+}
+/**
+ * Custom matchers compatible with both vitest and jest. Register once:
+ *
+ *   import { expect } from "vitest"; // or "@jest/globals"
+ *   import { vigilesMatchers } from "vigiles/harness-assert";
+ *   expect.extend(vigilesMatchers);
+ *
+ *   expect(result).toHaveCreated("RESULT");
+ *   expect(report).toBeatBaseline("vanilla", "gated", "caught");
+ */
+exports.vigilesMatchers = {
+    toHaveCreated(received, path) {
+        const pass = received.file(path) !== null;
+        return {
+            pass,
+            message: () => `expected the run ${pass ? "not " : ""}to create ${path}`,
+        };
+    },
+    toBlock(received) {
+        const pass = received.blocked;
+        return {
+            pass,
+            message: () => `expected the hook ${pass ? "not " : ""}to block (exit ${String(received.exitCode)}, decision ${String(received.decision)})`,
+        };
+    },
+    // eslint-disable-next-line max-params -- jest/vitest matchers take positional args
+    toBeatBaseline(received, baseline, arm, metric, by = 0) {
+        const delta = improvement(received, baseline, arm, metric);
+        const pass = delta > by;
+        return {
+            pass,
+            message: () => `expected ${arm} ${pass ? "not " : ""}to beat ${baseline} on ${metric} by > ${String(by)} (got ${delta.toFixed(3)})`,
+        };
+    },
+};
+//# sourceMappingURL=harness-assert.js.map

package/dist/harness-test.d.ts

@@ -0,0 +1,45 @@
+import { type ModelTurn } from "./mock-model.js";
+export { scriptModel, type ModelTurn } from "./mock-model.js";
+export { loadPlugin, resolveHarness } from "./plugin-loader.js";
+export interface HarnessTestSpec {
+    /** Fixture files to write in a fresh temp working dir (path → contents). */
+    readonly files?: Record<string, string>;
+    /** `.claude/settings.json` contents — the hooks/permissions under test. */
+    readonly settings?: unknown;
+    /**
+     * Path to a real plugin/repo whose harness (hooks + CLAUDE.md + skills) is
+     * loaded into the sandbox, so you test the assembled machine, not a retyped
+     * subset. Inline `settings`/`files` layer on top. See src/plugin-loader.ts.
+     */
+    readonly plugin?: string;
+    /** The scripted model turns the agent will take. */
+    readonly model: readonly ModelTurn[];
+    /** The user prompt. Default: "go". */
+    readonly prompt?: string;
+    /** Tools the agent may use. Default: Read Edit Write Bash. */
+    readonly allowedTools?: readonly string[];
+    /** Per-run wall-clock timeout in ms. Default 60000. */
+    readonly timeoutMs?: number;
+}
+export interface HarnessTestResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    /** Hook block messages and diagnostics land here. */
+    readonly stderr: string;
+    /** The temp working dir (inspect or clean it up). */
+    readonly cwd: string;
+    /** Number of model turns the agent took (mock turns served). */
+    readonly turns: number;
+    /** Final contents of a file under the working dir, or null if absent. */
+    file(path: string): string | null;
+    /** Remove the temp working dir. */
+    cleanup(): void;
+}
+/** Whether the `claude` CLI is available — harness tests need it. */
+export declare function claudeAvailable(): boolean;
+/**
+ * Run the real `claude` CLI against a scripted mock model, with the given
+ * fixture and settings (hooks). Deterministic — same script, same result.
+ */
+export declare function runHarnessTest(spec: HarnessTestSpec): Promise<HarnessTestResult>;
+//# sourceMappingURL=harness-test.d.ts.map

package/dist/harness-test.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
+exports.claudeAvailable = claudeAvailable;
+exports.runHarnessTest = runHarnessTest;
+/**
+ * vigiles — deterministic Claude Code harness testing.
+ *
+ * Test what your *harness* does — hooks, settings, skills, instruction files —
+ * without paying for or depending on a real model. `runHarnessTest` spins up the
+ * real `claude` CLI (so your real hooks and settings fire exactly as in
+ * production) but points it at a scripted mock model (`src/mock-model.ts`), so
+ * the agent's turns are fixed and the outcome is reproducible. No API key, no
+ * cost, CI-friendly.
+ *
+ *   const r = await runHarnessTest({
+ *     settings: { hooks: { Stop: [{ hooks: [{ type: "command",
+ *       command: "test -f DONE || { echo 'not done' >&2; exit 2; }" }] }] } },
+ *     model: scriptModel([
+ *       { text: "I'm done" },                              // tries to stop → blocked
+ *       { tool: "Bash", input: { command: "touch DONE" } },
+ *       { text: "now done" },
+ *     ]),
+ *   });
+ *   assert(JSON.parse(r.stdout).num_turns > 1);            // the Stop hook fired
+ *
+ * The "steps" are the scripted model turns — their real home is deterministic
+ * harness testing, not production enforcement.
+ *
+ * Note: the simple mock drives the Bash tool and Stop hooks reliably; the
+ * Edit/Write tools are gated in headless mode and don't fire via the mock —
+ * drive file actions through Bash, or use the real-model eval tier (`eval.ts`)
+ * for Edit/Write hooks.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const mock_model_js_1 = require("./mock-model.js");
+const plugin_loader_js_1 = require("./plugin-loader.js");
+var mock_model_js_2 = require("./mock-model.js");
+Object.defineProperty(exports, "scriptModel", { enumerable: true, get: function () { return mock_model_js_2.scriptModel; } });
+var plugin_loader_js_2 = require("./plugin-loader.js");
+Object.defineProperty(exports, "loadPlugin", { enumerable: true, get: function () { return plugin_loader_js_2.loadPlugin; } });
+Object.defineProperty(exports, "resolveHarness", { enumerable: true, get: function () { return plugin_loader_js_2.resolveHarness; } });
+/** Whether the `claude` CLI is available — harness tests need it. */
+function claudeAvailable() {
+    try {
+        return (0, node_child_process_1.spawnSync)("claude", ["--version"], { stdio: "ignore" }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function writeFixture(cwd, files, settings) {
+    for (const [p, content] of Object.entries(files)) {
+        const full = (0, node_path_1.resolve)(cwd, p);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(full), { recursive: true });
+        (0, node_fs_1.writeFileSync)(full, content);
+    }
+    if (settings !== undefined) {
+        // `{cwd}` in any hook command is substituted with the working dir, so a
+        // hook can reference an absolute path inside it (hooks don't run with the
+        // project dir as cwd).
+        const json = JSON.stringify(settings, null, 2).replaceAll("{cwd}", cwd);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(cwd, "settings.json"), json);
+    }
+}
+function spawnClaude(args, cwd, baseUrl, timeoutMs) {
+    return new Promise((resolvePromise) => {
+        const child = (0, node_child_process_1.spawn)("claude", args, {
+            cwd,
+            env: {
+                ...process.env,
+                ANTHROPIC_BASE_URL: baseUrl,
+                // Any value works — the mock ignores auth; this avoids needing a real key.
+                ANTHROPIC_API_KEY: "sk-vigiles-mock",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolvePromise({ code: code ?? 0, stdout, stderr });
+        });
+    });
+}
+/**
+ * Run the real `claude` CLI against a scripted mock model, with the given
+ * fixture and settings (hooks). Deterministic — same script, same result.
+ */
+async function runHarnessTest(spec) {
+    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    const { files, settings } = (0, plugin_loader_js_1.resolveHarness)({
+        plugin: spec.plugin,
+        settings: spec.settings,
+        files: spec.files,
+    });
+    writeFixture(cwd, files, settings);
+    const mock = await (0, mock_model_js_1.startMock)(spec.model);
+    try {
+        const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
+        const args = [
+            "-p",
+            spec.prompt ?? "go",
+            "--output-format",
+            "json",
+            "--model",
+            "claude-sonnet-4-5",
+            ...(settings !== undefined ? ["--settings", "settings.json"] : []),
+            "--allowedTools",
+            ...tools,
+        ];
+        const out = await spawnClaude(args, cwd, mock.url, spec.timeoutMs ?? 60000);
+        return {
+            exitCode: out.code,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            cwd,
+            turns: mock.count,
+            file: (p) => {
+                const f = (0, node_path_1.resolve)(cwd, p);
+                return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
+            },
+            cleanup: () => {
+                (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+            },
+        };
+    }
+    finally {
+        mock.close();
+    }
+}
+//# sourceMappingURL=harness-test.js.map

package/dist/inline.d.ts

@@ -25,8 +25,24 @@ export interface InlineRule {
     /** 1-based line number of the comment in the source file. */
     line: number;
 }
+/** A `<!-- vigiles:file <path> -->` reference (verified to exist). */
+export interface InlineFileRef {
+    /** Project-relative path to verify exists. */
+    path: string;
+    /** 1-based line number of the comment in the source file. */
+    line: number;
+}
+/** A `<!-- vigiles:cmd "<command>" -->` reference (npm scripts verified). */
+export interface InlineCmdRef {
+    /** Command to verify (npm scripts checked against package.json). */
+    command: string;
+    /** 1-based line number of the comment in the source file. */
+    line: number;
+}
 export interface InlineParseResult {
     rules: InlineRule[];
+    files: InlineFileRef[];
+    commands: InlineCmdRef[];
     /** Lines that look like vigiles: markers but failed to parse. */
     errors: {
         line: number;
@@ -46,13 +62,15 @@ export interface InlineParseResult {
  */
 export declare function parseInlineRules(content: string): InlineParseResult;
 /**
- * True if the content contains at least one parseable vigiles:enforce
- * rule (ignoring fenced code blocks and malformed markers). Used by
- * `require-spec` validation to treat inline mode as spec-equivalent.
+ * True if the content contains at least one parseable vigiles inline marker —
+ * an `enforce` rule, a `file` reference, or a `cmd` reference (ignoring fenced
+ * code blocks and malformed markers). Used by `require-spec` validation to
+ * treat inline mode as spec-equivalent: a file that pins even a single path is
+ * meaningfully managed.
  *
  * Deliberately delegates to `parseInlineRules` so a loose prefix regex
  * can't satisfy require-spec with a malformed marker that produces no
- * real enforceable rule.
+ * real reference.
  */
 export declare function hasInlineRules(content: string): boolean;
 //# sourceMappingURL=inline.d.ts.map