@jmtrin/opencode-kevin 0.2.0 → 0.4.0

package/README.md

@@ -6,6 +6,9 @@ Kevin is an [OpenCode](https://opencode.ai) plugin that **observes** every agent
 
 - **Local-first**: SQLite + FTS5, no external services, no network calls.
 - **Global memory**: a single `~/.opencode-kevin/kevin.db` shared across all your projects (WAL mode → safe for concurrent sessions). No per-project folders.
+- **Knowledge + Causality (v0.3.0)**: causal failure→fix chains, `kevin_why` explanations, OKF export/import, a supersede model, and human-in-the-loop AGENTS.md suggestions.
+- **Signal over Noise (v0.4.0)**: a quality gate that stores weak lessons without injecting them, an injection ledger with honest `precision_rate`, two-sided confidence, and a fixed compacting hook.
+- **Audited**: the v0.4.0 bug catalog (`docs/Kevin_v0.4.0_Bugs.md`) is fully closed — 16/16 bugs fixed and regression-tested (evidence in `kevin_query`/`kevin_get`, OKF round-trip fidelity, causal refresh guard, redaction precision, cross-session isolation).
 - **Standalone**: works without any other plugin. With the ecosystem, it learns more richly.
 
 ---
@@ -30,7 +33,7 @@ For a **single project**, put the same `plugin` array in `./opencode.json` or `.
 
 ### 2. Restart OpenCode
 
-Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes six tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`.
+Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes ten tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`, `kevin_config`.
 
 ### 3. Where data lives
 
@@ -89,32 +92,43 @@ Use `:memory:` for `dbPath` in tests.
          ▼
   ┌─────────────────┐
   │   OBSERVE        │  ToolCallObserver records every call
-  │  ToolCallObserver│  (tool, args redacted, success, duration, error_type)
-  │                  │  + stripPrivate blocks + opt-in dedup (v0.2.0)
+  │  ToolCallObserver│  (tool, args redacted, success, duration, error_type,
+  │                  │   id = callID) + stripPrivate + opt-in dedup (v0.2.0)
   └────────┬────────┘
-           │ on failure
-           ▼
-  ┌─────────────────┐
-  │   LEARN          │  Reflector generates a heuristic lesson
-  │   Reflector      │  per-error-code code table (v0.2.0 lesson v2),
-  │                  │  per-fingerprint throttle, origin='reflector',
-  │                  │  fingerprint=FNV-1a 64-bit
-  └────────┬────────┘
-           │
-           ▼
-  ┌─────────────────┐
-  │   SHARE          │  ContextInjector injects relevant lessons
-  │ ContextInjector  │  pre-prompt (1500 tokens) and on compacting (2000 tokens)
-  │                  │  + <protect> wrapper + id: line (v0.2.0)
+           │ on failure             │ on success
+           ▼                        ▼
+  ┌─────────────────┐   ┌─────────────────────────┐
+  │   LEARN          │   │  CAUSAL CHAIN (v0.3.0)  │
+  │   Reflector      │   │  CausalChain.onSuccess   │
+  │  heuristic lesson │   │  links the fix to the   │
+  │  per-error-code  │   │  failure within 10 tool │
+  │  rule table      │   │  calls (error_fingerprint)
+  │  (v0.2.0 v2),    │   └───────────┬─────────────┘
+  │  per-fingerprint │               │
+  │  throttle BEFORE │               │ session.idle
+  │  LLM enrich      │               ▼
+  │  (opt-in v0.3.0),│   ┌─────────────────────────┐
+  │  stamps          │   │  CausalChain.onSessionIdle│
+  │  error_fingerprint│  │  promotes recurring errors│
+  └────────┬────────┘   │  → causal patterns (idempotent,
+           │             │   cumulative evidence)     │
+           ▼             └───────────┬───────────────┘
+  ┌─────────────────┐               │
+  │   SHARE          │◄──────────────┘
+  │ ContextInjector  │  injects relevant lessons pre-prompt
+  │                  │  (1500 tokens) + on compacting (2000)
+  │                  │  + <protect> + id: line (v0.2.0)
   │                  │  + origin-aware rank (v0.2.0)
-  │                  │  + conditional budget (v0.2.0)
+  │                  │  + <kevin-suggestion> after negative
+  │                  │    feedback half (HITL, v0.3.0)
   └────────┬────────┘
            │ session.idle
            ▼
   ┌─────────────────┐
-  │  RETROSPECTIVE   │  Retrospective generates ~/.opencode-kevin/retrospectives/<session>.md
-  │                  │  with origin labels, false-positive recap, metrics snapshot (v0.2.0)
+  │  RETROSPECTIVE   │  generates ~/.opencode-kevin/retrospectives/<session>.md
+  │                  │  with origin labels, FP recap, metrics snapshot (v0.2.0)
   │                  │  + boostPositiveReflectors (v0.2.0)
+  │                  │  + penalizeRecurringReflectors (v0.3.0)
   │                  │  + PatternMiner.mine (opt-in, v0.2.0)
   └─────────────────┘
 ```
@@ -123,7 +137,7 @@ Use `:memory:` for `dbPath` in tests.
 
 ## Tools
 
-Kevin exposes 6 tools callable by the agent:
+Kevin exposes 10 tools callable by the agent:
 
 ### `kevin_save`
 
@@ -134,11 +148,13 @@ kevin_save({ type: "decision", content: "We use vitest for tests", scope: "proje
 // → { "id": "0195a3b2-..." }
 ```
 
-`type`: `error` | `pattern` | `decision` | `context`. `scope`: `project` (persists) | `session` (TTL 24h).
+`type`: `error` | `pattern` | `decision` | `context` | `rule` | `solution` (v0.3.0). `scope`: `project` (persists) | `session` (TTL 24h).
+
+Saving a `decision` or `rule` with the same `fingerprint` as an existing active row supersedes the old one (v0.3.0 — `status='superseded'`, hidden from default queries).
 
 ### `kevin_query`
 
-Searches memories by text (FTS5 + bm25). Returns a **slim** payload by default (v0.2.0). Pass `full: true` for the v0.1.x full content body.
+Searches memories by text (FTS5 + bm25). Returns a **slim** payload by default (v0.2.0). Pass `full: true` for the v0.1.x full content body, or `evidence: true` (v0.3.0) to include `confidence`, `evidence_count`, `last_verified_at` in the slim payload.
 
 ```
 kevin_query({ query: "typecheck", type: "error", limit: 5 })
@@ -156,12 +172,14 @@ Fetches a **single full memory** by id (v0.2.0 — progressive disclosure). Use
 kevin_get({ id: "0195a3b2-..." })
 // → { "id": "...", "type": "error", "content": "...", "scope": "project",
 //      "relevanceScore": 0.55, "origin": "reflector", "fingerprint": "cbf29ce484222325",
-//      "projectId": null, "metadata": null }
+//      "projectId": null, "metadata": null,
+//      "evidenceCount": 2, "recurrenceCount": 1, "lastVerifiedAt": "2026-08-01 10:00:00",
+//      "status": "active", "confidence": 0.55, "fixArgs": "npm i -g rg" }
 ```
 
 ### `kevin_recall`
 
-Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope.
+Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope. Pass `includeSuperseded: true` to include superseded rows (v0.3.0).
 
 ```
 kevin_recall({ query: "auth", limit: 3 })
@@ -170,15 +188,19 @@ kevin_recall({ query: "auth", limit: 3 })
 
 ### `kevin_status`
 
-Global counts and metrics (v0.2.0 adds `memories_reflector`, `memories_agent`, `memories_pattern`, and a `metrics` object with 6 seeded counters).
+Global counts and metrics. v0.2.0 adds `memories_reflector`, `memories_agent`, `memories_pattern` and a `metrics` object; v0.3.0 adds `memories_causal` and 3 more seeded counters (`patterns_causal`, `causal_links`, `memories_superseded`); v0.4.0 adds the precision block: `injections_total`, `injections_effective`, `injections_ineffective`, `precision_rate`, `patterns_promoted_new`, and per-origin `recurrence_by_origin`.
 
 ```
 kevin_status({})
 // → { "memories": 42, "memories_reflector": 12, "memories_agent": 30, "memories_pattern": 0,
-//      "tool_calls": 318, "retrospectives": 7,
+//      "memories_causal": 1, "tool_calls": 318, "retrospectives": 7,
 //      "metrics": { "tokens_injected_pre_prompt": 51, "tokens_injected_compacting": 0,
 //                   "reflections_throttled": 3, "duplicate_suppressions": 2,
-//                   "tool_calls_deduped": 0, "patterns_mined": 0 } }
+//                   "tool_calls_deduped": 0, "patterns_mined": 0,
+//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0 },
+//      "injections_total": 14, "injections_effective": 11, "injections_ineffective": 3,
+//      "precision_rate": 0.79, "patterns_promoted_new": 2,
+//      "recurrence_by_origin": { "reflector": 3, "causal": 1 } }
 ```
 
 ### `kevin_retrospective`
@@ -191,6 +213,46 @@ kevin_retrospective({ session_id: "sess-abc" })
 // or → { "message": "No failures in session sess-abc." }
 ```
 
+### `kevin_why` (v0.3.0)
+
+Explains *why* a failure keeps happening: looks up causal patterns for the query and builds a failure → fix trace from memories + tool_calls, including related TypeScript error-code rules.
+
+```
+kevin_why({ query: "TS2304 cannot find name" })
+// → { "summary": "TS2304 recurs because ... Confirmed by 2 fixes.",
+//      "confidence": 0.7, "evidence_count": 2, "last_verified": "2026-08-01 10:00:00",
+//      "trace": [ { "type": "error", "summary": "..." }, { "type": "fix", "tool": "bash" } ],
+//      "related_rules": [ { "code": "TS2304", "suggestion": "import or typo" } ] }
+```
+
+### `kevin_export` (v0.3.0)
+
+Exports knowledge for sharing: `decision`/`rule`/`pattern` memories (active only, no raw errors) as YAML-frontmatter blocks (`format: "okf"`) or markdown (`format: "markdown"`). Includes `id`, `type`, `confidence` (two-sided v0.4.0 formula), `evidence_count`, `recurrence_count`, `last_verified_at`, `fingerprint`. Timestamps are treated as UTC — a re-import reproduces the exact source values.
+
+### `kevin_import` (v0.3.0)
+
+Ingests an exported bundle. Each entry becomes a `context` memory with `origin='imported'`; a fingerprint collision with an existing `decision`/`rule` supersedes the old row. Returns `{ imported, superseded }`.
+
+### `kevin_config` (v0.4.0)
+
+Reads/writes `kevin_settings` without SQL. `action: "list"` returns every setting; `action: "set"` upserts a value (default `"1"` when omitted) and rejects unknown keys unless `strict: false`.
+
+```
+kevin_config({ action: "list" })
+// → { "quality_gate_enabled": "1", "lesson_snippet_injection": "1", "llm_reflection_enabled": "0", ... }
+
+kevin_config({ action: "set", key: "quality_gate_enabled", value: "0" })
+// → { "ok": true }
+```
+
+Known keys: `quality_gate_enabled`, `lesson_snippet_injection`, `llm_reflection_enabled`, `cross_project_enabled`, `patternminer_enabled`, `tool_calls_dedup_enabled` (v0.4.0).
+
+---
+
+## Precision (v0.4.0)
+
+Weak lessons — errors the reflector cannot dispatch to a deterministic rule — are **stored but never injected** while `quality_gate_enabled = '1'` (default). Injection now goes through a ledger: every pre-prompt/compacting injection is recorded and settled as effective or ineffective at session idle, so `kevin_status` reports the honest picture (`injections_total`, `injections_effective/ineffective`, `precision_rate`, `patterns_promoted_new`) instead of raw "lessons shared" counts. Recurrences demote lessons (`recurrence_count` → `stale`) and lower confidence. Debug mode: `kevin_config({ action: "set", key: "quality_gate_enabled", value: "0" })` re-injects weak lessons with a `(low confidence)` marker.
+
 ---
 
 ## Hooks
@@ -200,11 +262,11 @@ Kevin subscribes to 6 OpenCode hooks:
 | Hook | What Kevin does |
 |---|---|
 | `tool.execute.before` | Records tool call start (callID + redacted args) |
-| `tool.execute.after` | Records result; on failure → Reflector.invoke async (throttled) |
-| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (1500 tokens) |
-| `experimental.session.compacting` | Re-injects lessons in `<kevin-memory>` after compacting (2000 tokens) |
+| `tool.execute.after` | Records result (id = callID); on failure → Reflector.invoke async (throttled); on success → CausalChain.onSuccess links the fix (v0.3.0) |
+| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (1500 tokens) + optional `<kevin-suggestion>` (v0.3.0) |
+| `experimental.session.compacting` | Re-injects lessons in `<kevin-memory>` after compacting (2000 tokens) + optional `<kevin-suggestion>` |
 | `event` (`session.created`) | Captures current `sessionID` |
-| `event` (`session.idle`) | Generates retrospective.md for the session |
+| `event` (`session.idle`) | Generates retrospective.md; boosts positive lessons (v0.2.0); penalizes recurring failures (v0.3.0); promotes causal patterns + mines patterns (opt-in); flushes metrics |
 
 **Redaction**: absolute paths (`C:\Users\...`, `/home/...`) → `<path>` and secrets (`API_KEY=`, `Bearer`, `token`) → `<redacted>` before persisting anything. v0.2.0 adds `<private>…</private>` block redaction: sweeps tool call args and output before persistence, replaces with `<private: redacted N chars>`.
 
@@ -260,14 +322,23 @@ plugin/
   index.ts              # Entry point: KevinPlugin
   Store.ts              # Wrapper SQLite (node:sqlite / bun:sqlite / better-sqlite3 fallback)
   Migrate.ts            # Idempotent migrations + post-apply hooks
-  MemoryService.ts      # save/query/getRelevant (FTS5 + bm25 + origin-aware rank)
+  MemoryService.ts      # save/query/getRelevant (FTS5 + bm25 + origin-aware rank + supersede)
   ToolCallObserver.ts   # onBefore/onAfter + redact + inferErrorType + dedup (opt-in)
-  Reflector.ts          # Heuristic lessons + per-fingerprint throttle + lesson v2
-  ContextInjector.ts    # deriveQuery + pre-prompt/compacting injection + conditional budget
+  Reflector.ts          # Heuristic lessons + per-fingerprint throttle + lesson v2 + LLM enrich
+  CausalChain.ts        # v0.3.0 — links fixes to failures + promotes causal patterns
+  ContextInjector.ts    # deriveQuery + pre-prompt/compacting injection + <kevin-suggestion>
+  QualityGate.ts        # v0.4.0 — weak-lesson gate (stored, not injected by default)
+  InjectionLedger.ts    # v0.4.0 — injection ledger + settle → precision_rate
   Retrospective.ts      # Generates retrospective.md + FP recap + metrics snapshot
+  LessonFixer.ts        # v0.4.0 — deterministic fix_args capture + promotion enrichment
+  confidence.ts         # v0.4.0 — two-sided computeConfidence (evidence + recurrence)
   fingerprint.ts        # FNV-1a 64-bit (in-house, no node:crypto)
   metrics.ts            # In-memory counters + debounced flush to kevin_metrics
   PatternMiner.ts       # Opt-in deterministic 2-gram/3-gram miner
+  kevin_why.ts          # v0.3.0 — kevin_why tool: failure→fix traces + related rules
+  okf-export.ts         # v0.3.0 — kevin_export: OKF/markdown export
+  okf-import.ts         # v0.3.0 — kevin_import: bundle parser + import
+  query-tokenizer.ts    # v0.4.0 — FTS5 tokenizer for query sanitization
   memory-format.ts      # escapeInjectedText, formatMemories, <protect> + id: line wrappers
   redact.ts             # redactPaths + stripPrivate
   uuid.ts               # UUIDv7
@@ -275,6 +346,8 @@ migrations/
   001_initial.sql       # schema: memories, tool_calls, retrospectives
   002_indexes.sql       # FTS5 + indexes
   003_v02_signal.sql    # v0.2.0 Signal Quality: fingerprint, origin, metrics, dedup indexes
+  004_v03_knowledge.sql # v0.3.0 Knowledge + Causality: evidence/status/supersede, error_fingerprint
+  005_v04_signal.sql    # v0.4.0 Signal over Noise: recurrence_count, fix_args, last_injected_at
 tests/{unit,integration,e2e}/
 scripts/
   copy-migrations.mjs   # build step: copies *.sql to dist/migrations

package/dist/migrations/004_v03_knowledge.sql

@@ -0,0 +1,138 @@
+-- ============================================================
+-- Kevin 0.3.0 — Migration 004: Knowledge + Causality (additive)
+-- ============================================================
+-- Backward-compatible, additive only. All new columns are
+-- nullable or carry a NOT NULL DEFAULT so legacy rows keep
+-- working without a destructive rebuild.
+-- ============================================================
+
+-- 1. memories: evidence + lifecycle columns.
+--    evidence_count — how many times this fingerprint was confirmed as fixed.
+--    last_verified_at — timestamp of the most recent causal confirmation.
+--    status — lifecycle state; default 'active'. Superseded rows are hidden.
+ALTER TABLE memories ADD COLUMN evidence_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN last_verified_at TEXT;
+ALTER TABLE memories ADD COLUMN status TEXT NOT NULL DEFAULT 'active'
+  CHECK (status IN ('active', 'superseded', 'stale', 'archived'));
+
+-- 2. tool_calls: causal link + feedback-loop link columns.
+--    fix_for_fingerprint — set when this successful call resolved a prior failure
+--    with the given fingerprint. NULL for tool calls that were not fixes.
+--    error_fingerprint — set by Reflector (via onLinkError callback) when a call
+--    FAILS, to the stderr-based fingerprint the matching error memory uses.
+--    This fixes the v0.2.0/v0.3.0 feedback-loop fingerprint mismatch bug:
+--    tool_calls.fingerprint is hashed from "tool|args|success" by ToolCallObserver,
+--    while memories.fingerprint is hashed from stderr text by Reflector — they
+--    never agreed, so boost/penalize queries silently mismatched. The new column
+--    stores the SAME identity dimension the error memory uses.
+ALTER TABLE tool_calls ADD COLUMN fix_for_fingerprint TEXT;
+ALTER TABLE tool_calls ADD COLUMN error_fingerprint TEXT;
+
+-- 3. Index: causal linkage by fingerprint. Used by CausalChain.onSuccess
+--    and kevin_why to materialize traces.
+CREATE INDEX IF NOT EXISTS idx_tool_calls_fix_fp
+  ON tool_calls(fix_for_fingerprint)
+  WHERE fix_for_fingerprint IS NOT NULL;
+
+-- 3b. Index: feedback-loop linkage by error_fingerprint. Used by
+--     boostPositiveReflectors / penalizeRecurringReflectors to count
+--     recurrences by the same identity dimension the error memory uses.
+CREATE INDEX IF NOT EXISTS idx_tool_calls_error_fp
+  ON tool_calls(error_fingerprint)
+  WHERE error_fingerprint IS NOT NULL;
+
+-- 4. Index: memories by fingerprint for promotion + supersede queries.
+CREATE INDEX IF NOT EXISTS idx_memories_fp
+  ON memories(fingerprint)
+  WHERE fingerprint IS NOT NULL;
+
+-- 5. kevin_metrics: seed new v0.3 counters.
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('patterns_causal',     0),
+  ('causal_links',        0),
+  ('memories_superseded', 0);
+
+-- 6. kevin_settings: seed new opt-in flags.
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('llm_reflection_enabled', '0'),
+  ('cross_project_enabled',  '0');
+
+-- 7. Seed version 004.
+INSERT OR IGNORE INTO schema_version (version) VALUES ('004');
+
+-- ============================================================
+-- 8. Rebuild memories table with expanded CHECK constraints.
+--    v0.3.0 introduces new types (rule, solution) and origins
+--    (causal, imported). SQLite cannot ALTER a CHECK constraint,
+--    so we rebuild via a temporary table. FTS5 external-content
+--    table references the content table by name, so we drop+recreate
+--    the FTS5 triggers after the rebuild.
+-- ============================================================
+
+-- Step 1: Create new table with correct constraints
+CREATE TABLE memories_v04 (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('error','pattern','decision','context','rule','solution')),
+  content TEXT NOT NULL,
+  scope TEXT NOT NULL DEFAULT 'project' CHECK(scope IN ('project','session')),
+  relevance_score REAL DEFAULT 0.5,
+  source_tool TEXT,
+  source_session TEXT,
+  metadata TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT,
+  project_id TEXT,
+  fingerprint TEXT,
+  origin TEXT NOT NULL DEFAULT 'agent'
+    CHECK(origin IN ('reflector','agent','pattern','retrospective','causal','imported')),
+  evidence_count INTEGER NOT NULL DEFAULT 0,
+  last_verified_at TEXT,
+  status TEXT NOT NULL DEFAULT 'active'
+    CHECK(status IN ('active','superseded','stale','archived'))
+);
+
+-- Step 2: Copy data preserving rowids (FTS5 content sync relies on rowid)
+INSERT INTO memories_v04
+  (rowid, id, type, content, scope, relevance_score, source_tool,
+   source_session, metadata, created_at, updated_at, expires_at,
+   project_id, fingerprint, origin, evidence_count, last_verified_at, status)
+  SELECT rowid, id, type, content, scope, relevance_score, source_tool,
+         source_session, metadata, created_at, updated_at, expires_at,
+         project_id, fingerprint, origin, evidence_count, last_verified_at, status
+  FROM memories;
+
+-- Step 3: Drop old table and FTS triggers
+DROP TRIGGER IF EXISTS memories_ai;
+DROP TRIGGER IF EXISTS memories_ad;
+DROP TRIGGER IF EXISTS memories_au;
+DROP TABLE memories;
+
+-- Step 4: Rename new table
+ALTER TABLE memories_v04 RENAME TO memories;
+
+-- Step 5: Recreate FTS triggers (memories_fts is content=external, survives DROP of content table)
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+-- Step 6: Recreate indexes
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope);
+CREATE INDEX IF NOT EXISTS idx_memories_relevance ON memories(relevance_score DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_memories_error_fp
+  ON memories(project_id, fingerprint)
+  WHERE type = 'error' AND fingerprint IS NOT NULL AND origin = 'reflector';
+CREATE INDEX IF NOT EXISTS idx_memories_fp
+  ON memories(fingerprint)
+  WHERE fingerprint IS NOT NULL;

package/dist/migrations/005_v04_signal.sql

@@ -0,0 +1,57 @@
+-- ============================================================
+-- Kevin 0.4.0 — Migration 005: Signal over Noise (additive)
+-- ============================================================
+-- Backward-compatible, additive only. All new columns are
+-- nullable or carry a NOT NULL DEFAULT so legacy rows keep
+-- working without a destructive rebuild.
+-- ============================================================
+
+-- 1. memories: positive/negative evidence split (D4-03).
+--    recurrence_count — how many times this fingerprint recurred AFTER
+--                       injection (negative evidence; lowers confidence).
+--    fix_args — deterministic capture of the linked success call's
+--               args_summary ("Fixed by:" raw material, D4-07).
+--    last_injected_at — timestamp of the most recent injection of this memory.
+ALTER TABLE memories ADD COLUMN recurrence_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN fix_args TEXT;
+ALTER TABLE memories ADD COLUMN last_injected_at TEXT;
+
+-- 2. kevin_injections: the injection ledger (D4-04). One row per injected
+--    memory per prompt/compaction, settled at session.idle.
+CREATE TABLE IF NOT EXISTS kevin_injections (
+  id          TEXT PRIMARY KEY,
+  memory_id   TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  hook        TEXT NOT NULL CHECK (hook IN ('pre_prompt', 'compacting')),
+  tokens      INTEGER NOT NULL,
+  injected_at TEXT NOT NULL DEFAULT (datetime('now')),
+  outcome     TEXT CHECK (outcome IN ('unmeasured', 'effective', 'ineffective'))
+              NOT NULL DEFAULT 'unmeasured'
+);
+
+-- 2b. Indexes: settlement by session, recurrence lookups by fingerprint,
+--     and outcome rollups for precision_rate.
+CREATE INDEX IF NOT EXISTS idx_injections_fp
+  ON kevin_injections(fingerprint);
+CREATE INDEX IF NOT EXISTS idx_injections_session
+  ON kevin_injections(session_id);
+CREATE INDEX IF NOT EXISTS idx_injections_outcome
+  ON kevin_injections(outcome);
+
+-- 3. kevin_metrics: seed new v0.4 counters.
+--    patterns_promoted_new replaces patterns_causal (which was inflated by
+--    idempotent refreshes); the latter stays for compat but is frozen.
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('injections_total',        0),
+  ('injections_effective',    0),
+  ('injections_ineffective',  0),
+  ('patterns_promoted_new',   0);
+
+-- 4. kevin_settings: seed new v0.4 flags.
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('quality_gate_enabled',    '1'),
+  ('lesson_snippet_injection','1');
+
+-- 5. Seed version 005.
+INSERT OR IGNORE INTO schema_version (version) VALUES ('005');

package/dist/plugin/CausalChain.d.ts

@@ -0,0 +1,22 @@
+import { type EnrichFn } from "./LessonFixer.js";
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+export declare class CausalChain {
+    private store;
+    private memoryService;
+    private metrics;
+    private enrichFn?;
+    constructor(store: Store, memoryService: MemoryService, metrics: Metrics | null, enrichFn?: EnrichFn | undefined);
+    onSuccess(_tool: string, _args: Record<string, unknown>, _projectId: string | null, sessionId: string): void;
+    onSessionIdle(sessionId: string): Promise<number>;
+    /**
+     * v0.4.0 (K4-015) — fire the opt-in enrich hook at most once per
+     * promoted pattern. The hook's one-line phrase replaces the
+     * deterministic `Fixed by:` line; null keeps it. A call (phrase or
+     * not) stamps `metadata.enriched` so repeated idle cycles stay at
+     * one LLM call per pattern.
+     */
+    private enrichIfEnabled;
+    private isLlmReflectionEnabled;
+}

package/dist/plugin/CausalChain.js

@@ -0,0 +1,179 @@
+import { extractFixArgs, } from "./LessonFixer.js";
+/** K3-007 — a success only links to a failure within this many calls. */
+const MAX_LINK_DISTANCE = 10;
+export class CausalChain {
+    store;
+    memoryService;
+    metrics;
+    enrichFn;
+    constructor(store, memoryService, metrics, 
+    // v0.4.0 (K4-015) — opt-in promotion-time LLM phrasing. Absent in
+    // production (zero network calls by default); injected by tests or
+    // by a future settings-driven wiring.
+    enrichFn) {
+        this.store = store;
+        this.memoryService = memoryService;
+        this.metrics = metrics;
+        this.enrichFn = enrichFn;
+    }
+    // K3-007: link a success to the failing fingerprint only when it
+    // occurred within MAX_LINK_DISTANCE tool calls of the failure (plan
+    // §K3-007 acceptance: "within 24h and within 10 tool calls").
+    // v0.3.0 fix (bug #3) — the old code linked the most recent session
+    // success to the most recent unlinked error memory regardless of
+    // distance, so an unrelated success (e.g. an `ls` run after a
+    // typecheck failure) was stamped as the fix for that error.
+    onSuccess(_tool, _args, _projectId, sessionId) {
+        const successRow = this.store
+            .prepare(`SELECT rowid, tool, args_summary FROM tool_calls
+				 WHERE session_id = ? AND success = 1
+				 ORDER BY rowid DESC LIMIT 1`)
+            .get(sessionId);
+        if (!successRow)
+            return;
+        const linkedFps = new Set(this.store
+            .prepare(`SELECT DISTINCT fix_for_fingerprint FROM tool_calls
+						 WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL`)
+            .all(sessionId).map((r) => r.fix_for_fingerprint));
+        // Most recent failing calls in this session, newest first. The
+        // failing call's `error_fingerprint` (stamped by Reflector via
+        // onLinkError) is the SAME identity dimension the error memory
+        // uses; `fingerprint` is the legacy tool|args|success hash and
+        // simply never matches a reflector error memory.
+        const failRows = this.store
+            .prepare(`SELECT rowid, COALESCE(error_fingerprint, fingerprint) AS fp
+				 FROM tool_calls
+				 WHERE session_id = ?
+				   AND success = 0
+				   AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)
+				 ORDER BY rowid DESC LIMIT ?`)
+            .all(sessionId, MAX_LINK_DISTANCE);
+        for (const fail of failRows) {
+            if (!fail.fp || linkedFps.has(fail.fp))
+                continue;
+            const dist = successRow.rowid - fail.rowid;
+            if (dist <= 0 || dist > MAX_LINK_DISTANCE)
+                continue;
+            const mem = this.store
+                .prepare(`SELECT 1 FROM memories
+					 WHERE fingerprint = ? AND type = 'error'
+					   AND origin = 'reflector' AND status IN ('active', 'stale')
+					   AND created_at > datetime('now', '-24 hours')
+					 LIMIT 1`)
+                .get(fail.fp);
+            if (!mem)
+                continue;
+            this.store
+                .prepare("UPDATE tool_calls SET fix_for_fingerprint = ? WHERE rowid = ?")
+                .run(fail.fp, successRow.rowid);
+            // v0.4.0 (K4-014) — deterministic "Fixed by:" raw material
+            // (plan §5.4 / D4-07): copy the linked success call's
+            // args_summary into memories.fix_args for every active row of
+            // that fingerprint (error + pattern), zero LLM cost.
+            const fixArgs = extractFixArgs({
+                tool: successRow.tool,
+                args_summary: successRow.args_summary ?? null,
+            });
+            if (fixArgs) {
+                this.store
+                    .prepare(`UPDATE memories SET fix_args = ?
+						 WHERE fingerprint = ? AND status IN ('active', 'stale')`)
+                    .run(fixArgs, fail.fp);
+            }
+            this.metrics?.incr("causal_links", 1);
+            return;
+        }
+    }
+    async onSessionIdle(sessionId) {
+        const linkedErrors = this.store
+            .prepare(`SELECT m.id, m.fingerprint, m.recurrence_count,
+				        (SELECT COUNT(*)
+				         FROM tool_calls tc_all
+				         WHERE tc_all.fix_for_fingerprint = m.fingerprint) as evidence_count
+				 FROM memories m
+				 WHERE m.type = 'error'
+				   AND m.origin = 'reflector'
+				   AND m.fingerprint IN (
+				       SELECT DISTINCT fix_for_fingerprint
+				       FROM tool_calls
+				       WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL
+				   )
+				   AND m.status IN ('active', 'stale')
+				 GROUP BY m.fingerprint
+				 HAVING (
+				     SELECT MAX(tc.ts) FROM tool_calls tc
+				     WHERE tc.fix_for_fingerprint = m.fingerprint
+				 ) >= COALESCE(
+				     (SELECT MAX(m2.updated_at) FROM memories m2
+				      WHERE m2.fingerprint = m.fingerprint
+				        AND m2.type = 'pattern'
+				        AND m2.origin = 'causal'),
+				     '1970-01-01'
+				 )`)
+            .all(sessionId);
+        let promoted = 0;
+        for (const err of linkedErrors) {
+            try {
+                const result = this.memoryService.promoteToPattern(err.id, err.evidence_count, err.recurrence_count ?? 0);
+                if (result) {
+                    promoted++;
+                    // v0.4.0 (K4-009) — only a NEW pattern row counts as a
+                    // promotion; the idempotent refresh path no longer
+                    // inflates the metric. `patterns_causal` is deprecated
+                    // (key kept for compat, never incremented).
+                    if (result.created) {
+                        this.metrics?.incr("patterns_promoted_new", 1);
+                        // v0.4.0 (K4-015) — promotion-time LLM enrichment:
+                        // at most one call per NEW pattern, gated on
+                        // `kevin_settings.llm_reflection_enabled` and the
+                        // per-pattern `metadata.enriched` marker. Never on
+                        // the failure hot path.
+                        await this.enrichIfEnabled(err.id, result.id);
+                    }
+                }
+            }
+            catch {
+                // promoteToPattern may fail if the error memory was removed
+            }
+        }
+        return promoted;
+    }
+    /**
+     * v0.4.0 (K4-015) — fire the opt-in enrich hook at most once per
+     * promoted pattern. The hook's one-line phrase replaces the
+     * deterministic `Fixed by:` line; null keeps it. A call (phrase or
+     * not) stamps `metadata.enriched` so repeated idle cycles stay at
+     * one LLM call per pattern.
+     */
+    async enrichIfEnabled(errorId, patternId) {
+        if (!this.enrichFn || !this.isLlmReflectionEnabled())
+            return;
+        const pattern = this.memoryService.getById(patternId);
+        if (!pattern)
+            return;
+        const meta = (pattern.metadata ?? {});
+        if (meta.enriched === true)
+            return;
+        const phrase = await this.enrichFn({
+            lesson: pattern.content,
+            fixArgs: pattern.fixArgs ?? null,
+            originalError: this.memoryService.getById(errorId)?.content ?? null,
+        });
+        const content = phrase
+            ? pattern.content.includes("\nFixed by: ")
+                ? pattern.content.replace(/\nFixed by: .+$/s, `\n${phrase}`)
+                : `${pattern.content}\n${phrase}`
+            : pattern.content;
+        this.memoryService.update(patternId, {
+            content,
+            metadata: { ...meta, enriched: true },
+        });
+    }
+    isLlmReflectionEnabled() {
+        const row = this.store
+            .prepare("SELECT value FROM kevin_settings WHERE key = ?")
+            .get("llm_reflection_enabled");
+        return row?.value === "1";
+    }
+}
+//# sourceMappingURL=CausalChain.js.map

package/dist/plugin/CausalChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"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"}