@softspark/ai-toolkit 4.31.0 → 4.32.0

package/kb/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.4.0"
+version: "3.5.0"
 created: "2026-03-26"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -17,6 +17,19 @@ description: "Reference description of Claude Code global install, Claude app pl
 
 That means one machine-level install provides agents, skills, hooks, constitution, and rule files to every project without committing toolkit boilerplate into each repository.
 
+Language knowledge skills are the one part of the global install that is
+scoped by evidence (v4.32.0). Every `<lang>-rules` / `<lang>-patterns` skill is
+still symlinked, but `install` and `update` read the languages detected across
+the projects registered in `projects.json` and set `skillOverrides: off` in
+`~/.claude/settings.json` for the others, so their descriptions stop loading
+into every session. The entries the toolkit wrote are listed in `state.json`
+under `managed_skill_overrides`; only those are ever removed again (when a
+newly registered project brings the language back), a user's own override is
+left alone. With no registered project on disk nothing is disabled.
+`--language-skills all` restores everything and persists the choice
+(`language_skill_scope` in `state.json`); `ai-toolkit doctor` reports the
+resulting listing size and zero-use skills.
+
 Other editor targets are opt-in and only use documented file surfaces. Cursor
 rules stay project-local because Cursor's global user rules are managed through
 the settings UI, not a stable merge-safe file. Codex supports both project and
@@ -59,7 +72,7 @@ The `--profile` flag controls how much of each editor's native surface is activa
 |---------|-----------|----------|
 | `minimal` | Smallest editor surface. Copilot still receives its root instructions, native agents, and self-contained skills; Codex still receives instructions, agents, skills, and native safety hooks. | You want the smallest supported footprint. |
 | `standard` (default) | Claude Code + editor rule files. Includes Gemini and Antigravity hooks plus native Copilot instructions, agents, portable skills, and hooks. | Day-to-day installs. Most users. |
-| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
+| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks and the `git-team` common rule (feature branches, PR size, required approval, review SLA). | Tight team with zero tolerance for drift. A solo maintainer releasing straight to `main` wants `standard`, which keeps the solo-safe `git-workflow` core only. |
 | `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |
 
 Codex installs materialize the full skill catalog under `.agents/skills/`

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.11.0"
+version: "1.12.0"
 created: "2026-03-27"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -190,6 +190,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Matcher | *(all)* |
 | Script | `~/.softspark/ai-toolkit/hooks/quality-check.sh` |
 | Fires | After every Claude response |
+| Mode | Background (`"async": true`). The linter (`npx tsc`, `ruff`) was the bulk of a 3.3 s median Stop chain; its output is advisory and reaches you when it finishes instead of holding the turn open |
 
 **Action:** Runs language-appropriate linter:
 - Python: `ruff check .`
@@ -208,6 +209,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Matcher | *(all)* |
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
+| Mode | Background (`"async": true`): writes a file and exits 0, nothing to wait for |
 
 **Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
@@ -225,7 +227,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
 | Fires | Before Claude is allowed to finish a response |
 
-**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session.
+**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session. Ruff runs only when the project configured it (`ruff.toml`, `.ruff.toml`, or a `[tool.ruff]` table in `pyproject.toml`); a `pyproject.toml` that only carries build or pytest/mypy metadata does not trigger `ruff check .` under whatever configuration the machine resolves (v4.32.0).
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 

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/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/llms-full.txt

@@ -7204,9 +7204,9 @@ title: "SOP: AI Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.4.0"
+version: "3.5.0"
 created: "2026-03-23"
-last_updated: "2026-08-06"
+last_updated: "2026-09-04"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -7430,7 +7430,9 @@ that runtime should receive the change.
    greets the user with a traceback, and one that reads stdin must answer an
    empty stdin with an error rather than blocking forever.
 3. Update `kb/reference/skills-catalog.md` and `app/ARCHITECTURE.md`
-4. Run `scripts/validate.py` — it checks the invocation, the body budget, and
+4. Run `scripts/validate.py` — it checks the invocation, the body budget, the
+   description budget (warn over 400 characters, error over 1024; unquoted
+   descriptions containing `: ` or ` #` are rejected, use `>-`), and
    `reference/` link resolution
 5. Run `python3 scripts/surface_manifest.py` before the next release to adopt the
    new skill into the protected surface
@@ -7506,6 +7508,7 @@ bats tests/test_install.bats tests/test_codex.bats
 bats tests/test_claude_app.bats tests/test_hooks_per_editor.bats
 python3 scripts/claude_app.py verify
 python3 scripts/validate.py --strict
+npm run test:py   # pytest over scripts/ logic incl. the frontmatter corpus test (dev venv, see CONTRIBUTING.md)
 ```
 
 ## Managing Plugins
@@ -10453,7 +10456,7 @@ category: reference
 service: ai-toolkit
 tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -10468,6 +10471,7 @@ Usage: ai-toolkit <command> [options]
 | Command | Description |
 |---------|-------------|
 | `install` | First-time global install into `~/.claude/` + Cursor, Windsurf, Gemini |
+| `install --language-skills detected\|all` | `detected` (default): turn off `<lang>-rules`/`<lang>-patterns` skills for languages no registered project uses, via `skillOverrides` in `~/.claude/settings.json` (entries are tracked in `state.json` and restored when a project brings the language back; a user's own override is never touched); `all`: keep every language skill on. The choice persists across `install`/`update` |
 | `install --local` | Claude Code configs only; add `--editors all` or `--editors cursor,aider` for other tools |
 | `update` | Re-apply toolkit after `npm install -g @softspark/ai-toolkit@latest` |
 | `update --local` | Re-apply + auto-detect editors from existing project files |
@@ -10475,7 +10479,7 @@ Usage: ai-toolkit <command> [options]
 | `status` | Show installed modules and version |
 | `uninstall` | Remove toolkit from `~/.claude/` |
 | `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
-| `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
+| `doctor` | Diagnose install health, hooks, quick-win assets, artifact drift, context budget (est. resident tokens of the skill/agent listings and user rules, plus skills with zero recorded use; read-only, prints the `skillOverrides` key to paste), and permission rules (`permissions.allow` wildcards on interpreters, task runners, package installs, `gh api`, `curl`, `git fetch`, destructive commands; warns only, never edits) |
 | `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
 | `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
 | `claude-app export [--output FILE] [--no-custom-rules] [--verify]` | Build an uploadable Claude Chat/Desktop/Cowork plugin ZIP and global-instructions file |
@@ -12780,9 +12784,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.4.0"
+version: "3.5.0"
 created: "2026-03-26"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -12794,6 +12798,19 @@ description: "Reference description of Claude Code global install, Claude app pl
 
 That means one machine-level install provides agents, skills, hooks, constitution, and rule files to every project without committing toolkit boilerplate into each repository.
 
+Language knowledge skills are the one part of the global install that is
+scoped by evidence (v4.32.0). Every `<lang>-rules` / `<lang>-patterns` skill is
+still symlinked, but `install` and `update` read the languages detected across
+the projects registered in `projects.json` and set `skillOverrides: off` in
+`~/.claude/settings.json` for the others, so their descriptions stop loading
+into every session. The entries the toolkit wrote are listed in `state.json`
+under `managed_skill_overrides`; only those are ever removed again (when a
+newly registered project brings the language back), a user's own override is
+left alone. With no registered project on disk nothing is disabled.
+`--language-skills all` restores everything and persists the choice
+(`language_skill_scope` in `state.json`); `ai-toolkit doctor` reports the
+resulting listing size and zero-use skills.
+
 Other editor targets are opt-in and only use documented file surfaces. Cursor
 rules stay project-local because Cursor's global user rules are managed through
 the settings UI, not a stable merge-safe file. Codex supports both project and
@@ -12836,7 +12853,7 @@ The `--profile` flag controls how much of each editor's native surface is activa
 |---------|-----------|----------|
 | `minimal` | Smallest editor surface. Copilot still receives its root instructions, native agents, and self-contained skills; Codex still receives instructions, agents, skills, and native safety hooks. | You want the smallest supported footprint. |
 | `standard` (default) | Claude Code + editor rule files. Includes Gemini and Antigravity hooks plus native Copilot instructions, agents, portable skills, and hooks. | Day-to-day installs. Most users. |
-| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
+| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks and the `git-team` common rule (feature branches, PR size, required approval, review SLA). | Tight team with zero tolerance for drift. A solo maintainer releasing straight to `main` wants `standard`, which keeps the solo-safe `git-workflow` core only. |
 | `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |
 
 Codex installs materialize the full skill catalog under `.agents/skills/`
@@ -13225,9 +13242,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.11.0"
+version: "1.12.0"
 created: "2026-03-27"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -13412,6 +13429,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Matcher | *(all)* |
 | Script | `~/.softspark/ai-toolkit/hooks/quality-check.sh` |
 | Fires | After every Claude response |
+| Mode | Background (`"async": true`). The linter (`npx tsc`, `ruff`) was the bulk of a 3.3 s median Stop chain; its output is advisory and reaches you when it finishes instead of holding the turn open |
 
 **Action:** Runs language-appropriate linter:
 - Python: `ruff check .`
@@ -13430,6 +13448,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Matcher | *(all)* |
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
+| Mode | Background (`"async": true`): writes a file and exits 0, nothing to wait for |
 
 **Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
@@ -13447,7 +13466,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
 | Fires | Before Claude is allowed to finish a response |
 
-**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session.
+**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session. Ruff runs only when the project configured it (`ruff.toml`, `.ruff.toml`, or a `[tool.ruff]` table in `pyproject.toml`); a `pyproject.toml` that only carries build or pytest/mypy metadata does not trigger `ruff check .` under whatever configuration the machine resolves (v4.32.0).
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -14045,9 +14064,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."
 ---
 
@@ -14097,7 +14116,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
 
@@ -14187,13 +14206,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
 ---
@@ -14202,6 +14224,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):
 
 ```
@@ -14209,10 +14243,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.
 
-Common rule files: `.claude/rules/ai-toolkit-coding-style.md`, ...
+Always-on: `.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
@@ -14249,7 +14286,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 |
@@ -14270,9 +14307,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.
@@ -17070,7 +17107,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."
 ---
 
@@ -17185,6 +17222,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/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.31.0",
+  "version": "4.32.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -141,7 +141,7 @@
       "default": true
     },
     "rules-common": {
-      "description": "Common coding rules (5 files)",
+      "description": "Common coding rules (6 files; git-team ships with the strict profile only)",
       "default": true
     },
     "rules-typescript": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.31.0",
+  "version": "4.32.0",
   "description": "AI coding toolkit: 109 skills, 44 agents, 14 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",
@@ -75,7 +75,10 @@
     "generate:all": "npm run generate:language-rules && npm run generate:claude-app && npm run generate:agents && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:opencode-skills && 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:gemini-agents && npm run generate:cline && npm run generate:cline-hooks && npm run generate:roo && npm run generate:roo-rules && npm run generate:aider && npm run generate:augment-rules && npm run generate:antigravity && npm run generate:llms && npm run generate:badges",
     "generate:badges": "python3 scripts/sync_badges.py",
     "surface": "python3 scripts/surface_manifest.py",
-    "surface:update": "python3 scripts/surface_manifest.py --update"
+    "surface:update": "python3 scripts/surface_manifest.py --update",
+    "test:py": "python3 -m pytest tests/python",
+    "lint:py": "ruff check scripts --select E,F --ignore E501,E402 --line-length 120 --extend-exclude app/skills/*/scripts,benchmarks",
+    "typecheck:py": "python3 -m mypy"
   },
   "files": [
     "bin/",

package/scripts/benchmark_ecosystem.py

@@ -11,7 +11,6 @@ Usage:
 from __future__ import annotations
 
 import json
-import os
 import sys
 import urllib.request
 from datetime import date, datetime, timezone

package/scripts/check_split.py

@@ -54,6 +54,8 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir as default_toolkit_dir
+from frontmatter import FrontmatterError
+from frontmatter import split_frontmatter as _split_frontmatter
 
 # Sections that carry prescriptive process and environment-specific traps.
 # They must load on every run, so they never move down into reference/.
@@ -75,16 +77,16 @@ NON_FILE_PREFIXES = ("#", "/", "mailto:", "tel:", "$")
 # ---------------------------------------------------------------------------
 
 def split_frontmatter(text: str) -> tuple[str, str]:
-    """Return (frontmatter_block, body). Frontmatter is '' when absent."""
-    lines = text.splitlines()
-    if not lines or lines[0].strip() != "---":
+    """Return (frontmatter_block, body). Frontmatter is '' when absent.
+
+    An unterminated block counts as body rather than being swallowed, so the
+    split gate still compares every byte of such a file.
+    """
+    try:
+        block, body = _split_frontmatter(text)
+    except FrontmatterError:
         return "", text
-    for idx in range(1, len(lines)):
-        if lines[idx].strip() == "---":
-            return "\n".join(lines[1:idx]), "\n".join(lines[idx + 1:])
-    # Unterminated frontmatter — treat the whole file as body rather than
-    # silently swallowing it.
-    return "", text
+    return block or "", body
 
 
 def description_of(frontmatter: str) -> str:

package/scripts/claude_app.py

@@ -27,6 +27,9 @@ import tempfile
 import zipfile
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from frontmatter import split_frontmatter  # noqa: E402
+
 
 TOOLKIT_DIR = Path(__file__).resolve().parent.parent
 APP_DIR = TOOLKIT_DIR / "app"
@@ -55,13 +58,8 @@ def _write_text(path: Path, content: str) -> None:
 
 
 def _strip_frontmatter(content: str) -> str:
-    lines = content.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return content.strip()
-    for index in range(1, len(lines)):
-        if lines[index].strip() == "---":
-            return "\n".join(lines[index + 1 :]).strip()
-    return content.strip()
+    """Body of a rule file with surrounding whitespace removed."""
+    return split_frontmatter(content)[1].strip()
 
 
 def render_plugin_hooks() -> str:

package/scripts/codex_skill_adapter.py

@@ -280,8 +280,10 @@ def _build_portable_skill_text(skill_file: Path, platform: str) -> str:
             if invocation_lines:
                 rendered_frontmatter += "\n" + "\n".join(invocation_lines)
     else:
-        frontmatter = _parse_frontmatter(match.group("frontmatter"))
-        rendered_frontmatter = _render_frontmatter(frontmatter)
+        # Native skills pass their frontmatter through untouched. The old
+        # line-by-line re-render flattened nested keys (`hooks:` blocks) into
+        # top-level `key: ` lines, which is not the document the author wrote.
+        rendered_frontmatter = match.group("frontmatter").strip("\n")
 
     return f"---\n{rendered_frontmatter}\n---\n{body.rstrip()}\n"
 
@@ -1112,16 +1114,6 @@ def _is_relative_to(path: Path, parent: Path) -> bool:
         return False
 
 
-def _parse_frontmatter(frontmatter_text: str) -> list[tuple[str, str]]:
-    entries: list[tuple[str, str]] = []
-    for line in frontmatter_text.splitlines():
-        if ":" not in line:
-            continue
-        key, value = line.split(":", 1)
-        entries.append((key.strip(), value.strip()))
-    return entries
-
-
 def _invocation_metadata_lines(frontmatter_text: str) -> list[str]:
     """Return exact canonical invocation lines, rejecting duplicate fields."""
     fields = ("user-invocable", "disable-model-invocation")