@softspark/ai-toolkit 4.20.0 → 4.21.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.21.0 — one KB taxonomy, in one place (2026-07-28)
+
+### Fixed
+
+- **The `documentation-standards` skill contradicted itself.** Its frontmatter
+  said "5-category taxonomy", its table listed those five, and three paragraphs
+  below a "Valid categories" line named six — adding `planning`. An author
+  reading the table and a validator reading the code disagreed about what was
+  legal, and only the validator got a vote.
+- **`decisions` and `runbooks` were not valid categories**, while the
+  `kb-migration` SOP had been instructing people to create exactly those
+  directories for months. A correctly-filed ADR failed `scripts/validate.py`.
+  Both are now in the taxonomy, which is eight: `reference`, `howto`,
+  `procedures`, `troubleshooting`, `best-practices`, `decisions`, `runbooks`,
+  `planning`.
+- **`procedures` and `runbooks` no longer describe each other.** The table gave
+  "SOPs, runbooks, operational processes" for `procedures`, which left no way to
+  choose between them. `procedures` is a process a person follows; `runbooks`
+  are run against a live system, usually under pressure.
+
+### Added
+
+- **`section:` is documented as what it is: a legacy alias for `category:`.**
+  Older documents and the `kb-migration` SOP write `section:`; both names are
+  read in the wild. A document may carry both, and `validate.py` now rejects it
+  when they disagree — a document filed as `category: reference` and
+  `section: howto` is indexed twice and found once.
+- **`validate.py` checks that a document's category names its directory.** The
+  rule is scoped to directories that *are* category names, deliberately:
+  `kb/history/completed/` is a lifecycle location rather than a type, and a
+  finished plan filed there is still a `planning` document. Fifteen of this
+  project's own documents are in exactly that position.
+
+### Changed
+
+- `VALID_KB_CATEGORIES` in `scripts/validate.py` and the taxonomy table in
+  `app/skills/documentation-standards/SKILL.md` are one list in two places, and
+  each now says so. They were previously two lists that had drifted.
+
+---
+
 ## v4.20.0 — Apache-2.0, nine plugin packs removed (2026-07-27)
 
 ### Changed — licence: MIT to Apache-2.0

package/README.md

@@ -8,24 +8,30 @@
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
 [![Tests](https://img.shields.io/badge/tests-1473%20passing-success)](tests/)
 
-## What's New in v4.20.0
-
-v4.20.0 relicenses the project to Apache-2.0 and removes nine plugin packs that installed nothing. Plugin count: 11 → 2.
-
-- **Licence: MIT → Apache-2.0.** Still permissive — fork it, modify it, ship it commercially. The change is what a redistributor owes back: the contents of [NOTICE](NOTICE) must travel with any redistribution (§4d), modified files must say they were modified (§4b), and there is now an express patent grant and a trademark reservation. Releases up to v4.20.0 stay available under MIT; nothing already granted is revoked. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
-
-- **Nine packs removed**: `csharp`, `java`, `kotlin`, `ruby`, `rust`, `swift`, `frontend`, `research`, `security`. Each declared only skills and agents that already ship in the core install, so `plugin install` reported `(0 file items)` and wrote no file — on both runtimes and all three profiles. Eight owned nothing but a `README.md`. See [the measurement](kb/history/completed/no-op-plugin-packs-removed-20260727.md).
-- **Nothing is lost by the removal.** `rust-patterns`, `java-patterns`, `security-patterns`, `research-mastery` and the rest are **core skills**, still installed, still triggering as before. The packs never held them — they only listed them.
-- **`memory-pack` and `enterprise-pack` stay**: the two packs that ship files of their own — hooks, scripts, and in memory-pack's case its own skill and a SQLite store.
-- **A pack must now earn its existence**: `plugin-creator`'s authoring rule required referencing core assets rather than forking them, which against a core install that ships everything produced a no-op every time. It now requires that a pack install files the core does not, with a verification step in the checklist.
-- **`rtk-pack` retired in v4.19.0**: it broke every command it rewrote — exit 127 on `git`, `ls`, `cat`, `find`, `grep`. Measured value was 0.0615% of input tokens against a 0.05% kill number. See [the retirement note](kb/history/completed/rtk-pack-retirement-20260727.md).
-
-If you installed any removed pack, run `ai-toolkit plugin remove <name>` to drop its bookkeeping entry. No skill or agent disappears.
+## What's New in v4.21.0
+
+v4.21.0 makes the KB taxonomy one list instead of three, and teaches
+`validate.py` to enforce it.
+
+- **The taxonomy is eight categories**: `reference`, `howto`, `procedures`,
+  `troubleshooting`, `best-practices`, `decisions`, `runbooks`, `planning`.
+  `decisions` and `runbooks` were missing while the `kb-migration` SOP had been
+  telling people to create those directories for months — a correctly-filed ADR
+  failed validation.
+- **The `documentation-standards` skill no longer contradicts itself.** Its
+  frontmatter said "5-category", its table listed five, and a line below named
+  six. Author and validator disagreed, and only the validator got a vote.
+- **`section:` is documented as a legacy alias for `category:`**, and
+  `validate.py` rejects a document carrying both with different values — that
+  document is indexed twice and found once.
+- **A document's category must name its directory**, checked only for
+  directories that are category names: `kb/history/completed/` is a lifecycle
+  location, not a type, and a finished plan filed there is still `planning`.
+- **`procedures` and `runbooks` stopped describing each other.** A procedure is
+  followed by a person; a runbook is run against a live system.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
----
-
 ## Table of Contents
 
 - [Install](#install)

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.20.0",
+  "version": "4.21.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/documentation-standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-standards
-description: "KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base."
+description: "KB conventions: YAML frontmatter, 8-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base."
 effort: medium
 user-invocable: false
 allowed-tools: Read
@@ -27,7 +27,19 @@ version: "1.0.0"                           # optional — semver
 ---
 ```
 
-**All 7 fields above are REQUIRED.** Documents without valid frontmatter **fail `validate.sh` and block CI**.
+**All 7 fields above are REQUIRED.** Documents without valid frontmatter **fail
+`scripts/validate.py` and block CI**.
+
+### `section`: a legacy alias, not a second field
+
+Older documents and the `kb-migration` SOP write `section:` where this
+specification writes `category:`. Both names are read in the wild, so a document
+may carry both — and when it does **they must hold the same value**. A document
+filed as `category: reference` and `section: howto` is indexed twice, found
+once, and the reader gets whichever the index ranked higher.
+
+New documents should write `category:`. `section:` is accepted, never required,
+and never authoritative on its own.
 
 ## Category Taxonomy
 
@@ -35,11 +47,17 @@ version: "1.0.0"                           # optional — semver
 |----------|-----------|---------|----------|
 | `reference` | `kb/reference/` | Technical specifications, catalogs, architecture notes, API docs | `agents-catalog.md`, `architecture-overview.md` |
 | `howto` | `kb/howto/` | Step-by-step task guides | `use-corrective-rag.md`, `configure-mcp-server.md` |
-| `procedures` | `kb/procedures/` | SOPs, runbooks, operational processes | `maintenance-sop.md`, `incident-response.md` |
+| `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `maintenance-sop.md`, `sop-release.md` |
 | `troubleshooting` | `kb/troubleshooting/` | Problem resolution, debugging guides | `database-connection-issues.md` |
 | `best-practices` | `kb/best-practices/` | Guidelines, recommendations, standards | `security-checklist.md` |
+| `decisions` | `kb/decisions/` | Architecture decision records and design rationale | `adr-004-kb-migration.md` |
+| `runbooks` | `kb/runbooks/` | Procedures run against a live system, usually under pressure | `deployment.md`, `incident-response.md` |
+| `planning` | `kb/planning/` | Roadmaps, PRDs, work not yet done | `q3-roadmap.md` |
 
-**Rule:** The `category:` frontmatter field MUST match the directory the file lives in.
+**Rule:** A document filed under one of the directories above MUST declare that
+category. The rule is scoped to those directories deliberately: `kb/history/`
+and similar are lifecycle locations rather than types, and a finished plan filed
+under `history/completed/` is still a `planning` document.
 
 ## Naming Conventions
 
@@ -178,7 +196,9 @@ scripts/validate.py
 # Checks: required fields present, category is valid, tags non-empty
 ```
 
-Valid categories: `reference`, `howto`, `procedures`, `troubleshooting`, `best-practices`, `planning`.
+Valid categories are the eight in the table above. `scripts/validate.py` holds
+the same set in `VALID_KB_CATEGORIES`; the two are the same list in two places
+and a change belongs in both.
 
 ## Anti-Patterns
 

package/llms-full.txt

@@ -108,7 +108,7 @@
 - **design-engineering**: UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish.
 - **docker-devops**: Docker/K8s: Dockerfile, multi-stage, compose, manifests, Helm. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod.
 - **docs**: Generates/updates README, API docs, architecture notes. Triggers: docs, README, API docs, architecture note, documentation.
-- **documentation-standards**: KB conventions: YAML frontmatter, 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
+- **documentation-standards**: KB conventions: YAML frontmatter, 8-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
 - **ecommerce-patterns**: E-commerce: cart, checkout, payments (Stripe/Adyen), order state, inventory, promos, tax. Triggers: cart, checkout, SKU, payment, Stripe, Shopify, Medusa, Magento, coupon, refund.
 - **evaluate**: Evaluates RAG retrieval and LLM-as-judge metrics (faithfulness, relevancy, context precision). Triggers: measure RAG quality, knowledge gap, RAG eval, golden dataset.
 - **evolve**: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.20.0",
+  "version": "4.21.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.20.0",
+  "version": "4.21.0",
   "description": "AI coding toolkit: 108 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/validate.py

@@ -95,9 +95,16 @@ HOOK_REQUIRED_FIELDS = {
     "mcp_tool": ("server", "tool", "arguments"),
 }
 
+# The taxonomy. `app/skills/documentation-standards/SKILL.md` documents the same
+# eight and is what authors read; this set is what rejects a typo. They are one
+# list in two places, so a change belongs in both.
+#
+# `decisions` and `runbooks` were missing until v4.21.0 while the kb-migration
+# SOP had been telling people to create those directories for months, so a
+# correctly-filed ADR failed validation.
 VALID_KB_CATEGORIES = frozenset({
     "reference", "howto", "procedures", "troubleshooting", "best-practices",
-    "planning",
+    "decisions", "runbooks", "planning",
 })
 
 VALID_RULE_CATEGORIES = frozenset({
@@ -730,6 +737,31 @@ def validate_kb_documents(tk_dir: Path, vr: ValidationResult) -> None:
             vr.error(f"{kb_name} - Invalid category '{kb_category}' (valid: {', '.join(sorted(VALID_KB_CATEGORIES))})")
             kb_errors += 1
 
+        # `section` is a legacy alias for `category`, not a second axis. A
+        # document carrying both with different values is indexed twice and
+        # found once, and nothing about that is visible to its author.
+        kb_section = _fm_field(fm_lines, "section").strip()
+        if kb_section and kb_category and kb_section != kb_category:
+            vr.error(
+                f"{kb_name} - section '{kb_section}' disagrees with category "
+                f"'{kb_category}'; section is an alias and must match"
+            )
+            kb_errors += 1
+
+        # A document filed under a taxonomy directory must declare that
+        # category, or a browsing reader and a search hit disagree about what it
+        # is. The rule is scoped to directories that ARE category names on
+        # purpose: `kb/history/completed/` is a lifecycle location, not a type,
+        # and a finished plan is still a `planning` document.
+        relative = kb_file.relative_to(kb_dir).parts
+        top = relative[0] if len(relative) > 1 else ""
+        if kb_category and top in VALID_KB_CATEGORIES and top != kb_category:
+            vr.error(
+                f"{kb_name} - is in {top}/ but declares category "
+                f"'{kb_category}'; they must agree"
+            )
+            kb_errors += 1
+
         # Validate tags is not empty
         tags_val = _fm_field(fm_lines, "tags")
         if tags_val: