patchshuttle 0.1.0a4__tar.gz → 0.1.0a6__tar.gz

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a6}/.github/workflows/ci.yml

@@ -47,14 +47,46 @@ jobs:
       - name: Check formatting
         run: python -m black --check src tests tools
       - name: Run tests with branch coverage
-        run: |
-          python -m coverage erase
-          python -m coverage run -m pytest -q
-          python -m coverage report --fail-under=100
+        run: python -m coverage run -m pytest -q
+      - name: Require full branch coverage
+        run: python -m coverage report --fail-under=100
+
+  postgres:
+    name: Django / PostgreSQL 16
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: patchshuttle_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: disposable-ci-password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install Django adapter and PostgreSQL driver
+        run: python -m pip install -e ".[django]" "psycopg[binary]>=3.2,<4"
+      - name: Check migration lifecycle and cross-connection lock
+        env:
+          PSH_PG_DATABASE: patchshuttle_test
+          PSH_PG_USER: postgres
+          PSH_PG_PASSWORD: disposable-ci-password
+          PSH_PG_PORT: "5432"
+        run: python tools/django_postgres_smoke.py
 
   package:
     name: Build and smoke-test distributions
-    needs: test
+    needs: [test, postgres]
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     steps:

{patchshuttle-0.1.0a4 → patchshuttle-0.1.0a6}/.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.0a6}/CHANGELOG.md

@@ -3,7 +3,50 @@
 All notable changes to PatchShuttle are recorded in this file. The project
 uses semantic versioning, including Python-compatible pre-release versions.
 
-## Unreleased
+## 0.1.0a6 - 2026-10-21
+
+### Added
+
+- Guarded `read_imports`, `ensure_import` and `remove_import` with alias-aware AST matching, comment preservation and binding checks.
+
+- Optional authenticated MCP history server for ChatGPT, scoped to one workspace and OAuth subject.
+- Optional Django migration command with hashed plans, database locks, pre/post checks, explicit reversals and separate recovery journals.
+- Guarded `move_range` and `move_symbol` source transfers between files,
+  including destination fingerprints, structural validation, Python constructors,
+  and shared transaction rollback.
+- Guarded `move_file` with destination absence checks, byte/mode preservation,
+  explicit deleted-file reporting, and automatic and manual rollback.
+
+- Optional AST guards for `replace_symbol`, with hashes and Python version
+  reported by `read_symbol`, replacement declaration validation and compile
+  validation. Existing text-only job serialization remains compatible.
+
+### Changed
+
+- Formatter child interpreters and Black preflight explicitly enable Python
+  UTF-8 mode, including under isolated execution.
+
+See `docs/NEXT_RELEASE.md` for implemented scope and remaining release work.
+
+## 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
 

patchshuttle-0.1.0a4/README.md → patchshuttle-0.1.0a6/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.4
+Name: patchshuttle
+Version: 0.1.0a6
+Summary: Local, auditable patch workflows for AI-assisted software development
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,automation,cli,development-tools,patch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: black<27,>=24
+Requires-Dist: click<9,>=8.1
+Requires-Dist: filelock<4,>=3.30
+Requires-Dist: isort<7,>=5.13
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruff<1,>=0.16
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: django<7,>=5.2; extra == 'dev'
+Requires-Dist: mcp<2,>=1.30; extra == 'dev'
+Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: twine<7,>=6.1; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<7,>=5.2; extra == 'django'
+Provides-Extra: html
+Requires-Dist: djlint<2,>=1.44; extra == 'html'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30; extra == 'mcp'
+Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # PatchShuttle
 
 PatchShuttle is intended to provide local, auditable patch workflows for
@@ -6,7 +50,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.0a6` 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 +61,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 +74,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 +107,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.0a6"
 ```
 
 For development from a local checkout:
@@ -70,7 +120,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.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -472,6 +522,13 @@ rejects missing, duplicate, syntactically invalid, or stale targets, and does
 not use fuzzy relocation or automatic line shifting. Exact desired symbol
 content is an idempotent `NO_CHANGE`.
 
+The optional `expected_ast_sha256` guard uses the structural hash from
+`read_symbol` to tolerate formatting changes. It ignores ordinary comments,
+includes docstrings and decorators, and is scoped to the reported Python minor
+version. Supply the text hash too when comments must be guarded. AST-guarded
+replacements retain the name and kind and undergo compile and resolution
+validation. See [next-release work](docs/NEXT_RELEASE.md) for current scope.
+
 For a supported plan, the implemented sequence is:
 
 1. validate the workspace lock file and acquire a non-blocking cross-platform
@@ -834,12 +891,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.0a6-py3-none-any.whl --version 0.1.0a6
 ```
 
-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 +950,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:
@@ -916,3 +1022,61 @@ model, or project.
 ## License
 
 PatchShuttle is licensed under the MIT License.
+
+
+## Guarded source transfers
+
+- `move_range`: `path`, `start_line`, `end_line`, source `expected_content`
+  and/or `expected_sha256`, `destination`, `destination_line` and
+  `expected_destination_sha256`.
+- `move_symbol`: `path`, `symbol`, `expected_ast_sha256`, `destination`,
+  `expected_destination_sha256` and optional `destination_class`.
+
+Destination hashes cover simulated raw bytes; source range hashes cover
+canonical LF/UTF-8 text. Destinations must exist or be created earlier in the
+same job. Range insertion is before the 1-based destination line; EOF+1 appends.
+Symbol insertion appends at module scope or to the named class. Both files are
+validated and participate in the same backup/check/rollback transaction.
+
+Same-file transfers, case-only path differences, duplicate destination names,
+closure extraction, class-bound super/private-name moves and multiline-string
+reindentation are rejected. Imports and callers are not automatically rewritten;
+include explicit edits and focused project checks. These actions move source
+content and leave the source file present. Whole-file moves are separate work.
+
+
+## Whole-file transfers
+
+`move_file` moves an existing supported text file to an absent destination.
+Supply `path`, `destination`, and `expected_sha256` of the original raw bytes.
+The transaction preserves original bytes and permissions, creates missing
+parent directories, and reports the source in `deleted_files`. Formatters and
+checks target the surviving destination. Add explicit import and caller edits
+when moving Python modules; imports are not automatically rewritten.
+
+The source and destination must not have been touched earlier in the job.
+Subsequent edits to the destination are supported. Case-only moves, chains,
+swaps, binary files and reuse of the vacated path are currently rejected.
+A failed check restores the source and removes the destination. Manual rollback
+also verifies the applied state and refuses to overwrite a recreated source.
+
+
+## Optional integrations
+
+- `patchshuttle[mcp]`: authenticated, read-only history retrieval for ChatGPT. See [setup and deployment limits](docs/CHATGPT_INTEGRATION.md).
+- `patchshuttle[django]`: reviewed migration plans, explicit execution/reversal, and a separate recovery journal. See [Django workflow](docs/DJANGO_MIGRATIONS.md).
+
+
+## Structural editing and optional adapters in 0.1.0a6
+
+Use `read_symbol` AST hashes for guarded class/method replacements; use
+`read_imports`, `ensure_import`, and `remove_import` for structural imports.
+`move_file`, `move_range`, and `move_symbol` support explicit refactoring plans
+with shared checks and rollback. Imports and callers are not inferred.
+See [scope and examples](docs/NEXT_RELEASE.md).
+
+Optional [ChatGPT history retrieval](docs/CHATGPT_INTEGRATION.md) uses an
+owner-configured authenticated MCP server (`patchshuttle[mcp]`).
+Optional [Django migrations](docs/DJANGO_MIGRATIONS.md) provide reviewed plans,
+locks and recovery journals (`patchshuttle[django]`). A live ChatGPT deployment
+requires the owner's HTTPS endpoint and OAuth configuration.

patchshuttle-0.1.0a4/PKG-INFO → patchshuttle-0.1.0a6/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.4
-Name: patchshuttle
-Version: 0.1.0a4
-Summary: Local, auditable patch workflows for AI-assisted software development
-License-Expression: MIT
-License-File: LICENSE
-Keywords: ai,automation,cli,development-tools,patch
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: black<27,>=24
-Requires-Dist: click<9,>=8.1
-Requires-Dist: filelock<4,>=3.30
-Requires-Dist: isort<7,>=5.13
-Requires-Dist: pydantic<3,>=2.6
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: ruff<1,>=0.16
-Requires-Dist: tomli<3,>=2; python_version < '3.11'
-Provides-Extra: dev
-Requires-Dist: build<2,>=1.2; extra == 'dev'
-Requires-Dist: django<7,>=5.2; extra == 'dev'
-Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
-Requires-Dist: pytest<10,>=8; extra == 'dev'
-Requires-Dist: twine<7,>=6.1; extra == 'dev'
-Provides-Extra: html
-Requires-Dist: djlint<2,>=1.44; extra == 'html'
-Description-Content-Type: text/markdown
-
 # PatchShuttle
 
 PatchShuttle is intended to provide local, auditable patch workflows for
@@ -43,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.0a6` 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 +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,
@@ -67,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
 
@@ -94,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.0a6"
 ```
 
 For development from a local checkout:
@@ -107,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.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -509,6 +478,13 @@ rejects missing, duplicate, syntactically invalid, or stale targets, and does
 not use fuzzy relocation or automatic line shifting. Exact desired symbol
 content is an idempotent `NO_CHANGE`.
 
+The optional `expected_ast_sha256` guard uses the structural hash from
+`read_symbol` to tolerate formatting changes. It ignores ordinary comments,
+includes docstrings and decorators, and is scoped to the reported Python minor
+version. Supply the text hash too when comments must be guarded. AST-guarded
+replacements retain the name and kind and undergo compile and resolution
+validation. See [next-release work](docs/NEXT_RELEASE.md) for current scope.
+
 For a supported plan, the implemented sequence is:
 
 1. validate the workspace lock file and acquire a non-blocking cross-platform
@@ -871,12 +847,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.0a6-py3-none-any.whl --version 0.1.0a6
 ```
 
-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 +906,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:
@@ -953,3 +978,61 @@ model, or project.
 ## License
 
 PatchShuttle is licensed under the MIT License.
+
+
+## Guarded source transfers
+
+- `move_range`: `path`, `start_line`, `end_line`, source `expected_content`
+  and/or `expected_sha256`, `destination`, `destination_line` and
+  `expected_destination_sha256`.
+- `move_symbol`: `path`, `symbol`, `expected_ast_sha256`, `destination`,
+  `expected_destination_sha256` and optional `destination_class`.
+
+Destination hashes cover simulated raw bytes; source range hashes cover
+canonical LF/UTF-8 text. Destinations must exist or be created earlier in the
+same job. Range insertion is before the 1-based destination line; EOF+1 appends.
+Symbol insertion appends at module scope or to the named class. Both files are
+validated and participate in the same backup/check/rollback transaction.
+
+Same-file transfers, case-only path differences, duplicate destination names,
+closure extraction, class-bound super/private-name moves and multiline-string
+reindentation are rejected. Imports and callers are not automatically rewritten;
+include explicit edits and focused project checks. These actions move source
+content and leave the source file present. Whole-file moves are separate work.
+
+
+## Whole-file transfers
+
+`move_file` moves an existing supported text file to an absent destination.
+Supply `path`, `destination`, and `expected_sha256` of the original raw bytes.
+The transaction preserves original bytes and permissions, creates missing
+parent directories, and reports the source in `deleted_files`. Formatters and
+checks target the surviving destination. Add explicit import and caller edits
+when moving Python modules; imports are not automatically rewritten.
+
+The source and destination must not have been touched earlier in the job.
+Subsequent edits to the destination are supported. Case-only moves, chains,
+swaps, binary files and reuse of the vacated path are currently rejected.
+A failed check restores the source and removes the destination. Manual rollback
+also verifies the applied state and refuses to overwrite a recreated source.
+
+
+## Optional integrations
+
+- `patchshuttle[mcp]`: authenticated, read-only history retrieval for ChatGPT. See [setup and deployment limits](docs/CHATGPT_INTEGRATION.md).
+- `patchshuttle[django]`: reviewed migration plans, explicit execution/reversal, and a separate recovery journal. See [Django workflow](docs/DJANGO_MIGRATIONS.md).
+
+
+## Structural editing and optional adapters in 0.1.0a6
+
+Use `read_symbol` AST hashes for guarded class/method replacements; use
+`read_imports`, `ensure_import`, and `remove_import` for structural imports.
+`move_file`, `move_range`, and `move_symbol` support explicit refactoring plans
+with shared checks and rollback. Imports and callers are not inferred.
+See [scope and examples](docs/NEXT_RELEASE.md).
+
+Optional [ChatGPT history retrieval](docs/CHATGPT_INTEGRATION.md) uses an
+owner-configured authenticated MCP server (`patchshuttle[mcp]`).
+Optional [Django migrations](docs/DJANGO_MIGRATIONS.md) provide reviewed plans,
+locks and recovery journals (`patchshuttle[django]`). A live ChatGPT deployment
+requires the owner's HTTPS endpoint and OAuth configuration.