@softspark/ai-toolkit 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.9.0 — Project Registry & Doc Sync (2026-04-12)
+
+### Added
+- **Project registry** — `install --local` automatically registers project path in `~/.ai-toolkit/projects.json`. `ai-toolkit update` propagates updates to all registered projects in parallel via `ThreadPoolExecutor`
+- **`ai-toolkit projects`** — list registered projects, `--prune` to remove stale (deleted directories), `remove <path>` to unregister specific project
+- **Parallel update propagation** — `ai-toolkit update` (global) now auto-updates all registered local projects concurrently (max 8 workers)
+
+### Fixed
+- **README.md** — skill count 91→92 in comparison table, added Augment/Antigravity to cross-tool tables, fixed Notification hook description (inline→`notify-waiting.sh`)
+- **README.md** — added Config Inheritance section, Project Registry section, 6 new CLI commands to reference table
+- **ARCHITECTURE.md** — added Config Inheritance and Project Registry to Extension Points
+- **CLAUDE.md** — added `config` and `projects` commands
+
+---
+
+## v1.8.0 — Enterprise Config Inheritance (2026-04-12)
+
+### Added
+- **Configuration inheritance system** — `extends` pattern (like ESLint/TypeScript) for multi-repo AI governance. Organizations define a shared base config published as npm package, git URL, or local path; projects inherit via `.ai-toolkit.json`
+- **`ai-toolkit config validate`** — schema validation + extends resolution + enforcement check
+- **`ai-toolkit config diff`** — visual diff of project vs base config (profile, agents, rules, constitution, overrides)
+- **`ai-toolkit config init`** — interactive or flag-driven `.ai-toolkit.json` creation with extends validation
+- **`ai-toolkit config create-base`** — scaffolds ready-to-publish npm base config package (package.json, ai-toolkit.config.json, rules/, agents/, README)
+- **`ai-toolkit config check`** — CI enforcement gate with JSON output and exit codes (0=pass, 1=fail, 2=no config)
+- **Merge engine** — layered deep merge (base → project) with special handling for agents (requiredAgents enforcement), rules (union), constitution (immutability), enforce blocks (cannot weaken)
+- **Constitution immutability guard** — Articles I-V absolutely immutable; base config articles immutable; projects can only ADD new articles (6+)
+- **Override validation** — `override: true` + justification (min 20 chars) required; `forbidOverride` enforcement
+- **Enforce constraints** — 4 types: `minHookProfile`, `requiredPlugins`, `forbidOverride`, `requiredAgents`
+- **Lock file** (`.ai-toolkit.lock.json`) — pins resolved base config versions for reproducible installs across team; generated on `install --local`, updated on `update --local`
+- **Audit trail** — extends metadata recorded in `state.json` and `.ai-toolkit-extends.json`
+- **Offline fallback** — uses cached configs from `~/.ai-toolkit/config-cache/` when registry unavailable
+- **Cycle detection** — max 5-level extends chain with circular reference detection
+- **Install integration** — `install --local` and `update --local` auto-detect `.ai-toolkit.json`, resolve extends, merge, validate, inject rules + constitution amendments into generated files
+- **New CLI flags** — `--config <path>` (explicit config file), `--refresh-base` (force re-fetch)
+- **JSON Schema** — `scripts/schemas/ai-toolkit-config.schema.json` for editor autocompletion
+- **Enterprise config guide** — `kb/reference/enterprise-config-guide.md` comprehensive documentation
+- **52 new tests** — resolver (7), merger (13), CLI (23), install integration (9)
+
+### Changed
+- **`manifest.json`** — added `config_inheritance` section with schema references and v1 field list
+
+---
+
 ## v1.7.0 — Offline-First SLM Compilation (2026-04-11)
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-512%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-575%20passing-success)](tests/)
 
 ---
 
@@ -318,7 +318,7 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
 | SessionStart | `session-context.sh` | Capture environment snapshot (pwd, git branch, versions) to `~/.ai-toolkit/sessions/current-context.json` |
-| Notification | *(inline)* | macOS desktop notification |
+| Notification | `notify-waiting.sh` | Cross-platform desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |
 | PreToolUse | `guard-config.sh` | Block edits to linter/formatter config files unless explicitly requested |
@@ -612,18 +612,62 @@ All packs have `status: experimental`. Each has a `plugin.json` manifest and `RE
 
 ---
 
+## Config Inheritance (`extends`)
+
+Enterprise-grade configuration inheritance for multi-repo AI governance. Organizations define a shared base config published as an npm package, Git URL, or local path. Projects inherit via `.ai-toolkit.json`:
+
+```json
+{
+  "extends": "@mycompany/ai-toolkit-config",
+  "profile": "standard"
+}
+```
+
+**Key capabilities:**
+- **Layered merge** — base config + project overrides, with deep merge for dicts, union for lists, project-wins for scalars
+- **Constitution immutability** — Articles I-V and base articles cannot be modified; projects can only ADD new articles (6+)
+- **Enforce constraints** — `requiredAgents`, `forbidOverride`, `minHookProfile`, `requiredPlugins`
+- **Override validation** — requires explicit `override: true` + justification (min 20 chars)
+- **Lock file** — `.ai-toolkit.lock.json` pins resolved versions for reproducible installs
+- **Offline fallback** — uses cached configs from `~/.ai-toolkit/config-cache/` when registry unavailable
+
+```bash
+ai-toolkit config create-base @mycompany/ai-toolkit-config  # scaffold base package
+ai-toolkit config init --extends @mycompany/ai-toolkit-config # setup project
+ai-toolkit config validate    # schema + extends + enforcement
+ai-toolkit config diff        # project vs base differences
+ai-toolkit config check       # CI enforcement gate (exit 0/1/2, --json)
+```
+
+See [Enterprise Config Guide](kb/reference/enterprise-config-guide.md) for full documentation.
+
+---
+
+## Project Registry
+
+All projects installed with `--local` are automatically registered in `~/.ai-toolkit/projects.json`. Running `ai-toolkit update` propagates updates to all registered projects in parallel.
+
+```bash
+ai-toolkit projects              # list registered projects
+ai-toolkit projects --prune      # remove stale (deleted) entries
+ai-toolkit projects remove /path # unregister specific project
+ai-toolkit update                # global update + parallel update ALL projects
+```
+
+---
+
 ## Comparison
 
 | Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
 |---------|---------------|----------------------|-----------------|-------|
-| Skills | 91 | 100+ | 146 | 20+ |
+| Skills | 92 | 100+ | 146 | 20+ |
 | Agents | 44 | 30+ | 112 | 20+ |
 | Machine-enforced constitution | **Yes** | No (docs only) | No | No |
 | Skill-scoped lifecycle hooks | **Yes** | No | No | No |
 | Effort-based model budgeting | **Yes** | No | No | No |
 | Test suite | Yes (bats) | Yes (997 tests) | No | Yes |
 | npm/npx install | Yes | Yes | Yes | Yes |
-| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Codex** | 5+ tools | Smithery | Limited |
+| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity** | 5+ tools | Smithery | Limited |
 | Selective install | Yes | Yes | Yes (72 plugins) | No |
 | Session persistence | Yes | Yes | No | No |
 | Architecture notes | **Yes** | No | No | No |
@@ -662,6 +706,8 @@ Pre-configured team presets via `/teams`:
 | Cline | `.clinerules` | project |
 | Roo Code | `.roomodes` | project |
 | Aider | `.aider.conf.yml` | project |
+| Augment | `.augment/rules/ai-toolkit-*.md` | project |
+| Google Antigravity | `.agent/rules/` + `.agent/workflows/` | project |
 | Codex / OpenCode | `AGENTS.md` | project |
 
 ```bash
@@ -764,8 +810,14 @@ Usage: ai-toolkit <command> [options]
 | `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
 | `mcp show <name>` | Show MCP template config details |
 | `mcp remove <name>` | Remove MCP server from `.mcp.json` |
+| `config validate [path]` | Validate `.ai-toolkit.json` schema + extends + enforcement |
+| `config diff [path]` | Show project vs base config differences |
+| `config init [flags]` | Create `.ai-toolkit.json` (`--extends`, `--profile`, `--no-extends`) |
+| `config create-base <name>` | Scaffold base config npm package |
+| `config check [path]` | CI enforcement gate (exit 0=pass, 1=fail, 2=no config; `--json`) |
+| `projects` | List registered projects (`--prune` to clean stale, `remove <path>`) |
 | `status` | Show installed modules and version |
-| `update` | Re-install with saved modules (incremental) |
+| `update` | Re-install with saved modules + update all registered projects |
 | `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
 | `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
 | `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -315,6 +315,12 @@ The `inject_section_cli.py` script provides a stable marker-based injection API.
 ### SLM Compilation (`compile-slm`)
 `scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).
 
+### Config Inheritance (`extends`)
+`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.ai-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-V absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.ai-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
+
+### Project Registry
+`scripts/install_steps/project_registry.py`, `scripts/update_projects.py`, `scripts/projects_cli.py`. Tracks all `--local` installed projects in `~/.ai-toolkit/projects.json`. `ai-toolkit update` propagates to all registered projects in parallel via `ThreadPoolExecutor`. CLI: `ai-toolkit projects`, `--prune`, `remove <path>`.
+
 ### Manifest Install (`--modules`, `--auto-detect`)
 `manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or let the installer detect which language rules to add based on project files (e.g. `package.json` → `rules-typescript`, `go.mod` → `rules-golang`).
 

package/bin/ai-toolkit.js

@@ -75,6 +75,8 @@ const COMMANDS = {
   stats: 'Show skill usage statistics (--reset to clear, --json for raw output)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
   mcp: 'Manage MCP server templates (list, show, add, remove)',
+  config: 'Manage config inheritance (validate, diff, init, create-base, check)',
+  projects: 'List and manage registered projects (--prune, remove <path>)',
   plugin: 'Manage plugin packs (install, remove, update, clean, list, status)',
   sync: 'Sync config to/from GitHub Gist (--export, --push, --pull, --import)',
   'cursor-rules': 'Generate .cursorrules for Cursor IDE (legacy)',
@@ -376,6 +378,17 @@ function handleMcp(args) {
   run(scriptPath('mcp_manager.py'), args);
 }
 
+/**
+ * Handle `ai-toolkit config <subcommand>` -- config inheritance management.
+ * @param {string[]} args - Subcommand and its arguments
+ */
+function handleConfig(args) {
+  if (args.length === 0) {
+    args = ['--help'];
+  }
+  run(scriptPath('config_cli.py'), args);
+}
+
 /**
  * Handle `ai-toolkit generate-all` -- runs every generator plus llms-txt.
  * @param {string[]} _args - Unused, kept for signature consistency
@@ -413,6 +426,7 @@ function handleStatus(_args) {
  * @param {string[]} args
  */
 function handleUpdate(args) {
+  const isLocal = args.includes('--local');
   const statePath = path.join(process.env.HOME, '.ai-toolkit', 'state.json');
   let stateArgs = [];
 
@@ -435,6 +449,27 @@ function handleUpdate(args) {
 
   // User-provided args override state-derived args
   run(scriptPath('install.py'), [...stateArgs, ...args]);
+
+  // After global update (not --local), propagate to all registered projects
+  if (!isLocal) {
+    const registryPath = path.join(process.env.HOME, '.ai-toolkit', 'projects.json');
+    if (fs.existsSync(registryPath)) {
+      try {
+        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+        const projects = registry.projects || [];
+        if (projects.length > 0) {
+          console.log('');
+          console.log('## Updating registered projects');
+          console.log('');
+          // Pass through --skip, --refresh-base flags to project updates
+          const passthrough = args.filter(a => a.startsWith('--skip') || a === '--refresh-base');
+          run(scriptPath('update_projects.py'), passthrough);
+        }
+      } catch (_err) {
+        // Registry corrupt -- skip project updates
+      }
+    }
+  }
 }
 
 /** @type {Record<string, (args: string[]) => void>} */
@@ -446,6 +481,8 @@ const SPECIAL_HANDLERS = {
   'create':       handleCreate,
   'sync':         handleSync,
   'mcp':          handleMcp,
+  'config':       handleConfig,
+  'projects':     (args) => run(scriptPath('projects_cli.py'), args),
   'plugin':       (args) => run(scriptPath('plugin.py'), args),
   'remove-rule':  handleRemoveRule,
   'add-rule':     handleAddRule,

package/kb/{planning/enterprise-config-inheritance-plan.md → history/completed/enterprise-config-inheritance-plan-20260412.md}

@@ -11,10 +11,10 @@ tags:
   - team-management
   - monorepo
 doc_type: plan
-status: proposed
+status: completed
 created: "2026-04-10"
-last_updated: "2026-04-10"
-completion: "0%"
+last_updated: "2026-04-11"
+completion: "100%"
 description: "Configuration inheritance system for ai-toolkit. Enables organizations to define a shared base config (agents, rules, hooks, profiles, constitution overrides) published as an npm package or local path, which individual projects extend via an `extends` field. Changes to the base config propagate automatically on `ai-toolkit update`. Targets enterprises managing 10-100+ repositories with uniform AI governance."
 ---
 
@@ -121,21 +121,21 @@ Merge Pipeline:
 
 | # | Feature | Priority | Status | Est. Time | Notes |
 |---|---------|----------|--------|-----------|-------|
-| 1.1 | `.ai-toolkit.json` schema definition | P0 | Proposed | 1d | JSON Schema with `extends` field |
-| 1.2 | Config resolver (npm, git, local path) | P0 | Proposed | 3d | Fetch + cache + validate base configs |
-| 1.3 | Merge engine (layered merge with override semantics) | P0 | Proposed | 3d | Deep merge with `override: true` gates |
-| 1.4 | Constitution immutability guard | P0 | Proposed | 1d | Block weakening of safety articles |
-| 2.1 | Install/update integration | P0 | Proposed | 2d | Resolve extends during install/update |
-| 2.2 | `ai-toolkit config diff` command | P0 | Proposed | 1.5d | Show project vs base differences — primary debugging tool |
-| 2.3 | `ai-toolkit config validate` command | P0 | Proposed | 1d | Validate .ai-toolkit.json schema + extends resolution |
-| 2.4 | `ai-toolkit config init` command | P1 | Proposed | 1.5d | Interactive project config setup |
-| 2.5 | `ai-toolkit config create-base` command | P1 | Proposed | 2d | Scaffold base config package |
-| 3.1 | Audit trail in state.json | P1 | Proposed | 1d | Record resolved config provenance |
-| 3.2 | Lock file (`.ai-toolkit.lock.json`) | P1 | Proposed | 1.5d | Pin resolved versions for reproducibility |
-| 3.3 | Base config scaffolder (npm package template) | P1 | Proposed | 1.5d | Ready-to-publish template |
-| 3.4 | CI enforcement (`ai-toolkit config check`) | P2 | Proposed | 1d | Verify project adheres to base + no unapproved overrides |
-| 4.1 | Tests | P1 | Proposed | 3d | Unit: resolution, merge, immutability, override, CLI commands. Integration: `install --local` with `.ai-toolkit.json` containing `extends`, verify resolved `CLAUDE.md` has base + project rules merged end-to-end |
-| 4.2 | Documentation | P1 | Proposed | 3d | Enterprise setup guide + all 9 docs per CLAUDE.md: README, CLAUDE.md, ARCHITECTURE.md, package.json, llms.txt, llms-full.txt, AGENTS.md, skills-catalog.md, architecture-overview.md |
+| 1.1 | `.ai-toolkit.json` schema definition | P0 | **Done** | 1d | `scripts/schemas/ai-toolkit-config.schema.json` |
+| 1.2 | Config resolver (npm, git, local path) | P0 | **Done** | 3d | `scripts/config_resolver.py` (~330 LOC) |
+| 1.3 | Merge engine (layered merge with override semantics) | P0 | **Done** | 3d | `scripts/config_merger.py` (~340 LOC) |
+| 1.4 | Constitution immutability guard | P0 | **Done** | 1d | In config_merger.py `_merge_constitution()` |
+| 2.1 | Install/update integration | P0 | **Done** | 2d | `install.py` + `ai_tools.py` — auto-detect, resolve, merge, inject |
+| 2.2 | `ai-toolkit config diff` command | P0 | **Done** | 1.5d | `scripts/config_cli.py` `cmd_diff()` |
+| 2.3 | `ai-toolkit config validate` command | P0 | **Done** | 1d | `scripts/config_cli.py` `cmd_validate()` |
+| 2.4 | `ai-toolkit config init` command | P1 | **Done** | 1.5d | Interactive + flag-driven, validates extends |
+| 2.5 | `ai-toolkit config create-base` command | P1 | **Done** | 2d | `scripts/config_scaffold.py` — full npm package scaffold |
+| 3.1 | Audit trail in state.json | P1 | **Done** | 1d | `install_state.py` extends field + `.ai-toolkit-extends.json` |
+| 3.2 | Lock file (`.ai-toolkit.lock.json`) | P1 | **Done** | 1.5d | `scripts/config_lock.py` — generate/consume/staleness check |
+| 3.3 | Base config scaffolder (npm package template) | P1 | **Done** | 1.5d | Part of `config_scaffold.py` `create_base_package()` |
+| 3.4 | CI enforcement (`ai-toolkit config check`) | P2 | **Done** | 1d | `config_cli.py` `cmd_check()` — JSON output, exit codes |
+| 4.1 | Tests | P1 | **Done** | 3d | 39 tests: resolver (7), merger (13), CLI (10), install integration (9) |
+| 4.2 | Documentation | P1 | **Done** | 3d | `kb/reference/enterprise-config-guide.md` — comprehensive guide |
 
 **Phasing (MVP-first):**
 - **MVP Phase 1 (week 1-2):** Core engine — schema (1.1), resolver (1.2), merge engine (1.3), constitution guard (1.4)
@@ -864,25 +864,27 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 ## 11. Next Actions
 
 **MVP (ship first, ~3.5 weeks):**
-1. [ ] Approve plan
-2. [ ] Define `.ai-toolkit.json` JSON Schema — v1 scope only (1.1)
-3. [ ] Implement config resolver (npm, git, local) with caching (1.2)
-4. [ ] Implement merge engine with override validation (1.3)
-5. [ ] Implement constitution immutability guard (1.4)
-6. [ ] Integrate into install.py flow (2.1)
-7. [ ] Create `config diff` viewer (2.2) — primary debugging tool
-8. [ ] Create `config validate` checker (2.3)
-9. [ ] Tests for above (4.1 partial)
-10. [ ] **Ship MVP → announce → measure adoption**
-
-**Post-MVP (if demand validated):**
-11. [ ] Create `config init` interactive command (2.4)
-12. [ ] Create `config create-base` scaffolder (2.5)
-13. [ ] Add audit trail to state.json (3.1)
-14. [ ] Implement lock file generation + resolution (3.2)
-15. [ ] Create base config npm package template (3.3)
-16. [ ] Create CI enforcement command `config check` (3.4)
-17. [ ] Full tests + documentation — all 9 docs per CLAUDE.md (4.1, 4.2)
+1. [x] Approve plan
+2. [x] Define `.ai-toolkit.json` JSON Schema — v1 scope only (1.1)
+3. [x] Implement config resolver (npm, git, local) with caching (1.2)
+4. [x] Implement merge engine with override validation (1.3)
+5. [x] Implement constitution immutability guard (1.4)
+6. [x] Integrate into install.py flow (2.1)
+7. [x] Create `config diff` viewer (2.2) — primary debugging tool
+8. [x] Create `config validate` checker (2.3)
+9. [x] Tests for above (4.1 partial)
+10. [x] **Ship MVP → announce → measure adoption**
+
+**Post-MVP:**
+11. [x] Create `config init` interactive command (2.4)
+12. [x] Create `config create-base` scaffolder (2.5)
+13. [x] Add audit trail to state.json (3.1)
+14. [x] Implement lock file generation + resolution (3.2)
+15. [x] Create base config npm package template (3.3)
+16. [x] Create CI enforcement command `config check` (3.4)
+17. [x] Full tests + documentation (4.1, 4.2)
+
+**All 17 items completed — 2026-04-11.**
 
 ---