patchshuttle 0.1.0a5__tar.gz → 0.1.0a7__tar.gz

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

@@ -3,7 +3,60 @@
 All notable changes to PatchShuttle are recorded in this file. The project
 uses semantic versioning, including Python-compatible pre-release versions.
 
-## Unreleased
+## 0.1.0a7 - release candidate (not yet published)
+
+- Audit AI instructions: complete action catalogs, correct method YAML indentation
+  and job-ID rules, clarify guard sources, MCP limits and database boundaries.
+
+- Add `python_references` for bounded, explicitly unverified symbol-reference
+  candidates with import aliases and unresolved attributes.
+
+- Add read-only `python_dependencies` for static local import candidates, cycle
+  groups and explicitly unresolved/dynamic cases before module refactoring.
+
+- Add opt-in, bounded action drafts to symbol/import audits with observed guards;
+  fragments require review and never execute during audit.
+
+- Add `edit_imports`: 1-100 ordered import edits guarded by one initial import
+  hash, with step diagnostics and the existing import safety checks.
+
+- Explain structural replacement failures with bounded indentation context and
+  YAML guidance, without rewriting input or changing guard semantics.
+
+- Add reviewed `docs refresh` for recognized AI guide templates, retaining
+  appended owner notes and exact backups; unknown inline edits require review.
+- Add conditional Python symbol-edit guidance to CLI plans, full and compact
+  logs, including targeting failures; advisory does not alter guards or policy.
+- Add operation-selection rules and an audit-to-patch example to AI guidance.
+- Prefer configured MCP history retrieval, retaining manual logs as fallback.
+- Count symbol/range transfers and report structural imports and file moves.
+- Extract plan and discovery-log presentation into smaller modules without
+  relaxing the existing architecture ratchet.
+
+## 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
 

patchshuttle-0.1.0a5/README.md → patchshuttle-0.1.0a7/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.4
+Name: patchshuttle
+Version: 0.1.0a7
+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,8 @@ 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.0a5` implements the complete
+> PatchShuttle is alpha software. This branch prepares `0.1.0a7`; the latest
+> recorded published version is `0.1.0a6`. It 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
@@ -63,7 +108,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.0a5"
+python -m pip install "patchshuttle==0.1.0a6"
 ```
 
 For development from a local checkout:
@@ -76,7 +121,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.0a5"
+python -m pip install "patchshuttle[html]==0.1.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -439,7 +484,8 @@ retained formatted-file states, final check results, audit observations, and a
 workspace comparison where applicable.
 
 An audit executes `tree`, `read`, literal `search`, bounded `search_context`,
-Python `read_symbol`, `find_files`, `file_info`, SHA-256 `hash`, canonical
+Python `read_symbol`, `read_imports`, `python_structure`, `python_dependencies`,
+`python_references`, `find_files`, `file_info`, SHA-256 `hash`, canonical
 `hash_range`, `git_status`, and `environment`. Traversal, file reads, match
 counts, and recorded output are bounded by local policy. Protected and ignored
 paths are skipped, source content appears only when explicitly requested by a
@@ -459,7 +505,8 @@ automatically undo those changes.
 
 A patch plan may contain `create_directory`, `create_file`, `replace_exact`,
 `replace_symbol`, `insert_before`, `insert_after`, `delete_exact`,
-`replace_range`, `delete_range`, `insert_at_line`, or `apply_diff` actions and
+`replace_range`, `delete_range`, `insert_at_line`, `apply_diff`, `ensure_import`,
+`remove_import`, `edit_imports`, `move_file`, `move_range`, or `move_symbol` actions and
 applies the final bytes already computed by the planner.
 
 The optional line-range actions are strict guarded operations for cases where
@@ -478,6 +525,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
@@ -713,18 +767,19 @@ actions:
       symbol: Service.run
 ```
 
-If a change is needed, copy the canonical SHA-256 returned by `read_symbol`
-into a guarded patch action:
+If a change is needed, use the audit-derived draft or copy `ast_sha256` from
+`read_symbol` on the same Python minor version. Add its text `sha256` too when
+comments must be guarded. The action below is illustrative:
 
 ```yaml
 actions:
   - replace_symbol:
       path: src/example/service.py
       symbol: Service.run
-      expected_sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-      new_content: |
-        def run(self, value):
-            return value
+      expected_ast_sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+      new_content: |2
+            def run(self, value):
+                return value
 ```
 
 The same audit can be constructed through the public Python adapter:
@@ -840,7 +895,7 @@ 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.0a5-py3-none-any.whl --version 0.1.0a5
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a7-py3-none-any.whl --version 0.1.0a7
 ```
 
 The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
@@ -958,7 +1013,9 @@ The implemented local cycle is:
 5. For a patch, run optional changed-HTML linting, controlled checks, the
    locally resolved isort/Black scopes, and final checks.
 6. Receive a timestamped log or generate a fresh handoff.
-7. Review the log, upload it to the AI, and continue with the next job.
+7. Retrieve configured MCP history or provide the log through an authorized
+   channel. Current MCP history returns summaries/references, not full logs.
+   Review the observed result before continuing with the next job.
 
 See [SPEC_V0_1.md](SPEC_V0_1.md) for the approved product contract and
 [CHANGELOG.md](CHANGELOG.md) for release notes. PatchShuttle is designed for
@@ -971,3 +1028,76 @@ 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.
+
+
+## AI workflow in a7 development
+
+Start with the installed capabilities/schema and the workspace handoff. The
+[AI guide](src/patchshuttle/resources/AI_GUIDE.md) contains the operation decision
+table, guard sources, refactoring checklist and recovery boundaries. Existing
+Python declaration edits should normally use `read_symbol` then `replace_symbol`;
+request `include_template: true` for a guarded draft. Use `edit_imports` for a
+sequence of import edits. Keep audits separate from patches and review actual
+execution outcomes. The explicit `|2` in the method example preserves Python
+indentation after YAML parsing. Documentation examples use illustrative bodies
+and hashes; replace these with observed source and guards before submitting.
+
+This section describes the development branch, not a published a7 release.

patchshuttle-0.1.0a5/PKG-INFO → patchshuttle-0.1.0a7/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.4
-Name: patchshuttle
-Version: 0.1.0a5
-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,8 @@ 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.0a5` implements the complete
+> PatchShuttle is alpha software. This branch prepares `0.1.0a7`; the latest
+> recorded published version is `0.1.0a6`. It 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
@@ -100,7 +64,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.0a5"
+python -m pip install "patchshuttle==0.1.0a6"
 ```
 
 For development from a local checkout:
@@ -113,7 +77,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.0a5"
+python -m pip install "patchshuttle[html]==0.1.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -476,7 +440,8 @@ retained formatted-file states, final check results, audit observations, and a
 workspace comparison where applicable.
 
 An audit executes `tree`, `read`, literal `search`, bounded `search_context`,
-Python `read_symbol`, `find_files`, `file_info`, SHA-256 `hash`, canonical
+Python `read_symbol`, `read_imports`, `python_structure`, `python_dependencies`,
+`python_references`, `find_files`, `file_info`, SHA-256 `hash`, canonical
 `hash_range`, `git_status`, and `environment`. Traversal, file reads, match
 counts, and recorded output are bounded by local policy. Protected and ignored
 paths are skipped, source content appears only when explicitly requested by a
@@ -496,7 +461,8 @@ automatically undo those changes.
 
 A patch plan may contain `create_directory`, `create_file`, `replace_exact`,
 `replace_symbol`, `insert_before`, `insert_after`, `delete_exact`,
-`replace_range`, `delete_range`, `insert_at_line`, or `apply_diff` actions and
+`replace_range`, `delete_range`, `insert_at_line`, `apply_diff`, `ensure_import`,
+`remove_import`, `edit_imports`, `move_file`, `move_range`, or `move_symbol` actions and
 applies the final bytes already computed by the planner.
 
 The optional line-range actions are strict guarded operations for cases where
@@ -515,6 +481,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
@@ -750,18 +723,19 @@ actions:
       symbol: Service.run
 ```
 
-If a change is needed, copy the canonical SHA-256 returned by `read_symbol`
-into a guarded patch action:
+If a change is needed, use the audit-derived draft or copy `ast_sha256` from
+`read_symbol` on the same Python minor version. Add its text `sha256` too when
+comments must be guarded. The action below is illustrative:
 
 ```yaml
 actions:
   - replace_symbol:
       path: src/example/service.py
       symbol: Service.run
-      expected_sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-      new_content: |
-        def run(self, value):
-            return value
+      expected_ast_sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+      new_content: |2
+            def run(self, value):
+                return value
 ```
 
 The same audit can be constructed through the public Python adapter:
@@ -877,7 +851,7 @@ 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.0a5-py3-none-any.whl --version 0.1.0a5
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a7-py3-none-any.whl --version 0.1.0a7
 ```
 
 The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
@@ -995,7 +969,9 @@ The implemented local cycle is:
 5. For a patch, run optional changed-HTML linting, controlled checks, the
    locally resolved isort/Black scopes, and final checks.
 6. Receive a timestamped log or generate a fresh handoff.
-7. Review the log, upload it to the AI, and continue with the next job.
+7. Retrieve configured MCP history or provide the log through an authorized
+   channel. Current MCP history returns summaries/references, not full logs.
+   Review the observed result before continuing with the next job.
 
 See [SPEC_V0_1.md](SPEC_V0_1.md) for the approved product contract and
 [CHANGELOG.md](CHANGELOG.md) for release notes. PatchShuttle is designed for
@@ -1008,3 +984,76 @@ 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.
+
+
+## AI workflow in a7 development
+
+Start with the installed capabilities/schema and the workspace handoff. The
+[AI guide](src/patchshuttle/resources/AI_GUIDE.md) contains the operation decision
+table, guard sources, refactoring checklist and recovery boundaries. Existing
+Python declaration edits should normally use `read_symbol` then `replace_symbol`;
+request `include_template: true` for a guarded draft. Use `edit_imports` for a
+sequence of import edits. Keep audits separate from patches and review actual
+execution outcomes. The explicit `|2` in the method example preserves Python
+indentation after YAML parsing. Documentation examples use illustrative bodies
+and hashes; replace these with observed source and guards before submitting.
+
+This section describes the development branch, not a published a7 release.

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

@@ -863,7 +863,9 @@ Fields:
 
 - `path`: required existing Python text file;
 - `symbol`: required dotted class, function, method, or nested-symbol name;
-- `expected_sha256`: required canonical hash returned by `read_symbol`;
+- `expected_sha256`: optional canonical text hash returned by `read_symbol`;
+- `expected_ast_sha256`: optional structural hash returned by `read_symbol`;
+- at least one hash is required; when both are supplied both must match;
 - `new_content`: required complete replacement source.
 
 Planning parses the current sequential simulated file without importing it,
@@ -874,6 +876,15 @@ desired symbol content returns `NO_CHANGE`. Execution publishes the planner's
 final file bytes through the normal guarded transaction, backup, check,
 workspace-comparison, and rollback lifecycle.
 
+With `expected_ast_sha256`, whitespace and ordinary comment differences do not
+invalidate the guard. Hashes include AST fields but exclude source positions,
+and are scoped to the `ast_python` major/minor version reported by the audit.
+Docstrings, decorators and annotations remain part of the AST. The replacement
+must be one declaration of the same name and kind, the final module must compile
+without execution, and the qualified target must still resolve uniquely.
+Use the text guard as well when comment changes must invalidate the job.
+Old text-guarded jobs retain their normalized serialization and registry hash.
+
 ### 13.5 `insert_before`
 
 Fields:
@@ -2085,3 +2096,76 @@ unless this specification is explicitly revised:
 - logs are plain UTF-8 text with timestamped names and an AI handoff block;
 - implementation begins with tests for the contract before completing the
   execution engine.
+
+
+## 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.
+
+
+## Structural import edits
+
+`read_imports` accepts `path` and optional `max_bytes`. It reports top-level
+imports, `imports_ast_sha256`, and `ast_python`. The hash ignores formatting
+and comments, includes alias names and order, and is Python-minor-specific.
+Nested/conditional imports are not selected. Use the same interpreter for
+inspection and planning.
+
+`ensure_import` and `remove_import` require `path`, `statement` and
+`expected_imports_ast_sha256`. The statement must be exactly one Python
+`import` or `from ... import ...` with one alias, optionally renamed. Relative
+imports are supported. Star requests and ambiguous duplicate matches fail.
+The guard is always checked, including for already-present/absent imports.
+
+```yaml
+- ensure_import:
+    path: services/offers.py
+    statement: from .pricing import calculate_price
+    expected_imports_ast_sha256: "<64 hex digits from read_imports>"
+```
+
+An existing alias in a multi-alias import satisfies `ensure_import` without
+rewriting that line. Removal from a multi-alias import requires a separately
+reviewed rewrite. Removal retains comments, including comments inside a
+parenthesized import. Shared semicolon lines are rejected when editing them.
+Insertion preserves headers, the module docstring and future-import ordering.
+Existing bindings are checked conservatively across scopes; a conflicting
+local name may therefore require a separately reviewed edit too. The resulting
+module is compiled without importing or executing it.
+
+Unrelated source remains intact before the normal scoped formatter phase.
+Neither action rewrites callers, proves runtime compatibility, nor infers
+imports when moving files or symbols. A sequence of import edits needs the
+hash of each simulated intermediate import set, or separate audited jobs.