release(v0.2.0): bump versions, finalize changelog, implement the release-check gate

.github/workflows/release-check.yml

@@ -0,0 +1,32 @@
+name: Release gate — version sync · changelog · CLI docs
+
+# Deterministic release-readiness gate (see ai/lab/specs/SPEC_release-check.md).
+# Runs on every v* tag push (tag mode: the script reads GITHUB_REF and requires
+# tag == package.json version, a dated changelog section, and an emptied
+# [Unreleased]) and on demand via workflow_dispatch (pre-tag mode).
+# Zero third-party actions; the script itself is dependency-free Node.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # the coverage report diffs HEAD against the previous tag
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Release checks (version-sync · changelog-gate · coverage · cli-docs-sync)
+        run: node test/release-check.mjs
+      - name: Smoke tests
+        run: node test/run-tests.mjs
+      - name: Verify knowledge-layer path claims
+        run: node install.mjs verify . --strict

.github/workflows/release.yml

@@ -27,7 +27,7 @@ jobs:
         with:
           node-version: 20
           registry-url: "https://registry.npmjs.org"
-      - name: Smoke tests (both installers)
+      - name: Smoke tests
         run: node test/run-tests.mjs
       - name: Verify tag matches package.json version
         run: |

CHANGELOG.md

@@ -6,76 +6,35 @@ Format: [Keep a Changelog](https://keepachangelog.com/) · Versioning: [SemVer](
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-07-03
+
+Node-only runtime, hash-verified incremental re-runs with a child-lock protecting human-verified work, native GitHub Copilot and Google Antigravity support, a major test-suite hardening pass, a docs overhaul, and a deterministic release gate.
+
 ### Removed
-- **Python installer removed — the kit is now Node.js-only.** `install.py` and the
-  parallel Python modules (`lib/*.py`) are gone; `install.mjs` + `lib/*.mjs`
-  (Node.js ≥ 18, stdlib only, zero dependencies) is the single implementation.
-  Maintaining two feature-identical runtimes doubled the cost of every change and
-  risked silent behavior drift between them. Nothing changes for target repos:
-  Python projects are still fully supported by stack detection (`orient`),
-  `indepth` analysis, and all knowledge-layer features — only the runtime that
-  executes the kit itself now requires Node. CI and the smoke-test suite run
-  Node-only accordingly.
+- **Python installer** (`install.py`, `lib/*.py`) — the kit is now Node.js-only (`install.mjs` + `lib/*.mjs`, Node ≥ 18, stdlib, zero dependencies); Python **target** repos remain fully supported by `orient`/`indepth` and all knowledge-layer features.
 
 ### Added
-- **Incremental, hash-verified re-runs with a "child-lock" for human work.**
-  `install`/`shazam` re-runs are now safe by construction: the install manifest
-  records a SHA-256 content hash for every file the kit writes (`fileHashes` in
-  `ai/install-manifest.json`), and a three-way compare (recorded hash / disk /
-  freshly stamped template) classifies each file deterministically — no LLM, no guessing:
-  - files missing from disk are **written** (how new kit features, e.g. new tool
-    integrations, arrive on upgrade);
-  - kit-owned files never edited by a human are **refreshed** to the new template;
-  - files edited since install are **kept** untouched by default;
-  - with `--force`, edited files are overwritten only after a timestamped `_bkp_`
-    copy is written next to them — and files carrying a human `[verified]` tag are
-    **never** overwritten, even with `--force` (the child-lock protecting audit work);
-  - `--force-verified` (implies `--force`) is the explicit escape hatch through the
-    child-lock: it prints a per-file warning quoting the exact `[verified]` signature
-    lines that will be lost and what the file becomes afterwards, then requires the
-    word `overwrite` to be typed (backups still taken; `--yes` skips the prompt for
-    automation but the warning is always printed; non-interactive runs without
-    `--yes` abort safely);
-  - `ai/repo-profile.json` re-writes now carry the intake wizard's `humanContext`
-    forward, so onboarding answers survive re-runs.
-  Implemented in `lib/installer.mjs` (`classifyAction`); covered by new smoke
-  tests. Manifests written by older kit versions have no hashes, so their
-  existing files classify as "keep" — exactly the old skip behavior, nothing regresses.
-- **Native GitHub Copilot and Google Antigravity assets**, extending the kit beyond Claude Code:
-  - `templates/github/copilot-instructions.md`, `templates/github/prompts/*.prompt.md` (8 files),
-    and `templates/github/chatmodes/*.chatmode.md` (3 files) — installed to `.github/`, giving
-    Copilot Chat native `/cold-start`, `/add-feature`, etc. and chat-mode equivalents of the
-    `repo-explorer`/`feature-builder`/`test-runner` subagents.
-  - `templates/agents/workflows/*.md` (8 files) and `templates/agents/skills/add-feature/` —
-    installed to `.agents/`, giving Google Antigravity native workflow equivalents of the same
-    commands, plus the `add-feature` skill in the shared Agent Skills (`SKILL.md`) format that
-    Antigravity and Copilot both discover natively (no per-tool duplication).
-  - New `agents/` → `.agents/` destination mapping in `lib/installer.mjs`
-    (the `github/` → `.github/` mapping already covered the Copilot assets).
-  - No new rules files were added for Antigravity: it already reads the tool-agnostic
-    `AGENTS.md` at the repo root natively.
-- **Coverage-driven test-suite hardening.** The smoke suite grows substantially
-  (Node installer coverage: 78.6 % → 85.8 % lines, 66.6 % → 76.4 % branches):
-  - table-driven `orient` detector tests across every supported stack (Gradle both
-    variants, Go, Rust, Ruby, PHP, CMake, the bare-Makefile fallback and its
-    suppression, pip, yarn/bun/Pipenv lockfiles, Turborepo, `package.json` without
-    a `build` script, malformed `package.json`, empty repo, multi-stack note) plus
-    `--name`/`--description`/`--build`/`--test`/`--upstream` overrides and README
-    description-extraction edge cases (badge/HTML skipping, 160-char truncation,
-    fill-in fallback);
-  - per-ecosystem `indepth` dependency-parsing tests (pip, Poetry, Go, Cargo,
-    Bundler, Composer) and a real-git-repo fixture exercising the git-history
-    analyzer (commit/contributor/tag counts);
-  - unit tests for `classifyAction` pinning the full re-run matrix — including the
-    kit-upgrade `"update"` path that end-to-end tests cannot reach — and for the
-    intake wizard's `detectBranch` (normal / detached HEAD / no `.git`; exported
-    from `lib/intake.mjs` for testing);
-  - `verify` edge cases (no knowledge docs → clear error; duplicate basenames →
-    `2 matches` note) and CLI surface checks (usage text, unknown option);
-  - `npm run coverage` (c8, fetched via `npx`) and a CI `coverage` job in
-    `test.yml` enforcing a floor (83 % lines / 73 % branches).
-  (The suite briefly also carried a Node ↔ Python orient-parity gate; it was
-  retired in the same cycle when the Python runtime was removed.)
+- **Incremental re-runs with hash provenance** — the install manifest records a SHA-256 per written file; `install`/`shazam` re-runs deterministically write / refresh / keep each file, so new kit assets arrive on upgrade and human edits are never overwritten by default.
+- **Child-lock for audited work** — files carrying a human `[verified]` tag are never overwritten, even with `--force`.
+- **`--force-verified` escape hatch** — prints a per-signature warning and requires typed `overwrite` consent (backups always taken; safe non-interactive behavior).
+- **Intake answers survive re-runs** — `ai/repo-profile.json` re-writes carry `humanContext` forward.
+- **Native GitHub Copilot assets** — `copilot-instructions.md`, 8 prompt files, and 3 chat modes, stamped from `templates/github/` to `.github/`.
+- **Native Google Antigravity assets** — 8 workflows plus the `add-feature` skill in the shared Agent Skills format, stamped from `templates/agents/` to `.agents/` (new destination mapping).
+- **Deterministic release gate** — `npm run release-check` (version-sync, changelog gate, changed-files coverage report, CLI-docs sync per `ai/lab/specs/SPEC_release-check.md`), enforced on every `v*` tag by `.github/workflows/release-check.yml`.
+- **Coverage-driven test hardening** — orient detector matrix across every supported stack, per-ecosystem `indepth` dependency tests, `classifyAction`/`detectBranch` unit tests, verify/CLI edge cases; installer coverage 78.6 → 85.8 % lines, with `npm run coverage` and a CI floor (83 % lines / 73 % branches).
+
+### Fixed
+- **Windows CI tag counts** — `indepth` git-history analysis ran git through a shell, letting `cmd.exe` mangle the tag-format string; switched to `execFile` (no shell).
+- **`ai-check.yml` failing on every push** — `npm ci` had no committed lockfile; `package-lock.json` added.
+- **Drift baseline** re-anchored to main's tip after squash merges; stale `templates/claude/` map row resolved.
+
+### Docs
+- **New guides** — `docs/CLI-REFERENCE.md` (every command and flag), `docs/METHODOLOGY.md`, `docs/MULTI-TOOL-SETUP.md`; docs hub (`docs/README.md`) rebuilt.
+- **README** — defects fixed, previously undocumented capabilities surfaced, status badges and workflow diagram added.
+- **Release checklist** generalized for any `vX.Y.Z` release (was hardcoded to v0.1.0), with the release gate as step 0.
+- **Lessons-learnt series** extended and consolidated under `docs/dev/lessons-learnt/` (knowledge kinds / memory / context-harness stack; model tiering: plan heavy, implement light).
+- **Upcoming-features backlog** turned into an implementation-ready spec sheet (`docs/dev/upcoming-features.md`).
+- **Knowledge layer** — post-cold-start verification report, Mermaid architecture diagrams (`ai/analysis/diagrams/`), and a 360° pre-release maturity audit (`ai/analysis/audit-reports/`).
 
 ## [0.1.2] — 2026-06-30
 
@@ -159,6 +118,8 @@ First public release of the `ai-fication-kit` — a tool to create a knowledge l
 - **Uninstall Command**: Removes exactly what the installer wrote using the manifest record without touching any other files.
 - **Smoke Test Suite**: Cross-runtime test suite (`test/run-tests.mjs`) to verify Node and Python installers, stack detection, and verify operations.
 
+[Unreleased]: https://github.com/kunalsuri/ai-fication-kit/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/kunalsuri/ai-fication-kit/releases/tag/v0.2.0
 [0.1.2]: https://github.com/kunalsuri/ai-fication-kit/releases/tag/v0.1.2
 [0.1.1]: https://github.com/kunalsuri/ai-fication-kit/releases/tag/v0.1.1
 [0.1.0]: https://github.com/kunalsuri/ai-fication-kit/releases/tag/v0.1.0

CHECKSUMS.txt

@@ -6,7 +6,7 @@ a954e0a4d6c90afa79b399feaa71da24f0f4475f37f7cd8b4636d66bb5383d04  lib/indepth.mj
 c7bb55277c06cfb55af24e8de84d1b0572597fba40f9ac8b3963d1aa94f4d841  lib/intake.mjs
 3479e3169a847fb34853a97387225e4b878aa6f0f5eb2d000633230c32e5b032  lib/maturity.mjs
 ba6c4dbcf1da62906d83513bb52585c5d95bff5f6d7d93ce3e127207f0d065d3  lib/orient.mjs
-e042931270da6b2b98312d0ca77c2728aff183887f80d40f8b227e29e4937473  lib/util.mjs
+45ed8dc1d96b540782d21cdda9c023715b04e1d596bf0a713cffd2f93f53b22c  lib/util.mjs
 0b781db4b3c379cec86ae520efdad5bed4131d5eb858b06608343d285db61392  lib/verify.mjs
 561d926ade7fa98e6a592b84e3efb0e10de1c094388d9e884b50ee05b447d8a2  templates/AGENTS.md.tmpl
 f27f436b11fd71587f0071ba7eaed87bdde5c6df0a2936dfecf114ee4aef62e5  templates/CLAUDE.md.tmpl

CITATION.cff

@@ -17,8 +17,8 @@ authors:
     affiliation: "CEA LIST"
 license: Apache-2.0
 repository-code: "https://github.com/kunalsuri/ai-fication-kit"
-version: 0.1.0
-date-released: 2026-06-25
+version: 0.2.0
+date-released: 2026-07-03
 keywords:
   - AI coding agents
   - repository intelligence

README.md

@@ -533,7 +533,7 @@ If you use this kit in academic or research work, please cite it:
   year      = {2026},
   url       = {https://github.com/kunalsuri/ai-fication-kit},
   doi       = {10.5281/zenodo.20860637},
-  version   = {0.1.0},
+  version   = {0.2.0},
   license   = {Apache-2.0}
 }
 ```

ai/analysis/FEATURE_CATALOG.md

@@ -29,7 +29,7 @@ The kit's layers, used in the touch lists below:
 - **CLI** — `install.mjs` (arg parsing + dispatch only)
 - **Core** — the `lib/<name>.mjs` modules
 - **Payload** — `templates/` (what gets stamped into a target repo)
-- **Tests** — `test/run-tests.mjs` (smoke) and `test/run-deep-test.mjs` (standards)
+- **Tests** — `test/run-tests.mjs` (smoke), `test/run-deep-test.mjs` (standards), and `test/release-check.mjs` (release gate)
 
 ---
 
@@ -49,6 +49,7 @@ The kit's layers, used in the touch lists below:
 | F10 | **Claude Code workflow assets** | slash commands, subagents, add-feature skill stamped to `.claude/` | `templates/claude/commands/cold-start.md` `[inferred]` | `?` |
 | F11 | **CI knowledge-base check** | GitHub Actions template running `verify --strict` + `drift --git --strict` | `templates/github/workflows/ai-check.yml.tmpl` `[inferred]` | `?` |
 | F12 | **deep-test (kit standards gate)** | smoke + verify + drift + license headers + placeholder leaks | `test/run-deep-test.mjs` `[inferred]` | `?` |
+| F13 | **release-check (release gate)** | version-sync + changelog gate + coverage report + cli-docs-sync, on `v*` tags and on demand | `test/release-check.mjs` `[inferred]` | `?` |
 
 ---
 
@@ -119,6 +120,13 @@ F9 → `ai/analysis/audit-reports/DRIFT_REPORT.md` (+ gitignored manifest). `[in
 |---|---|---|
 | Tests | `test/run-deep-test.mjs` · trigger docs in `.agents/skills/deep-test/SKILL.md` · `package.json` script `deep-test` | `[inferred]` |
 
+### F13 — release-check
+| Layer | Files | Confidence |
+|---|---|---|
+| Tests | `test/release-check.mjs` · `package.json` script `release-check` · fixture scenarios in `test/run-tests.mjs` | `[inferred]` |
+| CI | `.github/workflows/release-check.yml` (runs on `v*` tags + `workflow_dispatch`) | `[inferred]` |
+| Docs | `docs/RELEASE-CHECKLIST.md` step 0 · spec `ai/lab/specs/SPEC_release-check.md` | `[inferred]` |
+
 ---
 
 ## §4 Where New Code Lives — decision tree

ai/analysis/audit-reports/VERIFICATION_REPORT.md

@@ -7,10 +7,10 @@
 
 | Status | Count | Meaning |
 |---|---|---|
-| confirmed | 147 | claim found on disk |
+| confirmed | 156 | claim found on disk |
 | moved | 0 | path is stale; a file with that name exists elsewhere |
 | missing | 0 | nothing on disk matches the claim |
 
 All claims confirmed. The knowledge docs match the tree.
 
-147 confirmed claim(s) — full list in VERIFICATION_MANIFEST.json.
+156 confirmed claim(s) — full list in VERIFICATION_MANIFEST.json.

ai/guide/FEATURE_MAP.md

@@ -86,6 +86,13 @@
 - **Gotchas:** Enforces license headers (Apache-2.0) on all `.js`, `.mjs`, `.md` source files and checks for leaked template placeholders (`{{...}}`).
 - **Related:** `verify`, `drift`
 
+### release-check  `[inferred]`
+- **Business goal:** Deterministic release-readiness gate: version-sync across every file stating a version, changelog gate, changed-files-vs-changelog coverage report, and CLI-docs sync (per `ai/lab/specs/SPEC_release-check.md`).
+- **Touches:** `test/release-check.mjs`, `package.json`, `.github/workflows/release-check.yml`, `docs/RELEASE-CHECKLIST.md`
+- **Verify with:** `npm run release-check`
+- **Gotchas:** Maintainer tooling for the kit repo itself — not stamped into target repos. Tag mode is auto-detected from `GITHUB_REF` (or forced with `--tag vX.Y.Z`) and additionally requires the dated changelog section and an emptied `[Unreleased]`. The coverage check is an informational keyword heuristic (exit 0) — a human judges its warnings.
+- **Related:** `deep-test`, `verify`
+
 ### ci-checks  `[inferred]`
 - **Business goal:** Provide a GitHub Actions workflow template that runs `verify --strict` and `drift --git --strict` automatically on push/PR for target repos.
 - **Touches:** `templates/github/workflows/ai-check.yml.tmpl`, `.github/workflows/ai-check.yml`, `lib/installer.mjs`

ai/guide/MODULE_MAP.md

@@ -31,7 +31,7 @@
 | `templates/claude/` | Claude Code assets stamped to `.claude/`: slash commands, subagents, the add-feature skill | `templates/claude/commands/cold-start.md` | ours | [inferred] (files under it changed in the v0.2 Python removal; human-audited 25/06/2026 before that — re-audit) |
 | `templates/github/` | Stamped to `.github/`: CI checks for verify/drift, plus GitHub Copilot assets (`copilot-instructions.md`, `prompts/*.prompt.md`, `chatmodes/*.chatmode.md`) | `templates/github/workflows/ai-check.yml.tmpl` | ours | [inferred] |
 | `templates/agents/` | Google Antigravity assets stamped to `.agents/`: workflow equivalents of the Claude commands, and the add-feature skill (shared Agent Skills format) | `templates/agents/workflows/cold-start.md` | ours | [inferred] |
-| `test/` | Smoke tests and deep-test standards verification | `test/run-tests.mjs` · `test/run-deep-test.mjs` | ours | [inferred] |
+| `test/` | Smoke tests, deep-test standards verification, and the deterministic release gate | `test/run-tests.mjs` · `test/run-deep-test.mjs` · `test/release-check.mjs` | ours | [inferred] |
 | `docs/` | Human-facing guides (audit guide, FAQ, release checklist) | `docs/README.md` | ours | [inferred] (files under it changed in the v0.2 Python removal; human-audited 25/06/2026 before that — re-audit) |
 | `examples/` | Sample target repos used to demonstrate/exercise the kit | `examples/README.md` | ours | [verified] (25/06/2026 20:52 CEST) |
 

ai/lab/specs/SPEC_release-check.md

@@ -1,6 +1,6 @@
 <!-- Copyright (c) 2026 Kunal Suri (CEA LIST). All rights reserved. -->
 # SPEC: release-check — deterministic release-readiness gate
-> **Status:** approved
+> **Status:** implemented (2026-07-03, `[inferred]` — see Knowledge update below)
 > **Author:** Claude (agent-drafted, `[inferred]`) · **Date:** 2026-07-02
 
 ## Goal
@@ -84,9 +84,9 @@ add files under `test/` (whose MODULE_MAP row is `[inferred]`) and read (not
 edit) `lib/util.mjs`.
 
 ## Knowledge update on completion
-- [ ] FEATURE_MAP.md entry added/updated
-- [ ] FEATURE_CATALOG.md amended
-- [ ] MODULE_MAP.md `test/` responsibility line still accurate (extend to mention the release gate)
+- [x] FEATURE_MAP.md entry added/updated (`release-check`, `[inferred]`)
+- [x] FEATURE_CATALOG.md amended (F13, `[inferred]`)
+- [x] MODULE_MAP.md `test/` responsibility line extended to mention the release gate
 
 ## Sequencing note
 Docs PR [#7](https://github.com/kunalsuri/ai-fication-kit/pull/7) must merge