knit-mcp 0.11.4 → 0.16.0

package/README.md

@@ -3,50 +3,80 @@
   <a href="https://github.com/PDgit12/knit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/PDgit12/knit/ci.yml?style=for-the-badge&label=CI&color=10b981" alt="CI" /></a>
   <img src="https://img.shields.io/badge/license-MIT-3b82f6?style=for-the-badge" alt="license" />
   <img src="https://img.shields.io/badge/node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/tests-665%20passing-22c55e?style=for-the-badge" alt="tests" />
-  <img src="https://img.shields.io/badge/MCP%20tools-53-7c3aed?style=for-the-badge" alt="tools" />
+  <img src="https://img.shields.io/badge/MCP%20tools-55-7c3aed?style=for-the-badge" alt="tools" />
+  <img src="https://img.shields.io/badge/agents-6-10b981?style=for-the-badge" alt="agents supported" />
+  <img src="https://img.shields.io/badge/local--first-100%25-3b82f6?style=for-the-badge" alt="local-first" />
 </p>
 
 <h1 align="center">🧶 knit</h1>
 
 <p align="center">
-  <strong>An intelligent command layer for Claude Code.</strong><br/>
-  Project-scoped memory · on-demand workflow · parallel team worktrees · honest token accounting.<br/>
-  <em>All in one MCP server.</em>
+  <strong>Universal MCP brain for agentic coding platforms.</strong><br/>
+  Project-scoped memory · on-demand workflow · parallel team worktrees · live analytics dashboard.<br/>
+  <em>Works with Claude Code, Cursor, Codex CLI, Cline, Continue, and GitHub Copilot (via VS Code Agent mode) — anything that speaks MCP.</em>
 </p>
 
 <p align="center">
   <a href="#-quick-start">Quick start</a> ·
   <a href="#-what-knit-is">What it is</a> ·
-  <a href="#-whats-new-in-v0110">v0.11</a> ·
-  <a href="#-52-mcp-tools">Tools</a> ·
-  <a href="#-how-its-different">Comparison</a> ·
-  <a href="#-honest-comparison-vs-memory-libraries">vs mem0/Letta</a>
+  <a href="#-how-search-works">How search works</a> ·
+  <a href="#-55-mcp-tools">Tools</a> ·
+  <a href="#-the-dashboard">Dashboard</a> ·
+  <a href="#-how-its-different">vs mem0/Letta</a>
 </p>
 
 ---
 
 ## 🧠 What knit is
 
-Knit makes Claude Code do the right thing automatically — because you can't predict how a user will phrase a request. It does three jobs at once:
+Knit gives **any MCP-speaking coding agent** the right defaults automatically — because you can't predict how a user will phrase a request, and every agent (Claude Code, Cursor, Codex CLI, Cline, Continue, GitHub Copilot) ends up burning tokens re-discovering the same project facts. Knit does four jobs at once:
 
 | | |
 |---|---|
-| 🧠 **Memory** | Every project keeps a brain at `~/.knit/projects/<hash>/`. Sessions compound: learnings, false positives, session summaries, and a static-analysis import graph are all queryable next session. |
-| 🪶 **Tokens** | `CLAUDE.md` is ~2 KB (project facts only). Protocol depth is fetched on demand via `knit_get_workflow(phase)`. Knit is **net-negative** on context cost. |
+| 🧠 **Memory** | Every project keeps a brain at `~/.knit/projects/<hash>/`. Sessions compound: learnings, false positives, session summaries, and a static-analysis import graph are all queryable next session. Cross-project pool at `~/.knit/global/`. |
+| 🪶 **Tokens** | `CLAUDE.md` is ~2 KB (project facts only). Protocol depth is fetched on demand via `knit_get_workflow(phase)`. Per-cache-hit savings ≈ 15K tokens (calibrated from instrumented RESEARCH phases — override via env). Reuse-ratio + ROI surfaced in the dashboard. |
 | 🛠️ **Workflow** | A 4-tier classification (Inquiry / Trivial / Standard / Complex) with phase-triggered plan mode, quality-gated `LEARN`, and team-scoped git worktrees so parallel agents don't step on each other. |
+| 📊 **Dashboard** | New in v0.13. `knit ui` opens a local-first analytics dashboard at `http://127.0.0.1:7421` — bento layout, brain savings, per-project ROI, **force-directed brain graph**, real-time sync via SSE. See [Dashboard](#-the-dashboard). |
 
-It's a **single product**, not three. Every design choice has to win on memory + tokens + workflow together.
+**Local-first** invariant: zero cloud calls in memory/retrieval/classification. Dashboard binds to `127.0.0.1` only, with Host/Origin validation + CSP headers. Your brain stays on your machine.
+
+It's a **single product**, not four. Every design choice has to win on memory + tokens + workflow + analytics together.
 
 ---
 
 ## 🚀 Quick start
 
 ```bash
-npx knit-mcp@latest setup
+npm install -g knit-mcp
+knit setup       # adds Knit MCP to your agent's config (Claude Code / Cursor / Codex / etc.)
+knit ui          # opens the brain dashboard at http://127.0.0.1:7421 (optional but recommended)
 ```
 
-Adds the Knit MCP server to your Claude Code config (`~/.claude.json`). **No per-project setup.** Open Claude Code in any project — the first MCP tool call auto-initializes the brain, hooks, and per-project CLAUDE.md block.
+**No per-project setup.** Open your MCP-speaking agent in any project — the first MCP tool call auto-initializes the brain, hooks, and per-project CLAUDE.md block.
+
+### Adoption per agent
+
+v0.14: a single `knit setup` detects **every** installed MCP-speaking agent on
+your machine and writes Knit's config into each one's native format. No
+per-agent manual setup, no copy-pasted JSON.
+
+| Agent | Auto-detected by `knit setup` | Config format written | Hook support |
+|---|---|---|---|
+| Claude Code | ✅ `~/.claude.json` | JSON · `mcpServers` | ✅ PreToolUse / PostToolUse / Stop |
+| Cursor | ✅ `.cursor/mcp.json` | JSON · `mcpServers` | ⚠️ approval flow only |
+| Codex CLI | ✅ `~/.codex/config.toml` | **TOML** · `[mcp_servers.knit-brain]` | ⚠️ approval flow only |
+| Cline | ✅ `~/.cline/mcp.json` + `AGENTS.md` | JSON · `mcpServers` | ⚠️ approval flow only |
+| Continue | ✅ `.continue/mcpServers/knit-brain.yaml` | **YAML** per-server | ⚠️ approval flow only |
+| GitHub Copilot (VS Code Agent mode) | ✅ `.vscode/mcp.json` | JSON · `servers` (unique key) | ⚠️ approval flow only |
+| Any other MCP client | ✅ stdio works universally | per the client's docs | varies |
+
+> **"Hook support" caveat:** only Claude Code has lifecycle hooks (PreToolUse /
+> PostToolUse / Stop). For the other 5 agents Knit enforces the protocol via
+> the MCP `instructions` field (handshake primer) + **server-side soft-gates**
+> in tool responses — same effect as hooks, transport-layer instead of host-layer.
+> Opt into block-strictness enforcement with `knit_set_protocol_strictness({level: 'block'})`.
+
+> **Supported shells:** macOS, Linux, WSL, Git Bash, PowerShell. Windows `cmd.exe` is not supported as the hook-runner shell — use PowerShell (default in modern Windows Terminal) or Git Bash.
 
 > **Supported shells:** macOS, Linux, WSL, Git Bash, PowerShell. Windows `cmd.exe` is not supported as the hook-runner shell — use PowerShell (default in modern Windows Terminal) or Git Bash.
 
@@ -73,32 +103,207 @@ Knit writes nowhere else on your machine.
 
 ---
 
-## ✨ What's new in v0.9.0
+## 🔍 How search works
+
+Knit's retrieval is **BM25 + Reciprocal Rank Fusion** over your learnings,
+session summaries, and the cross-project pool, with two cheap-but-honest
+lexical-bridging layers stacked on top: **2-gram fallback** for typos and
+rare compounds, and **curated coding-domain synonym expansion** for the
+most common semantic-gap pairs. No vector embeddings, no remote inference,
+no API calls.
+
+**Why this design choice (not an oversight):**
+
+- **Deterministic.** Same query → same ranking, every time. No model
+  drift, no upgrade-day surprises.
+- **Fast.** Sub-millisecond on corpora ≤ 1K entries (your typical
+  project memory). No cold start, no model load.
+- **Local-first.** Zero network calls. Your memory never leaves the
+  machine.
+- **Auditable.** You can explain every hit by looking at term overlap
+  + the synonym dictionary (50 pairs, hand-curated). No "the model
+  said so."
+- **Honest at the boundary.** The bench has documented misses where
+  even synonym expansion can't bridge the gap — we ship those visible,
+  not hidden.
+
+**What it does well.** Exact term match, identifier search
+(`knit_classify_task`), rare-term emphasis (e.g. `PIPE_BUF`), multi-word
+ranking, tag filtering, cross-project diversification (max 2 per
+project), branch diversification on sessions (max 2 per branch). **Typo
+recovery via 2-gram fallback** (`knit_clasify` → `knit_classify_task`).
+**Synonym recovery via curated dictionary** (`hook` ↔ `webhook`,
+`schema` ↔ `migration`, `auth` ↔ `authentication`, `cache` ↔ `memo`,
+`deploy` ↔ `ship` ↔ `release`, etc. — see
+[`src/engine/retrieval/synonyms.ts`](src/engine/retrieval/synonyms.ts)
+for the full ~50-pair dictionary). Synonym matches scored at 0.4× of a
+direct BM25 hit so genuine matches always rank higher.
+
+**What it still cannot do.** Multi-word paraphrase ("how do schema
+changes ship" with no shared terms). Deep abstraction-level bridging
+("data consistency" → "atomic temp+rename"). Question intent
+("what's the right pattern for X"). Negation. Cross-entry synthesis
+("based on the auth lessons, what should I do for OAuth"). These need
+either embeddings (model dependency + bundle weight, breaks local-first
+unless run locally via ONNX) or an LLM call layer (Knit-as-retrieval
+becomes Knit-as-agent, different identity). v0.20+ candidate: hybrid
+retrieval (BM25 + local embeddings via RRF) — opt-in, bench-gated.
+
+**The practical implication.** Search with words close to how you
+recorded the learning, OR words that have a synonym pair in the
+dictionary. If you write a learning about *webhook signatures*, you
+can now search either *webhook signatures* OR *hook signatures* —
+the dictionary bridges those. For genuinely different vocabulary that
+isn't in the synonym table, use `knit_search_global_learnings` to widen
+the corpus, or call `knit_search_sessions` to pull from past narrative
+summaries that may use more terms.
+
+**Bench numbers (v0.16):** synthetic 88.0% top-1 / **100% recall@5**,
+learnings (real-prose) 86.7% top-1 / 96.7% recall@5. Both default ON;
+opt-out via `enableNgramFallback: false` + `enableSynonyms: false` for
+a strict lexical-only baseline.
 
-v0.9 closes the **enforcement story** — every honest limit from the v0.8 architecture got a structural fix.
+---
 
-### Anti-hallucination
+## ✨ What's new in v0.15.0
+
+v0.15 is the **deep-clean release**. A second six-dimension internal audit
+graded the post-v0.14.1 codebase and surfaced the deferred items — defense-
+in-depth, retrieval honesty, UX parity, the trailing TODO debt. A single
+audit-cleanup branch closed them all, then six parallel agents re-graded
+the post-fix code to confirm nothing new slipped in.
+
+- **Security defense-in-depth.** Every `git` invocation in `worktrees.ts`
+  migrated to `execFileSync` with array args (no shell). Agent fetcher
+  cache writes are SHA256-verified via sidecars; tampered caches force
+  a fresh fetch with stderr alert; pre-v0.15 caches backfilled on first
+  read. `qs` CVE (GHSA-q8mj-m7cp-5q26) pinned via npm `overrides` —
+  `npm audit` now reports 0 vulnerabilities.
+- **Brain mechanics.** New `pruneLearningsByAge` parallels the sessions
+  pattern (atomic rewrite, conservatively preserves unparseable dates +
+  `#false-positive` entries). `readLearnings` schema-validates on read.
+  Opt-in BM25 2-gram fallback (`enableNgramFallback`, default off)
+  rescues typo-only queries without disturbing benchmarks.
+- **Retrieval honesty.** New `bench:learnings` regression bench against
+  30 real-learning-shape narrative entries — gates at top-1 ≥ 75% /
+  recall@5 ≥ 90% (currently 83.3% / 96.7%). Compounding-metrics response
+  now surfaces token-saved methodology with env-var overrides.
+- **UX & instructions.** Webapp DoctorView shows per-agent rows (parity
+  with CLI `knit doctor`). Workflow `EXECUTE` + `REVIEW` phases now embed
+  `knit_suggest_command` hooks so the agent defers to user slash-commands
+  for test/lint/ship/qa/review. `buildUpdateNotice` surfaces npm-update
+  banner in the MCP instructions field — Cursor/Codex/Cline/Continue/
+  Copilot users now see updates at handshake.
+
+## ✨ What's new in v0.14.0
+
+v0.14 is the **universality release**. Three coordinated shifts: every
+MCP-speaking agent works out of the box, Knit composes with the slash
+commands you already wrote, and enforcement works across all agents
+(not just Claude Code).
+
+### 🌍 Six agents, one install
+
+`knit setup` now detects every installed MCP-speaking agent and writes Knit's
+config into each one's native format — JSON for Claude Code / Cursor / Cline /
+VS Code (note: `servers` not `mcpServers` for VS Code), TOML for Codex CLI,
+YAML for Continue. If Codex CLI or Cline is detected, a marker-wrapped
+`AGENTS.md` is also written at project root (the cross-agent rules convention).
+`knit doctor` now reports per-agent registration status, so you can see
+which of your agents are wired up at a glance.
+
+### 🔧 Cross-platform protocol enforcement
+
+Only Claude Code has hook lifecycles (PreToolUse / PostToolUse / Stop). For
+the other 5 agents, v0.14 adds **server-side soft-gates** in MCP tool
+responses. When strictness is set to `block`, protocol-critical handlers
+return `{ status: 'protocol_required', next_action: '...' }` instead of
+proceeding — the agent reads the response, follows the breadcrumb, retries.
+This is the universality answer: same enforcement, transport layer instead
+of host layer. Default strictness stays `warn` so existing flows are unchanged.
+
+### ⚡ Agent-native slash-command auto-detection
+
+Two new Tier-1 MCP tools:
+
+- `knit_scan_agent_commands` — scans `.claude/commands/`, `.cursor/rules/`,
+  `.clinerules/`, `~/.codex/prompts/`, `~/.continue/prompts/`, `.github/prompts/`
+  and surfaces every user-defined slash command + its description.
+- `knit_suggest_command({phase})` — given a protocol phase (test/lint/review/
+  ship), returns matching commands so the agent can invoke `/test` (or
+  whatever you wrote) via the host's native slash mechanism, instead of
+  describing the work in prose.
+
+Cached at `~/.knit/projects/<hash>/agent-commands.json` with a 1-hour TTL
+(~10ms re-scan when stale). Read-only filesystem ops; Knit never executes
+commands — the host agent invokes via its own mechanism.
+
+Dashboard exposes the scan results at **`#/commands`** with searchable
+per-agent listing.
+
+### 🛡️ Audit + hardening before publish
+
+v0.14 included a deep-dive internal audit of every dashboard
+endpoint, MCP handler, fs.watch race condition, and supply-chain dep. Five
+inline fixes landed in commit `e4e1793`:
+- `fs.watch` error handler now resets `watcher = null` so SSE recovers
+  cleanly after a watcher death (pre-fix, real-time sync silently stopped
+  until `knit ui` restart).
+- JSON + SSE responses gained `X-Content-Type-Options: nosniff`,
+  `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` (pre-fix only on
+  HTML).
+- `handleDefineTeam` + `handlePostTeamFindings` now call `redactSecrets` on
+  user-supplied team metadata + finding descriptions (pre-fix: raw write to
+  disk). 9 of 9 write handlers now redact uniformly.
+
+CBSE-style attack class verified PASS on every dashboard endpoint:
+Host-validation + Origin-validation + read-only contract + same-origin CSP
++ hex-only project-id regex. No malicious-page-can-read-your-brain vector.
+
+## ✨ What's new in v0.13.0
+
+v0.13 ships the **dashboard** — the visual surface on top of the brain. Plus security hardening and the universal positioning (works with every MCP-speaking agent).
+
+### 📊 Brain dashboard (`knit ui`)
+
+A single command opens a local-first analytics surface at `http://127.0.0.1:7421` — bento layout inspired by modern fintech dashboards, color-blocked cards, generous spacing, real-time sync.
+
+| View | What it shows |
+|---|---|
+| **Brain** (`#/`) | Hero card with net tokens saved across all projects, recent activity feed (live), memory hit-rate arc, top projects by ROI |
+| **Graph** (`#/graph`) | Project picker → **force-directed brain graph**: every learning is a node, edges by Jaccard similarity over shared tags + domains. Click any node for the full lesson. Threshold slider. |
+| **Cross-project** (`#/global`) | Cross-project learnings pool, filterable by source project |
+| **Per-project** (`#/p/:id`) | Searchable learnings list, retrieval signals, ROI deep dive (`#/p/:id/metrics`), graph (`#/p/:id/graph`) |
+| **Health** (`#/doctor`) | Install diagnostics: ~/.knit writable, MCP registered, version current |
 
-- 📎 **Citation rule in the MCP `instructions` field.** Every session's system prompt now tells the agent: *"when you state a fact about this codebase, cite the Knit tool result that verified it — e.g. (per `knit_query_imports`). If you can't cite, say 'unverified' explicitly."* Makes hallucinations visible at the **claim level**.
-- 🔍 **`knit_verify_claim` tool.** Single-call fact-check against the knowledge graph. Parses *"A imports B"*, *"X exports Y"*, *"A is tested by B"*, *"X exists"* and returns `verified | contradicted | unparseable` with evidence.
+**Real-time sync via SSE.** The server watches `~/.knit/` via `fs.watch`; any agent recording a learning anywhere updates the open dashboard within ~250ms. No polling.
 
-### Smarter retrieval
+### 🔐 Security hardening (real, not theater)
 
-- ⚡ **Auto-search inside `knit_classify_task`.** For `standard` / `complex` tier, classify now runs BM25 over (description + affected domains) automatically and embeds top-3 hits as `pre_emptive_learnings`. Closes the *"agent skipped `knit_search_learnings` before re-investigating"* gap with **zero extra calls**.
-- 📚 **`suggested_reads` from `knit_build_context`.** Curated list of files worth opening *before* editing — three signals: graph-importers (blast radius), graph-imports (likely needed), memory-mentions (files referenced by past learnings). Each entry carries `{ path, reason, via }`.
-- 🪜 **`knit_get_learning` — hierarchical retrieval.** Search returns headlines (summary + tags); the agent expands a specific learning by id only when needed. **Pay-per-detail.**
-- 🧮 **`knit_consolidate_learnings`.** Tag-Jaccard clustering of similar learnings → one pattern entry per cluster. Dry-run by default; `commit=true` persists with originals tagged `#consolidated` (preserved but deprioritized).
+The dashboard is a localhost HTTP server, which has real attack surface. v0.13 closes it:
 
-### Hook-level enforcement (`HOOKS_VERSION` 6 → 7)
+- **Host-header validation** — rejects requests whose `Host` isn't `127.0.0.1`/`localhost`. Blocks **DNS rebinding** (a malicious site you visit could resolve `evil.com` to 127.0.0.1 and trick your browser into reading the dashboard).
+- **Origin-header validation** — cross-origin requests get `403`. Same defense pattern as PostgreSQL, Redis, Docker daemon, the React dev server.
+- **Content-Security-Policy** on every HTML response — same-origin scripts only, no `'unsafe-eval'`, no external sources.
+- **X-Frame-Options: DENY**, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer.
+- **No mutation endpoints** in v0.13 (read-only dashboard). Setup wizard / refresh button stay deferred until proper CSRF protection lands.
 
-| Hook | What it does |
-|---|---|
-| **PreToolUse search-gate** | For `standard`/`complex` tasks, blocks Edit/Write (in `block` mode) or warns (default `warn`) when `knit_search_learnings` hasn't fired in the current turn. |
-| **PreToolUse content inspection** | Reads proposed Edit/Write content, parses local imports, warns on relative paths that don't resolve on disk — **catches hallucinated imports before they land**. |
-| **PostToolUse import validation** | After the file lands, re-parses imports and warns about unresolved relative paths — catches anything that slipped past the pre-check. |
-| **Stop-hook budget watch** | Cheap CLAUDE.md size check at session end; warns if it crosses the 12.5 KB over-budget threshold. Drift becomes visible even when the agent doesn't call `knit_brain_status`. |
+### 🌍 Universal positioning
+
+Knit is an MCP server. Anything that speaks MCP works:
+
+- **Claude Code** — handshake via stdio, `instructions` field carries protocol primer
+- **Cursor** — register knit MCP server in settings
+- **Codex CLI** — `~/.codex/config.toml` mcpServers section
+- **Cline / Continue** — both speak MCP, same setup
+
+The dashboard works regardless of which agent you use — it reads the brain from disk.
 
-> **Upgrade note.** After `npx knit-mcp@latest setup`, **restart Claude Code**. The `instructions` field and tier-gated `tools/list` only flow into the system prompt at handshake. The `HOOKS_VERSION` bump auto-regenerates installed hooks on the next brain load — no manual `knit refresh` needed.
+### 🪙 Token-economy lever
+
+`knit ui` notifies you when a new `knit-mcp` is available on npm — polls the registry every 5 minutes server-side, banner pops in the dashboard with the one-line `npm install -g knit-mcp@latest` command. No stale installs.
+
+> **Upgrade note.** After `npm install -g knit-mcp@latest`, **restart your agent**. The `instructions` field flows into the system prompt at handshake. The `HOOKS_VERSION` bump auto-regenerates installed hooks on the next brain load — no manual `knit refresh` needed.
 
 ---
 
@@ -115,7 +320,47 @@ Each surface gets a `healthy | warn | over-budget` verdict from `knit_brain_stat
 
 ---
 
-## 🛠️ 43 MCP Tools
+## 📊 The dashboard
+
+Run `knit ui` to open the local analytics surface. **Single command**, no other CLI needed for normal operation:
+
+```bash
+knit ui
+# Knit Dashboard — http://127.0.0.1:7421
+# Reading from: /Users/<you>/.knit
+# Press Ctrl-C to stop.
+# (automatically opens your default browser)
+```
+
+| Feature | What you see |
+|---|---|
+| **Bento home** | Big "Net tokens saved" hero card (dark), live recent activity (green "live" dot when SSE connected), memory hit-rate gauge, top projects by ROI as color-blocked cards |
+| **Brain graph** | Force-directed visualization of one project's learnings. Nodes sized by access count, colored by domain. Edges by Jaccard similarity over tags + domains. Click any node → side panel with the full lesson. Threshold slider live-recomputes the graph. |
+| **Per-project deep dive** | Hero card with verdict tone (cold/warming/compounding/strong), retrieval signals, classifications-by-tier breakdown, top domains heatmap, searchable learnings list |
+| **Health** | Install diagnostics — Node version, Knit version, ~/.knit permissions, MCP registration in `~/.claude.json` |
+
+**API endpoints** (all read-only, all 127.0.0.1 only):
+
+- `GET /api/version` — runtime version + update check + security metadata
+- `GET /api/brain/summary` — global counts
+- `GET /api/brain/aggregate` — cross-project ROI totals
+- `GET /api/projects` — project list
+- `GET /api/projects/:id/learnings` — full learning entries
+- `GET /api/projects/:id/metrics` — compounding ROI for one project
+- `GET /api/projects/:id/graph` — force-directed node + edge data (Jaccard threshold tunable)
+- `GET /api/global/learnings` — cross-project pool
+- `GET /api/doctor` — install diagnostics
+- `GET /api/events` — Server-Sent Events stream for real-time sync
+
+---
+
+## 🛠️ 55 MCP Tools
+
+> **49 active by default** at first handshake. The remaining 6 are tier-gated:
+> teams (9 tools, auto-on when ≥3 domains detected), subagents (1 tool, auto-on
+> when `.claude/agents/` exists), and admin (3 tools, opt-in via
+> `knit_enable_feature("admin")`). Call `knit_list_features` to see what's
+> available and how to enable.
 
 <details open>
 <summary><strong>🕸️ Knowledge graph</strong> <em>(Tier 1, ~5ms)</em></summary>
@@ -452,6 +697,7 @@ LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). U
 
 | Version | Headline |
 |---|---|
+| **v0.12.0** | **Picture Perfect: Structural Enforcement.** Diagnostic → enforcing. Budget verdict surfaces in the MCP `instructions` field at handshake (before any tool description is read). `knit_load_session` carries `budget_health` + `learnings_health` nudges. `engram doctor` exits non-zero on over-budget; `engram setup` runs doctor as final step. New PostToolUse hook warns immediately on over-budget CLAUDE.md edits (HOOKS_VERSION 11→12; auto-rolls to existing users). This repo dogfoods: hand-curated 16KB CLAUDE.md migrated to lean 3.8KB plus an internal long-form sidecar. New `npm run bench:tokens` measures real MCP-on vs MCP-off cost: 93% smaller per-recall call, 50% smaller per-classify, payback at 3 recall calls. 53 tools, 705 tests. |
 | **v0.11.4** | Dogfood audit · ran a full audit of Knit's own codebase using its own `knit_spawn_team_worktree` primitive (4 parallel teams: Core Logic, Infrastructure, UI, Quality Assurance). Fixes: HIGH `engram refresh` no longer clobbers user-curated CLAUDE.md (now uses `spliceKnitBlock` like `cache.ts`); `saveSource`/`loadSource` validate `sourceId`; `appendGlobalLearning` propagates write failures; `redactSecrets` applied to `label`/`tags`/`domains` across all persistence boundaries; 100KB response ceiling on `knit_generate_test_cases`; full v0.11 tool surface now documented in `workflow-protocol.ts` generator (was frozen at the v0.4 surface). Plus: 16 key tools reclassified with `[PROTOCOL]`/`[REVIEW]`/`[MEMORY]`/`[GRAPH]` prefixes so the LLM picks the right tool reliably. 53 tools, 687 tests. |
 | **v0.11.3** | Propagation patch · `update_available` flag now surfaces in `knit_load_session` response (≈100% session reach vs. brain_status' low reach) + startup stderr nag on stale versions. Helps FUTURE upgrades land faster; doesn't retroactively reach v0.10.x users. 53 tools, 665 tests. |
 | **v0.11.2** | Pre-publish polish · chunk cap (2000) + `errorResponse` envelope across handlers + CLAUDE.md generator surfaces v0.11 tools · new `engram doctor` install health-check CLI · upgrade-path smoke test caught + fixed a data-loss bug in cache.ts (Case B was wiping user permissions on upgrade) · 11 real exploit-payload integration tests prove C1/C2/H1 fixes hold · `npm run bench` ships a synthetic retrieval harness (50 Q&A) measuring 86% top-1 / 96% R@5. 53 tools, 664 tests. |

package/dist/{cache-7HSMIYDJ.js → cache-7S5DFFQ6.js}

@@ -2,14 +2,15 @@ import {
   detectProjectRoot,
   getBrain,
   refreshBrain
-} from "./chunk-I63UMEBF.js";
-import "./chunk-HROSQ5MS.js";
-import "./chunk-GATMQQK5.js";
-import "./chunk-WKQHCLLO.js";
-import "./chunk-MOOVNMIN.js";
-import "./chunk-ST4X7LZT.js";
-import "./chunk-M3YZOJNW.js";
+} from "./chunk-JE4BZQUD.js";
+import "./chunk-QM4U75VE.js";
+import "./chunk-V54QPQ6K.js";
+import "./chunk-2FAS6CV4.js";
 import "./chunk-POXT5OYN.js";
+import "./chunk-WKQHCLLO.js";
+import "./chunk-FX3SVNHX.js";
+import "./chunk-YRLAWCYW.js";
+import "./chunk-BBQSWT4H.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
 import "./chunk-27TA2ZQZ.js";

package/dist/{chunk-HROSQ5MS.js → chunk-2FAS6CV4.js}

@@ -15,7 +15,7 @@ import {
 } from "./chunk-27TA2ZQZ.js";
 
 // src/generators/settings.ts
-var HOOKS_VERSION = 11;
+var HOOKS_VERSION = 12;
 function generateSettings(config, rootPath) {
   return {
     mcpServers: {
@@ -288,6 +288,39 @@ function generateHooks(config, rootPath) {
       }
     ]
   });
+  hooks.PostToolUse.push({
+    _knitOwned: true,
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [
+      {
+        type: "command",
+        command: nodeHook(`
+          let d = "";
+          process.stdin.on("data", (c) => d += c);
+          process.stdin.on("end", () => {
+            try {
+              const fs = require("fs");
+              const path = require("path");
+              const i = JSON.parse(d);
+              const ti = i.tool_input || {};
+              const f = ti.file_path || (i.tool_response && i.tool_response.filePath) || "";
+              if (!f) return;
+              if (path.basename(f) !== "CLAUDE.md") return;
+              const TARGET = 6500;
+              const SLACK = 6500 * 1.25;
+              let size = 0;
+              try { size = fs.statSync(f).size; } catch { return; }
+              if (size <= TARGET) return;
+              const kb = Math.round(size/1024*10)/10;
+              const verdict = size > SLACK ? "over-budget" : "warn";
+              process.stderr.write("[knit] BUDGET " + verdict + ": " + f + " is now " + kb + "KB (target 6.5KB). Trim CLAUDE.md or run \\\`knit refresh\\\` to regenerate.\\n");
+            } catch (e) { try { process.stderr.write('[knit] claude-md size watch hook failed: ' + (e && e.message ? e.message : e) + '\\n'); } catch {} }
+          });
+        `),
+        timeout: 5
+      }
+    ]
+  });
   hooks.PostToolUse.push({
     _knitOwned: true,
     matcher: "Write|Edit|MultiEdit",

package/dist/{chunk-M3YZOJNW.js → chunk-BBQSWT4H.js}

@@ -1,14 +1,30 @@
 // src/engine/learnings.ts
-import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, rmdirSync, renameSync } from "fs";
 import { dirname } from "path";
 function readLearnings(filePath) {
   if (!existsSync(filePath)) return [];
   const content = readFileSync(filePath, "utf-8");
   const entries = [];
   const sections = content.split(/^## /m).slice(1);
+  let parseFailures = 0;
+  let emptyShells = 0;
   for (const section of sections) {
     const entry = parseEntry(section);
-    if (entry) entries.push(entry);
+    if (!entry) {
+      parseFailures++;
+      continue;
+    }
+    if (!entry.summary.trim() || !entry.lesson.trim()) {
+      emptyShells++;
+      continue;
+    }
+    entries.push(entry);
+  }
+  if (parseFailures > 0 || emptyShells > 0) {
+    process.stderr.write(
+      `[knit] readLearnings(${filePath}): skipped ${parseFailures} unparseable, ${emptyShells} empty-shell entries
+`
+    );
   }
   return entries;
 }

package/dist/{chunk-MOOVNMIN.js → chunk-FX3SVNHX.js}

@@ -325,7 +325,7 @@ function buildSummary(allFiles, sourceFiles, importGraph, testMap, rootPath) {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
       if (pkg.main) entryPoints.push(pkg.main);
       if (pkg.bin) {
-        const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin);
+        const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin).filter((v) => typeof v === "string");
         entryPoints.push(...bins);
       }
     }

package/dist/{chunk-I63UMEBF.js → chunk-JE4BZQUD.js}

@@ -1,11 +1,17 @@
+import {
+  installAgentsForProject,
+  pruneSessionsByAge
+} from "./chunk-QM4U75VE.js";
+import {
+  writeFileAtomic
+} from "./chunk-V54QPQ6K.js";
 import {
   HOOKS_VERSION,
   generateSettings
-} from "./chunk-HROSQ5MS.js";
+} from "./chunk-2FAS6CV4.js";
 import {
-  installAgentsForProject,
-  pruneSessionsByAge
-} from "./chunk-GATMQQK5.js";
+  prewarmLatestVersion
+} from "./chunk-POXT5OYN.js";
 import {
   importFromMarkdown,
   loadKnowledgeBaseSafe,
@@ -14,16 +20,13 @@ import {
 import {
   buildKnowledge,
   buildReverseDependencies
-} from "./chunk-MOOVNMIN.js";
+} from "./chunk-FX3SVNHX.js";
 import {
   scanProject
-} from "./chunk-ST4X7LZT.js";
+} from "./chunk-YRLAWCYW.js";
 import {
   readLearnings
-} from "./chunk-M3YZOJNW.js";
-import {
-  prewarmLatestVersion
-} from "./chunk-POXT5OYN.js";
+} from "./chunk-BBQSWT4H.js";
 import {
   persistScanResult,
   scanIntegrations
@@ -50,7 +53,7 @@ import {
 
 // src/mcp/cache.ts
 import { execSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, readdirSync, statSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, copyFileSync, readdirSync, statSync } from "fs";
 import { join, basename, dirname } from "path";
 
 // src/generators/learnings.ts
@@ -111,6 +114,9 @@ function getBrain(rootPath) {
   const projectName = detectProjectName(rootPath);
   const kbLoad = loadKnowledgeBaseSafe(knowledgebasePath(rootPath), projectName);
   const knowledgeBase = kbLoad.kb;
+  if (!kbLoad.loadFailed && knowledgeBase.projectName !== projectName) {
+    knowledgeBase.projectName = projectName;
+  }
   const config = {
     name: projectName,
     packageManager: scan.packageManager,
@@ -119,7 +125,7 @@ function getBrain(rootPath) {
     targetAgent: "claude-code",
     tokenOptimization: "standard"
   };
-  writeFileSync(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2), "utf-8");
+  writeFileAtomic(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2));
   if (!kbLoad.loadFailed) {
     saveKnowledgeBase(knowledgebasePath(rootPath), knowledgeBase);
   }
@@ -178,14 +184,14 @@ function autoInitialize(rootPath) {
   });
   const learningsPath = learningsFilePath(rootPath, projectName);
   if (!existsSync(learningsPath)) {
-    writeFileSync(learningsPath, generateLearningsContent(config), "utf-8");
+    writeFileAtomic(learningsPath, generateLearningsContent(config));
   }
   const kbPath = knowledgebasePath(rootPath);
   const kb = loadKnowledgeBaseSafe(kbPath, projectName).kb;
   const entries = readLearnings(learningsPath);
   importFromMarkdown(kb, entries);
   saveKnowledgeBase(kbPath, kb);
-  writeFileSync(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2), "utf-8");
+  writeFileAtomic(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2));
 }
 function migrateLegacyData(rootPath) {
   mkdirSync(projectDataDir(rootPath), { recursive: true });
@@ -219,7 +225,7 @@ can be deleted at your discretion. Future learnings, knowledge indexes, and
 session memory live in the new path.
 `;
     try {
-      writeFileSync(breadcrumb, note, "utf-8");
+      writeFileAtomic(breadcrumb, note);
     } catch {
     }
   }
@@ -228,24 +234,23 @@ function writeProjectClaudeMd(rootPath, config, knowledge) {
   const claudeMdPath = join(rootPath, "CLAUDE.md");
   const block = generateClaudeMd(config, knowledge);
   if (!existsSync(claudeMdPath)) {
-    writeFileSync(claudeMdPath, block, "utf-8");
+    writeFileAtomic(claudeMdPath, block);
     return;
   }
   const existing = readFileSync(claudeMdPath, "utf-8");
   if (existing.includes(KNIT_MARKER_START)) {
     const { content } = spliceKnitBlock(existing, block);
-    writeFileSync(claudeMdPath, content, "utf-8");
+    writeFileAtomic(claudeMdPath, content);
     return;
   }
   const sidecarDir = join(rootPath, ".claude");
   const sidecarPath = join(sidecarDir, "KNIT.md");
-  mkdirSync(sidecarDir, { recursive: true });
   const sidecar = `<!-- This file is Knit's per-project workflow. -->
 <!-- Your CLAUDE.md exists without Knit markers, so Knit wrote here instead of clobbering it. -->
 <!-- To include this content in CLAUDE.md, add: @.claude/KNIT.md -->
 
 ${block}`;
-  writeFileSync(sidecarPath, sidecar, "utf-8");
+  writeFileAtomic(sidecarPath, sidecar);
 }
 function copyIfExists(src, dst) {
   if (existsSync(src) && !existsSync(dst)) {
@@ -258,8 +263,7 @@ function writeKnitHooks(rootPath, config) {
   const settingsPath = join(claudeDir, "settings.local.json");
   const fresh = generateSettings(config, rootPath);
   if (!existsSync(settingsPath)) {
-    mkdirSync(claudeDir, { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(fresh, null, 2), "utf-8");
+    writeFileAtomic(settingsPath, JSON.stringify(fresh, null, 2));
     return;
   }
   let existing;
@@ -299,8 +303,7 @@ function writeKnitHooks(rootPath, config) {
     _knitHooks: { ...fresh._knitHooks, merged: true }
   };
   delete merged._engramHooks;
-  mkdirSync(claudeDir, { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(merged, null, 2), "utf-8");
+  writeFileAtomic(settingsPath, JSON.stringify(merged, null, 2));
 }
 function detectProjectName(rootPath) {
   let name = basename(rootPath);