vigiles 12.1.0 → 12.2.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");
@@ -3611,135 +3610,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 +3626,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 +3731,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 +3836,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 +4391,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 +4420,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
@@ -5112,10 +5017,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 +5055,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 +5094,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 +5207,6 @@ async function main() {
             }
             break;
         }
-        case "scaffold-test":
-            handleScaffoldTest(restArgs, args);
-            break;
         // --- Plumbing ---
         case "generate":
             await handleGenerate(restArgs, args);

package/dist/eval.js

@@ -65,6 +65,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");
@@ -1677,6 +1678,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

package/dist/observe.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEDGER_FILE = exports.OBSERVE_VERSION = void 0;
+exports.formatObservation = formatObservation;
+exports.appendObservation = appendObservation;
+exports.readObservations = readObservations;
+exports.observationsOfKind = observationsOfKind;
+exports.summarizeObservations = summarizeObservations;
+exports.formatLedgerSummary = formatLedgerSummary;
+/**
+ * The local, agent-readable "flight recorder" ledger — `.vigiles/runs.jsonl`.
+ *
+ * The connective layer of the four-instrument loop (see the Direction section of
+ * CLAUDE.md and `research/harness-observability-direction.md`): every instrument
+ * (verify / gate / measure / observe) appends a typed record here, and the file is
+ * read three ways off ONE schema — by `vigiles audit`, by the agent debugging its own
+ * harness, and (later) by an aggregation surface.
+ *
+ * Harness-agnostic by construction: the record kinds are neutral concepts, so this
+ * lives at the composition/library root (adapters + cli CALL it; it imports no adapter,
+ * and it is NOT part of the reference-verification `core/` domain).
+ *
+ * Append is best-effort — recording must never break a live session.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Bumped when the record shape changes in a non-additive way. */
+exports.OBSERVE_VERSION = 1;
+/** The ledger filename under the `.vigiles/` directory. */
+exports.LEDGER_FILE = "runs.jsonl";
+/** Serialize one record to a single JSONL line (trailing newline included). */
+function formatObservation(record) {
+    return JSON.stringify(record) + "\n";
+}
+/**
+ * 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).
+ */
+function appendObservation(input, cwd = process.cwd()) {
+    try {
+        const dir = (0, node_path_1.resolve)(cwd, ".vigiles");
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const record = {
+            v: exports.OBSERVE_VERSION,
+            ts: new Date().toISOString(),
+            ...input,
+        };
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, exports.LEDGER_FILE), formatObservation(record));
+    }
+    catch {
+        /* best-effort — recording is never allowed to break a session */
+    }
+}
+/**
+ * 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.
+ */
+function readObservations(cwd = process.cwd()) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, ".vigiles", exports.LEDGER_FILE), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parsed = tryParseRecord(trimmed);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** Filter the ledger to one record kind, narrowing the type for the caller. */
+function observationsOfKind(records, kind) {
+    return records.filter((r) => r.kind === kind);
+}
+/** Was this record a denial (a blocked gate or an out-of-contract tool call)? */
+function isDenial(r) {
+    return ((r.kind === "hook" && r.decision === "deny") ||
+        (r.kind === "agent" && !r.allowed));
+}
+/** Structured description of a denial (the single source for label + reason). */
+function denialParts(r) {
+    if (r.kind === "hook")
+        return { label: `hook ${r.rule ?? r.event}`, reason: r.reason ?? "denied" };
+    if (r.kind === "agent")
+        return {
+            label: `${r.name} → ${r.tool}`,
+            reason: r.reason ?? "outside contract",
+        };
+    return { label: r.kind, reason: "" };
+}
+/** One line describing a denial for the terminal summary. */
+function denialLine(r) {
+    const d = denialParts(r);
+    return `    ✗ ${d.label}: ${d.reason}`;
+}
+/**
+ * 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.
+ */
+function summarizeObservations(records) {
+    if (records.length === 0)
+        return undefined;
+    const map = new Map();
+    for (const r of records)
+        map.set(r.kind, (map.get(r.kind) ?? 0) + 1);
+    const denied = records.filter(isDenial);
+    return {
+        total: records.length,
+        counts: Array.from(map.entries()).map(([kind, count]) => ({ kind, count })),
+        denials: denied.length,
+        recentDenials: denied.slice(-5).map(denialParts),
+    };
+}
+/**
+ * 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.
+ */
+function formatLedgerSummary(records) {
+    if (records.length === 0)
+        return "";
+    const lines = [
+        `Flight recorder — ${records.length} record${records.length === 1 ? "" : "s"} in .vigiles/${exports.LEDGER_FILE}`,
+    ];
+    const counts = new Map();
+    for (const r of records)
+        counts.set(r.kind, (counts.get(r.kind) ?? 0) + 1);
+    const byKind = Array.from(counts.entries())
+        .map(([k, n]) => `${n} ${k}`)
+        .join(", ");
+    lines.push(`  by kind: ${byKind}`);
+    const denials = records.filter(isDenial);
+    if (denials.length > 0) {
+        lines.push(`  recent denials (${denials.length}):`);
+        for (const r of denials.slice(-5))
+            lines.push(denialLine(r));
+    }
+    return lines.join("\n");
+}
+/** Parse one JSONL line into a record, or `null` if it is not a well-formed record. */
+function tryParseRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        if (value &&
+            typeof value === "object" &&
+            typeof value.kind === "string") {
+            return value;
+        }
+    }
+    catch {
+        /* tolerate a torn/malformed line */
+    }
+    return null;
+}
+//# sourceMappingURL=observe.js.map

package/dist/scaffold-test.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.scaffoldTest = scaffoldTest;
 exports.formatScaffolds = formatScaffolds;
 /**
- * `vigiles scaffold-test` — the deterministic test-gen engine (B1 v0).
+ * The deterministic test-gen engine (B1 v0) — skill-internal (the `test-harness`
+ * skill drives it; there is no standalone CLI verb).
  *
  * Free-form in, a RUNNABLE starter test out. Given an existing hand-written
  * skill / subagent / hook, emit a scaffolded `*.harness.mjs` / `*.eval.mjs` at the
@@ -35,7 +36,7 @@ function header(title, run) {
         "/**",
         ` * ${title}`,
         " *",
-        " * Generated by `vigiles scaffold-test` — a STARTER, not a finished test. Fill in",
+        " * Generated by vigiles (the test-harness skill) — a STARTER, not a finished test. Fill in",
         " * the TODOs (they're where a human/model must supply judgement), then run:",
         ` *   ${run}`,
         " */",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",