@softspark/ai-toolkit 4.28.0 → 4.29.1

package/CHANGELOG.md

@@ -7,6 +7,91 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.29.1 — The guard stops blocking the safe branch delete (2026-08-21)
+
+### Fixed
+
+- **`guard-destructive.sh` no longer folds `-d` onto `-D`.** Every pattern was
+  matched by a single `grep -qEi`, so the `git\s+branch\s+-D\b` pattern also
+  caught `git branch -d`. Those are different operations: `-D` discards an
+  unmerged branch, `-d` refuses to. The safe one is what
+  `.claude/rules/ai-toolkit-git-workflow.md` tells users to run after every
+  merge, and the guard blocked it — a false positive on the toolkit's own
+  advice, in the toolkit's own safety hook.
+- **Patterns are matched in two passes, split by whether case carries meaning.**
+  Command names and flags go through a case-sensitive `grep -qE`; POSIX flags
+  that differ only in case are different flags, and folding them together can
+  only lose information. SQL keywords and the Windows `format` command go
+  through a case-insensitive `grep -qEi`, because their casing genuinely varies
+  in the wild — `drop table`, `Truncate`, and `delete from` all still block.
+  The `-i` was presumably there for the SQL patterns all along; it was the
+  flag patterns that paid for it.
+
+- **A cross-file race in the test suite.** `doctor --fix regenerates missing
+  llms-full.txt` deleted the artifact from the shared checkout and asserted on
+  doctor's `FIXED` line. `npm test` runs `bats --jobs 4
+  --no-parallelize-within-files`, so files run concurrently, and
+  `test_doctor_plugin_double_load.bats` also runs `doctor --fix` — which
+  regenerates that artifact. When it won, the assertion saw a present file, no
+  `FIXED` line, and a red suite; the test also left a `llms-full.txt.test-bak`
+  in the repo, because the restoring `mv` never ran. v4.29.0 added a second
+  `doctor --fix` call to the plugin test file, which is what made a latent race
+  start firing. The test now runs doctor against a private copy of the toolkit,
+  so it mutates no shared state at all.
+
+### Changed
+
+- `kb/reference/hooks-catalog.md` documents the two-pass matching and lists the
+  safe branch delete among the guard's exemptions.
+- Test count: 1666 → 1671. The new cases pin both directions: the safe delete
+  and an uppercase non-flag pass, lowercase and mixed-case SQL block.
+
+### Known gap (not addressed here)
+
+- The guard matches `git branch -D` but not its long form, `git branch --delete
+  --force`. That gap predates this fix and closing it is a coverage change
+  rather than a case-sensitivity one, so it is left for a separate decision.
+
+---
+
+## v4.29.0 — Stale plugin uploads stop hiding (2026-08-21)
+
+### Added
+
+- **`doctor` reports Claude app plugin version drift.** Check 11 now compares the
+  `version` recorded for every `ai-toolkit@…` entry in
+  `~/.claude/plugins/installed_plugins.json` against the installed toolkit's
+  `package.json` and warns when they differ. The upload is a point-in-time ZIP:
+  once the toolkit moves on, Chat and Cowork keep running the skills, agents,
+  hooks, and rules from whenever the export was made, with no signal anywhere
+  that they are behind. `--fix` deliberately cannot clear this warning — the
+  export can be regenerated but the upload itself happens by hand in the app's
+  Customize > Plugins panel, so the check names the two steps instead of
+  pretending to do them.
+
+### Changed
+
+- **Version drift is checked before the enabled/disabled branch.** A plugin
+  disabled for Claude Code still feeds Chat and Cowork, which have no other
+  channel for toolkit content. The old flow returned `OK: registered but
+  disabled` and never looked at versions, so the state a user reaches by running
+  `doctor --fix` was also the state where a stale upload passed silently. That
+  was the wrong place to stop looking.
+- **`ai-toolkit install` re-asserts the plugin as disabled for Claude Code.**
+  Uploading the ZIP re-enables the plugin every time, which put the double-load
+  fix back on whoever remembered to run `doctor --fix` afterwards. Global
+  installs and updates now flip enabled toolkit plugins to `false` in
+  `~/.claude/settings.json` and print each key they touched. `--local` and
+  `--dry-run` are untouched, and non-toolkit plugins are never modified. The
+  disable logic moved into `disable_toolkit_plugins_for_claude_code()` in
+  `scripts/doctor.py`, shared by both call sites.
+- Test count: 1659 → 1666.
+- Skill body budget threshold unchanged. The largest body (`medplum-rules`, 16760
+  bytes) sits 1240 bytes under the 18000-byte warn line, short of the 2000-byte
+  margin the ratchet requires, so the threshold stays where it is this release.
+
+---
+
 ## v4.28.0 — MCP servers reach Chat and Cowork (2026-08-21)
 
 ### Added

package/README.md

@@ -6,22 +6,21 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1659%20passing-success)](tests/)
-
-## What's New in v4.28.0
-
-**v4.28.0** gives Claude Chat and Cowork their MCP servers:
-
-- The Claude app parses `claude_desktop_config.json` on startup and reports bad
-  entries in its own warning dialog, but ai-toolkit never wrote to it. A user
-  with seven servers configured for Claude Code still had an empty `mcpServers`
-  block in Cowork.
-- `ai-toolkit mcp install --editor claude-app --scope global <template>` now
-  writes it, on macOS, Windows, and Linux, honoring `CLAUDE_USER_DATA_DIR` the
-  way the app does. `--editor claude` remains Claude Code -- different runtime,
-  different file.
-- The app accepts stdio entries only, so HTTP/SSE templates are bridged as
-  `npx -y mcp-remote <url>` rather than written verbatim and silently skipped.
+[![Tests](https://img.shields.io/badge/tests-1671%20passing-success)](tests/)
+
+## What's New in v4.29.1
+
+**v4.29.1** stops the destructive-command guard from blocking a safe branch delete:
+
+- `guard-destructive.sh` matched every pattern with one case-insensitive grep, so
+  the force-delete pattern also caught the lowercase safe delete -- the variant
+  that refuses to drop an unmerged branch, and exactly the post-merge cleanup the
+  toolkit's own git-workflow rules prescribe.
+- Patterns are now matched in two passes. Command names and flags are matched
+  case-sensitively, because short flags that differ only in case are different
+  flags. SQL keywords and the Windows `format` command stay case-insensitive, so
+  lowercase SQL still blocks.
+- Force delete still blocks. Test count: 1666 -> 1671.
 
 ## Table of Contents
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.28.0",
+  "version": "4.29.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/guard-destructive.sh

@@ -40,7 +40,15 @@ fi
 # --force or -f left behind still blocks.
 SAFE_STRIPPED=$(printf '%s' "$NORMALIZED" | sed -E 's/--force-with-lease(=[^ ]*)?//g; s/--force-if-includes//g')
 
-# Destructive patterns — word-boundary aware where possible
+# Destructive patterns — word-boundary aware where possible.
+#
+# Two buckets, matched by two greps, because case sensitivity is not a uniform
+# property of these patterns. POSIX command names and flags are case-SIGNIFICANT:
+# `-d` and `-D` are different flags, and folding them together made the guard
+# block `git branch -d` — the safe delete that refuses unmerged branches — as if
+# it were `-D`. SQL keywords carry no such distinction and are written in every
+# casing in the wild, so they need folding. One case-insensitive grep over both
+# sets cannot express that, and the flag bucket is the one that loses.
 DESTRUCTIVE_PATTERNS=(
     # rm variants (short flags, long flags, separated flags, sudo, xargs/find piped)
     'rm\s+(-[rRf]{2,}|-r\s+-f|-f\s+-r)'
@@ -54,18 +62,13 @@ DESTRUCTIVE_PATTERNS=(
     'find\s+.*-delete'
     'find\s+.*-exec\s+rm\b'
 
-    # SQL destructive operations
-    'DROP\s+(TABLE|DATABASE|SCHEMA|INDEX)'
-    'TRUNCATE\s+'
-    'DELETE\s+FROM\s+\S+\s*(;|$|WHERE\s+1)'
-
     # Disk/filesystem destructive
-    'format\s+/'
     'dd\s+if='
     'mkfs\b'
     'shred\b'
 
-    # Git destructive operations
+    # Git destructive operations. `-D` only: `git branch -d` refuses to delete an
+    # unmerged branch and is the documented post-merge cleanup, not a hazard.
     'git\s+push\s+(--force|-f)\b'
     'git\s+push\s+.*--force'
     'git\s+reset\s+--hard'
@@ -88,10 +91,25 @@ DESTRUCTIVE_PATTERNS=(
     '>\s*/dev/sd[a-z]'
 )
 
-# Build combined regex
+# Case-insensitive bucket: patterns whose real-world casing genuinely varies.
+# SQL is written DROP TABLE, drop table, and Drop Table with equal frequency;
+# `format` is a Windows command and Windows command names are case-insensitive.
+DESTRUCTIVE_PATTERNS_NOCASE=(
+    # SQL destructive operations
+    'DROP\s+(TABLE|DATABASE|SCHEMA|INDEX)'
+    'TRUNCATE\s+'
+    'DELETE\s+FROM\s+\S+\s*(;|$|WHERE\s+1)'
+
+    # Disk/filesystem destructive
+    'format\s+/'
+)
+
+# Build combined regexes
 REGEX=$(IFS='|'; echo "${DESTRUCTIVE_PATTERNS[*]}")
+REGEX_NOCASE=$(IFS='|'; echo "${DESTRUCTIVE_PATTERNS_NOCASE[*]}")
 
-if echo "$SAFE_STRIPPED" | grep -qEi "($REGEX)"; then
+if echo "$SAFE_STRIPPED" | grep -qE "($REGEX)" \
+    || echo "$SAFE_STRIPPED" | grep -qEi "($REGEX_NOCASE)"; then
     echo "WARNING: Potentially destructive command detected. Please verify." >&2
     exit 2
 fi

package/kb/reference/hooks-catalog.md

@@ -95,8 +95,15 @@ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 - `git push --force`
 - `chmod -R 777`
 
+**Case sensitivity:** patterns are matched in two passes. Command names and flags
+are matched case-**sensitively**, because `-d` and `-D` are different flags —
+`git branch -D` blocks, `git branch -d` does not. SQL keywords and the Windows
+`format` command are matched case-**insensitively**, so `drop table` blocks the
+same as `DROP TABLE`.
+
 **Exemptions (avoid false positives):**
 - `git push --force-with-lease` / `--force-if-includes` — the safe force-push variants are allowed.
+- `git branch -d` — the safe delete refuses unmerged branches and is the post-merge cleanup the git-workflow rules prescribe. `git branch -D` still blocks.
 - A single, non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as *data* (e.g. a commit message mentioning `DROP TABLE`) is allowed. Chained commands (`&&`, `;`, `|`) are still inspected in full.
 
 ### PreToolUse (file ops) — `guard-path.sh`

package/llms-full.txt

@@ -12244,8 +12244,15 @@ for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 - `git push --force`
 - `chmod -R 777`
 
+**Case sensitivity:** patterns are matched in two passes. Command names and flags
+are matched case-**sensitively**, because `-d` and `-D` are different flags —
+`git branch -D` blocks, `git branch -d` does not. SQL keywords and the Windows
+`format` command are matched case-**insensitively**, so `drop table` blocks the
+same as `DROP TABLE`.
+
 **Exemptions (avoid false positives):**
 - `git push --force-with-lease` / `--force-if-includes` — the safe force-push variants are allowed.
+- `git branch -d` — the safe delete refuses unmerged branches and is the post-merge cleanup the git-workflow rules prescribe. `git branch -D` still blocks.
 - A single, non-chained `echo`/`printf`/`git commit`/`git tag` carrying a destructive token as *data* (e.g. a commit message mentioning `DROP TABLE`) is allowed. Chained commands (`&&`, `;`, `|`) are still inspected in full.
 
 ### PreToolUse (file ops) — `guard-path.sh`

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.28.0",
+  "version": "4.29.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.28.0",
+  "version": "4.29.1",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/doctor.py

@@ -683,6 +683,68 @@ def _registered_toolkit_plugins(registry: dict) -> list[str]:
     return [key for key in plugins if str(key).split("@", 1)[0] == "ai-toolkit"]
 
 
+def _registered_plugin_versions(registry: dict, keys: list[str]) -> dict[str, str]:
+    """Map plugin key to the version recorded in the Claude Code registry."""
+    plugins = registry.get("plugins", {})
+    versions: dict[str, str] = {}
+    for key in keys:
+        entries = plugins.get(key)
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if isinstance(entry, dict) and isinstance(entry.get("version"), str):
+                versions[key] = entry["version"]
+                break
+    return versions
+
+
+def _toolkit_package_version() -> str | None:
+    """Version of the installed toolkit package, or None when unreadable."""
+    try:
+        data = json.loads((toolkit_dir / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    version = data.get("version")
+    return version if isinstance(version, str) else None
+
+
+def disable_toolkit_plugins_for_claude_code() -> list[str]:
+    """Disable every enabled ai-toolkit plugin in ``~/.claude/settings.json``.
+
+    Returns the keys that were flipped. Uploading the Claude app plugin re-enables
+    it for Claude Code every time, so this is re-asserted rather than fixed once.
+    Raises OSError when settings.json cannot be written.
+    """
+    if not PLUGIN_REGISTRY.is_file():
+        return []
+    try:
+        registry = json.loads(PLUGIN_REGISTRY.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+
+    keys = _registered_toolkit_plugins(registry)
+    if not keys:
+        return []
+
+    settings_json = CLAUDE_DIR / "settings.json"
+    try:
+        settings = json.loads(settings_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    enabled = settings.get("enabledPlugins", {})
+    if not isinstance(enabled, dict):
+        enabled = {}
+
+    active = [key for key in keys if enabled.get(key, True)]
+    if not active:
+        return []
+
+    enabled.update({key: False for key in active})
+    settings["enabledPlugins"] = enabled
+    settings_json.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return active
+
+
 def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
     """Warn when the Claude app plugin and the global install both feed Claude Code.
 
@@ -709,6 +771,22 @@ def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
         dr.ok("no ai-toolkit plugin registered in Claude Code")
         return
 
+    # Version drift is independent of whether the plugin is enabled here: a
+    # plugin disabled for Claude Code still feeds Chat and Cowork, and those
+    # runtimes have no other channel for skills, agents, hooks, or rules. Report
+    # it before the enabled/disabled branch, which returns early on the healthy
+    # path and would otherwise let a stale upload pass unnoticed.
+    toolkit_version = _toolkit_package_version()
+    if toolkit_version:
+        for key, plugin_version in _registered_plugin_versions(registry, keys).items():
+            if plugin_version != toolkit_version:
+                dr.warn(
+                    f"{key} is v{plugin_version} but the toolkit is v{toolkit_version}: "
+                    "Chat and Cowork keep running the older skills, agents, hooks, and "
+                    "rules until you re-run `ai-toolkit claude-app export` and upload "
+                    "the ZIP again (--fix cannot do this; the upload is manual)"
+                )
+
     settings_json = CLAUDE_DIR / "settings.json"
     try:
         settings = json.loads(settings_json.read_text(encoding="utf-8"))
@@ -738,14 +816,12 @@ def check_plugin_double_load(dr: DiagResult, fix_mode: bool) -> None:
     if not fix_mode:
         return
 
-    enabled.update({key: False for key in active})
-    settings["enabledPlugins"] = enabled
     try:
-        settings_json.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+        disabled = disable_toolkit_plugins_for_claude_code()
     except OSError as exc:
         dr.fail(f"could not disable plugin in settings.json: {exc}")
         return
-    for key in active:
+    for key in disabled:
         dr.fixed(f"disabled {key} for Claude Code (global install stays authoritative)")
 
 

package/scripts/install.py

@@ -831,6 +831,18 @@ def main() -> None:
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")
 
+    # 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
+    # than left to whoever remembers to run `doctor --fix` afterwards.
+    if not local and not dry_run:
+        from doctor import disable_toolkit_plugins_for_claude_code
+        try:
+            for key in disable_toolkit_plugins_for_claude_code():
+                print(f"  Disabled Claude app plugin for Claude Code: {key}")
+        except OSError as error:
+            print(f"  WARNING: could not disable Claude app plugin: {error}")
+
     print_summary(local=local)