vigiles 2.1.1 → 2.2.0

package/dist/mock-model.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptModel = scriptModel;
+exports.startMock = startMock;
+/**
+ * vigiles — a scripted, deterministic Anthropic Messages API mock.
+ *
+ * Point a Claude Code client at it with `ANTHROPIC_BASE_URL` (and any dummy
+ * `ANTHROPIC_API_KEY`) and it serves a fixed *script* of model turns in order —
+ * each `POST /v1/messages` returns the next. This is the seam that makes harness
+ * testing deterministic: the real `claude` CLI runs your real hooks/settings,
+ * but the model's turns are scripted, so the outcome is reproducible and free.
+ *
+ *   scriptModel([
+ *     { tool: "Write", input: { file_path: "SKILL.md", content: "..." } },
+ *     { text: "done" },
+ *   ])
+ *
+ * Implements the parts a real client needs: SSE streaming (flushed per event),
+ * `/v1/messages/count_tokens` (else Claude Code hangs), HEAD/health tolerance,
+ * and echoing the requested model.
+ */
+const node_http_1 = __importDefault(require("node:http"));
+/** Build a scripted model from an ordered list of turns. */
+function scriptModel(turns) {
+    return [...turns];
+}
+function writeEvent(res, event, data) {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+const rid = (p) => `${p}${Math.random().toString(36).slice(2, 10)}`;
+function streamTurn(res, turn, model) {
+    res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+    });
+    writeEvent(res, "message_start", {
+        type: "message_start",
+        message: {
+            id: rid("msg_"),
+            type: "message",
+            role: "assistant",
+            model,
+            content: [],
+            stop_reason: null,
+            usage: { input_tokens: 10, output_tokens: 1 },
+        },
+    });
+    if (turn.tool) {
+        writeEvent(res, "content_block_start", {
+            type: "content_block_start",
+            index: 0,
+            content_block: {
+                type: "tool_use",
+                id: rid("toolu_"),
+                name: turn.tool,
+                input: {},
+            },
+        });
+        writeEvent(res, "content_block_delta", {
+            type: "content_block_delta",
+            index: 0,
+            delta: {
+                type: "input_json_delta",
+                partial_json: JSON.stringify(turn.input ?? {}),
+            },
+        });
+        writeEvent(res, "content_block_stop", {
+            type: "content_block_stop",
+            index: 0,
+        });
+        writeEvent(res, "message_delta", {
+            type: "message_delta",
+            delta: { stop_reason: "tool_use", stop_sequence: null },
+            usage: { output_tokens: 5 },
+        });
+    }
+    else {
+        writeEvent(res, "content_block_start", {
+            type: "content_block_start",
+            index: 0,
+            content_block: { type: "text", text: "" },
+        });
+        writeEvent(res, "content_block_delta", {
+            type: "content_block_delta",
+            index: 0,
+            delta: { type: "text_delta", text: turn.text ?? "" },
+        });
+        writeEvent(res, "content_block_stop", {
+            type: "content_block_stop",
+            index: 0,
+        });
+        writeEvent(res, "message_delta", {
+            type: "message_delta",
+            delta: { stop_reason: "end_turn", stop_sequence: null },
+            usage: { output_tokens: 5 },
+        });
+    }
+    writeEvent(res, "message_stop", { type: "message_stop" });
+    res.end();
+}
+function jsonTurn(res, turn, model) {
+    const content = turn.tool
+        ? [
+            {
+                type: "tool_use",
+                id: rid("toolu_"),
+                name: turn.tool,
+                input: turn.input ?? {},
+            },
+        ]
+        : [{ type: "text", text: turn.text ?? "" }];
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({
+        id: rid("msg_"),
+        type: "message",
+        role: "assistant",
+        model,
+        stop_reason: turn.tool ? "tool_use" : "end_turn",
+        stop_sequence: null,
+        content,
+        usage: { input_tokens: 10, output_tokens: 5 },
+    }));
+}
+/**
+ * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
+ * next turn (the last turn repeats if the client asks for more). Resolves to a
+ * handle with the base `url` and a `close()`.
+ */
+function startMock(script, opts = {}) {
+    let i = 0;
+    const server = node_http_1.default.createServer((req, res) => {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+            const url = req.url ?? "";
+            const isCount = url.includes("count_tokens");
+            const isMessages = url.includes("/v1/messages") && !isCount;
+            let reqBody = {};
+            try {
+                reqBody = JSON.parse(body);
+            }
+            catch {
+                /* HEAD / health checks have no JSON body */
+            }
+            if (req.method === "HEAD" || (!isMessages && !isCount)) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end("{}");
+                return;
+            }
+            if (isCount) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ input_tokens: 10 }));
+                return;
+            }
+            const last = JSON.stringify(reqBody.messages?.at(-1)?.content ?? "");
+            opts.onTurn?.({
+                n: i,
+                stream: reqBody.stream === true,
+                hasToolResult: last.includes('"tool_result"'),
+            });
+            const turn = script[Math.min(i, script.length - 1)] ?? { text: "" };
+            i++;
+            const model = reqBody.model ?? "claude-mock";
+            if (reqBody.stream === true)
+                streamTurn(res, turn, model);
+            else
+                jsonTurn(res, turn, model);
+        });
+    });
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            resolve({
+                url: `http://127.0.0.1:${String(port)}`,
+                close: () => server.close(),
+                get count() {
+                    return i;
+                },
+            });
+        });
+    });
+}
+//# sourceMappingURL=mock-model.js.map

package/dist/refs.d.ts

@@ -0,0 +1,44 @@
+/** An inline code span with its 1-based source line. */
+export interface Span {
+    readonly text: string;
+    readonly line: number;
+}
+/**
+ * Extract inline code spans, skipping fenced code blocks (R1). Returns each
+ * span's trimmed text and 1-based line.
+ */
+export declare function inlineSpans(markdown: string): Span[];
+/** A parsed file-qualified reference. */
+export interface SymbolRef {
+    readonly file: string;
+    readonly symbol: string;
+    readonly line: number;
+}
+/** A reference that failed verification. */
+export interface SymbolRefError extends SymbolRef {
+    readonly reason: string;
+}
+/** Extract the `vigiles:symbol` references from a markdown file. */
+export declare function symbolRefs(markdown: string): SymbolRef[];
+/**
+ * Verify the file-qualified symbol references in a markdown file: the named
+ * file must exist and define the named symbol. `basePath` is the directory the
+ * paths resolve against (the instruction file's own directory).
+ */
+export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
+/**
+ * Whether a span looks like a *code reference* that ought to carry a
+ * file-qualified mark — a scoped name, or an identifier that isn't a bare
+ * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
+ * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
+ * refs).
+ */
+export declare function isCodeShaped(text: string): boolean;
+/**
+ * Code-shaped inline references that are NOT yet marked — the spans the
+ * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
+ * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
+ * for the whole file).
+ */
+export declare function unmarkedCodeRefs(markdown: string): Span[];
+//# sourceMappingURL=refs.d.ts.map

package/dist/refs.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inlineSpans = inlineSpans;
+exports.symbolRefs = symbolRefs;
+exports.verifySymbolRefs = verifySymbolRefs;
+exports.isCodeShaped = isCodeShaped;
+exports.unmarkedCodeRefs = unmarkedCodeRefs;
+/**
+ * vigiles — file-qualified symbol reference verification (variant A).
+ *
+ * A reference names both the file and the symbol, as an inline code span:
+ *
+ *     See `src/config.ts#parseConfig` for the loader.
+ *     Render with `app/models/user.rb#full_name`.
+ *
+ * We parse *that one named file* and check it defines the symbol. No
+ * project-wide index, no cross-file resolution, no autoloader chasing, no
+ * ambiguity (the file disambiguates). Because the `path.ext#symbol` shape is
+ * unmistakable and deliberately written, it is a *declared* reference — like
+ * `vigiles:file` / `vigiles:cmd` — so a broken one is an **error**, not an
+ * inferred-prose warning. The author names the file; vigiles proves the symbol.
+ *
+ * R1 (cross-compat): only inline code spans are read. Fenced code blocks are
+ * never touched, so rustdoc doctests / typescript-docs-verifier keep working.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const symbols_js_1 = require("./symbols.js");
+const FENCE = /^\s*```/;
+const SPAN = /`([^`\n]+)`/g;
+/**
+ * Extract inline code spans, skipping fenced code blocks (R1). Returns each
+ * span's trimmed text and 1-based line.
+ */
+function inlineSpans(markdown) {
+    const spans = [];
+    let inFence = false;
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (FENCE.test(lines[i])) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const m of lines[i].matchAll(SPAN)) {
+            spans.push({ text: m[1].trim(), line: i + 1 });
+        }
+    }
+    return spans;
+}
+// A file-qualified symbol reference: `<path>.<ext>` then `#`/`::` then a symbol.
+// Requires a real file extension before the separator, so a bare scoped symbol
+// An explicit `vigiles:symbol <path>.<ext>#<symbol>` directive inside a code
+// span. The literal `vigiles:symbol` prefix means zero detection heuristic — a
+// span either carries it or it does not — consistent with the rest of vigiles'
+// markers. The mark is self-contained (file + symbol in one inline token), so
+// it binds unambiguously even in a long line with several references.
+const SYMBOL_MARK = /^vigiles:symbol\s+([\w@./-]+\.[A-Za-z0-9]+)(?:#|::)([A-Za-z_]\w*[?!]?)$/;
+/** Extract the `vigiles:symbol` references from a markdown file. */
+function symbolRefs(markdown) {
+    const refs = [];
+    for (const span of inlineSpans(markdown)) {
+        const m = SYMBOL_MARK.exec(span.text);
+        if (m)
+            refs.push({ file: m[1], symbol: m[2], line: span.line });
+    }
+    return refs;
+}
+/**
+ * Verify the file-qualified symbol references in a markdown file: the named
+ * file must exist and define the named symbol. `basePath` is the directory the
+ * paths resolve against (the instruction file's own directory).
+ */
+function verifySymbolRefs(markdown, basePath) {
+    const errors = [];
+    for (const ref of symbolRefs(markdown)) {
+        const full = (0, node_path_1.resolve)(basePath, ref.file);
+        if (!(0, node_fs_1.existsSync)(full)) {
+            errors.push({ ...ref, reason: `File not found: "${ref.file}"` });
+        }
+        else if ((0, symbols_js_1.langForFile)(ref.file) === null) {
+            errors.push({
+                ...ref,
+                reason: `Unsupported language for symbol check: "${ref.file}"`,
+            });
+        }
+        else if (!(0, symbols_js_1.fileDefinesSymbol)(full, ref.symbol)) {
+            errors.push({
+                ...ref,
+                reason: `"${ref.symbol}" is not defined in ${ref.file}`,
+            });
+        }
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Enforcement: force code references to carry the file-qualified mark
+// ---------------------------------------------------------------------------
+const PATH_LIKE = /[/\\]|\.[A-Za-z0-9]+$/; // a path or a bare filename
+const PLAIN_ID = /^[A-Za-z_]\w*$/;
+const SCOPED = /^[A-Za-z_]\w*(?:#|::)[\w?!]+$/;
+const IGNORE_FILE = /<!--\s*vigiles:ignore-file\s*-->/;
+const IGNORE_LINE = /<!--\s*vigiles:ignore\s*-->/;
+/**
+ * Whether a span looks like a *code reference* that ought to carry a
+ * file-qualified mark — a scoped name, or an identifier that isn't a bare
+ * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
+ * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
+ * refs).
+ */
+function isCodeShaped(text) {
+    const callee = text.replace(/\s*\([^)]*\)\s*$/, ""); // `foo(args)` → `foo`
+    if (SCOPED.test(callee))
+        return true;
+    if (!PLAIN_ID.test(callee))
+        return false;
+    const hasUnderscore = callee.includes("_");
+    const hasCamel = /[a-z][A-Z]/.test(callee);
+    const isPascal = /^[A-Z][a-z]/.test(callee);
+    const isScreaming = /^[A-Z][A-Z0-9_]+$/.test(callee);
+    return hasUnderscore || hasCamel || isPascal || isScreaming;
+}
+/**
+ * Code-shaped inline references that are NOT yet marked — the spans the
+ * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
+ * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
+ * for the whole file).
+ */
+function unmarkedCodeRefs(markdown) {
+    if (IGNORE_FILE.test(markdown))
+        return [];
+    const lines = markdown.split("\n");
+    return inlineSpans(markdown).filter((span) => {
+        if (IGNORE_LINE.test(lines[span.line - 1] ?? ""))
+            return false;
+        if (SYMBOL_MARK.test(span.text))
+            return false; // already a vigiles:symbol mark
+        if (PATH_LIKE.test(span.text))
+            return false; // a path/filename → file ref
+        return isCodeShaped(span.text);
+    });
+}
+//# sourceMappingURL=refs.js.map

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