vigiles 12.1.0 → 12.2.0

package/skills/debug-my-harness/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: debug-my-harness
+description: Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
+---
+
+Diagnose harness misbehavior from the **flight recorder** — the local, append-only ledger
+at `.vigiles/runs.jsonl` that vigiles writes as your harness runs. It records what actually
+happened, so you debug from evidence instead of guessing.
+
+## What's in the ledger
+
+One JSON record per line, each with a `kind`:
+
+- `hook` — a compiled-hook gate decision: `{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}`.
+- `agent` — a subagent tool-contract decision: `{name, tool, allowed, reason}` (a `false` = the agent went outside its lane).
+- `skill` — a skill activation: `{name, fired}`.
+- `eval` — a measured metric: `{name, metric, value}` (e.g. trigger-rate recall/precision).
+- `capability-diff` — a blast-radius change: `{pr, added, removed, widened}`.
+
+## Instructions
+
+### Step 1: Read the ledger
+
+Read `.vigiles/runs.jsonl` (JSONL — one record per line; tolerate a torn last line). If it's
+absent or empty, say so — there's nothing recorded yet; suggest running the harness (or
+`vigiles audit`) first. Do NOT fabricate records.
+
+### Step 2: Answer the specific question, evidence-first
+
+Match the user's question to the ledger:
+
+- **"Why did skill X stop firing / why does the wrong one run?"** — count `skill` fires by
+  name over time. If X's fire-rate dropped, look for a sibling that fired on the same kinds
+  of prompts (a **selection collision**) and check their descriptions for overlap. Recommend
+  differentiating or merging the descriptions.
+- **"Why didn't my hook block that?"** — find `hook` records for the event. A `decision:
+allow` on something that should be denied, or `mode: observe` (shadow, never blocks), or
+  the absence of any record, tells you which. Recommend flipping `observe`→`enforce` or
+  fixing the gate logic.
+- **"Did a subagent misbehave?"** — list `agent` records with `allowed: false`: the agent
+  reached for a tool outside its declared contract. Point at the contract to tighten or widen.
+- **"Is it getting worse?"** — compare `eval` metric values (recall/precision) across runs;
+  a downward trend is drift (often after a harness/model upgrade).
+
+### Step 3: Recommend a fix, tied to the evidence
+
+Prefer **promoting an ignored-but-decidable rule from prose to a deterministic gate**: a
+repeated `agent` violation or a rule the agent keeps breaking → a compiled hook or a tighter
+tool-contract (the `strengthen` skill can help). A description collision → differentiate the
+skill descriptions. Always cite the specific records you based the diagnosis on.
+
+### Step 4: Offer the next step
+
+If the fix is a spec change, hand off to `edit-spec`. If it's promoting guidance to a linter
+rule, hand off to `strengthen`. If a behavioral claim needs measuring (does the skill fire
+now?), hand off to `test-harness` (`measureTriggerRate`).

package/dist/core/hook-spec.d.ts

@@ -1,74 +0,0 @@
-/** A hook's declared side-effect posture. */
-export type HookEffect = "observe" | "mutate";
-/** A declared hook (the typed source the compiler reads). */
-export interface HookSpec {
-    /** The harness event, e.g. "PreToolUse" | "PostToolUse". */
-    readonly event: string;
-    /** The tool name(s) the hook matches, e.g. ["Bash"] or ["Edit", "Write"]. */
-    readonly match: readonly string[];
-    /** The `tool_input` fields the hook extracts (must exist on the matched tools). */
-    readonly reads: readonly string[];
-    /** Observe-only (a gate/checker) or allowed to mutate (an action runner). */
-    readonly effect: HookEffect;
-    /** Optional command the hook runs — classified against {@link effect}. */
-    readonly run?: string;
-}
-/** Build a hook spec (the untyped on-ramp; see `hookFor` for the typed one). */
-export declare const hook: (spec: HookSpec) => HookSpec;
-/** tool name → the `tool_input` fields it carries (injected; harness-specific). */
-export type ToolFieldCatalog = Record<string, readonly string[]>;
-export interface HookIssue {
-    readonly severity: "error" | "warning";
-    readonly message: string;
-}
-export interface ValidateHookOptions {
-    /** The per-tool `tool_input` field catalog for the active harness. */
-    readonly toolFields: ToolFieldCatalog;
-    /** The harness's known event names (optional — skips the event check if absent). */
-    readonly events?: readonly string[];
-}
-/**
- * Validate a hook spec — the compiler half. Flags wrong-field extraction (Check 1)
- * and effect misdeclaration (Check 2), plus an unknown event when `events` is given.
- * Pure; the same checks `compileHook` enforces before emitting.
- */
-export declare function validateHook(spec: HookSpec, opts: ValidateHookOptions): HookIssue[];
-/** A settings `hooks` block keyed by the spec's event (the generated artifact). */
-export interface CompiledHook {
-    readonly hooks: Record<string, readonly {
-        readonly matcher: string;
-        readonly hooks: readonly {
-            readonly type: "command";
-            readonly command: string;
-        }[];
-    }[]>;
-    /** field → the extraction expression a generated hook would use (the typed read). */
-    readonly extractions: Record<string, string>;
-}
-export declare class HookCompileError extends Error {
-}
-/**
- * Compile a validated hook to its settings block. Refuses (throws) on any error-level
- * issue — "an unsafe hook doesn't compile" — so a wrong-field read or a mutating
- * observe-hook never ships. The `extractions` map shows the correctly-typed field
- * reads the generated hook uses (here as jq paths) — never a hand-typed `jq` string.
- */
-export declare function compileHook(spec: HookSpec, opts: ValidateHookOptions & {
-    gateCommand?: string;
-}): CompiledHook;
-/**
- * The typed source for a hook over a field map `M` (tool → field-union) and the
- * matched tool(s) `T`. `reads` is constrained to the fields of `T` — a field absent
- * from the matched tool is a tsc error. `M` stays unconstrained so a plain interface
- * (no index signature) works as the field map.
- */
-export interface TypedHookSpec<M, T extends keyof M & string> {
-    readonly event: string;
-    readonly match: readonly T[];
-    readonly reads: readonly Extract<M[T], string>[];
-    readonly effect: HookEffect;
-    readonly run?: string;
-}
-/** Build a typed hook; `reads` outside the matched tool's field-union won't compile. */
-export declare function hookFor<M, T extends keyof M & string>(spec: TypedHookSpec<M, T>): HookSpec;
-//# sourceMappingURL=hook-spec.d.ts.map

package/dist/core/hook-spec.js

@@ -1,130 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HookCompileError = exports.hook = void 0;
-exports.validateHook = validateHook;
-exports.compileHook = compileHook;
-exports.hookFor = hookFor;
-/**
- * SPIKE — typed, effect-classified HOOKS (the "type-safe bash" angle).
- *
- * A Claude Code / Codex hook today is hand-written shell in settings.json. Two
- * silent footguns dominate, and both are exactly what a COMPILER catches:
- *
- *  1. WRONG-FIELD EXTRACTION (silent no-op). A PreToolUse event's `tool_input`
- *     shape depends on the matched tool — `Bash` carries `command`, `Edit`/`Write`
- *     carry `file_path`. A hook that matches `Bash` but does
- *     `jq '.tool_input.file_path'` extracts EMPTY forever and never fires; nothing
- *     tells you. `validateHook` makes "read a field the matched tool never provides"
- *     an error, and the typed `hookFor` builder makes it a tsc error at edit time.
- *
- *  2. EFFECT MISDECLARATION ("type-safe bash"). A hook declared observe-only (a
- *     read-only gate/checker) that actually RUNS a mutating command — `eslint --fix`,
- *     `git push` — is a side effect masquerading as an observation. We already own a
- *     deterministic Bash-effect classifier (`bash-effects.ts`), so the command's
- *     effect class becomes a TYPE: an `effect: "observe"` hook whose `run` command
- *     classifies as side-effecting/undecidable does NOT compile. No other plugin
- *     tool has the classifier to make that judgment.
- *
- * Pure core, harness-agnostic: the per-tool field catalog is INJECTED (a Codex hook
- * has different fields), and the Bash classifier is the harness-neutral one. The CC
- * field catalog + the typed edit-time builder live in the test (no CC literal in core).
- *
- * NOT wired to the CLI/public API — a spike to see whether the compile step earns its
- * keep on the hook surface. See research/harness-protocol-flow-moat.md.
- */
-const bash_effects_js_1 = require("./bash-effects.js");
-/** Build a hook spec (the untyped on-ramp; see `hookFor` for the typed one). */
-const hook = (spec) => spec;
-exports.hook = hook;
-/** Which matched tools actually carry `field`. */
-function toolsProviding(field, match, toolFields) {
-    return match.filter((t) => (toolFields[t] ?? []).includes(field));
-}
-/** Check 1 — every read field exists on the matched tool(s). */
-function fieldIssues(spec, toolFields) {
-    const out = [];
-    for (const field of spec.reads) {
-        const providers = toolsProviding(field, spec.match, toolFields);
-        if (providers.length === 0) {
-            out.push({
-                severity: "error",
-                message: `reads "${field}" but no matched tool (${spec.match.join("|")}) provides it — the extraction is always empty (silent no-op)`,
-            });
-        }
-        else if (providers.length < spec.match.length) {
-            const missing = spec.match.filter((t) => !providers.includes(t));
-            out.push({
-                severity: "warning",
-                message: `reads "${field}", which ${missing.join("/")} does not carry — empty on those events`,
-            });
-        }
-    }
-    return out;
-}
-/** Check 2 — an observe-only hook's command must be provably read-only. */
-function effectIssues(spec) {
-    if (spec.effect !== "observe" || spec.run === undefined)
-        return [];
-    const cls = (0, bash_effects_js_1.classifyBashCommand)(spec.run);
-    if (cls === "read-only")
-        return [];
-    return [
-        {
-            severity: "error",
-            message: `declared observe-only but its command is ${cls}: "${spec.run}" — an observe hook must not mutate (use effect:"mutate" or a read-only command)`,
-        },
-    ];
-}
-/**
- * Validate a hook spec — the compiler half. Flags wrong-field extraction (Check 1)
- * and effect misdeclaration (Check 2), plus an unknown event when `events` is given.
- * Pure; the same checks `compileHook` enforces before emitting.
- */
-function validateHook(spec, opts) {
-    const out = [];
-    if (opts.events && !opts.events.includes(spec.event)) {
-        out.push({
-            severity: "error",
-            message: `unknown event "${spec.event}" — it will never fire`,
-        });
-    }
-    out.push(...fieldIssues(spec, opts.toolFields));
-    out.push(...effectIssues(spec));
-    return out;
-}
-class HookCompileError extends Error {
-}
-exports.HookCompileError = HookCompileError;
-/**
- * Compile a validated hook to its settings block. Refuses (throws) on any error-level
- * issue — "an unsafe hook doesn't compile" — so a wrong-field read or a mutating
- * observe-hook never ships. The `extractions` map shows the correctly-typed field
- * reads the generated hook uses (here as jq paths) — never a hand-typed `jq` string.
- */
-function compileHook(spec, opts) {
-    const issues = validateHook(spec, opts);
-    const errors = issues.filter((i) => i.severity === "error");
-    if (errors.length > 0) {
-        throw new HookCompileError(`hook does not compile:\n  ${errors.map((e) => e.message).join("\n  ")}`);
-    }
-    const command = opts.gateCommand ?? "npx vigiles hook-runtime guard";
-    const extractions = {};
-    for (const field of spec.reads)
-        extractions[field] = `.tool_input.${field}`;
-    return {
-        hooks: {
-            [spec.event]: [
-                {
-                    matcher: spec.match.join("|"),
-                    hooks: [{ type: "command", command }],
-                },
-            ],
-        },
-        extractions,
-    };
-}
-/** Build a typed hook; `reads` outside the matched tool's field-union won't compile. */
-function hookFor(spec) {
-    return spec;
-}
-//# sourceMappingURL=hook-spec.js.map