@softspark/ai-toolkit 2.7.3 → 2.9.0

package/llms-full.txt

@@ -61,68 +61,68 @@
 - **a11y-validate**: Validate code against accessibility standards: WCAG 2.1 Level AA, EN 301 549, and the European Accessibility Act (EAA / Directive EU 2019/882). Covers semantics, text alternatives, keyboard/focus, color/contrast, forms, media, ARIA, motion, mobile, and EAA documentation requirements. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/React Native/Flutter/static HTML).
 - **agent-creator**: Creates new specialized agents with frontmatter, tool selection, and delegation guidance
 - **analyze**: Analyze code quality, complexity, and patterns
-- **api-patterns**: Loaded when user asks about REST API design or GraphQL patterns
-- **app-builder**: Loaded when user asks to scaffold or build a full-stack app
+- **api-patterns**: REST and GraphQL API design patterns: resource naming, versioning, pagination, error contracts, idempotency, HATEOAS, OpenAPI. Triggers: API design, REST, GraphQL, endpoint, route, OpenAPI, Swagger, pagination, rate limit, versioning, idempotency key. Load when designing or reviewing any HTTP API surface.
+- **app-builder**: Full-stack app scaffolding with stack-selection matrix: Next.js, React+Vite, Nuxt, Astro, FastAPI, Django, Laravel, React Native, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter template, build app, landing page, dashboard, API, mobile app, CLI, e-commerce, game. Load when user wants to start a new project from scratch.
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling.
-- **architecture-decision**: Loaded when user asks about architecture decisions or architecture note writing
+- **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
 - **biz-scan**: Scan codebase for business opportunities and KPIs
 - **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
 - **briefing**: Generate executive daily briefing across all agents
 - **build**: Build the project with auto-detected toolchain
 - **chaos**: Inject controlled faults for resilience testing
 - **ci**: Detect and run CI pipeline with status reporting
-- **ci-cd-patterns**: Loaded when user asks about CI/CD pipelines or deployment automation
-- **clean-code**: Loaded when user asks about clean code, naming, or code quality
+- **ci-cd-patterns**: CI/CD pipeline and deployment automation: GitHub Actions, GitLab CI, Jenkins, build stages, caching, artifact promotion, blue-green, canary, rollback gates. Triggers: CI, CD, pipeline, GitHub Actions, workflow YAML, deploy automation, release, artifact, rollout, canary, blue-green. Load when designing or fixing a build/release pipeline.
+- **clean-code**: Code quality principles: meaningful names, single responsibility, DRY, small functions, clear intent, guard clauses, refactoring rules. Triggers: clean code, naming, refactor for clarity, code smell, SRP, DRY, long function, god class, magic number, dead code. Load when reviewing or writing any production code.
 - **command-creator**: Creates new Claude Code slash commands with frontmatter, workflow guidance, and validation
 - **commit**: Create Conventional Commits with pre-commit validation
 - **content-moderation-patterns**: Loaded when user builds content moderation, safety filters, or policy enforcement with Claude. Covers pre-filter vs LLM-classify, category design, confidence thresholds, and human-in-the-loop.
 - **council**: 4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'.
-- **csharp-patterns**: Loaded when user asks about C# or .NET development patterns
+- **csharp-patterns**: C# and .NET development patterns: LINQ, async/await, dependency injection, records, nullable reference types, ASP.NET Core minimal APIs, EF Core, MediatR. Triggers: C#, .NET, dotnet, ASP.NET, EF Core, LINQ, IServiceCollection, record type, async C#, nullable reference types. Load when writing or reviewing C#/.NET code.
 - **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
-- **database-patterns**: Loaded when user asks about database schema or query optimization
+- **database-patterns**: Database schema design and query optimization: normalization, indexing strategies, joins, N+1, transactions, isolation levels, partitioning, EXPLAIN plans. Triggers: schema, table design, index, slow query, N+1, PostgreSQL, MySQL, SQL Server, SQL, EXPLAIN, query plan, transaction, deadlock. Load when designing tables or tuning queries.
 - **debug**: Debug errors and trace root causes systematically
-- **debugging-tactics**: Loaded when user is debugging an issue or needs root cause analysis
+- **debugging-tactics**: Root-cause debugging with 4-phase method: investigation, hypothesis, validation, fix. No fix without RCA. Triggers: bug, error, exception, stack trace, not working, intermittent, flaky, crash, regression, fails sometimes, why is X happening, broken after. Load when user reports a bug or asks to investigate failing code.
 - **deploy**: Deploy with pre-flight checks and health verification
 - **design-an-interface**: Generate multiple radically different interface designs using parallel sub-agents, then compare on simplicity, depth, and correctness. Based on 'Design It Twice' from Ousterhout. Use when user wants to design an API, explore interface options, compare module shapes, or mentions 'design it twice'.
-- **design-engineering**: Loaded when user asks about UI animations or CSS design craft
-- **docker-devops**: Loaded when user asks about Docker, containers, or DevOps patterns
+- **design-engineering**: UI craftsmanship (Emil Kowalski school): animation frequency rules, easing curves, micro-interactions, state polish, invisible-details philosophy. Triggers: animation, transition, ease-out, ease-in-out, motion, micro-interaction, hover state, loading state, UI polish, design detail, spring curve, delightful UX. Load when building or reviewing interactive UI.
+- **docker-devops**: Docker, containers, Kubernetes, and DevOps patterns: Dockerfile best practices, multi-stage builds, compose, k8s manifests, Helm charts, service mesh, image hardening. Triggers: Docker, Dockerfile, container, image, Kubernetes, k8s, compose, Helm, registry, layer caching, service mesh, pod, deployment yaml. Load when writing or fixing container/orchestration configs.
 - **docs**: Generate and update README, API docs, and architecture notes
-- **documentation-standards**: Loaded when creating or updating KB documents, architecture notes, SOPs, or any file in kb/ directory
-- **ecommerce-patterns**: Loaded when user asks about e-commerce or shopping cart features
+- **documentation-standards**: KB document conventions: YAML frontmatter (7 required fields), 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices), directory-category matching, validate.sh CI rules. Triggers: kb/, KB document, architecture note, SOP, runbook, howto, frontmatter, knowledge base entry, documentation standard. Load when creating or editing any file under kb/.
+- **ecommerce-patterns**: E-commerce domain patterns: cart, checkout flow, payment providers (Stripe/Adyen), order state machine, inventory, promotions, tax, B2B vs B2C. Triggers: cart, checkout, product, SKU, inventory, payment, Stripe, Shopify, Medusa, Magento, order status, promotion, tax calculation, coupon, refund. Load when working on any e-commerce feature.
 - **evaluate**: Evaluate skill quality and RAG retrieval accuracy
 - **evolve**: Evolve agent definitions via meta-architect
 - **explain**: Explain code, architecture, or concepts with diagrams
 - **explore**: Explore codebase structure, stack, and architecture
 - **fix**: Auto-fix lint errors, type issues, and simple bugs
-- **flutter-patterns**: Loaded when user asks about Flutter or Dart development patterns
-- **git-mastery**: Loaded when user asks about advanced Git workflows or history rewriting
+- **flutter-patterns**: Flutter and Dart development patterns: widget composition, state management (Riverpod/Bloc/Provider), navigation, async, platform channels, performance. Triggers: Flutter, Dart, widget, StatefulWidget, Riverpod, Bloc, Provider, pubspec, Navigator, platform channel, hot reload, StatelessWidget. Load when writing or reviewing Flutter code.
+- **git-mastery**: Advanced Git workflows: interactive rebase, bisect, reflog, cherry-pick, worktrees, history rewriting, submodules, large-file migration (LFS/filter-repo). Triggers: git rebase, bisect, cherry-pick, reflog, force push, history rewrite, detached HEAD, merge conflict, worktree, squash, fixup, submodule. Load when user needs non-trivial Git operations.
 - **grill-me**: Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'.
 - **health**: Report service and infrastructure health status
 - **hipaa-validate**: Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references
-- **hive-mind**: Loaded when orchestrating multi-agent swarms or consensus workflows
+- **hive-mind**: Multi-agent swarm coordination: consensus voting with confidence scores, output aggregation, file ownership, targeted vs broadcast messaging, map-reduce workflows. Triggers: swarm, hive mind, multi-agent, consensus, parallel agents, team of agents, aggregate results, agent voting, distributed agents. Load when orchestrating 3+ agents working in parallel.
 - **hook-creator**: Creates new Claude Code hooks with guided workflow, strict conventions, and validation
 - **index**: Index codebase into the knowledge base
 - **instinct-review**: Review and manage learned instincts from past sessions
 - **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
-- **java-patterns**: Loaded when user asks about Java development patterns
+- **java-patterns**: Java development patterns: Spring Boot, CompletableFuture, records, sealed types, streams, JPA/Hibernate, Maven/Gradle, virtual threads (Loom). Triggers: Java, Spring, Spring Boot, JPA, Hibernate, Maven, Gradle, CompletableFuture, record type, sealed class, virtual thread. Load when writing or reviewing Java code.
 - **json-mode-patterns**: Loaded when user needs structured JSON output from Claude. Covers tool-use-as-JSON-mode, schema design, parsing, partial recovery, and validation.
-- **kotlin-patterns**: Loaded when user asks about Kotlin development patterns
+- **kotlin-patterns**: Kotlin development patterns: coroutines, Flow, sealed classes, data classes, extension functions, null safety, Ktor, Jetpack Compose, KMP. Triggers: Kotlin, coroutine, Flow, suspend, Ktor, Android Kotlin, Jetpack Compose, sealed class, data class, KMP, kotlinx. Load when writing or reviewing Kotlin code.
 - **lint**: Lint code with auto-detected tools and fix suggestions
 - **mcp-builder**: Build production-grade MCP (Model Context Protocol) servers from scratch using the 4-phase methodology: research, implement, test, evaluate. Use when creating new MCP integrations for external APIs, databases, or internal services.
-- **mcp-patterns**: Loaded when user asks about MCP servers or tool protocol design
+- **mcp-patterns**: MCP (Model Context Protocol) server design: tool schemas, resource patterns, transport selection (stdio/SSE), client configuration, error handling, capability negotiation. Triggers: MCP, Model Context Protocol, MCP server, MCP tool, MCP resource, JSON-RPC, stdio transport, SSE transport, Claude Desktop config, Cursor MCP. Load when building or integrating MCP servers.
 - **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
 - **migrate**: Run database migrations with backup verification
-- **migration-patterns**: Loaded when user asks about database migrations or zero-downtime deploys
+- **migration-patterns**: Zero-downtime database migration patterns: expand-contract, double-write, backfill, blue-green schema changes, feature flags, rollback safety, online DDL. Triggers: migration, schema change, zero-downtime, expand-contract, double-write, backfill, ALTER TABLE, column rename, safe deploy, online DDL. Load when planning non-trivial DB schema changes.
 - **model-routing-patterns**: Loaded when user builds multi-model pipelines (Haiku/Sonnet/Opus). Covers cost-optimized routing, escalation, sub-agent delegation, and fallback chains.
 - **night-watch**: Run autonomous maintenance and dependency updates
-- **observability-patterns**: Loaded when user asks about logging, metrics, or tracing patterns
+- **observability-patterns**: Observability: structured logging, metrics (RED/USE/four golden signals), distributed tracing (OpenTelemetry), correlation IDs, log aggregation, SLO/SLI. Triggers: logging, log level, metrics, Prometheus, Grafana, OpenTelemetry, trace, span, structured log, observability, monitoring, SLO, SLI, alerting. Load when adding or reviewing logs, metrics, or traces.
 - **onboard**: Generate project onboarding materials
 - **orchestrate**: Coordinate multiple specialized agents in parallel
 - **panic**: Emergency stabilization via system-governor agent
-- **performance-profiling**: Loaded when user asks about performance profiling or optimization
+- **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
 - **plan**: Plan implementation with tasks and success criteria
-- **plan-writing**: Loaded when user asks to write an implementation plan or pre-mortem
+- **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
 - **pr**: Create pull requests with pre-flight validation
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
@@ -130,29 +130,29 @@
 - **predict**: Predict regressions and impact before changes land
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session.
-- **rag-patterns**: Loaded when user asks about RAG systems, embeddings, or vector search
+- **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
 - **refactor**: Refactor code for quality and maintainability
 - **refactor-plan**: Create a detailed refactor plan with tiny commits via user interview, then file as a GitHub issue RFC. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
 - **repeat**: Run a prompt or slash command on a recurring interval until task complete or limits reached. Use when user wants to set up a recurring task, poll for status, or run something repeatedly on an interval.
-- **research-mastery**: Loaded when user asks to research, verify, or synthesize information
+- **research-mastery**: Hierarchical information retrieval following strict order: KB first (smart_query/crag_search), then MCP/Context7, then web search, then LLM knowledge as last resort. Triggers: research, find information, verify fact, synthesize sources, fact-check, cross-reference, multi-source, cite sources, investigate topic. Load when any task requires external or cross-source knowledge.
 - **review**: Review code for quality, security, and correctness
 - **rollback**: Roll back a deployment safely with verification
-- **ruby-patterns**: Loaded when user asks about Ruby development patterns
-- **rust-patterns**: Loaded when user asks about Rust development patterns
+- **ruby-patterns**: Ruby and Rails development patterns: blocks, metaprogramming, ActiveRecord, Sidekiq, RSpec, Sorbet/RBS, Hanami, Roda, Rack middleware. Triggers: Ruby, Rails, ActiveRecord, Sidekiq, RSpec, gem, Gemfile, bundler, rake, Hanami, Sorbet. Load when writing or reviewing Ruby code.
+- **rust-patterns**: Rust development patterns: ownership, borrowing, lifetimes, async (Tokio), error handling (Result/anyhow/thiserror), traits, macros, zero-cost abstractions, unsafe boundaries. Triggers: Rust, borrow checker, lifetime, Tokio, async Rust, cargo, trait, impl, Result, unsafe, lifetime annotation, clippy. Load when writing or reviewing Rust code.
 - **search**: Search the knowledge base with semantic and hybrid modes
-- **security-patterns**: Loaded when user asks about security, OWASP, or auth patterns
+- **security-patterns**: Application security: OWASP Top 10, authN/authZ, input validation, secrets management, TLS, CSRF/XSS/SQLi, session handling, JWT, rate limiting, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, encryption, TLS, authentication, authorization, CSP, CORS, password hashing. Load when touching auth code, handling user input, or doing security review.
 - **seo-validate**: Validate code against SEO best practices: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Supports React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML.
 - **skill-audit**: Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions
 - **skill-creator**: Create new skills from templates with guided workflow
 - **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks.
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms
-- **swift-patterns**: Loaded when user asks about Swift or iOS development patterns
+- **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation.
 - **teams**: Launch pre-configured Agent Teams for common workflows
 - **test**: Run tests with coverage analysis and reporting
-- **testing-patterns**: Loaded when user asks about testing strategy, fixtures, or mocking
+- **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan.
-- **typescript-patterns**: Loaded when user asks about TypeScript patterns or type safety
+- **typescript-patterns**: TypeScript type safety patterns: strict mode, generics, conditional types, template literals, discriminated unions, branded types, Zod, satisfies operator, const assertions. Triggers: TypeScript, TS, generics, conditional type, utility type, strict, Zod, satisfies, discriminated union, type safety, type narrowing, template literal type. Load when writing or reviewing TypeScript code.
 - **ubiquitous-language**: Extract a DDD-style ubiquitous language glossary from the conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, or mentions DDD or domain model.
 - **verification-before-completion**: Loaded when agent is about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before assertions, always.
 - **workflow**: Start and manage autonomous agent workflows
@@ -3523,11 +3523,11 @@ What `uninstall` does:
 title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
-tags: [sop, release, version, publish, changelog, semver]
-version: "1.6.0"
+tags: [sop, release, version, publish, changelog, semver, provenance, sarif]
+version: "1.7.0"
 created: "2026-04-10"
-last_updated: "2026-04-17"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
+last_updated: "2026-04-18"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0."
 ---
 
 # SOP: Release Preparation
@@ -3563,8 +3563,13 @@ python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
-# 5. Validate + audit + test
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+# 5. Validate + audit + SARIF + test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && 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
 
 # 6. Commit + tag + push
 git add -A && git commit -m "chore: release vX.Y.Z"
@@ -3721,17 +3726,21 @@ Run the full quality gate:
 ```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
 npm test
 ```
 
 **Expected results:**
 - `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
-- `audit_skills.py`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
+- `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
 - `npm test`: `1..N` with zero `not ok`
 
 **One-liner:**
 ```bash
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:
@@ -3739,6 +3748,48 @@ python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci &&
 - Missing frontmatter → add to new KB docs
 - Broken symlink → `ai-toolkit doctor --fix`
 
+### 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
+grep -E '\-\-provenance|id-token: write' .github/workflows/publish.yml
+```
+
+- [ ] Both markers present (`--provenance` flag + `id-token: write` permission)
+- [ ] Any PR that changes `publish.yml` REQUIRES an approved security review
+
+**2. URL-sourced rules and hooks are checksum-pinned:**
+
+```bash
+# On a machine that has consumed URL rules/hooks at least once:
+jq 'to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/rules/sources.json
+jq 'to_entries | map(select(.value.url != null and (.value.sha256 // "" | length) == 0))' ~/.softspark/ai-toolkit/hooks/external/sources.json
+```
+
+- [ ] Both queries return empty arrays (every URL entry has a `sha256`)
+- [ ] If not, run `ai-toolkit update` to backfill missing hashes before tagging
+
+**3. Audit SARIF output is well-formed:**
+
+```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')"
+```
+
+- [ ] Prints `SARIF OK`
+- [ ] If the script ever grows new rule classes, extend the SARIF `rules[]` coverage before releasing
+
+**4. Strict-pin mode passes on CI** (optional, recommended for stable branches):
+
+```bash
+AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
+```
+
+- [ ] Exit 0, no `CHECKSUM CHANGED` line
+- [ ] Any unexpected upstream change blocks the release until explicitly approved
+
 ---
 
 ## Phase 6: Commit
@@ -3771,10 +3822,12 @@ git push origin main --tags
 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`
+3. Publishes to npm as `@softspark/ai-toolkit@X.Y.Z` with `--provenance` (SLSA v1 build attestation)
+
+**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.
 
 **After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
-to smoke-test the published package.
+to smoke-test the published package AND verify the provenance attestation landed on npm.
 
 ---
 
@@ -3809,11 +3862,15 @@ git push origin --delete vX.Y.Z
 | 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
 | 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_codex_rules.py`, `generate_llms_txt.py` | No unexpected diff |
 | 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
-| 10 | Security audit | `audit_skills.py --ci` | 0 HIGH |
-| 11 | Tests | `npm test` | All pass |
-| 12 | Commit | `git commit` | Clean working tree |
-| 13 | Tag | `git tag vX.Y.Z` | Tag exists |
-| 14 | Push | `git push origin main --tags` | CI triggered |
+| 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 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
+| 14 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
+| 15 | Tests | `npm test` | All pass |
+| 16 | Commit | `git commit` | Clean working tree |
+| 17 | Tag | `git tag vX.Y.Z` | Tag exists |
+| 18 | Push | `git push origin main --tags` | CI triggered with `id-token: write` |
 
 ---
 
@@ -3823,11 +3880,11 @@ git push origin --delete vX.Y.Z
 title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
-tags: [sop, verification, release, smoke-test, install, update, qa]
-version: "1.1.0"
+tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
+version: "1.2.0"
 created: "2026-04-08"
-last_updated: "2026-04-13"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, and eject from user perspective."
+last_updated: "2026-04-18"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard."
 ---
 
 # SOP: Release Verification
@@ -3852,7 +3909,7 @@ Verifies all critical paths from the user's perspective.
 
 ## Quick Checklist (TL;DR)
 
-10 commands — if all pass, the release is ready:
+13 commands — if all pass, the release is ready:
 
 ```bash
 # Pre-commit (Phase 0)
@@ -3868,6 +3925,11 @@ ai-toolkit status                                           # 7. Status OK?
 ai-toolkit doctor                                           # 8. Health check passed?
 ai-toolkit install --dry-run                                # 9. Global install OK?
 python3 scripts/audit_skills.py --ci                        # 10. Security audit clean?
+
+# 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')"   # 11. SARIF 2.1.0 well-formed?
+python3 scripts/audit_skills.py --permissions | head -30    # 12. 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')"   # 13. Provenance attested on npm?
 ```
 
 ---
@@ -4051,6 +4113,72 @@ cd - && rm -rf /tmp/ai-toolkit-eject-test
 - [ ] Skills copied as real directories
 - [ ] Rules inlined into CLAUDE.md
 - [ ] constitution.md and ARCHITECTURE.md copied
+- [ ] `output-styles/` directory present (v2.7.1+)
+
+---
+
+## Phase 8: Supply-Chain Verification (2 min, v2.8.0+)
+
+These checks enforce the v2.8.0 security standard on a freshly-published release. Run AFTER the `publish.yml` workflow completes on the tag.
+
+### 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\"]}')"
+```
+
+**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
+
+**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.
+
+### 8.2 Audit SARIF output (for GHAS ingest)
+
+```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')"
+```
+
+**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
+
+### 8.3 Per-skill permissions report
+
+```bash
+python3 scripts/audit_skills.py --permissions | head -40
+```
+
+**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
+
+### 8.4 URL-sourced rules/hooks are checksum-pinned
+
+```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}'; print(f'RULE PIN OK: {len(d)} 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}'; print(f'HOOK PIN OK: {len(d)} URL hooks, all with sha256')"
+```
+
+**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
+
+### 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
+- [ ] If a checksum change was intentional (e.g. upstream rule update), document it in the CHANGELOG entry before tagging
 
 ---
 
@@ -4100,9 +4228,13 @@ ai-toolkit eject /tmp/test # retry
 | Health | `doctor`: 0 errors, 0 warnings, PASSED |
 | Install | `--dry-run` correct counts, `--local` all configs |
 | Quality | `validate.py --strict`: PASSED |
-| Security | `audit_skills.py --ci`: 0 HIGH |
+| 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 |
+| Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
 | Guards | Destructive commands blocked |
 
 ---

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.7.3",
+  "version": "2.9.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.7.3",
-  "description": "Professional-grade AI coding toolkit: 99 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, opencode), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "2.9.0",
+  "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
     "claude-code",
@@ -77,7 +77,6 @@
     "llms-full.txt"
   ],
   "engines": {
-    "node": ">=18.0.0",
-    "bats": ">=1.8.0 — install via: brew install bats-core (macOS) or apt install bats (Ubuntu)"
+    "node": ">=18.0.0"
   }
 }

package/scripts/add_rule.py

@@ -68,7 +68,7 @@ def main() -> None:
 
         dest = rules_dir / f"{rule_name}.md"
         dest.write_bytes(data)
-        register_url_source(rules_dir, rule_name, source)
+        register_url_source(rules_dir, rule_name, source, content=data)
 
         print(f"Registered: '{rule_name}' -> {dest}")
         print(f"Source URL: {source} (auto-refreshed on update)")