docs: add v0.2 release readiness report

docs/V0.2-RELEASE-READINESS.md

@@ -0,0 +1,242 @@
+# v0.2 Release Readiness Report
+
+Status: blocked for v0.2 release, approved for release preparation.
+
+Date: 2026-06-15.
+
+Base commit reviewed: 7594346ebeb674a7e471197250bccbca8b4c36bf.
+
+CI run reviewed: 27545634227.
+
+This report records the release-readiness state after the unreleased v0.2 governance baseline landed on `main`.
+
+It is not a release note, tag decision, version bump, or stability claim.
+
+## Scope
+
+This report covers readiness for a future `v0.2.0` GitHub release of the governance baseline currently present on `main`.
+
+It does not approve:
+
+- changing `pyproject.toml`;
+- cutting a changelog release section;
+- creating a tag;
+- creating a GitHub Release;
+- uploading artifacts;
+- publishing to PyPI;
+- adding new governance rules;
+- changing CLI output behavior.
+
+Those actions require separate explicit phases.
+
+## Current verified state
+
+The reviewed `main` branch is clean and synchronized with `origin/main`.
+
+The reviewed commit is:
+
+- `7594346ebeb674a7e471197250bccbca8b4c36bf`.
+
+The reviewed GitHub Actions run is:
+
+- `27545634227`;
+- branch: `main`;
+- conclusion: `success`.
+
+Local checks pass through `./scripts/check.sh`.
+
+The current local check output includes:
+
+- Python syntax check passing;
+- 94 unit tests passing;
+- text hygiene passing;
+- Git whitespace checks passing.
+
+The published `v0.1.0` tag remains intact at:
+
+- `104697f263df450d45f195436235937a99d4918c`.
+
+The current package version is still:
+
+- `0.1.0`.
+
+That is correct for this phase and blocks any `v0.2.0` release until a dedicated version-cut phase.
+
+## Current unreleased v0.2 behavior on main
+
+Current `main` contains unreleased governance diagnostics for AI agent instruction files.
+
+The governance baseline remains within the intended product boundary:
+
+- local CLI;
+- read-only by default;
+- no runtime network dependency;
+- no runtime LLM dependency;
+- no execution of commands from analyzed repositories;
+- no security-scanner claim;
+- no proof-of-safety claim.
+
+Smoke output from the `risky-instructions` fixture shows governance findings in console output.
+
+JSON output includes structured finding evidence for line-based governance findings.
+
+Markdown output shows the documented finding table without evidence payloads.
+
+Golden contract coverage exists for current governance console, JSON, and Markdown output behavior.
+
+## Documentation state
+
+README.md distinguishes:
+
+- the published `v0.1.0` GitHub pre-release;
+- current unreleased v0.2 governance behavior on `main`;
+- absence of a stable public release.
+
+README.md no longer pins a fragile unit test count. It points to `./scripts/check.sh` and the matching GitHub Actions run as the source of truth.
+
+CHANGELOG.md records unreleased governance diagnostics, structured finding evidence, evidence redaction, golden contract coverage, and the GitHub Actions Node 24-compatible update under `[Unreleased]`.
+
+SECURITY.md preserves the security boundary:
+
+- not a security scanner;
+- no security guarantees;
+- best-effort pre-release support;
+- private reporting path preferred when available;
+- stable support policy still required before a stable release.
+
+docs/V0.2-GOVERNANCE-RULES-SPEC.md requires a release-readiness audit before any v0.2 version, tag, or release decision.
+
+## Release blockers
+
+The project is not ready for a `v0.2.0` release until these blockers are closed in separate phases.
+
+### Blocker 1: version metadata not cut
+
+`pyproject.toml` still declares:
+
+- `version = "0.1.0"`.
+
+A dedicated release-cut phase must update version metadata only after readiness gates are satisfied.
+
+### Blocker 2: changelog release section not cut
+
+CHANGELOG.md still uses `[Unreleased]` for v0.2 governance work.
+
+A dedicated release-cut phase must create a dated `0.2.0` section from the current unreleased entries.
+
+### Blocker 3: v0.2 artifacts not built and installed from clean environments
+
+The audit confirmed that `python -m build` is available, but did not build, checksum, install, and smoke-test `v0.2.0` wheel and sdist artifacts.
+
+A dedicated packaging dry-run phase must verify:
+
+- source distribution build;
+- wheel build;
+- clean virtual environment install from wheel;
+- clean virtual environment install from sdist;
+- console script execution;
+- `python -m agent_rules_kit.cli` execution;
+- no unexpected runtime dependencies.
+
+### Blocker 4: v0.2 tag and GitHub Release do not exist
+
+No `v0.2.0` tag or GitHub Release should exist yet.
+
+A dedicated release phase must create them only after version metadata, changelog, artifacts, and release notes are verified.
+
+### Blocker 5: branch protection and private vulnerability reporting need explicit release evidence
+
+README.md states that branch protection is active and names the required status check.
+
+The release-readiness command attempted read-only GitHub API checks, but the captured output did not provide enough visible evidence to close this as release evidence.
+
+Before a `v0.2.0` release, a dedicated verification phase must capture clear evidence for:
+
+- main branch protection;
+- required status checks;
+- admin enforcement;
+- force-push prevention;
+- deletion prevention;
+- pull-request review profile appropriate for a solo-maintainer repo;
+- private vulnerability reporting enabled, or explicit documented alternative if unavailable.
+
+### Blocker 6: release notes not cut from verified artifacts
+
+The release notes for `v0.2.0` must be written after artifacts are built and verified.
+
+They must not claim:
+
+- stable public maturity;
+- security scanning;
+- proof of repository safety;
+- complete governance coverage;
+- LLM-based semantic analysis;
+- PyPI availability unless PyPI publication is explicitly completed in a separate phase.
+
+## Required v0.2 release train
+
+The recommended release train is:
+
+1. `docs/add-v02-release-readiness-report`
+   - create and merge this report;
+   - no release mutation.
+
+2. `release/v02-packaging-dry-run`
+   - build wheel and sdist;
+   - install from clean temporary environments;
+   - smoke-test installed commands;
+   - document results if needed.
+
+3. `release/verify-v02-governance-boundaries`
+   - verify branch protection;
+   - verify required status check name;
+   - verify vulnerability reporting path or document explicit alternative;
+   - no code changes unless separately approved.
+
+4. `release/cut-v0.2.0-metadata`
+   - update `pyproject.toml` version;
+   - cut CHANGELOG.md `0.2.0` section;
+   - prepare release notes draft;
+   - no tag yet.
+
+5. `release/v0.2.0`
+   - verify final SHA;
+   - build final artifacts;
+   - checksum artifacts;
+   - create exact tag;
+   - create GitHub Release;
+   - upload verified artifacts;
+   - verify assets can be downloaded, installed, and smoke-tested.
+
+6. `audit/post-v0.2.0-release`
+   - verify tag;
+   - verify GitHub Release;
+   - verify artifacts;
+   - verify README/CHANGELOG/SECURITY alignment;
+   - verify CI for release SHA;
+   - confirm no open release blockers.
+
+## Decision
+
+Do not publish `v0.2.0` from the current state.
+
+The correct next action is a packaging and install dry-run after this report is merged.
+
+## Readiness verdict
+
+v0.2 release status:
+
+- implementation baseline: ready for release preparation;
+- documentation alignment: mostly ready;
+- tests: ready for release preparation;
+- CI: ready for release preparation;
+- packaging: not yet verified for v0.2 release;
+- version metadata: not cut;
+- changelog release section: not cut;
+- tag/release: not created;
+- security reporting evidence: not closed;
+- final release decision: blocked.
+
+Final verdict:
+
+`v0.2.0` is not releasable yet, but the repository is in a good state to continue a disciplined v0.2 release train.