@softspark/ai-toolkit 4.31.0 → 4.32.1

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-09-01T07:58:08Z",
+  "last_run": "2026-09-04T08:36:45Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "83f1458d1a2060e9",
+      "docs_hash": "0e91c48495240138",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "273703f5030fd2ab",
+      "docs_hash": "4ba2582ffb78c262",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -108,7 +108,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "eea5867f24e1ed91",
+      "docs_hash": "10fe9c9fa45efb7a",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -174,10 +174,10 @@
         "userConfig": false,
         "workflows": true
       },
-      "version": "2.1.252 (Claude Code)"
+      "version": "2.1.260 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "13a2b874f0e0173c",
+      "docs_hash": "53d71ba66743ef56",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -195,6 +195,7 @@
         "Kanban",
         "Observability",
         "On this page",
+        "Resources",
         "SDK",
         "Security & Governance",
         "Team Management",
@@ -224,7 +225,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "f7df4a0b9f583a2e",
+      "docs_hash": "5444e9c3b6b4d284",
       "headings": [
         "API",
         "API Reference",
@@ -241,6 +242,7 @@
         "Build with Codex",
         "Capabilities",
         "Categories",
+        "ChatGPT Work",
         "ChatGPT web",
         "ChatKit",
         "Choose a model",
@@ -363,10 +365,10 @@
         "plugin marketplace": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.151.0"
+      "version": "codex-cli 0.153.2"
     },
     "cursor": {
-      "docs_hash": "8665fb50dce5f322",
+      "docs_hash": "328f32fe1afe3e7e",
       "headings": [
         "Agent",
         "CLI",
@@ -399,7 +401,7 @@
       }
     },
     "dsh": {
-      "docs_hash": "265ff3799848801e",
+      "docs_hash": "217350a932acc7fb",
       "headings": [],
       "markers": {
         "Agent Preset": false,
@@ -410,7 +412,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "02285d342536bdeb",
+      "docs_hash": "b78dde41b3161819",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -451,7 +453,7 @@
       "version": "0.57.0"
     },
     "github-copilot": {
-      "docs_hash": "fd80b4ec446cec3f",
+      "docs_hash": "606c4417d0acebed",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -488,7 +490,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "9fe532d247c3e361",
+      "docs_hash": "8cbf9aaffb6b57bf",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -515,7 +517,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "154885af5c7de582",
+      "docs_hash": "4dac69e305e60373",
       "headings": [
         "Add features",
         "Ask questions",
@@ -577,7 +579,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "4a3e8dc19dfdedd6",
+      "docs_hash": "121e915ebbd89355",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -311,6 +311,8 @@ function showHelp() {
   console.log('                  dsh (explicit project target; requires --local; excluded from "all")');
   console.log('                  Default with --local: auto-detect from existing project files');
   console.log('  --auto-detect   Detect project languages and install matching rule modules');
+  console.log('  --language-skills <s>  detected (default): turn off <lang>-rules/<lang>-patterns skills for languages');
+  console.log('                  no registered project uses (skillOverrides, reversible); all: keep every language skill on');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
   console.log('\nOptions for create:');
   console.log('  skill <name> --template=<type>  Scaffold skill (types: linter, reviewer, generator, workflow, knowledge)');

package/kb/procedures/sop-maintenance.md

@@ -3,9 +3,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."
 ---
 
@@ -229,7 +229,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
@@ -305,6 +307,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

package/kb/reference/cli-reference.md

@@ -4,7 +4,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."
 ---
 
@@ -19,6 +19,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 |
@@ -26,7 +27,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 |

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/plugin-pack-conventions.md

@@ -3,9 +3,9 @@ title: "Plugin Pack Conventions"
 category: reference
 service: ai-toolkit
 tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
-version: "1.3.0"
+version: "1.4.0"
 created: "2026-03-28"
-last_updated: "2026-08-31"
+last_updated: "2026-09-04"
 description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across supported editors."
 ---
 
@@ -167,7 +167,7 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 1. **Claude Code target**: strips plugin hook entries from `~/.claude/settings.json` and removes plugin-local rule sections from `~/.claude/CLAUDE.md`
 2. **Codex target**: strips only command handlers carrying the exact `AI_TOOLKIT_HOOK_OWNER=ai-toolkit-plugin-<pack>` marker from `$CODEX_HOME/hooks.json`, removes owned `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-*` assets, and removes the pack's marker-bounded sections from `$CODEX_HOME/AGENTS.md`
 3. **Cursor/Gemini rules**: removes only exact content recorded in `rule_ownership`; foreign or user-modified files/sections are preserved with a warning
-4. **Claude/shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack
+4. **Claude/shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack, and only when the file on disk is byte-, mode- and inode-identical to what install recorded in `shared_asset_ownership`; a file the user edited is preserved and named in a `WARN preserved changed plugin asset` line. Before v4.32.1 the Claude and Codex install paths never recorded that ownership, so removal preserved every hook and script as "untracked" and each pack left 4-5 files behind (found by the post-release SOP on v4.32.0)
 5. **Updates** `plugins.json` state per runtime
 6. **Leaves** core agents/skills untouched (they belong to the base install)
 7. **Leaves** plugin data intact (e.g. `memory.db` — use `clean` to prune)

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.**