vigiles 2.0.0 → 2.1.1

package/dist/session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Post-session audit: analyze what an agent changed vs. what specs expected.
+ *
+ * Compares the git diff (files changed since a base ref) against the spec
+ * surface area (keyFiles, commands, tracked inputs). Reports:
+ * - Files modified that aren't in any spec's keyFiles
+ * - Specs whose inputs changed (may need recompile)
+ *
+ * Read-only analysis. No commands executed, no files modified.
+ */
+import type { SidecarManifest } from "./sidecar.js";
+/**
+ * Get files changed since a base ref (commit, branch, or HEAD~N).
+ * Returns paths relative to the repo root.
+ *
+ * Uses execFileSync with an argv array — `baseRef` is passed as a separate
+ * argument so shell metacharacters can't escape into command execution.
+ * `--no-renames` keeps both source and destination paths visible (without it,
+ * `git mv old.ts new.ts` would only report `new.ts`).
+ *
+ * Throws on git failure (e.g., invalid baseRef) so a typo doesn't silently
+ * masquerade as "no changes" and suppress real findings downstream.
+ */
+export declare function gitChangedFiles(basePath: string, baseRef: string): string[];
+/**
+ * Get the most recent commit hash. Returns null if not a git repo.
+ */
+export declare function gitHead(basePath: string): string | null;
+/**
+ * Find a reasonable base ref for session analysis.
+ *
+ * Strategy:
+ * 1. If `--base` is provided, use it directly.
+ * 2. If sidecar manifests exist, use the most recent compiledAt commit.
+ * 3. Fall back to HEAD (shows only uncommitted changes).
+ */
+export declare function resolveBaseRef(explicitBase?: string): string;
+/** Aggregated surface area from all specs via sidecar manifests. */
+export interface SpecSurface {
+    /** All files declared in any spec's keyFiles. */
+    keyFiles: Set<string>;
+    /** All files tracked as inputs to any spec. */
+    trackedInputs: Set<string>;
+    /** All spec source files. */
+    specFiles: Set<string>;
+    /** All compiled targets. */
+    targets: Set<string>;
+    /** Map: file → which spec targets track it. */
+    fileToSpecs: Map<string, string[]>;
+    /** Loaded manifests. */
+    manifests: SidecarManifest[];
+}
+/**
+ * Load all sidecar manifests and build the aggregate spec surface area.
+ */
+export declare function loadSpecSurface(basePath: string): SpecSurface;
+/**
+ * Load keyFiles from compiled markdown files. Reads each target's
+ * "## Key Files" section and extracts the file paths.
+ */
+export declare function loadKeyFilesFromSpecs(basePath: string): Set<string>;
+/** A finding about a file not tracked by any spec. */
+interface UntrackedFinding {
+    type: "untracked-file";
+    file: string;
+    message: string;
+}
+/** A finding about a file tracked by one or more specs. */
+interface TrackedFinding {
+    type: "stale-spec" | "spec-modified" | "target-modified";
+    file: string;
+    message: string;
+    specs: string[];
+}
+/** A single finding from session analysis. */
+export type SessionFinding = UntrackedFinding | TrackedFinding;
+/** Full session analysis result. */
+export interface SessionReport {
+    /** Git base ref used for comparison. */
+    baseRef: string;
+    /** All files changed since baseRef. */
+    changedFiles: string[];
+    /** Files changed that are tracked by at least one spec. */
+    trackedChanges: string[];
+    /** Files changed that are NOT tracked by any spec. */
+    untrackedChanges: string[];
+    /** Individual findings. */
+    findings: SessionFinding[];
+}
+/**
+ * Analyze a session: compare changed files against spec surface area.
+ */
+export declare function analyzeSession(basePath: string, baseRef: string): SessionReport;
+/** Format a session report as human-readable text. */
+export declare function formatSessionReport(report: SessionReport): string;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Post-session audit: analyze what an agent changed vs. what specs expected.
+ *
+ * Compares the git diff (files changed since a base ref) against the spec
+ * surface area (keyFiles, commands, tracked inputs). Reports:
+ * - Files modified that aren't in any spec's keyFiles
+ * - Specs whose inputs changed (may need recompile)
+ *
+ * Read-only analysis. No commands executed, no files modified.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitChangedFiles = gitChangedFiles;
+exports.gitHead = gitHead;
+exports.resolveBaseRef = resolveBaseRef;
+exports.loadSpecSurface = loadSpecSurface;
+exports.loadKeyFilesFromSpecs = loadKeyFilesFromSpecs;
+exports.analyzeSession = analyzeSession;
+exports.formatSessionReport = formatSessionReport;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const sidecar_js_1 = require("./sidecar.js");
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+/**
+ * Get files changed since a base ref (commit, branch, or HEAD~N).
+ * Returns paths relative to the repo root.
+ *
+ * Uses execFileSync with an argv array — `baseRef` is passed as a separate
+ * argument so shell metacharacters can't escape into command execution.
+ * `--no-renames` keeps both source and destination paths visible (without it,
+ * `git mv old.ts new.ts` would only report `new.ts`).
+ *
+ * Throws on git failure (e.g., invalid baseRef) so a typo doesn't silently
+ * masquerade as "no changes" and suppress real findings downstream.
+ */
+function gitChangedFiles(basePath, baseRef) {
+    const exec = (args) => (0, node_child_process_1.execFileSync)("git", args, {
+        cwd: basePath,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    let diffOutput;
+    try {
+        diffOutput = exec([
+            "diff",
+            "--name-only",
+            "--no-renames",
+            baseRef,
+            "--",
+            ".",
+        ]);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`git diff failed for baseRef "${baseRef}": ${detail}`, {
+            cause: e,
+        });
+    }
+    let untrackedOutput = "";
+    try {
+        untrackedOutput = exec([
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            "--",
+            ".",
+        ]);
+    }
+    catch {
+        // ls-files failure is non-fatal — diff already succeeded
+    }
+    const files = new Set();
+    if (diffOutput) {
+        for (const f of diffOutput.split("\n"))
+            files.add(f);
+    }
+    if (untrackedOutput) {
+        for (const f of untrackedOutput.split("\n"))
+            files.add(f);
+    }
+    return [...files].sort();
+}
+/**
+ * Get the most recent commit hash. Returns null if not a git repo.
+ */
+function gitHead(basePath) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], {
+            cwd: basePath,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a reasonable base ref for session analysis.
+ *
+ * Strategy:
+ * 1. If `--base` is provided, use it directly.
+ * 2. If sidecar manifests exist, use the most recent compiledAt commit.
+ * 3. Fall back to HEAD (shows only uncommitted changes).
+ */
+function resolveBaseRef(explicitBase) {
+    if (explicitBase)
+        return explicitBase;
+    return "HEAD";
+}
+/**
+ * Load all sidecar manifests and build the aggregate spec surface area.
+ */
+function loadSpecSurface(basePath) {
+    const surface = {
+        keyFiles: new Set(),
+        trackedInputs: new Set(),
+        specFiles: new Set(),
+        targets: new Set(),
+        fileToSpecs: new Map(),
+        manifests: [],
+    };
+    (0, sidecar_js_1.iterateSidecars)(basePath, (_target, manifest) => {
+        surface.manifests.push(manifest);
+        surface.targets.add(manifest.target);
+        surface.specFiles.add(manifest.specFile);
+        for (const file of Object.keys(manifest.files)) {
+            surface.trackedInputs.add(file);
+            const specs = surface.fileToSpecs.get(file);
+            if (specs) {
+                specs.push(manifest.target);
+            }
+            else {
+                surface.fileToSpecs.set(file, [manifest.target]);
+            }
+        }
+    });
+    return surface;
+}
+/**
+ * Load keyFiles from compiled markdown files. Reads each target's
+ * "## Key Files" section and extracts the file paths.
+ */
+function loadKeyFilesFromSpecs(basePath) {
+    const keyFiles = new Set();
+    (0, sidecar_js_1.iterateSidecars)(basePath, (_target, manifest) => {
+        const targetPath = (0, node_path_1.resolve)(basePath, manifest.target);
+        if (!(0, node_fs_1.existsSync)(targetPath))
+            return;
+        try {
+            // Normalize CRLF → LF so the regex works on Windows checkouts.
+            const content = (0, node_fs_1.readFileSync)(targetPath, "utf-8").replace(/\r\n/g, "\n");
+            const keyFilesMatch = content.match(/## Key Files\n\n((?:- `[^`]+` — .+\n?)+)/);
+            if (keyFilesMatch) {
+                const lines = keyFilesMatch[1].split("\n");
+                for (const line of lines) {
+                    const pathMatch = line.match(/^- `([^`]+)`/);
+                    if (pathMatch)
+                        keyFiles.add(pathMatch[1]);
+                }
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    });
+    return keyFiles;
+}
+/**
+ * Analyze a session: compare changed files against spec surface area.
+ */
+function analyzeSession(basePath, baseRef) {
+    const changedFiles = gitChangedFiles(basePath, baseRef);
+    const surface = loadSpecSurface(basePath);
+    const keyFiles = loadKeyFilesFromSpecs(basePath);
+    const trackedChanges = [];
+    const untrackedChanges = [];
+    const findings = [];
+    for (const file of changedFiles) {
+        const isTracked = surface.trackedInputs.has(file) || keyFiles.has(file);
+        // Treat any *.md.spec.ts as a spec even when sidecars haven't been
+        // written yet — without this, the first compile after `vigiles init`
+        // would silently drop the spec edit from the session report.
+        const isSpec = surface.specFiles.has(file) || file.endsWith(".md.spec.ts");
+        const isTarget = surface.targets.has(file);
+        const affectedSpecs = surface.fileToSpecs.get(file);
+        if (isTarget) {
+            findings.push({
+                type: "target-modified",
+                file,
+                message: `Compiled output modified directly — edit the .spec.ts source instead`,
+                specs: affectedSpecs ?? [],
+            });
+            trackedChanges.push(file);
+        }
+        else if (isSpec) {
+            findings.push({
+                type: "spec-modified",
+                file,
+                message: "Spec modified — run `vigiles compile` to update output",
+                specs: affectedSpecs ?? [],
+            });
+            trackedChanges.push(file);
+        }
+        else if (isTracked) {
+            findings.push({
+                type: "stale-spec",
+                file,
+                message: `Tracked input changed — affected specs may need recompile`,
+                specs: affectedSpecs ?? [],
+            });
+            trackedChanges.push(file);
+        }
+        else if (!file.startsWith(".vigiles/") && !isIgnoredFile(file)) {
+            // Agent modified a file not in any spec
+            untrackedChanges.push(file);
+            findings.push({
+                type: "untracked-file",
+                file,
+                message: "Modified file not tracked by any spec",
+            });
+        }
+    }
+    return {
+        baseRef,
+        changedFiles,
+        trackedChanges,
+        untrackedChanges,
+        findings,
+    };
+}
+/** Files that are always expected to change and shouldn't be flagged. */
+function isIgnoredFile(file) {
+    return (file === "package-lock.json" ||
+        file === "yarn.lock" ||
+        file === "pnpm-lock.yaml" ||
+        file === "bun.lockb" ||
+        file.startsWith("node_modules/") ||
+        file.startsWith("dist/") ||
+        file.startsWith(".git/"));
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/** Format a session report as human-readable text. */
+function formatSessionReport(report) {
+    if (report.changedFiles.length === 0) {
+        return "No changes detected since " + report.baseRef;
+    }
+    const lines = [];
+    lines.push(`Session analysis (${String(report.changedFiles.length)} files changed since ${report.baseRef}):`);
+    lines.push("");
+    const stale = report.findings.filter((f) => f.type === "stale-spec");
+    const untracked = report.findings.filter((f) => f.type === "untracked-file");
+    const targetMods = report.findings.filter((f) => f.type === "target-modified");
+    const specMods = report.findings.filter((f) => f.type === "spec-modified");
+    if (targetMods.length > 0) {
+        lines.push("  Compiled outputs modified directly:");
+        for (const f of targetMods) {
+            lines.push(`    ${f.file} — edit the .spec.ts source instead`);
+        }
+        lines.push("");
+    }
+    if (specMods.length > 0) {
+        lines.push("  Specs modified:");
+        for (const f of specMods) {
+            lines.push(`    ${f.file} — run vigiles compile`);
+        }
+        lines.push("");
+    }
+    if (stale.length > 0) {
+        lines.push("  Tracked inputs changed (specs may need recompile):");
+        for (const f of stale) {
+            const specList = f.specs.join(", ") || "unknown";
+            lines.push(`    ${f.file} (affects ${specList})`);
+        }
+        lines.push("");
+    }
+    if (untracked.length > 0) {
+        lines.push("  Files not tracked by any spec:");
+        for (const f of untracked) {
+            lines.push(`    ${f.file}`);
+        }
+        lines.push("");
+    }
+    // Summary
+    const issues = targetMods.length + stale.length;
+    if (issues === 0 && untracked.length === 0) {
+        lines.push("  All changes are within spec surface area.");
+    }
+    else {
+        const parts = [];
+        if (targetMods.length > 0)
+            parts.push(`${String(targetMods.length)} compiled output(s) edited directly`);
+        if (stale.length > 0)
+            parts.push(`${String(stale.length)} input(s) changed`);
+        if (untracked.length > 0)
+            parts.push(`${String(untracked.length)} untracked file(s)`);
+        lines.push("  Summary: " + parts.join(", "));
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=session.js.map

package/dist/sidecar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-spec sidecar manifests stored at `.vigiles/<target>.inputs.json`.
+ *
+ * Used by the post-session audit to know which targets exist and which
+ * spec source / inputs each one tracks. The compile pipeline writes
+ * these whenever a spec is built; readers (currently only session.ts)
+ * consume them at audit time.
+ *
+ * This module is the ONLY place sidecars live now — the freshness rule
+ * doesn't depend on them anymore.
+ */
+export interface SidecarManifest {
+    /** The spec source file (relative to basePath). */
+    specFile: string;
+    /** The compilation target (e.g., "CLAUDE.md"). */
+    target: string;
+    /** ISO 8601 timestamp of last compilation. */
+    compiledAt: string;
+    /** Per-file SHA-256 hashes (truncated, 16 hex chars). */
+    files: Record<string, string>;
+}
+export declare function sidecarPath(basePath: string, target: string): string;
+export declare function writeSidecarManifest(basePath: string, manifest: SidecarManifest): void;
+export declare function readSidecarManifest(basePath: string, target: string): SidecarManifest | null;
+export declare function computePerFileHashes(inputFiles: string[], basePath: string): Record<string, string>;
+/**
+ * Iterate all sidecar manifests under `.vigiles/`, including nested
+ * directories. Handles directory-not-found and read errors gracefully.
+ *
+ * Recurses so that nested targets (e.g. `.github/copilot-instructions.md`,
+ * which lives at `.vigiles/.github/copilot-instructions.md.inputs.json`)
+ * are not silently skipped.
+ */
+export declare function iterateSidecars(basePath: string, fn: (target: string, manifest: SidecarManifest) => void): void;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Per-spec sidecar manifests stored at `.vigiles/<target>.inputs.json`.
+ *
+ * Used by the post-session audit to know which targets exist and which
+ * spec source / inputs each one tracks. The compile pipeline writes
+ * these whenever a spec is built; readers (currently only session.ts)
+ * consume them at audit time.
+ *
+ * This module is the ONLY place sidecars live now — the freshness rule
+ * doesn't depend on them anymore.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sidecarPath = sidecarPath;
+exports.writeSidecarManifest = writeSidecarManifest;
+exports.readSidecarManifest = readSidecarManifest;
+exports.computePerFileHashes = computePerFileHashes;
+exports.iterateSidecars = iterateSidecars;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hash_js_1 = require("./hash.js");
+const SIDECAR_ROOT = ".vigiles";
+const MANIFEST_SUFFIX = ".inputs.json";
+function sidecarPath(basePath, target) {
+    return (0, node_path_1.resolve)(basePath, SIDECAR_ROOT, `${target}${MANIFEST_SUFFIX}`);
+}
+function writeSidecarManifest(basePath, manifest) {
+    // Targets can be nested (e.g. ".github/copilot-instructions.md"), so
+    // ensure every intermediate directory under .vigiles/ exists before
+    // writing — otherwise writeFileSync throws ENOENT.
+    const filePath = sidecarPath(basePath, manifest.target);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(filePath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(manifest, null, 2) + "\n");
+}
+function readSidecarManifest(basePath, target) {
+    const filePath = sidecarPath(basePath, target);
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function computePerFileHashes(inputFiles, basePath) {
+    const result = {};
+    for (const f of inputFiles) {
+        const fullPath = (0, node_path_1.resolve)(basePath, f);
+        result[f] = (0, node_fs_1.existsSync)(fullPath)
+            ? (0, hash_js_1.sha256short)((0, node_fs_1.readFileSync)(fullPath))
+            : "MISSING";
+    }
+    return result;
+}
+/**
+ * Iterate all sidecar manifests under `.vigiles/`, including nested
+ * directories. Handles directory-not-found and read errors gracefully.
+ *
+ * Recurses so that nested targets (e.g. `.github/copilot-instructions.md`,
+ * which lives at `.vigiles/.github/copilot-instructions.md.inputs.json`)
+ * are not silently skipped.
+ */
+function iterateSidecars(basePath, fn) {
+    const root = (0, node_path_1.resolve)(basePath, SIDECAR_ROOT);
+    if (!(0, node_fs_1.existsSync)(root))
+        return;
+    walk(root, root, basePath, fn);
+}
+function walk(dir, root, basePath, fn) {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = (0, node_path_1.resolve)(dir, entry);
+        let isDir;
+        try {
+            isDir = (0, node_fs_1.statSync)(fullPath).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            walk(fullPath, root, basePath, fn);
+            continue;
+        }
+        if (!entry.endsWith(MANIFEST_SUFFIX))
+            continue;
+        // Reconstruct the target name from the path relative to .vigiles/
+        const rel = (0, node_path_1.relative)(root, fullPath);
+        const target = rel.slice(0, -MANIFEST_SUFFIX.length);
+        const manifest = readSidecarManifest(basePath, target);
+        if (!manifest)
+            continue;
+        fn(target, manifest);
+    }
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/spec.d.ts

@@ -8,8 +8,8 @@
  *   enforce() — delegated to an external linter (ESLint, Ruff, Clippy, etc.)
  *   guidance() — prose only, no mechanical enforcement
  */
-/** Linters vigiles can cross-reference. */
-type BuiltinLinter = "eslint" | "stylelint" | "ruff" | "clippy" | "pylint" | "rubocop";
+/** Linters and policy catalogs vigiles can cross-reference. */
+type BuiltinLinter = "eslint" | "stylelint" | "ruff" | "clippy" | "pylint" | "rubocop" | "cedar";
 /** Scoped ESLint plugin prefix (e.g., @typescript-eslint). */
 type ScopedPlugin = `@${string}/${string}`;
 /** A linter/rule reference: "eslint/no-console", "ruff/T201", "@typescript-eslint/no-explicit-any". */
@@ -52,12 +52,12 @@ export type StrictFile = [keyof KnownProjectFiles] extends [never] ? string : Kn
 export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm run ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | `npm ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | (string & {});
 export type ClaudeTool = "Read" | "Write" | "Edit" | "Bash" | "Grep" | "Glob" | "Agent" | "TodoWrite" | "WebSearch" | "WebFetch" | "NotebookEdit";
 export type HookEvent = "PreToolUse" | "PostToolUse" | "PreSession" | "PostSession" | "Notification";
-/** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.). */
+/** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
-    readonly linterRule: LinterRule;
+    readonly linterRule: LinterRule | VigilesRef;
     readonly why: string;
-    /** Skip linter verification for this rule. Default: true (verify). */
+    /** Skip verification for this rule. Default: true (verify). */
     readonly verify: boolean;
 }
 /** A guidance-only rule (prose, no enforcement). */
@@ -65,18 +65,28 @@ export interface GuidanceRule {
     readonly _kind: "guidance";
     readonly text: string;
 }
-export type Rule = EnforceRule | GuidanceRule;
+/** A reactive rule: runs a command when watched files change. */
+export interface GuardRule {
+    readonly _kind: "guard";
+    readonly watch: string | readonly string[];
+    readonly run: string;
+    readonly description: string;
+}
+export type Rule = EnforceRule | GuidanceRule | GuardRule;
 /**
- * Declare a rule enforced by an external tool.
+ * Declare a rule enforced by an external tool or vigiles itself.
  *
  * When generated types are present, the `linterRule` argument is narrowed
- * to only accept rules that exist in your linter configs.
+ * to only accept rules that exist in your linter configs. Vigiles-internal
+ * checks use the `vigiles/<assertion-id>` namespace and are dispatched to
+ * built-in mechanical validators (e.g. `vigiles/orphan-docs`).
  *
  *   enforce("eslint/no-console", "Use structured logger.")
  *   enforce("@typescript-eslint/no-floating-promises", "Always await.")
  *   enforce("ruff/T201", "Use logging module.")
+ *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
-export declare function enforce(linterRule: NoInfer<StrictLinterRule>, why: string, options?: {
+export declare function enforce(ref: NoInfer<StrictLinterRule> | VigilesRef, why: string, options?: {
     verify?: boolean;
 }): EnforceRule;
 /**
@@ -85,6 +95,16 @@ export declare function enforce(linterRule: NoInfer<StrictLinterRule>, why: stri
  *   guidance("Google unfamiliar APIs before implementing.")
  */
 export declare function guidance(text: string): GuidanceRule;
+/**
+ * Declare a reactive guard: runs a command when watched files change.
+ *
+ *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ */
+export declare function guard(options: {
+    watch: string | readonly string[];
+    run: string;
+}, description: string): GuardRule;
 /**
  * Branded string types — these prove a reference has gone through
  * vigiles's verification. The compiler only accepts branded refs,

package/dist/spec.js

@@ -12,6 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforce = enforce;
 exports.guidance = guidance;
+exports.guard = guard;
 exports.file = file;
 exports.cmd = cmd;
 exports.ref = ref;
@@ -23,20 +24,23 @@ exports.defineConfig = defineConfig;
 // Builder functions
 // ---------------------------------------------------------------------------
 /**
- * Declare a rule enforced by an external tool.
+ * Declare a rule enforced by an external tool or vigiles itself.
  *
  * When generated types are present, the `linterRule` argument is narrowed
- * to only accept rules that exist in your linter configs.
+ * to only accept rules that exist in your linter configs. Vigiles-internal
+ * checks use the `vigiles/<assertion-id>` namespace and are dispatched to
+ * built-in mechanical validators (e.g. `vigiles/orphan-docs`).
  *
  *   enforce("eslint/no-console", "Use structured logger.")
  *   enforce("@typescript-eslint/no-floating-promises", "Always await.")
  *   enforce("ruff/T201", "Use logging module.")
+ *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
-function enforce(linterRule, why, options) {
+function enforce(ref, why, options) {
     return {
         _kind: "enforce",
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-        linterRule: linterRule,
+        linterRule: ref,
         why,
         verify: options?.verify ?? true,
     };
@@ -49,6 +53,20 @@ function enforce(linterRule, why, options) {
 function guidance(text) {
     return { _kind: "guidance", text };
 }
+/**
+ * Declare a reactive guard: runs a command when watched files change.
+ *
+ *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ */
+function guard(options, description) {
+    return {
+        _kind: "guard",
+        watch: options.watch,
+        run: options.run,
+        description,
+    };
+}
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.

package/dist/test-utils.d.ts

@@ -0,0 +1,8 @@
+import type { ClaudeSpec } from "./spec.js";
+export declare function makeTmpDir(suffix?: string): string;
+export declare function cleanupTmpDir(dir: string): void;
+export declare function makeSpec(overrides?: Partial<ClaudeSpec>): ClaudeSpec;
+declare function git(cwd: string, cmd: string): string;
+export declare function initGitRepo(dir: string): void;
+export { git };
+//# sourceMappingURL=test-utils.d.ts.map