bug: agentic update scope guard reverts included-doc edits

[Serhan-Asad]

Problem

prompts/agentic_update_LLM.prompt explicitly allows the update agent to modify:

• the prompt file
• documents referenced by <include> tags
• new shared include files in context/

But run_agentic_update() only allows the prompt, code file, and selected tests through _revert_out_of_scope_changes(). Any included doc or new context include that the agent edits or creates is out of scope and can be reverted.

This leaves pdd update --all unable to satisfy the documented "included docs are part of the prompt" requirement tracked by #860 and the closed #732.

Evidence

• prompts/agentic_update_LLM.prompt allows included-doc and new shared include edits.
• pdd/agentic_update.py builds _allowed = {prompt_path.resolve(), code_path.resolve()} plus selected tests, then calls _revert_out_of_scope_changes(PROJECT_ROOT, _allowed).
• The allowed set does not include resolved prompt include files or new shared include files.

Expected

run_agentic_update() should derive an allowlist from resolved prompt includes and preserve permitted included-doc edits and intentional new shared context include files, while still reverting unrelated mutations.

Acceptance criteria

• Add a regression test where a prompt includes a source doc and pdd update preserves an edit to that doc.
• Add a regression test where a new shared include file under an allowed context/docs path can be preserved when intentionally created.
• Keep unrelated file mutations reverted.
• Align the implementation allowlist with the permissions described in agentic_update_LLM.prompt.
• Reuse the same include parsing semantics as PDD preprocessing/fingerprinting once those are unified.

Related

• Bug: pdd sync generated-test phase can pollute or break existing test files #860
• feat: add PDD_SKIP_DUPLICATE_CHECK to skip Step 1 duplicate hard stop #732
• Heal Prompt Drift (code + tests) #727

---

Migrated from gltanaka/pdd#1369 (originally filed 2026-05-05 by gltanaka). gltanaka/pdd is deprecated.

[prompt-driven-github]

🚀 Autonomous Solving Started!

Job ID: Jd6cMGM8F3TASwv8hkCV
Triggered by: @Serhan-Asad
Label: issue

View Live Progress

[prompt-driven-github]

📋 Execution Plan

Commands: change → sync
Attempt: 1/3
Issue: #987

[prompt-driven-github]

⚡ Running pdd change

Job ID: pkErowMlm9iTY2nztTVs
View Live Progress

[prompt-driven-github]

Step 3/13: Research to clarify specifications

Status: FAILED

Error Details

All agent providers failed: anthropic: Exit code 1: {"type":"result","subtype":"success","is_error":true,"api_error_status":429,"duration_ms":608,"duration_api_ms":0,"num_turns":1,"result":"You've hit your limit · resets May 15, 11pm (UTC)","stop_reason":"stop_sequence","session_id":"ebee860f-60c0-483a-8528-8c22600928ee","total_cost_usd":0,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creati

---

Automated fallback comment — agent did not execute for this step.

[prompt-driven-github]

Step 1: Duplicate Check

Status: Similar issue exists (related to issue #880)

Search Performed

• Searched for: "agentic update scope guard included-doc", "agentic_update", related PRs
• Issues reviewed: 15+

Findings

A similar issue exists at #880 with the same title ("bug: agentic update scope guard reverts included-doc edits"). It was closed as COMPLETED on 2026-05-13 with related PR #965 ("fix: PDD bug for #880") still OPEN.

Since PR #965 has not yet been merged, the underlying fix is not yet on main. This issue #987 should proceed as a new change request to ensure the implementation lands. The acceptance criteria (allowlist derived from resolved prompt includes, regression tests, alignment with agentic_update_LLM.prompt permissions) remain valid investigation targets.

Related: #860, #732, #727, and the similar issue #880.

---

Proceeding to Step 2: Documentation Check

[prompt-driven-github]

Step 2: Documentation Check

Status: Not Implemented

Documentation Reviewed

• prompts/agentic_update_LLM.prompt — documents allowed scope (prompt file, <include>-referenced docs, new shared context/ includes)
• pdd/agentic_update.py — run_agentic_update() allowlist construction at lines 352-354
• pdd/agentic_common.py — _revert_out_of_scope_changes() helper
• CLAUDE.md and README.md — general project docs

Findings

@Serhan-Asad — Confirmed the bug as described:

• pdd/agentic_update.py:352-354 builds _allowed = {prompt_path.resolve(), code_path.resolve()} plus selected tests, then calls _revert_out_of_scope_changes(PROJECT_ROOT, _allowed).
• The allowlist does not include resolved <include> files referenced by the prompt, nor newly created shared include files under context/.
• The LLM-facing prompt at prompts/agentic_update_LLM.prompt explicitly permits the agent to edit those files, so the runtime guard contradicts the documented permissions.
• A related PR (fix: PDD bug for #880 #965) for the prior issue is still open and not merged to main, so the current main branch still exhibits the gap.

The implementation needs to be aligned with the documented scope: derive the allowlist from resolved prompt includes and intentional new shared includes under permitted paths, while still reverting unrelated mutations.

---

Proceeding to Step 3: Identify Dev Units

[prompt-driven-github]

Step 3: Research & Clarification

Status: Research Complete

Summary

Researched scope-guard / allowlist patterns for autonomous coding agents and surveyed the existing in-repo include-parsing utilities. The fix is well-scoped: reuse pdd/preprocess.py::compute_user_intent_paths to derive the allowlist from the prompt's <include>/<include-many>/backtick-include tags and union that with an opt-in shared-context directory (e.g. context/).

Research Findings

Technical Background

• Scope guard mechanism (in repo): pdd/agentic_common.py:2220 _revert_out_of_scope_changes runs git status --porcelain -uno, then git checkout HEAD -- for any modified path not in allowed_paths. Untracked files are not seen (-uno), so newly created files in any directory survive the guard today — only modifications to tracked files are reverted.
• Allowlist build site (in repo): pdd/agentic_update.py:352-354 constructs _allowed = {prompt_path, code_path} ∪ selected_tests. Resolved include paths are missing.
• Include parsing (already canonical in repo): pdd/preprocess.py:171 compute_user_intent_paths(text) extracts the full grammar — <include>path</include>, <include path=\"...\"/>, <include-many>...</include-many>, and backtick \`````— matching exactly whatprocess_include_tags` accepts. This is the right primitive to reuse (acceptance criterion 5).
• Documented permissions (in repo): prompts/agentic_update_LLM.prompt:55-62 permits edits to (a) the prompt file, (b) docs referenced by <include> tags, (c) new shared include files in context/ (or equivalent). The runtime allowlist must mirror this exactly.

Best Practices (from external research)

• Principle of least privilege / permission manifest: scope an agent's writable set to the smallest declared list. The fix aligns with OWASP-style agentic-skills guidance — the prompt's Scope Boundaries section is the de-facto manifest; the implementation just needs to honor it.
• Static vs. derived allowlists: derive from the artifact (prompt + its includes) rather than maintaining a parallel hard-coded list, so the permission surface tracks the prompt's actual <include> graph and cannot drift.
• Resolve before comparing: always compare Path.resolve() against Path.resolve() to defeat symlink / .. mismatches — same pattern already used at agentic_update.py:352.
• Untracked-file handling: -uno means newly created files are silently allowed. Either keep that behavior (simpler; relies on the prompt's instruction to write only to context/) or tighten to -u and explicitly allowlist a context root. Choosing the simpler option for now (keep -uno, document the behavior).

Similar Implementations

• The same compute_user_intent_paths helper is already used elsewhere in PDD for fingerprinting / preprocessing, satisfying the issue's acceptance criterion 5 ("reuse the same include parsing semantics as PDD preprocessing/fingerprinting").
• Agent-guardrails / Claude Code auto-mode patterns confirm the derive-from-artifact approach over hardcoded lists.

Security / Edge Cases

1. Relative vs. absolute include paths: compute_user_intent_paths returns raw strings; they must be resolved against the prompt's parent directory (or PROJECT_ROOT) and .resolve()-d before insertion into the allowlist.
2. ${VAR} placeholders in include paths: the helper's docstring notes that callers should union results from the original text and from _expand_vars(...) output. We should do the same so env-var-driven include paths aren't false-reverted.
3. Nonexistent include targets: a <include> may reference a file the agent is expected to create. Resolve the path string but do not require existence — add to allowlist unconditionally so post-creation it isn't reverted.
4. Transitive includes: when an included doc itself has <include> tags, decide whether to follow recursively. Simplest choice: shallow (one level) — matches the prompt's stated scope ("documents referenced by <include> tags") and avoids surprise allowlist explosion.
5. context/ directory existence: project may use a different shared-include directory. Make the context root configurable / opt-in: if a context/ (or .pddrc-declared equivalent) directory exists at PROJECT_ROOT, allow all paths under it; otherwise skip.
6. Path traversal safety: confine all resolved paths to PROJECT_ROOT — drop any allowlist entry whose resolved path escapes the repo root (defense in depth against include-tag-driven traversal).
7. Test files: keep the existing selected_tests allowance untouched (orthogonal concern).

Refined Specifications

1. Add a helper _resolve_prompt_includes(prompt_path: Path, project_root: Path) -> set[Path] in pdd/agentic_update.py that:
   • reads the prompt text,
   • calls compute_user_intent_paths(text) (and compute_user_intent_paths(_expand_vars(text, env))) and unions the results,
   • resolves each path relative to the prompt's parent (falling back to PROJECT_ROOT),
   • filters out any resolved path that escapes PROJECT_ROOT,
   • returns a set of resolved Path objects (existence not required).
2. Add a helper _shared_context_roots(project_root: Path) -> list[Path] returning configured shared-include dirs (default: [project_root / 'context'] when present).
3. Extend _revert_out_of_scope_changes (or build the allowlist before calling it) so paths under any shared-context root are allowed — implement as a directory-prefix check rather than enumerating files, so newly created files are also covered.
4. Update pdd/agentic_update.py:352 to union {prompt_path, code_path} with resolved-include set and tests; pass shared-context roots to the guard.
5. Add regression tests under tests/:
   • test_agentic_update_preserves_included_doc_edits — prompt with <include>docs/spec.md</include>, agent edits docs/spec.md, guard preserves the edit.
   • test_agentic_update_preserves_new_shared_context_include — agent creates context/shared.md, guard preserves it.
   • test_agentic_update_reverts_unrelated_mutation — guard still reverts an edit to pdd/unrelated.py.
6. Keep changes orthogonal to PR fix: PDD bug for #880 #965 (which is still open against bug: agentic update scope guard reverts included-doc edits #880) — implementation should be additive and merge-compatible.

Alternative Approaches Considered

• Hardcode context/ and a fixed list of doc extensions: simpler, but drifts from the prompt's actual <include> graph and fails when a project uses a different shared-include directory. Rejected.
• Switch scope guard to -u (include untracked) and explicitly track every created file: tighter, but requires building a full pre-snapshot of the file tree. Out of scope; keep -uno semantics.
• Recursively resolve transitive includes: more permissive, but enlarges blast radius and is not what agentic_update_LLM.prompt documents. Choose shallow resolution.
• Move the allowlist derivation into _revert_out_of_scope_changes: would couple the guard to PDD-specific include semantics. Better to keep the guard generic and pass in an already-built allowed_paths set + optional allowed_roots (directory-prefix list).

Recommended Approach

Derive the allowlist in run_agentic_update() by:

1. Calling compute_user_intent_paths against the (raw + env-expanded) prompt to get include path strings.
2. Resolving each against the prompt's parent directory, dropping any that escape PROJECT_ROOT.
3. Adding any existing context/-equivalent directory as a directory-prefix allowlist.
4. Passing both the file set and the directory-prefix set to a slightly extended _revert_out_of_scope_changes.

This satisfies all five acceptance criteria, reuses existing include-parsing semantics (criterion 5), and remains compatible with the still-open PR #965.

Sources:

• AI Agent Security Starts with Scope Control — CSA (2026-05-12)
• agent-guardrails: Merge gates and safety checks for AI coding agents
• Claude Code auto mode: a safer way to skip permissions
• AI Agent Governance: Skill Permissions & Allowlist Tools
• OWASP — Path Traversal
• MCP filesystem server path traversal issue

---

Proceeding to Step 4: Documentation Changes

[prompt-driven-github]

Step 4: Requirements Clarity Check

Status: Requirements Clear

Clarity Assessment

Aspect	Status
Problem statement	✅ Clear
Expected outcomes	✅ Defined
Scope	✅ Bounded
Edge cases	✅ Addressable

Understanding Summary

Expand the allowlist built in pdd/agentic_update.py so _revert_out_of_scope_changes() preserves edits to files referenced by <include> tags in the prompt, plus intentional new shared include files under an opt-in context/ directory. Reuse pdd/preprocess.py::compute_user_intent_paths for include resolution, keep all unrelated mutations reverted, and add three regression tests matching the acceptance criteria.

Assumptions Made

• Include paths resolve relative to the prompt file's parent directory, with ${VAR} expansion taking the union of all possible expansions (mirroring existing preprocessing semantics).
• Allowed new-file directory is context/ at the project root (as documented in agentic_update_LLM.prompt); only newly created files within that directory prefix are preserved, all other untracked files remain reverted.
• All allowed paths must resolve inside PROJECT_ROOT (path-traversal containment).
• Include resolution is shallow (non-recursive) for the allowlist — sufficient for the documented permission scope.
• Implementation stays additive so it remains merge-compatible with the still-open related PR.

---

Proceeding to Step 5: Documentation Changes

[prompt-driven-github]

Step 5: Documentation Changes

Status: No Documentation Changes Needed

Summary

This is an internal bug fix to pdd/agentic_update.py that aligns runtime allowlist semantics with the already-documented contract in prompts/agentic_update_LLM.prompt. No public CLI surface, flag, or workflow changes — therefore no user-facing documentation requires edits. The new regression tests are internal artifacts.

Files to Update

None.

Files to Create

None.

Associated Documents

(Documents reachable from the modified prompts' <include> graph, depth ≤ 3.)

Include-graph traversal from the prompt(s) Step 9 is expected to touch:

• prompts/agentic_update_LLM.prompt (depth 0; not edited — already documents the intended scope; the bug is runtime divergence from this prompt)
  • <include>docs/prompting_guide.md</include> (depth 1)
    • Scanned for references to agentic_update, scope-guard, allowlist, _revert_out_of_scope_changes, run_agentic_update, included-doc edits — no matches. The two allowlist hits at lines 1439 and 1452 are unrelated OAuth-redirect examples.
    • No edit required.

No other prompts are in the Step 5 starting set for this change. Step 9 will reconcile against Step 6's authoritative dev-unit list.

Result: No documents reachable via <include> from the modified prompts require section-scoped edits for this change.

Conflicts

None.

No Changes Needed

• README.md — pdd update section (lines ~2361–2447) describes user-facing behavior unchanged by this fix; the allowlist semantics are internal to the agentic runtime.
• docs/prompting_guide.md — does not document the agentic_update scope guard; no stale section.
• prompts/agentic_update_LLM.prompt — already correctly describes the intended scope; this is the source of truth the runtime is being aligned to (no edit needed here either, though Step 6 may surface it as a dev unit whose code-side test fixtures are updated).
• docs/ci.md, docs/TUTORIALS.md, docs/ONBOARDING.md, docs/faq.md — reviewed via path/title; none reference the scope guard or included-doc preservation.

---

Proceeding to Step 6: Identify Dev Units

[prompt-driven-github]

Step 6: Dev Units Identified

Status: Found 1 dev unit (primary) + 1 dependency

Change Summary

Align the run_agentic_update() scope-guard allowlist in pdd/agentic_update.py with the broader permissions documented in prompts/agentic_update_LLM.prompt by including <include>-referenced files and new shared context/ includes, reusing the canonical include-parsing semantics from pdd/preprocess.py::compute_user_intent_paths.

Project Structure (from .pddrc)

• Source directory: pdd/
• Test directory: tests/
• Example directory: examples/
• Language: python

Dev Units to MODIFY

Prompt	Code	Example	Test
prompts/agentic_update_python.prompt	pdd/agentic_update.py	(none — no example file exists; not required)	tests/test_agentic_update.py

The runtime allowlist construction lives in pdd/agentic_update.py (run_agentic_update, around lines 352-354). The corresponding module prompt is prompts/agentic_update_python.prompt. The LLM-task prompt prompts/agentic_update_LLM.prompt is the agent-facing contract that already documents the permitted scope (no change needed — the implementation must be brought up to it). Regression tests will be added/extended in tests/test_agentic_update.py.

Dev Units to CREATE

None.

All required behavior can be added by modifying the existing agentic_update dev unit. The include-parsing logic already exists in pdd/preprocess.py::compute_user_intent_paths and will be reused (acceptance criterion 5), so no new module is justified.

Reuse Analysis

• Existing modules considered for reuse:
  • pdd/preprocess.py::compute_user_intent_paths — already parses <include> directives, expands ${VAR} unions, resolves paths relative to the prompt's parent directory, and is used by PDD fingerprinting. This is exactly the parser the issue's acceptance criterion 5 asks us to share.
  • pdd/agentic_common.py::_revert_out_of_scope_changes — the guard itself. It accepts an allowlist; the simplest fix is to widen the allowlist passed in by run_agentic_update, no change to the guard's signature required.
• Conclusion: Extension of pdd/agentic_update.py is sufficient. No new module needed.

Dependencies (may need interface updates)

• prompts/preprocess_python.prompt / pdd/preprocess.py — read-only reuse of compute_user_intent_paths. No interface change planned. Per the dependency graph, preprocess has many downstream consumers (code_generator, context_generator, insert_includes, etc.), so the interface must remain stable — reusing without modifying it satisfies this.
• pdd/agentic_common.py — _revert_out_of_scope_changes is invoked by agentic_update. Per the dependency graph, agentic_common affects many orchestrators. We will NOT change its public signature; the fix is confined to the caller's allowlist.

Integration Points Discovered

No new module is being created, so no aggregator/registry registration is required. pdd/agentic_update.py is already wired into the CLI through pdd/update_main.py and pdd/cli.py; no integration-point edits needed.

Search performed:

• `grep -rn "run_agentic_update\|agentic_update" pdd/ --include='*.py'`
• `grep -rn "_revert_out_of_scope_changes" pdd/ --include='*.py'`
• `grep -rn "compute_user_intent_paths" pdd/ --include='*.py'`

Frontend Dev Units (Cross-Layer)

Not applicable — this is a CLI/backend-only change. There is no frontend surface that references this scope-guard logic.

Backend endpoints being created/modified: (none — internal Python function only)

Direct Edit Candidates (No Prompt)

None. All affected files are PDD-managed dev units with corresponding prompts.

Files Explored

• `.pddrc` — confirmed source=`pdd/`, tests=`tests/`, examples=`examples/`, lang=python
• `prompts/agentic_update_LLM.prompt` — documents the permitted-edit contract
• `prompts/agentic_update_python.prompt` — module prompt for the implementation
• `pdd/agentic_update.py` — allowlist construction site (lines 352-354 per Step 3)
• `pdd/agentic_common.py` — `_revert_out_of_scope_changes` guard
• `pdd/preprocess.py` — canonical include-parser (`compute_user_intent_paths`)
• `tests/test_agentic_update.py` — where the three new regression tests will be added
• `examples/` — confirmed no existing example for agentic_update; not required

---

Proceeding to Step 7: Architecture Review

[prompt-driven-github]

Step 7: Architecture Review

Status: Architecture Clear

Reuse Validation

• Step 6 proposes only MODIFY operations (no new modules) — confirmed minimal and correct
• Include-parsing logic is reused from pdd/preprocess.py::compute_user_intent_paths (not reimplemented), satisfying acceptance criterion 5
• Scope-revert guard pdd/agentic_common.py::_revert_out_of_scope_changes is reused as-is — only its allowed_paths argument is widened
• No new abstractions, helpers, or modules required

Analysis

The implementation approach is straightforward — this is a localized allowlist-widening fix in pdd/agentic_update.py with no cross-cutting design decisions:

1. Existing infrastructure covers the fix. compute_user_intent_paths already resolves <include> directives with ${VAR} expansion and relative-path semantics. _revert_out_of_scope_changes already supports an arbitrary allowlist set.
2. No API surface changes. No function signatures change in pdd/preprocess.py or pdd/agentic_common.py, protecting all downstream consumers.
3. Standard patterns apply. Path containment via Path.resolve() + PROJECT_ROOT check is the obvious approach for the new-context/-file allowance.

Implementation Approach

• In pdd/agentic_update.py at the allowlist-construction site (lines ~352-354):
  • Call compute_user_intent_paths(prompt_path) to get resolved <include> targets
  • Add each resolved include path (filtered to PROJECT_ROOT containment) to _allowed
  • Additionally permit untracked files created under context/ (directory-prefix allowlist) since the prompt's contract explicitly allows new shared includes there
• Implementation is additive — does not alter behavior for prompts without includes, preserving merge-compatibility with open PR fix: PDD bug for #880 #965

Architectural Decisions (made autonomously, simplest option)

• Include resolution depth: shallow (depth-1 only) — matches what compute_user_intent_paths returns; avoids over-broad allowlists from transitive includes
• context/ allowance: directory-prefix match (any file under context/ is permitted), not a precise file list — simplest interpretation of the prompt's "new shared include files in context/" clause
• Path containment: enforce PROJECT_ROOT containment on all resolved includes to prevent path-traversal escape
• Variable expansion: rely on compute_user_intent_paths' built-in ${VAR} handling; no separate union pass needed

Assumptions

• compute_user_intent_paths is safe to call during run_agentic_update() (no side effects, returns resolved Path set)
• New-file creation under context/ is rare enough that a directory-prefix rule won't cause false positives for unrelated mutations
• Tests in Step 6's plan will exercise both the include-edit and new-context-file preservation paths

---

Proceeding to Step 8: Analyze Prompt Changes