@softspark/ai-toolkit 4.19.1 → 4.21.0

package/kb/procedures/release-preparation-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
-version: "1.11.2"
+version: "1.13.0"
 created: "2026-04-10"
 last_updated: "2026-07-27"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, 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, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, the registry-vs-generators drift gate added in v1.10.0, and the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5)."
+description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, 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, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, the registry-vs-generators drift gate added in v1.10.0, the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5), the pre-push tag assertions added in v1.12.0 after v4.19.0 was tagged on the wrong commit (Phase 7), and the licensing gate added in v1.13.0 with the move to Apache-2.0 (Phase 5c)."
 ---
 
 # SOP: Release Preparation
@@ -65,10 +65,20 @@ python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footpri
 # 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 + tag + push
 git add -A && git commit -m "chore: release vX.Y.Z"
 git tag vX.Y.Z
-git push origin main --tags
+
+# 6a. Assert the tag before pushing it (v4.19.0 postmortem, Phase 7)
+test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)" || { echo "FAIL: tag not on HEAD"; 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; }
+
+# 6b. Branch first, then the single tag by full ref. Never --tags.
+git push origin main
+git push origin refs/tags/vX.Y.Z
 ```
 
 ---
@@ -332,6 +342,46 @@ 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 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.
+
+```bash
+# 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
+```
+
+`//` for JavaScript. Full convention and the reasoning behind the markdown
+exclusion: [Licensing](../reference/licensing.md).
+
+**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.
@@ -405,9 +455,34 @@ git commit -m "chore: release vX.Y.Z"
 
 ```bash
 git tag vX.Y.Z
-git push origin main --tags
+
+# 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)" = "$(git rev-parse HEAD)" \
+  || { echo "FAIL: tag is not on HEAD"; 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 branch, then the single release tag by its full ref.
+git push origin main
+git push origin refs/tags/vX.Y.Z
 ```
 
+**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.
+
+**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.)
+
 This triggers `.github/workflows/publish.yml` which:
 1. Runs `validate.py --strict`
 2. Runs `npm test`
@@ -460,7 +535,10 @@ git push origin --delete vX.Y.Z
 | 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 | Tag | `git tag vX.Y.Z` | Tag exists |
-| 19 | Push | `git push origin main --tags` | CI triggered with `id-token: write` |
+| 18a | Tag is on HEAD | `test "$(git rev-parse vX.Y.Z)" = "$(git rev-parse HEAD)"` | Exit 0 |
+| 18b | Tag is on the release commit | `git show --no-patch --format=%s vX.Y.Z` | Reads `chore: release vX.Y.Z` |
+| 19 | Push branch, then the single tag | `git push origin main && git push origin refs/tags/vX.Y.Z` | CI triggered with `id-token: write`. Never `--tags`. |

package/kb/reference/comparison.md

@@ -24,6 +24,6 @@ description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and
 | Session persistence | Yes | Yes | No | No |
 | Architecture notes | **Yes** | No | No | No |
 | KB/RAG integration | **Yes** | No | No | Yes |
-| License | MIT | MIT | MIT | MIT |
+| License | **Apache-2.0** (NOTICE attribution, change notices, patent grant) | MIT | MIT | MIT |
 
 For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).

package/kb/reference/enterprise-config-guide.md

@@ -137,7 +137,7 @@ Base configs can define non-overridable constraints via the `enforce` block:
 {
   "enforce": {
     "minHookProfile": "standard",
-    "requiredPlugins": ["security-pack"],
+    "requiredPlugins": ["memory-pack"],
     "forbidOverride": ["constitution", "guard-destructive"],
     "requiredAgents": ["security-auditor"]
   }

package/kb/reference/licensing.md

@@ -0,0 +1,148 @@
+---
+title: "Licensing"
+category: reference
+service: ai-toolkit
+tags: [licence, apache-2.0, spdx, notice, attribution, headers, mit]
+version: "1.0.0"
+created: "2026-07-27"
+last_updated: "2026-07-27"
+description: "ai-toolkit is Apache-2.0 from v4.20.0. What that obliges a redistributor to do, why NOTICE is the point, the SPDX header convention and which files deliberately do not get one, how MIT-era contributions are handled, and the CI gate that enforces all of it."
+---
+
+# Licensing
+
+ai-toolkit is licensed under the **Apache License 2.0** from v4.20.0. Releases up
+to and including v4.20.0 were published under MIT and remain available under MIT.
+The change applies going forward and revokes nothing already granted.
+
+Canonical files: [`LICENSE`](../../LICENSE) (verbatim Apache-2.0 text) and
+[`NOTICE`](../../NOTICE) (attribution).
+
+## Why Apache-2.0, given MIT already required attribution
+
+This is the part most often got wrong. MIT already says:
+
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+
+So attribution was never the new thing. What Apache-2.0 adds:
+
+| Mechanism | MIT | Apache-2.0 |
+|---|---|---|
+| Copyright notice must be preserved | yes | yes |
+| **`NOTICE` contents must travel into redistributions** (§4d) | — | **yes** |
+| **Modified files must carry a notice saying they changed** (§4b) | — | **yes** |
+| Express patent grant, terminated by patent litigation (§3) | — | yes |
+| No rights to the licensor's names or marks (§6) | — | yes |
+
+**`NOTICE` is the reason for the change.** It is the only mechanism in a
+permissive licence that forces a redistributor to reproduce your attribution —
+project name, copyright, source URL — somewhere their users can see it. Without
+it, MIT and Apache-2.0 are close to equivalent in practice.
+
+Consequence for packaging: `NOTICE` is listed in `package.json` `files`. A NOTICE
+that does not reach the consumer cannot satisfy §4(d), so that entry is a
+licensing requirement, not housekeeping, and is asserted in CI.
+
+## What a fork owes
+
+Fork it, modify it, ship it commercially. Three obligations:
+
+1. **Carry the `NOTICE`** into your distribution (§4d).
+2. **Say which files you changed** (§4b).
+3. **Do not use the "ai-toolkit" or "SoftSpark" names or marks** as if endorsed (§6).
+
+## Source header convention
+
+Short SPDX form, three lines, always **after** the shebang — an interpreter
+directive must stay on line 1 — and after a Python `coding:` line if present:
+
+```bash
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+#
+# guard-path.sh — the file's own description continues here.
+```
+
+`//` for JavaScript. SPDX was chosen over the 13-line Apache APPENDIX boilerplate
+because it is machine-readable — licence scanners, GitHub and SBOM tooling parse
+it — and because 13 lines on top of every source file buries the description that a
+reader of a hook actually needs.
+
+### Which files get a header
+
+| Included | Count |
+|---|---:|
+| `scripts/**/*.py` | 109 |
+| `tests/*.bats` | 77 |
+| `app/hooks/*.sh` | 32 |
+| `app/skills/**/*.py`, `**/*.js` | 27 |
+| `app/plugins/**/*.sh`, `**/*.py` | 6 |
+| `bin/*.js`, `benchmarks/**/*.py` | 2 |
+| **total** | **253** |
+
+These are a snapshot, not a contract — the CI gate checks that *every* matching
+file has a header, so the count moves with the codebase and nothing needs
+updating here when it does.
+
+### Which files deliberately do not, and why
+
+**No markdown file carries a header.** Not `app/skills/*/SKILL.md`, not
+`app/agents/*.md`, not `app/rules/`, not `kb/`. Two reasons, both concrete:
+
+1. **Frontmatter.** Skill and agent files open with parsed YAML. A header above
+   it breaks parsing; a header below it is invisible where it matters.
+2. **Token cost.** Skill and agent descriptions load into the system prompt of
+   every session — measured at 5,051 and 2,750 tokens respectively. A four-line
+   header across 108 skills and 45 agents would be a permanent per-session cost,
+   billed on every conversation forever, for a notice Apache only *recommends*.
+   `LICENSE` and `NOTICE` carry the full terms; the headers are a convenience.
+
+This exclusion is asserted in CI, so a well-meant sweep of the header script over
+`app/skills/` fails the build rather than silently taxing every session.
+
+## MIT-era contributions
+
+Contributions made while the project was MIT-licensed remain the copyright of
+their authors and were received under MIT terms. Three contributors other than
+the maintainer appear in the history.
+
+MIT explicitly permits sublicensing, so those contributions are redistributed
+here under Apache-2.0 **with the original MIT notice preserved verbatim** in
+`NOTICE`, which is what MIT requires. This is standard practice for an MIT to
+Apache-2.0 move and needs no contributor sign-off. A "clean" Apache-2.0 with no
+MIT remnant would need each contributor's agreement.
+
+*This is a description of what the project does, not legal advice.*
+
+## Enforcement
+
+`tests/test_licensing.bats`, seven assertions, run by `npm test` in CI:
+
+- every shipped source file carries an SPDX header
+- headers name Apache-2.0 and nothing else
+- **no** markdown file carries a header
+- `LICENSE` is the complete Apache 2.0 text, appendix included
+- `NOTICE` carries attribution, the source URL, §4(d) and the MIT-era notice
+- `LICENSE` and `NOTICE` both appear in `package.json` `files`
+- every manifest declaring a licence declares Apache-2.0
+
+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
+same gate before tagging so a failure surfaces before the tag, not after.
+
+## If the licence ever changes again
+
+Do not hand-type the licence text and do not paste a rendered copy — a
+markdown-formatted licence is not the licence. Take it verbatim from a published
+source, cross-verify against a second independent copy, and only then write
+`LICENSE`. That is how the Apache-2.0 text in this repository was installed.
+
+## Related
+
+- [`LICENSE`](../../LICENSE), [`NOTICE`](../../NOTICE)
+- [Release Preparation SOP](../procedures/release-preparation-sop.md) — Phase 5c
+- [Distribution Model](distribution-model.md) — what ships and where

package/kb/reference/plugin-pack-conventions.md

@@ -125,22 +125,30 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 
 ## Current Experimental Packs
 
-| Pack | Domain | Agents | Skills | Hooks | Description |
-|------|--------|--------|--------|-------|-------------|
-| `security-pack` | security | 3 | 3 | 2 | Security auditing, threat modeling, OWASP |
-| `research-pack` | research | 4 | 4 | 1 | Multi-source research, synthesis, fact-checking |
-| `frontend-pack` | frontend | 3 | 3 | 1 | React/Vue/CSS, SEO, design engineering |
-| `enterprise-pack` | enterprise | 3 | 3 | 3 | Executive briefings, infra architecture, status |
-| `memory-pack` | memory | 0 | 1 | 2 | SQLite persistent memory with FTS5 search |
-| `rust-pack` | rust | 0 | 1 | 0 | Rust patterns |
-| `java-pack` | java | 0 | 1 | 0 | Java patterns |
-| `csharp-pack` | csharp | 0 | 1 | 0 | C# patterns |
-| `kotlin-pack` | kotlin | 0 | 1 | 0 | Kotlin patterns |
-| `swift-pack` | swift | 0 | 1 | 0 | Swift patterns |
-| `ruby-pack` | ruby | 0 | 1 | 0 | Ruby patterns |
-
-Every pack here is content that ships in this repository. None fetches anything
-at install time.
+| Pack | Domain | Owns | Installs (claude / codex) | Description |
+|------|--------|------|---------------------------|-------------|
+| `memory-pack` | memory | 2 hooks, 2 scripts, 1 skill | 4 / 4 files | SQLite persistent memory with FTS5 search |
+| `enterprise-pack` | enterprise | 2 hooks | 2 / 2 files | Status-line and output-style overlays |
+
+Both packs ship content in this repository. Neither fetches anything at install
+time.
+
+### The rule the table now enforces
+
+**A pack must install files the core install does not.** `ai-toolkit install`
+links every core skill and agent, so a manifest naming only core assets resolves
+to nothing: `plugin install` reports `(0 file items)` and no file appears on
+disk. This is not a subtle degradation — it is a complete no-op, identical on
+every profile (`minimal`, `standard`, `strict`) and on both runtimes.
+
+Nine packs were removed in v4.20.0 for failing this: `csharp`, `java`, `kotlin`,
+`ruby`, `rust`, `swift`, `frontend`, `research`, `security`. Every one declared
+only skills and agents that already ship in core, and eight of them owned nothing
+but a `README.md`. Full measurement:
+[`no-op-plugin-packs-removed-20260727.md`](../history/completed/no-op-plugin-packs-removed-20260727.md).
+
+Before adding a pack, prove it does something: install core into a throwaway
+`HOME`, install the pack, and check that the reported file count is above zero.
 
 **A pack that downloads a binary has been tried once and retired.** `rtk-pack`
 (v4.18.0, removed in v4.19.0) fetched a checksum-pinned artifact in