@softspark/ai-toolkit 4.25.1 → 4.27.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.27.0 — Doctor sees the Claude app plugin (2026-08-21)
+
+### Added
+
+- **Doctor check 11: plugin double-load.** `ai-toolkit doctor` now reads the
+  Claude Code plugin registry (`~/.claude/plugins/installed_plugins.json`) and
+  `enabledPlugins` in `~/.claude/settings.json`. When an uploaded Claude app
+  plugin is active next to the global install, both feed the same session:
+  Claude Code merges plugin hooks with user hooks without deduplication, so every
+  toolkit hook fires twice per event and skills and agents load twice. The check
+  warns with the hook count, and `--fix` disables the plugin for Claude Code
+  while leaving the global install authoritative. Previously this passed as a
+  healthy install with no signal at all.
+- `kb/troubleshooting/plugin-double-load.md` documents the symptom, the debug-log
+  evidence, and the fix.
+
+---
+
+## v4.26.0 — Python floor is declared and enforced (2026-08-21)
+
+### Added
+
+- **Python preflight in the CLI.** `bin/ai-toolkit.js` now verifies `python3`
+  exists and reports at least 3.11 before spawning any script, and prints a
+  platform-specific fix (`brew install python@3.13` on macOS) instead of a
+  traceback from deep inside `scripts/`. The check is lazy and memoized, so
+  `help` and `--version` still run without a Python interpreter.
+- **Matching floor check in `scripts/_common.py`.** Every entry point imports
+  `_common` first, so `python3 scripts/install.py` run directly fails with the
+  same message rather than a `TypeError` from whichever module happens to use
+  3.11+ syntax.
+- **CI import sweep.** The `python-syntax` job now runs on a `['3.11', '3.13']`
+  matrix and imports every module under `scripts/` on each. `py_compile` only
+  catches syntax, which is exactly why a 3.10-only construct shipped: version-
+  gated runtime features surface on import, not on compile.
+
+### Fixed
+
+- **`ai-toolkit update --local` crashed on macOS system Python.** `/usr/bin/python3`
+  is 3.9 on every Mac, and `scripts/mcp_editors.py` uses
+  `@dataclass(frozen=True, slots=True)` (3.10+), so the install path died with
+  `TypeError: dataclass() got an unexpected keyword argument 'slots'` while
+  importing `install_steps/ai_tools.py`. The interpreter is now rejected up
+  front with instructions.
+
+### Changed
+
+- **`scripts/check_deps.py` declares Python >= 3.11**, up from a `min_version`
+  of `3.8` that never matched what the scripts actually needed, and its reason
+  string calls out the macOS 3.9 trap.
+- **Requirements are documented.** README gained a Requirements note above the
+  install snippet; `CLAUDE.md` records the three places the floor is declared
+  (`bin/ai-toolkit.js`, `scripts/_common.py`, `scripts/check_deps.py`) and the
+  CI matrix that guards it.
+
+### Ecosystem
+
+- Snapshot refreshed: 11 tools drifted, all class A (content reworded, no
+  heading delta). Claude Code 2.1.235 → 2.1.238 and Codex CLI 0.147.0 → 0.148.0
+  are upstream patch bumps with no new surface, so no generator changed.
+
+### Tests
+
+- Three CLI regression tests: a stale `python3` shim exits 1 with the version
+  message, a missing `python3` exits 1 instead of crashing, and `help` still
+  works with no interpreter on PATH. Test count: 1637 → 1640.
+
+---
+
 ## v4.25.1 — npm advisories count again (2026-08-19)
 
 ### Fixed

package/README.md

@@ -6,18 +6,23 @@
 [![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-1637%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1645%20passing-success)](tests/)
 
-## What's New in v4.25.1
+## What's New in v4.27.0
 
-**v4.25.1** fixes the CVE scanner path exercised by the published-package smoke test:
+**v4.27.0** teaches `doctor` about a collision it used to report as healthy:
 
-- Legacy npm audit `advisories` are normalized alongside the modern
-  `vulnerabilities` response.
-- HIGH advisories now produce findings and the documented non-zero exit code
-  instead of a false clean result.
-- The post-release scanner fixture now exercises accessibility, SEO, HIPAA, and
-  a deliberately vulnerable npm dependency with their real CLI flags.
+- Uploading the Claude app plugin ZIP registers it under `~/.claude/plugins`,
+  which Claude Code reads too. The plugin then carries the same skills, agents,
+  and hooks as the global install.
+- Claude Code merges plugin hooks with user hooks without deduplication, so
+  every toolkit hook fired twice per event and skills and agents loaded twice.
+  `doctor` printed `HEALTH CHECK PASSED` through all of it.
+- New check 11 reports the collision with the hook count; `doctor --fix`
+  disables the plugin for Claude Code and leaves the global install
+  authoritative.
+- `kb/troubleshooting/plugin-double-load.md` documents the debug-log evidence
+  and the verification steps.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -40,6 +45,10 @@ See [CHANGELOG.md](CHANGELOG.md) for full history.
 
 ## Install
 
+**Requirements:** Node.js >= 18 and Python >= 3.11.
+
+> **macOS:** `/usr/bin/python3` is Python 3.9 and will not run the toolkit. Install a supported one with `brew install python@3.13` and make sure `which python3` no longer points at `/usr/bin/python3`.
+
 ```bash
 # Option A: install globally (once per machine)
 npm install -g @softspark/ai-toolkit
@@ -183,7 +192,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats and Python test suite (1637 tests)
+├── tests/               # Bats and Python test suite (1645 tests)
 └── CHANGELOG.md
 ```
 

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

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-08-19T14:01:09Z",
+  "last_run": "2026-08-21T15:52:27Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "0f7df1fdf4962938",
+      "docs_hash": "516d8db28cb3ec63",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "5bba2a625b109b69",
+      "docs_hash": "cacc8b579baa5e86",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -107,7 +107,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "3d4394d0bf5dd8c1",
+      "docs_hash": "2b3d6b11c4be766f",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -173,10 +173,10 @@
         "userConfig": false,
         "workflows": true
       },
-      "version": "2.1.235 (Claude Code)"
+      "version": "2.1.238 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "bf058b01d03e0455",
+      "docs_hash": "f93d3a8437c1165f",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -223,7 +223,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "61aea7a06c8c6355",
+      "docs_hash": "df3b133739abfa24",
       "headings": [
         "API",
         "API Reference",
@@ -362,10 +362,10 @@
         "plugin marketplace": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.147.0"
+      "version": "codex-cli 0.148.0"
     },
     "cursor": {
-      "docs_hash": "793ca4e25e676e17",
+      "docs_hash": "2abfadb030c12d07",
       "headings": [
         "Agent",
         "CLI",
@@ -397,7 +397,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "f343c5f7c60fefcf",
+      "docs_hash": "c66bb0647b70c7cf",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -438,7 +438,7 @@
       "version": "0.55.1"
     },
     "github-copilot": {
-      "docs_hash": "79d741f4e3273f8d",
+      "docs_hash": "2e595a058e906644",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -502,7 +502,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "b112229db465d2e4",
+      "docs_hash": "3e9f45631e71a28c",
       "headings": [
         "Add features",
         "Ask questions",
@@ -564,7 +564,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "fddce54b82ac479e",
+      "docs_hash": "b08c4f883c276129",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -12,6 +12,9 @@ const fs = require('fs');
 const TOOLKIT_DIR = path.dirname(__dirname);
 const CWD = process.cwd();
 
+/** Minimum Python the toolkit scripts require: [major, minor]. */
+const PYTHON_MIN = [3, 11];
+
 if (!process.env.HOME) {
   console.error('Error: HOME environment variable is not set');
   process.exit(1);
@@ -139,6 +142,60 @@ function scriptPath(scriptName) {
   return path.join(TOOLKIT_DIR, 'scripts', scriptName);
 }
 
+/** Memoized result of requirePython(); null until the first check runs. */
+let pythonOk = null;
+
+/**
+ * Verify `python3` exists and is >= PYTHON_MIN before any script is spawned.
+ * Without this the caller sees a raw traceback from deep inside scripts/
+ * (e.g. `dataclass() got an unexpected keyword argument 'slots'` on Python
+ * 3.9, which is what macOS ships as /usr/bin/python3).
+ * Exits with an actionable message when the interpreter is missing or too old.
+ */
+function requirePython() {
+  if (pythonOk) return;
+  const probe = spawnSync('python3', ['-c', 'import sys; sys.stdout.write("%d.%d.%d" % sys.version_info[:3])'], {
+    encoding: 'utf8',
+  });
+  const want = PYTHON_MIN.join('.');
+
+  if (probe.error || probe.status !== 0) {
+    console.error(`Error: python3 not found on PATH — ai-toolkit requires Python >= ${want}`);
+    console.error(pythonHint());
+    process.exit(1);
+  }
+
+  const found = probe.stdout.trim();
+  const [major, minor] = found.split('.').map(Number);
+  if (major < PYTHON_MIN[0] || (major === PYTHON_MIN[0] && minor < PYTHON_MIN[1])) {
+    console.error(`Error: ai-toolkit requires Python >= ${want}, found ${found}`);
+    console.error(pythonHint());
+    process.exit(1);
+  }
+  pythonOk = true;
+}
+
+/**
+ * Platform-specific instructions for installing a supported Python.
+ * @returns {string} Multi-line hint text
+ */
+function pythonHint() {
+  const lines = [];
+  if (process.platform === 'darwin') {
+    lines.push('macOS ships Python 3.9 as /usr/bin/python3. Install a newer one:');
+    lines.push('  brew install python@3.13');
+    lines.push('Then make sure it comes first on PATH (`which python3` should not be /usr/bin/python3).');
+  } else if (process.platform === 'win32') {
+    lines.push('Install Python 3.11+ and make sure `python3` resolves to it:');
+    lines.push('  winget install Python.Python.3.13');
+  } else {
+    lines.push('Install Python 3.11+ via your package manager, e.g.:');
+    lines.push('  sudo apt install python3.13    # Debian/Ubuntu');
+    lines.push('  sudo dnf install python3.13    # Fedora/RHEL');
+  }
+  return lines.join('\n');
+}
+
 /**
  * Execute a generator script synchronously via python3, returning its stdout.
  * Exits the process on failure.
@@ -147,6 +204,7 @@ function scriptPath(scriptName) {
  * @returns {Buffer} stdout output
  */
 function runGenerator(scriptName, extraArgs = []) {
+  requirePython();
   try {
     return execFileSync('python3', [scriptPath(scriptName), ...extraArgs], { cwd: TOOLKIT_DIR });
   } catch (err) {
@@ -162,6 +220,7 @@ function runGenerator(scriptName, extraArgs = []) {
  * @param {{ cwd?: string }} [opts={}] - Options (cwd override)
  */
 function run(script, args = [], opts = {}) {
+  requirePython();
   const result = spawnSync('python3', [script, ...args], {
     stdio: 'inherit',
     cwd: opts.cwd || CWD,
@@ -178,6 +237,7 @@ function run(script, args = [], opts = {}) {
  * @param {...string} flags - Flags to pass: --rules, --hooks, --mcp
  */
 function propagateGlobal(...flags) {
+  requirePython();
   const result = spawnSync('python3', [scriptPath('propagate_global.py'), ...flags], {
     stdio: 'inherit',
     cwd: CWD,

package/kb/best-practices/README.md

@@ -4,6 +4,7 @@ service: ai-toolkit
 category: best-practices
 tags: [best-practices, guidelines]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit best-practices. No documents are filed here yet; new ones follow the best-practices template."
 ---
 
 # Best Practices

package/kb/howto/README.md

@@ -4,6 +4,7 @@ service: ai-toolkit
 category: howto
 tags: [howto, guides]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit howto. No documents are filed here yet; new ones follow the howto template."
 ---
 
 # How-To Guides

package/kb/troubleshooting/README.md

@@ -3,9 +3,12 @@ title: "Troubleshooting"
 service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
-last_updated: "2026-03-25"
+last_updated: "2026-08-21"
+description: "Section index for ai-toolkit troubleshooting, covering the Claude app plugin double-load collision."
 ---
 
 # Troubleshooting
 
-Problem resolution guides. Guides will be added here as they are created.
+Problem resolution guides.
+
+- [Claude App Plugin Loads Twice in Claude Code](plugin-double-load.md) -- hooks fire twice after the plugin ZIP is uploaded next to a global install.

package/kb/troubleshooting/plugin-double-load.md

@@ -0,0 +1,97 @@
+---
+title: "Claude App Plugin Loads Twice in Claude Code"
+category: troubleshooting
+service: ai-toolkit
+tags: [plugin, claude-app, hooks, duplication, doctor]
+created: "2026-08-21"
+last_updated: "2026-08-21"
+description: "Every toolkit hook fires twice and skills and agents load twice after the Claude app plugin ZIP is uploaded on a machine that already has the global install. Cause: the app registers the plugin under ~/.claude/plugins, which Claude Code also reads."
+---
+
+# Claude App Plugin Loads Twice in Claude Code
+
+## Symptom
+
+After uploading `ai-toolkit-claude-app.zip` through `Customize > Plugins`, Claude
+Code sessions get slower and every hook side effect appears twice: duplicate rows
+in `governance.log`, duplicate session state writes, two Stop gates per turn.
+`ai-toolkit doctor` reports a healthy install because it only inspected
+`~/.claude` and `app/plugins`.
+
+## Cause
+
+The Claude app writes uploaded plugins into
+`~/.claude/plugins/marketplaces/local-desktop-app-uploads/` and sets
+`enabledPlugins` in `~/.claude/settings.json`. Both paths belong to Claude Code
+as well, so Claude Code loads the plugin on top of the global install. The
+bundle carries the same catalog as `~/.claude`, and plugin hooks merge with user
+hooks without deduplication.
+
+Confirmed in a Claude Code debug log (`claude --debug -p ...`, then read
+`~/.claude/debug/latest`):
+
+```
+Loaded 111 unique skills (... user: 111 ...)
+Total plugin skills loaded: 111 (0 duplicate/user-owned entries skipped)
+Total plugin agents loaded: 44
+Read manifest hooks for plugin ai-toolkit (enabled=true): ./claude-app/hooks/hooks.json
+```
+
+The `skills` manifest field adds to the default `skills/` directory instead of
+replacing it, so the plugin contributes its 109 catalog skills plus the 2
+app-only rule skills.
+
+## Diagnosis
+
+```bash
+ai-toolkit doctor
+```
+
+Check 11 reports the collision:
+
+```
+## 11. Plugin Double-Load
+  WARN: ai-toolkit@local-desktop-app-uploads is active next to the global install: 28 toolkit hooks fire twice per event and skills/agents load twice (run: ai-toolkit doctor --fix)
+```
+
+To see the duplication directly, count hook invocations per source in a fresh
+session log:
+
+```bash
+grep -oE "[^\"' ]*hooks/[a-z0-9._-]+\.sh" ~/.claude/debug/latest | sort | uniq -c
+```
+
+## Fix
+
+```bash
+ai-toolkit doctor --fix
+```
+
+That sets the plugin to `false` in `enabledPlugins` and leaves the global
+install authoritative. Claude Code then logs
+`enabled=false; will NOT register, plugin is disabled`, and plugin skills and
+agents drop to 0.
+
+The global install is the richer surface for Claude Code: it delivers rules as
+real files under `~/.claude/rules/`, which are always in context, while the
+plugin exposes them as an `ai-toolkit-rules` skill the model has to load. The
+plugin also has no `session-context.sh` hook.
+
+Keep the plugin enabled only when Claude Code has no global install, for example
+a machine that runs the Claude app alone. In that case the plugin is the single
+source and check 11 stays quiet.
+
+## Verification
+
+```bash
+claude --debug -p "ok"
+grep -E "Total plugin (skills|agents) loaded|enabled=" ~/.claude/debug/latest
+```
+
+Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
+`plugin is disabled` line.
+
+## Related
+
+- `kb/reference/global-install-model.md`
+- `kb/procedures/maintenance-sop.md`

package/llms-full.txt

@@ -73,6 +73,7 @@
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
+- [Claude App Plugin Loads Twice in Claude Code](kb/troubleshooting/plugin-double-load.md)
 
 ## Skills
 
@@ -243,6 +244,7 @@ service: ai-toolkit
 category: best-practices
 tags: [best-practices, guidelines]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit best-practices. No documents are filed here yet; new ones follow the best-practices template."
 ---
 
 # Best Practices
@@ -5081,6 +5083,7 @@ service: ai-toolkit
 category: howto
 tags: [howto, guides]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit howto. No documents are filed here yet; new ones follow the howto template."
 ---
 
 # How-To Guides
@@ -16128,12 +16131,117 @@ title: "Troubleshooting"
 service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
-last_updated: "2026-03-25"
+last_updated: "2026-08-21"
+description: "Section index for ai-toolkit troubleshooting, covering the Claude app plugin double-load collision."
 ---
 
 # Troubleshooting
 
-Problem resolution guides. Guides will be added here as they are created.
+Problem resolution guides.
+
+- [Claude App Plugin Loads Twice in Claude Code](plugin-double-load.md) -- hooks fire twice after the plugin ZIP is uploaded next to a global install.
+
+---
+
+## kb/troubleshooting/plugin-double-load.md
+
+---
+title: "Claude App Plugin Loads Twice in Claude Code"
+category: troubleshooting
+service: ai-toolkit
+tags: [plugin, claude-app, hooks, duplication, doctor]
+created: "2026-08-21"
+last_updated: "2026-08-21"
+description: "Every toolkit hook fires twice and skills and agents load twice after the Claude app plugin ZIP is uploaded on a machine that already has the global install. Cause: the app registers the plugin under ~/.claude/plugins, which Claude Code also reads."
+---
+
+# Claude App Plugin Loads Twice in Claude Code
+
+## Symptom
+
+After uploading `ai-toolkit-claude-app.zip` through `Customize > Plugins`, Claude
+Code sessions get slower and every hook side effect appears twice: duplicate rows
+in `governance.log`, duplicate session state writes, two Stop gates per turn.
+`ai-toolkit doctor` reports a healthy install because it only inspected
+`~/.claude` and `app/plugins`.
+
+## Cause
+
+The Claude app writes uploaded plugins into
+`~/.claude/plugins/marketplaces/local-desktop-app-uploads/` and sets
+`enabledPlugins` in `~/.claude/settings.json`. Both paths belong to Claude Code
+as well, so Claude Code loads the plugin on top of the global install. The
+bundle carries the same catalog as `~/.claude`, and plugin hooks merge with user
+hooks without deduplication.
+
+Confirmed in a Claude Code debug log (`claude --debug -p ...`, then read
+`~/.claude/debug/latest`):
+
+```
+Loaded 111 unique skills (... user: 111 ...)
+Total plugin skills loaded: 111 (0 duplicate/user-owned entries skipped)
+Total plugin agents loaded: 44
+Read manifest hooks for plugin ai-toolkit (enabled=true): ./claude-app/hooks/hooks.json
+```
+
+The `skills` manifest field adds to the default `skills/` directory instead of
+replacing it, so the plugin contributes its 109 catalog skills plus the 2
+app-only rule skills.
+
+## Diagnosis
+
+```bash
+ai-toolkit doctor
+```
+
+Check 11 reports the collision:
+
+```
+## 11. Plugin Double-Load
+  WARN: ai-toolkit@local-desktop-app-uploads is active next to the global install: 28 toolkit hooks fire twice per event and skills/agents load twice (run: ai-toolkit doctor --fix)
+```
+
+To see the duplication directly, count hook invocations per source in a fresh
+session log:
+
+```bash
+grep -oE "[^\"' ]*hooks/[a-z0-9._-]+\.sh" ~/.claude/debug/latest | sort | uniq -c
+```
+
+## Fix
+
+```bash
+ai-toolkit doctor --fix
+```
+
+That sets the plugin to `false` in `enabledPlugins` and leaves the global
+install authoritative. Claude Code then logs
+`enabled=false; will NOT register, plugin is disabled`, and plugin skills and
+agents drop to 0.
+
+The global install is the richer surface for Claude Code: it delivers rules as
+real files under `~/.claude/rules/`, which are always in context, while the
+plugin exposes them as an `ai-toolkit-rules` skill the model has to load. The
+plugin also has no `session-context.sh` hook.
+
+Keep the plugin enabled only when Claude Code has no global install, for example
+a machine that runs the Claude app alone. In that case the plugin is the single
+source and check 11 stays quiet.
+
+## Verification
+
+```bash
+claude --debug -p "ok"
+grep -E "Total plugin (skills|agents) loaded|enabled=" ~/.claude/debug/latest
+```
+
+Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
+`plugin is disabled` line.
+
+## Related
+
+- `kb/reference/global-install-model.md`
+- `kb/procedures/maintenance-sop.md`
 
 ---
 

package/llms.txt

@@ -73,3 +73,4 @@
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
+- [Claude App Plugin Loads Twice in Claude Code](kb/troubleshooting/plugin-double-load.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.25.1",
+  "version": "4.27.0",
   "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.25.1",
+  "version": "4.27.0",
   "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/_common.py

@@ -20,8 +20,35 @@ from __future__ import annotations
 import os
 import platform
 import shutil
+import sys
 from pathlib import Path
 
+# ---------------------------------------------------------------------------
+# Python version floor
+# ---------------------------------------------------------------------------
+# Kept in sync with PYTHON_MIN in bin/ai-toolkit.js and the python3 entry in
+# scripts/check_deps.py. Checked here because _common is imported first by
+# every entry point, so a stale interpreter fails with this message instead of
+# a traceback from whichever module happens to use 3.11+ syntax.
+PYTHON_MIN = (3, 11)
+
+if sys.version_info < PYTHON_MIN:
+    _want = ".".join(str(n) for n in PYTHON_MIN)
+    _found = ".".join(str(n) for n in sys.version_info[:3])
+    sys.stderr.write(
+        "Error: ai-toolkit requires Python >= {}, found {} ({})\n".format(
+            _want, _found, sys.executable
+        )
+    )
+    if sys.platform == "darwin":
+        sys.stderr.write(
+            "macOS ships Python 3.9 as /usr/bin/python3. Install a newer one:\n"
+            "  brew install python@3.13\n"
+        )
+    else:
+        sys.stderr.write("Install Python 3.11+ via your package manager.\n")
+    sys.exit(1)
+
 # ---------------------------------------------------------------------------
 # Re-exports from frontmatter module
 # ---------------------------------------------------------------------------

package/scripts/check_deps.py

@@ -33,7 +33,7 @@ REQUIRED = [
     {
         "name": "python3",
         "check": "python3",
-        "min_version": "3.8",
+        "min_version": "3.11",
         "packages": {
             "brew": "python3",
             "apt": "python3",
@@ -45,7 +45,7 @@ REQUIRED = [
             "choco": "python",
             "scoop": "python",
         },
-        "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
+        "reason": "All toolkit scripts run on Python 3.11+ (stdlib only, no pip needed). macOS /usr/bin/python3 is 3.9 and will not work.",
     },
     {
         "name": "git",

package/scripts/doctor.py

@@ -15,6 +15,8 @@ Checks:
   7. Benchmark freshness
   8. Stale rules
   9. URL hook sources
+  10. Language rules drift (project-local)
+  11. Plugin double-load (Claude app plugin vs global install)
 
 Exit codes:
   0  all checks pass
@@ -44,6 +46,7 @@ HOOKS_DIR = _HOOKS_DIR
 RULES_DIR = _RULES_DIR
 EXTERNAL_HOOKS_DIR = _EXTERNAL_HOOKS_DIR
 BENCHMARK_DASHBOARD = toolkit_dir / "benchmarks" / "ecosystem-dashboard.json"
+PLUGIN_REGISTRY = CLAUDE_DIR / "plugins" / "installed_plugins.json"
 
 VALID_EVENTS = frozenset({
     "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
@@ -668,6 +671,84 @@ def check_language_drift(dr: DiagResult) -> None:
         dr.warn(f"{lang} detected but {skill} not injected — run: ai-toolkit install --local --lang {lang}")
 
 
+# ---------------------------------------------------------------------------
+# Check 11: Plugin Double-Load
+# ---------------------------------------------------------------------------
+
+def _registered_toolkit_plugins(registry: dict) -> list[str]:
+    """Return ai-toolkit plugin keys from the Claude Code plugin registry."""
+    plugins = registry.get("plugins", {})
+    if not isinstance(plugins, dict):
+        return []
+    return [key for key in plugins if str(key).split("@", 1)[0] == "ai-toolkit"]
+
+
+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.
+
+    Uploading the ``claude-app export`` ZIP from the Claude app registers it under
+    ``~/.claude/plugins``, which Claude Code reads as well. The plugin carries the
+    same skills, agents, and hooks as the global install, and Claude Code merges
+    plugin hooks with user hooks without deduplication, so every toolkit hook runs
+    twice per event.
+    """
+    print()
+    print("## 11. Plugin Double-Load")
+
+    if not PLUGIN_REGISTRY.is_file():
+        dr.skip("no Claude Code plugin registry")
+        return
+    try:
+        registry = json.loads(PLUGIN_REGISTRY.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        dr.warn(f"{PLUGIN_REGISTRY} is not valid JSON")
+        return
+
+    keys = _registered_toolkit_plugins(registry)
+    if not keys:
+        dr.ok("no ai-toolkit plugin registered in Claude Code")
+        return
+
+    settings_json = CLAUDE_DIR / "settings.json"
+    try:
+        settings = json.loads(settings_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        settings = {}
+    enabled = settings.get("enabledPlugins", {})
+    if not isinstance(enabled, dict):
+        enabled = {}
+
+    active = [key for key in keys if enabled.get(key, True)]
+    if not active:
+        dr.ok("ai-toolkit plugin registered but disabled for Claude Code")
+        return
+
+    hook_count, _ = _installed_toolkit_hook_count(settings)
+    if hook_count == 0:
+        dr.ok("ai-toolkit plugin active without global hooks (single source)")
+        return
+
+    for key in active:
+        dr.warn(
+            f"{key} is active next to the global install: {hook_count} toolkit hooks "
+            "fire twice per event and skills/agents load twice "
+            "(run: ai-toolkit doctor --fix)"
+        )
+
+    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")
+    except OSError as exc:
+        dr.fail(f"could not disable plugin in settings.json: {exc}")
+        return
+    for key in active:
+        dr.fixed(f"disabled {key} for Claude Code (global install stays authoritative)")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -691,6 +772,7 @@ def main() -> None:
     check_stale_rules(dr, fix_mode)
     check_url_hooks(dr, fix_mode)
     check_language_drift(dr)
+    check_plugin_double_load(dr, fix_mode)
 
     # Summary
     print("========================")