@jmtrin/opencode-kevin 0.3.0 → 0.5.0

package/README.md

@@ -7,6 +7,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.
+- **Glass Box (v0.5.0)**: honest measurement replaces estimates — three-way injection settlement (`effective` / `ineffective` / `inconclusive`), human feedback that actually moves confidence, a strict dry-run `kevin_trace`, a read-only `kevin_audit`, memory lifecycle completion (`superseded_by`, `ignored`, `archived`), and a hermetic replay harness. See [How Kevin measures itself](#how-kevin-measures-itself).
+- **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.
 
 ---
@@ -31,7 +34,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 nine tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`.
+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 thirteen tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`, `kevin_config`, `kevin_feedback`, `kevin_trace`, `kevin_audit` (v0.5.0 adds the last three).
 
 ### 3. Where data lives
 
@@ -114,7 +117,7 @@ Use `:memory:` for `dbPath` in tests.
   ┌─────────────────┐               │
   │   SHARE          │◄──────────────┘
   │ ContextInjector  │  injects relevant lessons pre-prompt
-  │                  │  (1500 tokens) + on compacting (2000)
+  │                  │  (900 tokens, configurable via pre_prompt_budget_tokens) + on compacting (2000)
   │                  │  + <protect> + id: line (v0.2.0)
   │                  │  + origin-aware rank (v0.2.0)
   │                  │  + <kevin-suggestion> after negative
@@ -135,7 +138,7 @@ Use `:memory:` for `dbPath` in tests.
 
 ## Tools
 
-Kevin exposes 9 tools callable by the agent:
+Kevin exposes 13 tools callable by the agent:
 
 ### `kevin_save`
 
@@ -171,7 +174,8 @@ kevin_get({ id: "0195a3b2-..." })
 // → { "id": "...", "type": "error", "content": "...", "scope": "project",
 //      "relevanceScore": 0.55, "origin": "reflector", "fingerprint": "cbf29ce484222325",
 //      "projectId": null, "metadata": null,
-//      "evidenceCount": 0, "lastVerifiedAt": null, "status": "active" }
+//      "evidenceCount": 2, "recurrenceCount": 1, "lastVerifiedAt": "2026-08-01 10:00:00",
+//      "status": "active", "confidence": 0.55, "fixArgs": "npm i -g rg" }
 ```
 
 ### `kevin_recall`
@@ -185,7 +189,7 @@ 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; v0.3.0 adds `memories_causal` and 3 more seeded counters (`patterns_causal`, `causal_links`, `memories_superseded`).
+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`. v0.5.0 adds `injections_inconclusive`, `coverage_rate`, `blocked`, `memories_ignored`, `memories_archived` and `feedback { positive, negative }`.
 
 ```
 kevin_status({})
@@ -194,7 +198,14 @@ kevin_status({})
 //      "metrics": { "tokens_injected_pre_prompt": 51, "tokens_injected_compacting": 0,
 //                   "reflections_throttled": 3, "duplicate_suppressions": 2,
 //                   "tool_calls_deduped": 0, "patterns_mined": 0,
-//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0 } }
+//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0,
+//                   "injections_inconclusive": 9, "injections_blocked_seen": 1, ... },
+//      "injections_total": 14, "injections_effective": 2, "injections_ineffective": 3,
+//      "injections_inconclusive": 9, "precision_rate": 0.40, "coverage_rate": 0.36,
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0, "ignored": 1 },
+//      "memories_ignored": 1, "memories_archived": 4,
+//      "feedback": { "positive": 2, "negative": 1 },
+//      "patterns_promoted_new": 2, "recurrence_by_origin": { "reflector": 3, "causal": 1 } }
 ```
 
 ### `kevin_retrospective`
@@ -221,12 +232,90 @@ kevin_why({ query: "TS2304 cannot find name" })
 
 ### `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`, `evidence_count`, `last_verified_at`, `fingerprint`.
+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), `deterministic_retrieval`, `pre_prompt_budget_tokens`, `archive_after_days` (v0.5.0).
+
+### `kevin_feedback` (v0.5.0)
+
+Rates an injected memory and makes the rating count. `verdict` is `useful` | `wrong` | `outdated` | `ignore`. The first three are stored in `memory_feedback` and move `kevin_why`'s confidence (`+0.05` / `-0.1` per count); **`ignore` is a hard action** — the memory is stamped `ignored = 1` and excluded from retrieval, queries and injection.
+
+```
+kevin_feedback({ memory_id: "0195a3b2-...", verdict: "wrong", note: "the fix was wrong" })
+// → { "ok": true, "verdict": "wrong" }
+```
+
+### `kevin_trace` (v0.5.0)
+
+Strict dry-run: predicts exactly which memories `onSystemTransform` WOULD inject for a query (optionally `session_id`, `tag` and `cap`), with **zero side effects** — no counters, no ledger rows, no seen-set writes, no relevance bumps. Rejected items carry their `GateReason` (`seen_this_session` | `weak` | `recurrence` | `stale` | `ignored`).
+
+```
+kevin_trace({ query: "tsc error" })
+// → { "query": "tsc error", "tag": "context", "cap": 900, "would_inject": true,
+//      "total_tokens": 82,
+//      "admitted": [ { "id": "...", "type": "error", "decision": "admitted", "tokens": 62 } ],
+//      "blocked": [ { "id": "...", "type": "error", "decision": "blocked", "reason": "seen_this_session", "tokens": 20 } ] }
+```
+
+### `kevin_audit` (v0.5.0)
+
+Read-only report of the whole system state: memories by `status`/`origin`/`type`, injection outcomes with `precision_rate`/`coverage_rate`, the five `blocked` counters, feedback by verdict, tokens injected. `verbose: true` adds the settings block. No writes, no LLM; on a pre-006 database it returns what it can with `"partial": true`.
+
+```
+kevin_audit({})
+// → { "memories": { "total": 42, "by_status": { "active": 37, "stale": 1, "archived": 4 },
+//                   "by_origin": { "reflector": 12, "agent": 30 }, "by_type": { "error": 20, ... },
+//                   "ignored": 1, "archived": 4, "with_feedback": 3, "superseded_with_target": 2 },
+//      "injections": { "total": 14, "effective": 2, "ineffective": 3, "inconclusive": 9,
+//                      "unmeasured": 0, "precision_rate": 0.40, "coverage_rate": 0.36 },
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0, "ignored": 1 },
+//      "feedback": { "positive": 2, "negative": 1, "by_verdict": { "useful": 2, "wrong": 1 } },
+//      "tokens": { "pre_prompt": 51, "compacting": 0 }, "partial": false }
+```
+
+---
+
+## 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.
+
+## How Kevin measures itself (v0.5.0)
+
+Every injection is settled at `session.idle` into one of **four outcomes**:
+
+| Outcome | Meaning | Counts toward precision? |
+|---|---|---|
+| `effective` | A linked fix was observed after the injection | yes (numerator) |
+| `ineffective` | The same error recurred after the injection | yes (denominator) |
+| `inconclusive` | Neither — the error did not recur, but no fix was seen either | no |
+| `unmeasured` | Session went idle before settlement could run | no |
+
+- **`precision_rate`** = `effective / (effective + ineffective)`. The v0.4.0 definition counted "did not recur" as success — measuring absence of recurrence, not effect. **Your precision rate will look lower on v0.5.0. That is the honest number.** Existing `effective` rows were remapped to `inconclusive` by migration 006.
+- **`coverage_rate`** = `(effective + ineffective) / total` — the share of injections that were actually measured. Reported alongside precision so a low measurable fraction stays visible instead of hiding behind a large total.
+- **`blocked`** counts every gate rejection by reason (`seen_this_session`, `weak`, `recurrence`, `stale`, `ignored`) — a rejection you did not count did not happen.
+
+`kevin_trace` shows you the plan *before* it happens (dry run, zero side effects); `kevin_audit` reads the whole picture after; `kevin_feedback` lets a human correct it — and the correction moves the confidence number `kevin_why` reports.
+
+## Replay harness (v0.5.0)
+
+`npm run replay` runs every transcript in `tests/replay/fixtures/` through the plugin against an in-memory database with a frozen clock and prints one table row per transcript (memories created, injection outcomes, `precision_rate`, `coverage_rate`, tokens). Record your own session as a JSON array of typed events (`session.created`, `chat.message`, `tool.before`, `tool.after`, `system.transform`, `compacting`, `session.idle`) with ISO-8601 `at` timestamps, drop it into `tests/replay/fixtures/`, and re-run. The `at` timestamps are the only source of time during replay.
+
 ---
 
 ## Hooks
@@ -237,7 +326,7 @@ Kevin subscribes to 6 OpenCode hooks:
 |---|---|
 | `tool.execute.before` | Records tool call start (callID + redacted args) |
 | `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.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (900 tokens by default, configurable) + 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; boosts positive lessons (v0.2.0); penalizes recurring failures (v0.3.0); promotes causal patterns + mines patterns (opt-in); flushes metrics |
@@ -266,6 +355,18 @@ KevinPlugin(input, {
 });
 ```
 
+### Settings (v0.5.0)
+
+Read/write via `kevin_config({ action: "list" | "set", ... })`. v0.5.0 adds:
+
+| Setting | Default | Effect |
+|---|---|---|
+| `deterministic_retrieval` | `"0"` | Freezes Kevin's internal clock (recency factor 1.0, no relevance bumps) — for hermetic tests and the replay harness |
+| `pre_prompt_budget_tokens` | `"900"` | Pre-prompt injection cap, clamped to `[100, 4000]` (was a hard-coded 1500) |
+| `archive_after_days` | `"30"` | Age at which stale non-pattern memories are retired to `archived` on `session.idle` |
+
+All settings are stored as TEXT in `kevin_settings`; values are compared against `"1"` for booleans.
+
 ---
 
 ## Development
@@ -276,8 +377,9 @@ cd opencode-kevin
 npm install
 npm run typecheck   # tsc --noEmit (strict)
 npm run lint        # biome check .
-npm test            # vitest run (unit + integration + e2e)
+npm test            # vitest run (unit + integration + e2e + replay)
 npm run verify      # post-install verification
+npm run replay      # replay report over tests/replay/fixtures (v0.5.0)
 ```
 
 ### Publishing (maintainer)
@@ -301,13 +403,18 @@ plugin/
   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
@@ -316,6 +423,7 @@ migrations/
   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/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/migrations/006_v05_glassbox.sql

@@ -0,0 +1,118 @@
+-- ============================================================================
+-- 006_v05_glassbox.sql — v0.5.0 "Glass Box"
+--
+-- Honest measurement, human feedback, lifecycle completion.
+--
+-- Section 1: rebuild kevin_injections to admit a fourth outcome.
+-- Section 2: human feedback storage.
+-- Section 3: memory lifecycle columns.
+-- Section 4: metric seeds.
+-- Section 5: setting seeds.
+-- Section 6: schema_version.
+-- ============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. kevin_injections: add 'inconclusive'.
+--
+-- SQLite cannot ALTER a CHECK constraint, so the table must be rebuilt.
+-- Migration 004 set this precedent. kevin_injections has no FTS5 triggers,
+-- so unlike 004 this is a straight four-step rebuild.
+--
+-- Existing rows with outcome='effective' are remapped to 'inconclusive'.
+-- This is not data loss: v0.4's 'effective' meant "the error did not recur",
+-- which is the exact definition of the new 'inconclusive' bucket. Rows that
+-- genuinely earned the new 'effective' will be re-settled naturally, and the
+-- post-apply hook re-derives the counters from the table.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS kevin_injections_new (
+  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 NOT NULL DEFAULT 'unmeasured'
+              CHECK (outcome IN ('unmeasured','effective','ineffective','inconclusive'))
+);
+
+INSERT INTO kevin_injections_new
+  (id, memory_id, fingerprint, session_id, hook, tokens, injected_at, outcome)
+SELECT
+  id, memory_id, fingerprint, session_id, hook, tokens, injected_at,
+  CASE WHEN outcome = 'effective' THEN 'inconclusive' ELSE outcome END
+FROM kevin_injections;
+
+DROP TABLE kevin_injections;
+ALTER TABLE kevin_injections_new RENAME TO kevin_injections;
+
+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);
+
+-- ---------------------------------------------------------------------------
+-- 2. Human feedback. Append-only audit trail; the hot path reads the
+--    denormalized counters on `memories` (section 3), never this table.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS memory_feedback (
+  id         TEXT PRIMARY KEY,
+  memory_id  TEXT NOT NULL,
+  verdict    TEXT NOT NULL CHECK (verdict IN ('useful','wrong','outdated','ignore')),
+  session_id TEXT,
+  note       TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_memory  ON memory_feedback(memory_id);
+CREATE INDEX IF NOT EXISTS idx_feedback_created ON memory_feedback(created_at);
+
+-- ---------------------------------------------------------------------------
+-- 3. Memory lifecycle and feedback columns.
+--
+--    feedback_positive / feedback_negative are SEPARATE from evidence_count
+--    and recurrence_count by design: human judgement is evidence about the
+--    memory, causal counters are evidence about the world. Mixing them was
+--    the confidence-poisoning defect closed in v0.4.0.
+--
+--    superseded_by has no REFERENCES clause on purpose. Store enables
+--    PRAGMA foreign_keys=ON, and a hard FK would block deletion of a memory
+--    that superseded another.
+-- ---------------------------------------------------------------------------
+ALTER TABLE memories ADD COLUMN feedback_positive INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN feedback_negative INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN ignored           INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN superseded_by     TEXT;
+ALTER TABLE memories ADD COLUMN archived_at       TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_memories_ignored  ON memories(ignored);
+CREATE INDEX IF NOT EXISTS idx_memories_archived ON memories(archived_at);
+
+-- ---------------------------------------------------------------------------
+-- 4. Metric seeds. Order matches the additions to METRIC_KEYS in metrics.ts.
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('injections_inconclusive',      0),
+  ('injections_blocked_seen',      0),
+  ('injections_blocked_weak',      0),
+  ('injections_blocked_recurrence',0),
+  ('injections_blocked_stale',     0),
+  ('injections_blocked_ignored',   0),
+  ('feedback_positive_total',      0),
+  ('feedback_negative_total',      0),
+  ('memories_archived',            0);
+
+-- ---------------------------------------------------------------------------
+-- 5. Setting seeds. Values are TEXT, always. Read them with an explicit
+--    string comparison or an explicit Number() parse — never `=== 1`.
+--    (That exact mistake kept cross_project_enabled unreachable for the
+--    whole of v0.3.0.)
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('deterministic_retrieval',    '0'),
+  ('pre_prompt_budget_tokens', '900'),
+  ('archive_after_days',        '30');
+
+-- ---------------------------------------------------------------------------
+-- 6. Version marker.
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO schema_version (version) VALUES ('006');

package/dist/plugin/Archiver.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * v0.5.0 Archiver (K5-012 / plan §5.4, D5-05).
+ *
+ * Lifecycle tail of the memory loop: reflectors mark a lesson `stale` when
+ * its fingerprint recurred enough times (penalizeRecurringReflectors,
+ * migration 003), but nothing ever retires those rows — they keep
+ * circulating through status filters and inflating counts. The Archiver
+ * runs on `session.idle` and retires stale memories whose last activity
+ * (`updated_at`, falling back to `last_verified_at`) is older than
+ * `archive_after_days` (kevin_settings, seeded '30' in migration 006).
+ *
+ * Rules:
+ *  - Only `status = 'stale'` rows with `archived_at IS NULL`.
+ *  - `type != 'pattern'`: a pattern is the FIXED form of a fingerprint
+ *    (K4-025); archiving it would break kevin_why and the recurrence
+ *    re-admission path (QualityGate rule 4).
+ *  - Clock: the injection clock (K5-008) — tests freeze it; production
+ *    defaults to `new Date()`. Never `Date.now()` inside.
+ *  - `memories_archived` is bumped by the batch size, once per run.
+ *  - Pre-006 DBs (no `archived_at`) degrade to a no-op.
+ *
+ * Archived rows remain queryable with `includeSuperseded: true`-style
+ * reads (status filter is exclusive, not destructive).
+ */
+export declare class Archiver {
+    private readonly store;
+    private readonly memoryService;
+    private readonly metrics;
+    private readonly now;
+    constructor(store: Store, memoryService: MemoryService, metrics?: Metrics | null, now?: () => Date);
+    /**
+     * Archives every eligible stale memory. Returns the number of rows
+     * retired. Idempotent: archived rows are excluded by `archived_at IS
+     * NULL`, so a second run archives nothing.
+     */
+    run(): number;
+    private archiveAfterDays;
+    private hasArchivedColumn;
+}

package/dist/plugin/Archiver.js

@@ -0,0 +1,98 @@
+/**
+ * v0.5.0 Archiver (K5-012 / plan §5.4, D5-05).
+ *
+ * Lifecycle tail of the memory loop: reflectors mark a lesson `stale` when
+ * its fingerprint recurred enough times (penalizeRecurringReflectors,
+ * migration 003), but nothing ever retires those rows — they keep
+ * circulating through status filters and inflating counts. The Archiver
+ * runs on `session.idle` and retires stale memories whose last activity
+ * (`updated_at`, falling back to `last_verified_at`) is older than
+ * `archive_after_days` (kevin_settings, seeded '30' in migration 006).
+ *
+ * Rules:
+ *  - Only `status = 'stale'` rows with `archived_at IS NULL`.
+ *  - `type != 'pattern'`: a pattern is the FIXED form of a fingerprint
+ *    (K4-025); archiving it would break kevin_why and the recurrence
+ *    re-admission path (QualityGate rule 4).
+ *  - Clock: the injection clock (K5-008) — tests freeze it; production
+ *    defaults to `new Date()`. Never `Date.now()` inside.
+ *  - `memories_archived` is bumped by the batch size, once per run.
+ *  - Pre-006 DBs (no `archived_at`) degrade to a no-op.
+ *
+ * Archived rows remain queryable with `includeSuperseded: true`-style
+ * reads (status filter is exclusive, not destructive).
+ */
+export class Archiver {
+    store;
+    memoryService;
+    metrics;
+    now;
+    constructor(store, memoryService, metrics, now = () => new Date()) {
+        this.store = store;
+        this.memoryService = memoryService;
+        this.metrics = metrics ?? null;
+        this.now = now;
+    }
+    /**
+     * Archives every eligible stale memory. Returns the number of rows
+     * retired. Idempotent: archived rows are excluded by `archived_at IS
+     * NULL`, so a second run archives nothing.
+     */
+    run() {
+        if (!this.hasArchivedColumn())
+            return 0;
+        const days = this.archiveAfterDays();
+        if (days <= 0)
+            return 0;
+        const now = this.now();
+        const cutoff = formatSqliteUtc(new Date(now.getTime() - days * 86_400_000));
+        this.store
+            .prepare(`UPDATE memories
+				    SET status = 'archived', archived_at = ?, updated_at = ?
+				  WHERE status = 'stale'
+				    AND type != 'pattern'
+				    AND archived_at IS NULL
+				    AND updated_at < ?`)
+            .run(formatSqliteUtc(now), formatSqliteUtc(now), cutoff);
+        const changed = this.store.prepare("SELECT changes() AS n").get();
+        const n = changed.n;
+        if (n > 0)
+            this.metrics?.incr("memories_archived", n);
+        return n;
+    }
+    archiveAfterDays() {
+        try {
+            const raw = this.memoryService.getSetting("archive_after_days", "30");
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : 30;
+        }
+        catch {
+            return 30;
+        }
+    }
+    hasArchivedColumn() {
+        return hasArchivedColumnCached(this.store);
+    }
+}
+const archivedColumnCache = new WeakMap();
+function hasArchivedColumnCached(store) {
+    const cached = archivedColumnCache.get(store);
+    if (cached !== undefined)
+        return cached;
+    try {
+        store.prepare("SELECT archived_at FROM memories LIMIT 1").get();
+        archivedColumnCache.set(store, true);
+        return true;
+    }
+    catch {
+        archivedColumnCache.set(store, false);
+        return false;
+    }
+}
+/** 'YYYY-MM-DD HH:MM:SS' UTC — the format SQLite `datetime('now')` uses,
+ * so lexicographic comparisons against `updated_at` are valid. */
+function formatSqliteUtc(d) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+//# sourceMappingURL=Archiver.js.map

package/dist/plugin/Archiver.js.map

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

package/dist/plugin/CausalChain.d.ts

@@ -1,3 +1,4 @@
+import { type EnrichFn } from "./LessonFixer.js";
 import type { MemoryService } from "./MemoryService.js";
 import type { Store } from "./Store.js";
 import type { Metrics } from "./metrics.js";
@@ -5,7 +6,17 @@ export declare class CausalChain {
     private store;
     private memoryService;
     private metrics;
-    constructor(store: Store, memoryService: MemoryService, metrics: Metrics | null);
+    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): number;
+    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;
 }