@softspark/ai-toolkit 4.31.0 → 4.32.0

package/scripts/generate_opencode_skills.py

@@ -21,7 +21,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from codex_skill_adapter import build_opencode_skill_text
 from emission import skills_dir
-from frontmatter import frontmatter_field
+from frontmatter import frontmatter_block, frontmatter_field, frontmatter_sections
 from secure_fs import SecureDestination, SecureTransaction, nearest_existing_root
 
 
@@ -43,24 +43,6 @@ class PreparedSkill:
         return {Path("SKILL.md"), Path(MANAGED_MANIFEST), *self.files}
 
 
-def _frontmatter_sections(skill_file: Path) -> dict[str, list[str]]:
-    text = skill_file.read_text(encoding="utf-8")
-    if not text.startswith("---\n"):
-        return {}
-    parts = text.split("---", 2)
-    if len(parts) != 3:
-        return {}
-    sections: dict[str, list[str]] = {}
-    current: str | None = None
-    for line in parts[1].strip("\n").splitlines():
-        if line and not line[0].isspace() and ":" in line:
-            current = line.split(":", 1)[0].strip()
-            sections[current] = [line]
-        elif current is not None:
-            sections[current].append(line)
-    return sections
-
-
 def _portable_body(skill_file: Path) -> str:
     rendered = build_opencode_skill_text(skill_file)
     if not rendered.startswith("---\n"):
@@ -72,7 +54,7 @@ def _portable_body(skill_file: Path) -> str:
 def _render_skill(skill_file: Path) -> str:
     name = frontmatter_field(skill_file, "name")
     description = frontmatter_field(skill_file, "description")
-    sections = _frontmatter_sections(skill_file)
+    sections = frontmatter_sections(frontmatter_block(skill_file))
     lines = [
         "---",
         f"name: {name}",

package/scripts/generate_windsurf_rules.py

@@ -50,7 +50,6 @@ from dir_rules_shared import (
     build_language_rules,
     build_registered_rules,
     cleanup_stale,
-    rule_testing,
     write_rules,
 )
 

package/scripts/generator_base.py

@@ -32,7 +32,6 @@ from __future__ import annotations
 
 import os
 import sys
-from pathlib import Path
 
 from paths import RULES_DIR
 

package/scripts/inject_hook_cli.py

@@ -221,8 +221,17 @@ def _entry_source(entry: dict) -> str | None:
     return None
 
 
+# Handler fields that change *how* a command hook is scheduled, not *what* it
+# runs. A legacy untagged entry that differs only in these is the same hook,
+# otherwise adding `async` or `timeout` to app/hooks.json would leave every
+# existing install running the old copy and the new copy side by side.
+_SCHEDULING_FIELDS = frozenset({
+    "async", "asyncRewake", "timeout", "statusMessage", "shell", "once", "if",
+})
+
+
 def _entry_signature(entry: dict) -> tuple:
-    """Return behavior-defining hook fields without source tags."""
+    """Return behavior-defining hook fields without source or scheduling tags."""
     handlers = []
     for hook in entry.get("hooks", []):
         if not isinstance(hook, dict):
@@ -230,7 +239,11 @@ def _entry_signature(entry: dict) -> tuple:
             continue
         handlers.append(
             tuple(
-                sorted((key, value) for key, value in hook.items() if key != "_source")
+                sorted(
+                    (key, value)
+                    for key, value in hook.items()
+                    if key != "_source" and key not in _SCHEDULING_FIELDS
+                )
             )
         )
     return (entry.get("matcher", ""), tuple(handlers))

package/scripts/inject_mcp_cli.py

@@ -55,7 +55,6 @@ from __future__ import annotations
 
 import copy
 import json
-import os
 import re
 import sys
 import urllib.parse
@@ -163,7 +162,7 @@ def _check_collisions(
 
     if not force:
         print(
-            f"Error: server name collision(s) in .mcp.json (re-run with --force):",
+            "Error: server name collision(s) in .mcp.json (re-run with --force):",
             file=sys.stderr,
         )
         for name, other_source in collisions:

package/scripts/install.py

@@ -41,6 +41,9 @@ Options:
   --persona <p>           backend-lead|frontend-lead|devops-eng|junior-dev
   --modules <list>        Install specific modules (comma-separated)
   --auto-detect           Detect project languages and install matching rules
+  --language-skills <s>   detected (default): turn off <lang>-rules/<lang>-patterns
+                          skills for languages no registered project uses;
+                          all: keep every language skill on (persisted)
   --status                Show installed modules and exit
 """
 from __future__ import annotations
@@ -50,7 +53,7 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _common import toolkit_dir, app_dir, inject_rule
+from _common import toolkit_dir, app_dir, inject_rule, should_install
 from emission import agent_count as count_agents, skill_count as count_skills
 
 # Step modules
@@ -223,6 +226,7 @@ def parse_args(argv: list[str]) -> dict:
         "refresh_base": False,
         "skip_register": False,
         "codex_skills": False,
+        "language_skills": "",
     }
     i = 0
     while i < len(argv):
@@ -283,6 +287,11 @@ def parse_args(argv: list[str]) -> dict:
             cfg["skip_register"] = True
         elif arg == "--codex-skills":
             cfg["codex_skills"] = True
+        elif arg.startswith("--language-skills="):
+            cfg["language_skills"] = arg.split("=", 1)[1]
+        elif arg == "--language-skills":
+            i += 1
+            cfg["language_skills"] = argv[i] if i < len(argv) else ""
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -335,6 +344,15 @@ def validate_args(cfg: dict) -> None:
             if c and c not in VALID_COMPONENTS:
                 errors.append(f"Unknown component in --skip: '{c}' (valid: {', '.join(sorted(VALID_COMPONENTS))})")
 
+    # Validate --language-skills
+    if cfg["language_skills"]:
+        from install_steps.skill_scope import VALID_SCOPES
+        if cfg["language_skills"] not in VALID_SCOPES:
+            errors.append(
+                f"Unknown --language-skills value: '{cfg['language_skills']}' "
+                f"(valid: {', '.join(VALID_SCOPES)})"
+            )
+
     # Validate --editors
     if cfg["editors"] and cfg["editors"] != "all":
         for e in cfg["editors"].split(","):
@@ -848,6 +866,19 @@ def main() -> None:
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")
 
+    # Language knowledge skills are symlinked for every language, but their
+    # descriptions load into every session. Scope them to the languages the
+    # registered projects actually use (after registration, so a new project's
+    # language re-enables its skills in the same run). Read-only in dry-run.
+    if should_install("skills", only, skip):
+        from install_steps.skill_scope import reconcile_language_skill_overrides, resolve_scope
+        reconcile_language_skill_overrides(
+            toolkit_dir,
+            target_dir / ".claude" / "settings.json",
+            scope=resolve_scope(cfg["language_skills"]),
+            dry_run=dry_run,
+        )
+
     # A global install is authoritative for Claude Code, so an uploaded Claude
     # app plugin must not feed it in parallel. Uploading the ZIP re-enables the
     # plugin every time, so this is re-asserted on every install/update rather

package/scripts/install_git_hooks.py

@@ -11,7 +11,6 @@ Usage: python3 install_git_hooks.py [target-dir]
 """
 from __future__ import annotations
 
-import os
 import sys
 from pathlib import Path
 

package/scripts/install_steps/ai_tools.py

@@ -12,6 +12,7 @@ import subprocess
 from pathlib import Path
 
 from _common import app_dir, inject_section, toolkit_dir
+from frontmatter import FrontmatterError, parse_frontmatter, split_frontmatter
 from codex_skill_adapter import (
     cleanup_codex_skills,
     managed_skill_surface_transaction,
@@ -965,7 +966,7 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         _apply_extends_config(cwd, merged_config)
 
     # Inject language-specific rules into project CLAUDE.md
-    _inject_language_rules(cwd, language_modules)
+    _inject_language_rules(cwd, language_modules, profile=profile)
 
     # Install editor configs only for resolved editors
     _create_local_ai_tool_configs(cwd, rules_dir, resolved_editors,
@@ -1061,17 +1062,21 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
         print("  Saved: .softspark-toolkit-extends.json (resolution metadata)")
 
 
-def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
+def _inject_language_rules(cwd: Path, language_modules: list[str] | None,
+                           profile: str = "standard") -> None:
     """Install Claude language-rule entrypoints for a project.
 
     Per-language rules (``app/rules/<lang>/``) are NOT injected here -- they
     ship as ``<lang>-rules`` knowledge skills under ``app/skills/`` and load
     contextually via the Agent Skills progressive-disclosure mechanism.
 
-    Common rules are written as Claude Code path-scoped rules under
-    ``.claude/rules/``. Current Claude Code guidance targets under 200 lines
-    per ``CLAUDE.md`` file; path-scoped rules keep startup context smaller
-    while still loading the rule bodies when project files are opened.
+    Common rules are written as Claude Code rules under ``.claude/rules/``.
+    Each source rule's ``paths`` frontmatter decides whether it is always-on
+    (``**/*``: coding-style, git-workflow, security) or path-scoped (testing,
+    performance load only for matching files). Current Claude Code guidance
+    targets under 200 lines per ``CLAUDE.md`` file; keeping rule bodies out
+    of it and scoping the ones that are file-type specific keeps startup
+    context smaller.
     """
     if not language_modules:
         return
@@ -1081,7 +1086,7 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     if not common_dir.is_dir():
         return
 
-    rule_files = _sync_claude_common_rules(cwd, common_dir)
+    rule_files = _sync_claude_common_rules(cwd, common_dir, profile)
 
     # Detect requested per-language modules so we can name the linked skills
     # in the marker block. The modules themselves are not inlined.
@@ -1095,12 +1100,18 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     lines: list[str] = ["# Language Rules", ""]
     lines.append(
         "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."
     )
-    if rule_files:
+    always_on = [p for p, on in rule_files if on]
+    scoped = [p for p, on in rule_files if not on]
+    if always_on:
         lines.append("")
-        lines.append("Common rule files: " + ", ".join(f"`{p}`" for p in rule_files) + ".")
+        lines.append("Always-on: " + ", ".join(f"`{p}`" for p in always_on) + ".")
+    if scoped:
+        lines.append("")
+        lines.append("Path-scoped: " + ", ".join(f"`{p}`" for p in scoped) + ".")
     lines.append("")
     lines.append(
         "Language-specific rules live in `<lang>-rules` knowledge skills "
@@ -1132,39 +1143,68 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
         tmp_path.unlink(missing_ok=True)
 
 
-def _strip_rule_frontmatter(text: str) -> str:
-    if text.startswith("---"):
-        end = text.find("\n---", 3)
-        if end != -1:
-            return text[end + 4:].lstrip("\n")
-    return text
+ALWAYS_ON_RULE_PATHS = ["**/*"]
+
 
+def _rule_source(src: Path) -> tuple[str, list[str], list[str]]:
+    """Return ``(body, paths, profiles)`` for one ``app/rules/common`` file.
 
-def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
+    ``paths`` defaults to always-on (``**/*``); an empty ``profiles`` means
+    the rule ships in every profile. Shipped rules pass ``validate.py`` before
+    release, so a parse failure here is a broken install, not a soft case.
+    """
+    text = src.read_text(encoding="utf-8")
+    try:
+        _, body = split_frontmatter(text)
+        meta = parse_frontmatter(text)
+    except FrontmatterError as error:
+        raise RuntimeError(f"invalid frontmatter in {src}: {error}") from error
+    paths = meta.get("paths")
+    profiles = meta.get("profiles")
+    return (
+        body,
+        [str(p) for p in paths] if isinstance(paths, list) and paths else list(ALWAYS_ON_RULE_PATHS),
+        [str(p) for p in profiles] if isinstance(profiles, list) else [],
+    )
+
+
+def _sync_claude_common_rules(cwd: Path, common_dir: Path,
+                              profile: str = "standard") -> list[tuple[str, bool]]:
     """Write common ai-toolkit rules as Claude Code path-scoped rules.
 
+    Each source rule's ``paths`` frontmatter decides its scope; rules
+    without one are always-on. A ``profiles`` frontmatter restricts the rule
+    to those install profiles (``git-team`` ships with ``strict`` only); a
+    managed file whose rule no longer applies is removed, so switching profile
+    on a rerun converges. Returns ``(relative path, always_on)`` pairs.
+
     Only ``ai-toolkit-*.md`` files are managed. User-authored files in
     ``.claude/rules/`` are preserved.
     """
     rules_dir = cwd / ".claude" / "rules"
     rules_dir.mkdir(parents=True, exist_ok=True)
 
-    source_files = sorted(common_dir.glob("*.md"))
-    expected = {f"ai-toolkit-{src.stem}.md" for src in source_files}
+    source_files: list[tuple[Path, str, list[str]]] = []
+    for src in sorted(common_dir.glob("*.md")):
+        body, paths, gate = _rule_source(src)
+        if gate and profile not in gate:
+            continue
+        source_files.append((src, body, paths))
+    expected = {f"ai-toolkit-{src.stem}.md" for src, _, _ in source_files}
     for stale in sorted(rules_dir.glob("ai-toolkit-*.md")):
         if stale.name not in expected:
             stale.unlink()
 
-    written: list[str] = []
-    for src in source_files:
-        body = _strip_rule_frontmatter(src.read_text(encoding="utf-8")).rstrip()
+    written: list[tuple[str, bool]] = []
+    for src, body, paths in source_files:
+        body = body.lstrip("\n").rstrip()
         rel = Path(".claude") / "rules" / f"ai-toolkit-{src.stem}.md"
         target = cwd / rel
         target.write_text(
             "\n".join([
                 "---",
                 "paths:",
-                '  - "**/*"',
+                *[f'  - "{p}"' for p in paths],
                 "---",
                 "",
                 body,
@@ -1172,7 +1212,7 @@ def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
             ]),
             encoding="utf-8",
         )
-        written.append(rel.as_posix())
+        written.append((rel.as_posix(), paths == ALWAYS_ON_RULE_PATHS))
 
     return written
 

package/scripts/install_steps/markers.py

@@ -214,10 +214,10 @@ def _refresh_url_rules(rules_dir: Path) -> None:
         except Exception as exc:
             if rule_file.is_file():
                 print(f"  Warning: could not refresh '{rule_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{rule_name}' from {url}: {exc}")
-                print(f"           No cached version — rule will be skipped.")
+                print("           No cached version — rule will be skipped.")
 
 
 def refresh_url_hooks(target_dir: str | None = None) -> None:
@@ -250,10 +250,10 @@ def refresh_url_hooks(target_dir: str | None = None) -> None:
         except Exception as exc:
             if cached_file.is_file():
                 print(f"  Warning: could not refresh '{hook_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{hook_name}' from {url}: {exc}")
-                print(f"           No cached version — hook will be skipped.")
+                print("           No cached version — hook will be skipped.")
                 continue
 
         # Re-inject from cached file
@@ -291,10 +291,10 @@ def refresh_url_mcp(target_dir: str | None = None) -> None:
         except Exception as exc:
             if cached_file.is_file():
                 print(f"  Warning: could not refresh '{template_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{template_name}' from {url}: {exc}")
-                print(f"           No cached version — template will be skipped.")
+                print("           No cached version — template will be skipped.")
                 continue
 
         if cached_file.is_file():

package/scripts/install_steps/skill_scope.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
+"""Scope language knowledge skills to the stacks a user actually works in.
+
+The global install symlinks every ``<lang>-rules`` / ``<lang>-patterns``
+skill into ``~/.claude/skills``. Each one's description then sits in the
+model-visible skill listing of every session, whether or not the user has a
+single project in that language. This step reads the languages detected
+across the registered projects (``projects.json``) and turns the others off
+through Claude Code's ``skillOverrides`` setting.
+
+Rules of engagement:
+
+* Evidence first. With no registered project on disk there is nothing to
+  judge, so nothing is disabled.
+* Only entries this step wrote are ever removed again. They are tracked in
+  ``state.json`` under ``managed_skill_overrides``; a user's own override is
+  left alone even when it names a language skill.
+* ``--language-skills all`` restores every managed entry and persists the
+  choice so later ``install`` / ``update`` runs do not prune again.
+* Reversible by hand: delete the key from ``~/.claude/settings.json``.
+
+Stdlib-only.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from install_steps.detect_language import detect_languages
+from install_steps.install_state import load_state, save_state
+from install_steps.project_registry import load_registry
+
+LANGUAGE_SKILL_SUFFIXES = ("rules", "patterns")
+SCOPE_ALL = "all"
+SCOPE_DETECTED = "detected"
+VALID_SCOPES = (SCOPE_ALL, SCOPE_DETECTED)
+STATE_SCOPE_KEY = "language_skill_scope"
+STATE_MANAGED_KEY = "managed_skill_overrides"
+
+
+def language_skill_names(toolkit_dir: Path) -> dict[str, str]:
+    """Map each shipped language knowledge skill to its language.
+
+    A skill counts as a language skill when it is named ``<lang>-rules`` or
+    ``<lang>-patterns`` and ``app/rules/<lang>/`` exists. ``flutter-patterns``
+    therefore does not (no ``app/rules/flutter``), which is deliberate:
+    only skills generated from a language rule set are scoped.
+    """
+    rules_root = toolkit_dir / "app" / "rules"
+    skills_root = toolkit_dir / "app" / "skills"
+    if not rules_root.is_dir() or not skills_root.is_dir():
+        return {}
+    languages = {p.name for p in rules_root.iterdir() if p.is_dir() and p.name != "common"}
+    mapping: dict[str, str] = {}
+    for skill_dir in sorted(skills_root.iterdir()):
+        if not skill_dir.is_dir() or "-" not in skill_dir.name:
+            continue
+        lang, _, suffix = skill_dir.name.rpartition("-")
+        if suffix in LANGUAGE_SKILL_SUFFIXES and lang in languages:
+            mapping[skill_dir.name] = lang
+    return mapping
+
+
+def detected_languages_from_registry(toolkit_dir: Path) -> set[str] | None:
+    """Union of languages detected across registered projects that still exist.
+
+    Returns ``None`` when no registered project directory exists, which
+    callers must read as "no evidence", not "no languages".
+    """
+    found: set[str] = set()
+    seen_project = False
+    for entry in load_registry():
+        path = entry.get("path")
+        if not isinstance(path, str):
+            continue
+        project_dir = Path(path)
+        if not project_dir.is_dir():
+            continue
+        seen_project = True
+        for module in detect_languages(project_dir, toolkit_dir):
+            if module.startswith("rules-") and module != "rules-common":
+                found.add(module[len("rules-"):])
+    return found if seen_project else None
+
+
+def _load_settings(settings_path: Path) -> dict[str, Any]:
+    if not settings_path.is_file():
+        return {}
+    try:
+        with open(settings_path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _save_settings(settings_path: Path, data: dict[str, Any]) -> None:
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+        f.write("\n")
+
+
+def resolve_scope(requested: str, state: dict[str, Any] | None = None) -> str:
+    """Pick the effective scope: explicit flag wins, else the persisted choice."""
+    if requested in VALID_SCOPES:
+        return requested
+    persisted = (state if state is not None else load_state()).get(STATE_SCOPE_KEY)
+    return persisted if persisted in VALID_SCOPES else SCOPE_DETECTED
+
+
+def reconcile_language_skill_overrides(
+    toolkit_dir: Path,
+    settings_path: Path,
+    *,
+    scope: str,
+    dry_run: bool = False,
+) -> tuple[list[str], list[str]]:
+    """Bring ``skillOverrides`` in line with the detected language set.
+
+    Returns ``(disabled, restored)`` skill names. Prints one line per
+    outcome in the install's ``  Verb: detail`` style.
+    """
+    state = load_state()
+    managed: set[str] = {
+        name for name in state.get(STATE_MANAGED_KEY, []) if isinstance(name, str)
+    }
+    skills = language_skill_names(toolkit_dir)
+    settings = _load_settings(settings_path)
+    overrides = settings.get("skillOverrides")
+    if not isinstance(overrides, dict):
+        overrides = {}
+
+    disabled: list[str] = []
+    restored: list[str] = []
+
+    if scope == SCOPE_ALL:
+        languages: set[str] | None = None
+    else:
+        languages = detected_languages_from_registry(toolkit_dir)
+
+    for name, lang in sorted(skills.items()):
+        keep_on = languages is None or lang in languages
+        if keep_on:
+            if name in managed and overrides.get(name) == "off":
+                overrides.pop(name)
+                restored.append(name)
+            managed.discard(name)
+            continue
+        if name in overrides:
+            # The user (or an earlier run) already has an opinion; a run never
+            # adopts an entry it did not write.
+            continue
+        overrides[name] = "off"
+        managed.add(name)
+        disabled.append(name)
+
+    if dry_run:
+        if languages is None and scope != SCOPE_ALL:
+            print("  Would skip: language skill scoping (no registered project on disk)")
+        for name in disabled:
+            print(f"  Would disable: skill {name} (skillOverrides)")
+        for name in restored:
+            print(f"  Would restore: skill {name} (skillOverrides)")
+        return disabled, restored
+
+    if disabled or restored:
+        if overrides:
+            settings["skillOverrides"] = overrides
+        else:
+            settings.pop("skillOverrides", None)
+        _save_settings(settings_path, settings)
+    save_state({STATE_SCOPE_KEY: scope, STATE_MANAGED_KEY: sorted(managed)})
+
+    if languages is None and scope != SCOPE_ALL:
+        print("  Skipped: language skill scoping (no registered project on disk; run install --local in a project first)")
+    elif disabled:
+        print(f"  Disabled: {len(disabled)} language skill(s) outside your detected stacks "
+              f"({', '.join(disabled)})")
+    if restored:
+        print(f"  Restored: {len(restored)} language skill(s) ({', '.join(restored)})")
+    if languages is not None and not disabled and not restored and scope == SCOPE_DETECTED:
+        print(f"  Language skills: scoped to {', '.join(sorted(languages)) or 'no detected languages'} (no change)")
+    return disabled, restored

package/scripts/instruction_core.py

@@ -6,8 +6,12 @@
 from __future__ import annotations
 
 import re
+import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from frontmatter import split_frontmatter  # noqa: E402
+
 
 CONSTITUTION_PATH = (
     Path(__file__).resolve().parent.parent / "app" / "constitution.md"
@@ -16,14 +20,7 @@ CONSTITUTION_PATH = (
 
 def _strip_frontmatter(text: str) -> str:
     """Return Markdown after an optional leading YAML frontmatter block."""
-    lines = text.splitlines()
-    if not lines or lines[0] != "---":
-        return text.strip()
-    try:
-        closing = lines.index("---", 1)
-    except ValueError:
-        return text.strip()
-    return "\n".join(lines[closing + 1:]).strip()
+    return split_frontmatter(text)[1].strip()
 
 
 def read_constitution(path: Path = CONSTITUTION_PATH) -> str:

package/scripts/merge-hooks.py

@@ -123,12 +123,22 @@ def _is_retired_toolkit_entry(entry: dict) -> bool:
     return True
 
 
+# Handler fields that change *how* a command hook is scheduled, not *what* it
+# runs. A legacy untagged entry that differs only in these is the same hook;
+# otherwise adding `async` or `timeout` in app/hooks.json would leave every
+# existing install running the old copy and the new copy side by side.
+_SCHEDULING_FIELDS = frozenset({
+    "async", "asyncRewake", "timeout", "statusMessage", "shell", "once", "if",
+})
+
+
 def _entry_signature(entry: dict) -> tuple:
     """Return the behavior-defining parts of a hook entry.
 
     Older ai-toolkit installs wrote hook entries without ``_source``. Matching
-    on the event, matcher, and handler payload lets current installs remove
-    those legacy duplicates while preserving unrelated user hooks.
+    on the event, matcher, and handler payload (minus scheduling fields) lets
+    current installs remove those legacy duplicates while preserving unrelated
+    user hooks.
     """
     handlers = []
     for hook in entry.get("hooks", []):
@@ -138,7 +148,7 @@ def _entry_signature(entry: dict) -> tuple:
         handlers.append(tuple(sorted(
             (key, value)
             for key, value in hook.items()
-            if key != "_source"
+            if key != "_source" and key not in _SCHEDULING_FIELDS
         )))
     return (entry.get("matcher", ""), tuple(handlers))
 

package/scripts/pack_codebase.py

@@ -37,7 +37,7 @@ import fnmatch
 import json
 import os
 import sys
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 
 # Token estimate: 4 chars per token is the standard rough heuristic for English / code.