@softspark/ai-toolkit 4.30.3 → 4.32.0

package/app/skills/edit-discipline/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: edit-discipline
+description: "Change files with the edit and write tools, never by rewriting them through bash (sed, awk, tee, heredoc, redirection), and show `git diff` before reporting a file-changing task as done. Triggers: edit, write, modify, refactor, patch, fix, diff, review changes."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Edit Discipline
+
+This rule comes from `app/rules/edit-discipline.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Edit Discipline & Reviewable Changes
+
+## Edit files with the editing tools, not the shell
+
+Use the `edit` and `write` tools to change a file. Do not rewrite tracked files
+through `bash` with `sed`, `awk`, `tee`, a heredoc, or `>` redirection.
+
+This is not a style preference. A shell rewrite is opaque to the host: the
+session records a command, not a change. An `edit` call records which file
+changed and how, so the interface can render it, a reviewer can read it, and a
+later turn can cite it. A `sed` line records none of that, and the only way to
+find out what happened is to read the file again.
+
+The shell remains correct for what it is for: running builds, tests, linters,
+git, package managers, and generators that own their own output.
+
+## Show the change before calling the work done
+
+Before reporting a file-changing task as finished, show what changed:
+
+```bash
+git diff -- <paths>          # tracked files
+git status --short           # what is new or removed
+```
+
+Paste the diff into the reply, or state precisely why it is too large and
+summarise it by file with the counts. A task that reports success without
+showing the change asks the reader to take the result on trust, and the reader
+is the one who has to decide whether to commit it.
+
+For an untracked file, show the content you wrote, not a description of it.
+
+## Why both halves matter together
+
+Editing through the tools makes a change *recordable*; showing the diff makes it
+*reviewed*. Either alone leaves the person deciding whether to ship blind to
+something they are accountable for.

package/app/skills/git-conventions/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: git-conventions
+description: "Conventional Commits only (feat, fix, docs, refactor, test, chore); no AI co-authorship trailer and no AI signature in a commit message. Triggers: commit, git, message, changelog, release, pull request."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Git Conventions
+
+This rule comes from `app/rules/git-conventions.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Git Conventions
+
+- Do NOT add `Co-Authored-By: Claude` or any AI co-authorship to commits
+- Do NOT add Claude signatures or attribution to commit messages
+- Conventional commits format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`

package/app/skills/output-mode/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: output-mode
+description: "Answer concisely: lead with the result, no preamble, tables over prose, no trailing restatement of a diff the reader can already see. Triggers: response style, verbosity, summary, explanation, report."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Output Mode
+
+This rule comes from `app/rules/output-mode.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode for this project is **concise**. The `brand-voice` skill (when present in ai-toolkit) auto-loads its `concise` rules; assistants without that skill should still apply the directives below.
+
+## Concise Mode Directives
+
+- **No preamble.** Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
+- **Lead with the result.** Conclusion or output first; explanation only if asked or non-obvious.
+- **Max 3 sentences per closed question.** Yes/no, single-fact, or "where is X" answers stay under three sentences.
+- **Tables and lists over prose** when comparing options, listing steps, or showing values.
+- **No trailing summaries.** If the diff or output already shows what changed, do not restate it.
+- **Drop filler adjectives.** No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+- **Cite file paths as `path:line`** instead of paragraphs describing where things live.
+- **Reserve longer prose** for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.
+
+## When to escalate to verbose
+
+- User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
+- Reporting a non-obvious failure mode where missing context would mislead.
+- Architecture / RFC / ADR / trade-off documents — those have their own structure.
+
+## How to override
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for even tighter)
+- Per-project: change this rule's `output-mode:` value in the project's `CLAUDE.md`
+- Permanent removal: re-run `ai-toolkit install --skip rules` or strip the `<!-- TOOLKIT:output-mode -->` block manually

package/app/skills/quality-gates/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: quality-gates
+description: "Plan before work over an hour, and hold the gates: ruff clean, mypy --strict clean, pytest coverage above 70 percent, no secrets in code. Triggers: quality, lint, mypy, pytest, coverage, gate, definition of done."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Quality Gates
+
+This rule comes from `app/rules/quality-gates.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Quality Gates & Mandatory Practices
+
+## MANDATORY PRACTICES
+1.  **Plan First:** Tasks >1h require Plan, Success Criteria, and Pre-Mortem.
+2.  **Quality Gates:**
+    *   `ruff check .` (0 errors)
+    *   `mypy --strict src/` (0 errors)
+    *   `pytest --cov=src` (>70% coverage)
+    *   **Type Safety:** 100% public APIs, >60% internal.
+3.  **Security:** No secrets in code, sanitization, auth z/n.

package/app/skills/review/SKILL.md

@@ -146,6 +146,16 @@ After all reviewers complete:
 - [ ] No memory leaks
 - [ ] Optimized loops
 
+### Frontend & UI Craft (Anti-Slop Gates)
+- [ ] No gradient text headlines (`background-clip: text`) or saturated purple/blue hero washes
+- [ ] No cliché 3-column card grids with icon-above-title tiles, card-in-card nesting, or side-stripe cards
+- [ ] Interactive elements implement all 8 states (default, hover, focus-visible, active, disabled, loading, error, success)
+- [ ] Input fields maintain constant 1px `border-width` across all states (zero layout shift) and reserve 2px transparent outline
+- [ ] Mobile responsive: `overflow-x: clip` on `html` and `body`; no buttons/links wrapping to 2 lines; image grid tracks use `minmax(0, 1fr)`
+- [ ] Typography: headings are roman (`font-style: normal`, no italic emphasis in headers); max 3 font families (2+1 rule)
+- [ ] Content honesty: no invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
+- [ ] No fake re-drawn browser/OS chrome; no emoji used as load-bearing icons
+
 ### Testing
 - [ ] Tests for new code
 - [ ] Edge cases covered

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/{ecosystem-sync-sop.md → sop-ecosystem-sync.md}

@@ -253,5 +253,5 @@ jobs:
 
 - [Supported Tools Registry](../reference/supported-tools-registry.md) — human-readable per-tool breakdown
 - [MCP Editor Compatibility](../reference/mcp-editor-compatibility.md) — MCP-specific adapter table
-- [Maintenance SOP](maintenance-sop.md) — general toolkit upkeep
-- [Release Preparation SOP](release-preparation-sop.md) — run the doctor before tagging
+- [Maintenance SOP](sop-maintenance.md) — general toolkit upkeep
+- [Release Preparation SOP](sop-release.md) — run the doctor before tagging

package/kb/procedures/{maintenance-sop.md → 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/procedures/{post-release-testing-sop.md → sop-post-release-testing.md}

@@ -16,7 +16,7 @@ actually install, from npm, rather than the working tree.
 
 Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
 ai-toolkit equivalent. It complements
-[Release Verification](release-verification-sop.md), which checks the toolkit
+[Release Verification](sop-release-verification.md), which checks the toolkit
 from the maintainer's own installed copy. The difference that matters: this one
 never writes to the maintainer's `~/.claude` or `~/.softspark`.
 
@@ -310,6 +310,6 @@ print(f'removed {sb} ({n} files)')
 
 ## Related
 
-- [Release Preparation](release-preparation-sop.md) — run before tagging
-- [Release Verification](release-verification-sop.md) — the maintainer-install checks
+- [Release Preparation](sop-release.md) — run before tagging
+- [Release Verification](sop-release-verification.md) — the maintainer-install checks
 - [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run

package/kb/procedures/sop-pre-commit.md

@@ -0,0 +1,96 @@
+---
+title: "SOP: Pre-Commit Gate"
+category: procedures
+service: ai-toolkit
+tags: [pre-commit, quality-gate, shellcheck, bats, validation, secrets]
+version: "1.0.0"
+created: "2026-09-02"
+last_updated: "2026-09-02"
+description: "The local gate to run before every commit to ai-toolkit: staged-file and secret scan, ShellCheck, Python syntax, toolkit validation, and the Bats suite. Runs the same checks CI runs, so main does not go red after a push."
+---
+
+# SOP: Pre-Commit Gate
+
+## Why this exists
+
+CI runs on `main` and on pull requests, but it runs *after* the push. Every
+check below already exists in `.github/workflows/ci.yml`; running them locally
+first is what keeps `main` green and keeps a release from becoming a debug
+session. The v4.5.1 postmortem in `sop-release.md` is the case
+where a hook lint failure published while reddening `main` CI.
+
+This gate is not a substitute for `sop-release.md`. That SOP gates
+a *tag*; this one gates a *commit*.
+
+## Prerequisites
+
+`shellcheck`, `python3` and `bats` must be on `PATH`. The suite is the one
+check that silently does nothing when its runner is absent, so install it
+before relying on this gate:
+
+```bash
+brew install bats-core shellcheck    # macOS
+sudo apt-get install -y bats shellcheck   # Debian / Ubuntu
+```
+
+## The gate
+
+Run all five from the repository root. Each mirrors a CI job.
+
+```bash
+# 1. Staged files: secrets, large blobs, commit-type suggestion
+python3 app/skills/commit/scripts/pre-commit-check.py
+
+# 2. ShellCheck hooks -- the CI job that has published while red before
+shellcheck --severity=warning app/hooks/*.sh app/plugins/*/hooks/*.sh
+
+# 3. Python syntax across every script the toolkit ships
+python3 -m py_compile scripts/*.py app/skills/*/scripts/*.py
+
+# 4. Toolkit integrity: agents, skills, registry drift, content quality
+npm run validate
+
+# 5. The suite. Run it ONCE -- see the single-run discipline below
+npm test
+```
+
+A non-zero exit from any of them is a stop, not a warning to note and push past.
+
+## Single-run discipline
+
+`npm test` runs the Bats suite with `--jobs 4`. Running it repeatedly to see
+whether a failure is "flaky" hides real ordering bugs and wastes minutes. Run
+it once. If it fails, read the failure and fix the cause; if the same test
+passes on a re-run without a code change, that instability is itself the bug
+and belongs in an issue, not in a retry.
+
+## What this gate does not cover
+
+- **Cross-platform.** The suite here runs on your machine only. Both
+  `ubuntu-latest` and `macos-latest` must be green before a tag; that gate
+  lives in `sop-release.md`, Phase 7, and is bound to the exact
+  release commit.
+- **Required files.** The `required-files` CI job checks that every file the
+  module template mandates is present and that the version is in sync across
+  all four manifests. It is cheap and runs on every push.
+- **Provenance and SARIF.** Release-time concerns; see
+  `sop-release.md`.
+
+## Commit message
+
+Conventional Commits, and no AI co-authorship trailer:
+
+```
+feat(scope): summary in the imperative
+fix(scope): summary in the imperative
+docs|refactor|test|chore(scope): ...
+```
+
+`pre-commit-check.py` suggests a type from the staged paths. It is a
+suggestion; the scope and the summary are yours.
+
+## Related
+
+- `sop-release.md` -- the pre-tag gate, including cross-platform CI
+- `sop-post-release-testing.md` -- what to verify after a release ships
+- `sop-release-verification.md` -- end-to-end smoke test of an installed build

package/kb/procedures/{release-preparation-sop.md → sop-release.md}

@@ -13,7 +13,7 @@ description: "Step-by-step checklist for preparing a new ai-toolkit release —
 
 Complete checklist for preparing a new `@softspark/ai-toolkit` release.
 Run this **before** tagging. After tagging and publishing, run the
-[Release Verification SOP](release-verification-sop.md) to smoke-test.
+[Release Verification SOP](sop-release-verification.md) to smoke-test.
 
 **Pipeline:**
 ```
@@ -32,10 +32,10 @@ git tag → CI publish → Release Verification SOP
 
 ```bash
 # 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
-#    Full procedure: kb/procedures/ecosystem-sync-sop.md
+#    Full procedure: kb/procedures/sop-ecosystem-sync.md
 python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
 cat /tmp/eco-report.txt
-# If drift detected: stop here, follow ecosystem-sync-sop.md Phase 2-4 to
+# If drift detected: stop here, follow sop-ecosystem-sync.md Phase 2-4 to
 # classify each drift (A-F), update generators as needed, refresh snapshot,
 # THEN resume this SOP.
 python3 scripts/ecosystem_doctor.py --update    # after all drift resolved
@@ -126,7 +126,7 @@ Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.
 
 ### 0.2 Act on drift
 
-For each drifting tool, follow [ecosystem-sync-sop.md](ecosystem-sync-sop.md) Phase 2-4:
+For each drifting tool, follow [sop-ecosystem-sync.md](sop-ecosystem-sync.md) Phase 2-4:
 
 | Drift class | Release impact |
 |-------------|----------------|
@@ -195,7 +195,7 @@ The canonical version lives in `package.json`. These files **must** match:
 
 | File | Field | When to update |
 |------|-------|---------------|
-| `kb/procedures/maintenance-sop.md` | frontmatter `version:` | If SOP content changed |
+| `kb/procedures/sop-maintenance.md` | frontmatter `version:` | If SOP content changed |
 | `kb/reference/skills-catalog.md` | frontmatter `version:` | If skills added/removed |
 | `kb/reference/agents-catalog.md` | frontmatter `version:` | If agents added/removed |
 | `kb/reference/hooks-catalog.md` | frontmatter `version:` | If hooks changed |
@@ -591,7 +591,7 @@ This triggers `.github/workflows/publish.yml` which:
 
 **Provenance is non-negotiable.** If `id-token: write` permission or the `--provenance` flag is missing from `publish.yml`, fix it BEFORE tagging — an unsigned release is a regression against the v2.8.0 standard.
 
-**After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
+**After CI completes:** Run the [Release Verification SOP](sop-release-verification.md)
 to smoke-test the published package AND verify the provenance attestation landed on npm.
 
 ---

package/kb/reference/architecture-overview.md

@@ -228,7 +228,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 46 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 51 |
 
 ## Multi-Agent Execution
 

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/copilot-compatibility.md

@@ -159,7 +159,7 @@ running the generators directly:
 
 - `scripts/generate_copilot.py` / `generate_copilot_hooks.py` contract tests
   (`tests/test_copilot.bats`, `tests/test_copilot_hooks.bats`).
-- Release layout check in `kb/procedures/release-verification-sop.md` asserts the
+- Release layout check in `kb/procedures/sop-release-verification.md` asserts the
   `.github/{agents,skills,instructions,prompts,hooks}` surfaces.
 - `validate.py --strict` + `audit_skills.py --ci` in CI.
 

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