release: prepare v0.4.0

CHANGELOG.md

@@ -6,6 +6,10 @@ This project has a published GitHub Release line, but no stable support or API g
 
 ## [Unreleased]
 
+No unreleased changes yet.
+
+## [0.4.0] - 2026-06-21
+
 - Documented the GitHub Actions pinning policy decision before the v0.4.0 release train.
 - Refreshed the external audit package manifest and corrected pre-v0.4.0 readiness statuses after F-01.
 - Triaged superseded v0.3.1 release-target wording before the v0.4.0 release train.
@@ -41,7 +45,6 @@ This project has a published GitHub Release line, but no stable support or API g
 - Improved PyPI package metadata with SPDX license metadata, explicit license files, project URLs, and additional classifiers.
 - Synced the README source-tree layout with the actual v0.3.0 module structure.
 - Reviewed the threat model for the v0.3.0 doctor, budget, and explain command surface.
-
 ## [0.3.0] - 2026-06-19
 
 ### Added

README.md

@@ -135,11 +135,11 @@ The default behavior is read-only.
 
 ## What This Project Does
 
-`v0.3.0` is the current published GitHub Release and PyPI package for `agent-rules-kit`.
+`v0.4.0` is the current published GitHub Release and PyPI package for `agent-rules-kit`.
 
-`v0.2.3` remains the previous published GitHub Release and PyPI package baseline.
+`v0.3.0` remains the previous published GitHub Release and PyPI package baseline.
 
-Current `main` may include post-v0.3.0 changes that are not part of the published PyPI package until a later release is cut and verified.
+Current `main` may include post-v0.4.0 changes that are not part of the published PyPI package until a later release is cut and verified.
 
 The current `main` behavior includes:
 
@@ -149,11 +149,11 @@ The current `main` 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 in the published v0.3.0 package and current `main`;
-- provides read-only `budget` local size and context-pressure approximation output in the published v0.3.0 package and current `main`;
-- provides read-only `explain` output for known governance rule IDs in the published v0.3.0 package and current `main`;
-- provides read-only `dedupe` duplicate instruction-line detection on current `main` as a post-v0.3.0 addition;
-- provides read-only `conflicts` contradictory-guidance detection on current `main` as a post-v0.3.0 addition;
+- provides read-only `doctor` repository diagnosis output in the published v0.4.0 package and current `main`;
+- provides read-only `budget` local size and context-pressure approximation output in the published v0.4.0 package and current `main`;
+- provides read-only `explain` output for known governance rule IDs in the published v0.4.0 package and current `main`;
+- provides read-only `dedupe` duplicate instruction-line detection in the published v0.4.0 package and current `main`;
+- provides read-only `conflicts` contradictory-guidance detection in the published v0.4.0 package and current `main`;
 - redacts supported secret-like values in supported output, including finding messages, paths, and evidence payloads;
 - avoids network calls;
 - avoids LLM calls;
@@ -213,7 +213,7 @@ A clean report means only that the implemented checks did not find a supported i
 
 ## Installation
 
-`v0.3.0` is the current published GitHub Release and PyPI package.
+`v0.4.0` is the current published GitHub Release and PyPI package.
 
 The published package can be installed from PyPI. Release publication uses PyPI Trusted Publishing from the GitHub Release workflow.
 
@@ -225,10 +225,10 @@ Requirements for using a published CLI release:
 - a Python virtual environment;
 - a published PyPI release of `agent-rules-kit`.
 
-Install `v0.3.0` in a virtual environment:
+Install `v0.4.0` in a virtual environment:
 
     python -m venv .venv
-    .venv/bin/python -m pip install agent-rules-kit==0.3.0
+    .venv/bin/python -m pip install agent-rules-kit==0.4.0
     .venv/bin/agent-rules-kit --version
     .venv/bin/agent-rules-kit check /path/to/repository --format console
 
@@ -256,7 +256,7 @@ The source tree can also be used directly for quick CLI inspection:
 
 ### Current main commands from source
 
-Current `main` can also be tested from the source tree. `doctor`, `budget`, and `explain` are part of the published v0.3.0 package. `dedupe` and `conflicts` are post-v0.3.0 current-main additions until the next release is cut and verified:
+Current `main` can also be tested from the source tree. `doctor`, `budget`, `explain`, `dedupe`, and `conflicts` are part of the published v0.4.0 package and current 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
@@ -270,7 +270,7 @@ These source-tree commands are development checks. Published-package behavior mu
 
 ## Release and PyPI Publishing
 
-The `v0.3.0` release was published through PyPI Trusted Publishing.
+The `v0.4.0` release was published through PyPI Trusted Publishing.
 
 Release publishing is handled by:
 
@@ -288,11 +288,11 @@ The workflow is intentionally limited:
 - it grants `id-token: write` only to the publish job;
 - it does not use a static PyPI token, username, or password.
 
-The published `v0.3.0` package must remain verifiable by:
+The published `v0.4.0` package must remain verifiable by:
 
 - the GitHub Release tag pointing to the verified release SHA;
 - a successful PyPI publish workflow run;
-- a clean virtual environment installing and running `agent-rules-kit==0.3.0` from PyPI.
+- a clean virtual environment installing and running `agent-rules-kit==0.4.0` from PyPI.
 
 ---
 
@@ -392,7 +392,7 @@ The first baseline is conservative: it detects implemented pattern families for
     PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
     PYTHONPATH=src python -m agent_rules_kit.cli explain --list
 
-These commands are implemented on current `main`. `doctor`, `budget`, and `explain` are part of the published v0.3.0 command surface. `dedupe` and `conflicts` are post-v0.3.0 `main` additions until the next release is cut and verified.
+These commands are implemented on current `main` and are part of the published v0.4.0 command surface.
 
 ---
 
@@ -452,13 +452,17 @@ See:
     │       ├── codeql.yml
     │       └── publish-pypi.yml
     ├── docs/
+    │   ├── ACTIONS-PINNING-POLICY.md
     │   ├── BUILD-PLAN.md
     │   ├── DEPENDABOT-DEPENDENCY-GRAPH.md
     │   ├── EXIT-CODES.md
+    │   ├── EXTERNAL-AUDIT-PACKAGE-CURRENT-MAIN.md
     │   ├── OPENSSF-SCORECARD-EVALUATION.md
     │   ├── OUTPUTS.md
+    │   ├── POST-AUDIT-ACTION-PLAN-CURRENT-MAIN.md
     │   ├── POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md
     │   ├── POST-V0.3.0-INTERNAL-READINESS-AUDIT.md
+    │   ├── PRE-V0.4.0-INTERNAL-READINESS-AUDIT.md
     │   ├── PRIVATE-VULNERABILITY-REPORTING.md
     │   ├── PRODUCT-STRATEGY.md
     │   ├── RULES.md
@@ -472,8 +476,14 @@ See:
     │   ├── V0.3-ARCHITECTURE-ROADMAP.md
     │   ├── V0.3.0-POST-RELEASE-AUDIT.md
     │   ├── V0.3.0-RELEASE-NOTES.md
+    │   ├── V0.4.0-RELEASE-EVIDENCE.md
+    │   ├── V0.4.0-RELEASE-NOTES.md
     │   └── screenshots/
     │       └── readme/
+    │           ├── agent-rules-kit-governance-findings.png
+    │           ├── agent-rules-kit-help-check.png
+    │           ├── agent-rules-kit-init-safety.png
+    │           └── agent-rules-kit-output-formats.png
     ├── scripts/
     │   ├── check.sh
     │   └── post-release-audit.sh
@@ -492,6 +502,8 @@ See:
     │       ├── init_write.py
     │       └── redaction.py
     ├── tests/
+    │   ├── fixtures/
+    │   │   └── repositories/
     │   ├── test_cli.py
     │   ├── test_conflicts.py
     │   ├── test_dedupe.py
@@ -543,7 +555,7 @@ Current verified local result on `main`:
 
 The exact unit test count may change as coverage evolves. The source of truth is the current `./scripts/check.sh` output and the matching GitHub Actions run for `main`.
 
-For current post-v0.3.0 functional evidence, including the verified command matrix, init write behavior, and release-boundary limits, see `docs/POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md`.
+For v0.4.0 release notes and release evidence, see `docs/V0.4.0-RELEASE-NOTES.md` and `docs/V0.4.0-RELEASE-EVIDENCE.md`.
 
 CI installs project development dependencies and then runs the same local check script through GitHub Actions.
 
@@ -557,19 +569,19 @@ The required status check for `main` is:
 
 Current status:
 
-- `v0.3.0` is published as the current GitHub Release and PyPI package;
-- `v0.2.3` remains the previous published GitHub Release and PyPI package baseline;
+- `v0.4.0` is published as the current GitHub Release and PyPI package;
+- `v0.3.0` remains the previous published GitHub Release and PyPI package baseline;
 - no stable support or API guarantee yet;
-- release tag `v0.3.0` points to the verified release SHA;
+- release tag `v0.4.0` 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 as v0.3.0 commands, while `dedupe` and `conflicts` are implemented on current `main` as post-v0.3.0 read-only command additions;
+- `doctor`, `budget`, `explain`, `dedupe`, and `conflicts` are implemented as v0.4.0 read-only command surfaces;
 - 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;
-- `.github/workflows/publish-pypi.yml` published `v0.3.0` through PyPI Trusted Publishing and remains the release publishing workflow;
+- `.github/workflows/publish-pypi.yml` published `v0.4.0` through PyPI Trusted Publishing and remains the release publishing workflow;
 - README screenshots are generated from real local CLI commands;
-- post-v0.3.0 functional contract evidence is documented in `docs/POST-V0.3.0-FUNCTIONAL-CONTRACT-EVIDENCE.md`;
+- v0.4.0 release notes and release evidence are documented in `docs/V0.4.0-RELEASE-NOTES.md` and `docs/V0.4.0-RELEASE-EVIDENCE.md`;
 - security boundaries documented;
 - threat model documented.
 

SECURITY.md

@@ -6,20 +6,21 @@ It is not a security scanner, provides no security guarantees, and must not be d
 
 ## Supported versions
 
-`v0.3.0` is the current published GitHub Release and PyPI package.
+`v0.4.0` is the current published GitHub Release and PyPI package.
 
-`v0.2.3` remains the previous published GitHub Release and PyPI package baseline.
+`v0.3.0` remains the previous published GitHub Release and PyPI package baseline.
 
 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.3.x | Current published GitHub Release line / best-effort security fixes |
-| 0.2.x | Previous published line / limited best-effort fixes |
+| 0.4.x | Current published GitHub Release line / best-effort security fixes |
+| 0.3.x | Previous published line / limited best-effort fixes |
+| 0.2.x | Historical line / limited best-effort fixes |
 | 0.1.x | Historical pre-release line / not supported |
 | < 0.1 | Not supported |
 
-`agent-rules-kit==0.3.0` is published on PyPI. Future PyPI availability claims must be verified per release before updating this policy.
+`agent-rules-kit==0.4.0` is published on PyPI. Future PyPI availability claims must be verified per release before updating this policy.
 
 ## Security boundaries
 
@@ -70,7 +71,7 @@ agent-rules-kit does not aim to:
 
 ## Maintainer response
 
-Security response is best-effort for the current published `0.3.x` GitHub Release line.
+Security response is best-effort for the current published `0.4.x` GitHub Release line.
 
 There is no commercial SLA or guaranteed response time.
 

SUPPORT.md

@@ -6,15 +6,15 @@ There is no commercial SLA, no guaranteed response time, no production-readiness
 
 ## Current published line
 
-`v0.3.0` is the current published GitHub Release and PyPI package line.
+`v0.4.0` is the current published GitHub Release and PyPI package line.
 
-`v0.2.3` remains the previous published GitHub Release and PyPI package baseline.
+`v0.3.0` remains the previous published GitHub Release and PyPI package baseline.
 
 ## Package availability
 
 The current published package is:
 
-    agent-rules-kit==0.3.0
+    agent-rules-kit==0.4.0
 
 Future PyPI availability claims must be verified per release before updating this policy.
 

docs/OUTPUTS.md

@@ -18,7 +18,7 @@ Implemented command surface:
 - `agent-rules-kit conflicts`;
 - `agent-rules-kit explain`.
 
-`doctor`, `budget`, and `explain` are implemented as v0.3.0 command baselines. `dedupe` and `conflicts` are implemented on current `main` after v0.3.0 and must not be described as published package behavior until the next release is cut and verified. Release publication is verified by the dedicated GitHub Release and PyPI workflow evidence, not by this output contract alone.
+The full command surface listed above is implemented in the published v0.4.0 command baseline. Release publication is verified by the dedicated GitHub Release and PyPI workflow evidence, not by this output contract alone.
 
 ## Contract status
 

docs/PRODUCT-STRATEGY.md

@@ -1,12 +1,12 @@
 # Product Strategy Roadmap
 
-This document defines the product direction for agent-rules-kit after the published v0.3.0 GitHub Release and PyPI package, with current post-v0.3.0 maintenance hardening on main.
+This document defines the product direction for agent-rules-kit after the published v0.4.0 GitHub Release and PyPI package.
 
 It is a strategy document, not an implementation plan for a specific feature. It must not be used to claim capabilities that are not already implemented.
 
 ## Current product truth
 
-agent-rules-kit has a published v0.3.0 GitHub Release and PyPI package line. `v0.2.3` remains the previous published GitHub Release and PyPI package baseline. Current main contains post-v0.3.0 `dedupe` and `conflicts` command additions plus maintenance hardening. The next public release target is v0.4.0, not a v0.3.x patch, because the new commands expand the compatible command surface.
+agent-rules-kit has a published v0.4.0 GitHub Release and PyPI package line. `v0.3.0` remains the previous published GitHub Release and PyPI package baseline. The v0.4.0 release publishes the compatible `dedupe` and `conflicts` command additions plus maintenance hardening that landed after v0.3.0.
 
 The implemented product currently supports:
 
@@ -28,7 +28,6 @@ The implemented product does not yet provide:
 
 - governance scoring;
 - cross-file consistency analysis;
-- instruction conflict detection;
 - exact tokenizer-specific token accounting;
 - policy profiles;
 - remediation workflows;
@@ -266,13 +265,12 @@ Candidate criteria:
 - private vulnerability reporting path or explicit documented alternative;
 - no unsupported security or maturity claims.
 
-## Next implementation direction after v0.3.0
+## Next implementation direction after v0.4.0
 
 The next implementation phase should be justified against the current repository state, not against older strategy snapshots.
 
 Good next candidates are narrow and evidence-backed:
 
-- v0.4.0 release preparation for the current `dedupe` and `conflicts` command additions, after final audit evidence is complete;
 - release and package smoke hardening;
 - README, support, security, and strategy public-truth checks;
 - supply-chain workflow additions only after dedicated evaluation phases;
@@ -287,8 +285,8 @@ Decision: keep product strategy as the boundary document after v0.2.
 
 Reason:
 
-- v0.3.0 already published the local diagnosis toolkit baseline;
-- current main contains post-v0.3.0 `dedupe` and `conflicts` command additions plus maintenance hardening that must be released, if approved, as v0.4.0 rather than a patch release;
+- v0.4.0 publishes the current local instruction-governance command baseline;
+- future post-v0.4.0 work should avoid broadening the tool before machine-readable output and renderer structure are improved;
 - adjacent tools still cover repository packaging, context frameworks, and broad rule generation better than this project should;
 - the real product wedge remains instruction governance;
 - future features must be justified against this document to avoid scope drift.

docs/THREAT-MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model
 
-This document defines the threat model for agent-rules-kit. It was last reviewed for the published v0.3.0 release line and the current post-v0.3.0 main state, including the published v0.3.0 doctor, budget, and explain command surface and the current-main post-v0.3.0 dedupe and conflicts read-only command additions.
+This document defines the threat model for agent-rules-kit. It was last reviewed for the published v0.4.0 release line, including the read-only check, init, doctor, budget, explain, dedupe, and conflicts command surface.
 
 It is intentionally narrow. agent-rules-kit is a local CLI for diagnosing AI agent instruction files. It is not a security scanner, malware detector, CI/CD auditor, sandbox, secret manager, or autonomous remediation agent.
 
@@ -14,13 +14,13 @@ In scope for the current release line and current main state:
 - read-only doctor repository diagnosis summaries;
 - read-only budget size and context-pressure approximation output;
 - read-only explain output for local governance rule IDs;
-- read-only dedupe duplicate instruction-line detection on current main as a post-v0.3.0 addition;
-- read-only conflicts contradictory-guidance detection on current main as a post-v0.3.0 addition;
+- read-only dedupe duplicate instruction-line detection;
+- read-only conflicts contradictory-guidance detection;
 - explicit init planning;
 - explicit init write behavior for baseline AGENTS.md creation or replacement with backup;
 - secret-like value redaction in findings and output.
 
-`dedupe` and `conflicts` are current-main post-v0.3.0 additions. They must not be represented as published PyPI package behavior until a later release is cut, published, and verified.
+`dedupe` and `conflicts` are included in the published v0.4.0 command surface after release publication and PyPI verification.
 
 Out of scope:
 
@@ -163,7 +163,7 @@ Before release, verify:
 - backups are created before replacing existing AGENTS.md;
 - no runtime network or LLM dependency was introduced;
 - no repository command execution was introduced;
-- post-v0.3.0 `dedupe` and `conflicts` command boundaries remain read-only if they are included in the next release scope;
+- `dedupe` and `conflicts` command boundaries remain read-only in the v0.4.0 release scope;
 - secret-like examples in tests and docs are fake or redacted;
 - README does not claim security guarantees;
 - CI is green for the release SHA.