vigiles 12.1.0 → 12.3.0

package/dist/cli-commands.d.ts

@@ -11,7 +11,7 @@
  * recognizes exactly these, so this list can't silently drift from the code.
  */
 /** Human-facing verbs (printed in help; typed by a human/agent/CI). */
-export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "scaffold-test", "generate", "hook-runtime"];
+export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "generate", "hook-runtime"];
 /** Runtime entrypoint kinds under `vigiles hook-runtime <kind>` (emitted, not typed). */
 export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
 export type Verb = (typeof VERBS)[number];

package/dist/cli-commands.js

@@ -22,7 +22,6 @@ exports.VERBS = [
     "test",
     "eval",
     "audit",
-    "scaffold-test",
     "generate",
     "hook-runtime",
 ];

package/dist/cli.js

@@ -22,8 +22,6 @@ const cli_flags_js_1 = require("./cli-flags.js");
 const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
-const scaffold_test_js_1 = require("./scaffold-test.js");
-const effects_js_1 = require("./core/effects.js");
 const scan_js_1 = require("./scan.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const dialect_drift_js_1 = require("./dialect-drift.js");
@@ -52,6 +50,7 @@ const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const observe_js_1 = require("./observe.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const refs_js_1 = require("./core/refs.js");
@@ -3488,11 +3487,29 @@ async function handleGenerateHarness(args, restArgs) {
     console.log(`\n✓ Generated ${(0, generate_harness_js_1.labelFor)(process.cwd(), fullOut)}`);
     console.log("  `tsc --noEmit` over this file now checks every delegate target resolves.");
 }
+/** Minimal TTY yes/no prompt (readline). Returns true only on an explicit y/yes. */
+async function promptYesNo(question) {
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await new Promise((res) => {
+            rl.question(question, res);
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * `vigiles test` / `vigiles eval` — discover and run the two-tier harness
  * scripts (deterministic `*.harness.mjs` / real-model `*.eval.mjs`) as child
  * `node` processes, aggregating exit codes so they work as a CI command. See
- * src/run-scripts.ts.
+ * src/run-scripts.ts. A bare `vigiles eval` (no target) asks before fanning out
+ * over the whole tree — it spends model quota (see `decideRunScripts`).
  *
  * `vigiles test` skips clean when the `claude` CLI is absent (the deterministic
  * tier needs it, just like the node:test suite). `--trials=N` is forwarded to
@@ -3533,7 +3550,7 @@ function resolveEvalLockEnv(args) {
     }
     return env;
 }
-function handleRunScripts(kind, args, restArgs) {
+async function handleRunScripts(kind, args, restArgs) {
     const cwd = process.cwd();
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
@@ -3564,6 +3581,33 @@ function handleRunScripts(kind, args, restArgs) {
         console.log(`No ${defaultGlob} files found.`);
         return;
     }
+    // Consent gate for a bare `vigiles eval`: it runs the REAL model on your
+    // subscription, and a no-target run discovered the whole tree — so never fan out
+    // over an unbounded glob without explicit intent. Mirrors audit's read-vs-run
+    // consent. `test` is free → always runs (decideRunScripts returns "run").
+    const runDecision = (0, run_scripts_js_1.decideRunScripts)({
+        kind,
+        explicitTargets: restArgs.length > 0,
+        matchedCount: files.length,
+        isTTY: (process.stdin.isTTY ?? false) && (process.stdout.isTTY ?? false),
+        all: args.includes("--all"),
+        yes: args.includes("--yes") || args.includes("--no-interactive"),
+    });
+    if (runDecision.kind === "refuse") {
+        console.error(`✗ vigiles eval: ${String(runDecision.count)} eval file(s) matched the whole tree, and each ` +
+            "runs the real model on your subscription. Refusing to fire them all non-interactively.\n" +
+            "  → name the eval(s):    vigiles eval path/to/x.eval.mjs\n" +
+            "  → or opt in to all:    vigiles eval --all");
+        process.exit(2);
+    }
+    if (runDecision.kind === "confirm") {
+        const ok = await promptYesNo(`About to run ${String(runDecision.count)} eval file(s) against the real model on your ` +
+            "subscription (uses your Claude quota). Continue? [y/N] ");
+        if (!ok) {
+            console.log("Aborted. Name specific eval(s), or pass --all to run them all.");
+            return;
+        }
+    }
     // No blanket skip: unit-tier (runHook) tests need no `claude`, so always run.
     // A script whose tier DOES need `claude` self-reports `⊘ SKIPPED` (exit 77) —
     // loud, never a silent green. Just flag up front that some may skip.
@@ -3611,135 +3655,6 @@ function capabilitiesOfReport(report, dialect) {
     }));
     return (0, generate_harness_js_1.computeHarnessCapabilities)(agents, dialect);
 }
-/**
- * The plugin's declared name for the namespaced skill id, read from the layout's
- * manifest (adapter-aware path, not a hardcoded `.claude-plugin/`), falling back to
- * the dir basename. JSON manifests only for now (a TOML/Codex manifest → basename).
- */
-function pluginNameFor(dir, manifestPath) {
-    try {
-        const manifest = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, manifestPath), "utf-8"));
-        if (typeof manifest.name === "string" && manifest.name)
-            return manifest.name;
-    }
-    catch {
-        /* missing / non-JSON manifest → fall back */
-    }
-    return (0, node_path_1.basename)(dir);
-}
-/** Enrich an untested Surface with the metadata the right template needs. */
-/** Extract `"name": type` fields from one rendered `vigiles:ok`/`err` shape block. */
-function parseContractFields(block) {
-    const fields = [];
-    const re = /"([^"]+)"\s*:\s*(string\[\]|string|number|boolean)/g;
-    let m;
-    while ((m = re.exec(block)) !== null) {
-        fields.push({ name: m[1], type: m[2] });
-    }
-    return fields;
-}
-/**
- * Parse a subagent's compiled `## Output contract` (the `vigiles:ok` / `vigiles:err`
- * blocks the compiler emits) back into a typed `ResultContract`, so the generator
- * can write an `assertAgentOk` test against the real fields. Returns null when the
- * agent has no result() contract.
- */
-function parseResultContract(md) {
-    const ok = /```vigiles:ok\n([\s\S]*?)```/.exec(md);
-    const err = /```vigiles:err\n([\s\S]*?)```/.exec(md);
-    if (!ok && !err)
-        return null;
-    const okFields = ok ? parseContractFields(ok[1]) : [];
-    const errFields = err ? parseContractFields(err[1]) : [];
-    if (okFields.length === 0 && errFields.length === 0)
-        return null;
-    return { ok: okFields, err: errFields };
-}
-function scaffoldInputFor(s, report, pluginName, dir, dialect) {
-    const base = { kind: s.kind, name: s.name, path: s.path };
-    switch (s.kind) {
-        case "skill": {
-            const sk = report.skills.find((x) => x.name === s.name);
-            return { ...base, pluginName, userInvoked: sk?.userInvoked };
-        }
-        case "agent": {
-            const ag = report.agents.find((x) => x.name === s.name);
-            const tools = ag?.tools ?? null;
-            const sideEffectingTools = tools
-                ? (0, effects_js_1.effectSurface)(tools, dialect).sideEffecting
-                : undefined;
-            let resultContract = null;
-            try {
-                resultContract = parseResultContract((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, s.path), "utf-8"));
-            }
-            catch {
-                // agent .md unreadable → no contract to generate against
-            }
-            return { ...base, tools, sideEffectingTools, resultContract };
-        }
-        case "hook":
-            return { ...base, hookCommand: `bash ${s.path}` };
-    }
-}
-/**
- * `vigiles scaffold-test [dir]` — generate a runnable STARTER test for each
- * untested skill/agent/hook (B1, test-gen from free-form). Reuses the
- * untested-surface detector for the list + `scan` for the metadata, then emits the
- * cheapest meaningful tier per kind (hook → `runHook`, skill → `measureTriggerRate`,
- * subagent → `runHarnessTest`) at the surface's suggested test path. Dry-run by
- * default (prints the scaffolds); `--write` creates the files (never clobbering an
- * existing one); `--json` for the agent-consumable `{ path, content }[]`.
- */
-function handleScaffoldTest(restArgs, args) {
-    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
-    const write = args.includes("--write");
-    const json = args.includes("--json");
-    const harnessFlag = harnessFlagFrom(args);
-    const adapter = harnessFlag
-        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
-        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
-    const { untested } = (0, test_coverage_js_1.findUntestedSurfaces)({
-        basePath: dir,
-        layout: adapter.layout,
-    });
-    const report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
-    const pluginName = pluginNameFor(dir, adapter.layout.manifestPath);
-    const scaffolds = untested.map((s) => (0, scaffold_test_js_1.scaffoldTest)(scaffoldInputFor(s, report, pluginName, dir, adapter.dialect)));
-    if (json) {
-        console.log(JSON.stringify(scaffolds, null, 2));
-        return;
-    }
-    if (!write) {
-        console.log((0, scaffold_test_js_1.formatScaffolds)(scaffolds));
-        for (const s of scaffolds) {
-            console.log(`\n# ${s.path}\n`);
-            console.log(s.content);
-        }
-        if (scaffolds.length > 0) {
-            console.log("Re-run with --write to create these files.");
-        }
-        return;
-    }
-    const written = [];
-    const skipped = [];
-    for (const s of scaffolds) {
-        const target = (0, node_path_1.resolve)(dir, s.path);
-        if ((0, node_fs_1.existsSync)(target)) {
-            skipped.push(s.path);
-            continue;
-        }
-        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
-        (0, node_fs_1.writeFileSync)(target, s.content);
-        written.push(s.path);
-    }
-    for (const p of written)
-        console.log(`✓ wrote ${p}`);
-    for (const p of skipped)
-        console.log(`⊘ skipped ${p} (already exists)`);
-    if (written.length === 0 && skipped.length === 0) {
-        console.log("Nothing to scaffold — every surface already has a test.");
-    }
-}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -3756,7 +3671,6 @@ function printUsage(command) {
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("                                 --update records each named eval's result to a committed lock (run locally on your subscription)");
     console.log("                                 --check verifies committed eval results against current inputs WITHOUT a model — the CI staleness gate");
-    console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
@@ -3862,6 +3776,11 @@ function skillStartCommand(target) {
         process.exit(2);
     }
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    // Record the fire in the flight recorder: the skill NAME is the parent dir of
+    // its SKILL.md (skills/<name>/SKILL.md), falling back to the raw target.
+    const parts = target.replace(/\\/g, "/").split("/").filter(Boolean);
+    const name = parts.length >= 2 ? parts[parts.length - 2] : (parts[0] ?? target);
+    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true });
     console.log(`Active skill: ${target}`);
 }
 /**
@@ -3962,6 +3881,13 @@ function agentHookCommand() {
         return;
     const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
+        (0, observe_js_1.appendObservation)({
+            kind: "agent",
+            name: (0, agent_runtime_js_1.readActiveAgent)(cwd) ?? "unknown",
+            tool,
+            allowed: false,
+            reason: decision.message,
+        });
         console.error(decision.message);
         process.exit(2);
     }
@@ -4510,10 +4436,26 @@ function emitGate(decision, on, mode, file) {
     const action = (0, hook_program_js_1.gateAction)(decision, mode);
     switch (action.kind) {
         case "block":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "deny",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
             console.error(action.reason);
             process.exit(2);
             return;
         case "ask":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: "ask",
+                mode: "enforce",
+                rule: file,
+                reason: action.reason,
+            });
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
                     hookEventName: on,
@@ -4523,6 +4465,14 @@ function emitGate(decision, on, mode, file) {
             }) + "\n");
             return;
         case "observe":
+            (0, observe_js_1.appendObservation)({
+                kind: "hook",
+                event: on,
+                decision: action.would,
+                mode: "observe",
+                rule: file,
+                reason: action.reason,
+            });
             recordObservation(file, on, action.would, action.reason);
             console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
             return; // exit 0 — observe never blocks
@@ -5029,10 +4979,10 @@ async function main() {
             break;
         }
         case "test":
-            handleRunScripts("test", args, restArgs);
+            await handleRunScripts("test", args, restArgs);
             break;
         case "eval":
-            handleRunScripts("eval", args, restArgs);
+            await handleRunScripts("eval", args, restArgs);
             break;
         case "audit": {
             // The Lighthouse run: a plain `audit` is a deterministic READ — rings, each
@@ -5112,10 +5062,14 @@ async function main() {
                 // Surfaced in the AuditReport (the report's "Create spec" command-emit
                 // buttons read it) and the terminal nudge below.
                 const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
+                // Read the local flight recorder ONCE — feeds both the JSON report
+                // (structured summary, the product boundary) and the terminal render.
+                const ledgerRecords = (0, observe_js_1.readObservations)(root);
                 const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
                     harness: adapter.name,
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
+                    observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);
@@ -5146,6 +5100,12 @@ async function main() {
                         .length);
                     if (fireNudge)
                         console.log("\n" + fireNudge);
+                    // The flight recorder: a compact summary of what the harness actually
+                    // DID in real sessions (hook/agent decisions), read off the local
+                    // agent-readable ledger. Empty (skipped) until something is recorded.
+                    const ledgerSummary = (0, observe_js_1.formatLedgerSummary)(ledgerRecords);
+                    if (ledgerSummary)
+                        console.log("\n" + ledgerSummary);
                 }
                 // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
                 // firing). A plain `audit` is a deterministic READ; these run only on
@@ -5179,6 +5139,21 @@ async function main() {
                     // default; `--fail-on-widen` exits non-zero (the opt-in CI gate).
                     const beforeReport = (0, scan_js_1.scanPlugin)((0, node_path_1.resolve)(capBase), adapter.layout, adapter.dialect);
                     const diff = (0, capability_diff_js_1.diffCapabilities)(capabilitiesOfReport(beforeReport, adapter.dialect), capabilitiesOfReport(report, adapter.dialect));
+                    // Feed the flight recorder: the blast-radius change (moat #2) as a record.
+                    // Write to the AUDITED root's ledger (not the caller's cwd) — the same
+                    // `root` the audit reads back via `readObservations(root)`, so a
+                    // `vigiles audit ./after --capability-diff=./before` from a parent dir
+                    // records into ./after/.vigiles/, not the parent workspace.
+                    (0, observe_js_1.appendObservation)({
+                        kind: "capability-diff",
+                        added: [
+                            ...diff.addedSideEffecting,
+                            ...diff.addedUnknown,
+                            ...diff.addedReadOnly,
+                        ],
+                        removed: [...diff.removed],
+                        widened: diff.widened,
+                    }, root);
                     console.log(json
                         ? JSON.stringify({ capabilityDiff: diff }, null, 2)
                         : "\n" + (0, capability_diff_js_1.formatCapabilityDiff)(diff));
@@ -5277,9 +5252,6 @@ async function main() {
             }
             break;
         }
-        case "scaffold-test":
-            handleScaffoldTest(restArgs, args);
-            break;
         // --- Plumbing ---
         case "generate":
             await handleGenerate(restArgs, args);

package/dist/eval.d.ts

@@ -270,6 +270,21 @@ export declare function spawnAgent(a: AgentRunArgs): Promise<RunOut>;
  * working model auth (e.g. `ANTHROPIC_API_KEY`). Thin wrapper over
  * `runEvalWith` with the real agent runner.
  */
+/**
+ * A `SKILL.md` written straight into a run's cwd (via an arm's `files`) is NOT
+ * registered as a skill by the harness. Claude Code — and Codex — load skills only
+ * from a plugin / `.claude/skills` layout, so a bare cwd `SKILL.md` sits unread:
+ * the arm silently measures NOTHING (baseline and "skill" become the same run). This
+ * is the exact footgun the ecosystem benchmark hit — a skill file delivered where it
+ * can never activate, with no error. Detect it so {@link runEval} / {@link measureArms}
+ * can WARN and point at `pluginDir` (a real `--plugin-dir` install) or `skillsDir`.
+ *
+ * HIGH-PRECISION (don't cry wolf): only a file whose basename is `SKILL.md` AND that
+ * carries real skill frontmatter (a `---` block naming `name`/`description`) is flagged
+ * — so an empty scratch `SKILL.md` a task is asked to AUTHOR is never flagged. Pure +
+ * exported for testing.
+ */
+export declare function unregisteredSkillFiles(files: Record<string, string> | undefined): string[];
 export declare function runEval<M extends Metrics>(spec: EvalSpec<M>): Promise<EvalReport>;
 /** A task run N times, scored against a `Trace` check vocabulary. */
 export interface MeasureSpec {

package/dist/eval.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = void 0;
 exports.resolveSpawnEnv = resolveSpawnEnv;
 exports.spawnAgent = spawnAgent;
+exports.unregisteredSkillFiles = unregisteredSkillFiles;
 exports.runEval = runEval;
 exports.measureWith = measureWith;
 exports.measure = measure;
@@ -65,6 +66,7 @@ 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 observe_js_1 = require("./observe.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const eval_cost_js_1 = require("./eval-cost.js");
@@ -144,7 +146,48 @@ function spawnAgent(a) {
  * working model auth (e.g. `ANTHROPIC_API_KEY`). Thin wrapper over
  * `runEvalWith` with the real agent runner.
  */
+/**
+ * A `SKILL.md` written straight into a run's cwd (via an arm's `files`) is NOT
+ * registered as a skill by the harness. Claude Code — and Codex — load skills only
+ * from a plugin / `.claude/skills` layout, so a bare cwd `SKILL.md` sits unread:
+ * the arm silently measures NOTHING (baseline and "skill" become the same run). This
+ * is the exact footgun the ecosystem benchmark hit — a skill file delivered where it
+ * can never activate, with no error. Detect it so {@link runEval} / {@link measureArms}
+ * can WARN and point at `pluginDir` (a real `--plugin-dir` install) or `skillsDir`.
+ *
+ * HIGH-PRECISION (don't cry wolf): only a file whose basename is `SKILL.md` AND that
+ * carries real skill frontmatter (a `---` block naming `name`/`description`) is flagged
+ * — so an empty scratch `SKILL.md` a task is asked to AUTHOR is never flagged. Pure +
+ * exported for testing.
+ */
+function unregisteredSkillFiles(files) {
+    if (files === undefined)
+        return [];
+    return Object.entries(files)
+        .filter(([p, c]) => skillBasename(p) && hasSkillFrontmatter(c))
+        .map(([p]) => p);
+}
+function skillBasename(path) {
+    return (path.split(/[\\/]/).pop() ?? path) === "SKILL.md";
+}
+function hasSkillFrontmatter(content) {
+    const m = /^\uFEFF?\s*---\s*\r?\n([\s\S]*?)\r?\n---/.exec(content);
+    return m !== null && /(^|\n)\s*(name|description)\s*:/.test(m[1]);
+}
+/** Warn (loud, non-fatal) for every arm that drops an unregistered skill file. */
+function warnUnregisteredSkillArms(arms) {
+    for (const [name, arm] of Object.entries(arms)) {
+        for (const path of unregisteredSkillFiles(arm.files)) {
+            console.warn(`⚠ eval arm "${name}": files["${path}"] is a SKILL.md with skill ` +
+                `frontmatter, but a SKILL.md written to the run cwd is NOT registered as a ` +
+                `skill by the harness — it never activates, so this arm measures nothing. ` +
+                `Install it via \`pluginDir\` (a real --plugin-dir plugin) or \`skillsDir\`, ` +
+                `not \`files\`. See docs/harness-testing.md.`);
+        }
+    }
+}
 async function runEval(spec) {
+    warnUnregisteredSkillArms(spec.arms);
     const report = await runEvalWith(spec, spawnAgent);
     // Surface what the run spent — tokens + API-equivalent $, and a LOUD warning if
     // it was billed to a metered API key instead of the subscription. See eval-cost.ts.
@@ -287,6 +330,7 @@ function stubArmPluginDirs(arms) {
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureArmsWith */
 /** Score checks across arms against the real `claude` CLI. */
 async function measureArms(spec) {
+    warnUnregisteredSkillArms(spec.arms);
     const report = await measureArmsWith(spec, spawnAgent);
     // Sum every arm's spend — an A/B run pays for both arms.
     (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.sumCosts)(Object.values(report.arms).map((a) => (0, eval_cost_js_1.costFromArm)(a.usage))));
@@ -1677,6 +1721,22 @@ async function measureTriggerRate(spec, opts = {}) {
     const report = await measureTriggerRateWith(spec, d.runner, d.parse, d.runError, d.harness ?? "claude-code");
     // Surface what the run spent (tokens + API-equivalent $ + metered warning).
     (0, eval_cost_js_1.emitCostSummary)((0, eval_cost_js_1.costFromArm)(report.usage));
+    // Feed the flight recorder: recall (+ precision when measured) for this skill.
+    const evalName = spec.name ?? "trigger-rate";
+    (0, observe_js_1.appendObservation)({
+        kind: "eval",
+        name: evalName,
+        metric: "recall",
+        value: report.rate,
+    });
+    if (report.precision !== undefined) {
+        (0, observe_js_1.appendObservation)({
+            kind: "eval",
+            name: evalName,
+            metric: "precision",
+            value: report.precision,
+        });
+    }
     return report;
 }
 /* v8 ignore stop */

package/dist/observe.d.ts

@@ -0,0 +1,109 @@
+/** Bumped when the record shape changes in a non-additive way. */
+export declare const OBSERVE_VERSION = 1;
+/** The ledger filename under the `.vigiles/` directory. */
+export declare const LEDGER_FILE = "runs.jsonl";
+/** Fields every record carries; `v`/`ts` are stamped by the writer, not the caller. */
+export interface ObservationBase {
+    /** schema version (`OBSERVE_VERSION`) */
+    v: number;
+    /** ISO-8601 timestamp */
+    ts: string;
+}
+/** A gate/hook decision observed in a real session. */
+export interface HookObservation extends ObservationBase {
+    kind: "hook";
+    event: string;
+    decision: "allow" | "deny" | "ask";
+    /** the compiled-hook rule/name, when known */
+    rule?: string;
+    /** enforce actually blocked; observe recorded a would-be block */
+    mode?: "enforce" | "observe";
+    /** the bash command inspected, when the gate keyed on one */
+    cmd?: string;
+    reason?: string;
+}
+/** A subagent tool-contract decision (the PreToolUse rail). */
+export interface AgentObservation extends ObservationBase {
+    kind: "agent";
+    /** the dispatched subagent */
+    name: string;
+    tool: string;
+    allowed: boolean;
+    reason?: string;
+}
+/** Whether a skill fired for a turn (behavioral surface — best-effort per harness). */
+export interface SkillObservation extends ObservationBase {
+    kind: "skill";
+    name: string;
+    fired: boolean;
+}
+/** A measured eval outcome (recall, cost, a check rate, …). */
+export interface EvalObservation extends ObservationBase {
+    kind: "eval";
+    name: string;
+    metric: string;
+    value: number;
+}
+/** A capability/blast-radius change observed at PR time. */
+export interface CapabilityDiffObservation extends ObservationBase {
+    kind: "capability-diff";
+    pr?: number;
+    added: string[];
+    removed?: string[];
+    /** true when the change loosened the agent's effect surface */
+    widened: boolean;
+}
+/** The discriminated union every reader narrows on `kind`. */
+export type ObservationRecord = HookObservation | AgentObservation | SkillObservation | EvalObservation | CapabilityDiffObservation;
+/** What a caller supplies — the writer stamps `v` + `ts`. */
+export type ObservationInput = Omit<HookObservation, "v" | "ts"> | Omit<AgentObservation, "v" | "ts"> | Omit<SkillObservation, "v" | "ts"> | Omit<EvalObservation, "v" | "ts"> | Omit<CapabilityDiffObservation, "v" | "ts">;
+/** Serialize one record to a single JSONL line (trailing newline included). */
+export declare function formatObservation(record: ObservationRecord): string;
+/**
+ * Append one observation to `<cwd>/.vigiles/runs.jsonl`. Best-effort: any failure is
+ * swallowed so recording can never break a live session (the `ts`/`clock` here is a
+ * runtime side effect, intentionally — this module records reality, it is not a spec).
+ */
+export declare function appendObservation(input: ObservationInput, cwd?: string): void;
+/**
+ * Read the ledger back. Tolerant by design: a malformed or partially-written line is
+ * skipped rather than throwing, so a torn append never nukes the whole read.
+ */
+export declare function readObservations(cwd?: string): ObservationRecord[];
+/** Filter the ledger to one record kind, narrowing the type for the caller. */
+export declare function observationsOfKind<K extends ObservationRecord["kind"]>(records: readonly ObservationRecord[], kind: K): Extract<ObservationRecord, {
+    kind: K;
+}>[];
+/** A denial rendered as a structured `{label, reason}` — the shared shape the
+ *  terminal line and the JSON summary both derive from (one-detector-no-drift). */
+export interface LedgerDenial {
+    readonly label: string;
+    readonly reason: string;
+}
+/** Per-kind record count. */
+export interface LedgerCount {
+    readonly kind: ObservationRecord["kind"];
+    readonly count: number;
+}
+/** The structured ledger summary carried in the versioned AuditReport JSON. */
+export interface LedgerSummary {
+    readonly total: number;
+    readonly counts: readonly LedgerCount[];
+    readonly denials: number;
+    /** The most recent denials (blocked gates / out-of-contract tool calls). */
+    readonly recentDenials: readonly LedgerDenial[];
+}
+/**
+ * The structured ledger summary for the AuditReport JSON — total, per-kind counts,
+ * and the recent denials. `undefined` when nothing is recorded, so the report field
+ * stays absent (additive/optional). Shares `isDenial`/`denialParts` with the
+ * terminal `formatLedgerSummary` so the two can't drift.
+ */
+export declare function summarizeObservations(records: readonly ObservationRecord[]): LedgerSummary | undefined;
+/**
+ * A compact human summary of the ledger for `vigiles audit` — total, counts by kind,
+ * and the recent high-signal denials. Empty string when there is nothing recorded, so
+ * the caller can skip the section entirely.
+ */
+export declare function formatLedgerSummary(records: readonly ObservationRecord[]): string;
+//# sourceMappingURL=observe.d.ts.map