Complete distribution and release hardening

.github/workflows/plananvil-tests.yml

@@ -9,8 +9,17 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: plananvil-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONDONTWRITEBYTECODE: "1"
+
 jobs:
-  test:
+  core:
+    name: core (${{ matrix.os }}, py${{ matrix.python-version }})
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -20,12 +29,13 @@ jobs:
           - windows-latest
         python-version:
           - "3.11"
+          - "3.14"
     runs-on: ${{ matrix.os }}
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Configure Git fixture identity
@@ -35,6 +45,38 @@ jobs:
           git config --global commit.gpgsign false
           git config --global protocol.file.allow always
       - name: Compile deterministic scripts and hooks
-        run: python -m compileall -q .agents/skills/plan-anvil .codex/hooks
-      - name: Run unit and integration tests
+        run: python -m compileall -q .agents/skills/plan-anvil .codex/hooks tools tests
+      - name: Run core unit and integration tests
         run: python -m unittest discover -s .agents/skills/plan-anvil/tests -v
+      - name: Check patch whitespace
+        run: git diff --check
+
+  distribution:
+    name: distribution and release candidate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.11"
+      - name: Configure Git fixture identity
+        run: |
+          git config --global user.name "PlanAnvil CI"
+          git config --global user.email "plananvil-ci@example.invalid"
+          git config --global commit.gpgsign false
+          git config --global protocol.file.allow always
+      - name: Run distribution and release tests
+        run: python -m unittest discover -s tests -v
+      - name: Validate prepared C01-C16 evidence templates
+        run: |
+          python tools/prepare_capabilities.py --target "$RUNNER_TEMP/plananvil-capabilities" --force
+          python tools/validate_capabilities.py --root "$RUNNER_TEMP/plananvil-capabilities"
+      - name: Validate release candidate metadata
+        run: python tools/release_check.py --candidate
+      - name: Build deterministic release archive
+        run: python tools/build_release.py --output "$RUNNER_TEMP/plananvil-dist"
+      - name: Check patch whitespace
+        run: git diff --check

.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: PlanAnvil release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+env:
+  PYTHONDONTWRITEBYTECODE: "1"
+
+jobs:
+  release:
+    name: validate and publish release
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.11"
+      - name: Configure Git fixture identity
+        run: |
+          git config --global user.name "PlanAnvil Release CI"
+          git config --global user.email "plananvil-release@example.invalid"
+          git config --global commit.gpgsign false
+          git config --global protocol.file.allow always
+      - name: Compile deterministic code
+        run: python -m compileall -q .agents/skills/plan-anvil .codex/hooks tools tests
+      - name: Run core tests
+        run: python -m unittest discover -s .agents/skills/plan-anvil/tests -v
+      - name: Run distribution tests
+        run: python -m unittest discover -s tests -v
+      - name: Validate live capability evidence
+        run: python tools/validate_capabilities.py
+      - name: Enforce production release gate
+        run: python tools/release_check.py --tag "${GITHUB_REF_NAME}"
+      - name: Build release archive
+        run: python tools/build_release.py --output dist
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="$(cat VERSION)"
+          gh release create "v${VERSION}" \
+            "dist/plananvil-${VERSION}.zip" \
+            "dist/SHA256SUMS" \
+            --verify-tag \
+            --title "PlanAnvil ${VERSION}" \
+            --notes-file dist/release-notes.md

CHANGELOG.md

@@ -4,12 +4,29 @@ All notable changes to PlanAnvil are documented here.
 
 ## [Unreleased]
 
+No queued changes.
+
+## [0.2.0] - 2026-08-28
+
+### Added
+
+- standard-library repository distribution manager with install, verify, upgrade, status and uninstall operations;
+- transactional rollback, ownership/hash state, conservative Codex config merging, and structural hook merging;
+- distribution tests covering clean repositories, existing `AGENTS.md`, existing `.codex/config.toml`, unrelated hooks, upgrade conflicts and uninstall conflicts;
+- deterministic release archive builder, candidate/production release gate, and tag-driven GitHub Release workflow;
+- deterministic C01-C16 qualification template archive containing fixture, prompt, config, expected result, current sanitized BLOCKED result, evaluation and SHA-256 manifests;
+- capability evidence materializer/validator/rehash tools and a live Codex sandbox runbook;
+- installation, troubleshooting, and release documentation.
+
 ### Changed
 
 - refresh the Codex capability baseline to 2.2 against current 2026-08-28 official documentation;
 - replace legacy agent concurrency/depth configuration with `agents.enabled` and `agents.max_concurrent_threads_per_session`;
 - enforce flat direct-child execution topology in the generated contract instead of relying on undocumented `agents.max_depth` behavior;
-- record the 2026-08-28 C01–C16 qualification attempt and its live Codex runtime blocker.
+- record the 2026-08-28 C01–C16 qualification attempt and its live Codex runtime blocker;
+- pin GitHub Actions to immutable SHAs and Node-24-based checkout/setup-python releases;
+- expand CI across Python 3.11 and the current upper supported interpreter on Ubuntu, macOS and Windows;
+- split distribution/release-candidate validation into a stable named CI check.
 
 ### Fixed
 
@@ -19,6 +36,10 @@ All notable changes to PlanAnvil are documented here.
 - make the Git-hook probe fixture emit explicit hook diagnostics while preserving fail-closed classification for unrelated commit failures;
 - synchronize golden blind-review fixtures and dependent comparison hashes with the required independent `plan-anvil-reviewer` author role.
 
+### Release status
+
+0.2.0 is code-complete as a release candidate. Production publication remains blocked until protected-`main` administration is enabled and required C01-C16 live Codex evidence is committed as `REPRODUCED`.
+
 ## [0.1.0] - 2026-07-12
 
 ### Added
@@ -39,4 +60,4 @@ All notable changes to PlanAnvil are documented here.
 
 ### Release status
 
-The deterministic core is implemented. Production readiness remains gated on reproduced Codex capability evidence defined in `docs/CODEX_CAPABILITY_BASELINE.md`.
+The deterministic core was implemented. Production readiness remained gated on reproduced Codex capability evidence.

README.md

@@ -6,9 +6,43 @@ It **generates and validates a plan but never executes it**. Product implementat
 
 ## Status
 
-The deterministic generator core, schemas, templates, tests, optional planning agents, and defense-in-depth hooks are implemented.
+**Distribution version:** 0.2.0.
 
-Release status is **candidate**, not production-ready. The Codex capability matrix in `docs/CODEX_CAPABILITY_BASELINE.md` remains a release gate until the required tests have committed sanitized `REPRODUCED` evidence for the current Codex version, model, operating systems, permission modes, and project-trust modes.
+The deterministic generator core, schemas, templates, tests, optional planning agents, defense-in-depth hooks, repository installer/upgrader/uninstaller, release tooling, and a deterministic C01-C16 live-qualification template archive/materializer are implemented.
+
+Release status is **candidate**, not production-ready. Deterministic CI is green, but production publication remains gated on two external steps:
+
+1. protect `main` with required PR/CI checks (tracked by issue #6);
+2. execute the prepared C01-C16 packages in an authenticated current Codex sandbox and commit required `REPRODUCED` evidence (tracked by issue #7).
+
+The capability contract is defined in `docs/CODEX_CAPABILITY_BASELINE.md`. Deterministic tests and prepared fixtures do not substitute for live Codex evidence.
+
+## Install into another repository
+
+From a PlanAnvil checkout or extracted release archive:
+
+```text
+python tools/plananvil_dist.py install --target /path/to/repository
+```
+
+The installer:
+
+- copies the PlanAnvil skill and project-scoped agent/hook files;
+- preserves an existing `AGENTS.md` unchanged;
+- conservatively merges compatible `[agents]` settings instead of replacing `.codex/config.toml`;
+- structurally merges only PlanAnvil entries into `.codex/hooks.json` while preserving unrelated hooks;
+- records file ownership/hashes in `.plananvil/installation.json`;
+- fails closed on unmanaged conflicts or locally modified managed files.
+
+Verify, upgrade, or uninstall:
+
+```text
+python tools/plananvil_dist.py verify --target /path/to/repository
+python tools/plananvil_dist.py --source /path/to/new/release upgrade --target /path/to/repository
+python tools/plananvil_dist.py uninstall --target /path/to/repository
+```
+
+See `docs/INSTALLATION.md` for the ownership and conflict contract.
 
 ## Use
 
@@ -44,31 +78,41 @@ python .agents/skills/plan-anvil/scripts/plan_anvil.py start \
   --goal "Add validation that rejects an empty display name."
 ```
 
-The bootstrap controller stops after isolation, profiling, run scaffolding, and durable bootstrap evidence. The skill then performs evidence-based analysis and plan authoring before deterministic validation, blind review, and the planning-only commit gate.
-
 ## Safety boundary
 
 PlanAnvil does not modify application code or tests, execute generated stages, deploy, migrate, restart services, switch a live environment, use destructive Git cleanup, or push or merge the base branch.
 
 The retained planning worktree is the durable control root. Machine-specific paths remain only in ignored local files; committed artifacts use repository-relative paths and Git identity.
 
-Project-scoped `.codex` agents and hooks are optional. Hooks require project trust and remain defense in depth; mandatory filesystem and Git postconditions apply in every hook mode.
+Project-scoped `.codex` agents and hooks remain defense in depth; mandatory filesystem and Git postconditions apply in every hook mode.
 
 ## Requirements
 
 - Python 3.11 or newer;
 - Git 2.30 or newer;
 - no elevated privileges;
-- no third-party Python packages for the deterministic core;
-- no network access for local validation.
+- no third-party Python packages for deterministic core/distribution tooling;
+- no network access for local validation or installation.
+
+CI tests Python 3.11 and the current upper supported interpreter on Ubuntu, macOS, and Windows. Parser/preflight tests enforce the Git 2.30 minimum; live Codex C16 remains responsible for the permission-mode Git capability matrix.
 
 ## Validation
 
 ```text
 python -m unittest discover -s .agents/skills/plan-anvil/tests -v
-python -m compileall -q .agents/skills/plan-anvil .codex/hooks
+python -m unittest discover -s tests -v
+python -m compileall -q .agents/skills/plan-anvil .codex/hooks tools tests
+python tools/release_check.py --candidate
 ```
 
+## Release and live qualification
+
+- `docs/RELEASE.md` — deterministic gates, tag workflow and publication contract
+- `docs/CODEX_SANDBOX_RUNBOOK.md` — exact remaining C01-C16 sandbox sequence
+- `capabilities/templates.part*` + `tools/prepare_capabilities.py` — deterministic prepared C01-C16 fixtures/prompts/config/assertions/results/hashes
+
+A production tag is rejected by `.github/workflows/release.yml` until every required capability is `REPRODUCED`.
+
 ## Documentation
 
 - `docs/IMPLEMENTATION_SPEC.md` — authoritative product and implementation contract
@@ -77,8 +121,11 @@ python -m compileall -q .agents/skills/plan-anvil .codex/hooks
 - `docs/RECOVERY_AND_VALIDATION.md` — crash recovery, checkpoint, schema and path-safety guarantees
 - `docs/OPENAI_COMPLIANCE.md` — Codex compatibility decisions
 - `docs/CODEX_CAPABILITY_BASELINE.md` — reproducible capability release gate
-- `docs/EXAMPLES.md` — expected decisions and output shapes
-- `capabilities/README.md` — evidence-package workflow
+- `docs/CODEX_CAPABILITY_QUALIFICATION_2026-08-28.md` — latest qualification audit
+- `docs/INSTALLATION.md` — install/upgrade/uninstall contract
+- `docs/TROUBLESHOOTING.md` — operational recovery guidance
+- `docs/RELEASE.md` — release workflow
+- `docs/CODEX_SANDBOX_RUNBOOK.md` — remaining live qualification procedure
 
 ## Author
 

VERSION

@@ -0,0 +1 @@
+0.2.0

capabilities/README.md

@@ -2,7 +2,14 @@
 
 This directory stores sanitized, reproducible evidence for the release gate in `docs/CODEX_CAPABILITY_BASELINE.md`.
 
-A capability is not `REPRODUCED` until its directory contains:
+`capabilities/templates.part*` contains deterministic prepared C01-C16 packages. Before a live qualification run, materialize them on the evidence branch:
+
+```text
+python tools/prepare_capabilities.py --force
+python tools/validate_capabilities.py
+```
+
+Each materialized package contains:
 
 ```text
 CXX/
@@ -17,6 +24,15 @@ CXX/
 └── hashes.json
 ```
 
-Record the exact Codex version, model slug, operating system, permission mode, project-trust mode, fixture commit, setup, cleanup, expected behavior, sanitized actual behavior, and evaluation. Remove usernames, home directories, private repository URLs, credentials, session identifiers, transcripts, unrelated Git databases, and proprietary source.
+The prepared result is `BLOCKED`: it documents the fixture and the lack of live runtime evidence. `REPRODUCED` requires a real current Codex run with exact Codex version, model slug, OS, permission mode, project-trust mode, fixture commit, sanitized observations, evaluation, and SHA-256 integrity.
+
+After editing one capability:
+
+```text
+python tools/rehash_capability.py C01
+python tools/validate_capabilities.py
+```
+
+Use `docs/CODEX_SANDBOX_RUNBOOK.md` for the full sequence. The materializer is path-traversal safe and writes only under `capabilities/`.
 
-The repository ships deterministic contract tests and evidence scaffolding, but does not label live Codex behavior as reproduced without these packages.
+Do not commit session transcripts, credentials, usernames, home directories, temporary absolute paths, private repository URLs, session identifiers, unrelated Git databases, or proprietary source. Keep only the minimal structural event/decision data required to evaluate `expected.json`.