pdd change: enforce subissue write scope after Step 9 direct edits

[Serhan-Asad]

Evidence

During promptdriven/pdd_cloud#1585 decomposition, child #1600's workflow state expanded beyond the child issue's narrow Cloud Build YAML task into manifest/docs/test files. Some follow-on files may be valid, but the run shows pdd change relies on prompt instructions instead of a deterministic write-scope guard.

Step 9 already says direct edits are limited, but there is no hard post-step revert/check equivalent to the agentic_update out-of-scope guard.

Current bad behavior

A decomposed child can drift outside its intended write contract. In a parallel parent run, this increases conflict risk and can make sibling subissues overlap.

Owning paths:

• prompts/agentic_change_step9_implement_LLM.prompt
• pdd/agentic_change_orchestrator.py

Fix

Add an orchestrator-enforced allowlist after Step 9.

Suggested behavior:

• Build allowed files from Step 6 dev units, confirmed Direct Edit Candidates, prompt/doc associated-document contract, and required PDD metadata.
• Revert or fail on changed files outside that allowlist before Step 10/13.
• Surface a clear workflow failure when the agent attempted out-of-scope edits.

Related run

• Parent: promptdriven/pdd_cloud#1585
• Child showing drift: promptdriven/pdd_cloud#1600

[Serhan-Asad]

Step 1/8: Project Discovery

Tech Stack

• Languages: Python 3.12+ (primary), TypeScript (PDD Connect frontend), Shell
• Frameworks: Click (CLI), Pydantic v2, FastAPI/Uvicorn (server), Textual (TUI), pytest (testing)
• Package Managers: pip / setuptools (build-backend: setuptools.build_meta), setuptools-scm for versioning
• Build Tools: Makefile, pyproject.toml, pytest.ini
• Key Deps: litellm (LLM abstraction), GitPython, firebase_admin, click 8.1.7, pydantic 2.11.4, rich, lxml, jsonschema, z3-solver

Project Structure

• pdd/ — main package (CLI entry pdd.cli:cli); orchestrators for agentic workflows (agentic_change_orchestrator.py, agentic_bug_orchestrator.py, agentic_test_orchestrator.py, agentic_e2e_fix_orchestrator.py, agentic_checkup_orchestrator.py, agentic_split_orchestrator.py), shared utilities (agentic_common.py, agentic_common_worktree.py, git_porcelain.py), sync engine (agentic_sync_runner.py, sync_orchestration.py), CLI sub-packages (pdd/commands/, pdd/core/, pdd/server/, pdd/frontend/)
• prompts/ — LLM prompt templates, including the in-scope agentic_change_step9_implement_LLM.prompt and sibling step prompts (agentic_change_step10_architecture_update_LLM.prompt, etc.)
• tests/ — pytest test suite (strict markers: real/integration/slow/e2e); contains test_agentic_change_* modules
• architecture.json — module manifest with PDD metadata (interface, dependencies, reasons)
• .pddrc — context map (pdd_cli, commands, core, server, routes, pdd_frontend contexts)
• Makefile, .github/, ci/ — build / CI scripts

Checkup Scope

Focused review on issue #1123: pdd change post-Step 9 write-scope enforcement. The scope is the pdd change agentic workflow, specifically:

• pdd/agentic_change_orchestrator.py — the 13-step orchestrator (Steps 5/6/8/8.5/9/10/10.5/13), responsible for any new orchestrator-enforced allowlist guard
• prompts/agentic_change_step9_implement_LLM.prompt — instructions that currently only soft-limit direct edits
• Supporting modules referenced by the allowlist contract: pdd/sync_order.py (discover_associated_documents), pdd/agentic_common_worktree.py (scope guards / revert helpers like revert_out_of_scope_changes_with_dirs), pdd/architecture_sync.py (PDD metadata writes), pdd/git_porcelain.py (lossless changed-file detection)
• Recent commits on this branch (7621b50c0, fd1baa528, 1de386c89, df2d11a4a, 18937524e) already attempt round 1-4 enforcement — checkup will verify the snapshot-based scope guard, deletion detection, content-revert handling, and preflight-flag clearing actually meet the allowlist contract described in the issue (Step 6 dev units + Direct Edit Candidates + associated docs + required PDD metadata)
• Tests under tests/ covering the change orchestrator and Step 9 scope behavior

The audit will compare the implemented guard against the agentic_update out-of-scope guard pattern referenced in the issue, and verify behavior on revert/fail paths before Step 10/13.

---

Proceeding to Step 2: Dependency Audit

[Serhan-Asad]

Step 1/8: Discovering project structure and tech stack

Step 1 completed; no <step_report> block returned by agent. Raw output retained in workflow state.

[Serhan-Asad]

Step 2/8: Dependency Audit

Scope: files owning the Step 9 write-scope guard work (pdd/agentic_change_orchestrator.py, prompts/agentic_change_step9_implement_LLM.prompt) and their close collaborators (pdd/agentic_common.py, pdd/agentic_common_worktree.py, pdd/sync_order.py, pdd/architecture_sync.py, pdd/git_porcelain.py, pdd/construct_paths.py, pdd/preprocess.py, pdd/load_prompt_template.py, pdd/architecture_registry.py, pdd/get_extension.py).

Manifests inspected: pyproject.toml, requirements.txt.

Missing Dependencies

None. All third-party imports in the in-scope files (rich, lxml) are declared in pyproject.toml (rich==14.0.0, lxml>=5.0.0) and requirements.txt.

Broken Local References

None. Every from pdd.<module> import in the in-scope files resolves to an existing file under pdd/ (verified: agentic_common, load_prompt_template, sync_order, construct_paths, get_extension, preprocess, architecture_registry, architecture_sync, agentic_common_worktree, git_porcelain, architecture_sync_helper).

Unused Dependencies

None observed within this audit's scope. A repo-wide unused-deps sweep is out of scope for this issue and would be noise here.

Version Notes

• Pins are tight but internally consistent (pydantic==2.11.4, click==8.1.7, litellm[caching]>=1.80.0,<=1.82.6). No conflicts between pyproject.toml and requirements.txt for the modules touched by this issue.
• requirements.txt upper-bounds litellm less tightly than pyproject.toml (>=1.80.0 vs >=1.80.0,<=1.82.6). Not blocking for this issue; flagged for awareness.

Issues Found

• None blocking. The Step 9 scope-guard fix can proceed without adding or removing dependencies.

---

Proceeding to Step 3: Build Check

[Serhan-Asad]

Step 2/8: Auditing dependencies

Step 2 completed; no <step_report> block returned by agent. Raw output retained in workflow state.

[Serhan-Asad]

Step 3/8: Build Check (Iteration 1)

Build Commands Run

• python -m py_compile pdd/agentic_change_orchestrator.py — OK
• python -c "import pdd.agentic_change_orchestrator" — OK
• python -c "from pdd import agentic_change_orchestrator, sync_order, architecture_sync, git_porcelain, agentic_common_worktree, preprocess" — OK (all scope modules import)
• python -m compileall -q pdd/ — OK (entire package compiles clean)
• python -m compileall -q tests/ — OK (1 SyntaxWarning, low severity, out of scope)

Build Errors

Severity	File	Error
low	tests/test_e2e_issue_737_step_completion_markers.py	SyntaxWarning: invalid escape sequence '\s' in module docstring — does not prevent execution, unrelated to #1123 scope

Summary

0 errors found (0 critical, 0 medium, 1 low warning). All scope-relevant modules (agentic_change_orchestrator.py, sync_order.py, architecture_sync.py, git_porcelain.py, agentic_common_worktree.py, preprocess.py) compile and import cleanly. The round 1–4 fix commits on this branch did not introduce syntax/import regressions.

---

Proceeding to Step 4: Interface Check

[Serhan-Asad]

Step 3/8: Running build/compile checks

Step 3 completed; no <step_report> block returned by agent. Raw output retained in workflow state.

[Serhan-Asad]

Step 4/8: Interface Check (Iteration 1)

Verified all in-scope interfaces by importing each module from this worktree (PYTHONPATH pinned to the checkup worktree to avoid masking by another editable install) and inspecting signatures with inspect.signature. Targeted unit tests for the new helpers also pass.

Module Interface Issues

Module	Issue Type	Description
—	—	None found in PR #1123 scope.

All new orchestrator-side imports resolve to real callables with compatible signatures:

• pdd.agentic_change_orchestrator → newly imports extract_step_report, normalize_step_comments_state, post_step_comment_once from pdd.agentic_common — all present and exported.
• New private helpers exist with the signatures the call sites use: _snapshot_worktree_status(Path) -> Dict[str, Tuple[str, Optional[str]]], _build_step9_allowlist(Path, str, str, Sequence[str]) -> Tuple[Set[Path], Set[str]], _enforce_step9_scope(Path, Dict, Dict, pre_status=..., quiet=...) -> List[str], _parse_direct_edit_candidates, _parse_step6_devunit_prompts, _parse_step6_dependency_prompts, _parse_step6_integration_prompts, _parse_step6_frontend_prompts, _parse_step5_doc_paths, _extract_section, _parse_md_table_column.
• Helpers from pdd.agentic_common_worktree consumed by the scope guard exist with matching signatures:
  • revert_out_of_scope_changes_with_dirs(cwd, allowed_dirs: set[str], allowed_files: set[Path], pre_snapshot=None, strict=False) -> List[Path] ← scope guard passes strict=True and pre_snapshot=<snapshot dict>, both supported.
  • _hash_file_content(path: Path) -> Optional[str] ← used by _snapshot_worktree_status.
• pdd.git_porcelain.parse_porcelain_z(stdout: Union[bytes, str]) -> List[PorcelainEntry] ← scope guard and _detect_worktree_changes pass result.stdout (bytes, since text= is not set), which the signature accepts. PorcelainEntry exposes .status and .path as used.
• pdd.sync_order.discover_associated_documents(Set[Path], Path, Optional[Path], int) ← Step 10.5 contract verifier signature matches the orchestrator call site.

Cross-Module Compatibility

No issues. Smoke-checked happy-path invariants:

• _build_step9_allowlist(<missing path>, '', '', []) → (set(), set()) (no crash on empty inputs).
• _snapshot_worktree_status(<missing path>) → {}.
• _enforce_step9_scope(<missing path>, {}, {}, pre_status=None) → [] (no-op when worktree absent / not a git tree — matches docstring contract).
• Italic-preamble Step 6 tolerance: _parse_direct_edit_candidates correctly returns ['pdd/foo.py', 'scripts/bar.sh'] when the heading is followed by a *Files that need scoped...* line plus a blank line (round-2 regression fix verified).
• revert_out_of_scope_changes_with_dirs accepts both the strict-mode and pre-snapshot kwargs the orchestrator now relies on for fail-closed enforcement.

Targeted test runs in the worktree:

• tests/test_agentic_change_orchestrator.py -k "scope or allowlist or direct_edit or snapshot or step9" → 56 passed.
• tests/test_git_porcelain.py + tests/test_issue_1080_porcelain_scope_guards.py → 15 passed.
• tests/test_agentic_common_worktree.py → 79 passed.

Frontend Navigation Reachability

N/A — PR #1123 scope is the Python CLI orchestrator (pdd change). No frontend pages/routes are touched. (pdd/frontend/constants.ts exists in the repo but is unrelated to this change.)

Frontend→Backend API Consistency

N/A — no frontend→backend call sites are added or modified by this PR.

Summary

0 interface issues found within the PR #1123 scope (Step 9 write-scope guard in pdd/agentic_change_orchestrator.py and its supporting helpers in agentic_common_worktree, git_porcelain, sync_order, architecture_sync). All new imports, helper signatures, and call sites are consistent.

---

Proceeding to Step 5: Test Execution

[Serhan-Asad]

Step 4/8: Checking cross-module interfaces

Step 4 completed; no <step_report> block returned by agent. Raw output retained in workflow state.

[Serhan-Asad]

Step 6a/8: Fix Issues (Iteration 1)

No fixes required this iteration — Steps 2-4 all reported clean within the PR scope (post-Step 9 write-scope guard in pdd/agentic_change_orchestrator.py and supporting modules):

• Step 2 (deps): no missing/broken/unused deps in scope; only an awareness-level cross-manifest version-bound difference on litellm.
• Step 3 (build): all scope modules and the full pdd/ package compile and import; only a low-severity SyntaxWarning in an out-of-scope test file.
• Step 4 (interfaces): all new imports resolve, all new scope-guard helpers exist with the signatures their call sites use; 56 scope/allowlist/direct-edit/snapshot/step9 tests + 15 porcelain scope-guard tests + 79 common-worktree tests all pass.
• Step 5 (tests): reported anthropic: Timeout expired — provider/transport failure, not a code or test defect. No remediation possible at the code layer.

Fixes Applied

Issue	File	Fix Description
—	—	No actionable defects surfaced in Steps 2-4; Step 5 failure was a provider timeout, not a test failure.

Files Changed

• (none)

Artifacts

• .agentic_prompt_b0318000.txt left in place (active workflow instruction file for the current run).
• new_file.txt (untracked, 0 bytes) left in place — not a recognized PDD artifact pattern (.agentic_prompt_*.txt, tmp*.py, crash logs).

---

Proceeding to Step 6b: Regression Tests

[Serhan-Asad]

Step 6.1/8: Fixing discovered issues

Step 6.1 completed; no <step_report> block returned by agent. Raw output retained in workflow state.

[Serhan-Asad]

Step 6b/8: Regression Tests (Iteration 1)

Regression Tests Written

Test	File	What It Verifies
(none)	—	Step 6a applied no fixes (Steps 2-4 clean; Step 5 was a provider timeout, not a code defect), so there are no fixes requiring a regression test in this iteration.

Existing scope-guard coverage from this branch's round 1-4 fix commits remains in place and passing (per Step 4): 56 scope/allowlist/direct-edit/snapshot/step9 tests, 15 porcelain scope-guard tests, and 79 common-worktree tests.

---

Proceeding to Step 6c: E2E Tests