@softspark/ai-toolkit 4.30.3 → 4.32.0

package/kb/reference/language-rules.md

@@ -3,9 +3,9 @@ title: "Language Rules System"
 category: reference
 service: ai-toolkit
 tags: [rules, languages, coding-style, testing, patterns, security]
-version: "2.1.0"
+version: "2.2.0"
 created: "2026-04-07"
-last_updated: "2026-06-30"
+last_updated: "2026-09-04"
 description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus common rules installed as Claude Code path-scoped project rules."
 ---
 
@@ -55,7 +55,7 @@ app/rules/
 └── medplum/
 ```
 
-**Total: 13 per-language directories × 5 files + 1 common directory × 5 files + 3 standalone files** (see README.md for canonical count). Per-language directories ship as `<lang>-rules` knowledge skills; the common directory is installed as Claude Code `.claude/rules/ai-toolkit-*.md` files.
+**Total: 13 per-language directories × 5 files + 1 common directory × 6 files (5 in every profile + `git-team` in `strict`) + 3 standalone files** (see README.md for canonical count). Per-language directories ship as `<lang>-rules` knowledge skills; the common directory is installed as Claude Code `.claude/rules/ai-toolkit-*.md` files.
 
 ## Supported Languages
 
@@ -145,13 +145,16 @@ Common rules are installed as path-scoped Claude Code rule files:
 ```
 .claude/rules/
 ├── ai-toolkit-coding-style.md
+├── ai-toolkit-git-team.md        # --profile strict only
 ├── ai-toolkit-git-workflow.md
 ├── ai-toolkit-performance.md
 ├── ai-toolkit-security.md
 └── ai-toolkit-testing.md
 ```
 
-Each file starts with:
+A source rule may also carry `profiles:` (same block-list form). `git-team` declares `profiles: ["strict"]`: branching, pull-request, and review conventions for teams, kept out of `standard` so a solo maintainer who releases straight to `main` is not told to open PRs against themselves. Rerunning `install --local` with a different profile adds or removes the managed file. Only the Claude Code local install honours `profiles`; the Claude app export, `compile-slm`, and editor `lang-common` bundles still receive every common rule (see `DECISIONS.md`, 2026-09-04).
+
+Each file's `paths` frontmatter is copied from the source rule in `app/rules/common/<category>.md`. A source rule without a `paths` block is always-on:
 
 ```yaml
 ---
@@ -160,6 +163,18 @@ paths:
 ---
 ```
 
+A source rule with a `paths` block is path-scoped, so Claude Code loads it only when a matching file is touched. As of v4.32.0 `testing` (`**/*.test.*`, `**/*.spec.*`, `**/test_*`, `**/*_test.*`, `**/tests/**`) and `performance` (source-file extensions plus `**/*.sql`) are scoped; `coding-style`, `git-workflow`, and `security` stay always-on because they carry prohibitions that must hold in every session. To change a scope, edit the source frontmatter; `validate.py` rejects inline lists and unquoted globs because the installer reads only the block form:
+
+```yaml
+---
+language: common
+category: testing
+version: "1.1.0"
+paths:
+  - "**/tests/**"
+---
+```
+
 The project `CLAUDE.md` receives only a compact index between a single named marker (the per-language markers from v1.x are no longer used):
 
 ```
@@ -167,10 +182,13 @@ The project `CLAUDE.md` receives only a compact index between a single named mar
 # Language Rules
 
 Common ai-toolkit rules live in `.claude/rules/ai-toolkit-*.md`
-with Claude Code `paths` frontmatter so they load when project files
-are opened instead of expanding this CLAUDE.md at session startup.
+with Claude Code `paths` frontmatter instead of expanding this
+CLAUDE.md. Always-on rules load in every session; path-scoped rules
+load only when a matching file is touched.
+
+Always-on: `.claude/rules/ai-toolkit-coding-style.md`, ...
 
-Common rule files: `.claude/rules/ai-toolkit-coding-style.md`, ...
+Path-scoped: `.claude/rules/ai-toolkit-performance.md`, ...
 
 Language-specific rules live in `<lang>-rules` knowledge skills (e.g.
 `python-rules`, `typescript-rules`) and load automatically when their
@@ -207,7 +225,7 @@ Language rules are tracked as modules in `manifest.json`:
 
 | Module | Description |
 |--------|-------------|
-| `rules-common` | Common coding rules (5 files), included in `standard` profile |
+| `rules-common` | Common coding rules (6 files: 5 in every profile, `git-team` in `strict` only), included in `standard` profile |
 | `rules-typescript` | TypeScript-specific rules |
 | `rules-python` | Python-specific rules |
 | `rules-golang` | Go-specific rules |
@@ -228,9 +246,9 @@ Language rules are tracked as modules in `manifest.json`:
 |---|---|---|---|
 | Source | `app/rules/common/` | `app/rules/<lang>/` | `app/skills/<name>/SKILL.md` |
 | Delivery to Claude | Path-scoped `.claude/rules/ai-toolkit-*.md` files (`--local`) + compact `CLAUDE.md` index | Generated as `<lang>-rules` knowledge skills, loaded contextually | Loaded contextually by description match |
-| Visibility | Loaded when project files are opened | Loaded when triggers match (file extensions, framework names) | Loaded when triggers match |
+| Visibility | Always-on (`coding-style`, `git-workflow`, `security`) or loaded when a matching file is touched (`testing`, `performance`) | Loaded when triggers match (file extensions, framework names) | Loaded when triggers match |
 | Scope | Language-agnostic standards (security, git, testing, perf, style) | Per-language coding-style, frameworks, patterns, security, testing | Domain skills (testing, debugging, RAG, etc.) |
-| Install | `ai-toolkit install --local` | Global install (skills directory is symlinked) | Global install |
+| Install | `ai-toolkit install --local` | Global install (skills directory is symlinked); skills for languages no registered project uses are turned off via `skillOverrides` (`--language-skills detected`, the default) unless `--language-skills all` was chosen | Global install |
 | Other editors | Inlined into editor-specific rule files | Inlined into editor-specific rule files (still full content, not skills) | N/A |
 
 Per-language content delivered as a knowledge skill is the same Markdown that other editors receive inlined. The split exists only for Claude, where the Agent Skills progressive-disclosure mechanism keeps the system prompt small.

package/kb/reference/licensing.md

@@ -131,7 +131,7 @@ MIT remnant would need each contributor's agreement.
 
 It is a test rather than a checklist line on purpose. This project has two
 same-day postmortems about SOPs that existed and were skipped; CI does not skip.
-[Release Preparation](../procedures/release-preparation-sop.md) Phase 5c runs the
+[Release Preparation](../procedures/sop-release.md) Phase 5c runs the
 same gate before tagging so a failure surfaces before the tag, not after.
 
 ## If the licence ever changes again
@@ -144,5 +144,5 @@ source, cross-verify against a second independent copy, and only then write
 ## Related
 
 - [`LICENSE`](../../LICENSE), [`NOTICE`](../../NOTICE)
-- [Release Preparation SOP](../procedures/release-preparation-sop.md) — Phase 5c
+- [Release Preparation SOP](../procedures/sop-release.md) — Phase 5c
 - [Distribution Model](distribution-model.md) — what ships and where

package/kb/reference/quick-wins-implementation-summary.md

@@ -53,7 +53,7 @@ Updated baseline docs:
 - `kb/reference/skills-catalog.md`
 - `kb/reference/plugin-pack-conventions.md`
 - `kb/reference/claude-ecosystem-benchmark-snapshot.md`
-- `kb/procedures/maintenance-sop.md`
+- `kb/procedures/sop-maintenance.md`
 
 ## Validation Evidence
 

package/kb/reference/supported-tools-registry.md

@@ -285,13 +285,13 @@ See [DSH Compatibility](./dsh-compatibility.md) for commands, topology, subscrip
 2. Delete its section from this document.
 3. Delete its snapshot entry from `benchmarks/ecosystem-doctor-snapshot.json` (or let the next `--update` prune it — currently not pruned automatically).
 4. Decide whether to keep the generator (`scripts/generate_<tool>_*.py`) for backwards compatibility or delete it.
-5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/maintenance-sop.md` `Supported editors` line.
+5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/sop-maintenance.md` `Supported editors` line.
 
 ---
 
 ## Related
 
-- [Ecosystem Sync SOP](../procedures/ecosystem-sync-sop.md) — how to use the doctor
+- [Ecosystem Sync SOP](../procedures/sop-ecosystem-sync.md) — how to use the doctor
 - [MCP Editor Compatibility](./mcp-editor-compatibility.md) — MCP-specific subset
 - `scripts/ecosystem_tools.json` — source of truth
 - `scripts/ecosystem_doctor.py` — drift detector

package/kb/reference/unique-features.md

@@ -4,7 +4,7 @@ category: reference
 service: ai-toolkit
 tags: [features, differentiators, constitution, hooks, security, tdd, memory]
 created: "2026-04-13"
-last_updated: "2026-08-06"
+last_updated: "2026-09-04"
 description: "Detailed description of ai-toolkit's unique features: constitution enforcement, hooks system, security scanning, effort budgeting, quality gates, and more."
 ---
 
@@ -119,6 +119,7 @@ added after the thing it checks had already shipped broken.
 | **Public surface** (`surface_manifest.py` + `app/surface.json`) | a skill, agent, CLI command, frontmatter field, hook, KB category or pack disappearing | `BACKWARD_COMPATIBILITY.md` listed the surfaces; renaming one still left every check green |
 | **Script invocation** (`validate.py`) | a skill running its own script by any path other than `${CLAUDE_SKILL_DIR}`, or through the wrong interpreter | nine skills shipped invocations that resolved only in the repo, never on an installed machine |
 | **Skill body budget** (`validate.py`) | a `SKILL.md` body over 20,000 bytes; warns over 18,000 | the body loads on every trigger match, including accidental ones; three skills sat at 24–35 KB |
+| **Skill description budget** (`validate.py`) | a description over 1,024 characters (the Agent Skills cap; the runtime truncates past it), or an unquoted description containing `: ` or ` #` (strict YAML drops every field, `allowed-tools` included); warns over 400; applied to plugin-pack skills too | two installed skills sat at 791 and 883 characters and made up 8% of the model's skill listing on their own |
 | **Split integrity** (`check_split.py`) | a body → `reference/` refactor that lost a fenced code line, a required section, the description, or a working link | run by hand during a split; caught a heading corrupted inside a fenced example on first use |
 
 The surface check is deliberately one-directional: **removals fail, additions pass.**

package/kb/troubleshooting/plugin-double-load.md

@@ -94,4 +94,4 @@ Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
 ## Related
 
 - `kb/reference/global-install-model.md`
-- `kb/procedures/maintenance-sop.md`
+- `kb/procedures/sop-maintenance.md`