@softspark/ai-toolkit 4.19.0 → 4.20.0

package/llms-full.txt

@@ -14,19 +14,22 @@
 - [Best Practices](kb/best-practices/README.md)
 - [No Hardcoded Counts in Secondary Docs](kb/best-practices/no-hardcoded-counts.md)
 - [Plan: Deep Coverage v3.0 — 100% Native Surface Utilization](kb/history/completed/deep-coverage-v3-20260423.md)
+- [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/history/completed/drop-cascade-hooks-after-sunset-20260710.md)
 - [Plan: Ecosystem Deep Sweep — All 12 Supported Tools](kb/history/completed/ecosystem-deep-sweep-20260423.md)
 - [Plan: Enterprise Config Inheritance — Multi-Repo Governance with `extends`](kb/history/completed/enterprise-config-inheritance-plan-20260412.md)
 - [Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision](kb/history/completed/f2-mcp-trim-spike-20260504.md)
+- [Language Plugin Packs — REMOVED](kb/history/completed/language-packs-removed-20260727.md)
+- [PRD: MCP Context Trim v4.0 — ABANDONED](kb/history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md)
 - [Implementation Plan: Native Tool Output Filter](kb/history/completed/native-tool-output-filter-plan.md)
+- [Removed: Nine Plugin Packs That Installed Nothing](kb/history/completed/no-op-plugin-packs-removed-20260727.md)
 - [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
 - [Retirement: Native Tool-Output Filter](kb/history/completed/output-filter-retirement-20260726.md)
 - [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
 - [rtk Pack Integration](kb/history/completed/rtk-pack-integration-20260726.md)
 - [Retirement: rtk-pack](kb/history/completed/rtk-pack-retirement-20260727.md)
+- [Closed: Tool-Output Token Reduction](kb/history/completed/tool-output-token-reduction-closed-20260727.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
-- [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/planning/drop-cascade-hooks-after-sunset.md)
-- [PRD: MCP Context Trim v4.0](kb/planning/mcp-context-trim-v4-prd.md)
 - [SOP: Ecosystem Sync](kb/procedures/ecosystem-sync-sop.md)
 - [SOP: AI Toolkit Maintenance](kb/procedures/maintenance-sop.md)
 - [SOP: Post-Release Testing](kb/procedures/post-release-testing-sop.md)
@@ -51,8 +54,8 @@
 - [Hierarchical Override Pattern](kb/reference/hierarchical-override-pattern.md)
 - [Hooks Catalog](kb/reference/hooks-catalog.md)
 - [External Integrations](kb/reference/integrations.md)
-- [Language Plugin Packs](kb/reference/language-packs.md)
 - [Language Rules System](kb/reference/language-rules.md)
+- [Licensing](kb/reference/licensing.md)
 - [Manifest-Driven Install System](kb/reference/manifest-install.md)
 - [MCP Editor Compatibility](kb/reference/mcp-editor-compatibility.md)
 - [MCP Server Templates](kb/reference/mcp-templates.md)
@@ -458,6 +461,131 @@ Definition of "100% coverage" chosen: **each editor works at 100% of its native
 
 ---
 
+## kb/history/completed/drop-cascade-hooks-after-sunset-20260710.md
+
+---
+title: "Plan: Drop Cascade hooks after 2026-07-01 sunset"
+category: planning
+service: ai-toolkit
+tags:
+  - windsurf
+  - devin
+  - cascade
+  - hooks
+  - deprecation
+  - cleanup
+doc_type: plan
+status: completed
+created: "2026-06-10"
+last_updated: "2026-07-10"
+completion: "100%"
+trigger_date: "2026-07-01"
+description: "Completed cleanup of the deprecated Windsurf Cascade hooks generator after the 2026-07-01 sunset; Devin CLI .devin/hooks.v1.json is now the sole live hook surface."
+---
+
+# Plan: Drop Cascade hooks after 2026-07-01 sunset
+
+**Completed in v4.13.0 (2026-07-10).** The deprecated generator and install/test wiring were removed; the Devin hook generator remains.
+
+> **Filed to history 2026-07-27.** The plan was finished in v4.13.0 but sat in
+> `kb/planning/` for another two and a half weeks, where it read as open work.
+> Before moving it, every claim in the Verification section below was re-run
+> against the codebase:
+>
+> | Check | Result |
+> |---|---|
+> | `scripts/generate_windsurf_hooks.py` deleted | gone |
+> | `grep -rn generate_windsurf_hooks scripts/ tests/` | no source references (one stale `.pyc` under gitignored `__pycache__`) |
+> | `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` retained in `validate.py` | present, line 882 |
+> | windsurf `our_generators` in `scripts/ecosystem_tools.json` | Cascade generator absent, `generate_devin_hooks.py` present |
+> | `kb/reference/supported-tools-registry.md` hooks-migration row | reads "Complete" in past tense |
+> | `validate.py --strict` | 0 errors, 0 warnings |
+>
+> The work was real and complete. Only the filing was wrong.
+>
+> **Process note.** This is the second document found misfiled in
+> `kb/planning/` on the same day; the other,
+> [`mcp-context-trim-v4-prd-obsoleted-20260727.md`](mcp-context-trim-v4-prd-obsoleted-20260727.md),
+> had gone obsolete because the platform shipped the fix first. A plan with a
+> `trigger_date` needs a matching move-to-history step in the release that acts
+> on it — otherwise `kb/planning/` accumulates work that is already done or no
+> longer worth doing, and the next reader cannot tell which is which.
+
+## Why this exists
+
+Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its
+`.windsurf/hooks.json` hook surface (`agent_action_name`/`tool_info` format) — is
+available **only through 2026-07-01**. Devin Local / Devin CLI do **not** read
+`.windsurf/hooks.json` as a fallback.
+
+v4.8.0 already shipped the replacement: `generate_devin_hooks.py` emits
+`.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses. During the
+transition **both** generators run at `profile=full` so pre-sunset Cascade users
+keep working. After 2026-07-01 the Cascade half is dead code and must be removed
+(Constitution Art. VI.1 — no dead code).
+
+## Trigger
+
+First ai-toolkit release **on or after 2026-07-01**. Do NOT do this earlier —
+removing it before the sunset breaks Cascade users who are still on the old agent.
+
+## Scope — remove the Cascade hooks surface
+
+1. **Delete the generator:** `scripts/generate_windsurf_hooks.py`.
+2. **Unwire the install step:** in `scripts/install_steps/ai_tools.py`, remove the
+   `_try_generator("generate_windsurf_hooks", cwd)` call (keep
+   `generate_devin_hooks`). Update the `profile=full` dry-run message to drop
+   `.windsurf/hooks.json (Cascade, deprecated)`.
+3. **Tests:** remove the windsurf-`.windsurf/hooks.json` cases from
+   `tests/test_hooks_per_editor.bats` (output path, valid JSON, source tag,
+   `$HOME` prefix, idempotence, user-preservation, `pre_write_code` coverage) and
+   the `profile=full` assertion in `tests/test_install_profiles.bats`
+   (`windsurf + full emits .windsurf/hooks.json`). Keep all `.devin/hooks.v1.json`
+   tests. Adjust the README test-count badge to the new total.
+4. **Registry:** in `scripts/ecosystem_tools.json` (windsurf entry), remove
+   `scripts/generate_windsurf_hooks.py` from `our_generators`; keep
+   `.windsurf/hooks.json` out of `config_paths` (it was never listed). Trim the
+   `status_note` hooks-migration paragraph to past tense ("Cascade hooks removed
+   in vX.Y.Z").
+5. **Docs:** in `kb/reference/supported-tools-registry.md` drop the
+   `generate_windsurf_hooks.py` row and the "drop after 2026-07-01" note; in
+   `kb/reference/hooks-catalog.md` remove the Cascade row from the
+   Per-Editor Native Hooks table and the deprecation wording, leaving the Devin CLI
+   section as the windsurf-family hook surface.
+6. **validate.py:** the `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` mapping STAYS —
+   it is what keeps the `devin` hook generator counted as windsurf hooks in the
+   README-honesty check after the Cascade generator is gone.
+7. **CHANGELOG / version:** minor bump, `Removed` entry, regen artifacts, full
+   release-preparation SOP gate.
+
+## Verification
+
+- `python3 scripts/validate.py --strict` — 0/0 (editor-hooks-honesty must still
+  report windsurf as hook-enabled via the `devin` generator alias).
+- `python3 scripts/ecosystem_doctor.py --offline --check` — exit 0.
+- `npm test` — 0 `not ok`; no test recreates the deleted
+  `generate_windsurf_hooks.py` generator.
+- `grep -rn "generate_windsurf_hooks" scripts/ tests/` returns nothing
+  (Art. VI.1 orphan check — the deleted generator is fully unwired).
+  `.windsurf/hooks.json` intentionally remains referenced by the one-time
+  migration/strip cleanup (`scripts/install_steps/ai_tools.py`) and its test,
+  and in narrative docs (CHANGELOG, README, `kb/`, docstrings).
+
+## Do NOT touch
+
+- `generate_devin_hooks.py` and `.devin/hooks.v1.json` — the live replacement.
+- The `.devin/`/`.windsurf/` rules + skills dual-emit (that fallback persists as
+  long as Devin Desktop reads legacy `.windsurf/` paths; this plan is hooks-only).
+
+## Related
+
+- `kb/reference/hooks-catalog.md` — Per-Editor Native Hooks + Devin CLI section
+- `kb/reference/supported-tools-registry.md` — windsurf entry, hooks-migration row
+- `kb/procedures/ecosystem-sync-sop.md` — class-D deprecation workflow
+- `scripts/ecosystem_tools.json` — windsurf `status_note`
+
+---
+
 ## kb/history/completed/ecosystem-deep-sweep-20260423.md
 
 ---
@@ -1780,110 +1908,389 @@ Estimate in the PRD: ~8 working days.
 
 ---
 
-## kb/history/completed/native-tool-output-filter-plan.md
+## kb/history/completed/language-packs-removed-20260727.md
 
 ---
-title: "Implementation Plan: Native Tool Output Filter"
+title: "AI Toolkit - Language Plugin Packs (removed)"
 category: planning
 service: ai-toolkit
-tags:
-  - output-filter
-  - hooks
-  - recovery
-  - performance
-  - claude-code
-doc_type: plan
+tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby, removed]
+doc_type: postmortem
 status: completed
-created: "2026-07-23"
-last_updated: "2026-07-23"
-completed: "2026-07-23"
-completion: "100% of approved Claude Code scope; other runtimes remain manual-only by capability decision"
-shipped_in: "Unreleased"
-description: "Approved implementation plan and completion evidence for the original dependency-free ai-toolkit tool-output filter, including conservative profiles, exact recovery, telemetry, runtime capability gates, and adjacent repairs."
+version: "1.1.0"
+created: "2026-03-29"
+last_updated: "2026-07-27"
+description: "REMOVED 2026-07-27 in v4.20.0. The six language packs wrapped skills that already ship in core, so installing one put zero files on disk. The skills themselves (rust-patterns, java-patterns, csharp-patterns, kotlin-patterns, swift-patterns, ruby-patterns) were never in the packs and are unaffected."
+---
+
+# Language Plugin Packs — REMOVED
+
+> **Removed 2026-07-27 in v4.20.0. Nothing was lost.**
+>
+> The six packs described below each declared exactly one skill —
+> `rust-patterns`, `java-patterns`, `csharp-patterns`, `kotlin-patterns`,
+> `swift-patterns`, `ruby-patterns` — and every one of those skills lives in
+> `app/skills/`, is part of the core install, and **still does**. The packs
+> owned no files of their own beyond a `README.md`.
+>
+> Because `ai-toolkit install` links every core skill, installing a language
+> pack put **zero** files on disk. Measured on both runtimes and all three
+> profiles: `(0 file items)` every time.
+>
+> **If you used one of these packs, you lose nothing.** The skill it named is
+> already installed and triggers on the same file types it always did — open a
+> `.rs` file and `rust-patterns` still loads.
+>
+> Full measurement and the rule that now prevents a repeat:
+> [`no-op-plugin-packs-removed-20260727.md`](no-op-plugin-packs-removed-20260727.md).
+>
+> The document below is preserved as written on 2026-03-29.
+
 ---
 
-# Implementation Plan: Native Tool Output Filter
+## Overview
 
-## Status
+Language packs are domain-scoped plugin packs that provide knowledge skills for specific programming languages. Each pack contains a single knowledge skill with idiomatic patterns, error handling, testing conventions, common frameworks, and performance tips.
 
-Completed on 2026-07-23 after user approval.
+## Available Packs
 
-Completion evidence:
+| Pack | Skill | Language | Key Topics |
+|------|-------|----------|------------|
+| `rust-pack` | `rust-patterns` | Rust | Ownership, borrowing, Cargo, tokio, serde |
+| `java-pack` | `java-patterns` | Java | Records, sealed classes, Spring Boot, JUnit 5 |
+| `csharp-pack` | `csharp-patterns` | C# / .NET | Nullable refs, async/await, ASP.NET Core, EF Core |
+| `kotlin-pack` | `kotlin-patterns` | Kotlin | Coroutines, DSLs, sealed classes, Ktor, MockK |
+| `swift-pack` | `swift-patterns` | Swift / iOS | Protocol-oriented, SwiftUI, async/await, SPM |
+| `ruby-pack` | `ruby-patterns` | Ruby | Blocks, Rails conventions, RSpec, ActiveRecord |
 
-- 69 focused Python tests pass, including the production-wrapper benchmark.
-- The 100-sample cold wrapper measures 63.565 ms p95 against the 75 ms gate.
-- The 8 MiB profile case measures 4.354 ms p95 and 8,792,932 peak traced
-  bytes against the 150 ms and 41,943,040 byte gates.
-- The strict repository validator reports 44 agents, 108 skills, and 1477
-  tests with zero errors or warnings.
-- Ruff, mypy, ShellCheck, skill audit, generated artifacts, and the final
-  repository test gate pass for the changed surface.
+## Skill Content Sections
 
-## Context
+Each language skill follows a consistent structure:
 
-`ai-toolkit` currently controls assistant response length and reports real
-Claude session tokens, but it does not transform live tool output before that
-output reaches the model. The requested feature is an original, MIT-licensed,
-dependency-free implementation inside `ai-toolkit`. RTK is research input only:
-no runtime dependency, vendoring, translated code, copied filters, fixtures,
-regex tables, CLI names, or configuration keys.
+1. **Project Structure** — standard directory layout and build tool configuration
+2. **Idioms / Code Style** — language-specific patterns and conventions
+3. **Error Handling** — error types, patterns, and best practices
+4. **Testing Patterns** — test frameworks, assertion libraries, mocking
+5. **Common Libraries / Frameworks** — ecosystem essentials
+6. **Performance Tips** — optimization techniques and profiling
+7. **Build / Package Management** — dependency management and CI
 
-The first native integration targets Claude Code because current Claude hooks
-support replacing successful tool output through
-`PostToolUse.hookSpecificOutput.updatedToolOutput`. The transformer remains
-strictly post-execution and cannot alter the command, arguments, environment,
-working directory, permission decision, exit status, or signal.
+## How Knowledge Skills Work
 
-This feature is separate from MCP `tools/list` description trimming. Hooks can
-transform an executed tool result, but they do not intercept MCP catalog
-metadata. [PATH: kb/history/completed/f2-mcp-trim-spike-20260504.md]
-[PATH: kb/planning/mcp-context-trim-v4-prd.md]
+These skills have `user-invocable: false` in their frontmatter, meaning they are NOT slash commands. Instead, Claude loads them contextually when the conversation topic matches the skill's description trigger.
 
-Relevant local boundaries:
+For example, when a user asks "How do I handle errors in Rust?", Claude automatically loads `rust-patterns` to provide idiomatic Rust error handling guidance.
 
-- Fixed lifecycle enforcement belongs in hooks. [PATH: CLAUDE.md:10]
-- The current safety guards run in `PreToolUse`. [PATH: app/hooks.json:37]
-- Hook runtime Python helpers are deployed explicitly.
-  [PATH: scripts/install_steps/hooks.py:71]
-- Runtime hook schemas differ by editor.
-  [PATH: kb/reference/hooks-catalog.md:571]
-- Existing output/token work intentionally uses native mechanisms.
-  [PATH: kb/history/completed/output-token-discipline-plan-20260504.md]
-- Claude hook contract:
-  <https://code.claude.com/docs/en/hooks>
+## Requesting New Language Packs
 
-## Scope
+File an issue with the `language-pack` label. Include:
+- Language name
+- Key topics to cover
+- Popular frameworks/libraries to include
 
-### Included
+---
 
-- Python standard library implementation under `scripts/`.
-- Pure post-execution transformation of successful textual Bash output.
-- `off`, `observe`, and `safe` modes.
-- Claude Code integration through `PostToolUse.updatedToolOutput`.
-- Manual CLI for fixture inspection, status, recovery, and cleanup.
-- Two initial deterministic profiles:
-  - `repeat-lines`: aggregate adjacent identical non-diagnostic lines and state
-    their multiplicity.
-  - `tap-success`: compact valid successful TAP while retaining plan,
-    directives, comments, totals, duration, and all diagnostic material.
-- Byte and line savings, latency, outcome, profile ID, and profile version.
-- Exact, bounded, session-scoped raw recovery when `safe` mode is enabled.
-- Capability-gated adapters for additional runtimes after Phase 2.
+## kb/history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md
 
-### Excluded
+---
+title: "PRD: MCP Context Trim v4.0 — Local Proxy with Description Compression"
+category: planning
+service: ai-toolkit
+tags:
+  - mcp
+  - proxy
+  - tool-descriptions
+  - jsonrpc
+  - tokens
+  - v4
+doc_type: plan
+status: obsoleted
+created: "2026-05-04"
+last_updated: "2026-07-27"
+completion: "0% — never started, and no longer worth starting"
+target_milestone: "v4.0 (abandoned)"
+predecessor:
+  - "kb/history/completed/output-token-discipline-plan-20260504.md"
+  - "kb/history/completed/f2-mcp-trim-spike-20260504.md"
+description: "ABANDONED 2026-07-27. Local MCP proxy that would compress tool descriptions before they reach the model. Never built. Claude Code now defers MCP tool schemas by default — the catalog costs ~120 tokens of tool names, with schemas fetched on demand — so the 8-15k per-turn overhead this PRD was written to remove no longer exists. Kept as the record of a plan the platform solved first."
+---
+
+# PRD: MCP Context Trim v4.0 — ABANDONED
+
+> **Abandoned 2026-07-27, never implemented.**
+>
+> **Why:** the premise expired. This PRD is built on one measured claim — that
+> MCP tool descriptions sit in every turn's system prompt, costing 8–15k tokens
+> per turn. Claude Code now **defers MCP tool schemas by default**: the model
+> receives roughly 120 tokens of tool *names*, and full schemas are fetched on
+> demand through tool search when a task actually needs one.
+> ([Claude Code docs — context window](https://code.claude.com/docs/en/context-window),
+> `ENABLE_TOOL_SEARCH=auto|false` controls the older eager behaviour.)
+>
+> The overhead this proxy was designed to remove is already gone. Building it
+> now would add a supervised local daemon, an `.mcp.json` rewrite, a rollback
+> path and five pre-mortem failure modes in order to compress a 120-token
+> catalog.
+>
+> **How it was caught:** during the 2026-07-27 token-reduction review, a
+> measurement of 1189 real sessions put the median startup context at 22,175
+> tokens against ~7,850 in the documented reference shape. Attributing that gap
+> showed the excess was skill and agent descriptions and rule files — not MCP.
+> The MCP catalog was already deferred, exactly as the docs describe. Full
+> context: [`tool-output-token-reduction-closed-20260727.md`](tool-output-token-reduction-closed-20260727.md).
+>
+> **What survives:** nothing in the architecture below is reusable, because it
+> exists to solve a problem the host now solves. What survives is the process
+> note — this PRD sat in `kb/planning/` for nearly three months while the
+> platform shipped the fix, and nobody re-checked the premise. A plan blocked on
+> a host limitation should carry a re-validation date, not wait indefinitely.
+>
+> Everything below is the document as written on 2026-05-04. It is preserved
+> unedited so the reasoning stays auditable.
+
+---
+
+**Status:** Proposed *(as of 2026-05-04; see abandonment note above)*
+**Target milestone:** v4.0
+**Carved out of:** [`output-token-discipline-plan-20260504.md`](output-token-discipline-plan-20260504.md) (was Feature 2)
+**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md)
 
-- RTK binaries, libraries, source code, filters, fixtures, configuration, or
-  branding.
-- Command rewriting, `sh -c`, shell parsing, permission decisions, or command
-  execution by the filter.
-- LLM-generated summaries or network calls.
-- Project-defined regex filters in the first release.
-- Failed commands, non-empty `stderr`, signals, TTY/streaming output, binary or
-  invalid text, pipes, redirects, security scanners, dependency audits,
-  deployment, migrations, permission failures, and destructive-command
-  diagnostics.
-- `Read`, web results, arbitrary MCP results, and MCP `tools/list`.
-- Claims that byte reduction equals billed-token or whole-session savings.
+## Problem
+
+MCP server tool descriptions are injected into every model turn's system prompt. With ~100 tools across 7 typical servers, descriptions consume 8–15k tokens per turn — pure overhead, paid every message. Examples observed in users' configs:
+
+- `dart-mcp-server` — ~30 tools with multi-paragraph descriptions
+- `filesystem` — verbose paths and example sections
+- `pencil` — "IMPORTANT" stanzas repeated across tools
+- `jira-mcp` — long `Use this tool to…` boilerplate
+
+The v3.2.0 output-discipline plan attempted to solve this with a hook-based trimmer. The spike conducted 2026-05-04 proved Claude Code hooks do not expose `tools/list` metadata or the system-prompt tool catalog. The only viable architecture is a local MCP proxy.
+
+## Goal
+
+Reduce MCP-description overhead by ≥40% per server, with **zero** loss of parameter schemas, required fields, or discrimination signals (`not`, `never`, `only`, `except`, `unless`).
+
+## Non-goals
+
+- Modifying tool **call** behavior (only descriptions)
+- Compressing user-facing prompts or completions
+- Replacing or rewriting upstream MCP servers
+- Touching MCP servers we do not control
+
+## Architecture
+
+### Proxy topology
+
+```
+Claude Code  ──stdio──▶  ai-toolkit MCP proxy  ──stdio/SSE──▶  upstream MCP server
+                                │
+                                └─ rewrites tools/list response
+                                   passes through tools/call unchanged
+```
+
+One proxy process per upstream server, supervised by `ai-toolkit mcp-trim daemon` (or equivalent). User's `~/.claude/.mcp.json` is rewritten by `ai-toolkit install` (opt-in) to point Claude Code at the proxy instead of upstream — proxy reads the original target from a sidecar config.
+
+### Required components
+
+| Component | Purpose |
+|-----------|---------|
+| `scripts/mcp_proxy_server.py` | JSON-RPC 2.0 proxy. Reads stdin, forwards to upstream over stdio or SSE, intercepts `tools/list` response, rewrites descriptions. Stdlib-only. |
+| `scripts/mcp_description_trimmer.py` | Pure function library: `trim(description: str) → str`. Reused from heuristics below. Stdlib-only. |
+| `scripts/mcp_proxy_config.py` | Reads `~/.softspark/ai-toolkit/mcp-proxy/servers.json`, validates upstream targets, generates supervisord/launchd config. |
+| `app/hooks/mcp-proxy-health.sh` | SessionStart hook — verifies all configured proxies responsive; fall through (warn, do not block) if any down. |
+| `app/skills/mcp-trim/SKILL.md` | Knowledge skill: how to enable, opt out, audit savings. |
+| `bin/ai-toolkit-mcp-trim` | CLI: `enable`, `disable`, `status`, `audit` (per-server token savings report). |
+| `tests/test_mcp_proxy.bats` | Integration tests with mock upstream MCP servers. |
+| `tests/test_mcp_trimmer.bats` | Unit tests for description trim heuristics on captured fixtures. |
+
+### Compression heuristics (from spike)
+
+Applied to each tool description in `tools/list` response:
+
+- Drop example sections >40 chars
+- Collapse `Use this server to…` / `Use this tool to…` boilerplate to minimum form preserving intent
+- Drop duplicate occurrences of tool name in its own description
+- **Preserve bytewise:** `inputSchema.properties[*].description`, `required`, `enum` values, URL/path identifiers
+- **Never strip:** the words `not`, `never`, `only`, `except`, `unless` — these carry "when NOT to use" signals
+- Target: ≥40% length reduction, 0% schema loss
+
+### Failure modes & rollback
+
+| Scenario | Behavior |
+|----------|----------|
+| Proxy crashes mid-session | `mcp-proxy-health.sh` detects on next SessionStart, prints warning, suggests `ai-toolkit mcp-trim disable <server>` |
+| Upstream MCP server changes its tool catalog | Proxy passes through unchanged tools (no cached schema), warns once if a tool's description was previously trimmed |
+| Trimmer produces malformed JSON | Proxy falls through to upstream response unchanged, logs to `~/.softspark/ai-toolkit/mcp-proxy/error.log` |
+| User wants to bypass | `AI_TOOLKIT_MCP_TRIM_DISABLE=1` env var → proxies pass everything through unchanged |
+| User wants to fully uninstall | `ai-toolkit mcp-trim disable` reverts `~/.claude/.mcp.json` to original upstream targets |
+
+### Migration of existing user `.mcp.json`
+
+`ai-toolkit mcp-trim enable` does:
+
+1. Backup `~/.claude/.mcp.json` → `~/.softspark/ai-toolkit/mcp-proxy/.mcp.json.bak.<timestamp>`
+2. Read each server entry, store in `~/.softspark/ai-toolkit/mcp-proxy/servers.json`
+3. Rewrite each entry to point at the local proxy (with sidecar `target` field)
+4. Spawn supervisor (per-OS: launchd on macOS, systemd on Linux, scheduled task on Windows)
+5. Verify each upstream reachable via proxy, abort + restore backup on any failure
+
+## Out-of-scope decisions (rejected mid-spike)
+
+| Option | Why rejected |
+|--------|--------------|
+| Pre-install rewrite of `.mcp.json` only | MCP spec sources descriptions from server runtime, not config — wouldn't take effect |
+| Source-side forks of MCP servers | Doesn't help users with custom servers; high maintenance |
+| F2-lite observability tool | User decision 2026-05-04: tracking token waste without trimming is half-value; do the full thing in v4.0 |
+| Hook-based interception | Spike proved hooks cannot reach `tools/list` |
+
+## Success criteria
+
+- ≥40% description-length reduction per server on the captured fixture set (jira, filesystem, dart, pencil)
+- Deep-equal `inputSchema` between trimmed and upstream — zero schema regression
+- Proxy adds <50ms per `tools/list` call (one-time per session)
+- Proxy adds <5ms per `tools/call` (passthrough overhead)
+- Round-trip correctness: every tool callable via proxy returns byte-identical result vs direct call
+- Zero MCP-skill regressions in `npm test` after enabling proxy in CI
+- Rollback (`ai-toolkit mcp-trim disable`) restores byte-identical original `.mcp.json`
+
+## Open questions
+
+1. Process supervision per-OS — launchd / systemd / scheduled-task wrappers, or a built-in `ai-toolkit-mcp-trimd` daemon binary?
+2. SSE-mode upstreams (e.g., rag-mcp at `http://localhost:8081/mcp/sse`) — proxy listens on SSE locally too, or stdio-only with internal SSE client?
+3. Description rewrites — static dictionary of "boilerplate phrases to drop" (faster, deterministic) vs LLM-based summarizer (more aggressive, less predictable)? Recommend static for v4.0, LLM as v4.1 stretch.
+4. Config path — `~/.softspark/ai-toolkit/mcp-proxy/` (matches existing convention) or `~/.claude/mcp-proxy/` (closer to MCP config)? Recommend the former.
+5. Telemetry — does this become an opt-in metric in `/briefing --tokens` ("MCP descriptions: 12.3k → 7.2k, saved 5.1k per turn")? Recommend yes.
+
+## Pre-mortem (failure scenarios to design against)
+
+1. **Proxy gets out of sync with upstream** — upstream adds a new tool, proxy doesn't know how to compress it → passthrough that tool's description unchanged, log warning
+2. **Compression breaks tool discriminability** — model picks wrong tool because trimmed description lost the "use only when X" qualifier → the `not/never/only/except/unless` blacklist must be exhaustive; add per-server allowlists for false positives
+3. **Multi-process race on `.mcp.json` rewrite** — two `ai-toolkit install` invocations clobber each other → file lock during enable/disable
+4. **Proxy supervisor fails to start on user's machine** — different distro / no systemd → ai-toolkit doctor must detect and report; degrade to "MCP proxy unavailable, falling through" with no functionality loss
+5. **User has custom MCP server we don't recognize** — must work without per-server schema; default heuristics must be safe enough for arbitrary servers
+
+## Estimate
+
+- Architecture spike + working proxy prototype: 2 days
+- Production proxy + supervisor + config + CLI: 3 days
+- Test suite + fixtures + CI integration: 2 days
+- Documentation + migration guide + release notes: 1 day
+
+**Total: ~8 working days** (1.5–2 weeks calendar time at typical pace)
+
+## Status
+
+| Date | Status | Author |
+|------|--------|--------|
+| 2026-05-04 | PRD drafted from spike conclusions, carved out of v3.2.0 plan | claude |
+| 2026-07-27 | Abandoned without implementation. Claude Code began deferring MCP tool schemas by default, removing the per-turn overhead this proxy targeted. Moved from `kb/planning/` to `kb/history/completed/`. | claude |
+
+---
+
+## kb/history/completed/native-tool-output-filter-plan.md
+
+---
+title: "Implementation Plan: Native Tool Output Filter"
+category: planning
+service: ai-toolkit
+tags:
+  - output-filter
+  - hooks
+  - recovery
+  - performance
+  - claude-code
+doc_type: plan
+status: completed
+created: "2026-07-23"
+last_updated: "2026-07-23"
+completed: "2026-07-23"
+completion: "100% of approved Claude Code scope; other runtimes remain manual-only by capability decision"
+shipped_in: "Unreleased"
+description: "Approved implementation plan and completion evidence for the original dependency-free ai-toolkit tool-output filter, including conservative profiles, exact recovery, telemetry, runtime capability gates, and adjacent repairs."
+---
+
+# Implementation Plan: Native Tool Output Filter
+
+## Status
+
+Completed on 2026-07-23 after user approval.
+
+Completion evidence:
+
+- 69 focused Python tests pass, including the production-wrapper benchmark.
+- The 100-sample cold wrapper measures 63.565 ms p95 against the 75 ms gate.
+- The 8 MiB profile case measures 4.354 ms p95 and 8,792,932 peak traced
+  bytes against the 150 ms and 41,943,040 byte gates.
+- The strict repository validator reports 44 agents, 108 skills, and 1477
+  tests with zero errors or warnings.
+- Ruff, mypy, ShellCheck, skill audit, generated artifacts, and the final
+  repository test gate pass for the changed surface.
+
+## Context
+
+`ai-toolkit` currently controls assistant response length and reports real
+Claude session tokens, but it does not transform live tool output before that
+output reaches the model. The requested feature is an original, MIT-licensed,
+dependency-free implementation inside `ai-toolkit`. RTK is research input only:
+no runtime dependency, vendoring, translated code, copied filters, fixtures,
+regex tables, CLI names, or configuration keys.
+
+The first native integration targets Claude Code because current Claude hooks
+support replacing successful tool output through
+`PostToolUse.hookSpecificOutput.updatedToolOutput`. The transformer remains
+strictly post-execution and cannot alter the command, arguments, environment,
+working directory, permission decision, exit status, or signal.
+
+This feature is separate from MCP `tools/list` description trimming. Hooks can
+transform an executed tool result, but they do not intercept MCP catalog
+metadata. [PATH: kb/history/completed/f2-mcp-trim-spike-20260504.md]
+[PATH: kb/planning/mcp-context-trim-v4-prd.md]
+
+Relevant local boundaries:
+
+- Fixed lifecycle enforcement belongs in hooks. [PATH: CLAUDE.md:10]
+- The current safety guards run in `PreToolUse`. [PATH: app/hooks.json:37]
+- Hook runtime Python helpers are deployed explicitly.
+  [PATH: scripts/install_steps/hooks.py:71]
+- Runtime hook schemas differ by editor.
+  [PATH: kb/reference/hooks-catalog.md:571]
+- Existing output/token work intentionally uses native mechanisms.
+  [PATH: kb/history/completed/output-token-discipline-plan-20260504.md]
+- Claude hook contract:
+  <https://code.claude.com/docs/en/hooks>
+
+## Scope
+
+### Included
+
+- Python standard library implementation under `scripts/`.
+- Pure post-execution transformation of successful textual Bash output.
+- `off`, `observe`, and `safe` modes.
+- Claude Code integration through `PostToolUse.updatedToolOutput`.
+- Manual CLI for fixture inspection, status, recovery, and cleanup.
+- Two initial deterministic profiles:
+  - `repeat-lines`: aggregate adjacent identical non-diagnostic lines and state
+    their multiplicity.
+  - `tap-success`: compact valid successful TAP while retaining plan,
+    directives, comments, totals, duration, and all diagnostic material.
+- Byte and line savings, latency, outcome, profile ID, and profile version.
+- Exact, bounded, session-scoped raw recovery when `safe` mode is enabled.
+- Capability-gated adapters for additional runtimes after Phase 2.
+
+### Excluded
+
+- RTK binaries, libraries, source code, filters, fixtures, configuration, or
+  branding.
+- Command rewriting, `sh -c`, shell parsing, permission decisions, or command
+  execution by the filter.
+- LLM-generated summaries or network calls.
+- Project-defined regex filters in the first release.
+- Failed commands, non-empty `stderr`, signals, TTY/streaming output, binary or
+  invalid text, pipes, redirects, security scanners, dependency audits,
+  deployment, migrations, permission failures, and destructive-command
+  diagnostics.
+- `Read`, web results, arbitrary MCP results, and MCP `tools/list`.
+- Claims that byte reduction equals billed-token or whole-session savings.
 
 ## Architecture
 
@@ -2302,53 +2709,185 @@ the savings threshold, and all unsafe paths remain exact passthrough.
 
 ---
 
-## kb/history/completed/offline-slm-profile-plan-20260411.md
+## kb/history/completed/no-op-plugin-packs-removed-20260727.md
 
 ---
-title: "Plan: Offline-First SLM Profile — Lightweight Mode for Local Models"
+title: "Removed: Nine Plugin Packs That Installed Nothing"
 category: planning
 service: ai-toolkit
 tags:
-  - offline
-  - slm
-  - small-language-models
-  - ollama
-  - lm-studio
-  - profile
-  - context-optimization
-  - privacy
-doc_type: plan
+  - plugins
+  - plugin-pack
+  - measurement
+  - postmortem
+  - dead-code
+doc_type: postmortem
 status: completed
-created: "2026-04-10"
-last_updated: "2026-04-11"
-completion: "100%"
-completed: "2026-04-11"
-description: "Lightweight profile for ai-toolkit optimized for Small Language Models (SLMs) running locally via Ollama, LM Studio, or similar. Compiles a minimal instruction set that fits within 4K-8K system prompt budgets while preserving critical safety guardrails. Targets air-gapped, privacy-first, and cost-sensitive development workflows."
+created: "2026-07-27"
+last_updated: "2026-07-27"
+shipped_in: "v4.20.0 (removal)"
+description: "Nine of eleven plugin packs installed zero files, because every asset they declared already ships in the core install. Measured across both runtimes and all three profiles. Records what was removed, what survived, why the authoring guidance produced the problem, and the check that now prevents a repeat."
 ---
 
-# Plan: Offline-First SLM Profile — Lightweight Mode for Local Models
+# Removed: Nine Plugin Packs That Installed Nothing
 
-**Status:** Completed
-**Completion:** 100%
-**Completed:** 2026-04-11
-**Created:** 2026-04-10
-**Origin:** Enterprise IP security requirements (air-gapped environments), cost-sensitive solo developers, and the growing adoption of local models (Ollama, LM Studio, llamafile). Current toolkit emits 20K+ token system prompts that exceed SLM context windows and degrade small model performance.
-**Estimated Effort:** 4-5 weeks (1 person)
+`csharp-pack`, `java-pack`, `kotlin-pack`, `ruby-pack`, `rust-pack`,
+`swift-pack`, `frontend-pack`, `research-pack`, `security-pack` — removed in
+v4.20.0. `memory-pack` and `enterprise-pack` stay.
 
----
+## The measurement
 
-## 1. Objective
+`ai-toolkit install` into a throwaway `HOME`, then `plugin install <pack>`, on
+each runtime. The number is what `plugin install` itself reports:
 
-Create a `--profile offline-slm` install profile and a `scripts/compile_slm.py` compiler that produces a minimal, high-signal instruction set optimized for Small Language Models (8B-32B parameters). The compiled output preserves critical safety guardrails while stripping agent orchestration, multi-agent coordination, and complex skill routing that SLMs cannot handle.
+| Pack | claude | codex |
+|---|---:|---:|
+| `csharp-pack` | 0 | 0 |
+| `java-pack` | 0 | 0 |
+| `kotlin-pack` | 0 | 0 |
+| `ruby-pack` | 0 | 0 |
+| `rust-pack` | 0 | 0 |
+| `swift-pack` | 0 | 0 |
+| `research-pack` | 0 | 0 |
+| `security-pack` | 0 | 0 |
+| `frontend-pack` | 0 | **1** |
+| **`memory-pack`** | **4** | **4** |
+| **`enterprise-pack`** | **2** | **2** |
+
+Cross-checked against the filesystem, not just the reported count: after core
+install (108 skills, 44 agents, 4742 characters of hook config), installing
+`rust-pack`, `security-pack`, `research-pack` or any language pack produced
+`+0` skills, `+0` agents, `+0` bytes of `settings.json` and `+0` files under
+`~/.softspark`.
+
+Profiles make no difference. `minimal`, `standard` and `strict` all install the
+same 108 skills and 44 agents, and packs add `+0` to each.
 
-**Key design principles:**
-- **Token budget** — compiled output fits within 4K tokens (system prompt), with optional 8K mode for larger SLMs
-- **Safety-preserved** — Constitution Articles I-V always included (non-negotiable)
-- **Single-agent focus** — no multi-agent orchestration, no /swarm, no /teams
-- **Deterministic compilation** — same input → same output, no LLM involved in compilation
-- **Model-aware** — detects model size from Ollama API or manual flag and adjusts verbosity
-- **Platform-agnostic** — outputs plain markdown consumable by any local inference engine
-- **Hooks stripped** — SLM providers don't support lifecycle hooks; rules compile into system prompt
+## Why
+
+Every one of the nine declared only assets that already ship in core:
+
+| Pack | Declared | All present in core? |
+|---|---|---|
+| `rust-pack` | `rust-patterns` | yes |
+| `security-pack` | `review`, `security-patterns`, `panic`, `security-auditor`, `security-architect`, `code-reviewer` | yes |
+| `research-pack` | `docs`, `research-mastery`, `plan`, `technical-researcher`, `fact-checker`, `search-specialist` | yes |
+
+Since `ai-toolkit install` links every core skill and agent, a manifest that
+names only core assets resolves to a set of things already installed. There is
+nothing left to do, so nothing is done.
+
+Eight of the nine owned no file but `README.md`. `security-pack`'s two hooks
+were core's `guard-destructive.sh` and `quality-gate.sh`; `research-pack`'s was
+core's `user-prompt-submit.sh`.
+
+## The one that was not quite zero
+
+`frontend-pack` installed exactly one file, on codex only:
+`plugin-frontend-pack-post-tool-use.sh`. The pack owned no such file — it
+declared core's `post-tool-use.sh`, which core's codex surface does not install,
+so the pack copied it in under a pack-prefixed name.
+
+That is a generic hook wearing a domain label, not frontend functionality. It
+was removed with the pack. **If `post-tool-use` should run on codex, it belongs
+in the core codex hook set**, and adding it there is a separate, honest change —
+not a side effect of installing a pack named after a UI framework.
+
+## The authoring rule that caused this
+
+`app/skills/plugin-creator/SKILL.md` told pack authors:
+
+> **MUST** reference existing toolkit assets before duplicating — packs extend,
+> they do not fork
+
+Read literally against a core install that ships everything, that instruction
+produces a no-op every time. It was correct about avoiding forks and silent
+about the pack needing to add anything. Nine packs followed it exactly.
+
+The rule now reads that a pack **must install something the core install does
+not**, with the verification spelled out, and the validation checklist carries a
+line item requiring a non-zero file count on every runtime the pack claims.
+
+## What survived, and what users lose
+
+**Nothing.** Every skill and agent the nine packs named is a core asset, still
+present, still installed, still triggering on the same conditions. A Rust
+developer who had `rust-pack` installed keeps `rust-patterns`, because it was
+never in the pack.
+
+The two remaining packs are the two that own files:
+
+- `memory-pack` — two hooks, `init_db.py`, `strip_private.py`, and its own
+  `mem-search` skill. Verified working the same day: driving
+  `observation-capture.sh` with a real payload wrote a row to the SQLite store.
+- `enterprise-pack` — `status-line.sh` and `output-style.sh`, both its own.
+
+## Process note
+
+The removal was nearly made on a wrong measurement. The first pass concluded
+"nine no-ops on every editor" after testing only four packs on the claude
+surface. `tests/test_plugin.bats` contradicted it by asserting that
+`frontend-pack` creates a file on codex — the test was right and the
+measurement was incomplete. The full 11 × 2 matrix was only then run.
+
+The existing test suite caught an error in a fresh measurement. That is worth
+remembering next time a test looks like it is merely in the way of a cleanup.
+
+## Related
+
+- [Plugin Pack Conventions](../../reference/plugin-pack-conventions.md) — the rule this postmortem installed
+- [Language Packs (removed)](language-packs-removed-20260727.md) — the reference doc for six of the nine
+- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — the pack removed the day before, for a different reason
+
+---
+
+## kb/history/completed/offline-slm-profile-plan-20260411.md
+
+---
+title: "Plan: Offline-First SLM Profile — Lightweight Mode for Local Models"
+category: planning
+service: ai-toolkit
+tags:
+  - offline
+  - slm
+  - small-language-models
+  - ollama
+  - lm-studio
+  - profile
+  - context-optimization
+  - privacy
+doc_type: plan
+status: completed
+created: "2026-04-10"
+last_updated: "2026-04-11"
+completion: "100%"
+completed: "2026-04-11"
+description: "Lightweight profile for ai-toolkit optimized for Small Language Models (SLMs) running locally via Ollama, LM Studio, or similar. Compiles a minimal instruction set that fits within 4K-8K system prompt budgets while preserving critical safety guardrails. Targets air-gapped, privacy-first, and cost-sensitive development workflows."
+---
+
+# Plan: Offline-First SLM Profile — Lightweight Mode for Local Models
+
+**Status:** Completed
+**Completion:** 100%
+**Completed:** 2026-04-11
+**Created:** 2026-04-10
+**Origin:** Enterprise IP security requirements (air-gapped environments), cost-sensitive solo developers, and the growing adoption of local models (Ollama, LM Studio, llamafile). Current toolkit emits 20K+ token system prompts that exceed SLM context windows and degrade small model performance.
+**Estimated Effort:** 4-5 weeks (1 person)
+
+---
+
+## 1. Objective
+
+Create a `--profile offline-slm` install profile and a `scripts/compile_slm.py` compiler that produces a minimal, high-signal instruction set optimized for Small Language Models (8B-32B parameters). The compiled output preserves critical safety guardrails while stripping agent orchestration, multi-agent coordination, and complex skill routing that SLMs cannot handle.
+
+**Key design principles:**
+- **Token budget** — compiled output fits within 4K tokens (system prompt), with optional 8K mode for larger SLMs
+- **Safety-preserved** — Constitution Articles I-V always included (non-negotiable)
+- **Single-agent focus** — no multi-agent orchestration, no /swarm, no /teams
+- **Deterministic compilation** — same input → same output, no LLM involved in compilation
+- **Model-aware** — detects model size from Ollama API or manual flag and adjusts verbosity
+- **Platform-agnostic** — outputs plain markdown consumable by any local inference engine
+- **Hooks stripped** — SLM providers don't support lifecycle hooks; rules compile into system prompt
 
 ---
 
@@ -4338,6 +4877,201 @@ designed for.
 
 ---
 
+## kb/history/completed/tool-output-token-reduction-closed-20260727.md
+
+---
+title: "Closed: Tool-Output Token Reduction — Three Attempts, One Ceiling"
+category: planning
+service: ai-toolkit
+tags:
+  - token-reduction
+  - measurement
+  - postmortem
+  - prompt-caching
+  - context-window
+  - closed-line-of-work
+doc_type: postmortem
+status: completed
+created: "2026-07-27"
+last_updated: "2026-07-27"
+description: "Closes the tool-output token-reduction line of work after a third measurement. Decomposes 1189 real sessions by cost: 84% is context being fed to the model, 14.7% is responses. Tool output is a small lever by construction and three independent attempts have now hit the same ceiling. Records what shipped (a 20.2% rag-mcp response trim, worth 0.49% of cost), what was killed by its own kill number, and the three measurement errors made on the way."
+---
+
+# Closed: Tool-Output Token Reduction
+
+**Read this before proposing a fourth attempt.**
+
+Three independent efforts have tried to cut tokens by shrinking what tools
+return. All three were competently built. All three measured out near zero.
+
+| Attempt | Shipped | Measured saving |
+|---|---|---:|
+| [Native tool-output filter](output-filter-retirement-20260726.md) | v4.16.0, removed v4.17.0 | **0.0000%** |
+| [rtk-pack](rtk-pack-retirement-20260727.md) | v4.18.0, removed v4.19.0 | **0.0615%** |
+| This review's only clean win (rag-mcp response trim) | rag-mcp, 2026-07-27 | **0.49%** |
+
+This is not three unlucky implementations. It is one structural fact, measured
+three different ways.
+
+## Where the money actually is
+
+1189 sessions with traffic, 83,352 assistant turns, priced at Opus list rates:
+
+| Component | Share of cost |
+|---|---:|
+| `cache_read` | **63.1%** |
+| `cache_creation` | 20.9% |
+| `output` | 14.7% |
+| `input` (uncached) | 1.3% |
+
+**84% of cost is feeding context to the model.** Responses are 14.7%. That
+closes "make the model write less" as a serious lever — the whole `brand-voice`
+concise mode plays for a seventh of the bill.
+
+Cache hit rate is **97.4%**. Published guidance treats 80–95% as the achievable
+band, so there is nothing to win in cache tuning either.
+
+Session shape: median 29 turns (mean 70.1), median peak context 71,276 tokens
+(mean 114,712), median startup context 22,175 tokens.
+
+## Why tool output cannot be the lever
+
+Decomposed by amplification — every tool result is re-read on every turn that
+follows it, so a result's true cost is its size times the turns remaining:
+
+| Category | Share of `cache_read` |
+|---|---:|
+| Fixed startup prelude | 12.4% |
+| `Read` results | 15.6% |
+| `Bash` results | 6.7% |
+| `rag-mcp` results | 3.8% |
+| Unattributed (assistant text, thinking, user messages, reminders) | ~61% |
+
+Every tool in the toolbox, amplified across every turn, is **26.1%** of
+`cache_read`, and it is not compressible without losing what it says. The
+original Phase 0 calculation reached the same place from the other direction:
+tool results are 4.54% of input-token volume, so 4.54% is the arithmetic
+ceiling for any mechanism operating on them.
+
+Raw tool-result bytes, 113 MB across 1308 session files:
+
+| Tool | Share of bytes |
+|---|---:|
+| `Read` | 62.2% |
+| `Bash` | 26.1% |
+| `rag-mcp` (3 tools) | 7.6% |
+| everything else | <2% each |
+
+## What shipped
+
+**rag-mcp response compaction** — `compact_payload()` in
+`app/rag-mcp-server/routes/kb_search.py`, applied to `smart_query`,
+`hybrid_search_kb` and `get_document`, plus both sides of the smart_query cache
+so a hit and a miss return identical bytes.
+
+Verified by running the shipped function over 1356 real responses captured from
+session logs: **20.2% smaller, with no field the agent acts on removed.**
+That is 0.77% of `cache_read`, **0.49% of total cost**.
+
+It drops request echo (`use_hyde`/`use_crag`/`use_multi_hop`), null result
+columns, `_from_cache: false`, `total_documents_used` when it equals the result
+count, and the part of `source_documents_used` that merely repeats
+`results[].kb_id`. It deliberately keeps `file_path` (addresses Read/Edit, where
+`kb_id` addresses get_document), `routing` (the only signal for which pipeline
+ran), `score: 0.0`, and empty result sets. 16 unit tests, most of them asserting
+what must survive rather than what gets removed.
+
+## What was killed, and by what
+
+A kill number was published before the work: *if the shipped changes do not cut
+`cache_read` by 3%, stop and do not proceed to the behavioural changes.*
+
+Result: **0.79%.** The threshold was not met, and the remaining items were not
+built. The kill number did its job — this is the first of the three attempts
+where it bound before code was written rather than after it shipped.
+
+## Three measurement errors, and what they cost
+
+Recorded because each one nearly produced a wrong decision, and because two of
+them are the same class of error that produced the previous two failures.
+
+**1. Duplicate reads: 11.1% was actually 0.1%.** The first pass keyed duplicate
+detection on `file_path` alone, counting re-reads of *different ranges* of the
+same file as waste. Re-keyed on `(file_path, offset, limit)`:
+
+| Key | Duplicates | Bytes | Share of `Read` |
+|---|---:|---:|---:|
+| path only (wrong) | 1754 | 7,787,530 | 11.1% |
+| path + offset + limit (right) | **36** | **90,975** | **0.1%** |
+
+A whole planned deliverable — a session-scoped dedup hook, with a designed
+mitigation for the post-compaction re-read hazard — rested on that 11.1%. It
+does not exist.
+
+**2. A 58% "trim" that was deleting document content.** An aggressive variant of
+the rag-mcp compaction measured 58% smaller. It was whitelisting top-level keys
+and thereby dropping `content` — which for `get_document` *is* the document,
+30.5% of all bytes those endpoints return. Not a trim; data loss that looked
+like a win. The honest figure is 20.2%.
+
+**3. "77.5% of the rag-mcp response is overhead."** Roughly half of that
+non-content mass is `kb_id`, `file_path`, `title` and `score` — fields the agent
+uses. Removable overhead is about 20%, not 77%.
+
+The common thread: **every one of these errors made the opportunity look bigger
+than it is, and every one was caught only by decomposing before building.** The
+filter retirement drew the same conclusion about premise validation; rtk-pack
+drew it about installing the artifact. This adds a third: decompose the metric
+before trusting its headline.
+
+## What is left, and why it was not taken
+
+| Option | Value | Why not |
+|---|---:|---|
+| Model routing | tens of % | Ruled out by the maintainer — Opus 5 stays |
+| Trim the toolkit's own startup prelude | ~2.5% of cost | Ruled out — costs skill/agent discoverability |
+| `Read` with ranges instead of whole files | up to 10.4% of `cache_read` | The only remaining item of size, and **not quality-neutral**: it is a behavioural change whose effect on correctness cannot be measured automatically |
+| Unattributed ~61% of `cache_read` | unknown | Assistant text, thinking blocks, user messages, system reminders — no clean cut available |
+
+For the record, the startup prelude was measured rather than guessed. Median
+startup context is 22,175 tokens against ~7,850 in the documented reference
+shape, and the gap is the toolkit's own:
+
+| Component | Count | ~tokens |
+|---|---:|---:|
+| skill descriptions | 108 | 5,051 |
+| agent descriptions | 44 | 2,750 |
+| project rules | 5 | 3,802 |
+| global rules | 6 | 3,133 |
+| `CLAUDE.md` files | 3 | 2,338 |
+| **total** | | **17,076** |
+
+The tool built to reduce tokens is the single largest addition to every
+session's context. That is worth knowing, and it is still only 2.5% of cost,
+because the prelude is 12.4% of `cache_read` and only part of it is removable.
+
+## The rule this leaves behind
+
+**Do not open a fourth tool-output token-reduction effort without first
+producing a measurement that beats 4.54%.** That is the ceiling on this workload
+and it has now been approached from three directions. Any proposal in this space
+must state, before any code, which share of *input token volume* it addresses —
+not which share of tool output, not which share of Bash bytes.
+
+If token cost genuinely needs to come down, the levers that are actually large
+are model selection and turn count. Both are policy decisions, not engineering
+projects, and neither is in this line of work.
+
+## Related
+
+- [Output Filter Retirement](output-filter-retirement-20260726.md) — attempt one, 0.0000%
+- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — attempt two, 0.0615%
+- [rtk Pack Integration](rtk-pack-integration-20260726.md) — the Phase 0 ceiling calculation
+- [MCP Context Trim v4.0 — abandoned](mcp-context-trim-v4-prd-obsoleted-20260727.md) — a fourth idea in this space, killed by the platform shipping the fix first
+- [Output & Token Discipline](output-token-discipline-plan-20260504.md) — the plan all of this descends from
+
+---
+
 ## kb/howto/README.md
 
 ---
@@ -5438,354 +6172,90 @@ Examples:
 3. **AWS credential scope too broad** — User provides admin-level AWS profile. Mitigation: `credentials test` checks actual permissions, WARN if write access detected, suggest read-only IAM policy in docs.
 4. **Three providers = 3x maintenance** — Each provider's CLI evolves independently. Mitigation: abstract provider interface, single test matrix, version tracking per provider.
 5. **Terraform parsing incomplete** — HCL syntax is complex (modules, variables, conditionals). Mitigation: wrap `terraform show -json` instead of parsing HCL. Fallback to flat regex for projects without `terraform` CLI.
-6. **SARIF adoption low** — Users may not know how to use SARIF with GitHub. Mitigation: provide copy-paste GitHub Actions workflow in docs and `--explain` for onboarding.
-
----
-
-## 12. Council Review Summary (2026-04-10)
-
-**Verdict:** CONDITIONAL FOR — implement with scope reduction.
-**Confidence:** MEDIUM (weighted score: FOR 3.1 vs AGAINST 2.9)
-
-**Key insights applied to this plan:**
-- [x] Timeline revised from 3-4 → 5-6 weeks
-- [x] ~~Azure deferred to Milestone 3~~ → **reinstated: full 3-provider delivery**
-- [x] SARIF v2.1.0 output added — essential for GitHub Advanced Security integration
-- [x] Incremental scan mode added (`--changed`) — how developers actually use security tools
-- [x] `terraform show -json` wrapper instead of HCL parsing — realistic path
-- [x] Single config file `.cloud-security.json` (merged ignore + context)
-- [x] `credentials init` interactive wizard — reduce onboarding friction
-- [x] `--explain <rule-id>` for on-demand remediation guidance
-- [x] Static mode as default — zero-setup first experience
-
-**Deferred to v2:**
-- Kubernetes/container security (separate pack candidate)
-- Secret scanning with entropy detection
-- Compliance framework mapping (SOC2, PCI-DSS, NIST 800-53)
-- Visual security dashboard in browser
-- GitHub PR comment integration beyond SARIF
-- Vendored YAML subset parser for CloudFormation YAML static scanning
-
-**Council strongest agreement:** False positive resolver is the killer feature and primary differentiator vs Checkov/Trivy/Prowler. No existing tool combines deterministic scanning with context-aware resolution.
-
----
-
-## 13. Orchestration Review Summary (2026-04-10)
-
-**Agents:** tech-lead, security-architect, product-manager, code-reviewer (4 parallel)
-
-**Verdict:** Plan structurally complete (14/14 elements). Three P0 security blockers identified and resolved.
-
-**Applied changes:**
-
-| # | Action | Source | Priority | Applied? |
-|---|--------|--------|----------|----------|
-| 1 | Programmatic Bash allowlist | security-architect | P0 | Yes — allowlist.sh + agent integration |
-| 2 | CI hardening (mktemp/trap/SARIF validation) | security-architect | P0 | Yes — CI examples rewritten |
-| 3 | Suppression governance (justification + diff detection) | security-architect | P0 | Yes — schema + SUPPRESSION_CHANGED finding |
-| 4 | Recursive descent parser for Firestore | code-reviewer | P1 | Yes — replaced regex approach, +1d estimate |
-| 5 | SARIF `driver.rules[]` for GitHub annotations | code-reviewer | P1 | Yes — schema + success criteria |
-| 6 | Task 4.1→3.2 numbering fix | tech-lead | P1 | Yes — renumbered |
-| 7 | `terraform plan` execution risk documented | security-architect | P1 | Yes — only `show -json` allowed |
-| 8 | `credentials init` deferred to M2 | code-reviewer | P2 | Yes — saves 1.5d in M1 |
-| 9 | False positive resolver budgeted +2d/provider | code-reviewer | P2 | Yes — estimate updated |
-| 10 | `SUPPRESSION_CHANGED` finding type | security-architect | P2 | Yes — in governance section |
-
-**Market positioning (product-manager):**
-- Not competing with Checkov on check count (40 vs 3000)
-- Competing on: zero-noise (false positive resolver), zero-setup (static-first), IDE-native (10 platforms), AI interpretation
-- Target: developers in ai-toolkit ecosystem, not enterprise security teams
-- Value as ecosystem feature, not standalone product
-
-**Timeline revision (code-reviewer):**
-- 1 person: 6-7 weeks realistic (was 5-6)
-- 2 people: 4-5 weeks (parallel GCP + AWS tracks)
-- All 3 providers ship in 6 weeks — no conditional gates
-
----
-
-## 14. Next Actions
-
-1. [ ] Approve plan
-2. [ ] Implement `credentials` CLI command (1.1) + Bash allowlist
-3. [ ] Create `cloud-security-auditor` agent (1.2)
-4. [ ] Implement SARIF formatter + incremental scan (1.3)
-5. [ ] Implement `firebase-rules-audit` — recursive descent parser (2.1)
-6. [ ] Implement `cloud-functions-audit` + false positive resolver GCP (2.2, 2.3)
-7. [ ] Implement `aws-security-audit` + `terraform show -json` wrapper (3.1)
-8. [ ] Implement orchestrator + plugin pack + `credentials init` (3.2, 1.1b)
-9. [ ] Implement `azure-security-audit` + false positive resolver Azure (4.1)
-10. [ ] Full test suite (70+) + documentation + release
-
----
-
-**Last Updated:** 2026-04-10
-**Council Reviewed:** 2026-04-10
-**Orchestration Reviewed:** 2026-04-10 (4 agents: tech-lead, security-architect, product-manager, code-reviewer)
-
----
-
-## kb/planning/drop-cascade-hooks-after-sunset.md
-
----
-title: "Plan: Drop Cascade hooks after 2026-07-01 sunset"
-category: planning
-service: ai-toolkit
-tags:
-  - windsurf
-  - devin
-  - cascade
-  - hooks
-  - deprecation
-  - cleanup
-doc_type: plan
-status: completed
-created: "2026-06-10"
-last_updated: "2026-07-10"
-completion: "100%"
-trigger_date: "2026-07-01"
-description: "Completed cleanup of the deprecated Windsurf Cascade hooks generator after the 2026-07-01 sunset; Devin CLI .devin/hooks.v1.json is now the sole live hook surface."
----
-
-# Plan: Drop Cascade hooks after 2026-07-01 sunset
-
-**Completed in v4.13.0 (2026-07-10).** The deprecated generator and install/test wiring were removed; the Devin hook generator remains.
-
-## Why this exists
-
-Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its
-`.windsurf/hooks.json` hook surface (`agent_action_name`/`tool_info` format) — is
-available **only through 2026-07-01**. Devin Local / Devin CLI do **not** read
-`.windsurf/hooks.json` as a fallback.
-
-v4.8.0 already shipped the replacement: `generate_devin_hooks.py` emits
-`.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses. During the
-transition **both** generators run at `profile=full` so pre-sunset Cascade users
-keep working. After 2026-07-01 the Cascade half is dead code and must be removed
-(Constitution Art. VI.1 — no dead code).
-
-## Trigger
-
-First ai-toolkit release **on or after 2026-07-01**. Do NOT do this earlier —
-removing it before the sunset breaks Cascade users who are still on the old agent.
-
-## Scope — remove the Cascade hooks surface
-
-1. **Delete the generator:** `scripts/generate_windsurf_hooks.py`.
-2. **Unwire the install step:** in `scripts/install_steps/ai_tools.py`, remove the
-   `_try_generator("generate_windsurf_hooks", cwd)` call (keep
-   `generate_devin_hooks`). Update the `profile=full` dry-run message to drop
-   `.windsurf/hooks.json (Cascade, deprecated)`.
-3. **Tests:** remove the windsurf-`.windsurf/hooks.json` cases from
-   `tests/test_hooks_per_editor.bats` (output path, valid JSON, source tag,
-   `$HOME` prefix, idempotence, user-preservation, `pre_write_code` coverage) and
-   the `profile=full` assertion in `tests/test_install_profiles.bats`
-   (`windsurf + full emits .windsurf/hooks.json`). Keep all `.devin/hooks.v1.json`
-   tests. Adjust the README test-count badge to the new total.
-4. **Registry:** in `scripts/ecosystem_tools.json` (windsurf entry), remove
-   `scripts/generate_windsurf_hooks.py` from `our_generators`; keep
-   `.windsurf/hooks.json` out of `config_paths` (it was never listed). Trim the
-   `status_note` hooks-migration paragraph to past tense ("Cascade hooks removed
-   in vX.Y.Z").
-5. **Docs:** in `kb/reference/supported-tools-registry.md` drop the
-   `generate_windsurf_hooks.py` row and the "drop after 2026-07-01" note; in
-   `kb/reference/hooks-catalog.md` remove the Cascade row from the
-   Per-Editor Native Hooks table and the deprecation wording, leaving the Devin CLI
-   section as the windsurf-family hook surface.
-6. **validate.py:** the `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` mapping STAYS —
-   it is what keeps the `devin` hook generator counted as windsurf hooks in the
-   README-honesty check after the Cascade generator is gone.
-7. **CHANGELOG / version:** minor bump, `Removed` entry, regen artifacts, full
-   release-preparation SOP gate.
-
-## Verification
-
-- `python3 scripts/validate.py --strict` — 0/0 (editor-hooks-honesty must still
-  report windsurf as hook-enabled via the `devin` generator alias).
-- `python3 scripts/ecosystem_doctor.py --offline --check` — exit 0.
-- `npm test` — 0 `not ok`; no test recreates the deleted
-  `generate_windsurf_hooks.py` generator.
-- `grep -rn "generate_windsurf_hooks" scripts/ tests/` returns nothing
-  (Art. VI.1 orphan check — the deleted generator is fully unwired).
-  `.windsurf/hooks.json` intentionally remains referenced by the one-time
-  migration/strip cleanup (`scripts/install_steps/ai_tools.py`) and its test,
-  and in narrative docs (CHANGELOG, README, `kb/`, docstrings).
-
-## Do NOT touch
-
-- `generate_devin_hooks.py` and `.devin/hooks.v1.json` — the live replacement.
-- The `.devin/`/`.windsurf/` rules + skills dual-emit (that fallback persists as
-  long as Devin Desktop reads legacy `.windsurf/` paths; this plan is hooks-only).
-
-## Related
-
-- `kb/reference/hooks-catalog.md` — Per-Editor Native Hooks + Devin CLI section
-- `kb/reference/supported-tools-registry.md` — windsurf entry, hooks-migration row
-- `kb/procedures/ecosystem-sync-sop.md` — class-D deprecation workflow
-- `scripts/ecosystem_tools.json` — windsurf `status_note`
-
----
-
-## kb/planning/mcp-context-trim-v4-prd.md
-
----
-title: "PRD: MCP Context Trim v4.0 — Local Proxy with Description Compression"
-category: planning
-service: ai-toolkit
-tags:
-  - mcp
-  - proxy
-  - tool-descriptions
-  - jsonrpc
-  - tokens
-  - v4
-doc_type: plan
-status: proposed
-created: "2026-05-04"
-last_updated: "2026-05-04"
-completion: "0%"
-target_milestone: "v4.0"
-predecessor:
-  - "kb/history/completed/output-token-discipline-plan-20260504.md"
-  - "kb/history/completed/f2-mcp-trim-spike-20260504.md"
-description: "Local MCP proxy server that compresses tool descriptions before they reach the model. Carved out of the v3.2.0 output-token-discipline plan (Feature 2), deferred after the 2026-05-04 spike showed Claude Code hooks cannot modify tools/list metadata. Targets ~8-15k token reduction per session for users with many MCP servers."
----
-
-# PRD: MCP Context Trim v4.0
-
-**Status:** Proposed
-**Target milestone:** v4.0
-**Carved out of:** [`output-token-discipline-plan-20260504.md`](../history/completed/output-token-discipline-plan-20260504.md) (was Feature 2)
-**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](../history/completed/f2-mcp-trim-spike-20260504.md)
-
-## Problem
-
-MCP server tool descriptions are injected into every model turn's system prompt. With ~100 tools across 7 typical servers, descriptions consume 8–15k tokens per turn — pure overhead, paid every message. Examples observed in users' configs:
-
-- `dart-mcp-server` — ~30 tools with multi-paragraph descriptions
-- `filesystem` — verbose paths and example sections
-- `pencil` — "IMPORTANT" stanzas repeated across tools
-- `jira-mcp` — long `Use this tool to…` boilerplate
-
-The v3.2.0 output-discipline plan attempted to solve this with a hook-based trimmer. The spike conducted 2026-05-04 proved Claude Code hooks do not expose `tools/list` metadata or the system-prompt tool catalog. The only viable architecture is a local MCP proxy.
-
-## Goal
-
-Reduce MCP-description overhead by ≥40% per server, with **zero** loss of parameter schemas, required fields, or discrimination signals (`not`, `never`, `only`, `except`, `unless`).
-
-## Non-goals
-
-- Modifying tool **call** behavior (only descriptions)
-- Compressing user-facing prompts or completions
-- Replacing or rewriting upstream MCP servers
-- Touching MCP servers we do not control
-
-## Architecture
-
-### Proxy topology
-
-```
-Claude Code  ──stdio──▶  ai-toolkit MCP proxy  ──stdio/SSE──▶  upstream MCP server
-                                │
-                                └─ rewrites tools/list response
-                                   passes through tools/call unchanged
-```
-
-One proxy process per upstream server, supervised by `ai-toolkit mcp-trim daemon` (or equivalent). User's `~/.claude/.mcp.json` is rewritten by `ai-toolkit install` (opt-in) to point Claude Code at the proxy instead of upstream — proxy reads the original target from a sidecar config.
-
-### Required components
-
-| Component | Purpose |
-|-----------|---------|
-| `scripts/mcp_proxy_server.py` | JSON-RPC 2.0 proxy. Reads stdin, forwards to upstream over stdio or SSE, intercepts `tools/list` response, rewrites descriptions. Stdlib-only. |
-| `scripts/mcp_description_trimmer.py` | Pure function library: `trim(description: str) → str`. Reused from heuristics below. Stdlib-only. |
-| `scripts/mcp_proxy_config.py` | Reads `~/.softspark/ai-toolkit/mcp-proxy/servers.json`, validates upstream targets, generates supervisord/launchd config. |
-| `app/hooks/mcp-proxy-health.sh` | SessionStart hook — verifies all configured proxies responsive; fall through (warn, do not block) if any down. |
-| `app/skills/mcp-trim/SKILL.md` | Knowledge skill: how to enable, opt out, audit savings. |
-| `bin/ai-toolkit-mcp-trim` | CLI: `enable`, `disable`, `status`, `audit` (per-server token savings report). |
-| `tests/test_mcp_proxy.bats` | Integration tests with mock upstream MCP servers. |
-| `tests/test_mcp_trimmer.bats` | Unit tests for description trim heuristics on captured fixtures. |
-
-### Compression heuristics (from spike)
-
-Applied to each tool description in `tools/list` response:
+6. **SARIF adoption low** — Users may not know how to use SARIF with GitHub. Mitigation: provide copy-paste GitHub Actions workflow in docs and `--explain` for onboarding.
 
-- Drop example sections >40 chars
-- Collapse `Use this server to…` / `Use this tool to…` boilerplate to minimum form preserving intent
-- Drop duplicate occurrences of tool name in its own description
-- **Preserve bytewise:** `inputSchema.properties[*].description`, `required`, `enum` values, URL/path identifiers
-- **Never strip:** the words `not`, `never`, `only`, `except`, `unless` — these carry "when NOT to use" signals
-- Target: ≥40% length reduction, 0% schema loss
+---
 
-### Failure modes & rollback
+## 12. Council Review Summary (2026-04-10)
 
-| Scenario | Behavior |
-|----------|----------|
-| Proxy crashes mid-session | `mcp-proxy-health.sh` detects on next SessionStart, prints warning, suggests `ai-toolkit mcp-trim disable <server>` |
-| Upstream MCP server changes its tool catalog | Proxy passes through unchanged tools (no cached schema), warns once if a tool's description was previously trimmed |
-| Trimmer produces malformed JSON | Proxy falls through to upstream response unchanged, logs to `~/.softspark/ai-toolkit/mcp-proxy/error.log` |
-| User wants to bypass | `AI_TOOLKIT_MCP_TRIM_DISABLE=1` env var → proxies pass everything through unchanged |
-| User wants to fully uninstall | `ai-toolkit mcp-trim disable` reverts `~/.claude/.mcp.json` to original upstream targets |
+**Verdict:** CONDITIONAL FOR — implement with scope reduction.
+**Confidence:** MEDIUM (weighted score: FOR 3.1 vs AGAINST 2.9)
 
-### Migration of existing user `.mcp.json`
+**Key insights applied to this plan:**
+- [x] Timeline revised from 3-4 → 5-6 weeks
+- [x] ~~Azure deferred to Milestone 3~~ → **reinstated: full 3-provider delivery**
+- [x] SARIF v2.1.0 output added — essential for GitHub Advanced Security integration
+- [x] Incremental scan mode added (`--changed`) — how developers actually use security tools
+- [x] `terraform show -json` wrapper instead of HCL parsing — realistic path
+- [x] Single config file `.cloud-security.json` (merged ignore + context)
+- [x] `credentials init` interactive wizard — reduce onboarding friction
+- [x] `--explain <rule-id>` for on-demand remediation guidance
+- [x] Static mode as default — zero-setup first experience
 
-`ai-toolkit mcp-trim enable` does:
+**Deferred to v2:**
+- Kubernetes/container security (separate pack candidate)
+- Secret scanning with entropy detection
+- Compliance framework mapping (SOC2, PCI-DSS, NIST 800-53)
+- Visual security dashboard in browser
+- GitHub PR comment integration beyond SARIF
+- Vendored YAML subset parser for CloudFormation YAML static scanning
 
-1. Backup `~/.claude/.mcp.json` → `~/.softspark/ai-toolkit/mcp-proxy/.mcp.json.bak.<timestamp>`
-2. Read each server entry, store in `~/.softspark/ai-toolkit/mcp-proxy/servers.json`
-3. Rewrite each entry to point at the local proxy (with sidecar `target` field)
-4. Spawn supervisor (per-OS: launchd on macOS, systemd on Linux, scheduled task on Windows)
-5. Verify each upstream reachable via proxy, abort + restore backup on any failure
+**Council strongest agreement:** False positive resolver is the killer feature and primary differentiator vs Checkov/Trivy/Prowler. No existing tool combines deterministic scanning with context-aware resolution.
 
-## Out-of-scope decisions (rejected mid-spike)
+---
 
-| Option | Why rejected |
-|--------|--------------|
-| Pre-install rewrite of `.mcp.json` only | MCP spec sources descriptions from server runtime, not config — wouldn't take effect |
-| Source-side forks of MCP servers | Doesn't help users with custom servers; high maintenance |
-| F2-lite observability tool | User decision 2026-05-04: tracking token waste without trimming is half-value; do the full thing in v4.0 |
-| Hook-based interception | Spike proved hooks cannot reach `tools/list` |
+## 13. Orchestration Review Summary (2026-04-10)
 
-## Success criteria
+**Agents:** tech-lead, security-architect, product-manager, code-reviewer (4 parallel)
 
-- ≥40% description-length reduction per server on the captured fixture set (jira, filesystem, dart, pencil)
-- Deep-equal `inputSchema` between trimmed and upstream — zero schema regression
-- Proxy adds <50ms per `tools/list` call (one-time per session)
-- Proxy adds <5ms per `tools/call` (passthrough overhead)
-- Round-trip correctness: every tool callable via proxy returns byte-identical result vs direct call
-- Zero MCP-skill regressions in `npm test` after enabling proxy in CI
-- Rollback (`ai-toolkit mcp-trim disable`) restores byte-identical original `.mcp.json`
+**Verdict:** Plan structurally complete (14/14 elements). Three P0 security blockers identified and resolved.
 
-## Open questions
+**Applied changes:**
 
-1. Process supervision per-OS — launchd / systemd / scheduled-task wrappers, or a built-in `ai-toolkit-mcp-trimd` daemon binary?
-2. SSE-mode upstreams (e.g., rag-mcp at `http://localhost:8081/mcp/sse`) — proxy listens on SSE locally too, or stdio-only with internal SSE client?
-3. Description rewrites — static dictionary of "boilerplate phrases to drop" (faster, deterministic) vs LLM-based summarizer (more aggressive, less predictable)? Recommend static for v4.0, LLM as v4.1 stretch.
-4. Config path — `~/.softspark/ai-toolkit/mcp-proxy/` (matches existing convention) or `~/.claude/mcp-proxy/` (closer to MCP config)? Recommend the former.
-5. Telemetry — does this become an opt-in metric in `/briefing --tokens` ("MCP descriptions: 12.3k → 7.2k, saved 5.1k per turn")? Recommend yes.
+| # | Action | Source | Priority | Applied? |
+|---|--------|--------|----------|----------|
+| 1 | Programmatic Bash allowlist | security-architect | P0 | Yes — allowlist.sh + agent integration |
+| 2 | CI hardening (mktemp/trap/SARIF validation) | security-architect | P0 | Yes — CI examples rewritten |
+| 3 | Suppression governance (justification + diff detection) | security-architect | P0 | Yes — schema + SUPPRESSION_CHANGED finding |
+| 4 | Recursive descent parser for Firestore | code-reviewer | P1 | Yes — replaced regex approach, +1d estimate |
+| 5 | SARIF `driver.rules[]` for GitHub annotations | code-reviewer | P1 | Yes — schema + success criteria |
+| 6 | Task 4.1→3.2 numbering fix | tech-lead | P1 | Yes — renumbered |
+| 7 | `terraform plan` execution risk documented | security-architect | P1 | Yes — only `show -json` allowed |
+| 8 | `credentials init` deferred to M2 | code-reviewer | P2 | Yes — saves 1.5d in M1 |
+| 9 | False positive resolver budgeted +2d/provider | code-reviewer | P2 | Yes — estimate updated |
+| 10 | `SUPPRESSION_CHANGED` finding type | security-architect | P2 | Yes — in governance section |
 
-## Pre-mortem (failure scenarios to design against)
+**Market positioning (product-manager):**
+- Not competing with Checkov on check count (40 vs 3000)
+- Competing on: zero-noise (false positive resolver), zero-setup (static-first), IDE-native (10 platforms), AI interpretation
+- Target: developers in ai-toolkit ecosystem, not enterprise security teams
+- Value as ecosystem feature, not standalone product
 
-1. **Proxy gets out of sync with upstream** — upstream adds a new tool, proxy doesn't know how to compress it → passthrough that tool's description unchanged, log warning
-2. **Compression breaks tool discriminability** — model picks wrong tool because trimmed description lost the "use only when X" qualifier → the `not/never/only/except/unless` blacklist must be exhaustive; add per-server allowlists for false positives
-3. **Multi-process race on `.mcp.json` rewrite** — two `ai-toolkit install` invocations clobber each other → file lock during enable/disable
-4. **Proxy supervisor fails to start on user's machine** — different distro / no systemd → ai-toolkit doctor must detect and report; degrade to "MCP proxy unavailable, falling through" with no functionality loss
-5. **User has custom MCP server we don't recognize** — must work without per-server schema; default heuristics must be safe enough for arbitrary servers
+**Timeline revision (code-reviewer):**
+- 1 person: 6-7 weeks realistic (was 5-6)
+- 2 people: 4-5 weeks (parallel GCP + AWS tracks)
+- All 3 providers ship in 6 weeks — no conditional gates
 
-## Estimate
+---
 
-- Architecture spike + working proxy prototype: 2 days
-- Production proxy + supervisor + config + CLI: 3 days
-- Test suite + fixtures + CI integration: 2 days
-- Documentation + migration guide + release notes: 1 day
+## 14. Next Actions
 
-**Total: ~8 working days** (1.5–2 weeks calendar time at typical pace)
+1. [ ] Approve plan
+2. [ ] Implement `credentials` CLI command (1.1) + Bash allowlist
+3. [ ] Create `cloud-security-auditor` agent (1.2)
+4. [ ] Implement SARIF formatter + incremental scan (1.3)
+5. [ ] Implement `firebase-rules-audit` — recursive descent parser (2.1)
+6. [ ] Implement `cloud-functions-audit` + false positive resolver GCP (2.2, 2.3)
+7. [ ] Implement `aws-security-audit` + `terraform show -json` wrapper (3.1)
+8. [ ] Implement orchestrator + plugin pack + `credentials init` (3.2, 1.1b)
+9. [ ] Implement `azure-security-audit` + false positive resolver Azure (4.1)
+10. [ ] Full test suite (70+) + documentation + release
 
-## Status
+---
 
-| Date | Status | Author |
-|------|--------|--------|
-| 2026-05-04 | PRD drafted from spike conclusions, carved out of v3.2.0 plan | claude |
+**Last Updated:** 2026-04-10
+**Council Reviewed:** 2026-04-10
+**Orchestration Reviewed:** 2026-04-10 (4 agents: tech-lead, security-architect, product-manager, code-reviewer)
 
 ---
 
@@ -6770,10 +7240,10 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
-version: "1.11.2"
+version: "1.13.0"
 created: "2026-04-10"
 last_updated: "2026-07-27"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, the registry-vs-generators drift gate added in v1.10.0, and the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5)."
+description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, the registry-vs-generators drift gate added in v1.10.0, the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5), the pre-push tag assertions added in v1.12.0 after v4.19.0 was tagged on the wrong commit (Phase 7), and the licensing gate added in v1.13.0 with the move to Apache-2.0 (Phase 5c)."
 ---
 
 # SOP: Release Preparation
@@ -6832,10 +7302,20 @@ python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footpri
 # 5b. Ecosystem gate — snapshot must be current before tag
 python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }
 
+# 5c. Licensing gate — SPDX headers, LICENSE, NOTICE, manifest consistency
+npx bats tests/test_licensing.bats || { echo "LICENSING GATE FAILED"; exit 1; }
+
 # 6. Commit + tag + push
 git add -A && git commit -m "chore: release vX.Y.Z"
 git tag vX.Y.Z
-git push origin main --tags
+
+# 6a. Assert the tag before pushing it (v4.19.0 postmortem, Phase 7)
+test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)" || { echo "FAIL: tag not on HEAD"; exit 1; }
+git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" || { echo "FAIL: tag not on release commit"; exit 1; }
+
+# 6b. Branch first, then the single tag by full ref. Never --tags.
+git push origin main
+git push origin refs/tags/vX.Y.Z
 ```
 
 ---
@@ -7099,6 +7579,46 @@ python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci &&
 - Missing frontmatter → add to new KB docs
 - Broken symlink → `ai-toolkit doctor --fix`
 
+### Phase 5c: Licensing Gate (v4.20.0+)
+
+The project is Apache-2.0. Attribution only works if the artefact actually
+carries it, and every part of that is mechanically checkable.
+
+```bash
+# The whole gate, enforced in CI. Run it here so a failure is caught before tagging.
+npx bats tests/test_licensing.bats
+```
+
+The seven assertions, and why each exists:
+
+| Check | Fails when |
+|---|---|
+| Every shipped source file carries an SPDX header | A new `.py`/`.sh`/`.js`/`.bats` file was added without one — the common case, and the reason this is a test rather than a habit |
+| Headers name Apache-2.0 and nothing else | A file was copied in from an MIT/GPL source with its own header intact |
+| **No** markdown file carries an SPDX header | Someone "helpfully" ran the header script over `app/skills/` — headers there sit above parsed frontmatter and bill every session for it |
+| `LICENSE` is the complete Apache 2.0 text | The file was truncated or replaced with a summary |
+| `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice | The attribution mechanism was gutted |
+| `LICENSE` **and** `NOTICE` ship in the npm package | `package.json` `files` lost an entry — a NOTICE that never reaches the consumer cannot satisfy §4(d) |
+| Every manifest declaring a licence declares Apache-2.0 | `package.json`, `manifest.json`, `plugin.json` and `package-lock.json` drifted apart |
+
+**Adding source files in this release?** The header goes *after* the shebang,
+never before it. Short SPDX form:
+
+```
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+```
+
+`//` for JavaScript. Full convention and the reasoning behind the markdown
+exclusion: [Licensing](../reference/licensing.md).
+
+**Changing the licence itself?** Do not hand-type the licence text. Take it
+verbatim from a published copy and cross-verify against a second independent
+copy before writing `LICENSE` — a rendered or summarised licence is not the
+licence. Prior releases stay under their original terms; a licence change
+applies going forward and revokes nothing already granted.
+
 ### Phase 5a: Supply-Chain Hardening Verification (v2.8.0+)
 
 These checks enforce the security standard introduced in v2.8.0. Do NOT tag a release until all pass.
@@ -7172,8 +7692,33 @@ git commit -m "chore: release vX.Y.Z"
 
 ```bash
 git tag vX.Y.Z
-git push origin main --tags
-```
+
+# Assert the tag before pushing it. Both checks are one line each and both
+# have caught a real broken release.
+test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)" \
+  || { echo "FAIL: tag is not on HEAD"; exit 1; }
+git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" \
+  || { echo "FAIL: tag is not on the chore: release commit"; exit 1; }
+
+# Push the branch, then the single release tag by its full ref.
+git push origin main
+git push origin refs/tags/vX.Y.Z
+```
+
+**Why the assertions (v4.19.0 postmortem).** v4.19.0 was tagged on a commit
+that contained only a KB document and still carried `package.json` version
+`4.18.0`; the actual release sat in the commit above it under a recycled
+`fix:` message. `publish.yml` fired, tried to publish a version already on
+npm, and failed. Nothing on npm, a tag pointing at the wrong tree, and the
+only way out was rewriting a pushed commit. Both assertions above catch this
+in under a second. Run them.
+
+**Never `git push --tags`.** It pushes every local tag at once, and GitHub
+suppresses tag-triggered workflow runs when many tags arrive in a single push
+— the workflow silently does not fire and nothing publishes. Push the single
+release tag by its full ref, as above. (Sibling evidence: this is exactly how
+rag-mcp's `1.0.3` image build was skipped, when a `--tags` push carried 37
+tags at once.)
 
 This triggers `.github/workflows/publish.yml` which:
 1. Runs `validate.py --strict`
@@ -7227,10 +7772,13 @@ git push origin --delete vX.Y.Z
 | 13 | ShellCheck hooks | `shellcheck --severity=warning app/hooks/*.sh` | Exit 0, no output (mirrors ci.yml; publish.yml does NOT run it) |
 | 14 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
 | 15 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
+| 15a | Licensing gate | `npx bats tests/test_licensing.bats` | 7/7 — SPDX headers, LICENSE, NOTICE, npm `files`, manifest consistency |
 | 16 | Tests | `git add -A kb/` if the KB changed, then `npm test` | All pass |
 | 17 | Commit | `git commit` | Clean working tree |
 | 18 | Tag | `git tag vX.Y.Z` | Tag exists |
-| 19 | Push | `git push origin main --tags` | CI triggered with `id-token: write` |
+| 18a | Tag is on HEAD | `test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)"` | Exit 0 |
+| 18b | Tag is on the release commit | `git show --no-patch --format=%s vX.Y.Z` | Reads `chore: release vX.Y.Z` |
+| 19 | Push branch, then the single tag | `git push origin main && git push origin refs/tags/vX.Y.Z` | CI triggered with `id-token: write`. Never `--tags`. |
 
 ---
 
@@ -9245,7 +9793,7 @@ description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and
 | Session persistence | Yes | Yes | No | No |
 | Architecture notes | **Yes** | No | No | No |
 | KB/RAG integration | **Yes** | No | No | Yes |
-| License | MIT | MIT | MIT | MIT |
+| License | **Apache-2.0** (NOTICE attribution, change notices, patent grant) | MIT | MIT | MIT |
 
 For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).
 
@@ -10319,7 +10867,7 @@ Base configs can define non-overridable constraints via the `enforce` block:
 {
   "enforce": {
     "minHookProfile": "standard",
-    "requiredPlugins": ["security-pack"],
+    "requiredPlugins": ["memory-pack"],
     "forbidOverride": ["constitution", "guard-destructive"],
     "requiredAgents": ["security-auditor"]
   }
@@ -12052,63 +12600,6 @@ ai-toolkit add-rule ./jira-rules.md
 
 ---
 
-## kb/reference/language-packs.md
-
----
-title: "AI Toolkit - Language Plugin Packs"
-category: reference
-service: ai-toolkit
-tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby]
-version: "1.0.0"
-created: "2026-03-29"
-last_updated: "2026-03-29"
-description: "6 language-specific plugin packs providing knowledge skills for Rust, Java, C#, Kotlin, Swift, and Ruby."
----
-
-# Language Plugin Packs
-
-## Overview
-
-Language packs are domain-scoped plugin packs that provide knowledge skills for specific programming languages. Each pack contains a single knowledge skill with idiomatic patterns, error handling, testing conventions, common frameworks, and performance tips.
-
-## Available Packs
-
-| Pack | Skill | Language | Key Topics |
-|------|-------|----------|------------|
-| `rust-pack` | `rust-patterns` | Rust | Ownership, borrowing, Cargo, tokio, serde |
-| `java-pack` | `java-patterns` | Java | Records, sealed classes, Spring Boot, JUnit 5 |
-| `csharp-pack` | `csharp-patterns` | C# / .NET | Nullable refs, async/await, ASP.NET Core, EF Core |
-| `kotlin-pack` | `kotlin-patterns` | Kotlin | Coroutines, DSLs, sealed classes, Ktor, MockK |
-| `swift-pack` | `swift-patterns` | Swift / iOS | Protocol-oriented, SwiftUI, async/await, SPM |
-| `ruby-pack` | `ruby-patterns` | Ruby | Blocks, Rails conventions, RSpec, ActiveRecord |
-
-## Skill Content Sections
-
-Each language skill follows a consistent structure:
-
-1. **Project Structure** — standard directory layout and build tool configuration
-2. **Idioms / Code Style** — language-specific patterns and conventions
-3. **Error Handling** — error types, patterns, and best practices
-4. **Testing Patterns** — test frameworks, assertion libraries, mocking
-5. **Common Libraries / Frameworks** — ecosystem essentials
-6. **Performance Tips** — optimization techniques and profiling
-7. **Build / Package Management** — dependency management and CI
-
-## How Knowledge Skills Work
-
-These skills have `user-invocable: false` in their frontmatter, meaning they are NOT slash commands. Instead, Claude loads them contextually when the conversation topic matches the skill's description trigger.
-
-For example, when a user asks "How do I handle errors in Rust?", Claude automatically loads `rust-patterns` to provide idiomatic Rust error handling guidance.
-
-## Requesting New Language Packs
-
-File an issue with the `language-pack` label. Include:
-- Language name
-- Key topics to cover
-- Popular frameworks/libraries to include
-
----
-
 ## kb/reference/language-rules.md
 
 ---
@@ -12356,6 +12847,159 @@ Per-language content delivered as a knowledge skill is the same Markdown that ot
 
 ---
 
+## kb/reference/licensing.md
+
+---
+title: "Licensing"
+category: reference
+service: ai-toolkit
+tags: [licence, apache-2.0, spdx, notice, attribution, headers, mit]
+version: "1.0.0"
+created: "2026-07-27"
+last_updated: "2026-07-27"
+description: "ai-toolkit is Apache-2.0 from v4.20.0. What that obliges a redistributor to do, why NOTICE is the point, the SPDX header convention and which files deliberately do not get one, how MIT-era contributions are handled, and the CI gate that enforces all of it."
+---
+
+# Licensing
+
+ai-toolkit is licensed under the **Apache License 2.0** from v4.20.0. Releases up
+to and including v4.20.0 were published under MIT and remain available under MIT.
+The change applies going forward and revokes nothing already granted.
+
+Canonical files: [`LICENSE`](../../LICENSE) (verbatim Apache-2.0 text) and
+[`NOTICE`](../../NOTICE) (attribution).
+
+## Why Apache-2.0, given MIT already required attribution
+
+This is the part most often got wrong. MIT already says:
+
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+
+So attribution was never the new thing. What Apache-2.0 adds:
+
+| Mechanism | MIT | Apache-2.0 |
+|---|---|---|
+| Copyright notice must be preserved | yes | yes |
+| **`NOTICE` contents must travel into redistributions** (§4d) | — | **yes** |
+| **Modified files must carry a notice saying they changed** (§4b) | — | **yes** |
+| Express patent grant, terminated by patent litigation (§3) | — | yes |
+| No rights to the licensor's names or marks (§6) | — | yes |
+
+**`NOTICE` is the reason for the change.** It is the only mechanism in a
+permissive licence that forces a redistributor to reproduce your attribution —
+project name, copyright, source URL — somewhere their users can see it. Without
+it, MIT and Apache-2.0 are close to equivalent in practice.
+
+Consequence for packaging: `NOTICE` is listed in `package.json` `files`. A NOTICE
+that does not reach the consumer cannot satisfy §4(d), so that entry is a
+licensing requirement, not housekeeping, and is asserted in CI.
+
+## What a fork owes
+
+Fork it, modify it, ship it commercially. Three obligations:
+
+1. **Carry the `NOTICE`** into your distribution (§4d).
+2. **Say which files you changed** (§4b).
+3. **Do not use the "ai-toolkit" or "SoftSpark" names or marks** as if endorsed (§6).
+
+## Source header convention
+
+Short SPDX form, three lines, always **after** the shebang — an interpreter
+directive must stay on line 1 — and after a Python `coding:` line if present:
+
+```bash
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+#
+# guard-path.sh — the file's own description continues here.
+```
+
+`//` for JavaScript. SPDX was chosen over the 13-line Apache APPENDIX boilerplate
+because it is machine-readable — licence scanners, GitHub and SBOM tooling parse
+it — and because 13 lines on top of every source file buries the description that a
+reader of a hook actually needs.
+
+### Which files get a header
+
+| Included | Count |
+|---|---:|
+| `scripts/**/*.py` | 109 |
+| `tests/*.bats` | 77 |
+| `app/hooks/*.sh` | 32 |
+| `app/skills/**/*.py`, `**/*.js` | 27 |
+| `app/plugins/**/*.sh`, `**/*.py` | 6 |
+| `bin/*.js`, `benchmarks/**/*.py` | 2 |
+| **total** | **253** |
+
+These are a snapshot, not a contract — the CI gate checks that *every* matching
+file has a header, so the count moves with the codebase and nothing needs
+updating here when it does.
+
+### Which files deliberately do not, and why
+
+**No markdown file carries a header.** Not `app/skills/*/SKILL.md`, not
+`app/agents/*.md`, not `app/rules/`, not `kb/`. Two reasons, both concrete:
+
+1. **Frontmatter.** Skill and agent files open with parsed YAML. A header above
+   it breaks parsing; a header below it is invisible where it matters.
+2. **Token cost.** Skill and agent descriptions load into the system prompt of
+   every session — measured at 5,051 and 2,750 tokens respectively. A four-line
+   header across 108 skills and 45 agents would be a permanent per-session cost,
+   billed on every conversation forever, for a notice Apache only *recommends*.
+   `LICENSE` and `NOTICE` carry the full terms; the headers are a convenience.
+
+This exclusion is asserted in CI, so a well-meant sweep of the header script over
+`app/skills/` fails the build rather than silently taxing every session.
+
+## MIT-era contributions
+
+Contributions made while the project was MIT-licensed remain the copyright of
+their authors and were received under MIT terms. Three contributors other than
+the maintainer appear in the history.
+
+MIT explicitly permits sublicensing, so those contributions are redistributed
+here under Apache-2.0 **with the original MIT notice preserved verbatim** in
+`NOTICE`, which is what MIT requires. This is standard practice for an MIT to
+Apache-2.0 move and needs no contributor sign-off. A "clean" Apache-2.0 with no
+MIT remnant would need each contributor's agreement.
+
+*This is a description of what the project does, not legal advice.*
+
+## Enforcement
+
+`tests/test_licensing.bats`, seven assertions, run by `npm test` in CI:
+
+- every shipped source file carries an SPDX header
+- headers name Apache-2.0 and nothing else
+- **no** markdown file carries a header
+- `LICENSE` is the complete Apache 2.0 text, appendix included
+- `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice
+- `LICENSE` and `NOTICE` both appear in `package.json` `files`
+- every manifest declaring a licence declares Apache-2.0
+
+It is a test rather than a checklist line on purpose. This project has two
+same-day postmortems about SOPs that existed and were skipped; CI does not skip.
+[Release Preparation](../procedures/release-preparation-sop.md) Phase 5c runs the
+same gate before tagging so a failure surfaces before the tag, not after.
+
+## If the licence ever changes again
+
+Do not hand-type the licence text and do not paste a rendered copy — a
+markdown-formatted licence is not the licence. Take it verbatim from a published
+source, cross-verify against a second independent copy, and only then write
+`LICENSE`. That is how the Apache-2.0 text in this repository was installed.
+
+## Related
+
+- [`LICENSE`](../../LICENSE), [`NOTICE`](../../NOTICE)
+- [Release Preparation SOP](../procedures/release-preparation-sop.md) — Phase 5c
+- [Distribution Model](distribution-model.md) — what ships and where
+
+---
+
 ## kb/reference/manifest-install.md
 
 ---
@@ -13670,22 +14314,30 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 
 ## Current Experimental Packs
 
-| Pack | Domain | Agents | Skills | Hooks | Description |
-|------|--------|--------|--------|-------|-------------|
-| `security-pack` | security | 3 | 3 | 2 | Security auditing, threat modeling, OWASP |
-| `research-pack` | research | 4 | 4 | 1 | Multi-source research, synthesis, fact-checking |
-| `frontend-pack` | frontend | 3 | 3 | 1 | React/Vue/CSS, SEO, design engineering |
-| `enterprise-pack` | enterprise | 3 | 3 | 3 | Executive briefings, infra architecture, status |
-| `memory-pack` | memory | 0 | 1 | 2 | SQLite persistent memory with FTS5 search |
-| `rust-pack` | rust | 0 | 1 | 0 | Rust patterns |
-| `java-pack` | java | 0 | 1 | 0 | Java patterns |
-| `csharp-pack` | csharp | 0 | 1 | 0 | C# patterns |
-| `kotlin-pack` | kotlin | 0 | 1 | 0 | Kotlin patterns |
-| `swift-pack` | swift | 0 | 1 | 0 | Swift patterns |
-| `ruby-pack` | ruby | 0 | 1 | 0 | Ruby patterns |
-
-Every pack here is content that ships in this repository. None fetches anything
-at install time.
+| Pack | Domain | Owns | Installs (claude / codex) | Description |
+|------|--------|------|---------------------------|-------------|
+| `memory-pack` | memory | 2 hooks, 2 scripts, 1 skill | 4 / 4 files | SQLite persistent memory with FTS5 search |
+| `enterprise-pack` | enterprise | 2 hooks | 2 / 2 files | Status-line and output-style overlays |
+
+Both packs ship content in this repository. Neither fetches anything at install
+time.
+
+### The rule the table now enforces
+
+**A pack must install files the core install does not.** `ai-toolkit install`
+links every core skill and agent, so a manifest naming only core assets resolves
+to nothing: `plugin install` reports `(0 file items)` and no file appears on
+disk. This is not a subtle degradation — it is a complete no-op, identical on
+every profile (`minimal`, `standard`, `strict`) and on both runtimes.
+
+Nine packs were removed in v4.20.0 for failing this: `csharp`, `java`, `kotlin`,
+`ruby`, `rust`, `swift`, `frontend`, `research`, `security`. Every one declared
+only skills and agents that already ship in core, and eight of them owned nothing
+but a `README.md`. Full measurement:
+[`no-op-plugin-packs-removed-20260727.md`](../history/completed/no-op-plugin-packs-removed-20260727.md).
+
+Before adding a pack, prove it does something: install core into a throwaway
+`HOME`, install the pack, and check that the reported file count is above zero.
 
 **A pack that downloads a binary has been tried once and retired.** `rtk-pack`
 (v4.18.0, removed in v4.19.0) fetched a checksum-pinned artifact in