vigiles 2.1.1 → 2.3.0

package/dist/skill-driver.d.ts

@@ -0,0 +1,77 @@
+/**
+ * vigiles — Skill driver: the generator (durable-imperative) form of a skill.
+ *
+ * The declarative `skill({ steps })` form compiles to a *static* SKILL.md — it
+ * can't express branching/looping, because that control flow depends on runtime
+ * values. The generator form does: a skill is a generator that `yield`s
+ * effects, and the harness drives it with `.next()`. Branches are real `if`,
+ * loops are real `for`/`while`; the harness owns the loop and runs the
+ * deterministic gates between yields, short-circuiting on failure (Railway).
+ *
+ * The model is an injected seam: `runStep(prose)` is what executes a prose step
+ * (in production it calls the LLM; in tests it's a scripted mock and the answer
+ * is fed back into the generator). Gates are deterministic and reuse the gate
+ * runtime. This module is the mechanics — fully testable without a live model.
+ */
+import type { Gate } from "./spec.js";
+import { type GateOutcome } from "./skill-runtime.js";
+export type SkillEffect = {
+    readonly kind: "act";
+    readonly prose: string;
+} | {
+    readonly kind: "gate";
+    readonly gate: Gate;
+    readonly retry: number;
+} | {
+    readonly kind: "result";
+    readonly gate: Gate;
+};
+/** A prose step for the model to perform. Its answer is yielded back in. */
+export declare function act(prose: string): SkillEffect;
+/** A deterministic checkpoint gate the harness runs after the prior step(s). */
+export declare function checkpoint(gate: Gate, retry?: number): SkillEffect;
+/** The terminal result gate — the skill is done only when it passes. */
+export declare function finish(gate: Gate): SkillEffect;
+/**
+ * A skill program: a generator that yields effects and receives, for each
+ * `act`, the model's answer back in (`const x = yield act(...)`).
+ */
+export type SkillProgram = () => Generator<SkillEffect, void, string>;
+/** Frontmatter metadata for a generator skill. */
+export interface GeneratorSkillMeta {
+    readonly name: string;
+    readonly description: string;
+    readonly disableModelInvocation?: boolean;
+}
+/**
+ * A generator skill = metadata + a generator program. Authored as
+ * `export default genSkill({ name, description }, function* () { … })`.
+ * The CLI compiles it to SKILL.md by parsing the source (it can't execute a
+ * generator to markdown); `runSkill`/`driveSkill` execute `program` directly.
+ */
+export interface GeneratorSkill extends GeneratorSkillMeta {
+    readonly _specType: "skill-generator";
+    readonly program: SkillProgram;
+}
+/** Define a generator skill (metadata + program). */
+export declare function genSkill(meta: GeneratorSkillMeta, program: SkillProgram): GeneratorSkill;
+export interface DriveStep {
+    readonly effect: SkillEffect;
+    /** The model's answer, for an `act` effect. */
+    readonly answer?: string;
+    /** The gate outcome, for a `gate`/`result` effect. */
+    readonly outcome?: GateOutcome;
+}
+export interface DriveReport {
+    readonly ok: boolean;
+    /** Index (in the trace) of the gate that blocked, or null if all passed. */
+    readonly blockedAt: number | null;
+    readonly trace: readonly DriveStep[];
+}
+/**
+ * Drive a skill program to completion (or to the first failed gate). `runStep`
+ * is the model seam: it executes a prose step and returns the model's answer,
+ * which is fed back into the generator so branches can switch on it.
+ */
+export declare function driveSkill(program: SkillProgram, cwd: string, runStep: (prose: string) => string): DriveReport;
+//# sourceMappingURL=skill-driver.d.ts.map

package/dist/skill-driver.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * vigiles — Skill driver: the generator (durable-imperative) form of a skill.
+ *
+ * The declarative `skill({ steps })` form compiles to a *static* SKILL.md — it
+ * can't express branching/looping, because that control flow depends on runtime
+ * values. The generator form does: a skill is a generator that `yield`s
+ * effects, and the harness drives it with `.next()`. Branches are real `if`,
+ * loops are real `for`/`while`; the harness owns the loop and runs the
+ * deterministic gates between yields, short-circuiting on failure (Railway).
+ *
+ * The model is an injected seam: `runStep(prose)` is what executes a prose step
+ * (in production it calls the LLM; in tests it's a scripted mock and the answer
+ * is fed back into the generator). Gates are deterministic and reuse the gate
+ * runtime. This module is the mechanics — fully testable without a live model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.act = act;
+exports.checkpoint = checkpoint;
+exports.finish = finish;
+exports.genSkill = genSkill;
+exports.driveSkill = driveSkill;
+const skill_runtime_js_1 = require("./skill-runtime.js");
+/** A prose step for the model to perform. Its answer is yielded back in. */
+function act(prose) {
+    return { kind: "act", prose };
+}
+/** A deterministic checkpoint gate the harness runs after the prior step(s). */
+function checkpoint(gate, retry = 1) {
+    return { kind: "gate", gate, retry };
+}
+/** The terminal result gate — the skill is done only when it passes. */
+function finish(gate) {
+    return { kind: "result", gate };
+}
+/** Define a generator skill (metadata + program). */
+function genSkill(meta, program) {
+    return { _specType: "skill-generator", ...meta, program };
+}
+/** Convert a spec-level Gate to the runtime gate the executor understands. */
+function toRuntimeGate(gate, retry) {
+    if (gate._ref === "cmd")
+        return { kind: "cmd", command: gate.command, retry };
+    if (gate._ref === "role")
+        return { kind: "role", role: gate.role, retry };
+    return { kind: "file", path: gate.path, retry };
+}
+/**
+ * Drive a skill program to completion (or to the first failed gate). `runStep`
+ * is the model seam: it executes a prose step and returns the model's answer,
+ * which is fed back into the generator so branches can switch on it.
+ */
+function driveSkill(program, cwd, runStep) {
+    const gen = program();
+    const trace = [];
+    let input = "";
+    for (;;) {
+        const { value: effect, done } = gen.next(input);
+        if (done)
+            break;
+        if (effect.kind === "act") {
+            const answer = runStep(effect.prose);
+            trace.push({ effect, answer });
+            input = answer;
+            continue;
+        }
+        const retry = effect.kind === "gate" ? effect.retry : 1;
+        const outcome = (0, skill_runtime_js_1.runGate)(toRuntimeGate(effect.gate, retry), cwd);
+        trace.push({ effect, outcome });
+        if (!outcome.ok)
+            return { ok: false, blockedAt: trace.length - 1, trace };
+        input = "";
+    }
+    return { ok: true, blockedAt: null, trace };
+}
+//# sourceMappingURL=skill-driver.js.map

package/dist/skill-runtime.d.ts

@@ -0,0 +1,101 @@
+/**
+ * vigiles — Skill runtime: the deterministic gate ladder.
+ *
+ * Parses the `vigiles:gate` / `vigiles:result` markers a compiled SKILL.md
+ * carries (emitted by compileSkill) and *executes* them: run each step's gate
+ * in document order, short-circuit on the first failure (Railway error track),
+ * then run the terminal result gate. This is the deterministic spine of the
+ * skill driver — the part that turns the markers from documentation into
+ * enforcement.
+ *
+ * Scope (v0): this runs the GATES only. It does not drive the LLM through the
+ * prose steps one at a time — that needs a live harness and is a later phase.
+ * `retry:N` is parsed and surfaced but executed once here: re-running a
+ * deterministic gate without a model in the loop to fix the step yields the
+ * same result. Retry is meaningful only once the model re-does the step
+ * between attempts.
+ *
+ * Safety: this executes the gate commands the skill author declared (e.g.
+ * `npm test`, `validate.py`) via an explicit, user-invoked command
+ * (`vigiles run-skill`). It is not a silent hook and runs nothing the spec
+ * didn't declare as a gate.
+ */
+export type RuntimeGate = {
+    readonly kind: "cmd";
+    readonly command: string;
+    readonly retry: number;
+} | {
+    readonly kind: "file";
+    readonly path: string;
+    readonly retry: number;
+} | {
+    readonly kind: "role";
+    readonly role: string;
+    readonly retry: number;
+};
+export interface SkillGates {
+    /** Per-step gates, in document order. */
+    readonly steps: readonly {
+        readonly step: number;
+        readonly gate: RuntimeGate;
+    }[];
+    /** Terminal postcondition gate, if any. */
+    readonly result?: RuntimeGate;
+}
+/** Extract the step gates and result gate from a compiled SKILL.md. */
+export declare function parseSkillGates(markdown: string): SkillGates;
+export interface GateOutcome {
+    readonly ok: boolean;
+    readonly output: string;
+}
+/**
+ * Resolve a project role (test/build/lint) to the host project's real command,
+ * detected from its ecosystem. Returns null when no command can be found —
+ * which the caller surfaces as a failed gate rather than a silent pass.
+ */
+export declare function detectProjectCommand(role: string, cwd: string): string | null;
+/**
+ * Run one gate against `cwd`: a command (exit 0 = pass), a file existence, or
+ * a project role resolved to the host project's command.
+ */
+export declare function runGate(gate: RuntimeGate, cwd: string): GateOutcome;
+/** Human-readable label for a gate (for reports and hook messages). */
+export declare function gateLabel(gate: RuntimeGate): string;
+export interface GateRunResult {
+    /** Step number, or "result" for the terminal gate. */
+    readonly at: number | "result";
+    readonly gate: RuntimeGate;
+    readonly ok: boolean;
+    readonly output: string;
+}
+export interface SkillRunReport {
+    readonly results: readonly GateRunResult[];
+    /** Where the ladder short-circuited, or null when every gate passed. */
+    readonly blockedAt: number | "result" | null;
+    readonly ok: boolean;
+}
+/**
+ * Run the gate ladder: step gates in order (short-circuiting on the first
+ * failure), then the result gate. Mirrors a Sequence behavior tree —
+ * ordered AND with short-circuit on FAILURE.
+ */
+export declare function runSkillGates(gates: SkillGates, cwd: string): SkillRunReport;
+/** Record the skill the agent is currently executing. */
+export declare function setActiveSkill(cwd: string, skillPath: string): void;
+/** Clear the active-skill marker (the skill finished). */
+export declare function clearActiveSkill(cwd: string): void;
+/** The path of the active skill, or null when none is in progress. */
+export declare function readActiveSkill(cwd: string): string | null;
+export interface StopDecision {
+    /** Whether the agent may stop (true) or must keep working (false). */
+    readonly allow: boolean;
+    /** Message for the user (allow) or fed back to the model (block). */
+    readonly message: string;
+}
+/**
+ * Stop-hook decision. If a skill is active and declares a result gate, run it:
+ * allow the stop only when the gate passes; otherwise block and tell the model
+ * what to fix. With no active skill (or no result gate), always allow.
+ */
+export declare function evaluateStopHook(cwd: string): StopDecision;
+//# sourceMappingURL=skill-runtime.d.ts.map

package/dist/skill-runtime.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * vigiles — Skill runtime: the deterministic gate ladder.
+ *
+ * Parses the `vigiles:gate` / `vigiles:result` markers a compiled SKILL.md
+ * carries (emitted by compileSkill) and *executes* them: run each step's gate
+ * in document order, short-circuit on the first failure (Railway error track),
+ * then run the terminal result gate. This is the deterministic spine of the
+ * skill driver — the part that turns the markers from documentation into
+ * enforcement.
+ *
+ * Scope (v0): this runs the GATES only. It does not drive the LLM through the
+ * prose steps one at a time — that needs a live harness and is a later phase.
+ * `retry:N` is parsed and surfaced but executed once here: re-running a
+ * deterministic gate without a model in the loop to fix the step yields the
+ * same result. Retry is meaningful only once the model re-does the step
+ * between attempts.
+ *
+ * Safety: this executes the gate commands the skill author declared (e.g.
+ * `npm test`, `validate.py`) via an explicit, user-invoked command
+ * (`vigiles run-skill`). It is not a silent hook and runs nothing the spec
+ * didn't declare as a gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSkillGates = parseSkillGates;
+exports.detectProjectCommand = detectProjectCommand;
+exports.runGate = runGate;
+exports.gateLabel = gateLabel;
+exports.runSkillGates = runSkillGates;
+exports.setActiveSkill = setActiveSkill;
+exports.clearActiveSkill = clearActiveSkill;
+exports.readActiveSkill = readActiveSkill;
+exports.evaluateStopHook = evaluateStopHook;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const STEP_RE = /^###\s+Step\s+(\d+)/;
+const GATE_CMD_RE = /<!--\s*vigiles:gate\s+"([^"]*)"(?:\s+retry:(\d+))?\s*-->/;
+const GATE_FILE_RE = /<!--\s*vigiles:gate\s+file:(\S+)\s*-->/;
+const GATE_ROLE_RE = /<!--\s*vigiles:gate\s+role:(\w+)(?:\s+retry:(\d+))?\s*-->/;
+const RESULT_CMD_RE = /<!--\s*vigiles:result\s+"([^"]*)"\s*-->/;
+const RESULT_FILE_RE = /<!--\s*vigiles:result\s+file:(\S+)\s*-->/;
+const RESULT_ROLE_RE = /<!--\s*vigiles:result\s+role:(\w+)\s*-->/;
+/** Parse a single line into a gate, or null if it carries none. */
+function parseGateLine(line) {
+    const cmd = GATE_CMD_RE.exec(line);
+    if (cmd) {
+        return { kind: "cmd", command: cmd[1], retry: cmd[2] ? Number(cmd[2]) : 1 };
+    }
+    const role = GATE_ROLE_RE.exec(line);
+    if (role) {
+        return {
+            kind: "role",
+            role: role[1],
+            retry: role[2] ? Number(role[2]) : 1,
+        };
+    }
+    const fileM = GATE_FILE_RE.exec(line);
+    if (fileM)
+        return { kind: "file", path: fileM[1], retry: 1 };
+    return null;
+}
+/** Parse the terminal result gate from a line, or null. */
+function parseResultLine(line) {
+    const cmd = RESULT_CMD_RE.exec(line);
+    if (cmd)
+        return { kind: "cmd", command: cmd[1], retry: 1 };
+    const role = RESULT_ROLE_RE.exec(line);
+    if (role)
+        return { kind: "role", role: role[1], retry: 1 };
+    const fileM = RESULT_FILE_RE.exec(line);
+    if (fileM)
+        return { kind: "file", path: fileM[1], retry: 1 };
+    return null;
+}
+/** Extract the step gates and result gate from a compiled SKILL.md. */
+function parseSkillGates(markdown) {
+    const steps = [];
+    let result;
+    let currentStep = 0;
+    for (const line of markdown.split("\n")) {
+        const stepMatch = STEP_RE.exec(line);
+        if (stepMatch) {
+            currentStep = Number(stepMatch[1]);
+            continue;
+        }
+        const resultGate = parseResultLine(line);
+        if (resultGate) {
+            result = resultGate;
+            continue;
+        }
+        const gate = parseGateLine(line);
+        if (gate)
+            steps.push({ step: currentStep, gate });
+    }
+    return { steps, result };
+}
+/** Execute a shell command in `cwd`; exit 0 = pass, capturing output. */
+function execCommand(command, cwd) {
+    try {
+        const out = (0, node_child_process_1.execSync)(command, {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, output: out.trim() };
+    }
+    catch (e) {
+        const err = e;
+        const output = [err.stdout, err.stderr].filter(Boolean).join("\n").trim();
+        return { ok: false, output };
+    }
+}
+const NPM_FOR_ROLE = {
+    test: "npm test",
+    build: "npm run build",
+    lint: "npm run lint",
+};
+/** Detect the npm command for a role from package.json scripts, or null. */
+function detectNpmCommand(role, cwd) {
+    const pkg = (0, node_path_1.resolve)(cwd, "package.json");
+    if (!(0, node_fs_1.existsSync)(pkg))
+        return null;
+    try {
+        const scripts = JSON.parse((0, node_fs_1.readFileSync)(pkg, "utf-8")).scripts ?? {};
+        return scripts[role] ? (NPM_FOR_ROLE[role] ?? null) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Non-npm ecosystems: marker files + the command for each role. */
+const ECOSYSTEMS = [
+    {
+        markers: ["pyproject.toml", "setup.cfg"],
+        commands: { test: "pytest", lint: "ruff check ." },
+    },
+    {
+        markers: ["Cargo.toml"],
+        commands: {
+            test: "cargo test",
+            build: "cargo build",
+            lint: "cargo clippy",
+        },
+    },
+    {
+        markers: ["go.mod"],
+        commands: { test: "go test ./...", build: "go build ./..." },
+    },
+];
+/**
+ * Resolve a project role (test/build/lint) to the host project's real command,
+ * detected from its ecosystem. Returns null when no command can be found —
+ * which the caller surfaces as a failed gate rather than a silent pass.
+ */
+function detectProjectCommand(role, cwd) {
+    const npm = detectNpmCommand(role, cwd);
+    if (npm)
+        return npm;
+    for (const eco of ECOSYSTEMS) {
+        const present = eco.markers.some((m) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, m)));
+        const command = eco.commands[role];
+        if (present && command)
+            return command;
+    }
+    return null;
+}
+/**
+ * Run one gate against `cwd`: a command (exit 0 = pass), a file existence, or
+ * a project role resolved to the host project's command.
+ */
+function runGate(gate, cwd) {
+    if (gate.kind === "file") {
+        const there = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, gate.path));
+        return { ok: there, output: there ? "" : `${gate.path} not found` };
+    }
+    if (gate.kind === "role") {
+        const command = detectProjectCommand(gate.role, cwd);
+        if (!command) {
+            return {
+                ok: false,
+                output: `No ${gate.role} command detected for this project`,
+            };
+        }
+        return execCommand(command, cwd);
+    }
+    return execCommand(gate.command, cwd);
+}
+/** Human-readable label for a gate (for reports and hook messages). */
+function gateLabel(gate) {
+    if (gate.kind === "cmd")
+        return `\`${gate.command}\``;
+    if (gate.kind === "role")
+        return `the project's ${gate.role} command`;
+    return `${gate.path} exists`;
+}
+/**
+ * Run the gate ladder: step gates in order (short-circuiting on the first
+ * failure), then the result gate. Mirrors a Sequence behavior tree —
+ * ordered AND with short-circuit on FAILURE.
+ */
+function runSkillGates(gates, cwd) {
+    const results = [];
+    for (const { step, gate } of gates.steps) {
+        const r = runGate(gate, cwd);
+        results.push({ at: step, gate, ok: r.ok, output: r.output });
+        if (!r.ok)
+            return { results, blockedAt: step, ok: false };
+    }
+    if (gates.result) {
+        const r = runGate(gates.result, cwd);
+        results.push({
+            at: "result",
+            gate: gates.result,
+            ok: r.ok,
+            output: r.output,
+        });
+        if (!r.ok)
+            return { results, blockedAt: "result", ok: false };
+    }
+    return { results, blockedAt: null, ok: true };
+}
+// ---------------------------------------------------------------------------
+// Stop-hook enforcement
+// ---------------------------------------------------------------------------
+//
+// A skill is "active" while the agent is executing it. The Stop hook then runs
+// the active skill's result gate and blocks completion until it passes — so the
+// agent cannot declare a skill done until its result is deterministically
+// proven. Which skill is active is tracked in `.vigiles/active-skill.json`
+// (Claude Code hooks don't surface the active skill, so we record it). Wiring
+// `skill-start` to fire automatically is the integration step; the decision
+// logic below is harness-agnostic and fully testable.
+const ACTIVE_PATH = ".vigiles/active-skill.json";
+/** Record the skill the agent is currently executing. */
+function setActiveSkill(cwd, skillPath) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ skill: skillPath }) + "\n");
+}
+/** Clear the active-skill marker (the skill finished). */
+function clearActiveSkill(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.rmSync)(p);
+}
+/** The path of the active skill, or null when none is in progress. */
+function readActiveSkill(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return typeof parsed.skill === "string" ? parsed.skill : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stop-hook decision. If a skill is active and declares a result gate, run it:
+ * allow the stop only when the gate passes; otherwise block and tell the model
+ * what to fix. With no active skill (or no result gate), always allow.
+ */
+function evaluateStopHook(cwd) {
+    const skillPath = readActiveSkill(cwd);
+    if (!skillPath)
+        return { allow: true, message: "" };
+    const full = (0, node_path_1.resolve)(cwd, skillPath);
+    if (!(0, node_fs_1.existsSync)(full))
+        return { allow: true, message: "" };
+    const gates = parseSkillGates((0, node_fs_1.readFileSync)(full, "utf-8"));
+    if (!gates.result)
+        return { allow: true, message: "" };
+    const outcome = runGate(gates.result, cwd);
+    const desc = gateLabel(gates.result);
+    if (outcome.ok) {
+        return {
+            allow: true,
+            message: `✓ ${skillPath}: result gate ${desc} passed.`,
+        };
+    }
+    const tail = outcome.output ? `\n${outcome.output}` : "";
+    return {
+        allow: false,
+        message: `Skill "${skillPath}" is not done: result gate ${desc} failed. Fix it, then finish.${tail}`,
+    };
+}
+//# sourceMappingURL=skill-runtime.js.map

package/dist/skill-test.d.ts

@@ -0,0 +1,47 @@
+/**
+ * vigiles — Skill testing: deterministic tests for a skill's action sequence.
+ *
+ * A thin wrapper over the generator driver (`driveSkill`) for use inside an
+ * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
+ * the *model* (the non-deterministic part) and assert the deterministic spine:
+ * which gates ran, in what order, which branch was taken, whether the result
+ * gate blocked. The model's prose quality is never asserted — that's the
+ * probabilistic boundary; everything else is deterministic and checkable.
+ */
+import { type SkillProgram, type GeneratorSkill } from "./skill-driver.js";
+export type ModelFn = (prose: string) => string;
+/**
+ * Script the mocked model. Pass:
+ *  - an array — answers consumed in order across all acts; or
+ *  - a map keyed by a case-insensitive substring of the act's prose, where each
+ *    value is a single answer, or an array consumed in order *per key* (so a
+ *    loop's prompt can return different answers on successive iterations).
+ * Unmatched prose yields "".
+ */
+export declare function scriptModel(spec: readonly string[] | Readonly<Record<string, string | readonly string[]>>): ModelFn;
+export interface SkillRunResult {
+    /** Every gate passed and the skill reached its end. */
+    readonly ok: boolean;
+    /** Trace index of the gate that blocked, or null when all passed. */
+    readonly blockedAt: number | null;
+    /** Prose steps the model executed, with the scripted answer fed back in. */
+    readonly acts: readonly {
+        prose: string;
+        answer: string;
+    }[];
+    /** Gates that ran, in order, with their label and outcome. */
+    readonly gates: readonly {
+        label: string;
+        terminal: boolean;
+        ok: boolean;
+    }[];
+}
+/**
+ * Drive a skill to completion (or first failed gate) with a scripted model and
+ * return a friendly summary to assert on with plain `assert`.
+ */
+export declare function runSkill(skill: SkillProgram | GeneratorSkill, opts?: {
+    cwd?: string;
+    model?: ModelFn;
+}): SkillRunResult;
+//# sourceMappingURL=skill-test.d.ts.map

package/dist/skill-test.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * vigiles — Skill testing: deterministic tests for a skill's action sequence.
+ *
+ * A thin wrapper over the generator driver (`driveSkill`) for use inside an
+ * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
+ * the *model* (the non-deterministic part) and assert the deterministic spine:
+ * which gates ran, in what order, which branch was taken, whether the result
+ * gate blocked. The model's prose quality is never asserted — that's the
+ * probabilistic boundary; everything else is deterministic and checkable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptModel = scriptModel;
+exports.runSkill = runSkill;
+const skill_driver_js_1 = require("./skill-driver.js");
+function gateLabel(g) {
+    if (g._ref === "cmd")
+        return g.command;
+    if (g._ref === "role")
+        return `project:${g.role}`;
+    return g.path;
+}
+/**
+ * Script the mocked model. Pass:
+ *  - an array — answers consumed in order across all acts; or
+ *  - a map keyed by a case-insensitive substring of the act's prose, where each
+ *    value is a single answer, or an array consumed in order *per key* (so a
+ *    loop's prompt can return different answers on successive iterations).
+ * Unmatched prose yields "".
+ */
+function scriptModel(spec) {
+    if (Array.isArray(spec)) {
+        const answers = spec;
+        let i = 0;
+        return () => answers[Math.min(i++, answers.length - 1)] ?? "";
+    }
+    const map = spec;
+    const idx = {};
+    return (prose) => {
+        const p = prose.toLowerCase();
+        for (const k of Object.keys(map)) {
+            if (!p.includes(k.toLowerCase()))
+                continue;
+            const v = map[k];
+            if (typeof v === "string")
+                return v;
+            const i = idx[k] ?? 0;
+            idx[k] = i + 1;
+            return v[Math.min(i, v.length - 1)] ?? "";
+        }
+        return "";
+    };
+}
+/**
+ * Drive a skill to completion (or first failed gate) with a scripted model and
+ * return a friendly summary to assert on with plain `assert`.
+ */
+function runSkill(skill, opts = {}) {
+    const program = typeof skill === "function" ? skill : skill.program;
+    const report = (0, skill_driver_js_1.driveSkill)(program, opts.cwd ?? process.cwd(), opts.model ?? (() => ""));
+    const acts = [];
+    const gates = [];
+    for (const t of report.trace) {
+        if (t.effect.kind === "act") {
+            acts.push({ prose: t.effect.prose, answer: t.answer ?? "" });
+        }
+        else {
+            gates.push({
+                label: gateLabel(t.effect.gate),
+                terminal: t.effect.kind === "result",
+                ok: t.outcome?.ok ?? false,
+            });
+        }
+    }
+    return { ok: report.ok, blockedAt: report.blockedAt, acts, gates };
+}
+//# sourceMappingURL=skill-test.js.map