feat: enforce split-contract allowed write sets in pdd sync (#1013)

CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+### Fix
+
+- **#1013 sync**: enforce split-contract allowed write sets. When the linked GitHub issue declares an allowed write set (HTML comment `<!-- PDD_ISSUE_CONTRACT ...json... -->`, a fenced "Allowed Write Set" / "Split Contract" block, or a `## Split Contract` heading with an `**Allowed write set:**` label followed by a bullet list), `pdd sync` now reverts tracked changes and removes untracked new files that fall outside the contract after each per-module subprocess, hard-fails the module on out-of-scope artifacts, and surfaces the contract source plus offending paths in checkup/review-loop reports. Companion artifacts under `.pdd/meta/*.json` are auto-allowed; additional companions can be opted in via the contract's `companion_allowlist` field. Use `--no-scope-guard` to opt out for a single run. Issues without a contract marker remain in permissive mode (no enforcement).
+
 ## v0.0.238 (2026-05-14)
 
 ### Feat

README.md

@@ -872,6 +872,7 @@ Options:
 - `--durable-branch TEXT`: Durable mode only. Override the durable checkpoint branch name. Default is `sync/issue-<N>` derived from the GitHub issue. Refused if it resolves to `main`, `master`, or the repository default branch.
 - `--no-resume`: Durable mode only. Ignore existing `PDD-Sync-Checkpoint-V1` commit trailers on the durable branch and re-run every selected module. By default, durable sync reads checkpoint trailers (`PDD-Sync-Checkpoint-V1: issue=<N> module=<basename>`) and skips modules already checkpointed for the same issue, which is what makes a cloud rerun safely resume completed work after a partial failure.
 - `--durable-max-parallel INT`: Durable mode only. Cap how many module worktrees run concurrently. Defaults to the standard runner concurrency. A total budget still forces sequential execution.
+- `--no-scope-guard`: Issue-sync only. Disable the split-contract scope guard for this run. By default, when the linked GitHub issue declares an allowed write set (split contract), `pdd sync` enforces it and rejects out-of-scope generated artifacts. Pass this flag only when intentionally overriding contract enforcement (e.g. recovering from a stale contract). See "Split-Contract Scope Guard" below.
 
 **Durable Issue Sync** (`--durable`):
 
@@ -1060,6 +1061,61 @@ Options (agentic mode):
 
 **Cross-Machine Resume**: Workflow state is stored in a hidden GitHub comment, enabling resume from any machine. Use `--no-github-state` to disable.
 
+**Split-Contract Scope Guard** (Issue #1013):
+
+When the linked GitHub issue declares an allowed write set (a "split contract"), `pdd sync` enforces it: each per-module subprocess is followed by a scope check that reverts tracked changes and removes untracked new files that fall outside the contract. Companion artifacts under `.pdd/meta/*.json` are auto-allowed because they are sync's own fingerprint bookkeeping; issues may opt additional companions (e.g. examples or architecture entries) into the allowlist explicitly.
+
+The contract is read from the issue body or any of its comments in one of three forms (tried in priority order — the first match wins):
+
+1. An HTML-comment block (preferred — invisible in rendered Markdown):
+   ```html
+   <!-- PDD_ISSUE_CONTRACT
+   {
+     "allowed_paths": [
+       "pdd/update_main.py",
+       "pdd/prompts/update_main_python.prompt",
+       "tests/test_update_main.py"
+     ],
+     "companion_allowlist": [".pdd/meta/*.json"]
+   }
+   -->
+   ```
+2. A fenced code block under a heading like `### Allowed Write Set` or `### Split Contract`:
+   ```text
+   pdd/update_main.py
+   pdd/prompts/update_main_python.prompt
+   tests/test_update_main.py
+   ```
+3. A bullet list under an inline `**Allowed write set:**` label (the
+   real-world shape used by sub-issues such as #1005):
+
+   ```markdown
+   ## Split Contract
+   **Command sequence:** change → sync
+   **Allowed write set:**
+   - `pdd/update_main.py`
+   - `pdd/prompts/update_main_python.prompt`
+   - `tests/test_update_main.py`
+   **Acceptance criteria:**
+   - ...
+   ```
+
+   The heading regex is the same as form 2; the inline `**Allowed write set:**` label discriminates the bullet list so unrelated bullets earlier in the body (e.g. a `## Files` section) are NOT captured. Each bullet is one repo-relative POSIX path with optional surrounding backticks. The list terminates at the next `**Label:**` (such as `**Acceptance criteria:**`), a `---` rule, another heading, a non-blank non-bullet line, or end of body.
+
+When an out-of-scope change is detected, the run records a hard failure for that module with a diagnostic of the form:
+
+```
+Scope guard reverted N out-of-scope file(s) for module '<basename>' (contract source: <source>):
+  - path/relative/to/repo
+  - another/path
+Allowed write set:
+  - path/from/contract
+Companion allowlist:
+  - .pdd/meta/*.json
+```
+
+This blocks the per-module success record so dependent modules do not schedule on top of an out-of-scope sync, and checkup/review-loop reports surface the failure instead of letting unrelated artifacts land in the PR. When no contract marker is present, the scope guard falls back to permissive mode — no enforcement, no reverts — preserving existing behavior for issues that have not opted in. Use `--no-scope-guard` to disable enforcement for a single run when you intentionally need to override the contract.
+
 ### 1a. sync-architecture
 
 Sync `architecture.json` from prompt metadata tags (`<pdd-reason>`, `<pdd-interface>`, and `<pdd-dependency>`). This is useful after editing prompt metadata directly, or after backfilling prompt tags, so the architecture graph and command metadata stay aligned with the prompts.

architecture.json

@@ -128,6 +128,16 @@
             "name": "clear_workflow_state",
             "signature": "(cwd: Path, issue_number: int, workflow_type: str, state_dir: Path, repo_owner: str, repo_name: str, use_github_state: bool = True) -> None",
             "returns": "None"
+          },
+          {
+            "name": "parse_issue_contract",
+            "signature": "(issue_body: Optional[str], issue_comments: Optional[List[str]] = None) -> Optional[IssueContract]",
+            "returns": "Optional[IssueContract]"
+          },
+          {
+            "name": "_revert_out_of_scope_changes",
+            "signature": "(cwd: Path, allowed_paths: set[Path]) -> List[Path]",
+            "returns": "List[Path]"
           }
         ]
       }
@@ -7264,15 +7274,15 @@
         "functions": [
           {
             "name": "run_agentic_sync",
-            "signature": "(issue_url: str, *, verbose: bool, quiet: bool, budget: Optional[float], skip_verify: bool, skip_tests: bool, dry_run: bool, agentic_mode: bool, no_steer: bool, max_attempts: Optional[int], timeout_adder: float, use_github_state: bool, one_session: bool, reasoning_time: Optional[float], durable: bool, durable_branch: Optional[str], no_resume: bool, durable_max_parallel: Optional[int]) -> Tuple[bool, str, float, str]",
+            "signature": "(issue_url: str, *, verbose: bool, quiet: bool, budget: Optional[float], skip_verify: bool, skip_tests: bool, dry_run: bool, agentic_mode: bool, no_steer: bool, max_attempts: Optional[int], timeout_adder: float, use_github_state: bool, one_session: bool, reasoning_time: Optional[float], durable: bool, durable_branch: Optional[str], no_resume: bool, durable_max_parallel: Optional[int], scope_guard: bool = True) -> Tuple[bool, str, float, str]",
             "returns": "Tuple[bool, str, float, str]",
             "sideEffects": [
               "None"
             ]
           },
           {
             "name": "run_global_sync",
-            "signature": "(*, verbose: bool, quiet: bool, budget: Optional[float], skip_verify: bool, skip_tests: bool, agentic_mode: bool, no_steer: bool, max_attempts: Optional[int], dry_run: bool, target_coverage: Optional[float], one_session: bool, local: bool, timeout_adder: float) -> Tuple[bool, str, float, str]",
+            "signature": "(*, verbose: bool, quiet: bool, budget: Optional[float], skip_verify: bool, skip_tests: bool, agentic_mode: bool, no_steer: bool, max_attempts: Optional[int], dry_run: bool, target_coverage: Optional[float], one_session: bool, local: bool, timeout_adder: float, scope_guard: bool = True) -> Tuple[bool, str, float, str]",
             "returns": "Tuple[bool, str, float, str]",
             "sideEffects": [
               "Runs AsyncSyncRunner for stale modules unless dry_run=True; timeout_adder is forwarded via sync_options so --timeout-adder stretches the per-module wall-clock cap on the global-sync path the same way it does on run_agentic_sync"
@@ -7324,7 +7334,7 @@
         "functions": [
           {
             "name": "AsyncSyncRunner",
-            "signature": "(basenames: List[str], dep_graph: Dict[str, List[str]], sync_options: Dict[str, Any], github_info: Optional[Dict[str, Any]], quiet: bool = False, verbose: bool = False, issue_url: Optional[str] = None, module_cwds: Optional[Dict[str, Path]] = None, initial_cost: float = 0.0)",
+            "signature": "(basenames: List[str], dep_graph: Dict[str, List[str]], sync_options: Dict[str, Any], github_info: Optional[Dict[str, Any]], quiet: bool = False, verbose: bool = False, issue_url: Optional[str] = None, module_cwds: Optional[Dict[str, Path]] = None, initial_cost: float = 0.0, *, allowed_write_set: Optional[Iterable[str]] = None, companion_allowlist: Optional[Iterable[str]] = None, scope_guard_enabled: bool = True)",
             "returns": "AsyncSyncRunner",
             "sideEffects": [
               "Initializes runner state; total_budget in sync_options forces sequential scheduling and per-child/per-retry remaining-budget caps"