@softspark/ai-toolkit 4.32.0 → 4.32.1

package/CHANGELOG.md

@@ -7,6 +7,38 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.32.1 - Plugin removal leaves nothing behind (2026-09-04)
+
+Both fixes come from running the post-release SOPs on v4.32.0 in an isolated
+sandbox; both defects predate that release (identical on v4.31.0).
+
+### Fixed
+
+- **`plugin remove` deletes the hooks and scripts a pack installed.** The
+  Claude and Codex install paths copied `hooks/plugin-<pack>-*` and
+  `plugin-scripts/<pack>/*` into `~/.softspark/ai-toolkit` but never recorded
+  them in `shared_asset_ownership`, so removal found no owner and preserved
+  every file as "untracked": each pack left 4-5 files behind. Install now
+  records sha256/mode/inode for what it copied; removal deletes only entries
+  this editor consumes that no other editor still uses and that are unchanged
+  on disk, preserves an edited file with a `WARN preserved changed plugin
+  asset` line, and drops the empty `plugin-scripts/<pack>/` directory.
+  `tests/test_plugin_asset_removal.bats` covers install, zero-residue removal,
+  user-edited preservation, two-editor sharing, and reinstall.
+- **Five skill scripts answer `--help`.** `doc-inventory.py`,
+  `dependency-graph.py`, `migration-status.py`, `refactor-scan.py`, and
+  `complexity.py` treated `--help` as a path and returned a JSON error.
+  `tests/test_skill_scripts_help.bats` now probes every documented
+  `${CLAUDE_SKILL_DIR}` invocation with `--help` (exit 0, no traceback), the
+  same check as post-release SOP Phase 4b. The probe uses `perl alarm` as its
+  hang guard, not GNU `timeout`, which the macOS CI runner does not have.
+- **`pre_deploy_check.py` no longer crashes on Linux.** It probed for docker
+  by running the shell builtin `command -v` through `subprocess`, which only
+  works on macOS (a `/usr/bin/command` binary exists there); on Linux it raised
+  `FileNotFoundError` before any check ran. Now `shutil.which`. Caught by the
+  new `--help` probe on the Ubuntu CI runner, which is the point of that test.
+- **Test count.** Bats increased from 1966 to 1972.
+
 ## v4.32.0 - Context budget: scoped rules, scoped language skills, doctor budget checks (2026-09-04)
 
 ### Added

package/README.md

@@ -6,30 +6,25 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-114-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1966%20passing-success)](tests/)
-
-## What's New in v4.32.0
-
-**v4.32.0** cuts what every session pays for before you type, and adds the
-checks that keep it cut:
-
-- Common rules are path-scoped from their source: `testing` and `performance`
-  load only for matching files, and the project `.claude/CLAUDE.md` index says
-  which rules are always-on instead of claiming lazy loading for all of them.
-- Language knowledge skills follow your projects: `install --language-skills
-  detected` (default) turns off `<lang>-rules`/`<lang>-patterns` skills for
-  languages no registered project uses, reversibly, and restores them when a
-  project brings the language back.
-- `ai-toolkit doctor` gains a Context Budget check (est. resident tokens,
-  zero-use skills) and a Permission Rules check (over-broad `permissions.allow`
-  wildcards). Both read-only.
-- One strict frontmatter parser replaces twelve private copies; `validate.py`
-  now rejects descriptions over 1024 characters or unquoted ones containing
-  `: `. Every shipped Markdown file parses under the strict grammar.
-- Team-only git conventions moved to a `git-team` rule that ships with
-  `--profile strict`; `quality-gate.sh` lints with ruff only when the project
-  configured ruff; advisory Stop hooks run in the background. Test count:
-  1931 -> 1966 bats + 348 pytest.
+[![Tests](https://img.shields.io/badge/tests-1972%20passing-success)](tests/)
+
+## What's New in v4.32.1
+
+**v4.32.1** fixes two defects the post-release SOPs found on v4.32.0 (both
+older than that release):
+
+- `ai-toolkit plugin remove` now deletes the hooks and scripts a pack
+  installed under `~/.softspark/ai-toolkit`. Install records what it copied;
+  removal deletes only unchanged, unshared files and names anything it
+  preserves. Every pack used to leave 4-5 files behind.
+- Five skill scripts (`doc-inventory`, `dependency-graph`, `migration-status`,
+  `refactor-scan`, `complexity`) answer `--help` instead of treating it as a
+  path; a new test probes every documented skill script with `--help`.
+- Still in this train from v4.32.0: path-scoped common rules, language skills
+  scoped to your registered projects (`--language-skills`), `doctor` Context
+  Budget and Permission Rules checks, one strict frontmatter parser, and the
+  `git-team` rule for `--profile strict`. Test count: 1966 -> 1972 bats +
+  348 pytest.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

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.32.0",
+  "version": "4.32.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/analyze/scripts/complexity.py

@@ -125,6 +125,9 @@ def _summary(root: Path, all_files: list[Path]) -> tuple[int, int]:
 
 def main() -> None:
     """Entry point: analyse directory and print text report to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: complexity.py [directory]\n\nReport per-file code complexity for directory (default: cwd).")
+        return
     root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
     now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 

package/app/skills/deploy/scripts/pre_deploy_check.py

@@ -16,6 +16,7 @@ Usage::
 from __future__ import annotations
 
 import json
+import shutil
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -50,12 +51,15 @@ def _git_branch() -> str:
 
 
 def _docker_available() -> bool:
-    """Return True if the ``docker`` command is on PATH."""
-    result = _run(["command", "-v", "docker"])
-    # Fallback: just try docker --version
-    if result.returncode != 0:
-        result = _run(["docker", "--version"])
-    return result.returncode == 0
+    """Return True if the ``docker`` command is on PATH.
+
+    ``command -v`` is a shell builtin; running it through ``subprocess`` only
+    worked on macOS, which ships a ``/usr/bin/command`` binary. On Linux it
+    raised ``FileNotFoundError`` before any check ran (v4.32.1).
+    """
+    if shutil.which("docker") is None:
+        return False
+    return _run(["docker", "--version"]).returncode == 0
 
 
 def _docker_services_running() -> bool:
@@ -155,6 +159,9 @@ def _run_checks(env: str) -> _CheckCollector:
 
 def main() -> None:
     """Entry point: run checks and print JSON result to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: pre_deploy_check.py [environment]\n\nRun pre-deployment checks for environment (default: staging) and print JSON.")
+        return
     env = sys.argv[1] if len(sys.argv) > 1 else "staging"
     branch = _git_branch()
     collector = _run_checks(env)

package/app/skills/docs/scripts/doc-inventory.py

@@ -130,6 +130,9 @@ def get_mtime(filepath: str) -> float:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: doc-inventory.py [directory]\n\nInventory documentation files under directory (default: cwd) as JSON.")
+        return
     root = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.getcwd()
     if not os.path.isdir(root):
         print(json.dumps({"error": f"Not a directory: {root}"}))

package/app/skills/explain/scripts/dependency-graph.py

@@ -159,6 +159,9 @@ def generate_mermaid(target_name: str, imports: list, imported_by: list) -> str:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: dependency-graph.py <file_or_directory>\n\nPrint the import/dependency graph of a file or directory as JSON.")
+        return
     if len(sys.argv) < 2:
         print(json.dumps({"error": "Usage: dependency-graph.py <file_or_directory>"}))
         sys.exit(1)

package/app/skills/migrate/scripts/migration-status.py

@@ -182,6 +182,9 @@ def detect(project_dir: Path) -> dict[str, object]:
 
 def main() -> None:
     """Entry point: detect migration tool and print JSON result to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: migration-status.py [project_dir]\n\nDetect the migration tool in project_dir (default: cwd) and report its status as JSON.")
+        return
     project_dir = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
     if not project_dir.is_dir():
         print(json.dumps({"error": f"Not a directory: {project_dir}"}))

package/app/skills/refactor/scripts/refactor-scan.py

@@ -154,6 +154,9 @@ def analyze_file(filepath: str, project_root: str) -> dict:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: refactor-scan.py <file_or_directory>\n\nScan a file or directory for refactoring candidates and print JSON.")
+        return
     if len(sys.argv) < 2:
         print(json.dumps({"error": "Usage: refactor-scan.py <file_or_directory>"}))
         sys.exit(1)

package/kb/reference/plugin-pack-conventions.md

@@ -3,9 +3,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."
 ---
 
@@ -167,7 +167,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)

package/llms-full.txt

@@ -15855,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."
 ---
 
@@ -16019,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)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.32.0",
+  "version": "4.32.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.32.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",

package/scripts/plugin.py

@@ -2006,6 +2006,16 @@ def _apply_asset_install(
             "inode": version.inode,
         }
         print(f"    Installed plugin {spec.kind}: {spec.path.name}")
+    return _merge_asset_ownership(previous_ownership, name, editor, produced_entries)
+
+
+def _merge_asset_ownership(
+    previous_ownership: dict | None,
+    name: str,
+    editor: str,
+    produced_entries: dict[str, dict],
+) -> dict:
+    """Fold one editor's freshly written assets into the pack's ownership record."""
     entries = _asset_entries(previous_ownership, name)
     entries.update(produced_entries)
     consumers = _shared_asset_consumers(previous_ownership, name)
@@ -2022,6 +2032,37 @@ def _apply_asset_install(
     }
 
 
+def _ownership_from_copied_assets(
+    name: str,
+    editor: str,
+    pack_dir: Path,
+    hook_specs: list[dict],
+    previous_ownership: dict | None,
+) -> dict:
+    """Record what the non-transactional Claude/Codex install just copied.
+
+    ``_copy_plugin_hook_scripts`` and ``_copy_plugin_scripts`` write the same
+    paths ``_prepare_asset_specs`` describes but never recorded them, so
+    removal had nothing to verify against and preserved every file as
+    "untracked" (v4.32.1). Reading the versions back from disk after the copy
+    gives removal the same sha256/mode/inode contract the JSON runtimes get.
+    """
+    produced: dict[str, dict] = {}
+    for spec in _prepare_asset_specs(name, pack_dir, hook_specs):
+        version = _read_file_version(spec.path)
+        if version is None:
+            continue
+        produced[spec.key] = {
+            "path": str(spec.path),
+            "kind": spec.kind,
+            "sha256": hashlib.sha256(version.content).hexdigest(),
+            "mode": version.mode,
+            "device": version.device,
+            "inode": version.inode,
+        }
+    return _merge_asset_ownership(previous_ownership, name, editor, produced)
+
+
 def _preflight_asset_removal(
     transaction: PluginFileTransaction,
     ownership: dict | None,
@@ -2075,6 +2116,74 @@ def _apply_asset_removal(
         print(f"    WARN preserved changed or user-owned plugin asset: {path}")
 
 
+def _remove_owned_plugin_assets(state: dict | None, name: str, editor: str) -> None:
+    """Delete the hook and script files this pack installed for ``editor``.
+
+    Claude and Codex removal never consulted ``shared_asset_ownership``: the
+    files were written on install, recorded, and then reported as "untracked"
+    on remove because nothing looked the record up. Every pack left its hooks
+    and ``plugin-scripts/<name>/`` behind (v4.32.1).
+
+    Same rules as the transactional runtimes: an entry is deleted only when
+    this editor consumes it, no other editor still does, and the file on disk
+    is byte- and inode-identical to what install recorded. Anything else
+    (user edits, a file install never wrote, a symlink) is preserved and named.
+    """
+    ownership = _shared_asset_ownership_for(state or {}, name)
+    entries = _asset_entries(ownership, name)
+    consumers = _shared_asset_consumers(ownership, name)
+    editor_keys = set(consumers.get(editor, ()))
+    other_keys = {
+        key
+        for consumer, keys in consumers.items()
+        if consumer != editor
+        for key in keys
+    }
+    scripts_root = TOOLKIT_DATA_DIR / "plugin-scripts" / name
+    hook_prefix = f"plugin-{name}-"
+    handled: set[Path] = set()
+
+    for key, entry in entries.items():
+        raw_path = entry.get("path")
+        if not isinstance(raw_path, str):
+            continue
+        path = Path(raw_path)
+        handled.add(path.absolute())
+        if key not in editor_keys or key in other_keys:
+            continue
+        kind = entry.get("kind")
+        if kind == "hook":
+            safe = path.parent.absolute() == HOOKS_DIR.absolute() and path.name.startswith(hook_prefix)
+        elif kind == "script":
+            safe = path.parent.absolute() == scripts_root.absolute()
+        else:
+            safe = False
+        if not safe:
+            print(f"    WARN refused to remove plugin asset outside its owned root: {path}")
+            continue
+        if path.is_symlink():
+            print(f"    WARN preserved symlinked plugin asset: {path}")
+            continue
+        version = _read_file_version(path)
+        if version is None:
+            continue
+        if not _asset_entry_matches(path, version, entry):
+            print(f"    WARN preserved changed plugin asset: {path}")
+            continue
+        path.unlink()
+        print(f"    Removed plugin asset: {path.name}")
+
+    for hook in sorted(HOOKS_DIR.glob(f"{hook_prefix}*")):
+        if hook.absolute() not in handled:
+            print(f"    WARN preserved untracked plugin hook: {hook}")
+    if scripts_root.is_dir():
+        for leftover in sorted(scripts_root.iterdir()):
+            if leftover.absolute() not in handled:
+                print(f"    WARN preserved untracked plugin script: {leftover}")
+        if not any(scripts_root.iterdir()):
+            scripts_root.rmdir()
+
+
 def _state_after_removal(
     state: dict,
     editor: str,
@@ -2616,19 +2725,15 @@ def _remove_claude_pack_links(pack: dict, pack_dir: Path) -> None:
 
 
 def remove_pack_claude(
-    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool
+    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool,
+    state: dict | None = None,
 ) -> bool:
     hook_specs = _resolve_pack_hooks(pack, pack_dir)
     rule_specs = _resolve_pack_rules(pack, pack_dir)
     _remove_claude_pack_links(pack, pack_dir)
 
     if not keep_shared_assets:
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
-            print(f"    WARN preserved untracked plugin hook: {hook}")
-
-        scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
-        if scripts_dir.is_dir():
-            print(f"    WARN preserved untracked plugin scripts: {scripts_dir}")
+        _remove_owned_plugin_assets(state, name, "claude")
 
     if any(not spec["is_core"] for spec in hook_specs):
         _strip_claude_hooks(name)
@@ -3000,7 +3105,8 @@ def install_pack_codex(name: str, pack: dict, pack_dir: Path) -> bool:
 
 
 def remove_pack_codex(
-    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool
+    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool,
+    state: dict | None = None,
 ) -> bool:
     _assert_safe_codex_surface()
     _strip_codex_hooks(name)
@@ -3016,14 +3122,10 @@ def remove_pack_codex(
                 print(f"    WARN preserved user-owned Codex hook: {hook.name}")
 
     if not keep_shared_assets:
-        # Clean paths used by releases before native Codex plugin assets moved
-        # under $CODEX_HOME. Claude still owns these when installed for both.
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
-            print(f"    WARN preserved untracked plugin hook: {hook}")
-
-        scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
-        if scripts_dir.is_dir():
-            print(f"    WARN preserved untracked plugin scripts: {scripts_dir}")
+        # Paths used by releases before native Codex plugin assets moved under
+        # $CODEX_HOME. Claude still owns these when installed for both, which
+        # the ownership consumers encode; only Codex-consumed entries go.
+        _remove_owned_plugin_assets(state, name, "codex")
 
     _remove_codex_rules(name)
     print(f"  Done: removed {name} from codex")
@@ -3202,6 +3304,14 @@ def _install_pack_locked(
             if transaction_snapshots is not None:
                 _restore_file_snapshots(transaction_snapshots)
             return False
+        if editor in ("claude", "codex"):
+            asset_ownership = _ownership_from_copied_assets(
+                name,
+                editor,
+                pack_dir,
+                _resolve_pack_hooks(pack, pack_dir),
+                _shared_asset_ownership_for(state, name),
+            )
 
         if hook_config_update is not None:
             if transaction_snapshots is not None:
@@ -3362,6 +3472,7 @@ def _remove_pack_locked(
                 pack,
                 pack_dir,
                 keep_shared_assets=keep_shared_assets,
+                state=state,
             )
         elif editor == "codex":
             ok = remove_pack_codex(
@@ -3369,6 +3480,7 @@ def _remove_pack_locked(
                 pack,
                 pack_dir,
                 keep_shared_assets=keep_shared_assets,
+                state=state,
             )
         elif editor in JSON_HOOK_RUNTIMES:
             ok = remove_pack_json_runtime(