From d6077af61977a6ae229e46b8e1344e7807acb936 Mon Sep 17 00:00:00 2001 From: CoderDeltaLAN Date: Mon, 15 Jun 2026 13:41:57 +0100 Subject: [PATCH] docs: add v0.2 release readiness report --- docs/V0.2-RELEASE-READINESS.md | 242 +++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 docs/V0.2-RELEASE-READINESS.md diff --git a/docs/V0.2-RELEASE-READINESS.md b/docs/V0.2-RELEASE-READINESS.md new file mode 100644 index 0000000..594e845 --- /dev/null +++ b/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.