@softspark/ai-toolkit 4.19.0 → 4.20.0

package/kb/{planning/drop-cascade-hooks-after-sunset.md → history/completed/drop-cascade-hooks-after-sunset-20260710.md}

@@ -22,6 +22,30 @@ description: "Completed cleanup of the deprecated Windsurf Cascade hooks generat
 
 **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

package/kb/{reference/language-packs.md → history/completed/language-packs-removed-20260727.md}

@@ -1,15 +1,40 @@
 ---
-title: "AI Toolkit - Language Plugin Packs"
-category: reference
+title: "AI Toolkit - Language Plugin Packs (removed)"
+category: planning
 service: ai-toolkit
-tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby]
-version: "1.0.0"
+tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby, removed]
+doc_type: postmortem
+status: completed
+version: "1.1.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."
+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
+# 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.
+
+---
 
 ## Overview
 

package/kb/{planning/mcp-context-trim-v4-prd.md → history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md}

@@ -10,23 +10,56 @@ tags:
   - tokens
   - v4
 doc_type: plan
-status: proposed
+status: obsoleted
 created: "2026-05-04"
-last_updated: "2026-05-04"
-completion: "0%"
-target_milestone: "v4.0"
+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: "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."
+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
+# 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
+---
+
+**Status:** Proposed *(as of 2026-05-04; see abandonment note above)*
 **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)
+**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)
 
 ## Problem
 
@@ -156,3 +189,4 @@ Applied to each tool description in `tools/list` response:
 | 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 |

package/kb/history/completed/no-op-plugin-packs-removed-20260727.md

@@ -0,0 +1,127 @@
+---
+title: "Removed: Nine Plugin Packs That Installed Nothing"
+category: planning
+service: ai-toolkit
+tags:
+  - plugins
+  - plugin-pack
+  - measurement
+  - postmortem
+  - dead-code
+doc_type: postmortem
+status: completed
+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."
+---
+
+# Removed: Nine Plugin Packs That Installed Nothing
+
+`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
+
+`ai-toolkit install` into a throwaway `HOME`, then `plugin install <pack>`, on
+each runtime. The number is what `plugin install` itself reports:
+
+| 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.
+
+## 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

package/kb/history/completed/tool-output-token-reduction-closed-20260727.md

@@ -0,0 +1,190 @@
+---
+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

package/kb/procedures/release-preparation-sop.md

@@ -3,10 +3,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
@@ -65,10 +65,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
 ```
 
 ---
@@ -332,6 +342,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.
@@ -405,9 +455,34 @@ 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`
 2. Runs `npm test`
@@ -460,7 +535,10 @@ 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`. |

package/kb/reference/comparison.md

@@ -24,6 +24,6 @@ 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).

package/kb/reference/enterprise-config-guide.md

@@ -137,7 +137,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"]
   }