@softspark/ai-toolkit 4.25.1 → 4.26.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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,19 @@
 [![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-1640%20passing-success)](tests/)
 
-## What's New in v4.25.1
+## What's New in v4.26.0
 
-**v4.25.1** fixes the CVE scanner path exercised by the published-package smoke test:
+**v4.26.0** declares and enforces the Python floor the scripts already needed:
 
-- 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.
+- `ai-toolkit` now checks `python3` before running anything and requires 3.11+.
+- macOS `/usr/bin/python3` is 3.9, which used to crash `update --local` with a
+  raw `dataclass() got an unexpected keyword argument 'slots'` traceback. You
+  now get the version, the requirement, and `brew install python@3.13`.
+- `python3 scripts/*.py` run directly fails the same way, via `_common.py`.
+- CI runs the syntax check plus a full import sweep on both 3.11 and 3.13, so a
+  version-gated runtime feature cannot slip through `py_compile` again.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -40,6 +41,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 +188,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 (1640 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.26.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-21T08:34:52Z",
   "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": "7e06a1985d5bb822",
       "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": "fc1c7e43bec9f748",
       "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": "a2c9759e0296670d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -438,7 +438,7 @@
       "version": "0.55.1"
     },
     "github-copilot": {
-      "docs_hash": "79d741f4e3273f8d",
+      "docs_hash": "ab9b7f5b4b692e05",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -475,7 +475,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "8cbf9aaffb6b57bf",
+      "docs_hash": "9fe532d247c3e361",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -502,7 +502,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "b112229db465d2e4",
+      "docs_hash": "4287f7d767dda4a8",
       "headings": [
         "Add features",
         "Ask questions",
@@ -564,7 +564,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "fddce54b82ac479e",
+      "docs_hash": "60e25f8cb4c381be",
       "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

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

package/llms-full.txt

@@ -243,6 +243,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 +5082,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
@@ -16129,6 +16131,7 @@ service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit troubleshooting. No documents are filed here yet; new ones follow the troubleshooting template."
 ---
 
 # Troubleshooting

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.25.1",
+  "version": "4.26.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.26.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",