@softspark/ai-toolkit 3.1.1 → 3.2.0

package/llms-full.txt

@@ -16,9 +16,12 @@
 - [Plan: Deep Coverage v3.0 — 100% Native Surface Utilization](kb/history/completed/deep-coverage-v3-20260423.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)
 - [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
+- [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.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: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
 - [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
@@ -71,7 +74,7 @@
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
 - **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
-- **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
+- **brand-voice**: Loaded when writing documentation, content, README, or user-facing text, AND when an output-mode is set for conversational responses. Prevents generic LLM rhetoric, enforces direct technical voice, and supplies optional concise/strict response modes.
 - **briefing**: Generate an executive daily briefing that aggregates reports from all agents into a short, decision-focused summary. Use when the user asks for a status update across the whole system — not for one-agent activity reports.
 - **build**: Build the project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Use when the user asks to compile, bundle, or produce artifacts — not to run tests or deploy.
 - **chaos**: Inject controlled faults for resilience testing on non-production targets. Use when the user explicitly asks for a chaos experiment, latency injection, or dependency kill — never implicit.
@@ -217,7 +220,7 @@
 - **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
 - **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
 - **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
-- **seo-specialist**: Search engine optimization specialist. Trigger words: SEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org
+- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
 - **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
 - **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
 - **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
@@ -1652,6 +1655,128 @@ This plan shares modification targets with the Offline SLM plan:
 
 ---
 
+## kb/history/completed/f2-mcp-trim-spike-20260504.md
+
+---
+title: "Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision"
+category: planning
+service: ai-toolkit
+tags:
+  - mcp
+  - hooks
+  - claude-code
+  - spike
+  - feasibility
+doc_type: spike
+status: completed
+created: "2026-05-04"
+last_updated: "2026-05-04"
+completed: "2026-05-04"
+shipped_in: "v3.2.0 (decision only — implementation deferred to v4.0)"
+description: "Spike conclusion for Feature 2 of the output-token-discipline plan. Determines whether Claude Code hooks can modify MCP tool descriptions before they reach the LLM. Result: hooks operate per-call, not on tool list metadata. Full feature requires an MCP proxy server (multi-day scope). Outcome: F2 deferred to v4.0 with own dedicated PRD."
+---
+
+# Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision
+
+## Question
+
+Can Claude Code's hook system modify MCP **tool descriptions** that get included in the model's system prompt, or do hooks only intercept individual tool **calls**?
+
+## Method
+
+Reviewed local sources only (RAG MCP offline at spike time):
+
+1. `app/skills/hook-creator/SKILL.md` — exhaustive list of supported hook events and their data shapes
+2. `app/hooks/guard-destructive.sh`, `app/hooks/guard-path.sh` — actual examples reading `tool_input` from stdin
+3. `app/skills/mcp-builder/SKILL.md` — MCP server-side conventions
+4. `~/.claude/.mcp.json` — user's installed MCP servers (Context7, sequential-thinking, filesystem, rag-mcp, memory, jira-mcp)
+
+## Findings
+
+### Hook events that touch tool data
+
+| Event | Modifies tool list? | Modifies tool input? | Notes |
+|-------|--------------------|--------------------|-------|
+| `PreToolUse` | no | no (only block via exit 2) | Reads `tool_input.*`, decides allow/deny |
+| `PostToolUse` | no | no | Sees result for logging / feedback |
+| `PermissionRequest` | no | yes (`updatedInput`) | Can rewrite a single call's args |
+| `Elicitation` | no | n/a | Intercepts MCP UI prompts, not tool list |
+| `SessionStart` | no | n/a | Context injection only |
+| `InstructionsLoaded` | no | n/a | Verifies CLAUDE.md presence |
+
+**No event exposes the MCP `tools/list` response or the system-prompt tool catalog**. The tool catalog is materialized once per MCP server connection from the server's own `tools/list` reply.
+
+### Why this matters
+
+The compression target was the bulk of MCP tool descriptions sitting in every model turn's system prompt. Examples from the user's installed servers:
+
+- `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
+
+At ~100 tools across 7 servers in this user's config, easily 8–15k tokens of pure description text. Real waste, but Claude Code does not let a hook touch it.
+
+### What would actually work
+
+To compress MCP tool descriptions before they reach the LLM, exactly two architectures are viable:
+
+1. **Local MCP proxy server** between Claude Code and each target server. The proxy re-implements `tools/list` to rewrite descriptions on the fly while passing through `tools/call`. Requires JSON-RPC 2.0 over stdio + SSE per server, per-server config in `~/.claude/.mcp.json`, and a process supervisor for the proxies. Multi-day scope. Failure mode: a buggy proxy breaks all MCP-dependent skills.
+2. **Source-side fork**: ship pre-trimmed copies of common MCP servers (`@softspark/jira-mcp-trim`, etc.) — high maintenance burden, doesn't help users with custom servers.
+
+Neither is a "minimal change" by the standards of this plan.
+
+## Decision (final, 2026-05-04)
+
+**Drop F2 from v3.2.0 entirely. Defer the full MCP proxy approach to v4.0** with its own dedicated PRD and architecture spike.
+
+The spike originally surfaced a smaller "F2-lite observability tool" alternative (read-only inventory + suggestions). After review, the user chose to drop both options from v3.2.0:
+
+- v3.2.0 ships F1 + F3 + F3.5 only (output modes, token telemetry, default statusline)
+- F2 work — including any observability-first prototype — moves wholesale to v4.0 milestone
+- Reasoning: keep v3.2.0 release scope tight; v4.0 owns MCP-cost story end-to-end with proper proxy architecture
+
+## Alternatives considered
+
+| Option | Pros | Cons | Verdict |
+|--------|------|------|---------|
+| Build full MCP proxy in v3.2.0 | Achieves original compression goal | Multi-day work, single-bug-breaks-all-MCP failure mode, would block release | Rejected — too big for current release |
+| Pre-install rewrite of `.mcp.json` | One-shot, no runtime cost | MCP spec sources descriptions from server, not config — wouldn't actually take effect | Rejected — does not work |
+| F2-lite observability tool in v3.2.0 | Low risk, gives users data | Not the original target; partial value; mixes two milestones | Rejected by user — keep v3.2.0 focused |
+| **Defer F2 entirely to v4.0** | Clean release boundaries; v4.0 owns MCP story end-to-end with full proxy scope | Token waste in MCP descriptions stays invisible to users until v4.0 | **Selected** |
+
+## What was delivered in v3.2.0 (F1 + F3 + F3.5)
+
+The output-discipline goal is partially addressed by what shipped:
+
+- **Output modes** (F1) cut conversational response tokens 60–80% on the shipped fixture set
+- **Real token telemetry** (F3) lets users see actual cost per session — including the MCP description overhead, even if they cannot yet trim it
+- **Default statusline** (F3.5) surfaces that cost continuously
+
+Users now have visibility into the MCP-description waste this spike identified, even though automated compression has to wait for v4.0.
+
+## What goes into v4.0
+
+Tracked as an active PRD: [`kb/planning/mcp-context-trim-v4-prd.md`](../../planning/mcp-context-trim-v4-prd.md). It carries forward:
+
+1. Compression heuristics from the original F2 design (migrated out of the archived plan into the live PRD)
+2. Local MCP proxy server architecture: JSON-RPC 2.0 over stdio + SSE per server, process supervisor, per-server config in `~/.softspark/ai-toolkit/mcp-proxy/`
+3. Rollback / opt-out story — a buggy proxy must not break MCP-dependent skills
+4. Failure mode — proxy down → fall through to direct MCP server, with telemetry warning
+5. Migration of existing user `.mcp.json` configs
+
+Estimate in the PRD: ~8 working days.
+
+## Status
+
+| Date | Status | Author |
+|------|--------|--------|
+| 2026-05-04 | Spike completed | claude |
+| 2026-05-04 | User decision: defer F2 to v4.0 entirely (no F2-lite in v3.2.0) | lukasz.krzemien |
+| 2026-05-04 | Spike archived to `kb/history/completed/` alongside the parent plan | claude |
+
+---
+
 ## kb/history/completed/offline-slm-profile-plan-20260411.md
 
 ---
@@ -2401,6 +2526,272 @@ This plan shares modification targets with the Enterprise Config plan:
 
 ---
 
+## kb/history/completed/output-token-discipline-plan-20260504.md
+
+---
+title: "Plan: Output & Token Discipline — Concise Modes, MCP Trim, Token Receipts"
+category: planning
+service: ai-toolkit
+tags:
+  - brand-voice
+  - output-style
+  - mcp
+  - statusline
+  - token-tracking
+  - hooks
+  - briefing
+doc_type: plan
+status: completed
+created: "2026-05-04"
+last_updated: "2026-05-04"
+completed: "2026-05-04"
+completion: "100% of v3.2.0 scope (F2 deferred to v4.0 per spike conclusion)"
+shipped_in: "v3.2.0"
+description: "Three coordinated extensions to ai-toolkit that reduce token usage and surface real cost data: (1) brand-voice output modes for concise/strict Claude responses, (2) MCP description trimmer to compact tool listings before they reach the model, (3) token receipts in statusline reading session JSONL directly. Native extensions, no third-party skill names imported."
+---
+
+# Plan: Output & Token Discipline
+
+**Status:** Completed (shipped in v3.2.0 on 2026-05-04)
+**Author:** lukasz.krzemien
+**Source of inspiration:** external Claude Code plugin observed 2026-05-04 (mechanism only, not naming or branding)
+**Spike companion:** [`kb/history/completed/f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md)
+
+## Cel
+
+Zmniejszyć realne zużycie tokenów w sesjach Claude Code i dać użytkownikowi widoczność tego zużycia w czasie rzeczywistym. Trzy mechanizmy działające razem, każdy jako natywne rozszerzenie istniejących komponentów ai-toolkit (`brand-voice`, `briefing`, `track-usage.sh`). Bez importowania obcych nazw — adaptacja idei jako własnych.
+
+## Kontekst
+
+Obecnie ai-toolkit ma:
+
+- `brand-voice` skill — pilnuje stylu pisanego (docs, README, content)
+- `track-usage.sh` hook — liczy `/skill` invocations do `~/.softspark/ai-toolkit/stats.json`
+- `compile_slm.py` — kompresuje cały toolkit dla małych modeli (inny scope)
+- 113 skilli, pełen system hooków, doctor, eject
+
+Brakuje:
+
+- Trybu zwięzłego dla *odpowiedzi* Claude'a (brand-voice działa tylko dla pisanej zawartości)
+- Kompresji opisów MCP-tooli, które zżerają setki tokenów na każdym wywołaniu
+- Realnego pomiaru tokenów per sesja (mamy tylko licznik invocations, nie tokenów)
+
+## Zakres
+
+Trzy features, zaplanowane w kolejności narastającego ryzyka.
+
+---
+
+## Feature 1 — `brand-voice` output modes
+
+### Cel
+Rozszerzyć `brand-voice` o tryby zwięzłości stosowane do odpowiedzi konwersacyjnych Claude'a, nie tylko do generowanych dokumentów.
+
+### Decyzje nazewnicze
+- **Wybrane:** zostaje `brand-voice` z wewnętrznymi trybami (`default`, `concise`, `strict`)
+- **Odrzucone:**
+  - `concise` jako osobny skill — duplikuje brand-voice, niepotrzebny rozłam
+  - `terse` — niejednoznaczne, kojarzy się z "rude"
+  - `output-discipline` — zbyt biurokratyczne
+
+### Pliki
+
+| Ścieżka | Akcja | Cel |
+|---------|-------|-----|
+| `app/skills/brand-voice/SKILL.md` | edit | Dodaj sekcję `## Output Modes` z opisem trzech trybów i sposobu aktywacji |
+| `app/skills/brand-voice/modes/concise.md` | new | Reguły: max 3 zdania per odpowiedź na pytanie zamknięte, brak preamble, brak "I'll now..." |
+| `app/skills/brand-voice/modes/strict.md` | new | Reguły: tylko fakty, zero filler adjectives, max 1 zdanie per fakt, listy zamiast prozy |
+| `app/skills/brand-voice/scripts/measure.py` | new | Eval przed/po na fixtures, raport oszczędności tokenów |
+| `tests/fixtures/output-modes/` | new | 10 par baseline/expected dla różnych typów zadań (debug, review, plan, eksploracja) |
+| `tests/skills_brand_voice.bats` | edit | Dodaj asercje dla modes (regex na zakazane filler, max-line-length) |
+
+### Aktywacja
+
+Trzy mechanizmy:
+
+1. Frontmatter w projekcie: `output-mode: concise` w `CLAUDE.md` lub `.claude/settings.json`
+2. Slash: `/brand-voice concise` przełącza dla bieżącej sesji (przez `track-usage.sh` zapisuje do session state)
+3. Auto-trigger: skill ładuje się także przy długich sesjach generowania (>30 min, heurystyka)
+
+### Success criteria
+
+- Na zestawie 10 fixtures `concise` redukuje output >40% bez utraty kluczowych faktów
+- Test asercji: zachowane są wszystkie nazwy plików i symboli z baseline (regex match)
+- `validate.py --strict` przechodzi
+- `audit_skills.py --ci` zero HIGH
+
+### Estymata
+4–6h
+
+---
+
+## Feature 2 — MCP context trim — DEFERRED TO v4.0
+
+**Status:** Deferred. Spike conducted before implementation, conclusion in [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md).
+
+**Reason:** Claude Code hooks do not expose the MCP `tools/list` response or the system-prompt tool catalog. Hook events (`PreToolUse`, `PermissionRequest`, `Elicitation`) operate on individual tool calls only. Modifying tool descriptions before they reach the model requires a local MCP proxy server — multi-day scope, single-bug-breaks-all-MCP failure mode, out of scope for v3.2.0.
+
+**Resolution:** Full proxy-server approach moved to its own active planning doc: [`kb/planning/mcp-context-trim-v4-prd.md`](../../planning/mcp-context-trim-v4-prd.md). The mid-spike "F2-lite observability tool" alternative was also dropped per user decision (2026-05-04) — v3.2.0 ships F1+F3 only; v4.0 picks up the proxy-server work in full scope.
+
+The compression heuristics, file plan, and risk register from the original Feature 2 design were migrated into the v4.0 PRD. They are no longer duplicated in this archived doc.
+
+---
+
+## Feature 3 — Token receipts w statusline
+
+### Cel
+Pokazać realne (nie estymowane) zużycie tokenów per-sesja w statusline Claude Code. Dane czytane z session JSONL, nie z heurystyk.
+
+### Decyzje nazewnicze
+- **Wybrane:** rozszerzenie istniejącego skilla `briefing` + nowy hook `statusline-tokens.sh` + nowy skrypt `session_token_stats.py`
+- **Odrzucone:**
+  - Nowy skill `stats` / `receipts` — duplikuje funkcjonalnie `briefing`
+  - Modyfikacja istniejącego `track-usage.sh` jako jedynego punktu — za duża odpowiedzialność jednego pliku
+
+### Pliki
+
+| Ścieżka | Akcja | Cel |
+|---------|-------|-----|
+| `scripts/session_token_stats.py` | new | Parser JSONL stdlib-only. Funkcje: `read_session()`, `aggregate_by_skill()`, `compare_baseline_vs_concise()` |
+| `app/hooks/statusline-tokens.sh` | new | Type `statusLine` w settings.json. Sumuje `usage.input_tokens` + `usage.output_tokens` z bieżącej sesji JSONL |
+| `app/hooks/track-usage.sh` | edit | Po wykryciu `/skill` zapisuj też `prompt_tokens` jeśli `transcript_path` dostępne |
+| `app/skills/briefing/SKILL.md` | edit | Nowa sekcja "Token receipts", komendy `/briefing --tokens --since 7d`, `/briefing --tokens --share` |
+| `scripts/merge-hooks.py` | edit | Statusline injection do `settings.json`, preserve user-customized entries (delivered as F3.5) |
+| `app/hooks/ai-toolkit-statusline.sh` | new | Comprehensive statusline (cwd + git + ctx + tokens + cost + model), default install (delivered as F3.5) |
+| `tests/session_token_stats.bats` | new | Fixture JSONL z 3 messages, asercje na sumę i breakdown |
+| `tests/statusline_tokens.bats` | new | Mock JSONL, weryfikacja outputu hooka (max 80 znaków, brak NaN, fallback gdy brak sesji) |
+
+### Format statusline (proponowany)
+
+```
+[ai-toolkit] /concise · session: 24.7k · trend: ↓18%
+```
+
+Krótki tryb default, `--verbose` dodaje breakdown per skill.
+
+### Ścieżka odczytu sesji
+
+Claude Code zapisuje JSONL do `~/.claude/projects/<sanitized-cwd>/<session-id>.jsonl`. Każda linia to message z polem `usage` (input_tokens, output_tokens, cache_*). Skrypt:
+
+1. Identyfikuje aktualną sesję z env var `CLAUDE_SESSION_ID` (jeśli istnieje) lub najświeższy plik
+2. Parsuje linie ignorując te bez `usage`
+3. Sumuje + agreguje per skill (jeśli `track-usage.sh` zapisał skill mapping w sidecar pliku)
+
+### Success criteria
+
+- Statusline pokazuje liczbę tokenów odczytaną z JSONL z dokładnością ±2% vs Anthropic API report (jeśli dostępny)
+- Brak crash gdy sesja jeszcze pusta
+- Brak crash gdy JSONL malformed
+- `validate.py --strict` przechodzi
+
+### Estymata
+6–8h
+
+---
+
+## Co nie wchodzi w plan
+
+| Pomysł | Powód odrzucenia |
+|--------|------------------|
+| Memory/file compressor (`/compress <file>`) | `compile_slm.py` już kompresuje toolkit, brak konkretnego use-case dla per-file |
+| Compact `/commit`, `/review` modes | Powstaną automatycznie po Feature 1 (te skille będą używać reguł `concise` mode) |
+| "Caveman speak" / classical Chinese mode | Nie pasuje do tonu workmanlike, sprzeczne z brand-voice |
+| Single curl-installer | Już mamy `ai-toolkit install` z profilami |
+
+---
+
+## Kolejność realizacji i zależności
+
+```
+Feature 1 (brand-voice modes)
+    ↓ dostarcza reguły zwięzłości
+Feature 3 (token receipts)
+    ↓ dostarcza pomiar before/after dla F1
+Feature 2 (mcp-trim)  ← spike research najpierw, niezależne od F1/F3
+```
+
+**F1 i F3 mogą iść parallel po dokończeniu F1 mode files.**
+**F2 ma osobną decyzję go/no-go po spike'u.**
+
+## Estymata zbiorcza
+
+| Feature | Min | Max |
+|---------|-----|-----|
+| F1 | 4h | 6h |
+| F3 | 6h | 8h |
+| F2 spike | 1h | 1h |
+| F2 implementacja | 0h | 10h |
+| **Total** | **11h** | **25h** |
+
+## Doc & test sweep (obowiązkowy po każdym feature)
+
+1. `python3 scripts/validate.py --strict`
+2. `python3 scripts/audit_skills.py --ci`
+3. Regen `AGENTS.md`: `python3 scripts/generate_agents_md.py > AGENTS.md`
+4. Regen `llms.txt`: `python3 scripts/generate_llms_txt.py > llms.txt`
+5. Bump version w `package.json` + `plugin.json`
+6. Update `skills-catalog.md` z nowymi/zmienionymi skillami
+7. Update `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `architecture-overview.md` jeśli zmiana behavior
+8. Commit conventional: `feat(brand-voice): add output modes`, `feat(briefing): add token receipts`, `feat(mcp-trim): add description trimmer`
+
+## Open questions — resolved
+
+1. **Czy `PreToolUse` może modyfikować deklarację tool'a w MCP listingu?** — NIE. Spike potwierdził że żaden hook event nie wystawia `tools/list`. F2 wymaga MCP proxy. Odsunięte do v4.0.
+2. **Czy Claude Code wystawia hookom `CLAUDE_SESSION_ID`?** — częściowo. `scripts/session_token_stats.py` używa fallback "newest JSONL w katalogu projektu" + opcjonalnie cwd → sanitize → match. Działa stabilnie na realnych sesjach (96.6k tokens parsed correctly w smoke tescie).
+3. **Czy włączyć `concise` mode jako default?** — pozostaje opt-in. `brand-voice` z trybami auto-loaduje się tylko gdy projekt ustawi `output-mode: concise` w `CLAUDE.md` lub user wpisze `/brand-voice concise`. Pomiary z F3 dadzą dane do późniejszej decyzji.
+
+## Final delivery (v3.2.0)
+
+### Shipped
+
+| Feature | Outcome | Pliki |
+|---------|---------|-------|
+| **F1 — brand-voice output modes** | Done. Aggregate ratio na 3 fixtures: concise **21%**, strict **14%** (cel ≤60% / ≤40%). | `app/skills/brand-voice/SKILL.md`, `app/skills/brand-voice/modes/{concise,strict}.md`, `app/skills/brand-voice/scripts/measure.py`, `tests/fixtures/output-modes/{debug-explanation,plan-question,review-summary}/`, `tests/test_brand_voice.bats` (14 tests) |
+| **F3 — token receipts** | Done. Smoke-test na realnej sesji: 96.6k tokenów poprawnie sparsowane. | `scripts/session_token_stats.py`, `tests/fixtures/session-jsonl/{three-messages,malformed,empty}.jsonl`, `tests/test_session_token_stats.bats` (15 tests) |
+| **F3.5 — comprehensive default statusline** | Done. Pełny segment: cwd + git + ctx% + tokens + trend + model-aware cost + model. Installed by default via `merge-hooks.py`, user-custom statusLine preserved untouched. | `app/hooks/ai-toolkit-statusline.sh`, `app/hooks.json` (`statusLine` entry), `scripts/merge-hooks.py` (statusLine inject/strip), `tests/test_statusline_hook.bats` (14 tests), `tests/test_merge_hooks_statusline.bats` (8 tests) |
+| **briefing skill extension** | `/briefing --tokens` + wire-up docs + opt-out env vars. | `app/skills/briefing/SKILL.md` |
+
+### Deviations from plan
+
+| Plan said | Shipped | Reason |
+|-----------|---------|--------|
+| 10 fixtures w F1 | 3 fixtures + `must_contain.txt` mechanism | Mniejszy zestaw + extensible konwencja wystarcza do walidacji budżetów; jakość > ilość |
+| F3 hook integracja jako follow-up (manual settings.json edit) | F3.5 dostarczył pełny default install via `merge-hooks.py` | User feedback w trakcie pracy: "niech ai-toolki instaluje go domyslnie od nowej wersji" |
+| F2 implementacja po spike'u | F2 deferred do v4.0 | Spike pokazał że Claude Code hooki nie wystawiają `tools/list` → wymaga proxy server, multi-day scope |
+
+### Quality gates passed
+
+- `validate.py --strict`: 0 errors / 0 warnings
+- `audit_skills.py --ci`: 0 HIGH / 0 WARN / 13 INFO (pre-existing)
+- `audit_skills.py --sarif`: SARIF 2.1.0 valid, 5 rules
+- `npm test`: 1032 / 1032 passing (was 981 in v3.1.1)
+- Registry drift: clean
+- Provenance + checksum-pin: verified
+- Ecosystem doctor: 9 cosmetic drifts (class A) refreshed
+
+### Skill classification change
+
+`brand-voice` przeszedł `user-invocable: false → true` (knowledge → hybrid):
+
+- **Hybrid**: 31 → 32
+- **Knowledge**: 49 → 48
+- **Task**: 32 (no change)
+
+Updated: `README.md`, `kb/reference/architecture-overview.md`, `kb/reference/skills-catalog.md`.
+
+## Status & rewizje
+
+| Data | Zmiana | Autor |
+|------|--------|-------|
+| 2026-05-04 | Initial draft | lukasz.krzemien |
+| 2026-05-04 | F1 implementation done — brand-voice modes, measure.py, 3 fixtures, 14 bats tests. Aggregate ratio: concise 21%, strict 14%. | claude |
+| 2026-05-04 | F3 implementation done — `session_token_stats.py`, `statusline-tokens.sh`, briefing skill extension. 22 new bats tests. Smoke-tested on real session. | claude |
+| 2026-05-04 | F3.5 follow-up done — replaced focused tokens hook with comprehensive `ai-toolkit-statusline.sh`. Extended `merge-hooks.py` for safe statusLine injection. Version bumped 3.1.1 → 3.2.0. 22 new bats tests. CHANGELOG + README updated. | claude |
+| 2026-05-04 | F2 spike completed — see [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md). Hooks cannot modify `tools/list`. F2 deferred to v4.0 with own PRD. | claude |
+| 2026-05-04 | Plan archived to `kb/history/completed/`. Shipped in v3.2.0. | claude |
+
+---
+
 ## kb/howto/README.md
 
 ---
@@ -3588,6 +3979,169 @@ Examples:
 
 ---
 
+## 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:
+
+- 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 |
+
+---
+
 ## kb/procedures/ecosystem-sync-sop.md
 
 ---
@@ -4701,10 +5255,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.4.1"
+version: "1.4.2"
 created: "2026-04-08"
-last_updated: "2026-04-28"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
+last_updated: "2026-04-29"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds. v1.4.2 makes the Phase 9.4 idempotence check deterministic by sorting file paths before hashing."
 ---
 
 # SOP: Release Verification
@@ -5080,10 +5634,13 @@ grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Ge
 
 ```bash
 D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+# Sort file paths before hashing — find traversal order follows inode order,
+# which can shift between runs even when content is byte-identical, producing
+# false FAIL signals.
 ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+SHA1=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
 ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+SHA2=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
 [ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
 ```
 
@@ -5722,8 +6279,8 @@ Three tiers determine how to approach a task:
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
-| Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 49 |
+| Hybrid | (neither) | User via `/skill` + agent knowledge | 32 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 48 |
 
 ## Multi-Agent Execution
 
@@ -10479,7 +11036,7 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **seo-validate** | `/seo-validate` | medium | Scan codebase for SEO issues: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Framework-aware (Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML). |
 | **mcp-builder** | `/mcp-builder` | high | Build production-grade MCP servers using the 4-phase methodology (research, implement, test, evaluate). TypeScript/Python, stdio/streamable-http. |
 
-## Hybrid Skills (31)
+## Hybrid Skills (32)
 
 Hybrid skills combine slash-command invocation with domain knowledge that agents reference.
 
@@ -10516,6 +11073,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **persona** | `/persona` | low | Switch engineering persona at runtime (backend-lead, frontend-lead, devops-eng, junior-dev) |
 | **council** | `/council` | high | 4-perspective decision evaluation (Advocate, Critic, Pragmatist, User-Proxy) with synthesis and confidence-rated recommendation. Tier 1, orchestrator, `context: fork`. |
 | **introspect** | `/introspect` | medium | Agent self-debugging: classify failure pattern, suggest smallest recovery action, emit structured introspection report |
+| **brand-voice** | `/brand-voice` | medium | Anti-trope list, voice principles, LLM rhetoric prevention; output modes (`concise` ≤60% tokens, `strict` ≤40%) governing conversational responses. |
 
 ### `/workflow` types
 
@@ -10537,7 +11095,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | `application-deploy` | 3 | Deploy → smoke test → release notes |
 | `proactive-troubleshooting` | 4 | Investigate → check perf → preventive fix → docs |
 
-## Knowledge Skills - Development (16)
+## Knowledge Skills - Development (15)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
@@ -10556,7 +11114,6 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **ruby-patterns** | `skills/ruby-patterns/` | Blocks, Rails conventions, RSpec, ActiveRecord |
 | **design-engineering** | `skills/design-engineering/` | UI polish, animation craft, easing, transforms, accessibility |
 | **documentation-standards** | `skills/documentation-standards/` | KB document conventions, frontmatter validation, category taxonomy |
-| **brand-voice** | `skills/brand-voice/` | Anti-trope list, voice principles, LLM rhetoric prevention |
 
 ## Knowledge Skills - Infrastructure (6)