diff --git a/CHANGELOG.md b/CHANGELOG.md index b13445e..6e58b81 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 13c0f05..4ffdf53 100644 --- a/README.md +++ b/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; diff --git a/SECURITY.md b/SECURITY.md index 19aae36..a94e83f 100644 --- a/SECURITY.md +++ b/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. diff --git a/SUPPORT.md b/SUPPORT.md index f2cf177..f442884 100644 --- a/SUPPORT.md +++ b/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 diff --git a/docs/V0.3-ARCHITECTURE-ROADMAP.md b/docs/V0.3-ARCHITECTURE-ROADMAP.md index b98af83..ac7f475 100644 --- a/docs/V0.3-ARCHITECTURE-ROADMAP.md +++ b/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 diff --git a/docs/V0.3.0-RELEASE-NOTES-DRAFT.md b/docs/V0.3.0-RELEASE-NOTES-DRAFT.md new file mode 100644 index 0000000..ba1dbb0 --- /dev/null +++ b/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.