@softspark/ai-toolkit 4.4.1 → 4.5.0

package/scripts/doctor.py

@@ -60,6 +60,7 @@ EXPECTED_HOOKS = [
     "config-desync-guard.sh",
     "instructions-audit.sh",
     "post-tool-use.sh",
+    "loop-guard.sh",
     "quality-check.sh",
     "quality-gate.sh",
     "revert-guard.sh",
@@ -549,6 +550,55 @@ def check_url_hooks(dr: DiagResult, fix_mode: bool) -> None:
                     print(f"    Could not re-fetch: {exc}")
 
 
+# ---------------------------------------------------------------------------
+# Check 10: Language Rules Drift (project-local)
+# ---------------------------------------------------------------------------
+
+def check_language_drift(dr: DiagResult) -> None:
+    """Warn when the current project gained a language but its rules were not injected.
+
+    Runs only inside a local-install project (cwd has .claude/CLAUDE.md with the
+    language-rules block). A new Cargo.toml / go.mod that appears after install
+    otherwise leaves the matching <lang>-rules unlinked with zero signal.
+    """
+    print()
+    print("## 10. Language Rules Drift")
+
+    claude_md = Path.cwd() / ".claude" / "CLAUDE.md"
+    if not claude_md.is_file():
+        dr.skip("not a local-install project (no .claude/CLAUDE.md)")
+        return
+    try:
+        content = claude_md.read_text(encoding="utf-8")
+    except OSError:
+        dr.skip("could not read .claude/CLAUDE.md")
+        return
+    if "TOOLKIT:language-rules" not in content:
+        dr.skip("no language-rules block in .claude/CLAUDE.md")
+        return
+
+    try:
+        from install_steps.detect_language import detect_languages
+    except Exception:
+        dr.skip("language detection unavailable")
+        return
+
+    missing = []
+    for module in detect_languages(Path.cwd(), toolkit_dir):
+        if not module.startswith("rules-"):
+            continue
+        skill = f"{module[len('rules-'):]}-rules"
+        if skill not in content:
+            missing.append(skill)
+
+    if not missing:
+        dr.ok("project language rules in sync")
+        return
+    for skill in missing:
+        lang = skill[: -len("-rules")]
+        dr.warn(f"{lang} detected but {skill} not injected — run: ai-toolkit install --local --lang {lang}")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -571,6 +621,7 @@ def main() -> None:
     check_benchmark_freshness(dr)
     check_stale_rules(dr, fix_mode)
     check_url_hooks(dr, fix_mode)
+    check_language_drift(dr)
 
     # Summary
     print("========================")

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-05-25",
+  "last_updated": "2026-05-30",
   "tools": [
     {
       "id": "claude-code",
@@ -24,12 +24,16 @@
       "capability_markers": [
         "PreToolUse",
         "PostToolUse",
+        "PostToolUseFailure",
+        "PostToolBatch",
         "SessionStart",
         "SessionEnd",
         "SubagentStart",
         "SubagentStop",
         "UserPromptSubmit",
+        "UserPromptExpansion",
         "Notification",
+        "MessageDisplay",
         "Stop",
         "StopFailure",
         "PreCompact",
@@ -452,6 +456,10 @@
         "hook event: UserPromptSubmit",
         "hook event: Stop",
         "hook event: PermissionRequest",
+        "hook event: PreCompact",
+        "hook event: PostCompact",
+        "hook event: SubagentStart",
+        "hook event: SubagentStop",
         "hook handler: command",
         "hook handler: prompt",
         "hook handler: agent",

package/scripts/generate_codex_hooks.py

@@ -4,10 +4,11 @@
 Maps compatible ai-toolkit hooks to Codex lifecycle events.
 Hook scripts are shared with Claude Code (stored in ~/.softspark/ai-toolkit/hooks/).
 
-Codex supports 6 events (PascalCase in config.toml / hooks.json):
-``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``SessionStart``,
-``UserPromptSubmit``, ``Stop``. PreToolUse/PostToolUse only support
-the ``Bash`` matcher.
+Codex exposes 10 lifecycle events (PascalCase in config.toml / hooks.json):
+``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``PreCompact``,
+``PostCompact``, ``SessionStart``, ``UserPromptSubmit``, ``SubagentStart``,
+``SubagentStop``, ``Stop``. PreToolUse/PostToolUse only support the ``Bash``
+matcher. We currently wire the subset defined in ``CODEX_HOOKS`` below.
 
 Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
 Reference: codex-rs/config/src/hook_config.rs.

package/scripts/validate.py

@@ -785,6 +785,9 @@ def validate_metadata_contracts(
     # Cross-validate versions: package.json vs manifest.json vs plugin.json
     _validate_version_sync(tk_dir, vr)
 
+    # Cross-validate the README platform matrix's Hooks column against reality
+    _validate_editor_hooks_honesty(tk_dir, vr)
+
     print()
     return actual_tests
 
@@ -836,6 +839,87 @@ def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
                     )
 
 
+# Editors that receive lifecycle hook enforcement without a generate_*_hooks.py
+# generator: Claude is native (app/hooks), opencode bridges via its plugin
+# (generate_opencode_plugin.py). Every other hook-enabled editor is derived
+# from the generate_<editor>_hooks.py set so this check stays honest as
+# generators come and go.
+_NATIVE_HOOK_EDITORS = {"claude", "opencode"}
+
+# README platform label (lowercased) -> canonical editor key.
+_README_PLATFORM_KEY = {
+    "claude code": "claude",
+    "cursor": "cursor",
+    "windsurf": "windsurf",
+    "gemini cli": "gemini",
+    "github copilot": "copilot",
+    "cline": "cline",
+    "roo code": "roo",
+    "aider": "aider",
+    "augment": "augment",
+    "google antigravity": "antigravity",
+    "codex cli": "codex",
+    "opencode": "opencode",
+}
+
+
+def _validate_editor_hooks_honesty(tk_dir: Path, vr: ValidationResult) -> None:
+    """Ensure the README platform matrix's Hooks column matches reality.
+
+    Guards against the overclaim that every editor gets hook enforcement when
+    only a subset does — the machine-enforced constitution needs generated
+    hooks, and rules-only editors receive guidance text without blocking hooks.
+    """
+    scripts_dir = tk_dir / "scripts"
+    readme = tk_dir / "README.md"
+    if not scripts_dir.is_dir() or not readme.is_file():
+        return  # installed copy without source — nothing to cross-check
+
+    # Actual hook-enabled editors: native set + generate_<editor>_hooks.py stems.
+    actual = set(_NATIVE_HOOK_EDITORS)
+    for gen in scripts_dir.glob("generate_*_hooks.py"):
+        stem = gen.name[len("generate_"):-len("_hooks.py")]
+        actual.add(stem)
+
+    content = readme.read_text(encoding="utf-8")
+    if "| Hooks |" not in content:
+        return  # matrix has no Hooks column to validate
+
+    claimed: set[str] = set()
+    parsed_any = False
+    for line in content.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 4:
+            continue
+        key = _README_PLATFORM_KEY.get(cells[0].lower())
+        if key is None:
+            continue  # header, separator, or unknown row
+        parsed_any = True
+        if "✅" in cells[2]:  # ✅
+            claimed.add(key)
+
+    if not parsed_any:
+        return
+
+    missing = actual - claimed       # has hooks but README omits the ✅
+    overclaimed = claimed - actual   # README claims ✅ but no generator exists
+    if missing:
+        vr.error(
+            "README Hooks column understates enforcement for: "
+            + ", ".join(sorted(missing))
+        )
+    if overclaimed:
+        vr.error(
+            "README Hooks column overclaims enforcement for: "
+            + ", ".join(sorted(overclaimed))
+            + " (no hook generator or native bridge found)"
+        )
+    if not missing and not overclaimed:
+        print(f"  OK: editor hooks honesty ({len(claimed)} hook-enabled editors)")
+
+
 ROMAN_NUMERALS = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]