docs: prepare v0.3 release documentation

CHANGELOG.md

@@ -8,6 +8,8 @@ This project has a published GitHub Release line, but no stable support or API g
 
 ### Added
 
+- Prepared v0.3.0 release documentation and release-notes draft without creating a tag, GitHub Release, or PyPI publication.
+
 - Added v0.3 architecture and roadmap planning documentation.
 - Added initial output and exit-code contract documentation for existing `check` and `init` behavior and planned v0.3 `doctor`, `budget`, and `explain` commands.
 - Added golden output foundation tests for current `check` and `init` console, JSON, Markdown, stdout, stderr, and exit-code behavior.

README.md

@@ -135,7 +135,9 @@ The default behavior is read-only.
 
 ## What This Project Does
 
-`v0.2.3` is published as a GitHub Release and PyPI package for `agent-rules-kit`. Current `main` reflects that published state and may include later documentation or maintenance updates.
+`v0.2.3` remains the current published GitHub Release and PyPI package for `agent-rules-kit`.
+
+Current `main` contains the v0.3.0 release-candidate command baselines. Until the dedicated release phase completes, `v0.3.0` must not be described as a published GitHub Release or PyPI package.
 
 The implemented behavior includes:
 
@@ -145,6 +147,9 @@ The implemented behavior includes:
 - provides `init --dry-run` for planning baseline instruction files;
 - provides explicit `init --write` behavior for creating or replacing root `AGENTS.md`;
 - backs up existing root `AGENTS.md` before replacement;
+- provides read-only `doctor` repository diagnosis output on `main`;
+- provides read-only `budget` local size and context-pressure approximation output on `main`;
+- provides read-only `explain` output for known governance rule IDs on `main`;
 - redacts supported secret-like values in supported output, including finding messages, paths, and evidence payloads;
 - avoids network calls;
 - avoids LLM calls;
@@ -204,7 +209,9 @@ A clean report means only that the implemented checks did not find a supported i
 
 ## Installation
 
-`v0.2.3` is published as a GitHub Release and PyPI package.
+`v0.2.3` is the current published GitHub Release and PyPI package.
+
+The v0.3.0 command baselines are present on `main` but are not published until the dedicated release phase completes tag, GitHub Release, PyPI publication, and clean-install verification.
 
 The published package can be installed from PyPI. Release publication uses PyPI Trusted Publishing from the GitHub Release workflow.
 
@@ -245,6 +252,16 @@ The source tree can also be used directly for quick CLI inspection:
 
     PYTHONPATH=src python -m agent_rules_kit.cli --help
 
+### v0.3.0 release-candidate commands from source
+
+Until `v0.3.0` is published, the new command baselines should be tested from the source tree:
+
+    PYTHONPATH=src python -m agent_rules_kit.cli doctor tests/fixtures/repositories/multi-agent-overlap
+    PYTHONPATH=src python -m agent_rules_kit.cli budget tests/fixtures/repositories/multi-agent-overlap
+    PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
+
+These source-tree commands are release-candidate behavior, not PyPI publication evidence.
+
 ---
 
 ## Release and PyPI Publishing
@@ -336,6 +353,27 @@ If root `AGENTS.md` already exists, it is backed up before replacement:
 
     AGENTS.md.agent-rules-kit.bak
 
+### Doctor release-candidate command
+
+`doctor` summarizes supported instruction files, finding counts, and review status from local source-tree execution until `v0.3.0` is published:
+
+    PYTHONPATH=src python -m agent_rules_kit.cli doctor tests/fixtures/repositories/multi-agent-overlap
+
+### Budget release-candidate command
+
+`budget` reports deterministic local size metrics. It is an approximation, not tokenizer-specific counting:
+
+    PYTHONPATH=src python -m agent_rules_kit.cli budget tests/fixtures/repositories/multi-agent-overlap
+
+### Explain release-candidate command
+
+`explain` lists or explains known local governance rule IDs:
+
+    PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
+    PYTHONPATH=src python -m agent_rules_kit.cli explain --list
+
+These v0.3.0 commands are source-tree release-candidate behavior until the dedicated release phase publishes and verifies the package.
+
 ---
 
 ## Output Formats
@@ -391,11 +429,14 @@ See:
     │       └── publish-pypi.yml
     ├── docs/
     │   ├── BUILD-PLAN.md
+    │   ├── EXIT-CODES.md
     │   ├── OUTPUTS.md
     │   ├── PRODUCT-STRATEGY.md
     │   ├── RULES.md
     │   ├── THREAT-MODEL.md
     │   ├── V0.2-GOVERNANCE-RULES-SPEC.md
+    │   ├── V0.3-ARCHITECTURE-ROADMAP.md
+    │   ├── V0.3.0-RELEASE-NOTES-DRAFT.md
     │   └── screenshots/
     │       └── readme/
     │           ├── agent-rules-kit-governance-findings.png
@@ -407,8 +448,11 @@ See:
     ├── src/
     │   └── agent_rules_kit/
     │       ├── __init__.py
+    │       ├── budget.py
     │       ├── cli.py
     │       ├── discovery.py
+    │       ├── doctor.py
+    │       ├── explain.py
     │       ├── findings.py
     │       ├── governance.py
     │       ├── init_plan.py
@@ -465,13 +509,14 @@ The required status check for `main` is:
 
 Current status:
 
-- `v0.2.3` is published as a GitHub Release and PyPI package;
-- `v0.2.2` remains the previous published GitHub Release and PyPI package baseline;
-- `main` may include post-`v0.2.3` documentation or maintenance updates;
+- `v0.2.3` is published as the current GitHub Release and PyPI package;
+- `main` contains the v0.3.0 release-candidate command baselines;
+- `v0.3.0` is not published yet and must not be claimed as available from PyPI until the dedicated release phase verifies it;
 - no stable support or API guarantee yet;
 - release tag `v0.2.3` points to the verified release SHA;
 - local CLI behavior implemented;
 - governance diagnostics, structured finding evidence, and evidence redaction are implemented;
+- `doctor`, `budget`, and `explain` are implemented on `main` as v0.3.0 release-candidate commands;
 - CI active;
 - branch protection is active with the required `local-checks / Python 3.12` status check;
 - the `pypi` GitHub environment exists for the release publishing workflow;

SECURITY.md

@@ -6,15 +6,18 @@ It is not a security scanner, provides no security guarantees, and must not be d
 
 ## Supported versions
 
-`v0.2.3` is published as a GitHub Release and PyPI package.
+`v0.2.3` remains the current published GitHub Release and PyPI package.
 
-Current `main` may include post-`v0.2.3` documentation or maintenance updates after the published package.
+Current `main` is preparing the `v0.3.0` release candidate and may include command baselines or documentation not yet available from PyPI.
+
+`v0.3.0` must not be described as a supported published release until the dedicated release phase verifies the GitHub Release, PyPI publication, and clean installation.
 
 The project is still maintained on a best-effort basis. There is no commercial SLA, no guaranteed response time, and no guarantee that every security-relevant issue will be found or fixed.
 
 | Version | Status |
 | --- | --- |
-| 0.2.x | Current GitHub Release line / best-effort security fixes |
+| 0.3.x | Release candidate on `main` / not yet published |
+| 0.2.x | Current published GitHub Release line / best-effort security fixes |
 | 0.1.x | Historical pre-release line / not supported |
 | < 0.1 | Not supported |
 
@@ -67,7 +70,7 @@ agent-rules-kit does not aim to:
 
 ## Maintainer response
 
-Security response is best-effort for the current `0.2.x` GitHub Release line.
+Security response is best-effort for the current published `0.2.x` GitHub Release line until `v0.3.0` is published and verified.
 
 There is no commercial SLA or guaranteed response time.
 

SUPPORT.md

@@ -6,19 +6,19 @@ There is no commercial SLA, no guaranteed response time, no production-readiness
 
 ## Current published line
 
-`v0.2.3` is the current published GitHub Release and PyPI package line.
+`v0.2.3` remains the current published GitHub Release and PyPI package line.
 
-`v0.2.2` remains the previous published GitHub Release and PyPI package baseline.
+Current `main` is preparing the `v0.3.0` release candidate and may include command baselines or documentation not yet available from PyPI.
 
-Current `main` may include post-`v0.2.3` documentation or maintenance updates after the published package.
+`v0.3.0` must not be described as a published GitHub Release or PyPI package until the dedicated release phase completes and verifies publication.
 
 ## Package availability
 
-The package is published on PyPI as:
+The current published package is:
 
     agent-rules-kit==0.2.3
 
-Future PyPI availability claims must be verified per release before updating this policy.
+Do not claim `agent-rules-kit==0.3.0` is available on PyPI until the release phase verifies the published package and a clean install smoke test.
 
 ## What support means
 

docs/V0.3-ARCHITECTURE-ROADMAP.md

@@ -8,21 +8,29 @@ It is a maintainer planning document. It does not declare a stable public API, a
 
 The published baseline is `v0.2.3`.
 
-Current implemented behavior:
+Current implemented behavior on `main`:
 
 - discovers supported AI agent instruction files;
 - emits `check` output in console, JSON, and Markdown;
 - provides explicit `init --dry-run` and `init --write` behavior;
 - reports conservative governance findings;
 - redacts supported secret-like values in supported output paths;
+- provides the read-only `doctor` baseline command;
+- provides the read-only `budget` baseline command;
+- provides the read-only `explain` baseline command;
 - avoids runtime network calls;
 - avoids runtime LLM calls;
 - avoids executing commands from analyzed repositories.
 
-Current command surface:
+Current command surface on `main`:
 
 - `agent-rules-kit check`;
-- `agent-rules-kit init`.
+- `agent-rules-kit init`;
+- `agent-rules-kit doctor`;
+- `agent-rules-kit budget`;
+- `agent-rules-kit explain`.
+
+`v0.3.0` is not published yet. The current published baseline remains `v0.2.3` until the dedicated release phase cuts the version, creates the tag and GitHub Release, publishes to PyPI, and verifies clean installation.
 
 ## v0.3 objective
 

docs/V0.3.0-RELEASE-NOTES-DRAFT.md

@@ -0,0 +1,89 @@
+# v0.3.0 Release Notes Draft
+
+Status: draft / not published.
+
+Target version: `v0.3.0`.
+
+This document is release-preparation evidence. It does not create a tag, publish a GitHub Release, publish to PyPI, or prove release readiness by itself.
+
+## Release summary
+
+`agent-rules-kit` v0.3.0 moves the project from a check-focused diagnostic CLI toward a small local-first instruction-governance toolkit.
+
+The release keeps the product boundary:
+
+- local CLI;
+- read-only diagnosis commands;
+- no runtime network calls;
+- no runtime LLM calls;
+- no execution of commands from analyzed repositories;
+- no security-scanner claim;
+- no proof-of-safety claim.
+
+## Main changes
+
+v0.3.0 is expected to include:
+
+- `doctor`, a read-only repository-level diagnosis summary;
+- `budget`, a read-only local size and context-pressure approximation;
+- `explain`, a read-only local explanation command for known governance rule IDs;
+- output and exit-code contract documentation for the implemented command surface;
+- golden output and regression coverage for the expanded command surface;
+- updated release documentation for the v0.3.0 release train.
+
+## Command surface
+
+The intended v0.3.0 command surface is:
+
+- `agent-rules-kit --version`;
+- `agent-rules-kit check`;
+- `agent-rules-kit init --dry-run`;
+- `agent-rules-kit init --write`;
+- `agent-rules-kit doctor`;
+- `agent-rules-kit budget`;
+- `agent-rules-kit explain`.
+
+## Release and PyPI status
+
+`v0.3.0` is not published yet.
+
+Before publication, the release phase must verify:
+
+- `main` is clean and synchronized with `origin/main`;
+- CI is green for the exact release SHA;
+- package metadata declares `0.3.0`;
+- `CHANGELOG.md` has a dated `0.3.0` release section;
+- the GitHub Release tag points to the verified SHA;
+- the PyPI publish workflow uses Trusted Publishing;
+- PyPI contains `agent-rules-kit==0.3.0` after publication;
+- a clean install from PyPI can execute the CLI smoke checks.
+
+## Security and support notes
+
+This project is not a security scanner and does not prove that a repository is safe.
+
+Support remains best-effort. There is no commercial SLA, no guaranteed response time, no production-readiness guarantee, and no stable public API guarantee before v1.0.
+
+Private vulnerability reporting must not be claimed as enabled unless the setting is verified during the release phase.
+
+## Not included
+
+v0.3.0 must not claim:
+
+- stable public API compatibility;
+- production readiness;
+- security certification;
+- complete governance coverage;
+- complete secret scanning;
+- dependency vulnerability scanning;
+- model-specific token counting;
+- repository packaging for LLMs;
+- automatic rewriting or fixing;
+- runtime network access;
+- runtime LLM behavior.
+
+## Release decision
+
+Do not publish `v0.3.0` from documentation preparation alone.
+
+The next release phase must perform the version cut, package build, GitHub Release, PyPI publication, and clean-install smoke verification from the verified release SHA.