@jmtrin/opencode-kevin 0.3.0 → 0.4.0

package/README.md

@@ -7,6 +7,8 @@ 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.
 
 ---
@@ -31,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 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 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
 
@@ -135,7 +137,7 @@ Use `:memory:` for `dbPath` in tests.
 
 ## Tools
 
-Kevin exposes 9 tools callable by the agent:
+Kevin exposes 10 tools callable by the agent:
 
 ### `kevin_save`
 
@@ -171,7 +173,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 +188,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`.
 
 ```
 kevin_status({})
@@ -194,7 +197,10 @@ 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_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`
@@ -221,12 +227,32 @@ 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).
+
+---
+
+## 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
@@ -301,13 +327,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 +347,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/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;
 }

package/dist/plugin/CausalChain.js

@@ -1,13 +1,20 @@
+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;
-    constructor(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
@@ -18,7 +25,7 @@ export class CausalChain {
     // typecheck failure) was stamped as the fix for that error.
     onSuccess(_tool, _args, _projectId, sessionId) {
         const successRow = this.store
-            .prepare(`SELECT rowid FROM tool_calls
+            .prepare(`SELECT rowid, tool, args_summary FROM tool_calls
 				 WHERE session_id = ? AND success = 1
 				 ORDER BY rowid DESC LIMIT 1`)
             .get(sessionId);
@@ -50,7 +57,7 @@ export class CausalChain {
             const mem = this.store
                 .prepare(`SELECT 1 FROM memories
 					 WHERE fingerprint = ? AND type = 'error'
-					   AND origin = 'reflector' AND status = 'active'
+					   AND origin = 'reflector' AND status IN ('active', 'stale')
 					   AND created_at > datetime('now', '-24 hours')
 					 LIMIT 1`)
                 .get(fail.fp);
@@ -59,13 +66,27 @@ export class CausalChain {
             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;
         }
     }
-    onSessionIdle(sessionId) {
+    async onSessionIdle(sessionId) {
         const linkedErrors = this.store
-            .prepare(`SELECT m.id, m.fingerprint,
+            .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
@@ -77,26 +98,38 @@ export class CausalChain {
 				       FROM tool_calls
 				       WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL
 				   )
-				   AND m.status = 'active'
+				   AND m.status IN ('active', 'stale')
 				 GROUP BY m.fingerprint
 				 HAVING (
-				     SELECT MAX(tc.rowid) FROM tool_calls tc
+				     SELECT MAX(tc.ts) FROM tool_calls tc
 				     WHERE tc.fix_for_fingerprint = m.fingerprint
-				 ) > COALESCE(
-				     (SELECT MAX(m2.rowid) FROM memories m2
+				 ) >= COALESCE(
+				     (SELECT MAX(m2.updated_at) FROM memories m2
 				      WHERE m2.fingerprint = m.fingerprint
 				        AND m2.type = 'pattern'
 				        AND m2.origin = 'causal'),
-				     0
+				     '1970-01-01'
 				 )`)
             .all(sessionId);
         let promoted = 0;
         for (const err of linkedErrors) {
             try {
-                const id = this.memoryService.promoteToPattern(err.id, err.evidence_count);
-                if (id) {
+                const result = this.memoryService.promoteToPattern(err.id, err.evidence_count, err.recurrence_count ?? 0);
+                if (result) {
                     promoted++;
-                    this.metrics?.incr("patterns_causal", 1);
+                    // 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 {
@@ -105,5 +138,42 @@ export class CausalChain {
         }
         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

@@ -1 +1 @@
-{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"AAIA,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,MAAM,OAAO,WAAW;IAEd;IACA;IACA;IAHT,YACS,KAAY,EACZ,aAA4B,EAC5B,OAAuB;QAFvB,UAAK,GAAL,KAAK,CAAO;QACZ,kBAAa,GAAb,aAAa,CAAe;QAC5B,YAAO,GAAP,OAAO,CAAgB;IAC7B,CAAC;IAEJ,iEAAiE;IACjE,oEAAoE;IACpE,8DAA8D;IAC9D,oEAAoE;IACpE,iEAAiE;IACjE,8DAA8D;IAC9D,4DAA4D;IAC5D,SAAS,CACR,KAAa,EACb,KAA8B,EAC9B,UAAyB,EACzB,SAAiB;QAEjB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK;aAC3B,OAAO,CACP;;iCAE6B,CAC7B;aACA,GAAG,CAAC,SAAS,CAAkC,CAAC;QAClD,IAAI,CAAC,UAAU;YAAE,OAAO;QAExB,MAAM,SAAS,GAAG,IAAI,GAAG,CAEvB,IAAI,CAAC,KAAK;aACR,OAAO,CACP;gEAC0D,CAC1D;aACA,GAAG,CAAC,SAAS,CACf,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CACnC,CAAC;QAEF,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,iDAAiD;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK;aACzB,OAAO,CACP;;;;;iCAK6B,CAC7B;aACA,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAG/B,CAAC;QAEJ,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YACjD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,iBAAiB;gBAAE,SAAS;YAEpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK;iBACpB,OAAO,CACP;;;;cAIS,CACT;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,IAAI,CAAC,KAAK;iBACR,OAAO,CACP,+DAA+D,CAC/D;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YACtC,OAAO;QACR,CAAC;IACF,CAAC;IAED,aAAa,CAAC,SAAiB;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK;aAC7B,OAAO,CACP;;;;;;;;;;;;;;;;;;;;;;;OAuBG,CACH;aACA,GAAG,CAAC,SAAS,CAIZ,CAAC;QAEJ,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC;gBACJ,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAC7C,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,cAAc,CAClB,CAAC;gBACF,IAAI,EAAE,EAAE,CAAC;oBACR,QAAQ,EAAE,CAAC;oBACX,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,4DAA4D;YAC7D,CAAC;QACF,CAAC;QAED,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD"}
+{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"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"}

package/dist/plugin/ContextInjector.d.ts

@@ -1,5 +1,8 @@
+import type { InjectionLedger } from "./InjectionLedger.js";
 import type { MemoryService } from "./MemoryService.js";
 import { type Metrics } from "./metrics.js";
+export declare const QUALITY_GATE_SETTING = "quality_gate_enabled";
+export declare const SNIPPET_INJECTION_SETTING = "lesson_snippet_injection";
 export interface ChatMessage {
     role: string;
     content: string;
@@ -21,19 +24,45 @@ export interface CompactingOutput {
 export declare class ContextInjector {
     private memoryService;
     private metrics;
+    private ledger;
     private lastRecurrenceCount;
-    constructor(memoryService: MemoryService, metrics?: Metrics | null);
+    /** v0.4.0 (K4-016) — session that produced the last recurrence set. */
+    private lastRecurredSession;
+    /** v0.4.0 (K4-017) — per-session seen-set (plan §5.1 rule 3). */
+    private readonly seenBySession;
+    constructor(memoryService: MemoryService, metrics?: Metrics | null, ledger?: InjectionLedger | null);
+    /**
+     * v0.4.0 (K4-017) — reset the per-session seen-set when a session is
+     * created (plan §5.1 rule 3). Wired from the `session.created` event.
+     */
+    onSessionCreated(sessionId: string): void;
     /**
      * v0.3.0 (K3-020) — notify the injector that the negative feedback half
      * fired N times in the last session.idle. The next system.transform or
      * compacting hook will prepend a HITL suggestion block.
+     * v0.4.0 (K4-016) — the session id enables the concrete suggestion:
+     * the most-recurred fingerprint's pattern + its fix_args.
      */
-    setRecurrences(count: number): void;
+    setRecurrences(count: number, sessionId?: string): void;
     /**
-     * v0.3.0 (K3-020) — generate a HITL suggestion block when recurrences
-     * occurred. Returns the block or empty string. Resets the counter.
+     * v0.4.0 (K4-016) — generate a CONCRETE HITL suggestion block when
+     * recurrences occurred (plan §5.5): names the most-recurred pattern,
+     * its exact recurrence count, observed fix_args and confidence. The
+     * AGENTS.md draft line derives from the lesson's `Suggestion:` text —
+     * never a canned string, and never the anonymous "the same error
+     * pattern" without naming the pattern and count.
+     *
+     * BUG-012 — emits AT MOST ONCE per session: calling it resets the
+     * pending recurrence signal, so whichever hook (system.transform or
+     * compacting) runs first in a session consumes the block. Documented
+     * behavior; wire index.ts to match.
      */
     generateSuggestion(): string;
+    /**
+     * v0.4.0 (K4-016) — the AGENTS.md draft line derives from the lesson's
+     * `Suggestion:` text (kept verbatim in the pattern's `Original:` block).
+     */
+    private agentsDraftLine;
     /**
      * v0.2.0 (K2-024): origin-aware ranking at injection time is delegated
      * to `MemoryService.getRelevant()` (K2-023, D2-13). The injector does
@@ -42,8 +71,55 @@ export declare class ContextInjector {
      * callers. Plan §B6.5: "apply the same multiplier as
      * MemoryService.recall so reflector lessons outrank agent-saved notes
      * at injection time" — satisfied transitively via the getRelevant call.
+     *
+     * v0.4.0 (K4-017): after retrieval, every memory is filtered through
+     * `QualityGate.canInject` (session seen-set + recurrence + strength),
+     * and each admitted memory is recorded in the `InjectionLedger`
+     * (plan §5.2 — one row per injected memory).
      */
     private inject;
+    /**
+     * v0.4.0 (K4-017) — QualityGate admission: filters the ranked slice to
+     * memories that may be injected this session, updating the session
+     * seen-set.
+     *
+     * BUG-005 — strength/actionability now go through the REAL
+     * `QualityGate.evaluate` semantics (plan §5.1 rules 1-2), which this
+     * class had only re-derived from `metadata.dispatch`:
+     *   - dispatched code → strong + actionable (rescued errorType);
+     *   - generic fallback suggestion + no code → weak, NOT actionable
+     *     (the generic-suggestion ban is now enforced even for legacy
+     *     lessons without dispatch metadata, as long as the `Suggestion:`
+     *     text is available);
+     *   - specific suggestion without code → strong + actionable;
+     *   - no `Suggestion:` text at all (agent-saved note) → strong +
+     *     actionable — the agent explicitly asked to remember it;
+     *   - causal patterns (type='pattern') → always strong + actionable:
+     *     they are the FIXED form of a fingerprint (K4-025).
+     */
+    private admit;
+    /**
+     * BUG-005 — the single source of truth for a memory's lesson quality,
+     * shared by `admit` (the gate) and `format` (the K4-023 `(low
+     * confidence)` marker). Routes lessons through `QualityGate.evaluate`
+     * — the production call site that was previously missing.
+     */
+    private lessonQuality;
+    /**
+     * v0.4.0 (K4-017) — one ledger row per admitted memory (plan §5.2).
+     * Token attribution uses the memory's share of the final block.
+     */
+    private recordInjections;
+    /**
+     * v0.4.0 (K4-012) — snippet injection payload (plan §5.1 rule 5,
+     * D4-05): rows show `id:` + first 2 non-empty lines + `<protect>`
+     * instead of the full body. Gated by the `lesson_snippet_injection`
+     * setting (default `'1'`); when `'0'`, full content is restored.
+     * `escapeInjectedText` is applied to snippet content by the formatter.
+     * v0.4.0 (K4-023) — weak lessons admitted in debug mode are flagged so
+     * the formatter renders the `(low confidence)` marker.
+     */
+    private format;
     deriveQuery(messages: ChatMessage[]): string;
     onSystemTransform(input: SystemTransformInput, output: SystemTransformOutput): void;
     onCompacting(input: CompactingInput, output: CompactingOutput): void;