@softspark/ai-toolkit 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -7,6 +7,29 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.0.2 — Validation, Windows, Telemetry, and generate:all parity (2026-04-24)
+
+Patch release that closes known validation gaps, expands the hook-surface contracts, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI so registered custom rules reach every editor.
+
+### Added
+
+- **Hook surface validation** — `scripts/validate.py` now accepts the current Claude Code hook event surface, including `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion`.
+- **Hook handler contracts** — validation now checks supported handler types (`command`, `http`, `prompt`, `agent`, `mcp_tool`), required handler fields, and prompt/agent event compatibility.
+- **Language rule validation** — `scripts/validate.py` now checks `app/rules/<language>/*.md` frontmatter, category names, filename/category alignment, directory/language alignment, and required category coverage.
+- **Windows dependency hints** — `_common.detect_os()` recognizes Windows package managers (`winget`, Chocolatey, Scoop), and `check_deps.py` emits package install commands for Python, Git, Node, SQLite, and supported optional tooling.
+- **Product telemetry summary** — `ai-toolkit stats --summary` reports local usage telemetry; `--summary --json` emits machine-readable totals, coverage, unused catalog count, recent activity, and top skills.
+- **Dedicated gap tests** — added contracts for structured rules, Windows dependency support, council/brand-voice/introspect skill coverage, and `npm run generate:all` directory-rule generator coverage. Total test count: 945 -> 960.
+- **Windows Support KB** — new `kb/reference/windows-support.md` documents WSL, Git Bash, package managers, and hook runtime constraints.
+
+### Changed
+
+- **`package.json` `generate:all`** — now invokes all directory-based rule generators (`generate_cursor_mdc.py`, `generate_windsurf_rules.py`, `generate_roo_rules.py`, `generate_augment_rules.py`) so registered custom rules in `~/.softspark/ai-toolkit/rules/` propagate to every editor that supports per-rule module files. Restores parity with `ai-toolkit generate-all` (CLI).
+- **`app/skills/hook-creator/SKILL.md`** — documents the expanded hook event and handler type surface.
+- **`README.md` and `kb/reference/cli-reference.md`** — document `stats --summary` and Windows support.
+- **`kb/reference/hooks-catalog.md`** — documents the validated hook surface and non-command handler support.
+
+---
+
 ## v3.0.1 — Release SOP Deep-Coverage Checks (2026-04-24)
 
 Doc-only patch. No code, generators, or runtime behavior changed.

package/README.md

@@ -6,16 +6,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-945%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-960%20passing-success)](tests/)
 
 ---
 
-## What's New in v3.0.1
+## What's New in v3.0.2
 
-**3.0.1 is a doc-only patch** that tightens the release SOPs. No code or generator changes. The v3.0.0 feature set below is still what you get when you upgrade from 2.x.
+**3.0.2 is a patch release** that closes known validation gaps, expands the validated hook surface, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI.
 
-- Release Verification SOP gains **Phase 9: Deep-Coverage Checks** — six automated assertions for the v3.0.0 native surfaces (`--profile full` emission, `--codex-skills` orthogonality, breaking-change surfaces on `standard`, install idempotence, live JSON parse, registry/generator drift) plus refreshed thresholds and a HOME-scoped-write safety warning.
-- Release Preparation SOP now runs the registry-vs-generators drift check in Phase 5 so a misaligned `supported-tools-registry.md` can't escape into a release.
+- `validate.py` now checks hook handler types, required handler fields, prompt/agent event compatibility, and structured language-rule frontmatter/category coverage.
+- Hook docs and validation now cover `PostToolUseFailure`, `PostToolBatch`, `UserPromptExpansion`, plus `command`, `http`, `prompt`, `agent`, and `mcp_tool` handler types.
+- `ai-toolkit stats --summary` reports local product telemetry: total invocations, unique skills used, catalog coverage, unused skills, recent activity, and top skills.
+- Windows dependency detection now emits package hints for `winget`, Chocolatey, and Scoop; WSL remains the recommended runtime for Bash hooks.
+- `npm run generate:all` now invokes every directory-based rule generator, so registered custom rules in `~/.softspark/ai-toolkit/rules/` propagate to every editor that supports per-rule module files.
 
 ### Carried from v3.0.0 (feature release)
 
@@ -66,6 +69,8 @@ npx @softspark/ai-toolkit install
 
 **That's it.** Claude Code picks up 99 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
+**Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
+
 ### Update
 
 ```bash
@@ -161,7 +166,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (945 tests)
+├── tests/               # Bats test suite (960 tests)
 └── CHANGELOG.md
 ```
 
@@ -187,6 +192,8 @@ ai-toolkit/
 
 **Persistent memory** — `memory-pack` plugin: SQLite + FTS5 search across past sessions.
 
+**Local product telemetry** — `ai-toolkit stats --summary` reports total invocations, skill coverage, unused catalog skills, recent activity, and top skills from local usage data.
+
 **Persona presets** — 4 roles (backend-lead, frontend-lead, devops-eng, junior-dev) adjust style and priorities.
 
 **Config inheritance** — Enterprise `extends` system with constitution immutability and enforcement constraints. See [Enterprise Config Guide](kb/reference/enterprise-config-guide.md).

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/hook-creator/SKILL.md

@@ -30,6 +30,8 @@ Create a new Claude Code hook following ai-toolkit conventions.
 |-------|-----------|---------|-------------|
 | `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) or `if:` rule | Safety guards, validation, `"defer"` for headless |
 | `PostToolUse` | After a tool executes | tool name | Feedback loops, logging, format-on-save |
+| `PostToolUseFailure` | After a tool fails | tool name | Failure telemetry, recovery hints |
+| `PostToolBatch` | After a batch of tool calls completes | any | Batch summaries, aggregate validation |
 
 ### Turn lifecycle
 
@@ -37,6 +39,7 @@ Create a new Claude Code hook following ai-toolkit conventions.
 |-------|-----------|---------|-------------|
 | `Stop` | Claude finishes responding | any | Quality checks, session save |
 | `StopFailure` | Turn ends due to an API error (rate limit, auth) | any | Alerting, fallback behavior |
+| `UserPromptExpansion` | Claude expands or rewrites a submitted prompt | any | Prompt policy and context shaping |
 
 ### Subagent lifecycle
 
@@ -88,12 +91,13 @@ Create a new Claude Code hook following ai-toolkit conventions.
 
 ## Hook Handler Types
 
-Claude Code supports four handler `type` values in `hooks.json`:
+Claude Code supports five handler `type` values in `hooks.json`:
 
 | Type | Purpose | Required fields |
 |------|---------|-----------------|
 | `command` | Run a shell script / binary | `command` (path + args) |
-| `prompt` | Inject a prompt to the fast inline model and use its verdict | Handler-managed |
+| `http` | Call a local or remote HTTP endpoint | `url` |
+| `prompt` | Inject a prompt to the fast inline model and use its verdict | `prompt` |
 | `agent` | Spawn a full subagent to evaluate the event (must target `Stop` / `SubagentStop`) | `agent` (agent name) |
 | `mcp_tool` | Invoke an MCP tool directly (no subprocess) | `server`, `tool`, `arguments` |
 
@@ -137,7 +141,7 @@ Claude Code supports four handler `type` values in `hooks.json`:
 Required fields:
 - `_source`: always `"ai-toolkit"` (used by merge/strip logic)
 - `matcher`: tool name or regex for Pre/PostToolUse, empty string for global events
-- `hooks[].type`: `"command"`, `"prompt"`, `"agent"`, or `"mcp_tool"` (ai-toolkit uses `"command"`)
+- `hooks[].type`: `"command"`, `"http"`, `"prompt"`, `"agent"`, or `"mcp_tool"` (ai-toolkit uses `"command"`)
 - `hooks[].command`: path to script using `$HOME/.softspark/ai-toolkit/hooks/` prefix (for `type: command`)
 
 Optional fields (read from Claude Code docs, not emitted by ai-toolkit by default):

package/app/skills/introspect/SKILL.md

@@ -61,7 +61,7 @@ Answer these three questions:
 
 ## Step 4: Select Recovery Action
 
-Apply the **smallest possible fix** — do not restart from scratch unless absolutely necessary:
+Choose the **smallest recovery action** and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:
 
 | Pattern | Recovery Action |
 |---------|----------------|

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-04-23T13:13:00Z",
+  "last_run": "2026-04-24T08:04:02Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "91dbc84ba3b8652b",
+      "docs_hash": "5754553b0e436fd7",
       "headings": [
         "Agent",
         "Code Completions",
@@ -57,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "a117026a47c684b9",
+      "docs_hash": "0c111b1b1f28960d",
       "headings": [
         "Claude Code overview",
         "\u200bGet started",
@@ -102,10 +102,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.118 (Claude Code)"
+      "version": "2.1.119 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "5ed2cada4d9b3fa6",
+      "docs_hash": "17c24d27216f70cf",
       "headings": [
         "Cline CLI",
         "Cline Documentation",
@@ -135,7 +135,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "d66e6b65d5c69da4",
+      "docs_hash": "7a7f5cdf9411c5e2",
       "headings": [
         "About",
         "Contributing",
@@ -154,7 +154,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 732",
+        "Releases 735",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -184,10 +184,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.122.0"
+      "version": "codex-cli 0.124.0"
     },
     "cursor": {
-      "docs_hash": "594d7b663fb8b3e1",
+      "docs_hash": "a94b8e8f685b0831",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -203,7 +203,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "51d03cce48332772",
+      "docs_hash": "9415ea08e344013d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -242,7 +242,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "377b588e529c7deb",
+      "docs_hash": "8bcd2db0db925807",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -290,7 +290,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "81d548872ef2d912",
+      "docs_hash": "760fbf466036892f",
       "headings": [
         "Add features",
         "Ask questions",
@@ -351,7 +351,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "99ecee90bc1efe60",
+      "docs_hash": "81d0aafbf97b18c8",
       "headings": [
         "Advanced",
         "App Deploys",

package/bin/ai-toolkit.js

@@ -74,7 +74,7 @@ const COMMANDS = {
   benchmark: 'Benchmark toolkit (--my-config to compare your setup vs defaults vs ecosystem)',
   'benchmark-ecosystem': 'Generate ecosystem benchmark snapshot (GitHub metadata + offline fallback)',
   evaluate: 'Run skill evaluation suite',
-  stats: 'Show skill usage statistics (--reset to clear, --json for raw output)',
+  stats: 'Show skill usage statistics (--summary for product telemetry, --reset to clear)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
   mcp: 'Manage MCP templates and install native editor MCP configs',
   config: 'Manage config inheritance (validate, diff, init, create-base, check)',
@@ -280,6 +280,10 @@ function showHelp() {
   console.log('                                Remove from .mcp.json or native editor configs');
   console.log('\nOptions for doctor:');
   console.log('  --fix           Auto-repair detected issues');
+  console.log('\nOptions for stats:');
+  console.log('  --summary       Show aggregated product telemetry (usage coverage, top skills, unused catalog)');
+  console.log('  --json          Emit raw stats, or machine-readable telemetry when combined with --summary');
+  console.log('  --reset         Clear local usage stats');
   console.log('\nOptions for eject:');
   console.log('  [target-dir]    Target directory (default: current directory)');
   console.log('');

package/kb/reference/cli-reference.md

@@ -2,9 +2,9 @@
 title: "CLI Reference"
 category: reference
 service: ai-toolkit
-tags: [cli, commands, reference, install, update, plugin, mcp]
+tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-04-15"
+last_updated: "2026-04-24"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -111,7 +111,7 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
+| `stats` | Show skill usage statistics (`--summary` for product telemetry, `--reset` to clear, `--json` for raw output) |
 | `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
 | `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
 | `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
@@ -119,6 +119,17 @@ Usage: ai-toolkit <command> [options]
 | `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
 | `evaluate` | Run skill evaluation suite |
 
+### `stats`
+
+```bash
+ai-toolkit stats                 # table of local skill usage
+ai-toolkit stats --summary       # product telemetry summary
+ai-toolkit stats --summary --json  # machine-readable telemetry
+ai-toolkit stats --reset         # clear local stats
+```
+
+`--summary` reports total invocations, unique skills used, catalog coverage, unused catalog skills, active skills in the last 7 days, and top skills. Data stays local in `~/.softspark/ai-toolkit/stats.json`.
+
 ## Install / Update Options
 
 ```bash

package/kb/reference/competitive-features-implementation.md

@@ -13,7 +13,7 @@ tags:
 doc_type: plan
 status: completed
 created: "2026-04-07"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 completion: "100%"
 description: "Implementation plan for features identified from competitive analysis of everything-claude-code and claude-mem. Focus on learning system, language rules, advanced hooks, MCP templates, and rag-mcp integration. COMPLETED: 8/9 features shipped (1 skipped). See kb/reference/ for permanent documentation."
 ---
@@ -142,8 +142,8 @@ app/rules/
 - [x] 13 languages × 5 rule files created (70 files: 13 dirs × 5 + 5 common)
 - [x] `ai-toolkit install --local` auto-detects language and injects rules (two-phase: marker files + extension scan)
 - [x] Manual override: `ai-toolkit install --local --lang typescript` (with aliases: go→golang, c++→cpp, cs→csharp)
-- [ ] validate.py checks rules format (not yet implemented)
-- [ ] Tests: >=13 (no test_rules file yet)
+- [x] validate.py checks rules format
+- [x] Tests: dedicated `tests/test_rules.bats`
 
 ---
 
@@ -497,7 +497,7 @@ context: fork
 - [x] `/council` invocable
 - [x] 4 perspectives generated
 - [x] Structured output with recommendation
-- [ ] Tests: dedicated council tests not yet written
+- [x] Tests: dedicated council skill contract
 
 ---
 
@@ -516,7 +516,7 @@ context: fork
 **Success Criteria:**
 - [x] Skill auto-loads when writing docs/content
 - [x] Anti-trope list prevents generic LLM rhetoric
-- [ ] Tests: dedicated brand-voice tests not yet written
+- [x] Tests: dedicated brand-voice skill contract
 
 ---
 
@@ -538,7 +538,7 @@ context: fork
 - [x] `/introspect` invocable when agent is stuck
 - [x] Classifies failure pattern
 - [x] Suggests recovery action
-- [ ] Tests: dedicated introspect tests not yet written
+- [x] Tests: dedicated introspect skill contract
 
 ---
 
@@ -660,9 +660,9 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 All major features shipped. Outstanding items:
 
-1. [ ] `validate.py` does not check rules format (1.1)
-2. [ ] No dedicated `test_rules` test file (1.1)
-3. [ ] No dedicated tests for council, brand-voice, introspect skills (3.1-3.3)
+1. [x] `validate.py` checks rules format (1.1)
+2. [x] Dedicated `test_rules` test file exists (1.1)
+3. [x] Dedicated tests exist for council, brand-voice, introspect skills (3.1-3.3)
 4. [x] `observe-session.sh` lives in rag-mcp (consumer), not ai-toolkit — by design
 
 ---

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.4.2"
+version: "1.5.0"
 created: "2026-03-27"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -15,6 +15,12 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
+## Supported Surface
+
+`scripts/validate.py` validates both event names and handler shapes before release. The accepted lifecycle surface includes `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` in addition to the installed ai-toolkit events below.
+
+Supported handler types are `command`, `http`, `prompt`, `agent`, and `mcp_tool`. ai-toolkit ships command hooks by default; non-command handlers are validated so external consumers can safely inject richer hook definitions through `inject-hook`.
+
 ## Installation
 
 ```bash

package/kb/reference/windows-support.md

@@ -0,0 +1,50 @@
+---
+title: "Windows Support"
+category: reference
+service: ai-toolkit
+tags: [windows, wsl, install, dependencies, hooks]
+created: "2026-04-24"
+last_updated: "2026-04-24"
+description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, and hook runtime constraints."
+---
+
+# Windows Support
+
+ai-toolkit supports Windows through two practical modes:
+
+1. **WSL recommended** — best compatibility for Bash hooks, POSIX paths, symlinks, and editor configs.
+2. **Native Windows with Git Bash** — supported for CLI usage when Bash is available on `PATH`.
+
+## Dependency Detection
+
+`scripts/check_deps.py` now emits install hints for Windows package managers:
+
+| Manager | Command Prefix |
+|---------|----------------|
+| winget | `winget install` |
+| Chocolatey | `choco install -y` |
+| Scoop | `scoop install` |
+
+Required dependency package IDs:
+
+| Dependency | winget | Chocolatey | Scoop |
+|------------|--------|------------|-------|
+| Python 3 | `Python.Python.3` | `python` | `python` |
+| Git | `Git.Git` | `git` | `git` |
+| Node.js | `OpenJS.NodeJS` | `nodejs` | `nodejs` |
+
+## Hook Runtime
+
+ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Code can execute `~/.softspark/ai-toolkit/hooks/*.sh`.
+
+Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.
+
+## Verification
+
+```bash
+ai-toolkit doctor
+python3 scripts/check_deps.py
+python3 scripts/validate.py
+```
+
+The Windows support contract is covered by `tests/test_windows_support.bats`.

package/llms-full.txt

@@ -58,6 +58,7 @@
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
+- [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
 
 ## Skills
@@ -6208,9 +6209,9 @@ The reference benchmark set is intentionally curated:
 title: "CLI Reference"
 category: reference
 service: ai-toolkit
-tags: [cli, commands, reference, install, update, plugin, mcp]
+tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-04-15"
+last_updated: "2026-04-24"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -6317,7 +6318,7 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
+| `stats` | Show skill usage statistics (`--summary` for product telemetry, `--reset` to clear, `--json` for raw output) |
 | `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
 | `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
 | `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
@@ -6325,6 +6326,17 @@ Usage: ai-toolkit <command> [options]
 | `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
 | `evaluate` | Run skill evaluation suite |
 
+### `stats`
+
+```bash
+ai-toolkit stats                 # table of local skill usage
+ai-toolkit stats --summary       # product telemetry summary
+ai-toolkit stats --summary --json  # machine-readable telemetry
+ai-toolkit stats --reset         # clear local stats
+```
+
+`--summary` reports total invocations, unique skills used, catalog coverage, unused catalog skills, active skills in the last 7 days, and top skills. Data stays local in `~/.softspark/ai-toolkit/stats.json`.
+
 ## Install / Update Options
 
 ```bash
@@ -6538,7 +6550,7 @@ tags:
 doc_type: plan
 status: completed
 created: "2026-04-07"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 completion: "100%"
 description: "Implementation plan for features identified from competitive analysis of everything-claude-code and claude-mem. Focus on learning system, language rules, advanced hooks, MCP templates, and rag-mcp integration. COMPLETED: 8/9 features shipped (1 skipped). See kb/reference/ for permanent documentation."
 ---
@@ -6667,8 +6679,8 @@ app/rules/
 - [x] 13 languages × 5 rule files created (70 files: 13 dirs × 5 + 5 common)
 - [x] `ai-toolkit install --local` auto-detects language and injects rules (two-phase: marker files + extension scan)
 - [x] Manual override: `ai-toolkit install --local --lang typescript` (with aliases: go→golang, c++→cpp, cs→csharp)
-- [ ] validate.py checks rules format (not yet implemented)
-- [ ] Tests: >=13 (no test_rules file yet)
+- [x] validate.py checks rules format
+- [x] Tests: dedicated `tests/test_rules.bats`
 
 ---
 
@@ -7022,7 +7034,7 @@ context: fork
 - [x] `/council` invocable
 - [x] 4 perspectives generated
 - [x] Structured output with recommendation
-- [ ] Tests: dedicated council tests not yet written
+- [x] Tests: dedicated council skill contract
 
 ---
 
@@ -7041,7 +7053,7 @@ context: fork
 **Success Criteria:**
 - [x] Skill auto-loads when writing docs/content
 - [x] Anti-trope list prevents generic LLM rhetoric
-- [ ] Tests: dedicated brand-voice tests not yet written
+- [x] Tests: dedicated brand-voice skill contract
 
 ---
 
@@ -7063,7 +7075,7 @@ context: fork
 - [x] `/introspect` invocable when agent is stuck
 - [x] Classifies failure pattern
 - [x] Suggests recovery action
-- [ ] Tests: dedicated introspect tests not yet written
+- [x] Tests: dedicated introspect skill contract
 
 ---
 
@@ -7185,9 +7197,9 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 All major features shipped. Outstanding items:
 
-1. [ ] `validate.py` does not check rules format (1.1)
-2. [ ] No dedicated `test_rules` test file (1.1)
-3. [ ] No dedicated tests for council, brand-voice, introspect skills (3.1-3.3)
+1. [x] `validate.py` checks rules format (1.1)
+2. [x] Dedicated `test_rules` test file exists (1.1)
+3. [x] Dedicated tests exist for council, brand-voice, introspect skills (3.1-3.3)
 4. [x] `observe-session.sh` lives in rag-mcp (consumer), not ai-toolkit — by design
 
 ---
@@ -8159,9 +8171,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.4.2"
+version: "1.5.0"
 created: "2026-03-27"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -8171,6 +8183,12 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
+## Supported Surface
+
+`scripts/validate.py` validates both event names and handler shapes before release. The accepted lifecycle surface includes `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` in addition to the installed ai-toolkit events below.
+
+Supported handler types are `command`, `http`, `prompt`, `agent`, and `mcp_tool`. ai-toolkit ships command hooks by default; non-command handlers are validated so external consumers can safely inject richer hook definitions through `inject-hook`.
+
 ## Installation
 
 ```bash
@@ -11326,6 +11344,61 @@ Agents follow a research-before-action protocol enforced via rules:
 
 ---
 
+## kb/reference/windows-support.md
+
+---
+title: "Windows Support"
+category: reference
+service: ai-toolkit
+tags: [windows, wsl, install, dependencies, hooks]
+created: "2026-04-24"
+last_updated: "2026-04-24"
+description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, and hook runtime constraints."
+---
+
+# Windows Support
+
+ai-toolkit supports Windows through two practical modes:
+
+1. **WSL recommended** — best compatibility for Bash hooks, POSIX paths, symlinks, and editor configs.
+2. **Native Windows with Git Bash** — supported for CLI usage when Bash is available on `PATH`.
+
+## Dependency Detection
+
+`scripts/check_deps.py` now emits install hints for Windows package managers:
+
+| Manager | Command Prefix |
+|---------|----------------|
+| winget | `winget install` |
+| Chocolatey | `choco install -y` |
+| Scoop | `scoop install` |
+
+Required dependency package IDs:
+
+| Dependency | winget | Chocolatey | Scoop |
+|------------|--------|------------|-------|
+| Python 3 | `Python.Python.3` | `python` | `python` |
+| Git | `Git.Git` | `git` | `git` |
+| Node.js | `OpenJS.NodeJS` | `nodejs` | `nodejs` |
+
+## Hook Runtime
+
+ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Code can execute `~/.softspark/ai-toolkit/hooks/*.sh`.
+
+Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.
+
+## Verification
+
+```bash
+ai-toolkit doctor
+python3 scripts/check_deps.py
+python3 scripts/validate.py
+```
+
+The Windows support contract is covered by `tests/test_windows_support.bats`.
+
+---
+
 ## kb/troubleshooting/README.md
 
 ---

package/llms.txt

@@ -58,4 +58,5 @@
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
+- [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
@@ -62,7 +62,11 @@
     "generate:codex-rules": "python3 scripts/generate_codex_rules.py .",
     "generate:opencode-agents": "python3 scripts/generate_opencode_agents.py .",
     "generate:opencode-commands": "python3 scripts/generate_opencode_commands.py .",
-    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+    "generate:cursor-mdc": "python3 scripts/generate_cursor_mdc.py .",
+    "generate:windsurf-rules": "python3 scripts/generate_windsurf_rules.py .",
+    "generate:roo-rules": "python3 scripts/generate_roo_rules.py .",
+    "generate:augment-rules": "python3 scripts/generate_augment_rules.py .",
+    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:cursor-mdc && npm run generate:windsurf && npm run generate:windsurf-rules && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:roo-rules && npm run generate:aider && npm run generate:augment-rules && npm run generate:llms"
   },
   "files": [
     "bin/",

package/scripts/_common.py

@@ -165,6 +165,27 @@ def detect_os() -> dict[str, str]:
             "install_cmd": install_cmd,
         }
 
+    if system == "windows":
+        managers = (
+            ("winget", "winget install"),
+            ("choco", "choco install -y"),
+            ("scoop", "scoop install"),
+        )
+        for manager, install_cmd in managers:
+            if shutil.which(manager):
+                return {
+                    "os": "Windows",
+                    "distro": platform.version(),
+                    "pkg_manager": manager,
+                    "install_cmd": install_cmd,
+                }
+        return {
+            "os": "Windows",
+            "distro": platform.version(),
+            "pkg_manager": "none",
+            "install_cmd": "",
+        }
+
     return {
         "os": system,
         "distro": "",

package/scripts/check_deps.py

@@ -37,6 +37,9 @@ REQUIRED = [
             "pacman": "python3",
             "apk": "python3",
             "zypper": "python3",
+            "winget": "Python.Python.3",
+            "choco": "python",
+            "scoop": "python",
         },
         "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
     },
@@ -50,6 +53,9 @@ REQUIRED = [
             "pacman": "git",
             "apk": "git",
             "zypper": "git",
+            "winget": "Git.Git",
+            "choco": "git",
+            "scoop": "git",
         },
         "reason": "Version control — hooks, commits, PR workflows",
     },
@@ -64,6 +70,9 @@ REQUIRED = [
             "pacman": "nodejs",
             "apk": "nodejs",
             "zypper": "nodejs18",
+            "winget": "OpenJS.NodeJS",
+            "choco": "nodejs",
+            "scoop": "nodejs",
         },
         "reason": "CLI entry point (bin/ai-toolkit.js)",
     },
@@ -80,6 +89,9 @@ OPTIONAL = [
             "pacman": "sqlite",
             "apk": "sqlite",
             "zypper": "sqlite3",
+            "winget": "SQLite.SQLite",
+            "choco": "sqlite",
+            "scoop": "sqlite",
         },
         "reason": "Memory plugin pack (session persistence via SQLite + FTS5)",
     },
@@ -93,6 +105,8 @@ OPTIONAL = [
             "pacman": "bash-bats",
             "apk": "bats",
             "zypper": "bats",
+            "choco": "bats",
+            "scoop": "bats",
         },
         "reason": "Running toolkit test suite (npm test)",
     },

package/scripts/stats.py

@@ -5,11 +5,13 @@ Reads ~/.softspark/ai-toolkit/stats.json (populated by track-usage.sh hook)
 and displays a sorted table of skill invocations.
 
 Options:
-  --reset   Clear all stats
-  --json    Output raw JSON
+  --reset     Clear all stats
+  --json      Output raw JSON
+  --summary   Output product telemetry summary
 """
 from __future__ import annotations
 
+from datetime import datetime, timedelta
 import json
 import sys
 from pathlib import Path
@@ -18,14 +20,120 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 from paths import STATS_FILE as _STATS_FILE
 
 STATS_FILE = _STATS_FILE
+TOOLKIT_DIR = Path(__file__).resolve().parent.parent
+
+
+def _load_stats() -> dict:
+    """Load the stats file, returning an empty dict when absent."""
+    if not STATS_FILE.is_file():
+        return {}
+    with open(STATS_FILE, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _aggregate_rows(data: dict) -> list[tuple[str, dict]]:
+    """Normalize supported stats formats into sorted (name, info) rows."""
+    if not data:
+        return []
+
+    # Handle both formats: {skill: {count, last_used}} and {loop_runs: [...]}
+    if "loop_runs" in data:
+        agg: dict[str, dict] = {}
+        for run in data.get("loop_runs", []):
+            cmd = run.get("command", "unknown")
+            iters = run.get("iterations", [])
+            if cmd not in agg:
+                agg[cmd] = {"count": 0, "last_used": "unknown"}
+            agg[cmd]["count"] += len(iters) if iters else 1
+            started = run.get("started_at", "")
+            if started > agg[cmd]["last_used"]:
+                agg[cmd]["last_used"] = started
+        return sorted(agg.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+
+    skill_data = {k: v for k, v in data.items() if isinstance(v, dict)}
+    return sorted(skill_data.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+
+
+def _catalog_skill_names() -> set[str]:
+    """Return skill directory names from the installed toolkit catalog."""
+    skills_dir = TOOLKIT_DIR / "app" / "skills"
+    if not skills_dir.is_dir():
+        return set()
+    return {
+        p.name
+        for p in skills_dir.iterdir()
+        if p.is_dir() and not p.name.startswith("_") and (p / "SKILL.md").is_file()
+    }
+
+
+def _parse_datetime(value: str) -> datetime | None:
+    """Parse stats timestamps emitted by toolkit hooks and loop runs."""
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%SZ"):
+        try:
+            return datetime.strptime(value[:19] + ("Z" if fmt.endswith("Z") else ""), fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _build_summary(rows: list[tuple[str, dict]]) -> dict:
+    """Build machine-readable product telemetry from aggregated rows."""
+    catalog = _catalog_skill_names()
+    used_names = {name for name, _ in rows}
+    used_catalog = used_names & catalog if catalog else used_names
+    total = sum(int(info.get("count", 0) or 0) for _, info in rows)
+
+    cutoff = datetime.now() - timedelta(days=7)
+    active_7d = 0
+    for _, info in rows:
+        last_used = _parse_datetime(str(info.get("last_used", "")))
+        if last_used and last_used >= cutoff:
+            active_7d += 1
+
+    catalog_total = len(catalog)
+    unused = max(catalog_total - len(used_catalog), 0) if catalog_total else 0
+
+    return {
+        "totalInvocations": total,
+        "uniqueSkillsUsed": len(used_names),
+        "catalogSkillsTotal": catalog_total,
+        "unusedCatalogSkills": unused,
+        "catalogCoveragePct": round((len(used_catalog) / catalog_total) * 100, 1) if catalog_total else 0,
+        "activeSkills7d": active_7d,
+        "topSkills": [
+            {
+                "name": name,
+                "count": int(info.get("count", 0) or 0),
+                "lastUsed": info.get("last_used", "unknown"),
+            }
+            for name, info in rows[:5]
+        ],
+    }
+
+
+def _print_summary(summary: dict) -> None:
+    """Print a compact human-readable product telemetry summary."""
+    print("Product Telemetry")
+    print("=================")
+    print(f"Total invocations: {summary['totalInvocations']}")
+    print(f"Unique skills used: {summary['uniqueSkillsUsed']}")
+    print(f"Catalog skills total: {summary['catalogSkillsTotal']}")
+    print(f"Unused catalog skills: {summary['unusedCatalogSkills']}")
+    print(f"Catalog coverage: {summary['catalogCoveragePct']}%")
+    print(f"Active skills in last 7 days: {summary['activeSkills7d']}")
+    if summary["topSkills"]:
+        print()
+        print("Top skills:")
+        for item in summary["topSkills"]:
+            print(f"- {item['name']}: {item['count']} ({item['lastUsed']})")
 
 
 def main() -> None:
     """Display, export, or reset usage statistics."""
-    flag = sys.argv[1] if len(sys.argv) > 1 else ""
+    args = set(sys.argv[1:])
 
     # --reset
-    if flag == "--reset":
+    if "--reset" in args:
         if STATS_FILE.is_file():
             STATS_FILE.unlink()
             print("Stats reset.")
@@ -33,12 +141,20 @@ def main() -> None:
             print("No stats file found.")
         return
 
-    # --json
-    if flag == "--json":
-        if STATS_FILE.is_file():
-            print(STATS_FILE.read_text(encoding="utf-8"), end="")
+    data = _load_stats()
+    rows = _aggregate_rows(data)
+
+    if "--summary" in args:
+        summary = _build_summary(rows)
+        if "--json" in args:
+            print(json.dumps(summary, indent=2))
         else:
-            print("{}")
+            _print_summary(summary)
+        return
+
+    # --json
+    if "--json" in args:
+        print(STATS_FILE.read_text(encoding="utf-8") if STATS_FILE.is_file() else "{}")
         return
 
     # Default: pretty-print table
@@ -53,39 +169,10 @@ def main() -> None:
     print("========================")
     print()
 
-    with open(STATS_FILE, encoding="utf-8") as f:
-        data: dict = json.load(f)
-
-    if not data:
+    if not rows:
         print("No invocations recorded.")
         return
 
-    # Handle both formats: {skill: {count, last_used}} and {loop_runs: [...]}
-    if "loop_runs" in data:
-        runs = data["loop_runs"]
-        if not runs:
-            print("No invocations recorded.")
-            return
-        # Aggregate loop_runs by command
-        agg: dict[str, dict] = {}
-        for run in runs:
-            cmd = run.get("command", "unknown")
-            iters = run.get("iterations", [])
-            if cmd not in agg:
-                agg[cmd] = {"count": 0, "last_used": "unknown"}
-            agg[cmd]["count"] += len(iters) if iters else 1
-            started = run.get("started_at", "")
-            if started > agg[cmd]["last_used"]:
-                agg[cmd]["last_used"] = started
-        rows = sorted(agg.items(), key=lambda x: x[1]["count"], reverse=True)
-    else:
-        # Original format: {skill_name: {count, last_used}}
-        skill_data = {k: v for k, v in data.items() if isinstance(v, dict)}
-        if not skill_data:
-            print("No invocations recorded.")
-            return
-        rows = sorted(skill_data.items(), key=lambda x: x[1].get("count", 0), reverse=True)
-
     print(f"{'Skill':<30} {'Count':>6}  {'Last Used':<20}")
     print("-" * 60)
     for name, info in rows:

package/scripts/validate.py

@@ -42,9 +42,9 @@ VALID_HOOK_EVENTS = frozenset({
     # Core lifecycle
     "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
     # Tool lifecycle
-    "PreToolUse", "PostToolUse",
+    "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
     # Turn lifecycle
-    "Stop", "StopFailure",
+    "Stop", "StopFailure", "UserPromptExpansion",
     # Subagent lifecycle
     "SubagentStart", "SubagentStop",
     # Compaction
@@ -61,11 +61,67 @@ VALID_HOOK_EVENTS = frozenset({
     "Setup", "InstructionsLoaded",
 })
 
+VALID_HOOK_TYPES = frozenset({
+    "command",
+    "http",
+    "prompt",
+    "agent",
+    "mcp_tool",
+})
+
+HOOK_TYPE_EVENTS = {
+    "agent": frozenset({"Stop", "SubagentStop"}),
+    "prompt": frozenset({
+        "PreToolUse",
+        "PostToolUse",
+        "PostToolUseFailure",
+        "PostToolBatch",
+        "UserPromptSubmit",
+        "UserPromptExpansion",
+        "Stop",
+        "SubagentStop",
+    }),
+}
+
+HOOK_REQUIRED_FIELDS = {
+    "command": ("command",),
+    "http": ("url",),
+    "prompt": ("prompt",),
+    "agent": ("agent",),
+    "mcp_tool": ("server", "tool", "arguments"),
+}
+
 VALID_KB_CATEGORIES = frozenset({
     "reference", "howto", "procedures", "troubleshooting", "best-practices",
     "planning",
 })
 
+VALID_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "performance",
+    "git-workflow",
+    "patterns",
+    "frameworks",
+})
+
+COMMON_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "performance",
+    "git-workflow",
+})
+
+LANGUAGE_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "patterns",
+    "frameworks",
+})
+
 PLANNED_ASSETS = [
     "app/.claude-plugin/plugin.json",
     "scripts/doctor.py",
@@ -354,8 +410,49 @@ def validate_legacy_commands(tk_dir: Path, vr: ValidationResult) -> None:
             print()
 
 
+def _validate_hook_handler(event: str, hook: dict, vr: ValidationResult) -> None:
+    """Validate one hooks.json handler object."""
+    hook_type = hook.get("type")
+    if not hook_type:
+        vr.error(f"{event}: hook entry missing type")
+        return
+
+    if hook_type not in VALID_HOOK_TYPES:
+        vr.error(f"Unsupported hook handler type '{hook_type}' for event {event}")
+        return
+
+    allowed_events = HOOK_TYPE_EVENTS.get(hook_type)
+    if allowed_events is not None and event not in allowed_events:
+        vr.error(f"Hook type '{hook_type}' is not supported for event {event}")
+
+    for field in HOOK_REQUIRED_FIELDS.get(hook_type, ()):
+        if field not in hook:
+            vr.error(f"{event}: hook type '{hook_type}' missing required field '{field}'")
+
+
+def _validate_hook_entries(event: str, entries: object, vr: ValidationResult) -> None:
+    """Validate hooks.json matcher entries for one event."""
+    if not isinstance(entries, list):
+        vr.error(f"{event}: expected list of hook matcher entries")
+        return
+
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            vr.error(f"{event}[{index}]: expected hook matcher entry object")
+            continue
+        hooks = entry.get("hooks")
+        if not isinstance(hooks, list) or not hooks:
+            vr.error(f"{event}[{index}]: missing non-empty hooks list")
+            continue
+        for hook_index, hook in enumerate(hooks):
+            if not isinstance(hook, dict):
+                vr.error(f"{event}[{index}].hooks[{hook_index}]: expected hook object")
+                continue
+            _validate_hook_handler(event, hook, vr)
+
+
 def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
-    """Validate hook event names in hooks.json."""
+    """Validate hook event names and handler shapes in hooks.json."""
     print("## Hook Events")
     hooks_file = tk_dir / "app" / "hooks.json"
 
@@ -373,9 +470,10 @@ def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
         return
 
     hooks = data.get("hooks", {})
-    for event in hooks:
+    for event, entries in hooks.items():
         if event in VALID_HOOK_EVENTS:
             print(f"  OK: {event}")
+            _validate_hook_entries(event, entries, vr)
         else:
             vr.error(f"Unknown hook event: {event}")
 
@@ -386,6 +484,63 @@ def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
     print()
 
 
+def validate_language_rules(tk_dir: Path, vr: ValidationResult) -> None:
+    """Validate structured language-rule directories under app/rules."""
+    print("## Language Rules")
+    rules_dir = tk_dir / "app" / "rules"
+    rule_count = 0
+    rule_errors = 0
+
+    if not rules_dir.is_dir():
+        vr.error("app/rules directory not found")
+        print()
+        return
+
+    for rule_dir in sorted(p for p in rules_dir.iterdir() if p.is_dir()):
+        language = rule_dir.name
+        expected = COMMON_RULE_CATEGORIES if language == "common" else LANGUAGE_RULE_CATEGORIES
+        seen: set[str] = set()
+
+        for rule_file in sorted(rule_dir.glob("*.md")):
+            rel = str(rule_file.relative_to(tk_dir))
+            rule_count += 1
+            if not _has_frontmatter(rule_file):
+                vr.error(f"{rel} - Missing YAML frontmatter")
+                rule_errors += 1
+                continue
+
+            fm_lines = _parse_frontmatter_lines(rule_file)
+            for field in ("language", "category", "version"):
+                if not _fm_has(fm_lines, field):
+                    vr.error(f"{rel} - Missing required field: {field}")
+                    rule_errors += 1
+
+            rule_language = _fm_field(fm_lines, "language").strip()
+            if rule_language and rule_language != language:
+                vr.error(f"{rel} language '{rule_language}' does not match directory '{language}'")
+                rule_errors += 1
+
+            category = _fm_field(fm_lines, "category").strip()
+            if category:
+                seen.add(category)
+                if category not in VALID_RULE_CATEGORIES:
+                    vr.error(f"{rel} has invalid rule category '{category}'")
+                    rule_errors += 1
+                if rule_file.stem != category:
+                    vr.error(f"{rel} filename does not match category '{category}'")
+                    rule_errors += 1
+
+        for category in sorted(expected - seen):
+            vr.error(f"app/rules/{language} missing required rule category: {category}")
+            rule_errors += 1
+
+    if rule_errors == 0:
+        print(f"  OK: {rule_count} rule files validated")
+    else:
+        print(f"  Found: {rule_count} rule files ({rule_errors} with errors)")
+    print()
+
+
 def validate_planned_assets(tk_dir: Path, vr: ValidationResult) -> None:
     """Validate that planned assets exist and are non-empty."""
     print("## Planned Assets")
@@ -781,6 +936,7 @@ def _run_all_checks(tk_dir: Path, vr: ValidationResult) -> tuple[int, int, str]:
     skill_count = validate_skills(tk_dir, vr)
     validate_legacy_commands(tk_dir, vr)
     validate_hook_events(tk_dir, vr)
+    validate_language_rules(tk_dir, vr)
     validate_planned_assets(tk_dir, vr)
     validate_plugin_packs(tk_dir, vr)
     validate_kb_documents(tk_dir, vr)