@jmtrin/opencode-kevin 1.2.0 → 1.3.0

package/README.md

@@ -1,605 +0,0 @@
-<div align="center">
-
-# ⚡ Kevin
-
-```
-╔══════════════════════════════════════════════╗
-║                                              ║
-║   ██╗  ██╗███████╗██╗   ██╗██╗███╗   ██╗     ║
-║   ██║ ██╔╝██╔════╝██║   ██║██║████╗  ██║     ║
-║   █████╔╝ █████╗  ██║   ██║██║██╔██╗ ██║     ║
-║   ██╔═██╗ ██╔══╝  ╚██╗ ██╔╝██║██║╚██╗██║     ║
-║   ██║  ██╗███████╗ ╚████╔╝ ██║██║ ╚████║     ║
-║   ╚═╝  ╚═╝╚══════╝  ╚═══╝  ╚═╝╚═╝  ╚═══╝     ║
-║                                              ║
-║        Local-First Memory for OpenCode       ║
-║                                              ║
-╚══════════════════════════════════════════════╝
-```
-
-### Local-first memory for OpenCode — it observes, learns, remembers and proves it.
-
-**Kevin watches. Kevin learns. Kevin remembers.**
-
-It turns every coding session into durable, confidence-scored knowledge,
-injects exactly what matters back into the model's context, curates the best
-of it into files you control, and shares it across a team through one
-git-friendly file — deterministically, locally, with zero network calls.
-
-![version](https://img.shields.io/badge/version-1.1.0-blue)
-![node](https://img.shields.io/badge/node-%E2%89%A522.5-green)
-![tests](https://img.shields.io/badge/tests-1380%20passing-brightgreen)
-![deps](https://img.shields.io/badge/runtime%20deps-1-orange)
-![network](https://img.shields.io/badge/network-zero-black)
-![license](https://img.shields.io/badge/license-MIT-lightgrey)
-
-</div>
-
-<!-- uncomment when docs/demo.gif lands
-![demo](docs/demo.gif)
--->
-
-> **AI agents are good at solving problems. Kevin makes sure they don't have to solve the same problem twice.**
-
----
-
-## 📖 Contents
-
-- [Why Kevin](#-why-kevin)
-- [The Kevin loop](#-the-kevin-loop)
-- [Quick start](#-quick-start)
-- [What's new in 1.1.0](#-whats-new-in-110)
-- [What's new in 1.0.0](#-whats-new-in-100)
-- [How it works](#-how-it-works)
-- [The 26 tools](#-the-26-tools)
-- [The benchmark: proven, not promised](#-the-benchmark-proven-not-promised)
-- [Curation: from session noise to AGENTS.md](#-curation-from-session-noise-to-agentsmd)
-- [Team sharing: one file, zero servers](#-team-sharing-one-file-zero-servers)
-- [The contract](#-the-contract)
-- [Hooks & latency budgets](#-hooks--latency-budgets)
-- [Configuration](#%EF%B8%8F-configuration)
-- [Supported runtimes](#-supported-runtimes)
-- [Design & trust](#-design--trust)
-- [Development](#-development)
-- [License](#-license)
-
----
-
-## 🤔 Why Kevin
-
-Every coding session produces experience — errors, fixes, decisions,
-conventions, lessons. Without memory, most of it evaporates when the context
-window closes: the next session starts near zero and walks straight into the
-same wall.
-
-Kevin closes that loop:
-
-| 🔍 Observe | 🧠 Learn | 🎯 Recall | ✍️ Curate | 👥 Share | 📏 Prove |
-|---|---|---|---|---|---|
-| Tool calls, chat messages, session signals | Failures become lessons, causal chains, patterns | Relevant knowledge ranked and injected inside a token budget | The best knowledge becomes human-approved `AGENTS.md` guidance | Curated knowledge travels through one git-friendly file | Latency and retrieval quality are measured, not assumed |
-
-**Local first, by design.** Your coding experience belongs to you:
-
-```
-no cloud service · no telemetry · no network calls · no hidden write path
-```
-
-Knowledge lives in a local SQLite database, is projected into files you
-control, and is shared — optionally — through a single file you can read,
-diff and review like code.
-
----
-
-## 🔁 The Kevin loop
-
-```
-        CODING SESSION
-              │
-              ▼
-       🔍 OBSERVE ────── tool calls, chat signals, failures
-              │
-              ▼
-        🧠 LEARN ─────── lessons, causal chains, patterns
-              │
-              ▼
-       💾 REMEMBER ───── confidence · provenance · recurrence
-              │
-              ▼
-        🎯 RECALL ────── rank → gates → token budget
-              │
-              ▼
-      MODEL CONTEXT ──── only what matters now
-              │
-              ▼
-       ✍️ CURATE ─────── propose → HUMAN review → approve
-              │
-              ▼
-         AGENTS.md
-              │
-              ▼
-        NEXT SESSION ─────────────────▶ 🔁
-```
-
-**Experience compounds instead of evaporating.**
-
----
-
-## 🚀 Quick start
-
-### 1. Declare the plugin
-
-```jsonc
-// opencode.json
-{
-  "plugin": ["@jmtrin/opencode-kevin"]
-}
-```
-
-```bash
-npm install @jmtrin/opencode-kevin
-```
-
-### 2. Restart OpenCode
-
-On first boot Kevin migrates its database to schema version `012` and starts
-observing. Nothing else is required.
-
-### 3. Talk to it
-
-```
-kevin_status    → is everything healthy?
-kevin_why       → why did this keep failing, and how was it fixed?
-kevin_query     → what does Kevin remember about X?
-kevin_doctor    → health report: hooks, deps, perf, verdict
-```
-
-### 4. Where data lives
-
-```
-~/.opencode-kevin/
-├── kevin.db            ← everything Kevin learns (SQLite, WAL)
-├── skills/             ← generated pull channels
-├── refs/               ← topic reference bundles
-└── tui/
-    ├── proposals.json  ← pending proposals projection (512 KiB cap)
-    ├── conflicts.json  ← open conflicts projection
-    ├── health.json     ← doctor+perf snapshot
-    ├── meta.json       ← {generatedAt, versions}
-    ├── dashboard.html  ← static review surface (file://, zero network)
-    ├── actions.json    ← mailbox queue (TUI panels → session.idle)
-    └── results.json    ← last action results (audit)
-
-<repo>/.kevin/
-├── AGENTS.md           ← curated knowledge (marker block, human-approved)
-└── knowledge.okf       ← optional team-sharing file (opt-in)
-```
-
----
-
-## 🆕 What's new in 1.1.0 — "Drift"
-
-> 1.1.0 protects what 1.0.0 proved: a published number without a regression gate is marketing.
-
-- 🛡️ **Continuous benchmark gate** — `npm run bench:regress` compares the last two `bench/results` against per-metric thresholds (`precision@k` >0.02, `recall` >0.05, `mrr` >0.05 on the `kevin` arm); CI fails when truth drifts.
-- 🗑️ **Lifecycle closure — `kevin_forget`** — dry-run default, `confirm:true` archives locally and publishes a tombstone through the single write path; second identical run is a `noop`.
-- ⏱️ **Millisecond timestamps** — new `_ms` columns with conservative backfill; `settle()` and `CausalChain` now decide sub-second causality.
-- 🧹 **Debt paid** — one `STOP_WORDS` source, one `readOriginCallId`, `ConflictDetector` via `mapRow`, one column-probe registry; every setting has an on-path test.
-- 📜 **Public hygiene** — `LICENSE` (MIT), `homepage` filled, `docs/DISTRIBUTION.md` checklist, `scripts/release-notes.mjs` for `gh release create`, and `<!-- demo -->` slot.
-
----
-
-## 🆕 What's new in 1.2.0 — "Surface"
-
-> 1.2.0 gives the human-in-the-loop a place to stand: every pending proposal is readable with its diff without opening an editor, and every approval rides the same gated handler.
-
-- 🖥️ **Three review surfaces, one projection** — TUI panels (`/kevin` route, `k` to open) where the host renders them, plus a static `dashboard.html` under `~/.opencode-kevin/tui/` that opens via `file://` with zero network, zero fetch, inline CSS/JS and embedded JSON.
-- 💬 **Chat-command bridge `/kevin-*` (universal, immediate)** — `/kevin-approve <id> <token>`, `/kevin-reject <id> <token> [note]`, `/kevin-ack <id>` execute through the existing `kevinApprove` / acknowledge handlers; valid commands are swallowed, invalid/stale ones pass through untouched to the model.
-- 📦 **Mailbox for TUI panels (idle-latency)** — proposals approved from the TUI write `~/.opencode-kevin/tui/actions.json`; the session consumes it at the next `session.idle` before `curator.propose`, then refreshes snapshots (`tui_snapshots_enabled='1'`).
-- ⏱️ **Latency honesty** — chat commands apply this turn; mailbox actions apply at next idle. Both disclosed in-surface (`queued — applies at session idle` toast, copy hint on dashboard).
-- 📦 **Packaging** — new export `opencode-kevin/tui` (`dist/plugin/tui.*`), `engines.opencode ^1.18.0` validated by the host with skip-with-warning.
-
-| Surface | Review | Action | Latency |
-|---|---|---|---|
-| TUI panel (`/kevin`) — CLI/TUI host | Proposals / Conflicts / Health tabs, diff dialog, truncation markers | `a` approve / `r` reject / `x` ack → mailbox | next idle |
-| Static dashboard (`dashboard.html`) | Proposals (+escaped diff `<pre>`), conflicts two-column, health banner | Copy `/kevin-*` button → paste into chat input | immediate (chat bridge) |
-| Any client (Desktop, CLI) | — | Type `/kevin-approve …` etc in chat input | immediate |
-
-Snapshots + dashboard are capped at 512 KiB (diff truncation with `truncated:true`), written atomically via `tmp`+`rename`, and read best-effort with empty-state explanations (`no snapshots yet — open an opencode session…`) when missing/corrupt/stale-token.
-
----
-
-## 🆕 What's new in 1.0.0
-
-> 1.0.0 is the **proven release**: the surface is frozen as data, the cost is
-> measured, the value is benchmarked — reproducibly.
-
-- ❄️ **A frozen public contract** — nine clauses (`C-01` … `C-09`) derived from
-  live source, digest-stamped, enforced by an append-only golden file.
-  Inspect it live with `kevin_contract`.
-- ⏱️ **Latency budgets** — eight instrumented scopes; `npm run bench:check`
-  fails if any scope exceeds its p95 budget. `dispose` joins as the seventh
-  hook with crash-safe deferred settlement.
-- 📊 **A reproducible benchmark** — committed synthetic corpus, four arms,
-  committed result. See [below](#-the-benchmark-proven-not-promised).
-- 🛡️ **An untrusted-input boundary** — everything reaching an artifact or
-  prompt is escaped at the single write path; stored text is never trusted.
-- 📦 **A corrected published package** — types-first exports, `dist/` only,
-  verified against the packed tarball by `npm run verify:pack`.
-
----
-
-## ⚙️ How it works
-
-Kevin is an intentionally deterministic pipeline — no LLM in the core loop:
-
-```
-     your coding session
-             │
-             ▼
-┌────────────────────────────────────────────┐
-│ 🔍 OBSERVE                                 │
-│ tool.execute.before/after · chat.message   │
-│ Failures auto-detected from exit codes,    │
-│ stderr and stdout markers.                 │
-└──────────────────┬─────────────────────────┘
-                   ▼
-┌────────────────────────────────────────────┐
-│ 🧠 LEARN                                   │
-│ Reflector    → lessons                     │
-│ CausalChain  → failure/fix links           │
-│ PatternMiner → repeated sequences          │
-│ Evidence raises confidence; recurrence     │
-│ lowers it and flags staleness.             │
-└──────────────────┬─────────────────────────┘
-                   ▼
-┌────────────────────────────────────────────┐
-│ 🎯 INJECT                                  │
-│ QualityGate → BM25 × origin × recency ×    │
-│ truth penalty → token-budget fit           │
-│ Deduped per session, inside <kevin-context>│
-└──────────────────┬─────────────────────────┘
-                   ▼
-┌────────────────────────────────────────────┐
-│ ✍️ CURATE                                  │
-│ propose → HUMAN REVIEW → approve           │
-│ Nothing writes without approval.           │
-└──────────────────┬─────────────────────────┘
-                   ▼
-┌────────────────────────────────────────────┐
-│ 📏 PROVE                                   │
-│ perf budgets · retrieval benchmark ·       │
-│ contract digest                            │
-│ The system measures itself instead of      │
-│ merely claiming to work.                   │
-└────────────────────────────────────────────┘
-```
-
----
-
-## 🧰 The 26 tools
-
-<details open>
-<summary><b>🧠 Core memory</b></summary>
-
-| Tool | What it does |
-|---|---|
-| `kevin_save` | Store a memory: decision, rule, pattern, context or solution |
-| `kevin_query` | Search memories — slim payload; `evidence: true` exposes confidence |
-| `kevin_get` | Fetch one memory in full |
-| `kevin_recall` | Ranked recall with origin-aware scoring |
-| `kevin_status` | Session scoreboard: counts, precision, metrics |
-| `kevin_config` | List/set any of the 31 settings — no SQL required |
-| `kevin_project` | Show, initialize or rekey the repository identity |
-
-</details>
-
-<details>
-<summary><b>🔎 Understanding & debugging</b></summary>
-
-| Tool | What it does |
-|---|---|
-| `kevin_why` | Failure→fix trace for a recurring error, with confidence and evidence |
-| `kevin_trace` | Dry-run: exactly what would be injected for a query, zero side effects |
-| `kevin_feedback` | Rate an injected memory `useful` / `wrong` / `outdated` / `ignore` |
-| `kevin_conflicts` | Surface contradictions between memories and repository truth |
-| `kevin_facts` | Scan the repository for ground-truth facts |
-| `kevin_retrospective` | Per-session markdown retrospective |
-
-</details>
-
-<details>
-<summary><b>✍️ Curation & publishing</b></summary>
-
-| Tool | What it does |
-|---|---|
-| `kevin_propose` | Dry-run curation proposals with unified diffs — writes nothing |
-| `kevin_approve` | The **only** path that writes `AGENTS.md` (or rejects) |
-| `kevin_publish` | Regenerate skill/ref pull bundles under `~/.opencode-kevin/` |
-
-</details>
-
-<details>
-<summary><b>👥 Team & operations</b></summary>
-
-| Tool | What it does |
-|---|---|
-| `kevin_share` | Promote curated memories into `.kevin/knowledge.okf` (approval-gated) |
-| `kevin_sync` | Import the shared file into the local layer |
-| `kevin_export` / `kevin_import` | Markdown/OKF bundles out and in |
-| `kevin_audit` | Whole-system report: memories, injections, channels, team, perf, contract |
-| `kevin_doctor` | Health verdict: `healthy` / `degraded` / `unknown`, with reasons |
-| `kevin_native` | Show/enable/disable native host registration (default off) |
-| `kevin_contract` | **v1.0.0** — inspect the frozen public surface at runtime |
-| `kevin_bench` | **v1.0.0** — report benchmark results; never runs them in-session |
-
-</details>
-
----
-
-## 📊 The benchmark: proven, not promised
-
-Kevin ships a committed synthetic corpus and a four-arm harness measuring
-whether real retrieval beats trivial baselines at surfacing labelled-relevant
-memories:
-
-```
-bench/corpus/
-seed:   1262835273   (xorshift32, byte-for-byte regenerable)
-digest: adecbdf4c7af82e2
-result: bench/results/2026-08-21-adecbdf4c7af82e2.json   (k = 5)
-```
-
-```
-npm run bench          # run the harness (also persists one row per arm)
-npm run bench:check    # gate: every perf scope within its p95 budget
-npm run verify:pack    # gate: seven properties against the packed tarball
-```
-
-| Arm | Precision@5 | Recall@5 | MRR |
-|---|---:|---:|---:|
-| `none` (control) | 0.000 | 0.000 | 0.000 |
-| `recent-k` (baseline) | 0.050 | 0.026 | 0.109 |
-| `random-k` (floor) | 0.048 | 0.028 | 0.093 |
-| **`kevin`** | **0.950** | **0.546** | **1.000** |
-
-```
-Precision@5                    Recall@5                MRR
-0.950  ██████████████████░░    0.546  ██████████░░░░   1.000  ████████████████████
-0.050  █░░░░░░░░░░░░░░░░░░░    0.026  █░░░░░░░░░░░░░   0.109  ██░░░░░░░░░░░░░░░░░░
-```
-
-The labelling rule is mechanical and the retrieval numbers are exactly
-reproducible — asserted by running the harness twice in-process.
-
-**Honest limits, stated up front.** This benchmark measures retrieval on a
-synthetic corpus built to have a ranked answer; it does **not** prove that real sessions look like this synthetic corpus. It does not prove that a surfaced memory changed what the model did. Retrieval quality is one layer of the agent loop, not the whole of it.
-
----
-
-## ✍️ Curation: from session noise to AGENTS.md
-
-Knowledge worth keeping becomes a proposal; a human decides; only then is it
-written — once, atomically, inside a marker pair you can edit around:
-
-```
-memories ──▶ kevin_propose ──▶ pending proposals (unified diffs, no writes)
-                                    │
-                              HUMAN REVIEW
-                                    │
-                    ┌── approve ────┴──── reject ──▶ decision recorded
-                    ▼                                nothing written
-AGENTS.md updated atomically  ◀── the single write path (D6-01)
-```
-
-```markdown
-<!-- kevin:begin — curated by opencode-kevin, safe to edit -->
-- Always run `npm run typecheck` before committing (fixed 3 CI failures)
-<!-- kevin:end -->
-```
-
-Deliberately conservative: only non-inferable memories are eligible — an
-LLM-recoverable diagnostic is not something a human should have to review into
-a permanent rule. Re-applying an unchanged plan is a counted noop, never a
-write. **Kevin can propose. Humans decide.**
-
----
-
-## 👥 Team sharing: one file, zero servers
-
-Opt-in via `shared_layer_enabled='1'`. Curated knowledge exports to one
-`.kevin/knowledge.okf` — header lines plus one JSON entry per line, sorted by a
-deterministic `entry_id`, LF-only, ≤4096 bytes per line — designed so git
-merges are meaningful and conflicts are parseable:
-
-```
-   DEV A                                DEV B
-     │ share (approval-gated)             │ git pull
-     ▼                                    ▼
-  knowledge.okf ◀═══════ git ══════▶ knowledge.okf
-                                          │ kevin_sync
-                                          ▼
-                        projected into local memories
-                        (layer='shared', immutable)
-```
-
-Repository identity resolves **once**, in order:
-`.kevin/project.json` (declared) → git remote hash (never a raw URL) → path.
-Two clones of the same repository are one team; different repositories never
-leak into each other. Sharing requires explicit approval
-(`share_requires_approval='1'`), author identity is hashed by default, and
-tombstones archive rather than delete.
-
----
-
-## 📜 The contract
-
-Kevin 1.x makes promises about its published surface **in writing**.
-[`docs/CONTRACT.md`](docs/CONTRACT.md) freezes nine clauses — `C-01` … `C-09` —
-from the `AGENTS.md` marker bytes to the database schema, each tagged `frozen`
-or `forward-only` and stamped with the release that incurred the obligation. A
-test diffs the live contract against an append-only golden file on every run:
-removals and silent changes fail loudly; additions must carry `since`.
-
-```jsonc
-// kevin_contract (excerpt)
-{
-  "contract_version": 1,
-  "digest": "1de9740bba2e9f95",
-  "clauses": [
-    { "id": "C-03", "title": "Tool names and argument shapes", "stability": "frozen", "since": "0.2.0" },
-    { "id": "C-07", "title": "Database schema", "stability": "forward-only", "since": "0.1.0" }
-  ]
-}
-```
-
-> 1.0.0 is not just a version number — it is where Kevin starts making explicit, testable promises about its surface.
-
----
-
-## ⏱️ Hooks & latency budgets
-
-Six host hooks plus Kevin's own `dispose` checkpoint — eight measured scopes,
-each with a declared p95/max budget enforced by `npm run bench:check`:
-
-| Scope | p95 budget | max |
-|---|---:|---:|
-| `tool.execute.before` | 2 ms | 10 ms |
-| `tool.execute.after` | 5 ms | 25 ms |
-| `chat.message` | 2 ms | 10 ms |
-| `chat.system.transform` | 15 ms | 50 ms |
-| `session.compacting` | 15 ms | 50 ms |
-| `event` | 5 ms | 25 ms |
-| `session.idle` | 150 ms | 600 ms |
-| `dispose` | 50 ms | 250 ms |
-
-Measured on the reference laptop: retrieval p50 ≈ 0.2 ms, p95 < 1 ms — orders
-of magnitude under budget. Samples persist to `perf_samples` at idle; a breach
-degrades `kevin_doctor`'s verdict, because a plugin that is technically alive
-but consistently slow is not healthy.
-
----
-
-## ⚙️ Configuration
-
-Everything is a TEXT setting managed through `kevin_config` (or any SQLite
-client). All values are TEXT — flags compare with `=== "1"`, never truthiness.
-
-| Key | Default | Purpose |
-|---|---|---|
-| `quality_gate_enabled` | `'1'` | Weak lessons stored but never injected |
-| `lesson_snippet_injection` | `'1'` | Compact 2-line snippets instead of full bodies |
-| `patternminer_enabled` | `'0'` | Deterministic tool-sequence mining (≥5 sessions) |
-| `cross_project_enabled` | `'0'` | Include imported cross-project rows |
-| `llm_reflection_enabled` | `'0'` | Opt-in LLM enrichment at pattern promotion |
-| `tool_calls_dedup_enabled` | `'0'` | Suppress duplicate call recordings per minute bucket |
-| `deterministic_retrieval` | `'0'` | Freeze the clock for hermetic tests/replay |
-| `pre_prompt_budget_tokens` | `'400'` | Pre-prompt injection cap (clamped `[0, 4000]`) |
-| `archive_after_days` | `'30'` | Age threshold for idle archival |
-| `curation_enabled` | `'1'` | Idle dry-run proposal generation |
-| `agents_md_path` | `'AGENTS.md'` | Where curated knowledge lands |
-| `skill_emission_enabled` | `'0'` | Register project-knowledge skill on v2 hosts |
-| `reference_emission_enabled` | `'0'` | Register `@kevin/<topic>` mentions |
-| `injection_confidence_floor` | `'0.6'` | Memories below this never inject |
-| `repo_truth_enabled` | `'0'` | Repository fact scanning |
-| `convention_mining_enabled` | `'0'` | Deterministic convention mining |
-| `conflict_detection_enabled` | `'0'` | Contradiction surfacing |
-| `error_lesson_mode` | `'all'` | Error lesson injection mode |
-| `shared_layer_enabled` | `'0'` | Team sharing via `.kevin/knowledge.okf` |
-| `okf_path` | `'.kevin/knowledge.okf'` | Shared file location |
-| `share_requires_approval` | `'1'` | No export without human confirmation |
-| `author_identity_mode` | `'hashed'` | Author identity hashed, never raw email |
-| `shared_confidence_floor` | `'0.7'` | Confidence floor for shared projections |
-| `hook_liveness_enabled` | `'1'` | Per-hook liveness tracking |
-| `native_registration_enabled` | `'0'` | v2 native skill/reference registration |
-| `host_probe_history_enabled` | `'0'` | Append-only probe history |
-| `dead_hook_report_threshold` | `'3'` | Consecutive misses before a hook reads dead |
-| `perf_enabled` | `'1'` | Latency instrumentation |
-| `perf_ring_capacity` | `'512'` | Samples per scope (clamped `[64, 8192]`) |
-| `perf_flush_on_idle` | `'1'` | Persist samples at idle |
-| `contract_report_enabled` | `'1'` | Contract block in `kevin_audit` |
-| `tui_snapshots_enabled` | `'1'` | Snapshot + dashboard flush at idle (opencode-kevin/tui) |
-
----
-
-## 🖥️ Supported runtimes
-
-| Runtime | SQLite backend | Status |
-|---|---|---|
-| Node 24.x | `node:sqlite` (stable) | ✅ **Supported** — the reference row |
-| Node 22.5+ | `better-sqlite3` (optional dep) | ⚠️ **Supported with a caveat** — needs a build toolchain; without one there is no backend (and npm install still succeeds silently) |
-| Node 22.5+ | `node:sqlite` behind `--experimental-sqlite` | 🔶 Works, unsupported — exercised in CI, not promised |
-| Bun ≥ 1.1 | `bun:sqlite` | ✅ **Supported** — smoke-tested in `npm run verify` |
-
-Zero process spawns, zero network calls — asserted by source scan on every
-test run.
-
----
-
-## 🎨 Design & trust
-
-**Principles.** Local first · deterministic by default (no LLM in the core
-loop) · evidence over vibes (every memory carries evidence, provenance,
-recurrence and confidence) · signal over noise (inject *less, better* context,
-not more) · humans hold the write boundary · git-friendly collaboration ·
-important claims become executable checks.
-
-**Security model.** Stored knowledge is treated as untrusted input: anything
-reaching an artifact or prompt passes through idempotent escaping at the
-single write path; permanent project-file changes require explicit human
-approval; author identity in the shared layer is hashed
-(`author_identity_mode='hashed'`). No network service is required to store,
-retrieve or share knowledge.
-
-**Without memory vs with Kevin:**
-
-```
-without:  session 1 solve ─▶ context closes ─▶ session 2 same problem ─▶ solve again
-
-with:     session 1 solve ─▶ lesson ─▶ memory ─┐
-          session 2 problem ◀── recall ◀───────┘ ─▶ fix ─▶ evidence ↑
-```
-
-**Why not just `AGENTS.md`?** It is excellent for durable, human-authored
-guidance — Kevin treats it as a curated destination, not as a memory system.
-It cannot do failure/fix traces, confidence scoring, evidence tracking, ranked
-retrieval, recurrence signals, dry-run injection inspection, automatic
-proposal generation, team projections, or performance and contract
-instrumentation. That is what Kevin adds around it.
-
----
-
-## 🛠️ Development
-
-```bash
-npm install
-npm run typecheck     # tsc --noEmit (strict)
-npm run lint          # biome
-npm test              # vitest — 1374 tests across 190 files
-npm run verify        # install checks + Bun smoke + verify:pack
-npm run gen:corpus    # regenerate the seeded corpus (byte-identical)
-npm run replay        # replay recorded sessions deterministically
-```
-
-Project layout:
-
-```
-plugin/      53 modules — Store, MemoryService, Reflector, Perf, Contract, columns, kevin_forget …
-migrations/  001 → 012 — additive, idempotent, forward-only forever
-scripts/     bench · gen-corpus · verify-pack · verify-install · …
-tests/       unit · integration · e2e · replay fixtures
-bench/       committed corpus + committed results
-docs/        CONTRACT.md · per-release plans/tasks · roadmap
-```
-
----
-
-## 📄 License
-
-MIT — see the package manifest. Kevin is built by [jmtrin](https://github.com/jmtrin);
-bug reports and PRs welcome at the [issue tracker](https://github.com/jmtrin/opencode-kevin/issues).
-
-<div align="center">
-
-### ⚡ Kevin — *Observe. Learn. Remember. Improve.*
-
-</div>