@softspark/ai-toolkit 4.31.0 → 4.32.1

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.
@@ -15818,9 +15855,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."
 ---
 
@@ -15982,7 +16019,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)
@@ -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.1",
   "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.1",
   "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")

package/scripts/compile_slm.py

@@ -35,17 +35,16 @@ import re
 import sys
 import urllib.request
 import urllib.error
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from frontmatter import split_frontmatter
 from _common import (
-    toolkit_dir,
     app_dir,
     agents_dir,
     skills_dir,
     frontmatter_field,
-    frontmatter_block,
 )
 
 # ---------------------------------------------------------------------------
@@ -209,16 +208,6 @@ def _read_file_text(path: Path) -> str:
         return ""
 
 
-def _strip_frontmatter(text: str) -> str:
-    """Remove YAML frontmatter (--- delimited) from text."""
-    if not text.startswith("---"):
-        return text
-    end = text.find("---", 3)
-    if end == -1:
-        return text
-    return text[end + 3:].lstrip("\n")
-
-
 def _parse_persona_skills(persona_path: Path) -> list[str]:
     """Extract preferred skill names from a persona file."""
     text = _read_file_text(persona_path)
@@ -252,7 +241,7 @@ def parse_components(
     constitution_path = app_dir / "constitution.md"
     if constitution_path.is_file():
         text = _read_file_text(constitution_path)
-        body = _strip_frontmatter(text)
+        body = split_frontmatter(text)[1].lstrip("\n")
         components.append(Component(
             name="Constitution",
             type="constitution",
@@ -289,7 +278,7 @@ def parse_components(
     # --- Persona definition (score=0.90) ---
     if persona_path and persona_path.is_file():
         text = _read_file_text(persona_path)
-        body = _strip_frontmatter(text)
+        body = split_frontmatter(text)[1].lstrip("\n")
         components.append(Component(
             name=f"Persona: {persona}",
             type="persona",
@@ -310,7 +299,7 @@ def parse_components(
     if common_rules_dir.is_dir():
         for rule_file in sorted(common_rules_dir.glob("*.md")):
             text = _read_file_text(rule_file)
-            body = _strip_frontmatter(text)
+            body = split_frontmatter(text)[1].lstrip("\n")
             components.append(Component(
                 name=f"Rule: common/{rule_file.stem}",
                 type="rule",
@@ -332,7 +321,7 @@ def parse_components(
                 continue
             for rule_file in sorted(lang_dir.glob("*.md")):
                 text = _read_file_text(rule_file)
-                body = _strip_frontmatter(text)
+                body = split_frontmatter(text)[1].lstrip("\n")
                 components.append(Component(
                     name=f"Rule: {lang}/{rule_file.stem}",
                     type="rule",
@@ -355,7 +344,6 @@ def parse_components(
             skill_name = frontmatter_field(skill_file, "name")
             if not skill_name:
                 skill_name = skill_dir.name
-            description = frontmatter_field(skill_file, "description")
             user_invocable = frontmatter_field(skill_file, "user-invocable")
 
             # Skip non-user-invocable knowledge skills for SLM
@@ -364,7 +352,7 @@ def parse_components(
 
             # Build a compact skill summary (name + description)
             text = _read_file_text(skill_file)
-            body = _strip_frontmatter(text)
+            body = split_frontmatter(text)[1].lstrip("\n")
 
             # Persona relevance boost
             p_relevance = 0.7 if skill_name in persona_skills else 0.3
@@ -391,9 +379,8 @@ def parse_components(
             agent_name = frontmatter_field(agent_file, "name")
             if not agent_name:
                 agent_name = agent_file.stem
-            description = frontmatter_field(agent_file, "description")
             text = _read_file_text(agent_file)
-            body = _strip_frontmatter(text)
+            body = split_frontmatter(text)[1].lstrip("\n")
 
             # Persona relevance: match if agent skills overlap persona skills
             agent_skills_str = frontmatter_field(agent_file, "skills")
@@ -457,7 +444,7 @@ def compress_component(component: Component, level_config: dict[str, object]) ->
         return
 
     # Strip frontmatter (already done in parsing, but safety check)
-    text = _strip_frontmatter(text)
+    text = split_frontmatter(text)[1].lstrip("\n")
 
     # Strip examples
     strip_examples = level_config.get("strip_examples", True)
@@ -611,9 +598,6 @@ def pack_components(
 
     # Constitution budget guard
     if fixed_tokens > effective_budget:
-        constitution_tokens = sum(
-            c.tokens_compressed for c in fixed if c.type == "constitution"
-        )
         print(
             f"ERROR: Constitution + safety rules alone require {fixed_tokens} tokens, "
             f"exceeding budget of {effective_budget} (budget={budget} × {BUDGET_SAFETY_MARGIN}).\n"
@@ -995,7 +979,7 @@ def main(argv: list[str] | None = None) -> int:
     level = args.level or str(model_config["level"])
 
     # Parse languages
-    languages = [l.strip() for l in args.lang.split(",") if l.strip()] if args.lang else []
+    languages = [lang.strip() for lang in args.lang.split(",") if lang.strip()] if args.lang else []
 
     # Parse components
     components = parse_components(persona=args.persona, languages=languages)