@softspark/ai-toolkit 4.30.3 → 4.31.0

package/llms-full.txt

@@ -32,11 +32,12 @@
 - [Closed: Tool-Output Token Reduction](kb/history/completed/tool-output-token-reduction-closed-20260727.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
-- [SOP: Ecosystem Sync](kb/procedures/ecosystem-sync-sop.md)
-- [SOP: AI Toolkit Maintenance](kb/procedures/maintenance-sop.md)
-- [SOP: Post-Release Testing](kb/procedures/post-release-testing-sop.md)
-- [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
-- [SOP: Release Verification](kb/procedures/release-verification-sop.md)
+- [SOP: Ecosystem Sync](kb/procedures/sop-ecosystem-sync.md)
+- [SOP: AI Toolkit Maintenance](kb/procedures/sop-maintenance.md)
+- [SOP: Post-Release Testing](kb/procedures/sop-post-release-testing.md)
+- [SOP: Pre-Commit Gate](kb/procedures/sop-pre-commit.md)
+- [SOP: Release Verification](kb/procedures/sop-release-verification.md)
+- [SOP: Release Preparation](kb/procedures/sop-release.md)
 - [Agents Catalog](kb/reference/agents-catalog.md)
 - [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
 - [AI Toolkit Architecture](kb/reference/architecture-overview.md)
@@ -95,6 +96,7 @@
 - **chaos**: Injects controlled faults for resilience testing on non-prod. Triggers: chaos, fault injection, latency injection, dependency kill, resilience test.
 - **ci**: Detect/generate/debug CI pipeline config (GitHub Actions, GitLab CI). Triggers: CI setup, build pipeline, GitHub Actions config, debug CI, GitLab CI.
 - **ci-cd-patterns**: CI/CD: GitHub Actions, GitLab CI, Jenkins, caching, blue-green, canary. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, release, canary, rollout.
+- **claude-toolkit-rules**: SoftSpark working agreement: never guess a home directory path, give at least three alternatives, and apply a devil's advocate critique to decisions. Triggers: toolkit, conventions, workflow, alternatives, review.
 - **clean-code**: Code quality: meaningful names, SRP, DRY, small functions, guard clauses, refactoring. Triggers: clean code, naming, code smell, SRP, DRY, long function, god class, dead code.
 - **command-creator**: Creates new Claude Code slash commands with frontmatter and validation. Triggers: new slash command, create command, command scaffold.
 - **commit**: Creates Conventional Commits with pre-commit validation. Triggers: commit, conventional commit, git commit, message.
@@ -115,12 +117,14 @@
 - **docs**: Generates/updates README, API docs, architecture notes. Triggers: docs, README, API docs, architecture note, documentation.
 - **documentation-standards**: KB conventions: YAML frontmatter, 10-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning/business/templates). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
 - **ecommerce-patterns**: E-commerce: cart, checkout, payments (Stripe/Adyen), order state, inventory, promos, tax. Triggers: cart, checkout, SKU, payment, Stripe, Shopify, Medusa, Magento, coupon, refund.
+- **edit-discipline**: Change files with the edit and write tools, never by rewriting them through bash (sed, awk, tee, heredoc, redirection), and show `git diff` before reporting a file-changing task as done. Triggers: edit, write, modify, refactor, patch, fix, diff, review changes.
 - **evaluate**: Evaluates RAG retrieval and LLM-as-judge metrics (faithfulness, relevancy, context precision). Triggers: measure RAG quality, knowledge gap, RAG eval, golden dataset.
 - **evolve**: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.
 - **explain**: Explains code/architecture with Mermaid diagrams and sequence flows. Triggers: what does X do, how does Y work, explain code, sequence diagram.
 - **explore**: Explores codebase structure, stack, and architecture. Triggers: explore codebase, project structure, stack overview, architecture map.
 - **fix**: Applies targeted fix to known bug/lint error, verifies with same command that surfaced it. Triggers: fix, apply fix, fix bug, fix lint, targeted fix.
 - **flutter-patterns**: Flutter/Dart: widgets, state mgmt (Riverpod/Bloc), navigation, platform channels. Triggers: Flutter, Dart, widget, Riverpod, Bloc, pubspec, hot reload.
+- **git-conventions**: Conventional Commits only (feat, fix, docs, refactor, test, chore); no AI co-authorship trailer and no AI signature in a commit message. Triggers: commit, git, message, changelog, release, pull request.
 - **git-mastery**: Advanced Git: rebase, bisect, reflog, cherry-pick, worktrees, LFS. Triggers: rebase, bisect, cherry-pick, reflog, force push, merge conflict, worktree.
 - **golang-rules**: Go coding rules: style, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt.
 - **grill-me**: Stress-tests a plan via Socratic questioning down each decision branch. Triggers: stress-test, grill me, validate assumptions, challenge plan, socratic review.
@@ -147,6 +151,7 @@
 - **observability-patterns**: Observability: structured logs, metrics (RED/USE), tracing, SLO/SLI. Triggers: logging, metrics, Prometheus, Grafana, OpenTelemetry, trace, monitoring.
 - **onboard**: Sets up ai-toolkit in a project: symlinks, CLAUDE.md, intent interview. Triggers: onboard, setup project, install ai-toolkit, migrate project.
 - **orchestrate**: Coordinates multiple specialized agents in parallel. Triggers: orchestrate, multi-agent, parallel agents, coordinate agents.
+- **output-mode**: Answer concisely: lead with the result, no preamble, tables over prose, no trailing restatement of a diff the reader can already see. Triggers: response style, verbosity, summary, explanation, report.
 - **panic**: Emergency kill switch — halts all agents via lockfile gate. Triggers: panic, stop everything, kill switch, halt agents, agents looping.
 - **performance-profiling**: Performance: golden signals, p50/p95/p99, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, bottleneck, memory leak.
 - **persona**: Switches engineering persona at runtime. Triggers: persona, switch role, backend-lead, frontend-lead, devops-eng, junior-dev.
@@ -160,6 +165,7 @@
 - **prompt-caching-patterns**: Anthropic API prompt caching: TTL, breakpoints, stacking, invalidation, hit rate. Triggers: prompt caching, cache_control, cache breakpoint, cache TTL, hit rate.
 - **python-rules**: Python coding rules: style, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy.
 - **qa-session**: Interactive QA: user reports bugs conversationally, agent files GitHub issues. Triggers: QA session, report bug, file issue, conversational QA, bug intake.
+- **quality-gates**: Plan before work over an hour, and hold the gates: ruff clean, mypy --strict clean, pytest coverage above 70 percent, no secrets in code. Triggers: quality, lint, mypy, pytest, coverage, gate, definition of done.
 - **rag-patterns**: RAG: embeddings, chunking, hybrid search (BM25+vector), reranking, CRAG, multi-hop. Triggers: RAG, embedding, pgvector, Qdrant, Pinecone, Weaviate, reranker, semantic search.
 - **refactor**: Refactors code for quality and maintainability. Triggers: refactor, clean up, restructure, improve code, modernize.
 - **refactor-plan**: Creates detailed refactor plan with tiny commits via interview, files as GitHub RFC. Triggers: refactor plan, refactoring RFC, incremental refactor, safe steps.
@@ -6929,7 +6935,7 @@ Examples:
 
 ---
 
-## kb/procedures/ecosystem-sync-sop.md
+## kb/procedures/sop-ecosystem-sync.md
 
 ---
 title: "SOP: Ecosystem Sync"
@@ -7186,12 +7192,12 @@ jobs:
 
 - [Supported Tools Registry](../reference/supported-tools-registry.md) — human-readable per-tool breakdown
 - [MCP Editor Compatibility](../reference/mcp-editor-compatibility.md) — MCP-specific adapter table
-- [Maintenance SOP](maintenance-sop.md) — general toolkit upkeep
-- [Release Preparation SOP](release-preparation-sop.md) — run the doctor before tagging
+- [Maintenance SOP](sop-maintenance.md) — general toolkit upkeep
+- [Release Preparation SOP](sop-release.md) — run the doctor before tagging
 
 ---
 
-## kb/procedures/maintenance-sop.md
+## kb/procedures/sop-maintenance.md
 
 ---
 title: "SOP: AI Toolkit Maintenance"
@@ -7705,7 +7711,7 @@ What `uninstall` does:
 
 ---
 
-## kb/procedures/post-release-testing-sop.md
+## kb/procedures/sop-post-release-testing.md
 
 ---
 title: "SOP: Post-Release Testing"
@@ -7725,7 +7731,7 @@ actually install, from npm, rather than the working tree.
 
 Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
 ai-toolkit equivalent. It complements
-[Release Verification](release-verification-sop.md), which checks the toolkit
+[Release Verification](sop-release-verification.md), which checks the toolkit
 from the maintainer's own installed copy. The difference that matters: this one
 never writes to the maintainer's `~/.claude` or `~/.softspark`.
 
@@ -8019,1201 +8025,1302 @@ print(f'removed {sb} ({n} files)')
 
 ## Related
 
-- [Release Preparation](release-preparation-sop.md) — run before tagging
-- [Release Verification](release-verification-sop.md) — the maintainer-install checks
+- [Release Preparation](sop-release.md) — run before tagging
+- [Release Verification](sop-release-verification.md) — the maintainer-install checks
 - [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run
 
 ---
 
-## kb/procedures/release-preparation-sop.md
+## kb/procedures/sop-pre-commit.md
 
 ---
-title: "SOP: Release Preparation"
+title: "SOP: Pre-Commit Gate"
 category: procedures
 service: ai-toolkit
-tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
-version: "1.15.0"
-created: "2026-04-10"
+tags: [pre-commit, quality-gate, shellcheck, bats, validation, secrets]
+version: "1.0.0"
+created: "2026-09-02"
 last_updated: "2026-09-02"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, branch CI, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, checksum-pin, ShellCheck, licensing, exact-tag assertions, and a green Ubuntu/macOS branch-CI gate before any release tag is created."
+description: "The local gate to run before every commit to ai-toolkit: staged-file and secret scan, ShellCheck, Python syntax, toolkit validation, and the Bats suite. Runs the same checks CI runs, so main does not go red after a push."
 ---
 
-# SOP: Release Preparation
+# SOP: Pre-Commit Gate
 
-Complete checklist for preparing a new `@softspark/ai-toolkit` release.
-Run this **before** tagging. After tagging and publishing, run the
-[Release Verification SOP](release-verification-sop.md) to smoke-test.
+## Why this exists
 
-**Pipeline:**
-```
-Ecosystem Sync SOP (drift check + generator updates)
-      ↓
-Release Preparation (this SOP)
-      ↓
-git tag → CI publish → Release Verification SOP
-```
+CI runs on `main` and on pull requests, but it runs *after* the push. Every
+check below already exists in `.github/workflows/ci.yml`; running them locally
+first is what keeps `main` green and keeps a release from becoming a debug
+session. The v4.5.1 postmortem in `sop-release.md` is the case
+where a hook lint failure published while reddening `main` CI.
 
-**Time:** 10-20 minutes (includes ecosystem sync review)
+This gate is not a substitute for `sop-release.md`. That SOP gates
+a *tag*; this one gates a *commit*.
 
----
+## Prerequisites
 
-## Quick Checklist (TL;DR)
+`shellcheck`, `python3` and `bats` must be on `PATH`. The suite is the one
+check that silently does nothing when its runner is absent, so install it
+before relying on this gate:
 
 ```bash
-# 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
-#    Full procedure: kb/procedures/ecosystem-sync-sop.md
-python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
-cat /tmp/eco-report.txt
-# If drift detected: stop here, follow ecosystem-sync-sop.md Phase 2-4 to
-# classify each drift (A-F), update generators as needed, refresh snapshot,
-# THEN resume this SOP.
-python3 scripts/ecosystem_doctor.py --update    # after all drift resolved
-
-# 1. Decide version bump
-#    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
-#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag, any ecosystem-class-B/F change
-#    major (1.4.2 → 2.0.0): breaking change, any ecosystem-class-D removed path
-
-# 2. Sync version across all files
-python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
-
-# 3. Write CHANGELOG.md entry
-# 4. Regenerate artifacts
-python3 scripts/generate_agents_md.py > AGENTS.md
-python3 scripts/generate_llms_txt.py > llms.txt
-python3 scripts/generate_llms_txt.py --full > llms-full.txt
-
-# 5. Validate + audit + SARIF + shellcheck + test + ecosystem check
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && shellcheck --severity=warning app/hooks/*.sh && npm test
-
-# 5a. Supply-chain standard (v2.8.0+) — non-negotiable
-grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --provenance"; exit 1; }
-grep -q 'id-token: write'   .github/workflows/publish.yml || { echo "MISSING id-token: write"; exit 1; }
-python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footprint
-
-# 5b. Ecosystem gate — snapshot must be current before tag
-python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }
-
-# 5c. Licensing gate — SPDX headers, LICENSE, NOTICE, manifest consistency
-npx bats tests/test_licensing.bats || { echo "LICENSING GATE FAILED"; exit 1; }
-
-# 6. Commit, push branch, and wait for the exact commit's full CI
-git add -A && git commit -m "chore: release vX.Y.Z"
-RELEASE_SHA=$(git rev-parse HEAD)
-git push origin main || { echo "FAIL: release commit push failed"; exit 1; }
-RUN_ID=""
-for ATTEMPT in 1 2 3 4 5; do
-  RUN_ID=$(gh run list --workflow ci.yml --event push --commit "$RELEASE_SHA" \
-    --limit 1 --json databaseId --jq '.[0].databaseId')
-  [ -n "$RUN_ID" ] && break
-  echo "Waiting for CI run registration ($ATTEMPT/5)" >&2
-  [ "$ATTEMPT" -eq 5 ] || sleep 60
-done
-test -n "$RUN_ID" || { echo "FAIL: CI run not found for release commit"; exit 1; }
-gh run watch "$RUN_ID" --exit-status \
-  || { echo "FAIL: release commit CI failed"; exit 1; }
-for OS in ubuntu-latest macos-latest; do
-  gh run view "$RUN_ID" --json jobs \
-    --jq ".jobs[] | select(.name == \"Bats test suite ($OS)\") | .conclusion" \
-    | grep -qx success || { echo "FAIL: $OS test job not green"; exit 1; }
-done
-test "$(git rev-parse HEAD)" = "$RELEASE_SHA" || { echo "FAIL: local HEAD changed during CI"; exit 1; }
-git fetch origin main || { echo "FAIL: origin/main refresh failed"; exit 1; }
-test "$(git rev-parse origin/main)" = "$RELEASE_SHA" || { echo "FAIL: origin/main changed during CI"; exit 1; }
-
-# 6a. Only green branch CI authorizes tag creation
-git tag vX.Y.Z "$RELEASE_SHA"
-
-# 6b. Assert the tag before pushing it (v4.19.0 postmortem, Phase 7)
-test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA" || { echo "FAIL: tag not on tested release commit"; exit 1; }
-git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" || { echo "FAIL: tag not on release commit"; exit 1; }
-
-# 6c. Push the single tag by full ref. Never --tags.
-git push origin refs/tags/vX.Y.Z
+brew install bats-core shellcheck    # macOS
+sudo apt-get install -y bats shellcheck   # Debian / Ubuntu
 ```
 
----
+## The gate
 
-## Phase 0: Ecosystem Sync (MANDATORY for minor/major)
+Run all five from the repository root. Each mirrors a CI job.
 
-Before touching version numbers, confirm the toolkit is aligned with the current state of every editor / platform it integrates with. Skipping this phase ships a release whose generators may lag a month-old CLI refactor, a rename of `.cursorrules` to `.cursor/rules/`, or a new hook event we do not yet emit.
+```bash
+# 1. Staged files: secrets, large blobs, commit-type suggestion
+python3 app/skills/commit/scripts/pre-commit-check.py
 
-**When this phase is mandatory:**
-- Minor release (X.Y.0) — always
-- Major release (X.0.0) — always
-- Patch release (X.Y.Z) — only if the patch touches a generator or install flow
+# 2. ShellCheck hooks -- the CI job that has published while red before
+shellcheck --severity=warning app/hooks/*.sh app/plugins/*/hooks/*.sh
 
-**When to skip:** pure doc-only patches, SOP edits, internal refactors that do not touch `scripts/generate_*` or `app/skills/*/SKILL.md`.
+# 3. Python syntax across every script the toolkit ships
+python3 -m py_compile scripts/*.py app/skills/*/scripts/*.py
 
-### 0.1 Run the doctor
+# 4. Toolkit integrity: agents, skills, registry drift, content quality
+npm run validate
 
-```bash
-python3 scripts/ecosystem_doctor.py --format text | tee /tmp/eco-report.txt
+# 5. The suite. Run it ONCE -- see the single-run discipline below
+npm test
 ```
 
-Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.
+A non-zero exit from any of them is a stop, not a warning to note and push past.
 
-### 0.2 Act on drift
+## Single-run discipline
 
-For each drifting tool, follow [ecosystem-sync-sop.md](ecosystem-sync-sop.md) Phase 2-4:
+`npm test` runs the Bats suite with `--jobs 4`. Running it repeatedly to see
+whether a failure is "flaky" hides real ordering bugs and wastes minutes. Run
+it once. If it fails, read the failure and fix the cause; if the same test
+passes on a re-run without a code change, that instability is itself the bug
+and belongs in an issue, not in a retry.
 
-| Drift class | Release impact |
-|-------------|----------------|
-| A (cosmetic reword) | No version impact — refresh snapshot, continue |
-| B (new feature — integrate) | **Minor** version bump at minimum; new generator or extended generator |
-| C (new feature — not adopted) | No impact — note in registry |
-| D (deprecation) | **Minor** or **major** depending on user impact; add migration warning |
-| E (feature promoted to default) | **Minor**; simplify generator, keep fallback comment |
-| F (feature newly globally available) | **Minor**; may require new generator or new config path |
+## What this gate does not cover
 
-If any B/D/E/F changes land in this preparation pass, mention them explicitly in the CHANGELOG entry (Phase 3) under a `Ecosystem` subsection.
+- **Cross-platform.** The suite here runs on your machine only. Both
+  `ubuntu-latest` and `macos-latest` must be green before a tag; that gate
+  lives in `sop-release.md`, Phase 7, and is bound to the exact
+  release commit.
+- **Required files.** The `required-files` CI job checks that every file the
+  module template mandates is present and that the version is in sync across
+  all four manifests. It is cheap and runs on every push.
+- **Provenance and SARIF.** Release-time concerns; see
+  `sop-release.md`.
 
-### 0.3 Refresh snapshot
+## Commit message
 
-Once every drift is resolved (either by code change or by re-classifying as acceptable):
+Conventional Commits, and no AI co-authorship trailer:
 
-```bash
-python3 scripts/ecosystem_doctor.py --update
+```
+feat(scope): summary in the imperative
+fix(scope): summary in the imperative
+docs|refactor|test|chore(scope): ...
 ```
 
-This writes the new baseline to `benchmarks/ecosystem-doctor-snapshot.json`. Commit it as part of the release commit.
+`pre-commit-check.py` suggests a type from the staged paths. It is a
+suggestion; the scope and the summary are yours.
 
-### 0.4 Gate
+## Related
 
-```bash
-python3 scripts/ecosystem_doctor.py --offline --check
-```
+- `sop-release.md` -- the pre-tag gate, including cross-platform CI
+- `sop-post-release-testing.md` -- what to verify after a release ships
+- `sop-release-verification.md` -- end-to-end smoke test of an installed build
 
-Must exit `0`. If it exits `1`, the snapshot is stale — rerun Phase 0.3 or review the remaining drift.
+---
 
+## kb/procedures/sop-release-verification.md
+
+---
+title: "SOP: Release Verification"
+category: procedures
+service: ai-toolkit
+tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif, dsh]
+version: "1.8.0"
+created: "2026-04-08"
+last_updated: "2026-09-01"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, explicit DSH lifecycle, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
 ---
 
-## Phase 1: Determine Version Bump
+# SOP: Release Verification
 
-Follow [Semantic Versioning](https://semver.org/):
+End-to-end smoke test after installing or updating `@softspark/ai-toolkit`.
+Verifies all critical paths from the user's perspective.
 
-| Change Type | Bump | Examples |
-|-------------|------|---------|
-| Bugfix, typo, doc-only | **patch** | Fix install flag, correct description |
-| New feature, skill, agent, flag | **minor** | Add `/hipaa-validate`, add `--output json` |
-| Breaking CLI change, removed skill, config format change | **major** | Rename `install` to `setup`, remove skill |
+**Use this SOP when:**
+- After `npm install -g @softspark/ai-toolkit@latest`
+- After `ai-toolkit update`
+- Before tagging a new version (`git tag`)
+- Before publishing to npm (`npm publish`)
+- As a smoke test in CI/CD
 
-**Rule:** When in doubt, bump minor.
+**Prerequisites:**
+- Node.js >= 18, Python 3, `bats`, git
+- `@softspark/ai-toolkit` installed globally
+
+**Time:** 10-15 minutes (full), 2 minutes (quick checklist)
 
 ---
 
-## Phase 2: Sync Version in All Files
+## Quick Checklist (TL;DR)
 
-The canonical version lives in `package.json`. These files **must** match:
+The 14 core commands below must pass. Releases that change DSH must also complete Phase 10.
 
-### Mandatory sync (every release)
+```bash
+# Pre-commit (Phase 0)
+python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt             # 2. Regenerate llms.txt
+python3 scripts/validate.py --strict                        # 3. Validation passed?
+npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 4. All tests passed? (single run, cached)
 
-| File | Field | How to update |
-|------|-------|---------------|
-| `package.json` | `"version": "X.Y.Z"` | Edit directly |
-| `manifest.json` | `"version": "X.Y.Z"` | Edit directly |
-| `app/.claude-plugin/plugin.json` | `"version": "X.Y.Z"` | Edit directly |
+# Post-install verification (Phases 1-7)
+ai-toolkit --version                                        # 5. Version OK?
+ai-toolkit status                                           # 6. Status OK?
+ai-toolkit doctor                                           # 7. Health check passed?
+ai-toolkit install --dry-run                                # 8. Global install OK?
+python3 scripts/audit_skills.py --ci                        # 9. Security audit clean?
 
-### Auto-synced (no manual action)
+# Supply-chain verification (Phase 8, v2.8.0+)
+python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 10. SARIF 2.1.0 well-formed?
+python3 scripts/audit_skills.py --permissions | head -30    # 11. Broad-access skills reviewed?
+npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 12. Provenance attested on npm?
+python3 scripts/claude_app.py verify                         # 13. Claude Chat/Cowork plugin contract valid?
 
-| File | Mechanism |
-|------|-----------|
-| `package-lock.json` | Regenerated by `npm install --package-lock-only` |
+# Deep-coverage verification (Phase 9, v3.0.0+)
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
+diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
+```
 
-### Conditional sync (only if the doc was modified in this release)
+---
 
-| File | Field | When to update |
-|------|-------|---------------|
-| `kb/procedures/maintenance-sop.md` | frontmatter `version:` | If SOP content changed |
-| `kb/reference/skills-catalog.md` | frontmatter `version:` | If skills added/removed |
-| `kb/reference/agents-catalog.md` | frontmatter `version:` | If agents added/removed |
-| `kb/reference/hooks-catalog.md` | frontmatter `version:` | If hooks changed |
-| `kb/reference/architecture-overview.md` | frontmatter `version:` | If architecture changed |
-| `kb/reference/distribution-model.md` | frontmatter `version:` | If install model changed |
-| `kb/reference/global-install-model.md` | frontmatter `version:` | If install model changed |
+## Phase 0: Pre-Commit & Pre-Push (2 min)
 
-> **Note:** KB `version:` fields track the **document version**, not the toolkit version.
-> Only bump them when the document content actually changes in this release.
+Run these commands **before every commit and push to main**. CI validates
+counts but does NOT auto-regenerate — you must do it locally.
 
-### Count sync (if skills/agents/hooks changed)
+```bash
+# 1. Regenerate generated artifacts
+python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt
+python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
-| File | What to check |
-|------|---------------|
-| `package.json` | `"description"` — skill/agent count |
-| `README.md` | Badge counts, "What You Get" table |
-| `app/ARCHITECTURE.md` | Section headings with counts |
+# 2. Validate everything (catches stale counts, missing assets)
+python3 scripts/validate.py --strict
 
-> **Tip:** `validate.py --strict` catches count drift AND version mismatches
-> (package.json vs manifest.json vs plugin.json) automatically.
-> If validation passes, counts and versions are correct.
+# 3. Security audit
+python3 scripts/audit_skills.py --ci
 
-### Verification command
+# 4. Run tests
+npm test
 
-After syncing, verify all mandatory files match:
+# 5. Stage and commit
+# AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated and
+# gitignored — do NOT commit them (regenerated at prepublishOnly). Only the
+# doc artifacts llms.txt / llms-full.txt are committed.
+git add llms.txt llms-full.txt
+git add -p  # stage your other changes
+git commit -m "feat: your change description"
+```
+
+**Why local?** Branch protection on `main` requires PRs and status checks.
+CI cannot push directly to `main`, so generated artifacts must be committed
+by the developer as part of their PR.
 
+**One-liner (copy-paste):**
 ```bash
-VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
-echo "Target: $VERSION"
-echo "manifest.json:     $(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")"
-echo "plugin.json:       $(python3 -c "import json; print(json.load(open('app/.claude-plugin/plugin.json'))['version'])")"
-echo "package-lock.json: $(python3 -c "import json; print(json.load(open('package-lock.json'))['version'])")"
+python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
 ```
 
-All four must print the same version. If not, fix before proceeding.
+---
 
-### Public surface review
+## Phase 1: CLI & Version (1 min)
 
 ```bash
-python3 scripts/surface_manifest.py --update
-git diff app/surface.json
-```
-
-**Every line the diff removes is a breaking change.** Restore it, or take the
-deprecation path in `BACKWARD_COMPATIBILITY.md` and add a `DECISIONS.md` entry
-before the tag. Lines added are new surface being adopted into protection — that
-needs no ceremony.
-
-Do not run `--update` to make a red build green. The check fails because something
-users depend on disappeared; regenerating the manifest deletes the evidence, not
-the problem.
-
-### Skill body budget ratchet
-
-`validate.py` prints the largest skill body on every run:
-
-```
-Body budget: largest is <skill> at <N> bytes (warn 18000, error 20000)
+ai-toolkit --version
+ai-toolkit --help
+which ai-toolkit
 ```
 
-Once that number sits at least 2000 bytes under `SKILL_BODY_BUDGET_WARN`, lower
-`SKILL_BODY_BUDGET_WARN` by 2000 in `scripts/validate.py` and ship the tightened
-threshold with the release. Target floor is 12000.
-
-Two rules, both learned the hard way:
-
-- **Never lower a threshold in the same change that something violates it.** Split
-  the offending skill into `SKILL.md` + `reference/` first, prove it with
-  `python3 scripts/check_split.py <skill> --before <pre-split SKILL.md>`, then
-  tighten in a follow-up.
-- **Never raise a threshold to make a red build green.** A body over budget means
-  detail that belongs in `reference/` is loading on every trigger match, including
-  the accidental ones. Raising the number hides the cost, it does not remove it.
-
-If the largest body has not moved since the previous release, leave the threshold
-alone and say so in the release notes. A ratchet that never advances is honest;
-one that advances past reality is not.
+**Verify:**
+- [ ] `--version` returns correct semver (e.g., `1.4.0`)
+- [ ] `--help` displays full command list without errors
+- [ ] `which` points to global npm bin path
 
 ---
 
-## Phase 3: Write CHANGELOG Entry
+## Phase 2: Global Install & Status (2 min)
 
-Add entry at the top of `CHANGELOG.md` (after the header, before previous release):
+```bash
+ai-toolkit install --dry-run
+ai-toolkit status
+```
 
-```markdown
-## vX.Y.Z — Short Title (YYYY-MM-DD)
+**Verify `--dry-run`:**
+- [ ] Agents: 44
+- [ ] Skills: 108
+- [ ] Hooks merged into settings.json
+- [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.
 
-### Added
-- **Feature name** — description
+**Verify `status`:**
+- [ ] Version matches expected
+- [ ] Profile: minimal/standard/strict
+- [ ] Modules: list of installed modules
+- [ ] Latest: up to date / update available
 
-### Changed
-- **What changed** — old behavior → new behavior
+---
 
-### Fixed
-- **Bug description** — what was broken and how it's fixed
+## Phase 3: Doctor Health Check (1 min)
 
-### Removed
-- **What was removed** — migration path if any
+```bash
+ai-toolkit doctor
 ```
 
-**Rules:**
-- Use **bold** for feature names
-- Start descriptions with a verb (Added, Changed, Fixed, Removed)
-- Reference skill names with backticks and slash: `/hipaa-validate`
-- Include script names: `scripts/hipaa_scan.py`
-- Include count changes: `Skill count: 91 → 92`
-- Date format: `YYYY-MM-DD`
-- Title: short, descriptive, no version number repetition
-
-### Update README "What's New" section
-
-**MANDATORY on every release.** Update the `## What's New in vX.Y.Z` section in `README.md`:
-
-1. Change the heading version: `## What's New in vX.Y.Z`
-2. Replace bullet points with 3-5 highlights from this release
-3. **Keep only the latest version block.** Delete the previous `## What's New in vA.B.C` section(s). README is the shop window, not the archive — users see the current release, full history lives in `CHANGELOG.md`.
-4. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link directly below the bullet list.
+**Expected sections (all OK):**
+- Environment: node, bash, python3, bats
+- Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
+- Hook Scripts: all present and executable
+- Hook Configuration: 14 events registered
+- Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
+- Planned Assets: plugin.json, benchmarks, plugin packs
+- Benchmark Freshness: < 30 days
+- Stale Rules: all healthy
 
-> **Warning:** This section is the first thing users see after the badges.
-> A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
-> signals an unmaintained project. Do NOT skip this step.
+**Verify:**
+- [ ] `Errors: 0 | Warnings: 0`
+- [ ] `HEALTH CHECK PASSED`
 
-> **Single-version rule:** README.md must contain **exactly one** `## What's New in vX.Y.Z` heading at any time. If you find multiple stacked (e.g. v2.6.1 + v2.6.0 + v2.5.0), that is a SOP drift — collapse to the latest on the next release commit.
+If doctor detects problems: `ai-toolkit doctor --fix` auto-repairs
+(broken symlinks, non-executable hooks, missing scripts, missing llms-full.txt).
 
 ---
 
-## Phase 4: Regenerate Artifacts
-
-Use the npm scripts, not the generators directly:
+## Phase 4: Local Install (2 min)
 
 ```bash
-npm run generate:agents   # AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_agents_md.py > AGENTS.md
-npm run generate:llms     # llms.txt + llms-full.txt
+mkdir -p /tmp/ai-toolkit-verify && cd /tmp/ai-toolkit-verify
+git init -q
+ai-toolkit install --local --editors all --dry-run
+cd - && rm -rf /tmp/ai-toolkit-verify
 ```
 
-`generate:agents` sets `AI_TOOLKIT_NO_CUSTOM_RULES=1`. Running
-`generate_agents_md.py` bare picks up whatever is registered in the maintainer's
-own `~/.softspark/ai-toolkit/rules/`, which then ships inside `AGENTS.md`.
-
-Check if anything actually changed:
+**Verify "Project-local" section:**
+- [ ] Would create: CLAUDE.md
+- [ ] Would create: .claude/settings.local.json
+- [ ] Would inject: .claude/constitution.md
+- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
+- [ ] Would generate configs for each editor (legacy + directory-based)
+- [ ] Would install: .git/hooks/pre-commit
+- [ ] Would inject language rules (auto-detected)
 
+**Also test auto-detect (no --editors flag):**
 ```bash
-git diff --stat AGENTS.md llms.txt llms-full.txt
+ai-toolkit install --local --dry-run
+# → Editors: none (empty project has no existing configs)
 ```
 
-If no diff, the artifacts are already current. If there is a diff, stage them.
-
 ---
 
-## Phase 5: Validate, Audit, Test
-
-Run the full quality gate:
+## Phase 5: Validation & Security Audit (3 min)
 
 ```bash
 python3 scripts/validate.py --strict
 python3 scripts/audit_skills.py --ci
-python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
-python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
+```
 
-# ShellCheck on hooks (added in 1.11.0). Mirrors the ci.yml "ShellCheck hooks"
-# job. NOT run by validate.py, npm test, OR publish.yml — so a hook with a
-# ShellCheck warning passes every other gate AND still publishes on tag while
-# turning main CI red. Run it here, before tagging.
-shellcheck --severity=warning app/hooks/*.sh && echo "OK: shellcheck clean"
+**Verify validate.py:**
+- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
+- [ ] Hook events: 14, Hook scripts: >= 30
+- [ ] Plugin packs >= 10, KB documents >= 20
+- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
 
-# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
-META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
-diff \
-  <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
-  <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
-  && echo "OK: registry matches filesystem" \
-  || { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
+**Verify audit_skills.py:**
+- [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
+- [ ] `WARN: 0`
+- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, workflow)
 
-# Stage first IF this release adds or deletes a kb/ file. The test
-# "npm package KB files match the tracked release set" compares `git ls-files
-# kb` (the index) against what `npm pack` sees (the working tree), so an
-# unstaged addition reads as "extra" and an unstaged deletion as "missing".
-# Phase 6 stages, and it runs after this one, so the ordering fails the test
-# for any release that touches the KB. Staging early costs nothing.
-git status --porcelain kb/ | grep -qE '^(\?\?| D|\?M)' && git add -A kb/
+---
 
-# Run npm test ONCE, cache output, parse from file. The suite is 1400+ bats
-# cases — rerunning it per check wastes minutes. Do not pipe npm test into
-# tail/grep multiple times in the same session.
+## Phase 6: Tests (3-5 min)
+
+```bash
+# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
+# re-running it per check (tail / grep ok / grep not ok piped separately)
+# wastes minutes every release. Always cache the output.
 npm test > /tmp/npm-test.log 2>&1
+exit=$?
 tail -3 /tmp/npm-test.log
-echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
+echo "ok:     $(grep -c '^ok '    /tmp/npm-test.log)"
+echo "not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
+echo "exit:   $exit"
 ```
 
-**Expected results:**
-- `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
-- `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
-- `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
-- `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
-- `shellcheck --severity=warning app/hooks/*.sh`: no output, exit 0. A common false positive is `SC2034` on `INPUT` or env vars (e.g. `AI_TOOLKIT_HOOK_FORMAT`) that a *sourced* helper (`_hook-io.sh`) consumes — ShellCheck cannot see cross-file use. Fix with a `# shellcheck disable=SC2034` directive or `export`, matching `guard-destructive.sh`. Never tag with a red ShellCheck.
-- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
-- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
-
-> **Why this matters (v4.5.1 postmortem):** `publish.yml` runs only `validate.py` + `npm test`, so it published v4.5.0 even though the `main` CI `ShellCheck hooks` job was red on two `SC2034` warnings in a new hook. The publish workflow does **not** depend on the CI workflow. Until that is fixed, ShellCheck is a manual pre-tag gate — run it here every time.
+**Verify:**
+- [ ] `exit == 0`
+- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
+- [ ] `not ok == 0`
+- [ ] Bats runs tests in parallel (4 jobs)
+- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
+      install, kb, mcp, readme, profiles, uninstall, validate
 
-**One-liner:**
+**Anti-pattern — do NOT do this:**
 ```bash
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && shellcheck --severity=warning app/hooks/*.sh && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py|generate_language_rules_skills\.py' | sort -u) && npm test
+# Runs the full suite THREE times. Adds 1-3 min and pressures CI capacity.
+npm test 2>&1 | tail -3
+npm test 2>&1 | grep -c '^ok '
+npm test 2>&1 | grep -c '^not ok'
 ```
 
-**If tests fail:** Fix the issue, do NOT skip. Common failures:
-- Stale counts → re-run `generate:all` or fix README/ARCHITECTURE
-- Missing frontmatter → add to new KB docs
-- Broken symlink → `ai-toolkit doctor --fix`
+**Key test areas:**
+- Guards: rm -rf, DROP TABLE, git push --force blocked
+- Install: idempotent, profiles, --only/--skip, orphan cleanup
+- Eject: real files (not symlinks), inlined rules
+- Uninstall: removes toolkit, preserves user content
 
-### Phase 5c: Licensing Gate (v4.20.0+)
+---
 
-The project is Apache-2.0. Attribution only works if the artefact actually
-carries it, and every part of that is mechanically checkable.
+## Phase 7: Eject (1 min)
 
 ```bash
-# The whole gate, enforced in CI. Run it here so a failure is caught before tagging.
-npx bats tests/test_licensing.bats
+mkdir -p /tmp/ai-toolkit-eject-test
+cd /tmp/ai-toolkit-eject-test
+ai-toolkit eject
+cd - && rm -rf /tmp/ai-toolkit-eject-test
 ```
 
-The seven assertions, and why each exists:
+**Verify:**
+- [ ] Agents copied as real files (not symlinks)
+- [ ] Skills copied as real directories
+- [ ] Rules inlined into CLAUDE.md
+- [ ] constitution.md and ARCHITECTURE.md copied
+- [ ] `output-styles/` directory present (v2.7.1+)
 
-| Check | Fails when |
-|---|---|
-| Every shipped source file carries an SPDX header | A new `.py`/`.sh`/`.js`/`.bats` file was added without one — the common case, and the reason this is a test rather than a habit |
-| Headers name Apache-2.0 and nothing else | A file was copied in from an MIT/GPL source with its own header intact |
-| **No** markdown file carries an SPDX header | Someone "helpfully" ran the header script over `app/skills/` — headers there sit above parsed frontmatter and bill every session for it |
-| `LICENSE` is the complete Apache 2.0 text | The file was truncated or replaced with a summary |
-| `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice | The attribution mechanism was gutted |
-| `LICENSE` **and** `NOTICE` ship in the npm package | `package.json` `files` lost an entry — a NOTICE that never reaches the consumer cannot satisfy §4(d) |
-| Every manifest declaring a licence declares Apache-2.0 | `package.json`, `manifest.json`, `plugin.json` and `package-lock.json` drifted apart |
+---
 
-**Adding source files in this release?** The header goes *after* the shebang,
-never before it. Short SPDX form:
+## Phase 8: Supply-Chain Verification (2 min, v2.8.0+)
 
-```
-# SPDX-License-Identifier: Apache-2.0
-# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
-# Source: https://github.com/softspark/ai-toolkit
-```
+These checks enforce the v2.8.0 security standard on a freshly-published release. Run AFTER the `publish.yml` workflow completes on the tag.
 
-`//` for JavaScript. Full convention and the reasoning behind the markdown
-exclusion: [Licensing](../reference/licensing.md).
+### 8.1 Provenance attestation on npm
 
-**Changing the licence itself?** Do not hand-type the licence text. Take it
-verbatim from a published copy and cross-verify against a second independent
-copy before writing `LICENSE` — a rendered or summarised licence is not the
-licence. Prior releases stay under their original terms; a licence change
-applies going forward and revokes nothing already granted.
+```bash
+VERSION="X.Y.Z"                                           # the tag just published
+npm view "@softspark/ai-toolkit@${VERSION}" --json \
+  | python3 -c "import json, sys; d=json.load(sys.stdin); att=d['dist'].get('attestations', {}); assert att.get('provenance', {}).get('predicateType') == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE for {d[\"version\"]}'; print(f'PROVENANCE OK: {att[\"url\"]}')"
+```
 
-### Phase 5a: Supply-Chain Hardening Verification (v2.8.0+)
+**Verify:**
+- [ ] Exit 0 and prints `PROVENANCE OK: https://registry.npmjs.org/...`
+- [ ] `https://www.npmjs.com/package/@softspark/ai-toolkit/v/${VERSION}` shows the green "Provenance" badge
 
-These checks enforce the security standard introduced in v2.8.0. Do NOT tag a release until all pass.
+**If provenance is missing:** the `publish.yml` ran without `id-token: write` or `--provenance`. Restore them and cut a patch release — a silently unsigned publish is a regression against the v2.8.0 standard.
 
-**1. Publish workflow emits provenance:**
+### 8.2 Audit SARIF output (for GHAS ingest)
 
 ```bash
-grep -E '\-\-provenance|id-token: write' .github/workflows/publish.yml
+python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif
+python3 -c "import json; d=json.load(open('/tmp/audit.sarif')); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']=='ai-toolkit-audit-skills'; print(f'SARIF OK: {len(d[\"runs\"][0][\"results\"])} results across {len(d[\"runs\"][0][\"tool\"][\"driver\"][\"rules\"])} rules')"
 ```
 
-- [ ] Both markers present (`--provenance` flag + `id-token: write` permission)
-- [ ] Any PR that changes `publish.yml` REQUIRES an approved security review
+**Verify:**
+- [ ] Valid SARIF 2.1.0
+- [ ] In the publishing repo, the CI job uploads `audit.sarif` via `github/codeql-action/upload-sarif@v3` so findings appear in the Security tab
 
-**2. URL-sourced rules and hooks are checksum-pinned:**
+### 8.3 Per-skill permissions report
 
 ```bash
-# On a machine that has consumed URL rules/hooks at least once
-# (schema_version 1: entries live under the .rules / .hooks key):
-jq '.rules | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/rules/sources.json
-jq '.hooks | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/hooks/external/sources.json
+python3 scripts/audit_skills.py --permissions | head -40
 ```
 
-- [ ] Both queries return empty arrays (every URL entry has a `sha256`)
-- [ ] If not, run `ai-toolkit update` to backfill missing hashes before tagging
+**Verify:**
+- [ ] Bash skill count has NOT jumped unexpectedly since the previous release
+- [ ] Any newly added entry under `Skills with Bash + Write + Edit` matches a CHANGELOG bullet that justifies the broad scope
+- [ ] JSON form (`--permissions --json`) is available for automated drift dashboards
 
-**3. Audit SARIF output is well-formed:**
+### 8.4 URL-sourced rules/hooks are checksum-pinned
+
+`sources.json` is an envelope of the form `{"schema_version": 1, "rules"|"hooks": {...}}`, so the jq filter must pick the nested map before piping into the pin assertion. The URL-count in the success message ignores local `path:`-only entries — only entries with a `url:` field are pinned and counted.
 
 ```bash
-python3 scripts/audit_skills.py --sarif | python3 -c "import json, sys; d=json.load(sys.stdin); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']; print('SARIF OK')"
+jq '.rules // .hooks // {}' ~/.softspark/ai-toolkit/rules/sources.json 2>/dev/null \
+  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'RULE PIN OK: {url_n} URL rules, all with sha256')"
+jq '.hooks // {}' ~/.softspark/ai-toolkit/hooks/external/sources.json 2>/dev/null \
+  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'HOOK PIN OK: {url_n} URL hooks, all with sha256')"
 ```
 
-- [ ] Prints `SARIF OK`
-- [ ] If the script ever grows new rule classes, extend the SARIF `rules[]` coverage before releasing
+**Verify:**
+- [ ] Both commands print `... PIN OK`
+- [ ] If any entry is unpinned, the `register_url_source()` call missed passing `content=` — fix the call-site and retag
 
-**4. Strict-pin mode passes on CI** (optional, recommended for stable branches):
+### 8.5 Strict-pin smoke test (optional but recommended)
 
 ```bash
 AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 ```
 
+**Verify:**
 - [ ] Exit 0, no `CHECKSUM CHANGED` line
-- [ ] Any unexpected upstream change blocks the release until explicitly approved
+- [ ] If a checksum change was intentional (e.g. upstream rule update), document it in the CHANGELOG entry before tagging
 
 ---
 
-## Phase 6: Commit
+## Phase 9: Deep-Coverage Checks (v3.0.0+)
 
-Stage all release files:
+These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
+
+> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
+
+### 9.1 `--profile full` emits every native surface
 
 ```bash
-git add package.json manifest.json app/.claude-plugin/plugin.json
-git add package-lock.json
-git add CHANGELOG.md
-git add llms.txt llms-full.txt
-# NOTE: AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated
-# editor configs and are gitignored — do NOT commit them. `prepublishOnly` runs
-# `npm run generate:all`, so the shipped package (which lists AGENTS.md in
-# package.json `files`) gets a fresh copy at publish time.
-git add -p  # review and stage any other changes
+D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot \
+  --profile full --dry-run 2>&1 \
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.devin/hooks\\.v1\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/(agents|hooks)|\\.agents/skills|\\.github/(agents|skills|instructions|prompts|hooks)"
 ```
 
-Commit:
+**Verify** — at least the following lines appear:
+- [ ] `.cursor/hooks.json` and `.cursor/agents/`
+- [ ] `.devin/hooks.v1.json`
+- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
+- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
+- [ ] `.codex/hooks.json` + `.codex/hooks/` + `.codex/agents/`
+- [ ] `.agents/skills/` (Codex native discovery path)
+- [ ] `.github/agents/` + `.github/skills/` + `.github/instructions/` + `.github/prompts/` + `.github/hooks/`
+
+### 9.2 Codex skills are profile-independent
 
 ```bash
-git commit -m "chore: release vX.Y.Z"
+D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors codex --profile minimal --dry-run 2>&1 \
+  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills emit at minimal"
+ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
+  | grep -q "Would refresh: .agents/skills" && echo "OK: legacy flag explicitly refreshes the same catalog"
 ```
 
----
+**Verify:**
+- [ ] Selecting Codex emits all skills under `.agents/skills/` at every profile
+- [ ] `--codex-skills` remains an explicit refresh alias; it is not required for installation
+- [ ] No profile emits `.codex/skills/`
 
-## Phase 7: Push Branch, Verify CI, Tag, and Push Tag
+### 9.3 Breaking-change surfaces land on `--profile standard`
+
+The standard profile must include:
+- Copilot scoped instructions, prompts, custom agents, portable skills, and hooks
+- Gemini hooks (`.gemini/settings.json`)
 
 ```bash
-RELEASE_SHA=$(git rev-parse HEAD)
-git push origin main || { echo "FAIL: release commit push failed"; exit 1; }
+D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
+  | tee /tmp/aitk-breaking.log
+grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
+grep -q "\\.github/agents/.*\\.github/skills/" /tmp/aitk-breaking.log && echo "OK: Copilot agents and skills at standard"
+grep -q "\\.github/hooks/" /tmp/aitk-breaking.log && echo "OK: Copilot hooks at standard"
+grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
+```
 
-# Bind the gate to the exact release commit. GitHub run registration is
-# asynchronous, so retry at most five times and log every attempt.
-RUN_ID=""
-for ATTEMPT in 1 2 3 4 5; do
-  RUN_ID=$(gh run list --workflow ci.yml --event push --commit "$RELEASE_SHA" \
-    --limit 1 --json databaseId --jq '.[0].databaseId')
-  [ -n "$RUN_ID" ] && break
-  echo "Waiting for CI run registration ($ATTEMPT/5)" >&2
-  [ "$ATTEMPT" -eq 5 ] || sleep 60
-done
-test -n "$RUN_ID" || { echo "FAIL: CI run not found for release commit"; exit 1; }
-gh run watch "$RUN_ID" --exit-status \
-  || { echo "FAIL: release commit CI failed"; exit 1; }
+**Verify all four lines print `OK:`**. If any is missing, native Copilot or Gemini coverage has regressed.
 
-# publish.yml is Ubuntu-only. Require both full CI matrix jobs before creating
-# the tag so a green publish job cannot bypass a red macOS test.
-for OS in ubuntu-latest macos-latest; do
-  gh run view "$RUN_ID" --json jobs \
-    --jq ".jobs[] | select(.name == \"Bats test suite ($OS)\") | .conclusion" \
-    | grep -qx success || { echo "FAIL: $OS test job not green"; exit 1; }
-done
+### 9.4 Install is idempotent
 
-# Refuse to tag if either local or remote main moved while CI was running.
-test "$(git rev-parse HEAD)" = "$RELEASE_SHA" \
-  || { echo "FAIL: local HEAD changed during CI"; exit 1; }
-git fetch origin main || { echo "FAIL: origin/main refresh failed"; exit 1; }
-test "$(git rev-parse origin/main)" = "$RELEASE_SHA" \
-  || { echo "FAIL: origin/main changed during CI"; exit 1; }
+```bash
+D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+# Sort file paths before hashing — find traversal order follows inode order,
+# which can shift between runs even when content is byte-identical, producing
+# false FAIL signals.
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA1=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA2=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
+[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
+```
 
-git tag vX.Y.Z "$RELEASE_SHA"
+**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
 
-# Assert the tag before pushing it. Both checks are one line each and both
-# have caught a real broken release.
-test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA" \
-  || { echo "FAIL: tag is not on the tested release commit"; exit 1; }
-git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" \
-  || { echo "FAIL: tag is not on the chore: release commit"; exit 1; }
+### 9.5 Live-install JSON outputs parse
 
-# Push the single release tag by its full ref.
-git push origin refs/tags/vX.Y.Z
+The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
+
+```bash
+D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
+for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
+  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
+done
 ```
 
-**Why branch CI comes before the tag (v4.30.2 postmortem).** The publish
-workflow runs only on Ubuntu and can publish while the separate macOS matrix job
-is red. `v4.30.2` exposed this with a macOS-only DSH timing failure. A release
-commit must therefore pass the complete Ubuntu/macOS branch workflow before its
-tag exists; a successful publish workflow is not a substitute for green CI.
+**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
 
-**Why the assertions (v4.19.0 postmortem).** v4.19.0 was tagged on a commit
-that contained only a KB document and still carried `package.json` version
-`4.18.0`; the actual release sat in the commit above it under a recycled
-`fix:` message. `publish.yml` fired, tried to publish a version already on
-npm, and failed. Nothing on npm, a tag pointing at the wrong tree, and the
-only way out was rewriting a pushed commit. Both assertions above catch this
-in under a second. Run them.
+### 9.6 Registry / generator drift check
 
-**Never `git push --tags`.** It pushes every local tag at once, and GitHub
-suppresses tag-triggered workflow runs when many tags arrive in a single push
-— the workflow silently does not fire and nothing publishes. Push the single
-release tag by its full ref, as above. (Sibling evidence: this is exactly how
-rag-mcp's `1.0.3` image build was skipped, when a `--tags` push carried 37
-tags at once.)
+`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
 
-This triggers `.github/workflows/publish.yml` which:
-1. Runs `validate.py --strict`
-2. Runs `npm test`
-3. Publishes to npm as `@softspark/ai-toolkit@X.Y.Z` with `--provenance` (SLSA v1 build attestation)
+```bash
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
+REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
+FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
+diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
+```
 
-**Provenance is non-negotiable.** If `id-token: write` permission or the `--provenance` flag is missing from `publish.yml`, fix it BEFORE tagging — an unsigned release is a regression against the v2.8.0 standard.
+**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
 
-**After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
-to smoke-test the published package AND verify the provenance attestation landed on npm.
+### 9.7 Claude Chat / Cowork plugin validates and exports
+
+```bash
+python3 scripts/claude_app.py verify
+D=/tmp/aitk-claude-app-${RANDOM}
+python3 scripts/claude_app.py export --output "$D.zip" --no-custom-rules
+python3 -c "import zipfile; z=zipfile.ZipFile('$D.zip'); assert '.claude-plugin/plugin.json' in z.namelist(); assert 'claude-app/skills/ai-toolkit-rules/SKILL.md' in z.namelist(); print('OK: Claude app archive')"
+```
+
+**Verify:** the official validator exits 0; the archive contains the manifest,
+app-native rules skill, bundled agents/skills, and plugin-relative Cowork hooks.
 
 ---
 
-## Rollback
+## Phase 10: Explicit DSH Qualification (v4.30.0+)
 
-If a bad release was published:
+Run this phase whenever the release changes the `dsh` target, package pins, preset lifecycle, or DSH compatibility documentation. Use a new task-specific `DSH_HOME`; never replace `HOME` or reuse a regular profile.
+
+Prerequisites: DSH `0.1.1-rc.2`, pnpm `>=11.7.0,<12.0.0`, Codex logged in through ChatGPT, Claude Code logged in natively, and GitHub Copilot CLI logged in natively. Do not supply provider API keys.
 
 ```bash
-# Unpublish from npm (within 72h)
-npm unpublish @softspark/ai-toolkit@X.Y.Z
+DSH_SMOKE_ROOT="$(mktemp -d)"
+export DSH_HOME="$DSH_SMOKE_ROOT/dsh-home"
 
-# Or deprecate (preferred — doesn't break existing installs)
-npm deprecate @softspark/ai-toolkit@X.Y.Z "Known issue: <description>. Use vA.B.C instead."
+ai-toolkit dsh install --profile web
+ai-toolkit dsh doctor --profile web
+dsh --profile web --host 127.0.0.1 --port 0 --no-open
+```
 
-# Delete tag
-git tag -d vX.Y.Z
-git push origin --delete vX.Y.Z
+In a new `softspark-orchestrator` session, select the `codex` provider and run two standalone marker prompts:
+
+1. `subagent_claude_code` returns an exact child marker, then the Codex parent returns its exact completion marker.
+2. `subagent_gemini_copilot` returns an exact child marker, then the Codex parent returns its exact completion marker.
+
+Stop DSH, then remove only the managed profile artifacts:
+
+```bash
+ai-toolkit dsh uninstall --profile web --yes
 ```
 
+**Verify:** both tool results have `isError=false`, both turns end as `completed`, `doctor` reports no recovery requirement before uninstall, and an unrelated preset fixture remains unchanged. Preserve only redacted event sequence evidence; never attach credentials, auth files, or full private prompts.
+
 ---
 
-## Checklist Summary
+## Troubleshooting
 
-| # | Step | Command / Action | Pass Criteria |
-|---|------|-----------------|---------------|
-| 0a | Ecosystem drift check | `ecosystem_doctor.py --format text` | All tools Clean, or drift classified and resolved |
-| 0b | Ecosystem snapshot refresh | `ecosystem_doctor.py --update` | `benchmarks/ecosystem-doctor-snapshot.json` updated |
-| 0c | Ecosystem gate | `ecosystem_doctor.py --offline --check` | Exit 0 |
-| 1 | Version bump type | Decide patch/minor/major | — |
-| 2 | `package.json` version | Edit `"version"` | Matches target |
-| 3 | `manifest.json` version | Edit `"version"` | Matches target |
-| 4 | `plugin.json` version | Edit `"version"` | Matches target |
-| 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
-| 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
-| 7 | CHANGELOG.md | Add release entry (incl. `Ecosystem` subsection if any B/D/E/F drift) | Entry exists for vX.Y.Z |
-| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_llms_txt.py` | No unexpected diff |
-| 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
-| 10 | Security audit (CI mode) | `audit_skills.py --ci` | 0 HIGH |
-| 11 | Security audit (SARIF) | `audit_skills.py --sarif` | Valid SARIF 2.1.0 JSON |
-| 12 | Per-skill permissions | `audit_skills.py --permissions` | New broad-access skills justified in CHANGELOG |
-| 13 | ShellCheck hooks | `shellcheck --severity=warning app/hooks/*.sh` | Exit 0, no output (mirrors ci.yml; publish.yml does NOT run it) |
-| 14 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
-| 15 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
-| 15a | Licensing gate | `npx bats tests/test_licensing.bats` | 7/7 — SPDX headers, LICENSE, NOTICE, npm `files`, manifest consistency |
-| 16 | Tests | `git add -A kb/` if the KB changed, then `npm test` | All pass |
-| 17 | Commit | `git commit` | Clean working tree |
-| 18 | Push branch | `git push origin main` | Exact release commit is on `origin/main` |
-| 18a | Full branch CI | `gh run watch "$RUN_ID" --exit-status` plus matrix job assertions | Ubuntu and macOS Bats jobs both conclude `success` |
-| 19 | Tag | `git tag vX.Y.Z` | Tag exists only after green branch CI |
-| 19a | Tag is on tested SHA | `test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA"` | Exit 0 |
-| 19b | Tag is on the release commit | `git show --no-patch --format=%s vX.Y.Z` | Reads `chore: release vX.Y.Z` |
-| 20 | Push the single tag | `git push origin refs/tags/vX.Y.Z` | Publish CI triggered with `id-token: write`. Never `--tags`. |
+### `ai-toolkit: command not found`
 
----
+```bash
+npm install -g @softspark/ai-toolkit
+# or check PATH:
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
 
-## kb/procedures/release-verification-sop.md
+### Doctor: broken symlinks
 
----
-title: "SOP: Release Verification"
-category: procedures
-service: ai-toolkit
-tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif, dsh]
-version: "1.8.0"
-created: "2026-04-08"
-last_updated: "2026-09-01"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, explicit DSH lifecycle, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
----
+```bash
+ai-toolkit doctor --fix    # auto-repair
+ai-toolkit update          # or full re-install
+```
 
-# SOP: Release Verification
+### Tests fail: missing bats
 
-End-to-end smoke test after installing or updating `@softspark/ai-toolkit`.
-Verifies all critical paths from the user's perspective.
+```bash
+brew install bats-core     # macOS
+npm install -g bats        # cross-platform
+```
 
-**Use this SOP when:**
-- After `npm install -g @softspark/ai-toolkit@latest`
-- After `ai-toolkit update`
-- Before tagging a new version (`git tag`)
-- Before publishing to npm (`npm publish`)
-- As a smoke test in CI/CD
+### validate.py: stale counts
 
-**Prerequisites:**
-- Node.js >= 18, Python 3, `bats`, git
-- `@softspark/ai-toolkit` installed globally
+README badges don't match the current agents/skills/tests counts.
+Update README.md and re-run.
 
-**Time:** 10-15 minutes (full), 2 minutes (quick checklist)
+### Eject: missing skills
+
+```bash
+ai-toolkit update          # re-link missing symlinks
+ai-toolkit eject /tmp/test # retry
+```
 
 ---
 
-## Quick Checklist (TL;DR)
+## Success Criteria
 
-The 14 core commands below must pass. Releases that change DSH must also complete Phase 10.
+| Area | Criterion |
+|------|-----------|
+| CLI | `--version` correct, `--help` full list, `status` current |
+| Health | `doctor`: 0 errors, 0 warnings, PASSED |
+| Install | `--dry-run` correct counts, `--local` all configs |
+| Quality | `validate.py --strict`: PASSED |
+| Security (baseline) | `audit_skills.py --ci`: 0 HIGH |
+| Security (SARIF) | `audit_skills.py --sarif`: valid SARIF 2.1.0 with non-empty rules array |
+| Security (permissions) | `audit_skills.py --permissions`: broad-access skills unchanged or justified in CHANGELOG |
+| Supply chain | `dist.attestations.provenance.predicateType == https://slsa.dev/provenance/v1` on npm |
+| Supply chain | All `sources.json` URL entries carry a `sha256`; `AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run` passes |
+| Tests | `npm test`: N/N passed, 0 failures |
+| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
+| Guards | Destructive commands blocked |
+| Deep coverage | `--profile full` emits every documented native surface, including Codex agents/skills/hooks and Copilot agents/skills/hooks |
+| Profile contract | Codex skills emit at every profile without `--codex-skills`; Copilot standard emits agents, skills, instructions, prompts, and hooks |
+| Idempotence | Second `install` run produces byte-identical output in every managed path |
+| Live JSON | Every generated `.json` file on disk parses as valid JSON |
+| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |
 
-```bash
-# Pre-commit (Phase 0)
-python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
-python3 scripts/generate_llms_txt.py > llms.txt             # 2. Regenerate llms.txt
-python3 scripts/validate.py --strict                        # 3. Validation passed?
-npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 4. All tests passed? (single run, cached)
+---
 
-# Post-install verification (Phases 1-7)
-ai-toolkit --version                                        # 5. Version OK?
-ai-toolkit status                                           # 6. Status OK?
-ai-toolkit doctor                                           # 7. Health check passed?
-ai-toolkit install --dry-run                                # 8. Global install OK?
-python3 scripts/audit_skills.py --ci                        # 9. Security audit clean?
+## kb/procedures/sop-release.md
 
-# Supply-chain verification (Phase 8, v2.8.0+)
-python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 10. SARIF 2.1.0 well-formed?
-python3 scripts/audit_skills.py --permissions | head -30    # 11. Broad-access skills reviewed?
-npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 12. Provenance attested on npm?
-python3 scripts/claude_app.py verify                         # 13. Claude Chat/Cowork plugin contract valid?
+---
+title: "SOP: Release Preparation"
+category: procedures
+service: ai-toolkit
+tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
+version: "1.15.0"
+created: "2026-04-10"
+last_updated: "2026-09-02"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, branch CI, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, checksum-pin, ShellCheck, licensing, exact-tag assertions, and a green Ubuntu/macOS branch-CI gate before any release tag is created."
+---
 
-# Deep-coverage verification (Phase 9, v3.0.0+)
-META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
-diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
+# SOP: Release Preparation
+
+Complete checklist for preparing a new `@softspark/ai-toolkit` release.
+Run this **before** tagging. After tagging and publishing, run the
+[Release Verification SOP](sop-release-verification.md) to smoke-test.
+
+**Pipeline:**
+```
+Ecosystem Sync SOP (drift check + generator updates)
+      ↓
+Release Preparation (this SOP)
+      ↓
+git tag → CI publish → Release Verification SOP
 ```
 
----
+**Time:** 10-20 minutes (includes ecosystem sync review)
 
-## Phase 0: Pre-Commit & Pre-Push (2 min)
+---
 
-Run these commands **before every commit and push to main**. CI validates
-counts but does NOT auto-regenerate — you must do it locally.
+## Quick Checklist (TL;DR)
 
 ```bash
-# 1. Regenerate generated artifacts
+# 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
+#    Full procedure: kb/procedures/sop-ecosystem-sync.md
+python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
+cat /tmp/eco-report.txt
+# If drift detected: stop here, follow sop-ecosystem-sync.md Phase 2-4 to
+# classify each drift (A-F), update generators as needed, refresh snapshot,
+# THEN resume this SOP.
+python3 scripts/ecosystem_doctor.py --update    # after all drift resolved
+
+# 1. Decide version bump
+#    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
+#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag, any ecosystem-class-B/F change
+#    major (1.4.2 → 2.0.0): breaking change, any ecosystem-class-D removed path
+
+# 2. Sync version across all files
+python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
+
+# 3. Write CHANGELOG.md entry
+# 4. Regenerate artifacts
 python3 scripts/generate_agents_md.py > AGENTS.md
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
-# 2. Validate everything (catches stale counts, missing assets)
-python3 scripts/validate.py --strict
+# 5. Validate + audit + SARIF + shellcheck + test + ecosystem check
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && shellcheck --severity=warning app/hooks/*.sh && npm test
 
-# 3. Security audit
-python3 scripts/audit_skills.py --ci
+# 5a. Supply-chain standard (v2.8.0+) — non-negotiable
+grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --provenance"; exit 1; }
+grep -q 'id-token: write'   .github/workflows/publish.yml || { echo "MISSING id-token: write"; exit 1; }
+python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footprint
 
-# 4. Run tests
-npm test
+# 5b. Ecosystem gate — snapshot must be current before tag
+python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }
 
-# 5. Stage and commit
-# AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated and
-# gitignored — do NOT commit them (regenerated at prepublishOnly). Only the
-# doc artifacts llms.txt / llms-full.txt are committed.
-git add llms.txt llms-full.txt
-git add -p  # stage your other changes
-git commit -m "feat: your change description"
-```
+# 5c. Licensing gate — SPDX headers, LICENSE, NOTICE, manifest consistency
+npx bats tests/test_licensing.bats || { echo "LICENSING GATE FAILED"; exit 1; }
 
-**Why local?** Branch protection on `main` requires PRs and status checks.
-CI cannot push directly to `main`, so generated artifacts must be committed
-by the developer as part of their PR.
+# 6. Commit, push branch, and wait for the exact commit's full CI
+git add -A && git commit -m "chore: release vX.Y.Z"
+RELEASE_SHA=$(git rev-parse HEAD)
+git push origin main || { echo "FAIL: release commit push failed"; exit 1; }
+RUN_ID=""
+for ATTEMPT in 1 2 3 4 5; do
+  RUN_ID=$(gh run list --workflow ci.yml --event push --commit "$RELEASE_SHA" \
+    --limit 1 --json databaseId --jq '.[0].databaseId')
+  [ -n "$RUN_ID" ] && break
+  echo "Waiting for CI run registration ($ATTEMPT/5)" >&2
+  [ "$ATTEMPT" -eq 5 ] || sleep 60
+done
+test -n "$RUN_ID" || { echo "FAIL: CI run not found for release commit"; exit 1; }
+gh run watch "$RUN_ID" --exit-status \
+  || { echo "FAIL: release commit CI failed"; exit 1; }
+for OS in ubuntu-latest macos-latest; do
+  gh run view "$RUN_ID" --json jobs \
+    --jq ".jobs[] | select(.name == \"Bats test suite ($OS)\") | .conclusion" \
+    | grep -qx success || { echo "FAIL: $OS test job not green"; exit 1; }
+done
+test "$(git rev-parse HEAD)" = "$RELEASE_SHA" || { echo "FAIL: local HEAD changed during CI"; exit 1; }
+git fetch origin main || { echo "FAIL: origin/main refresh failed"; exit 1; }
+test "$(git rev-parse origin/main)" = "$RELEASE_SHA" || { echo "FAIL: origin/main changed during CI"; exit 1; }
 
-**One-liner (copy-paste):**
-```bash
-python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+# 6a. Only green branch CI authorizes tag creation
+git tag vX.Y.Z "$RELEASE_SHA"
+
+# 6b. Assert the tag before pushing it (v4.19.0 postmortem, Phase 7)
+test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA" || { echo "FAIL: tag not on tested release commit"; exit 1; }
+git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" || { echo "FAIL: tag not on release commit"; exit 1; }
+
+# 6c. Push the single tag by full ref. Never --tags.
+git push origin refs/tags/vX.Y.Z
 ```
 
 ---
 
-## Phase 1: CLI & Version (1 min)
+## Phase 0: Ecosystem Sync (MANDATORY for minor/major)
 
-```bash
-ai-toolkit --version
-ai-toolkit --help
-which ai-toolkit
-```
+Before touching version numbers, confirm the toolkit is aligned with the current state of every editor / platform it integrates with. Skipping this phase ships a release whose generators may lag a month-old CLI refactor, a rename of `.cursorrules` to `.cursor/rules/`, or a new hook event we do not yet emit.
 
-**Verify:**
-- [ ] `--version` returns correct semver (e.g., `1.4.0`)
-- [ ] `--help` displays full command list without errors
-- [ ] `which` points to global npm bin path
+**When this phase is mandatory:**
+- Minor release (X.Y.0) — always
+- Major release (X.0.0) — always
+- Patch release (X.Y.Z) — only if the patch touches a generator or install flow
 
----
+**When to skip:** pure doc-only patches, SOP edits, internal refactors that do not touch `scripts/generate_*` or `app/skills/*/SKILL.md`.
 
-## Phase 2: Global Install & Status (2 min)
+### 0.1 Run the doctor
 
 ```bash
-ai-toolkit install --dry-run
-ai-toolkit status
+python3 scripts/ecosystem_doctor.py --format text | tee /tmp/eco-report.txt
 ```
 
-**Verify `--dry-run`:**
-- [ ] Agents: 44
-- [ ] Skills: 108
-- [ ] Hooks merged into settings.json
-- [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.
+Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.
 
-**Verify `status`:**
-- [ ] Version matches expected
-- [ ] Profile: minimal/standard/strict
-- [ ] Modules: list of installed modules
-- [ ] Latest: up to date / update available
+### 0.2 Act on drift
 
----
+For each drifting tool, follow [sop-ecosystem-sync.md](sop-ecosystem-sync.md) Phase 2-4:
 
-## Phase 3: Doctor Health Check (1 min)
+| Drift class | Release impact |
+|-------------|----------------|
+| A (cosmetic reword) | No version impact — refresh snapshot, continue |
+| B (new feature — integrate) | **Minor** version bump at minimum; new generator or extended generator |
+| C (new feature — not adopted) | No impact — note in registry |
+| D (deprecation) | **Minor** or **major** depending on user impact; add migration warning |
+| E (feature promoted to default) | **Minor**; simplify generator, keep fallback comment |
+| F (feature newly globally available) | **Minor**; may require new generator or new config path |
+
+If any B/D/E/F changes land in this preparation pass, mention them explicitly in the CHANGELOG entry (Phase 3) under a `Ecosystem` subsection.
+
+### 0.3 Refresh snapshot
+
+Once every drift is resolved (either by code change or by re-classifying as acceptable):
 
 ```bash
-ai-toolkit doctor
+python3 scripts/ecosystem_doctor.py --update
 ```
 
-**Expected sections (all OK):**
-- Environment: node, bash, python3, bats
-- Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
-- Hook Scripts: all present and executable
-- Hook Configuration: 14 events registered
-- Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
-- Planned Assets: plugin.json, benchmarks, plugin packs
-- Benchmark Freshness: < 30 days
-- Stale Rules: all healthy
+This writes the new baseline to `benchmarks/ecosystem-doctor-snapshot.json`. Commit it as part of the release commit.
 
-**Verify:**
-- [ ] `Errors: 0 | Warnings: 0`
-- [ ] `HEALTH CHECK PASSED`
+### 0.4 Gate
 
-If doctor detects problems: `ai-toolkit doctor --fix` auto-repairs
-(broken symlinks, non-executable hooks, missing scripts, missing llms-full.txt).
+```bash
+python3 scripts/ecosystem_doctor.py --offline --check
+```
+
+Must exit `0`. If it exits `1`, the snapshot is stale — rerun Phase 0.3 or review the remaining drift.
 
 ---
 
-## Phase 4: Local Install (2 min)
+## Phase 1: Determine Version Bump
 
-```bash
-mkdir -p /tmp/ai-toolkit-verify && cd /tmp/ai-toolkit-verify
-git init -q
-ai-toolkit install --local --editors all --dry-run
-cd - && rm -rf /tmp/ai-toolkit-verify
-```
+Follow [Semantic Versioning](https://semver.org/):
 
-**Verify "Project-local" section:**
-- [ ] Would create: CLAUDE.md
-- [ ] Would create: .claude/settings.local.json
-- [ ] Would inject: .claude/constitution.md
-- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
-- [ ] Would generate configs for each editor (legacy + directory-based)
-- [ ] Would install: .git/hooks/pre-commit
-- [ ] Would inject language rules (auto-detected)
+| Change Type | Bump | Examples |
+|-------------|------|---------|
+| Bugfix, typo, doc-only | **patch** | Fix install flag, correct description |
+| New feature, skill, agent, flag | **minor** | Add `/hipaa-validate`, add `--output json` |
+| Breaking CLI change, removed skill, config format change | **major** | Rename `install` to `setup`, remove skill |
 
-**Also test auto-detect (no --editors flag):**
-```bash
-ai-toolkit install --local --dry-run
-# → Editors: none (empty project has no existing configs)
-```
+**Rule:** When in doubt, bump minor.
 
 ---
 
-## Phase 5: Validation & Security Audit (3 min)
+## Phase 2: Sync Version in All Files
 
-```bash
-python3 scripts/validate.py --strict
-python3 scripts/audit_skills.py --ci
-```
+The canonical version lives in `package.json`. These files **must** match:
 
-**Verify validate.py:**
-- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
-- [ ] Hook events: 14, Hook scripts: >= 30
-- [ ] Plugin packs >= 10, KB documents >= 20
-- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
+### Mandatory sync (every release)
 
-**Verify audit_skills.py:**
-- [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
-- [ ] `WARN: 0`
-- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, workflow)
+| File | Field | How to update |
+|------|-------|---------------|
+| `package.json` | `"version": "X.Y.Z"` | Edit directly |
+| `manifest.json` | `"version": "X.Y.Z"` | Edit directly |
+| `app/.claude-plugin/plugin.json` | `"version": "X.Y.Z"` | Edit directly |
 
----
+### Auto-synced (no manual action)
 
-## Phase 6: Tests (3-5 min)
+| File | Mechanism |
+|------|-----------|
+| `package-lock.json` | Regenerated by `npm install --package-lock-only` |
+
+### Conditional sync (only if the doc was modified in this release)
+
+| File | Field | When to update |
+|------|-------|---------------|
+| `kb/procedures/sop-maintenance.md` | frontmatter `version:` | If SOP content changed |
+| `kb/reference/skills-catalog.md` | frontmatter `version:` | If skills added/removed |
+| `kb/reference/agents-catalog.md` | frontmatter `version:` | If agents added/removed |
+| `kb/reference/hooks-catalog.md` | frontmatter `version:` | If hooks changed |
+| `kb/reference/architecture-overview.md` | frontmatter `version:` | If architecture changed |
+| `kb/reference/distribution-model.md` | frontmatter `version:` | If install model changed |
+| `kb/reference/global-install-model.md` | frontmatter `version:` | If install model changed |
+
+> **Note:** KB `version:` fields track the **document version**, not the toolkit version.
+> Only bump them when the document content actually changes in this release.
+
+### Count sync (if skills/agents/hooks changed)
+
+| File | What to check |
+|------|---------------|
+| `package.json` | `"description"` — skill/agent count |
+| `README.md` | Badge counts, "What You Get" table |
+| `app/ARCHITECTURE.md` | Section headings with counts |
+
+> **Tip:** `validate.py --strict` catches count drift AND version mismatches
+> (package.json vs manifest.json vs plugin.json) automatically.
+> If validation passes, counts and versions are correct.
+
+### Verification command
+
+After syncing, verify all mandatory files match:
 
 ```bash
-# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
-# re-running it per check (tail / grep ok / grep not ok piped separately)
-# wastes minutes every release. Always cache the output.
-npm test > /tmp/npm-test.log 2>&1
-exit=$?
-tail -3 /tmp/npm-test.log
-echo "ok:     $(grep -c '^ok '    /tmp/npm-test.log)"
-echo "not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
-echo "exit:   $exit"
+VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
+echo "Target: $VERSION"
+echo "manifest.json:     $(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")"
+echo "plugin.json:       $(python3 -c "import json; print(json.load(open('app/.claude-plugin/plugin.json'))['version'])")"
+echo "package-lock.json: $(python3 -c "import json; print(json.load(open('package-lock.json'))['version'])")"
 ```
 
-**Verify:**
-- [ ] `exit == 0`
-- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
-- [ ] `not ok == 0`
-- [ ] Bats runs tests in parallel (4 jobs)
-- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
-      install, kb, mcp, readme, profiles, uninstall, validate
+All four must print the same version. If not, fix before proceeding.
+
+### Public surface review
 
-**Anti-pattern — do NOT do this:**
 ```bash
-# Runs the full suite THREE times. Adds 1-3 min and pressures CI capacity.
-npm test 2>&1 | tail -3
-npm test 2>&1 | grep -c '^ok '
-npm test 2>&1 | grep -c '^not ok'
+python3 scripts/surface_manifest.py --update
+git diff app/surface.json
 ```
 
-**Key test areas:**
-- Guards: rm -rf, DROP TABLE, git push --force blocked
-- Install: idempotent, profiles, --only/--skip, orphan cleanup
-- Eject: real files (not symlinks), inlined rules
-- Uninstall: removes toolkit, preserves user content
+**Every line the diff removes is a breaking change.** Restore it, or take the
+deprecation path in `BACKWARD_COMPATIBILITY.md` and add a `DECISIONS.md` entry
+before the tag. Lines added are new surface being adopted into protection — that
+needs no ceremony.
 
----
+Do not run `--update` to make a red build green. The check fails because something
+users depend on disappeared; regenerating the manifest deletes the evidence, not
+the problem.
 
-## Phase 7: Eject (1 min)
+### Skill body budget ratchet
 
-```bash
-mkdir -p /tmp/ai-toolkit-eject-test
-cd /tmp/ai-toolkit-eject-test
-ai-toolkit eject
-cd - && rm -rf /tmp/ai-toolkit-eject-test
+`validate.py` prints the largest skill body on every run:
+
+```
+Body budget: largest is <skill> at <N> bytes (warn 18000, error 20000)
 ```
 
-**Verify:**
-- [ ] Agents copied as real files (not symlinks)
-- [ ] Skills copied as real directories
-- [ ] Rules inlined into CLAUDE.md
-- [ ] constitution.md and ARCHITECTURE.md copied
-- [ ] `output-styles/` directory present (v2.7.1+)
+Once that number sits at least 2000 bytes under `SKILL_BODY_BUDGET_WARN`, lower
+`SKILL_BODY_BUDGET_WARN` by 2000 in `scripts/validate.py` and ship the tightened
+threshold with the release. Target floor is 12000.
 
----
+Two rules, both learned the hard way:
 
-## Phase 8: Supply-Chain Verification (2 min, v2.8.0+)
+- **Never lower a threshold in the same change that something violates it.** Split
+  the offending skill into `SKILL.md` + `reference/` first, prove it with
+  `python3 scripts/check_split.py <skill> --before <pre-split SKILL.md>`, then
+  tighten in a follow-up.
+- **Never raise a threshold to make a red build green.** A body over budget means
+  detail that belongs in `reference/` is loading on every trigger match, including
+  the accidental ones. Raising the number hides the cost, it does not remove it.
 
-These checks enforce the v2.8.0 security standard on a freshly-published release. Run AFTER the `publish.yml` workflow completes on the tag.
+If the largest body has not moved since the previous release, leave the threshold
+alone and say so in the release notes. A ratchet that never advances is honest;
+one that advances past reality is not.
 
-### 8.1 Provenance attestation on npm
+---
 
-```bash
-VERSION="X.Y.Z"                                           # the tag just published
-npm view "@softspark/ai-toolkit@${VERSION}" --json \
-  | python3 -c "import json, sys; d=json.load(sys.stdin); att=d['dist'].get('attestations', {}); assert att.get('provenance', {}).get('predicateType') == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE for {d[\"version\"]}'; print(f'PROVENANCE OK: {att[\"url\"]}')"
-```
+## Phase 3: Write CHANGELOG Entry
 
-**Verify:**
-- [ ] Exit 0 and prints `PROVENANCE OK: https://registry.npmjs.org/...`
-- [ ] `https://www.npmjs.com/package/@softspark/ai-toolkit/v/${VERSION}` shows the green "Provenance" badge
+Add entry at the top of `CHANGELOG.md` (after the header, before previous release):
 
-**If provenance is missing:** the `publish.yml` ran without `id-token: write` or `--provenance`. Restore them and cut a patch release — a silently unsigned publish is a regression against the v2.8.0 standard.
+```markdown
+## vX.Y.Z — Short Title (YYYY-MM-DD)
 
-### 8.2 Audit SARIF output (for GHAS ingest)
+### Added
+- **Feature name** — description
 
-```bash
-python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif
-python3 -c "import json; d=json.load(open('/tmp/audit.sarif')); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']=='ai-toolkit-audit-skills'; print(f'SARIF OK: {len(d[\"runs\"][0][\"results\"])} results across {len(d[\"runs\"][0][\"tool\"][\"driver\"][\"rules\"])} rules')"
+### Changed
+- **What changed** — old behavior → new behavior
+
+### Fixed
+- **Bug description** — what was broken and how it's fixed
+
+### Removed
+- **What was removed** — migration path if any
 ```
 
-**Verify:**
-- [ ] Valid SARIF 2.1.0
-- [ ] In the publishing repo, the CI job uploads `audit.sarif` via `github/codeql-action/upload-sarif@v3` so findings appear in the Security tab
+**Rules:**
+- Use **bold** for feature names
+- Start descriptions with a verb (Added, Changed, Fixed, Removed)
+- Reference skill names with backticks and slash: `/hipaa-validate`
+- Include script names: `scripts/hipaa_scan.py`
+- Include count changes: `Skill count: 91 → 92`
+- Date format: `YYYY-MM-DD`
+- Title: short, descriptive, no version number repetition
 
-### 8.3 Per-skill permissions report
+### Update README "What's New" section
 
-```bash
-python3 scripts/audit_skills.py --permissions | head -40
-```
+**MANDATORY on every release.** Update the `## What's New in vX.Y.Z` section in `README.md`:
 
-**Verify:**
-- [ ] Bash skill count has NOT jumped unexpectedly since the previous release
-- [ ] Any newly added entry under `Skills with Bash + Write + Edit` matches a CHANGELOG bullet that justifies the broad scope
-- [ ] JSON form (`--permissions --json`) is available for automated drift dashboards
+1. Change the heading version: `## What's New in vX.Y.Z`
+2. Replace bullet points with 3-5 highlights from this release
+3. **Keep only the latest version block.** Delete the previous `## What's New in vA.B.C` section(s). README is the shop window, not the archive — users see the current release, full history lives in `CHANGELOG.md`.
+4. Keep the `See [CHANGELOG.md](CHANGELOG.md) for full history.` link directly below the bullet list.
 
-### 8.4 URL-sourced rules/hooks are checksum-pinned
+> **Warning:** This section is the first thing users see after the badges.
+> A stale version here (e.g., "What's New in v2.1.3" when shipping v2.3.0)
+> signals an unmaintained project. Do NOT skip this step.
 
-`sources.json` is an envelope of the form `{"schema_version": 1, "rules"|"hooks": {...}}`, so the jq filter must pick the nested map before piping into the pin assertion. The URL-count in the success message ignores local `path:`-only entries — only entries with a `url:` field are pinned and counted.
+> **Single-version rule:** README.md must contain **exactly one** `## What's New in vX.Y.Z` heading at any time. If you find multiple stacked (e.g. v2.6.1 + v2.6.0 + v2.5.0), that is a SOP drift — collapse to the latest on the next release commit.
+
+---
+
+## Phase 4: Regenerate Artifacts
+
+Use the npm scripts, not the generators directly:
 
 ```bash
-jq '.rules // .hooks // {}' ~/.softspark/ai-toolkit/rules/sources.json 2>/dev/null \
-  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'RULE PIN OK: {url_n} URL rules, all with sha256')"
-jq '.hooks // {}' ~/.softspark/ai-toolkit/hooks/external/sources.json 2>/dev/null \
-  | python3 -c "import json, sys; d=json.load(sys.stdin) or {}; bad=[n for n,v in d.items() if v.get('url') and not v.get('sha256')]; assert not bad, f'UNPINNED: {bad}'; url_n=sum(1 for v in d.values() if v.get('url')); print(f'HOOK PIN OK: {url_n} URL hooks, all with sha256')"
+npm run generate:agents   # AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_agents_md.py > AGENTS.md
+npm run generate:llms     # llms.txt + llms-full.txt
 ```
 
-**Verify:**
-- [ ] Both commands print `... PIN OK`
-- [ ] If any entry is unpinned, the `register_url_source()` call missed passing `content=` — fix the call-site and retag
+`generate:agents` sets `AI_TOOLKIT_NO_CUSTOM_RULES=1`. Running
+`generate_agents_md.py` bare picks up whatever is registered in the maintainer's
+own `~/.softspark/ai-toolkit/rules/`, which then ships inside `AGENTS.md`.
 
-### 8.5 Strict-pin smoke test (optional but recommended)
+Check if anything actually changed:
 
 ```bash
-AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
+git diff --stat AGENTS.md llms.txt llms-full.txt
 ```
 
-**Verify:**
-- [ ] Exit 0, no `CHECKSUM CHANGED` line
-- [ ] If a checksum change was intentional (e.g. upstream rule update), document it in the CHANGELOG entry before tagging
+If no diff, the artifacts are already current. If there is a diff, stage them.
 
 ---
 
-## Phase 9: Deep-Coverage Checks (v3.0.0+)
+## Phase 5: Validate, Audit, Test
 
-These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
+Run the full quality gate:
 
-> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
+python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
 
-### 9.1 `--profile full` emits every native surface
+# ShellCheck on hooks (added in 1.11.0). Mirrors the ci.yml "ShellCheck hooks"
+# job. NOT run by validate.py, npm test, OR publish.yml — so a hook with a
+# ShellCheck warning passes every other gate AND still publishes on tag while
+# turning main CI red. Run it here, before tagging.
+shellcheck --severity=warning app/hooks/*.sh && echo "OK: shellcheck clean"
 
-```bash
-D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot \
-  --profile full --dry-run 2>&1 \
-  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.devin/hooks\\.v1\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/(agents|hooks)|\\.agents/skills|\\.github/(agents|skills|instructions|prompts|hooks)"
+# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
+diff \
+  <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
+  <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
+  && echo "OK: registry matches filesystem" \
+  || { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
+
+# Stage first IF this release adds or deletes a kb/ file. The test
+# "npm package KB files match the tracked release set" compares `git ls-files
+# kb` (the index) against what `npm pack` sees (the working tree), so an
+# unstaged addition reads as "extra" and an unstaged deletion as "missing".
+# Phase 6 stages, and it runs after this one, so the ordering fails the test
+# for any release that touches the KB. Staging early costs nothing.
+git status --porcelain kb/ | grep -qE '^(\?\?| D|\?M)' && git add -A kb/
+
+# Run npm test ONCE, cache output, parse from file. The suite is 1400+ bats
+# cases — rerunning it per check wastes minutes. Do not pipe npm test into
+# tail/grep multiple times in the same session.
+npm test > /tmp/npm-test.log 2>&1
+tail -3 /tmp/npm-test.log
+echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
 ```
 
-**Verify** — at least the following lines appear:
-- [ ] `.cursor/hooks.json` and `.cursor/agents/`
-- [ ] `.devin/hooks.v1.json`
-- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
-- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
-- [ ] `.codex/hooks.json` + `.codex/hooks/` + `.codex/agents/`
-- [ ] `.agents/skills/` (Codex native discovery path)
-- [ ] `.github/agents/` + `.github/skills/` + `.github/instructions/` + `.github/prompts/` + `.github/hooks/`
+**Expected results:**
+- `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
+- `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
+- `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
+- `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
+- `shellcheck --severity=warning app/hooks/*.sh`: no output, exit 0. A common false positive is `SC2034` on `INPUT` or env vars (e.g. `AI_TOOLKIT_HOOK_FORMAT`) that a *sourced* helper (`_hook-io.sh`) consumes — ShellCheck cannot see cross-file use. Fix with a `# shellcheck disable=SC2034` directive or `export`, matching `guard-destructive.sh`. Never tag with a red ShellCheck.
+- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
+- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
 
-### 9.2 Codex skills are profile-independent
+> **Why this matters (v4.5.1 postmortem):** `publish.yml` runs only `validate.py` + `npm test`, so it published v4.5.0 even though the `main` CI `ShellCheck hooks` job was red on two `SC2034` warnings in a new hook. The publish workflow does **not** depend on the CI workflow. Until that is fixed, ShellCheck is a manual pre-tag gate — run it here every time.
 
+**One-liner:**
 ```bash
-D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors codex --profile minimal --dry-run 2>&1 \
-  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills emit at minimal"
-ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
-  | grep -q "Would refresh: .agents/skills" && echo "OK: legacy flag explicitly refreshes the same catalog"
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && shellcheck --severity=warning app/hooks/*.sh && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py|generate_language_rules_skills\.py' | sort -u) && npm test
 ```
 
-**Verify:**
-- [ ] Selecting Codex emits all skills under `.agents/skills/` at every profile
-- [ ] `--codex-skills` remains an explicit refresh alias; it is not required for installation
-- [ ] No profile emits `.codex/skills/`
+**If tests fail:** Fix the issue, do NOT skip. Common failures:
+- Stale counts → re-run `generate:all` or fix README/ARCHITECTURE
+- Missing frontmatter → add to new KB docs
+- Broken symlink → `ai-toolkit doctor --fix`
 
-### 9.3 Breaking-change surfaces land on `--profile standard`
+### Phase 5c: Licensing Gate (v4.20.0+)
 
-The standard profile must include:
-- Copilot scoped instructions, prompts, custom agents, portable skills, and hooks
-- Gemini hooks (`.gemini/settings.json`)
+The project is Apache-2.0. Attribution only works if the artefact actually
+carries it, and every part of that is mechanically checkable.
 
 ```bash
-D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
-  | tee /tmp/aitk-breaking.log
-grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
-grep -q "\\.github/agents/.*\\.github/skills/" /tmp/aitk-breaking.log && echo "OK: Copilot agents and skills at standard"
-grep -q "\\.github/hooks/" /tmp/aitk-breaking.log && echo "OK: Copilot hooks at standard"
-grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
+# The whole gate, enforced in CI. Run it here so a failure is caught before tagging.
+npx bats tests/test_licensing.bats
+```
+
+The seven assertions, and why each exists:
+
+| Check | Fails when |
+|---|---|
+| Every shipped source file carries an SPDX header | A new `.py`/`.sh`/`.js`/`.bats` file was added without one — the common case, and the reason this is a test rather than a habit |
+| Headers name Apache-2.0 and nothing else | A file was copied in from an MIT/GPL source with its own header intact |
+| **No** markdown file carries an SPDX header | Someone "helpfully" ran the header script over `app/skills/` — headers there sit above parsed frontmatter and bill every session for it |
+| `LICENSE` is the complete Apache 2.0 text | The file was truncated or replaced with a summary |
+| `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice | The attribution mechanism was gutted |
+| `LICENSE` **and** `NOTICE` ship in the npm package | `package.json` `files` lost an entry — a NOTICE that never reaches the consumer cannot satisfy §4(d) |
+| Every manifest declaring a licence declares Apache-2.0 | `package.json`, `manifest.json`, `plugin.json` and `package-lock.json` drifted apart |
+
+**Adding source files in this release?** The header goes *after* the shebang,
+never before it. Short SPDX form:
+
+```
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
 ```
 
-**Verify all four lines print `OK:`**. If any is missing, native Copilot or Gemini coverage has regressed.
+`//` for JavaScript. Full convention and the reasoning behind the markdown
+exclusion: [Licensing](../reference/licensing.md).
 
-### 9.4 Install is idempotent
+**Changing the licence itself?** Do not hand-type the licence text. Take it
+verbatim from a published copy and cross-verify against a second independent
+copy before writing `LICENSE` — a rendered or summarised licence is not the
+licence. Prior releases stay under their original terms; a licence change
+applies going forward and revokes nothing already granted.
+
+### Phase 5a: Supply-Chain Hardening Verification (v2.8.0+)
+
+These checks enforce the security standard introduced in v2.8.0. Do NOT tag a release until all pass.
+
+**1. Publish workflow emits provenance:**
 
 ```bash
-D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-# Sort file paths before hashing — find traversal order follows inode order,
-# which can shift between runs even when content is byte-identical, producing
-# false FAIL signals.
-ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA1=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
-ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
-SHA2=$(find .cursor .gemini -type f -print0 | LC_ALL=C sort -z | xargs -0 shasum | shasum | awk '{print $1}')
-[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
+grep -E '\-\-provenance|id-token: write' .github/workflows/publish.yml
 ```
 
-**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
-
-### 9.5 Live-install JSON outputs parse
+- [ ] Both markers present (`--provenance` flag + `id-token: write` permission)
+- [ ] Any PR that changes `publish.yml` REQUIRES an approved security review
 
-The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
+**2. URL-sourced rules and hooks are checksum-pinned:**
 
 ```bash
-D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
-for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
-  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
-done
+# On a machine that has consumed URL rules/hooks at least once
+# (schema_version 1: entries live under the .rules / .hooks key):
+jq '.rules | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/rules/sources.json
+jq '.hooks | to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/hooks/external/sources.json
 ```
 
-**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
-
-### 9.6 Registry / generator drift check
+- [ ] Both queries return empty arrays (every URL entry has a `sha256`)
+- [ ] If not, run `ai-toolkit update` to backfill missing hashes before tagging
 
-`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
+**3. Audit SARIF output is well-formed:**
 
 ```bash
-META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
-REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
-FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
-diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
+python3 scripts/audit_skills.py --sarif | python3 -c "import json, sys; d=json.load(sys.stdin); assert d['version']=='2.1.0' and d['runs'][0]['tool']['driver']['name']; print('SARIF OK')"
 ```
 
-**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
+- [ ] Prints `SARIF OK`
+- [ ] If the script ever grows new rule classes, extend the SARIF `rules[]` coverage before releasing
 
-### 9.7 Claude Chat / Cowork plugin validates and exports
+**4. Strict-pin mode passes on CI** (optional, recommended for stable branches):
 
 ```bash
-python3 scripts/claude_app.py verify
-D=/tmp/aitk-claude-app-${RANDOM}
-python3 scripts/claude_app.py export --output "$D.zip" --no-custom-rules
-python3 -c "import zipfile; z=zipfile.ZipFile('$D.zip'); assert '.claude-plugin/plugin.json' in z.namelist(); assert 'claude-app/skills/ai-toolkit-rules/SKILL.md' in z.namelist(); print('OK: Claude app archive')"
+AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 ```
 
-**Verify:** the official validator exits 0; the archive contains the manifest,
-app-native rules skill, bundled agents/skills, and plugin-relative Cowork hooks.
+- [ ] Exit 0, no `CHECKSUM CHANGED` line
+- [ ] Any unexpected upstream change blocks the release until explicitly approved
 
 ---
 
-## Phase 10: Explicit DSH Qualification (v4.30.0+)
-
-Run this phase whenever the release changes the `dsh` target, package pins, preset lifecycle, or DSH compatibility documentation. Use a new task-specific `DSH_HOME`; never replace `HOME` or reuse a regular profile.
+## Phase 6: Commit
 
-Prerequisites: DSH `0.1.1-rc.2`, pnpm `>=11.7.0,<12.0.0`, Codex logged in through ChatGPT, Claude Code logged in natively, and GitHub Copilot CLI logged in natively. Do not supply provider API keys.
+Stage all release files:
 
 ```bash
-DSH_SMOKE_ROOT="$(mktemp -d)"
-export DSH_HOME="$DSH_SMOKE_ROOT/dsh-home"
-
-ai-toolkit dsh install --profile web
-ai-toolkit dsh doctor --profile web
-dsh --profile web --host 127.0.0.1 --port 0 --no-open
+git add package.json manifest.json app/.claude-plugin/plugin.json
+git add package-lock.json
+git add CHANGELOG.md
+git add llms.txt llms-full.txt
+# NOTE: AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are generated
+# editor configs and are gitignored — do NOT commit them. `prepublishOnly` runs
+# `npm run generate:all`, so the shipped package (which lists AGENTS.md in
+# package.json `files`) gets a fresh copy at publish time.
+git add -p  # review and stage any other changes
 ```
 
-In a new `softspark-orchestrator` session, select the `codex` provider and run two standalone marker prompts:
+Commit:
 
-1. `subagent_claude_code` returns an exact child marker, then the Codex parent returns its exact completion marker.
-2. `subagent_gemini_copilot` returns an exact child marker, then the Codex parent returns its exact completion marker.
+```bash
+git commit -m "chore: release vX.Y.Z"
+```
 
-Stop DSH, then remove only the managed profile artifacts:
+---
+
+## Phase 7: Push Branch, Verify CI, Tag, and Push Tag
 
 ```bash
-ai-toolkit dsh uninstall --profile web --yes
-```
+RELEASE_SHA=$(git rev-parse HEAD)
+git push origin main || { echo "FAIL: release commit push failed"; exit 1; }
 
-**Verify:** both tool results have `isError=false`, both turns end as `completed`, `doctor` reports no recovery requirement before uninstall, and an unrelated preset fixture remains unchanged. Preserve only redacted event sequence evidence; never attach credentials, auth files, or full private prompts.
+# Bind the gate to the exact release commit. GitHub run registration is
+# asynchronous, so retry at most five times and log every attempt.
+RUN_ID=""
+for ATTEMPT in 1 2 3 4 5; do
+  RUN_ID=$(gh run list --workflow ci.yml --event push --commit "$RELEASE_SHA" \
+    --limit 1 --json databaseId --jq '.[0].databaseId')
+  [ -n "$RUN_ID" ] && break
+  echo "Waiting for CI run registration ($ATTEMPT/5)" >&2
+  [ "$ATTEMPT" -eq 5 ] || sleep 60
+done
+test -n "$RUN_ID" || { echo "FAIL: CI run not found for release commit"; exit 1; }
+gh run watch "$RUN_ID" --exit-status \
+  || { echo "FAIL: release commit CI failed"; exit 1; }
 
----
+# publish.yml is Ubuntu-only. Require both full CI matrix jobs before creating
+# the tag so a green publish job cannot bypass a red macOS test.
+for OS in ubuntu-latest macos-latest; do
+  gh run view "$RUN_ID" --json jobs \
+    --jq ".jobs[] | select(.name == \"Bats test suite ($OS)\") | .conclusion" \
+    | grep -qx success || { echo "FAIL: $OS test job not green"; exit 1; }
+done
 
-## Troubleshooting
+# Refuse to tag if either local or remote main moved while CI was running.
+test "$(git rev-parse HEAD)" = "$RELEASE_SHA" \
+  || { echo "FAIL: local HEAD changed during CI"; exit 1; }
+git fetch origin main || { echo "FAIL: origin/main refresh failed"; exit 1; }
+test "$(git rev-parse origin/main)" = "$RELEASE_SHA" \
+  || { echo "FAIL: origin/main changed during CI"; exit 1; }
 
-### `ai-toolkit: command not found`
+git tag vX.Y.Z "$RELEASE_SHA"
 
-```bash
-npm install -g @softspark/ai-toolkit
-# or check PATH:
-export PATH="$(npm config get prefix)/bin:$PATH"
+# Assert the tag before pushing it. Both checks are one line each and both
+# have caught a real broken release.
+test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA" \
+  || { echo "FAIL: tag is not on the tested release commit"; exit 1; }
+git show --no-patch --format=%s vX.Y.Z | grep -qx "chore: release vX.Y.Z" \
+  || { echo "FAIL: tag is not on the chore: release commit"; exit 1; }
+
+# Push the single release tag by its full ref.
+git push origin refs/tags/vX.Y.Z
 ```
 
-### Doctor: broken symlinks
+**Why branch CI comes before the tag (v4.30.2 postmortem).** The publish
+workflow runs only on Ubuntu and can publish while the separate macOS matrix job
+is red. `v4.30.2` exposed this with a macOS-only DSH timing failure. A release
+commit must therefore pass the complete Ubuntu/macOS branch workflow before its
+tag exists; a successful publish workflow is not a substitute for green CI.
 
-```bash
-ai-toolkit doctor --fix    # auto-repair
-ai-toolkit update          # or full re-install
-```
+**Why the assertions (v4.19.0 postmortem).** v4.19.0 was tagged on a commit
+that contained only a KB document and still carried `package.json` version
+`4.18.0`; the actual release sat in the commit above it under a recycled
+`fix:` message. `publish.yml` fired, tried to publish a version already on
+npm, and failed. Nothing on npm, a tag pointing at the wrong tree, and the
+only way out was rewriting a pushed commit. Both assertions above catch this
+in under a second. Run them.
 
-### Tests fail: missing bats
+**Never `git push --tags`.** It pushes every local tag at once, and GitHub
+suppresses tag-triggered workflow runs when many tags arrive in a single push
+— the workflow silently does not fire and nothing publishes. Push the single
+release tag by its full ref, as above. (Sibling evidence: this is exactly how
+rag-mcp's `1.0.3` image build was skipped, when a `--tags` push carried 37
+tags at once.)
 
-```bash
-brew install bats-core     # macOS
-npm install -g bats        # cross-platform
-```
+This triggers `.github/workflows/publish.yml` which:
+1. Runs `validate.py --strict`
+2. Runs `npm test`
+3. Publishes to npm as `@softspark/ai-toolkit@X.Y.Z` with `--provenance` (SLSA v1 build attestation)
 
-### validate.py: stale counts
+**Provenance is non-negotiable.** If `id-token: write` permission or the `--provenance` flag is missing from `publish.yml`, fix it BEFORE tagging — an unsigned release is a regression against the v2.8.0 standard.
 
-README badges don't match the current agents/skills/tests counts.
-Update README.md and re-run.
+**After CI completes:** Run the [Release Verification SOP](sop-release-verification.md)
+to smoke-test the published package AND verify the provenance attestation landed on npm.
 
-### Eject: missing skills
+---
+
+## Rollback
+
+If a bad release was published:
 
 ```bash
-ai-toolkit update          # re-link missing symlinks
-ai-toolkit eject /tmp/test # retry
+# Unpublish from npm (within 72h)
+npm unpublish @softspark/ai-toolkit@X.Y.Z
+
+# Or deprecate (preferred — doesn't break existing installs)
+npm deprecate @softspark/ai-toolkit@X.Y.Z "Known issue: <description>. Use vA.B.C instead."
+
+# Delete tag
+git tag -d vX.Y.Z
+git push origin --delete vX.Y.Z
 ```
 
 ---
 
-## Success Criteria
+## Checklist Summary
 
-| Area | Criterion |
-|------|-----------|
-| CLI | `--version` correct, `--help` full list, `status` current |
-| Health | `doctor`: 0 errors, 0 warnings, PASSED |
-| Install | `--dry-run` correct counts, `--local` all configs |
-| Quality | `validate.py --strict`: PASSED |
-| Security (baseline) | `audit_skills.py --ci`: 0 HIGH |
-| Security (SARIF) | `audit_skills.py --sarif`: valid SARIF 2.1.0 with non-empty rules array |
-| Security (permissions) | `audit_skills.py --permissions`: broad-access skills unchanged or justified in CHANGELOG |
-| Supply chain | `dist.attestations.provenance.predicateType == https://slsa.dev/provenance/v1` on npm |
-| Supply chain | All `sources.json` URL entries carry a `sha256`; `AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run` passes |
-| Tests | `npm test`: N/N passed, 0 failures |
-| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
-| Guards | Destructive commands blocked |
-| Deep coverage | `--profile full` emits every documented native surface, including Codex agents/skills/hooks and Copilot agents/skills/hooks |
-| Profile contract | Codex skills emit at every profile without `--codex-skills`; Copilot standard emits agents, skills, instructions, prompts, and hooks |
-| Idempotence | Second `install` run produces byte-identical output in every managed path |
-| Live JSON | Every generated `.json` file on disk parses as valid JSON |
-| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |
+| # | Step | Command / Action | Pass Criteria |
+|---|------|-----------------|---------------|
+| 0a | Ecosystem drift check | `ecosystem_doctor.py --format text` | All tools Clean, or drift classified and resolved |
+| 0b | Ecosystem snapshot refresh | `ecosystem_doctor.py --update` | `benchmarks/ecosystem-doctor-snapshot.json` updated |
+| 0c | Ecosystem gate | `ecosystem_doctor.py --offline --check` | Exit 0 |
+| 1 | Version bump type | Decide patch/minor/major | — |
+| 2 | `package.json` version | Edit `"version"` | Matches target |
+| 3 | `manifest.json` version | Edit `"version"` | Matches target |
+| 4 | `plugin.json` version | Edit `"version"` | Matches target |
+| 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
+| 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
+| 7 | CHANGELOG.md | Add release entry (incl. `Ecosystem` subsection if any B/D/E/F drift) | Entry exists for vX.Y.Z |
+| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_llms_txt.py` | No unexpected diff |
+| 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
+| 10 | Security audit (CI mode) | `audit_skills.py --ci` | 0 HIGH |
+| 11 | Security audit (SARIF) | `audit_skills.py --sarif` | Valid SARIF 2.1.0 JSON |
+| 12 | Per-skill permissions | `audit_skills.py --permissions` | New broad-access skills justified in CHANGELOG |
+| 13 | ShellCheck hooks | `shellcheck --severity=warning app/hooks/*.sh` | Exit 0, no output (mirrors ci.yml; publish.yml does NOT run it) |
+| 14 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
+| 15 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
+| 15a | Licensing gate | `npx bats tests/test_licensing.bats` | 7/7 — SPDX headers, LICENSE, NOTICE, npm `files`, manifest consistency |
+| 16 | Tests | `git add -A kb/` if the KB changed, then `npm test` | All pass |
+| 17 | Commit | `git commit` | Clean working tree |
+| 18 | Push branch | `git push origin main` | Exact release commit is on `origin/main` |
+| 18a | Full branch CI | `gh run watch "$RUN_ID" --exit-status` plus matrix job assertions | Ubuntu and macOS Bats jobs both conclude `success` |
+| 19 | Tag | `git tag vX.Y.Z` | Tag exists only after green branch CI |
+| 19a | Tag is on tested SHA | `test "$(git rev-parse vX.Y.Z)" = "$RELEASE_SHA"` | Exit 0 |
+| 19b | Tag is on the release commit | `git show --no-patch --format=%s vX.Y.Z` | Reads `chore: release vX.Y.Z` |
+| 20 | Push the single tag | `git push origin refs/tags/vX.Y.Z` | Publish CI triggered with `id-token: write`. Never `--tags`. |
 
 ---
 
@@ -9801,7 +9908,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 46 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 51 |
 
 ## Multi-Agent Execution
 
@@ -11738,7 +11845,7 @@ running the generators directly:
 
 - `scripts/generate_copilot.py` / `generate_copilot_hooks.py` contract tests
   (`tests/test_copilot.bats`, `tests/test_copilot_hooks.bats`).
-- Release layout check in `kb/procedures/release-verification-sop.md` asserts the
+- Release layout check in `kb/procedures/sop-release-verification.md` asserts the
   `.github/{agents,skills,instructions,prompts,hooks}` surfaces.
 - `validate.py --strict` + `audit_skills.py --ci` in CI.
 
@@ -14313,7 +14420,7 @@ MIT remnant would need each contributor's agreement.
 
 It is a test rather than a checklist line on purpose. This project has two
 same-day postmortems about SOPs that existed and were skipped; CI does not skip.
-[Release Preparation](../procedures/release-preparation-sop.md) Phase 5c runs the
+[Release Preparation](../procedures/sop-release.md) Phase 5c runs the
 same gate before tagging so a failure surfaces before the tag, not after.
 
 ## If the licence ever changes again
@@ -14326,7 +14433,7 @@ source, cross-verify against a second independent copy, and only then write
 ## Related
 
 - [`LICENSE`](../../LICENSE), [`NOTICE`](../../NOTICE)
-- [Release Preparation SOP](../procedures/release-preparation-sop.md) — Phase 5c
+- [Release Preparation SOP](../procedures/sop-release.md) — Phase 5c
 - [Distribution Model](distribution-model.md) — what ships and where
 
 ---
@@ -16006,7 +16113,7 @@ Updated baseline docs:
 - `kb/reference/skills-catalog.md`
 - `kb/reference/plugin-pack-conventions.md`
 - `kb/reference/claude-ecosystem-benchmark-snapshot.md`
-- `kb/procedures/maintenance-sop.md`
+- `kb/procedures/sop-maintenance.md`
 
 ## Validation Evidence
 
@@ -16860,13 +16967,13 @@ See [DSH Compatibility](./dsh-compatibility.md) for commands, topology, subscrip
 2. Delete its section from this document.
 3. Delete its snapshot entry from `benchmarks/ecosystem-doctor-snapshot.json` (or let the next `--update` prune it — currently not pruned automatically).
 4. Decide whether to keep the generator (`scripts/generate_<tool>_*.py`) for backwards compatibility or delete it.
-5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/maintenance-sop.md` `Supported editors` line.
+5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/sop-maintenance.md` `Supported editors` line.
 
 ---
 
 ## Related
 
-- [Ecosystem Sync SOP](../procedures/ecosystem-sync-sop.md) — how to use the doctor
+- [Ecosystem Sync SOP](../procedures/sop-ecosystem-sync.md) — how to use the doctor
 - [MCP Editor Compatibility](./mcp-editor-compatibility.md) — MCP-specific subset
 - `scripts/ecosystem_tools.json` — source of truth
 - `scripts/ecosystem_doctor.py` — drift detector
@@ -17399,7 +17506,7 @@ Expect `Total plugin skills loaded: 0`, `Total plugin agents loaded: 0`, and the
 ## Related
 
 - `kb/reference/global-install-model.md`
-- `kb/procedures/maintenance-sop.md`
+- `kb/procedures/sop-maintenance.md`
 
 ---