@jmtrin/opencode-kevin 0.5.0 → 0.7.0

package/README.md

@@ -6,14 +6,30 @@ 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).
+- **Knowledge + Causality**: causal failure→fix chains, `kevin_why` explanations, OKF export/import, a supersede model, and human-in-the-loop AGENTS.md suggestions.
+- **Signal over Noise**: a quality gate that stores weak lessons without injecting them, an injection ledger with honest `precision_rate`, and two-sided confidence.
+- **Glass Box**: 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`, and a hermetic replay harness.
+- **Pull**: knowledge earns its way into files the model actually reads — `kevin_propose` generates a reviewable diff, a human approves, and **only then** does Kevin write, inside a frozen marker block, preserving your file's CRLF/BOM/formatting byte-for-byte outside it. Plus three distribution channels (AGENTS.md, skills, references) and a push budget gated by a confidence floor.
+- **Audited**: the v0.4.0 bug catalog (`docs/Kevin_v0.4.0_Bugs.md`) is fully closed — 16/16 bugs fixed and regression-tested.
 - **Standalone**: works without any other plugin. With the ecosystem, it learns more richly.
 
 ---
 
+## Contents
+
+- [Installation](#installation)
+- [How Kevin works](#how-kevin-works)
+- [Tools](#tools)
+- [How Kevin measures itself](#how-kevin-measures-itself)
+- [Curation & Pull](#curation--pull)
+- [Replay harness](#replay-harness)
+- [Hooks](#hooks)
+- [Configuration](#configuration)
+- [Development](#development)
+- [License](#license)
+
+---
+
 ## Installation
 
 ### 1. Declare the plugin
@@ -34,7 +50,9 @@ 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 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).
+Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, Kevin exposes 18 tools, including `kevin_facts` and `kevin_conflicts`.
+
+Contradictions de-rank memories and surface conflicts. They never delete, stale, archive, or auto-resolve a memory.
 
 ### 3. Where data lives
 
@@ -85,60 +103,48 @@ Use `:memory:` for `dbPath` in tests.
 
 ---
 
-## Cycle: Observe → Learn → Share
+## How Kevin works
+
+Every tool call is observed; every failure becomes a lesson; every lesson is either pushed into the next prompt, written into an artifact a human approved, or retired when it stops earning its place.
 
 ```
   Tool call (success or failure)
          │
          ▼
-  ┌─────────────────┐
-  │   OBSERVE        │  ToolCallObserver records every call
-  │  ToolCallObserver│  (tool, args redacted, success, duration, error_type,
-  │                  │   id = callID) + stripPrivate + opt-in dedup (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
-  │                  │  (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
-  │                  │    feedback half (HITL, v0.3.0)
-  └────────┬────────┘
-           │ session.idle
-           ▼
-  ┌─────────────────┐
-  │  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)
-  └─────────────────┘
-```
+  ┌─────────────────────────┐  OBSERVE
+  │    ToolCallObserver     │  records every call (tool, redacted args,
+  └───────────┬─────────────┘  success, duration, error type, dedup)
+              │
+   failure    │              success
+   ┌──────────▼───────────┐   ┌─────────────────────────┐
+   │       Reflector      │   │       CausalChain       │
+   │  heuristic lesson    │   │  links the fix to the   │
+   │  per error code      │   │  failure within 10 calls│
+   │  (throttled per      │   └────────────┬────────────┘
+   │   fingerprint)       │                │
+   └──────────┬───────────┘                │ session.idle
+              │                            ▼
+              ▼              ┌─────────────────────────┐
+  ┌───────────────────────┐  │  promotes recurring     │
+  │    ContextInjector    │◄─┤  errors → causal        │
+  │  SHARE: injects       │  │  patterns (cumulative   │
+  │  <kevin-context>      │  │  evidence)              │
+  │  ≤400 tokens/prompt   │  └─────────────────────────┘
+  └───────────┬───────────┘
+              │ session.idle
+              ▼
+  ┌─────────────────────────┐  RETROSPECTIVE: <session>.md with
+  │     Retrospective       │  lessons, metrics snapshot, causal
+  └─────────────────────────┘  promotion, pattern mining (opt-in)
+```
+
+At `session.idle` Kevin also settles injection outcomes, retires stale memories, and — when curation is enabled — drafts pull proposals for your review (see [Curation & Pull](#curation--pull)).
 
 ---
 
 ## Tools
 
-Kevin exposes 13 tools callable by the agent:
+Kevin exposes 16 tools callable by the agent.
 
 ### `kevin_save`
 
@@ -149,25 +155,23 @@ kevin_save({ type: "decision", content: "We use vitest for tests", scope: "proje
 // → { "id": "0195a3b2-..." }
 ```
 
-`type`: `error` | `pattern` | `decision` | `context` | `rule` | `solution` (v0.3.0). `scope`: `project` (persists) | `session` (TTL 24h).
+`type`: `error` | `pattern` | `decision` | `context` | `rule` | `solution`. `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).
+Saving a `decision` or `rule` with the same `fingerprint` as an existing active row supersedes the old one (`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, or `evidence: true` (v0.3.0) to include `confidence`, `evidence_count`, `last_verified_at` in the slim payload.
+Searches memories by text (FTS5 + bm25). Returns a **slim** payload by default; pass `full: true` for the complete content, or `evidence: true` to include `confidence`, `evidence_count` and `last_verified_at`.
 
 ```
 kevin_query({ query: "typecheck", type: "error", limit: 5 })
-// → [{ "id": "...", "type": "error", "scope": "project", "score": -0.87, "snippet": "When bash fails with typecheck:..." }, ...]
-
-kevin_query({ query: "typecheck", type: "error", limit: 5, full: true })
-// → [{ "id": "...", "type": "error", "content": "...", "scope": "project" }, ...]
+// → [{ "id": "...", "type": "error", "scope": "project", "score": -0.87,
+//      "snippet": "When bash fails with typecheck:..." }, ...]
 ```
 
 ### `kevin_get`
 
-Fetches a **single full memory** by id (v0.2.0 — progressive disclosure). Use when `kevin_query` returns a slim snippet and you need the complete content.
+Fetches a **single full memory** by id (progressive disclosure) — use it when `kevin_query` returned a slim snippet and you need the complete content.
 
 ```
 kevin_get({ id: "0195a3b2-..." })
@@ -180,7 +184,7 @@ kevin_get({ id: "0195a3b2-..." })
 
 ### `kevin_recall`
 
-Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope. Pass `includeSuperseded: true` to include superseded rows (v0.3.0).
+Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope. Pass `includeSuperseded: true` to include superseded rows.
 
 ```
 kevin_recall({ query: "auth", limit: 3 })
@@ -189,28 +193,33 @@ 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`); 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 }`.
+Global counts and metrics: memory census, the precision block, the six blocked-gate counters, feedback totals, and the v0.6 block (`schema_version`, `curation_enabled`, emission states, `proposals_pending` — omitted on pre-007 databases).
 
 ```
 kevin_status({})
-// → { "memories": 42, "memories_reflector": 12, "memories_agent": 30, "memories_pattern": 0,
-//      "memories_causal": 1, "tool_calls": 318, "retrospectives": 7,
+// → { "memories": 42, "memories_reflector": 12, "memories_agent": 30,
+//      "memories_pattern": 0, "memories_causal": 1, "tool_calls": 318,
+//      "retrospectives": 7, "tool_count": 16,
 //      "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,
-//                   "injections_inconclusive": 9, "injections_blocked_seen": 1, ... },
+//                   "injections_inconclusive": 9, ... },
 //      "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 },
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0,
+//                   "ignored": 1, "confidence": 2 },
 //      "memories_ignored": 1, "memories_archived": 4,
 //      "feedback": { "positive": 2, "negative": 1 },
-//      "patterns_promoted_new": 2, "recurrence_by_origin": { "reflector": 3, "causal": 1 } }
+//      "patterns_promoted_new": 2, "recurrence_by_origin": { "reflector": 3, "causal": 1 },
+//      "v06": { "schema_version": "007", "curation_enabled": "1",
+//               "skill_emission": "off", "reference_emission": "off",
+//               "proposals_pending": 2 } }
 ```
 
 ### `kevin_retrospective`
 
-Generates a retrospective for a session (uses current session if `session_id` is omitted).
+Generates a retrospective for a session (uses the current session if `session_id` is omitted).
 
 ```
 kevin_retrospective({ session_id: "sess-abc" })
@@ -218,7 +227,7 @@ kevin_retrospective({ session_id: "sess-abc" })
 // or → { "message": "No failures in session sess-abc." }
 ```
 
-### `kevin_why` (v0.3.0)
+### `kevin_why`
 
 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.
 
@@ -230,29 +239,31 @@ kevin_why({ query: "TS2304 cannot find name" })
 //      "related_rules": [ { "code": "TS2304", "suggestion": "import or typo" } ] }
 ```
 
-### `kevin_export` (v0.3.0)
+### `kevin_export`
 
-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.
+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`, `recurrence_count`, `last_verified_at`, `fingerprint`. Timestamps are treated as UTC — a re-import reproduces the exact source values.
 
-### `kevin_import` (v0.3.0)
+### `kevin_import`
 
 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)
+### `kevin_config`
 
 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", ... }
+// → { "quality_gate_enabled": "1", "lesson_snippet_injection": "1",
+//      "llm_reflection_enabled": "0", "pre_prompt_budget_tokens": "400",
+//      "injection_confidence_floor": "0.6", ... }
 
 kevin_config({ action: "set", key: "quality_gate_enabled", value: "0" })
-// → { "ok": true }
+// → { "ok": true, "key": "quality_gate_enabled", "value": "0" }
 ```
 
-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).
+All settings and their defaults are listed in [Configuration](#configuration).
 
-### `kevin_feedback` (v0.5.0)
+### `kevin_feedback`
 
 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.
 
@@ -261,41 +272,79 @@ kevin_feedback({ memory_id: "0195a3b2-...", verdict: "wrong", note: "the fix was
 // → { "ok": true, "verdict": "wrong" }
 ```
 
-### `kevin_trace` (v0.5.0)
+### `kevin_trace`
 
-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`).
+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` | `confidence`).
 
 ```
 kevin_trace({ query: "tsc error" })
-// → { "query": "tsc error", "tag": "context", "cap": 900, "would_inject": true,
+// → { "query": "tsc error", "tag": "context", "cap": 400, "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 } ] }
+//      "blocked": [ { "id": "...", "type": "error", "decision": "blocked",
+//                     "reason": "confidence", "tokens": 20 } ] }
 ```
 
-### `kevin_audit` (v0.5.0)
+### `kevin_audit`
 
-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`.
+Read-only report of the whole system state: memories by `status`/`origin`/`type`, injection outcomes with `precision_rate`/`coverage_rate`, the six `blocked` counters, feedback by verdict, tokens injected, the push-vs-pull `channels` comparison and the `curation` scoreboard. `verbose: true` adds the settings block. No writes, no LLM; on pre-007 databases it omits the v0.6 blocks and reports `"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 },
+//                   "ignored": 1, "with_feedback": 3 },
 //      "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 },
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0,
+//                   "ignored": 1, "confidence": 2 },
 //      "feedback": { "positive": 2, "negative": 1, "by_verdict": { "useful": 2, "wrong": 1 } },
-//      "tokens": { "pre_prompt": 51, "compacting": 0 }, "partial": false }
+//      "tokens": { "pre_prompt": 51, "compacting": 0 }, "partial": false,
+//      "channels": { "push": { "tokens_pre_prompt": 51, "injections_total": 14,
+//                              "precision_rate": 0.40, "coverage_rate": 0.36,
+//                              "budget_tokens": 400 },
+//                    "pull": { "proposals_created": 6, "proposals_approved": 1,
+//                              "proposals_rejected": 2, "artifact_writes_total": 2,
+//                              "artifact_writes_noop": 1, "references_registered": 0,
+//                              "skills_registered": 0,
+//                              "skill_emission": "off", "reference_emission": "off" } },
+//      "curation": { "eligible": 5, "curated": 1, "inferable": 3, "non_inferable": 2,
+//                    "unknown": 1, "proposals_by_status": { "pending": 2, "applied": 1, ... } } }
 ```
 
----
+### `kevin_propose`
+
+Creates curation proposals as `pending` rows with unified diffs — **a strict dry run**. Reads the eligible memories (`inferable != 1`), renders what would go into the artifact, and returns the minimal diff. No disk write, no `curated` marks, no side effects. Only `kevin_approve` may write.
 
-## Precision (v0.4.0)
+```
+kevin_propose({ kind: "agents_md" })   // kind: "agents_md" | "skill" | "reference"
+// → { "proposals": [ { "id": "...", "kind": "agents_md", "targetPath": "AGENTS.md",
+//                      "memoryIds": ["mem-1"], "status": "pending",
+//                      "createdAt": "2026-08-14 10:00:00",
+//                      "diff": "--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ ..." } ] }
+```
 
-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.
+### `kevin_approve`
 
-## How Kevin measures itself (v0.5.0)
+The **only** code path that writes a file. `approve` applies the proposal's diff atomically (temp file + rename, CRLF/BOM preserved), records an `artifact_writes` audit row, marks the proposal `applied` and its memories `curated`. `reject` records the human decision and touches nothing. Refusals and noops are audited, never silent.
+
+```
+kevin_approve({ proposal_id: "...", decision: "approve" })   // or "reject"
+// → { "proposalId": "...", "status": "applied", "outcome": "written", "curated": 1 }
+//   ("outcome": "noop" when the artifact already matches, "refused" when the
+//    marker block is malformed; a rejected proposal returns
+//    { "proposalId": "...", "status": "rejected" })
+```
+
+### `kevin_publish`
+
+Regenerates the pull-channel bundles under `~/.opencode-kevin/` — `skills/project-knowledge.md` and `refs/<topic>.md` — reporting per-bundle outcome and the emission state (`on` / `off` / `unavailable`). Registration with the host happens at plugin startup; this tool only materializes and reports.
+
+---
+
+## How Kevin measures itself
+
+### Injection outcomes
 
 Every injection is settled at `session.idle` into one of **four outcomes**:
 
@@ -306,13 +355,77 @@ Every injection is settled at `session.idle` into one of **four outcomes**:
 | `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.
+- **`precision_rate`** = `effective / (effective + ineffective)`. Measuring *effect*, not absence of recurrence: a lesson that was injected and never contradicted counts as `inconclusive`, not success. **Your precision rate will look lower than before v0.5.0. That is the honest number.**
 - **`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.
+- **`blocked`** counts every gate rejection by reason — `seen_this_session`, `weak`, `recurrence`, `stale`, `ignored`, `confidence` — a rejection you did not count did not happen.
+
+### The quality gate
+
+Weak lessons — errors the reflector cannot dispatch to a deterministic rule — are **stored but never injected** while `quality_gate_enabled = '1'` (default). 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.
+
+### Seeing the whole picture
+
+`kevin_trace` shows you the plan *before* it happens (dry run, zero side effects); `kevin_audit` reads the whole state after; `kevin_feedback` lets a human correct it — and the correction moves the confidence number `kevin_why` reports.
+
+---
+
+## Curation & Pull
 
-`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.
+### The marker contract
 
-## Replay harness (v0.5.0)
+Kevin never edits your files directly. Every artifact write happens inside a frozen marker block, delimited verbatim by:
+
+```
+<!-- kevin:begin — curated by opencode-kevin, safe to edit -->
+<!-- kevin:end -->
+```
+
+These exact strings are **frozen for the v0.x line** — README, tests and the v1.0.0 migration plan all depend on their byte sequences. What Kevin guarantees:
+
+- **Only the block between the markers may change.** Bytes outside them are byte-identical after every write — including line endings (a CRLF file stays CRLF everywhere, even inside the generated block), a leading UTF-8 BOM, and the file's final newline.
+- **Malformed markers are refused, never repaired.** If the file contains a `begin` without an `end` (or vice versa), Kevin refuses the write with an explicit reason and the file is untouched. Repairing would mean guessing at user intent; refusing means the state stays visible and auditable.
+- **Idempotent**: applying an unchanged plan is a counted `noop` — no temp file, no write, no mtime churn.
+
+### The propose → review → approve flow
+
+```
+   eligible memories (inferable != 1)
+          │
+          ▼
+   kevin_propose({ kind })          ── creates pending rows + unified diffs.
+          │                            NO disk write, NO curated marks.
+          ▼
+   HUMAN REVIEWS THE DIFF           ── this is the entire safety model:
+          │                            a memory earns its way into a file
+          ▼                            only after a human said yes.
+   kevin_approve({ proposal_id, decision })
+          │
+          ├── "approve"  ── ArtifactWriter.apply() (the ONLY write path)
+          │                 atomic temp+rename, audit row in artifact_writes,
+          │                 memory marked curated, proposal marked applied
+          └── "reject"   ── recorded, nothing touches disk
+```
+
+Rejection history is never deleted: it is the evidence base for the roadmap's kill criterion "proposals rejected more often than approved".
+
+### Three distribution channels
+
+| Channel | Artifact | Cost when unused |
+|---|---|---|
+| **Push** | per-prompt `<kevin-context>` injection | charges on every prompt — now capped at 400 tokens by default |
+| **Pull — AGENTS.md** | marker block in the project's `AGENTS.md` | zero |
+| **Pull — skills** | `~/.opencode-kevin/skills/project-knowledge.md` (`skill_emission_enabled`) | zero |
+| **Pull — references** | `~/.opencode-kevin/refs/<topic>.md` (`reference_emission_enabled`) | zero |
+
+`kevin_audit`'s `channels` block compares push vs pull on the same axes, and reports each emission channel as `"on"`, `"off"` (setting `'0'` on a capable host) or `"unavailable"` (host without the v2 domain).
+
+### The confidence floor gate
+
+`injection_confidence_floor` (default `'0.6'`) rejects memories whose computed confidence is below the floor, counted as `injections_blocked_confidence` — the sixth gate rejection reason, measured exactly like the first five. Single-observation memories (base confidence 0.5, no confirmed evidence) stop being pushed by default; `kevin_config({ action: "set", key: "injection_confidence_floor", value: "0" })` restores v0.5 behaviour exactly.
+
+---
+
+## Replay harness
 
 `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.
 
@@ -325,15 +438,15 @@ 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 (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>` (900 tokens by default, configurable) + optional `<kevin-suggestion>` (v0.3.0) |
+| `tool.execute.after` | Records result (id = callID); on failure → Reflector.invoke async (throttled); on success → CausalChain links the fix |
+| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (400 tokens by default, configurable) + optional `<kevin-suggestion>` |
 | `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 |
+| `event` (`session.created`) | Captures current `sessionID` (skill/reference emissions register at plugin startup, not per session) |
+| `event` (`session.idle`) | Settles injection outcomes; generates the retrospective; boosts positive lessons; penalizes recurring failures; promotes causal patterns and mines patterns (opt-in); drafts curation proposals (`curation_enabled`); 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>`.
+**Redaction**: absolute paths (`C:\Users\...`, `/home/...`) → `<path>` and secrets (`API_KEY=`, `Bearer`, `token`) → `<redacted>` before persisting anything. `<private>…</private>` blocks are swept from tool call args and output before persistence and replaced with `<private: redacted N chars>`.
 
-**Throttle**: Reflector generates at most 1 lesson per minute per unique fingerprint (v0.2.0: per-fingerprint, not global). Configurable via `throttleMs`.
+**Throttle**: Reflector generates at most 1 lesson per minute per unique fingerprint (per-fingerprint, not global). Configurable via `throttleMs`.
 
 **Truncation**: content > 4KB keeps the lesson searchable; only the additional context is truncated (`metadata.truncated = true`).
 
@@ -341,6 +454,8 @@ Kevin subscribes to 6 OpenCode hooks:
 
 ## Configuration
 
+### Plugin options
+
 Kevin accepts options via the plugin's tuple form (see Installation → Advanced). Programmatic defaults:
 
 ```ts
@@ -355,17 +470,26 @@ KevinPlugin(input, {
 });
 ```
 
-### Settings (v0.5.0)
+### Settings
 
-Read/write via `kevin_config({ action: "list" | "set", ... })`. v0.5.0 adds:
+Read/write via `kevin_config({ action: "list" | "set", ... })`. All values are TEXT; booleans compare against `"1"`.
 
 | Setting | Default | Effect |
 |---|---|---|
+| `quality_gate_enabled` | `"1"` | Weak lessons are stored but never injected while enabled |
+| `lesson_snippet_injection` | `"1"` | Injects the rescued errorType snippet with each lesson |
+| `llm_reflection_enabled` | `"0"` | Opt-in LLM enrichment of reflector lessons |
+| `cross_project_enabled` | `"0"` | `kevin_query` includes imported cross-project memories |
+| `patternminer_enabled` | `"0"` | Opt-in deterministic 2-gram/3-gram pattern miner at `session.idle` |
+| `tool_calls_dedup_enabled` | `"0"` | Opt-in dedup of repeated tool calls |
 | `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) |
+| `pre_prompt_budget_tokens` | `"400"` | Pre-prompt injection cap, clamped to `[0, 4000]`; `0` turns push off |
 | `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.
+| `curation_enabled` | `"1"` | Generates curation proposals at `session.idle` |
+| `agents_md_path` | `"AGENTS.md"` | Where the AGENTS.md channel writes (project-relative) |
+| `skill_emission_enabled` | `"0"` | Registers the curated skill with the host at startup (v2 hosts only) |
+| `reference_emission_enabled` | `"0"` | Registers `@kevin/<topic>` references at startup (v2 hosts only) |
+| `injection_confidence_floor` | `"0.6"` | Push gate: memories below this confidence are counted and rejected |
 
 ---
 
@@ -379,7 +503,7 @@ npm run typecheck   # tsc --noEmit (strict)
 npm run lint        # biome check .
 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)
+npm run replay      # replay report over tests/replay/fixtures
 ```
 
 ### Publishing (maintainer)
@@ -395,42 +519,64 @@ npm publish --access public
 
 ```
 plugin/
-  index.ts              # Entry point: KevinPlugin
-  Store.ts              # Wrapper SQLite (node:sqlite / bun:sqlite / better-sqlite3 fallback)
+  index.ts              # Entry point: KevinPlugin (wires hooks, tools, emissions)
+  Store.ts              # SQLite wrapper (node:sqlite / bun:sqlite / better-sqlite3 fallback)
+  sqlite-adapter.ts     # Runtime-agnostic SQLite adapter behind Store
   Migrate.ts            # Idempotent migrations + post-apply hooks
   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 + LLM enrich
-  CausalChain.ts        # v0.3.0 — links fixes to failures + promotes causal patterns
+  Reflector.ts          # Heuristic lessons + per-fingerprint throttle + LLM enrich (opt-in)
   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
+  Feedback.ts           # kevin_feedback: verdicts, confidence terms, ignored stamp
+  Archiver.ts           # Retires stale non-pattern memories past archive_after_days
+  CausalChain.ts        # Links fixes to failures + promotes causal patterns
+  QualityGate.ts        # Weak-lesson gate (stored, not injected by default)
+  InjectionLedger.ts    # Injection ledger + settle → precision_rate
+  LessonFixer.ts        # Deterministic fix_args capture + promotion enrichment
   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
+  Curator.ts            # Curation candidates + propose/approve lifecycle
+  ArtifactWriter.ts     # The SINGLE write path (markers, atomic, noop, audit rows)
+  Materializer.ts       # Pull-channel topic bundles (skills, refs)
+  inferability.ts       # Deterministic inferable/non-inferable/unknown classifier
+  capabilities.ts       # v2 domain probe (skills / references)
+  diff.ts               # Minimal unified diff for proposal review
+  replay.ts             # Hermetic replay driver over recorded transcripts
+  replay-types.ts       # Transcript/result types for the replay harness
+  kevin_propose.ts      # kevin_propose tool (strict dry run)
+  kevin_approve.ts      # kevin_approve tool (only writer call site)
+  kevin_publish.ts      # kevin_publish tool (bundle regeneration)
+  kevin_audit.ts        # Read-only audit + channels/curation blocks
+  kevin_why.ts          # kevin_why tool: failure→fix traces + related rules
+  okf-export.ts         # kevin_export: OKF/markdown export
+  okf-import.ts         # kevin_import: bundle parser + import
+  confidence.ts         # Two-sided computeConfidence (evidence + recurrence + feedback)
+  query-tokenizer.ts    # FTS5 tokenizer for query sanitization
   memory-format.ts      # escapeInjectedText, formatMemories, <protect> + id: line wrappers
   redact.ts             # redactPaths + stripPrivate
+  fingerprint.ts        # FNV-1a 64-bit (in-house, no node:crypto)
+  metrics.ts            # In-memory counters + debounced flush to kevin_metrics
   uuid.ts               # UUIDv7
 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}/
+  003_v02_signal.sql    # fingerprint, origin, metrics, dedup indexes
+  004_v03_knowledge.sql # evidence/status/supersede, error_fingerprint
+  005_v04_signal.sql    # recurrence_count, fix_args, last_injected_at
+  006_v05_glassbox.sql  # ignored/archived/superseded_by, feedback, metrics
+  007_v06_pull.sql      # curation_proposals, artifact_writes, curated/inferable
+tests/
+  unit/                 # component tests
+  integration/          # tool-level tests through real components
+  e2e/                  # closed-loop tests through the host hooks
+  replay/               # transcript fixtures + replay harness tests
 scripts/
   copy-migrations.mjs   # build step: copies *.sql to dist/migrations
   verify-install.ts     # npm run verify
 ```
 
 ---
+
 ## License
 
-MIT
+MIT