patchshuttle 0.1.0a4__tar.gz → 0.1.0a5__tar.gz

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/.gitignore

@@ -26,5 +26,6 @@ Thumbs.db
 patches/applied/
 patches/backups/
 patches/failed/
+patches/history/
 patches/logs/
 patches/state/

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/CHANGELOG.md

@@ -5,6 +5,26 @@ uses semantic versioning, including Python-compatible pre-release versions.
 
 ## Unreleased
 
+## 0.1.0a5 - 2026-08-28
+
+Fourth alpha release, focused on persistent structured execution history
+for bounded external retrieval and long-term orchestration.
+
+### Added
+
+- Schema-versioned, append-only structured job history records under
+  `patches/history/<job-id>/` separate declared intent from observed execution
+  facts, reference detailed logs, preserve successful, failed, declined, and
+  rollback attempts, and expose bounded read-only Python and CLI access. History
+  persistence is a best-effort secondary artifact and cannot change a job result
+  or trigger rollback.
+
+### Fixed
+
+- Structured history models retain the canonical external `schema` JSON key
+  without shadowing Pydantic's legacy `BaseModel.schema` attribute or emitting a
+  warning during command startup.
+
 ## 0.1.0a4 - 2026-08-27
 
 Third alpha release, focused on bounded Python source discovery, compact

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchshuttle
-Version: 0.1.0a4
+Version: 0.1.0a5
 Summary: Local, auditable patch workflows for AI-assisted software development
 License-Expression: MIT
 License-File: LICENSE
@@ -43,7 +43,7 @@ describes a small job, the user reviews and runs it locally, and PatchShuttle
 records the result for the next iteration.
 
 > [!IMPORTANT]
-> PatchShuttle is alpha software. Version `0.1.0a4` implements the complete
+> PatchShuttle is alpha software. Version `0.1.0a5` implements the complete
 > local v0.1 workflow. It executes bounded read-only
 > audits, approved patch transactions, and approved one-pass verification jobs
 > under a project lock. Patch jobs retain backups, run controlled checks, apply
@@ -54,9 +54,9 @@ records the result for the next iteration.
 > Trusted Publishing workflows are implemented. Every versioned release must
 > pass its own local qualification, GitHub-hosted Windows/Ubuntu matrix,
 > TestPyPI installation, production publication, and post-release smoke gates.
-> The immutable `0.1.0a2` and `0.1.0a3` qualification evidence, plus the
-> separately scoped `0.1.0a2` ChatGPT end-to-end workflow, are retained in
-> [docs/RELEASE.md](docs/RELEASE.md).
+> The immutable `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` qualification
+> evidence, plus the separately scoped `0.1.0a2` ChatGPT end-to-end
+> workflow, are retained in [docs/RELEASE.md](docs/RELEASE.md).
 
 > [!NOTE]
 > Compared with `0.1.0a2`, version `0.1.0a3` adds AI-facing planner diagnostics,
@@ -67,14 +67,20 @@ records the result for the next iteration.
 > range hash.
 
 > [!NOTE]
-> The current development branch also contains unreleased work completed after
-> `0.1.0a3`: `search_context`, `read_symbol`, guarded `replace_symbol`, a fixed
-> Ruff F-only check, compact text and JSON AI log views, explicit Django warning
-> baselines, owner-controlled project-check Python selection, evidence-only
-> Python discovery telemetry, expanded Python secret redaction, nested
-> dependency-environment exclusions, and bounded declaration-only
-> `python_structure` discovery. These features are available from the source
-> branch and are not part of the immutable `0.1.0a3` PyPI artifacts.
+> Version `0.1.0a4` adds `search_context`, `read_symbol`, guarded
+> `replace_symbol`, the fixed Ruff F-only check, compact AI log views, Django
+> warning baselines, owner-controlled project-check Python selection,
+> evidence-only Python discovery telemetry, expanded redaction, bounded
+> declaration-only `python_structure` discovery with compact output, and
+> owner-controlled architecture ratchets. These features are included in the
+> immutable `0.1.0a4` PyPI artifacts.
+
+> [!NOTE]
+> Version `0.1.0a5` adds schema-versioned append-only structured job
+> history, facts-first records, best-effort persistence, and bounded
+> read-only Python and CLI retrieval. Detailed execution logs remain the
+> diagnostic source; external orchestrators remain responsible for project
+> memory, semantic retrieval, requirements, and user decisions.
 
 ## Design goals
 
@@ -94,7 +100,7 @@ After publication, install the exact alpha release from PyPI:
 ```bash
 python -m venv .venv
 python -m pip install --upgrade pip
-python -m pip install "patchshuttle==0.1.0a4"
+python -m pip install "patchshuttle==0.1.0a5"
 ```
 
 For development from a local checkout:
@@ -107,7 +113,7 @@ To enable opt-in HTML template linting in an installed release, install the
 `html` extra:
 
 ```bash
-python -m pip install "patchshuttle[html]==0.1.0a4"
+python -m pip install "patchshuttle[html]==0.1.0a5"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -871,12 +877,13 @@ python -m coverage report --fail-under=100
 python -m build
 python -m twine check dist/*
 python tools/release_checks.py dist
-python tools/wheel_smoke.py dist/patchshuttle-0.1.0a4-py3-none-any.whl --version 0.1.0a4
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a5-py3-none-any.whl --version 0.1.0a5
 ```
 
-The `0.1.0a2` and `0.1.0a3` alpha releases each passed the required Ubuntu and
-Windows compatibility matrix, TestPyPI qualification, production PyPI Trusted
-Publishing, and a clean post-release installation. Their exact release and
+The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
+required Ubuntu and Windows compatibility matrix, TestPyPI qualification,
+production PyPI Trusted Publishing, and a clean post-release installation.
+Their exact release and
 workflow links and artifact hashes, together with the separately scoped
 `0.1.0a2` ChatGPT end-to-end evidence, are recorded in
 [docs/RELEASE.md](docs/RELEASE.md). Follow that guide in order for every future
@@ -929,6 +936,54 @@ confirmation, backup, or project checks.
 This is deliberately a structural guard. It does not infer feature boundaries,
 build dependency or call graphs, detect cycles, judge semantic responsibility,
 reorganize files, or change the patch scope selected by the AI.
+
+## Structured project history
+
+PatchShuttle writes one compact JSON record for each recorded execution attempt to
+`patches/history/<job-id>/<record-id>.json`. These records are intended for
+long-term external ingestion and AI retrieval. They describe PatchShuttle's own
+operations only; requirements, conversations, product decisions, stages, browser
+tests, and semantic project memory belong to an external orchestrator.
+
+History has a different purpose from the other outputs:
+
+- execution logs contain detailed diagnostic evidence and command output;
+- AI logs are bounded deterministic views derived from execution logs;
+- history records contain compact schema-versioned facts plus references to the
+  detailed log and its derived AI-log view.
+
+`job.title` and bounded, redacted `job.description` are stored below `declared` as
+operator or AI-supplied intent. They are never presented as observed facts.
+`observed` contains only trusted execution state: status, files, checks, failures,
+rollback, warnings, and reliably targeted symbols. PatchShuttle does not infer
+workarounds, semantic meaning, relationships, or affected symbols it cannot prove.
+
+Read records without parsing human-readable logs:
+
+```powershell
+patchshuttle history list --limit 20
+patchshuttle history latest
+patchshuttle history latest PATCH-EXAMPLE-001
+patchshuttle history show PATCH-EXAMPLE-001/2026_08_27_120000_000001_abcdef01
+```
+
+`latest` and `show` return the full canonical JSON record. `list` returns bounded
+JSON summaries, one per line. Python integrations can call
+`list_history_records`, `latest_history_record`, and `read_history_record` from
+`patchshuttle.history`. External systems may also ingest the per-attempt JSON files
+directly.
+
+History writing occurs after the required detailed log and registry update. It is
+best-effort: a history storage failure is exposed through the Python result's
+`history_warning`, but does not turn a completed job into a failure or trigger
+rollback. Existing protocol-1 jobs require no changes. Existing workspaces may add
+`patches/history/**` to `project.ignored_paths`; new default configurations already
+exclude it from workspace inventories.
+
+The v1 layout is append-only and uses exclusive file creation. It deliberately has
+no database, JSONL index, semantic search, vector store, relationship graph, or
+Farm-specific behavior.
+
 ## Manual workflow
 
 The implemented local cycle is:

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/README.md

@@ -6,7 +6,7 @@ describes a small job, the user reviews and runs it locally, and PatchShuttle
 records the result for the next iteration.
 
 > [!IMPORTANT]
-> PatchShuttle is alpha software. Version `0.1.0a4` implements the complete
+> PatchShuttle is alpha software. Version `0.1.0a5` implements the complete
 > local v0.1 workflow. It executes bounded read-only
 > audits, approved patch transactions, and approved one-pass verification jobs
 > under a project lock. Patch jobs retain backups, run controlled checks, apply
@@ -17,9 +17,9 @@ records the result for the next iteration.
 > Trusted Publishing workflows are implemented. Every versioned release must
 > pass its own local qualification, GitHub-hosted Windows/Ubuntu matrix,
 > TestPyPI installation, production publication, and post-release smoke gates.
-> The immutable `0.1.0a2` and `0.1.0a3` qualification evidence, plus the
-> separately scoped `0.1.0a2` ChatGPT end-to-end workflow, are retained in
-> [docs/RELEASE.md](docs/RELEASE.md).
+> The immutable `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` qualification
+> evidence, plus the separately scoped `0.1.0a2` ChatGPT end-to-end
+> workflow, are retained in [docs/RELEASE.md](docs/RELEASE.md).
 
 > [!NOTE]
 > Compared with `0.1.0a2`, version `0.1.0a3` adds AI-facing planner diagnostics,
@@ -30,14 +30,20 @@ records the result for the next iteration.
 > range hash.
 
 > [!NOTE]
-> The current development branch also contains unreleased work completed after
-> `0.1.0a3`: `search_context`, `read_symbol`, guarded `replace_symbol`, a fixed
-> Ruff F-only check, compact text and JSON AI log views, explicit Django warning
-> baselines, owner-controlled project-check Python selection, evidence-only
-> Python discovery telemetry, expanded Python secret redaction, nested
-> dependency-environment exclusions, and bounded declaration-only
-> `python_structure` discovery. These features are available from the source
-> branch and are not part of the immutable `0.1.0a3` PyPI artifacts.
+> Version `0.1.0a4` adds `search_context`, `read_symbol`, guarded
+> `replace_symbol`, the fixed Ruff F-only check, compact AI log views, Django
+> warning baselines, owner-controlled project-check Python selection,
+> evidence-only Python discovery telemetry, expanded redaction, bounded
+> declaration-only `python_structure` discovery with compact output, and
+> owner-controlled architecture ratchets. These features are included in the
+> immutable `0.1.0a4` PyPI artifacts.
+
+> [!NOTE]
+> Version `0.1.0a5` adds schema-versioned append-only structured job
+> history, facts-first records, best-effort persistence, and bounded
+> read-only Python and CLI retrieval. Detailed execution logs remain the
+> diagnostic source; external orchestrators remain responsible for project
+> memory, semantic retrieval, requirements, and user decisions.
 
 ## Design goals
 
@@ -57,7 +63,7 @@ After publication, install the exact alpha release from PyPI:
 ```bash
 python -m venv .venv
 python -m pip install --upgrade pip
-python -m pip install "patchshuttle==0.1.0a4"
+python -m pip install "patchshuttle==0.1.0a5"
 ```
 
 For development from a local checkout:
@@ -70,7 +76,7 @@ To enable opt-in HTML template linting in an installed release, install the
 `html` extra:
 
 ```bash
-python -m pip install "patchshuttle[html]==0.1.0a4"
+python -m pip install "patchshuttle[html]==0.1.0a5"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -834,12 +840,13 @@ python -m coverage report --fail-under=100
 python -m build
 python -m twine check dist/*
 python tools/release_checks.py dist
-python tools/wheel_smoke.py dist/patchshuttle-0.1.0a4-py3-none-any.whl --version 0.1.0a4
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a5-py3-none-any.whl --version 0.1.0a5
 ```
 
-The `0.1.0a2` and `0.1.0a3` alpha releases each passed the required Ubuntu and
-Windows compatibility matrix, TestPyPI qualification, production PyPI Trusted
-Publishing, and a clean post-release installation. Their exact release and
+The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
+required Ubuntu and Windows compatibility matrix, TestPyPI qualification,
+production PyPI Trusted Publishing, and a clean post-release installation.
+Their exact release and
 workflow links and artifact hashes, together with the separately scoped
 `0.1.0a2` ChatGPT end-to-end evidence, are recorded in
 [docs/RELEASE.md](docs/RELEASE.md). Follow that guide in order for every future
@@ -892,6 +899,54 @@ confirmation, backup, or project checks.
 This is deliberately a structural guard. It does not infer feature boundaries,
 build dependency or call graphs, detect cycles, judge semantic responsibility,
 reorganize files, or change the patch scope selected by the AI.
+
+## Structured project history
+
+PatchShuttle writes one compact JSON record for each recorded execution attempt to
+`patches/history/<job-id>/<record-id>.json`. These records are intended for
+long-term external ingestion and AI retrieval. They describe PatchShuttle's own
+operations only; requirements, conversations, product decisions, stages, browser
+tests, and semantic project memory belong to an external orchestrator.
+
+History has a different purpose from the other outputs:
+
+- execution logs contain detailed diagnostic evidence and command output;
+- AI logs are bounded deterministic views derived from execution logs;
+- history records contain compact schema-versioned facts plus references to the
+  detailed log and its derived AI-log view.
+
+`job.title` and bounded, redacted `job.description` are stored below `declared` as
+operator or AI-supplied intent. They are never presented as observed facts.
+`observed` contains only trusted execution state: status, files, checks, failures,
+rollback, warnings, and reliably targeted symbols. PatchShuttle does not infer
+workarounds, semantic meaning, relationships, or affected symbols it cannot prove.
+
+Read records without parsing human-readable logs:
+
+```powershell
+patchshuttle history list --limit 20
+patchshuttle history latest
+patchshuttle history latest PATCH-EXAMPLE-001
+patchshuttle history show PATCH-EXAMPLE-001/2026_08_27_120000_000001_abcdef01
+```
+
+`latest` and `show` return the full canonical JSON record. `list` returns bounded
+JSON summaries, one per line. Python integrations can call
+`list_history_records`, `latest_history_record`, and `read_history_record` from
+`patchshuttle.history`. External systems may also ingest the per-attempt JSON files
+directly.
+
+History writing occurs after the required detailed log and registry update. It is
+best-effort: a history storage failure is exposed through the Python result's
+`history_warning`, but does not turn a completed job into a failure or trigger
+rollback. Existing protocol-1 jobs require no changes. Existing workspaces may add
+`patches/history/**` to `project.ignored_paths`; new default configurations already
+exclude it from workspace inventories.
+
+The v1 layout is append-only and uses exclusive file creation. It deliberately has
+no database, JSONL index, semantic search, vector store, relationship graph, or
+Farm-specific behavior.
+
 ## Manual workflow
 
 The implemented local cycle is:

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/SPEC_V0_1.md

@@ -13,20 +13,17 @@
 > on 2026-08-16, followed by successful TestPyPI qualification, production
 > PyPI publication, and a clean installation smoke test. A recorded ChatGPT
 > end-to-end workflow passed on Windows 11 with Python 3.14.2 on 2026-08-17.
-> Version `0.1.0a3` is a published alpha release, not stable `0.1.0`.
-> Compared with published `0.1.0a2`, it adds AI-facing mismatch diagnostics,
-> resolved diff previews, Python formatter preflight, opt-in changed-HTML
-> linting, early failure logs, explicit workspace routing, installed-contract
-> self-documentation, per-file formatter policy, Django-aware import checks,
-> defensive runtime-cache cleanup, and guarded physical-line range actions.
-> The feature-complete source passed 834 local tests on Linux/Python 3.12 with
-> one environment-only skip, 100% statement and branch coverage, release
-> artifact validation, `twine check`, and a clean wheel smoke test. The final
-> versioned commit `06f3125aacd92ae32a832d34d86246a97fdc74f7` passed the
-> required hosted Windows/Ubuntu matrix, TestPyPI qualification, production
-> PyPI publication, and a clean Windows CPython 3.14 installation on
-> 2026-08-23. TestPyPI and production PyPI contain byte-identical `0.1.0a3`
-> distributions.
+> Version `0.1.0a4` is a published alpha release, not stable `0.1.0`.
+> It retains the published `0.1.0a3` workflow and adds bounded Python source
+> discovery, compact structure output, owner-controlled project-check Python
+> selection, evidence-only discovery telemetry, and owner-controlled Python
+> architecture ratchets. The immutable artifacts were built from commit
+> `f0f6188b6e81727401152023d701f0e065fcc481` and passed the required hosted
+> Windows/Ubuntu matrix, TestPyPI qualification, production PyPI Trusted
+> Publishing, and a clean Windows CPython 3.14 installation on 2026-08-27.
+> TestPyPI and production PyPI contain byte-identical `0.1.0a4`
+> distributions; exact workflow links, sizes, and SHA-256 hashes are recorded
+> in `docs/RELEASE.md`.
 >
 > This document defines the target behavior of PatchShuttle v0.1. The README
 > identifies the currently implemented subset; all other features remain
@@ -413,6 +410,36 @@ The policy is structural only: it does not inspect source semantics, infer
 features or dependencies, build graphs, reorganize files, or choose patch scope.
 Disabling or changing thresholds requires an owner edit to
 `patches/patchshuttle.toml`.
+### 9.2 Persistent structured job history
+
+PatchShuttle records compact facts about its own execution attempts separately from
+full diagnostic logs. A history record is a schema-versioned JSON projection of the
+same trusted run state used by logging. It separates submitted intent from observed
+execution facts and references, rather than duplicates, detailed evidence.
+
+Version 1 uses one exclusive file per attempt under
+`patches/history/<job-id>/<record-id>.json`. Multiple attempts for the same job ID
+never overwrite one another. Readers validate schema, project identity, record/path
+identity, real-file boundaries, and size and scan limits. External orchestrators may
+ingest these files into their own databases and indexes.
+
+Required content includes PatchShuttle and schema versions, job identity and hash,
+timestamp, result and exit code, bounded declared title and description intent,
+planned counts and targets, observed file changes, executed checks, failure and
+rollback facts, check warnings, and references to detailed log, derived AI-log view,
+archived job, and backup. Affected symbols are included only when an explicit
+`replace_symbol` target corresponds to an observed affected file. Relationships are
+`null` in v1 because protocol 1 supplies no authoritative relationship metadata.
+
+History creation is a best-effort secondary operation after log and registry
+persistence. Failure to create it does not fail or roll back an otherwise completed
+job. The Python result exposes the bounded warning. Existing job schemas, normalized
+hashes, registry semantics, logs, and AI-log formats remain unchanged.
+
+PatchShuttle does not store conversations, requirements, product decisions, stages,
+artifacts, runtime history, semantic memory, or vector indexes. Those remain the
+responsibility of external orchestration systems.
+
 ## 10. YAML job protocol
 
 ### 10.1 Canonical extension
@@ -1930,7 +1957,7 @@ has been tested through a documented end-to-end scenario.
   TestPyPI and production Trusted Publishing, and a clean production-index
   installation on 2026-08-23.
 
-### Unreleased after `0.1.0a3`
+### `0.1.0a4`
 
 - bounded `search_context` and decorator-aware Python `read_symbol` audits;
 - guarded `replace_symbol` planning and transactional execution;
@@ -1952,6 +1979,25 @@ has been tested through a documented end-to-end scenario.
   the standard-library AST, with no project-code execution, semantic resolution,
   cache, persistence, inferred patch scope, or symbol-index implementation verdict.
 
+- opt-in compact `python_structure` output that retains bounded navigational
+  identities, source ranges, parse errors, and limit signals;
+- owner-controlled `modular-monolith` / `package-by-feature` architecture
+  ratchets with bounded stable `ARCH` findings;
+- immutable artifacts from commit
+  `f0f6188b6e81727401152023d701f0e065fcc481` passed final `main` and tag CI,
+  TestPyPI and production Trusted Publishing, and a clean production-index
+  Windows CPython 3.14 installation on 2026-08-27.
+### `0.1.0a5`
+
+- schema-versioned append-only structured records for PatchShuttle job
+  attempts, with declared intent kept separate from observed execution facts;
+- compact file, check, failure, rollback, warning, and diagnostic-reference
+  metadata without full command output, patch contents, or project memory;
+- best-effort secondary persistence that cannot change an authoritative job
+  result or trigger rollback;
+- bounded read-only Python and CLI retrieval for external ingestion, without a
+  database, semantic search, relationship graph, or orchestrator-specific state.
+
 ### `0.1.0b1`
 
 - AI guide and handoff;
@@ -2008,7 +2054,7 @@ PatchShuttle v0.1.0 is ready when all of the following are demonstrated:
 
 ### Current qualification record
 
-As of the completed `0.1.0a3` qualification on 2026-08-23, criteria 1 through
+As of the completed `0.1.0a4` qualification on 2026-08-27, criteria 1 through
 18 above have explicit evidence for that published alpha release: local
 implementation and test evidence for criteria 2 through 16, plus independent
 hosted CI, TestPyPI, production PyPI, and clean post-release installation

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # PatchShuttle release guide
 
-This guide records the immutable published `0.1.0a2` and `0.1.0a3` evidence and
+This guide records the immutable published `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` evidence and
 the staged qualification procedure for later releases. Do not publish a
 stable `0.1.0` release until every acceptance criterion in `SPEC_V0_1.md` has
 passed and the stable release is approved.
@@ -98,6 +98,44 @@ The **Tested with ChatGPT** statement remains scoped to the separately recorded
 `0.1.0a2` end-to-end workflow above; this release record does not silently
 extend that product claim to `0.1.0a3`.
 
+## 0.2. Recorded `0.1.0a4` qualification
+
+The immutable `0.1.0a4` artifacts were built from commit
+`f0f6188b6e81727401152023d701f0e065fcc481`. The annotated
+`v0.1.0a4` tag resolves to the same commit. The release adds bounded
+Python source discovery, compact structure output, owner-controlled
+project-check Python selection, evidence-only discovery telemetry, and
+owner-controlled Python architecture ratchets.
+
+The release passed these external gates on 2026-08-27:
+
+- [final release-candidate CI on `main`](https://github.com/ratundo/patchshuttle/actions/runs/33089001064);
+- [TestPyPI publication](https://github.com/ratundo/patchshuttle/actions/runs/33094686124);
+- [CI for tag `v0.1.0a4`](https://github.com/ratundo/patchshuttle/actions/runs/33095708487);
+- [GitHub `v0.1.0a4` pre-release](https://github.com/ratundo/patchshuttle/releases/tag/v0.1.0a4);
+- [production PyPI Trusted Publishing](https://github.com/ratundo/patchshuttle/actions/runs/33096689962);
+- [production PyPI release](https://pypi.org/project/patchshuttle/0.1.0a4/)
+  and a clean post-release installation smoke test.
+
+TestPyPI and production PyPI received byte-identical distributions:
+
+- wheel `patchshuttle-0.1.0a4-py3-none-any.whl`, 167610 bytes,
+  SHA-256:
+  `b5a372b3879ea7382903556cb041ff9233d5e44624da28a5d1a2d8a2bdd2c832`;
+- source archive `patchshuttle-0.1.0a4.tar.gz`, 296869 bytes,
+  SHA-256:
+  `14585ad971f374da2466807e876c4742acd140a069ae2ab159afccec297ad05c`.
+
+A separate clean Windows CPython 3.14 temporary environment installed
+`patchshuttle[html]==0.1.0a4` from production PyPI with
+`--no-cache-dir`. `patchshuttle version` reported
+`PatchShuttle 0.1.0a4`; `patchshuttle capabilities` reported
+`patchshuttle_version: 0.1.0a4` and `protocol: 1`.
+
+The **Tested with ChatGPT** statement remains scoped to the separately
+recorded `0.1.0a2` end-to-end workflow above. This release record does
+not extend that claim to every action, AI model, project, or intentional
+failure and rollback path.
 ## 1. Local release gate
 
 From a clean repository root, use Python 3.12 and start with an empty `dist/`
@@ -119,8 +157,8 @@ python tools/wheel_smoke.py dist/patchshuttle-<VERSION>-py3-none-any.whl --versi
 
 `release_checks.py` requires exactly one wheel and one source archive for the
 source version and writes `dist/SHA256SUMS`. Replace `<VERSION>` with the exact
-source version under qualification. For the recorded qualification above it
-was `0.1.0a3`. Do not reuse an immutable published version for a future upload.
+source version under qualification. For the most recent recorded qualification it
+was `0.1.0a4`. Do not reuse an immutable published version for a future upload.
 
 During a source-version transition, metadata in an already-installed editable
 environment may still report the previous version until the package is
@@ -128,11 +166,12 @@ reinstalled. Source-tree tests validate the imported source version. The build,
 `release_checks.py`, and clean-wheel smoke test are the authoritative metadata
 alignment gates for the new distributions.
 
-For the next alpha, the local and hosted suites must also retain explicit
-coverage for formatter baseline-versus-planned classification, per-tool local
-exclusions, `django_import_check`, and rollback after runtime `.pyc` creation.
-The plan and run logs must show the resolved formatter decision for each
-changed Python path.
+Future release candidates must retain explicit coverage for formatter
+baseline-versus-planned classification, per-tool local exclusions,
+`django_import_check`, rollback after runtime `.pyc` creation, bounded Python
+structure discovery, architecture-ratchet evaluation, structured-history wheel
+contents, and clean-installed history persistence and retrieval. Plan and run
+logs must keep exposing resolved formatter and architecture decisions.
 
 ## 2. Publish the repository and run CI
 

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/src/patchshuttle/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the PatchShuttle package version."""
 
-__version__ = "0.1.0a4"
+__version__ = "0.1.0a5"

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/src/patchshuttle/cli.py

@@ -26,6 +26,7 @@ from patchshuttle.execution import (
     record_declined_plan,
     resolve_registered_job,
 )
+from patchshuttle.history.cli import history_command
 from patchshuttle.logging import (
     AttemptLogData,
     current_run_clock,
@@ -74,6 +75,9 @@ def main(workspace_path: Path | None) -> None:
     """Run local, auditable workflows for AI-assisted project changes."""
 
 
+main.add_command(history_command)
+
+
 @main.command()
 def version() -> None:
     """Print the installed PatchShuttle version."""
@@ -328,10 +332,7 @@ def snapshot_command() -> None:
     except WorkspaceError as error:
         _fail_workspace(error, failure_prefix="SNAPSHOT_FAILED")
     except ExecutionError as error:
-        click.echo(
-            _render_execution_error(error, prefix="SNAPSHOT_FAILED"),
-            err=True,
-        )
+        click.echo(_render_execution_error(error, prefix="SNAPSHOT_FAILED"), err=True)
         raise click.exceptions.Exit(execution_exit_code(error.code)) from error
     click.echo(
         "\n".join(
@@ -355,10 +356,7 @@ def handoff_command() -> None:
     except WorkspaceError as error:
         _fail_workspace(error, failure_prefix="HANDOFF_FAILED")
     except ExecutionError as error:
-        click.echo(
-            _render_execution_error(error, prefix="HANDOFF_FAILED"),
-            err=True,
-        )
+        click.echo(_render_execution_error(error, prefix="HANDOFF_FAILED"), err=True)
         raise click.exceptions.Exit(execution_exit_code(error.code)) from error
     click.echo(
         "\n".join(

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/src/patchshuttle/config.py

@@ -46,6 +46,7 @@ DEFAULT_PROTECTED_PATH_EXCEPTIONS = (
 DEFAULT_IGNORED_PATHS = (
     ".git/**",
     "patches/backups/**",
+    "patches/history/**",
     "patches/logs/**",
     "patches/state/**",
     "**/.venv/**",

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a5}/src/patchshuttle/errors.py

@@ -268,6 +268,8 @@ class ExecutionError(RuntimeError):
         workspace_comparison: WorkspaceComparison | None = None,
         log_path: Path | None = None,
         archived_job_path: Path | None = None,
+        history_path: Path | None = None,
+        history_warning: str | None = None,
     ) -> None:
         self.code = code
         self.message = message
@@ -285,6 +287,8 @@ class ExecutionError(RuntimeError):
         self.workspace_comparison = workspace_comparison
         self.log_path = log_path
         self.archived_job_path = archived_job_path
+        self.history_path = history_path
+        self.history_warning = history_warning
         super().__init__(message)
 
     def __str__(self) -> str: