pdd-cli 0.0.239__tar.gz → 0.0.241__tar.gz

{pdd_cli-0.0.239/pdd_cli.egg-info → pdd_cli-0.0.241}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdd-cli
-Version: 0.0.239
+Version: 0.0.241
 Summary: PDD (Prompt-Driven Development) Command Line Interface
 Author: Greg Tanaka
 Author-email: glt@alumni.caltech.edu
@@ -52,6 +52,7 @@ Requires-Dist: uvicorn[standard]>=0.32.0
 Requires-Dist: websockets>=13.0
 Requires-Dist: watchdog>=4.0.0
 Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: filelock>=3.12
 Provides-Extra: dev
 Requires-Dist: commitizen; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -65,7 +66,7 @@ Requires-Dist: twine; extra == "dev"
 Requires-Dist: httpx==0.28.1; extra == "dev"
 Dynamic: license-file
 
-.. image:: https://img.shields.io/badge/pdd--cli-v0.0.239-blue
+.. image:: https://img.shields.io/badge/pdd--cli-v0.0.241-blue
    :alt: PDD-CLI Version
 
 .. image:: https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord&logoColor=white&link=https://discord.gg/Yp4RTh8bG7
@@ -142,7 +143,7 @@ After installation, verify:
 
    pdd --version
 
-You'll see the current PDD version (e.g., 0.0.239).
+You'll see the current PDD version (e.g., 0.0.241).
 
 Getting Started with Examples
 -----------------------------

{pdd_cli-0.0.239 → pdd_cli-0.0.241}/README.md

@@ -1,6 +1,6 @@
 # PDD (Prompt-Driven Development) Command Line Interface
 
-![PDD-CLI Version](https://img.shields.io/badge/pdd--cli-v0.0.239-blue) [![Discord](https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord&logoColor=white)](https://discord.gg/Yp4RTh8bG7)
+![PDD-CLI Version](https://img.shields.io/badge/pdd--cli-v0.0.241-blue) [![Discord](https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord&logoColor=white)](https://discord.gg/Yp4RTh8bG7)
 
 ## Introduction
 
@@ -362,7 +362,7 @@ For proper model identifiers to use in your custom configuration, refer to the [
 
 ## Version
 
-Current version: 0.0.239
+Current version: 0.0.241
 
 To check your installed version, run:
 ```
@@ -2658,6 +2658,14 @@ The command uses a two-stage retrieval pipeline when candidates exceed 50:
 
 After inserting `<include>` directives, the command performs a **deduplication pass** that identifies and removes inline content in the prompt that semantically duplicates what the included documents already provide.
 
+**Metadata finalization (on success):** After a successful `auto-deps` run, the command writes/updates a fingerprint in `.pdd/meta/` for the file that was actually written (with `operation="auto-deps"` and the current include-dependency hashes) and clears any stale per-module `_run.json` report keyed by the same identity, so downstream commands see a consistent view. The fingerprint write and the include-dependency metadata update are committed together (atomic from the caller's perspective) and use hash-based, language-agnostic helpers from `pdd.operation_log`. Finalization errors are surfaced as warnings and do not mask a successful `auto-deps` result. Invalid `<include>` tags stripped by the prompt sanitizer and architecture-merge failures (e.g. `architecture.json` could not be patched in place) are also surfaced as yellow warnings before the success summary.
+
+Identity is derived from the **output path**:
+- **In-place mode** (`--output <PROMPT_FILE>`, or `pdd sync`'s post-move flow): the output path is the canonical prompt, so the fingerprint lands at `.pdd/meta/<basename>_<language>.json`.
+- **Default mode** (output is the separate `<basename>_<language>_with_deps.prompt` derivative): the fingerprint lands at `.pdd/meta/<basename>_<language>_with_deps.json`. Canonical metadata is intentionally untouched in this case — the derivative fingerprint records that an `auto-deps` run produced that file without overwriting the canonical module's record.
+
+**Note on `pdd sync`:** `pdd sync` invokes `auto-deps` with a `*_with_deps.prompt` temp output and then moves it onto the canonical prompt. To avoid leaving orphan `.pdd/meta/*_with_deps.json` files for the moved temp prompt (and to avoid clearing the wrong run report), sync passes the internal `_skip_finalization=True` flag to `auto_deps_main` and owns canonical metadata itself: sync writes the canonical fingerprint via its atomic state machinery (`_save_fingerprint_atomic`) and clears the canonical `_run.json` via `clear_run_report` immediately after the move.
+
 The command maintains a CSV file with the following columns:
 - `full_path`: The full path to the dependency file
 - `file_summary`: A one-sentence summary of the file's content and purpose

{pdd_cli-0.0.239 → pdd_cli-0.0.241}/pdd/agentic_e2e_fix_orchestrator.py

@@ -262,6 +262,70 @@ def _resolve_step9_loop_token(step_output: str, console: Console) -> Optional[st
     return None
 
 
+def _resolve_cached_step9_output(step_outputs: Dict[str, str]) -> str:
+    """Return the authoritative Step 9 output for resume token resolution.
+
+    Step 9 may run twice in one cycle: the initial pass, plus a retry when the
+    initial pass emits no recognizable loop-control token. The retry output is
+    stored under ``step_outputs["9_retry"]`` (see the retry persistence site
+    in the inner loop); the initial output is ``step_outputs["9"]``. The retry
+    output is the authoritative one when it ran — if the retry succeeded with
+    ``ALL_TESTS_PASS`` but the workflow was interrupted before the next pause,
+    reading only ``"9"`` (which can be tokenless) would let resume fall
+    through to ``CONTINUE_CYCLE`` and silently advance into a fresh cycle even
+    though Step 9 actually succeeded. Prefer the retry output when present
+    and non-empty (#1001).
+    """
+    retry_out = step_outputs.get("9_retry", "")
+    if retry_out:
+        return retry_out
+    return step_outputs.get("9", "")
+
+
+def _post_step9_resume_action(
+    step9_output: str,
+    current_cycle: int,
+    max_cycles: int,
+    console: Console,
+) -> str:
+    """Decide what resume should do when last_completed_step >= 9 (Issue #1001).
+
+    The prior buggy code unconditionally advanced the cycle whenever
+    `last_completed_step >= 9` on resume, ignoring what Step 9 actually
+    emitted. This helper inspects the cached Step 9 output and branches:
+
+    - "SUCCESS_FALL_THROUGH" — Step 9 declared success (ALL_TESTS_PASS,
+      LOCAL_TESTS_PASS, or NOT_A_BUG). Caller must keep `current_cycle`,
+      `last_completed_step`, and `step_outputs` intact and fall through
+      to Step 11 cleanup + Step 10 CI validation.
+    - "ADVANCE_CYCLE" — Step 9 wants another cycle and budget remains.
+    - "MAX_CYCLES_REACHED" — Either Step 9 explicitly emitted
+      MAX_CYCLES_REACHED (resolved via the tier-1–3 classifier in
+      `_classify_step_output` or the tier-4 LLM fallback in
+      `_resolve_step9_loop_token`), or Step 9 wants another cycle but
+      the cycle budget is exhausted. In both cases the caller must
+      surface this as a non-success exit, reusing the same path Step 9
+      uses when emitting MAX_CYCLES_REACHED directly (see
+      `_apply_step9_resolved_token` MAX_CYCLES_REACHED handler).
+    """
+    # Defensive NOT_A_BUG check: Step 9 normally doesn't emit NOT_A_BUG
+    # (that's Step 3), but if the cached output surfaces it, treat as
+    # success — Step 3 would already have determined no bug exists.
+    if "NOT_A_BUG" in step9_output:
+        return "SUCCESS_FALL_THROUGH"
+    tok = _resolve_step9_loop_token(step9_output, console)
+    if tok in ("ALL_TESTS_PASS", "LOCAL_TESTS_PASS"):
+        return "SUCCESS_FALL_THROUGH"
+    # Explicit terminal token from Step 9 (tier-1–3 detect_control_token
+    # or tier-4 LLM classifier) must NOT be overridden by the budget
+    # check below — Step 9 already declared the loop terminal.
+    if tok == "MAX_CYCLES_REACHED":
+        return "MAX_CYCLES_REACHED"
+    if current_cycle < max_cycles:
+        return "ADVANCE_CYCLE"
+    return "MAX_CYCLES_REACHED"
+
+
 class _Step9TokenApplyResult(NamedTuple):
     """Outcome of applying a resolved Step 9 loop token (shared initial + retry paths)."""
 
@@ -477,6 +541,7 @@ def _is_intermediate_file(filepath: str) -> bool:
     - *.bak, *.backup, *.orig, *.tmp extensions
     - error_output*.txt (e.g., error_output.txt, error_output_models.txt)
     - .pdd/** (any file under .pdd/ directory — backups, core_dumps, etc.)
+    - .gh-wrapper/** (executor `gh` wrapper artifacts — Issue #1001)
     - *_errors.txt, *_fix_errors.txt (e.g., waitlist_fix_errors.txt)
     - step*_output.md (e.g., step9_output.md)
     - test_issue_*_reproduction.py (e.g., test_issue_824_reproduction.py)
@@ -491,6 +556,13 @@ def _is_intermediate_file(filepath: str) -> bool:
     stem = path.stem  # filename without extension
     suffix = path.suffix  # extension including dot
 
+    # Issue #1001: filter executor wrapper artifacts.
+    # Anchor on the directory boundary so legitimate paths like
+    # "gh-wrapper-docs.md" or "tools/gh_wrapper.py" are not over-filtered.
+    normalized_gh = str(filepath).replace("\\", "/")
+    if normalized_gh.startswith(".gh-wrapper/") or "/.gh-wrapper/" in normalized_gh:
+        return True
+
     # Check for backup extensions (e.g., foo.py.bak, foo.py.backup)
     if suffix in _BACKUP_EXTENSIONS:
         return True
@@ -1038,6 +1110,20 @@ def _has_unpushed_commits(cwd: Path) -> bool:
     return False
 
 
+def _push_unpushed_commits_or_report_noop(
+    cwd: Path,
+    repo_owner: str,
+    repo_name: str,
+) -> Tuple[bool, str]:
+    """Push ahead commits if present; otherwise treat the commit step as a no-op."""
+    if _has_unpushed_commits(cwd):
+        push_ok, push_err = _push_with_retry(cwd, repo_owner, repo_name)
+        if push_ok:
+            return True, "Pushed existing commits"
+        return False, f"Push failed: {push_err}"
+    return True, "No changes to commit"
+
+
 def push_with_retry(
     cwd: Path,
     *,
@@ -1273,15 +1359,8 @@ def _commit_and_push(
         fallback_files = [f for f in fallback_files if not _is_intermediate_file(f)]
         if fallback_files:
             files_to_commit = list(fallback_files)
-        elif _has_unpushed_commits(cwd):
-            # Check if there are unpushed commits to push
-            push_ok, push_err = _push_with_retry(cwd, repo_owner, repo_name)
-            if push_ok:
-                return True, "Pushed existing commits"
-            else:
-                return False, f"Push failed: {push_err}"
         else:
-            return True, "No changes to commit"
+            return _push_unpushed_commits_or_report_noop(cwd, repo_owner, repo_name)
 
     # Stage only workflow-changed files
     for filepath in files_to_commit:
@@ -1306,12 +1385,12 @@ def _commit_and_push(
         # Commit may fail with "nothing to commit" when fallback files were
         # already committed on the branch (merge-base diff includes them).
         # In that case, push any unpushed commits instead of failing.
-        if _has_unpushed_commits(cwd):
-            push_ok, push_err = _push_with_retry(cwd, repo_owner, repo_name)
-            if push_ok:
-                return True, "Pushed existing commits"
-            else:
-                return False, f"Push failed: {push_err}"
+        commit_output = f"{commit_result.stdout}\n{commit_result.stderr}".lower()
+        if (
+            "nothing to commit" in commit_output
+            or "no changes added to commit" in commit_output
+        ):
+            return _push_unpushed_commits_or_report_noop(cwd, repo_owner, repo_name)
         return False, f"Failed to commit: {commit_result.stderr}"
 
     # Push to remote with retry on auth failure
@@ -1539,6 +1618,9 @@ def run_agentic_e2e_fix_orchestrator(
     # against it (e.g. NOT_A_BUG direct-edit suppression) keep working.
     resumed_initial_file_hashes: Optional[Dict[str, Optional[str]]] = None
     resumed_initial_sha: Optional[str] = None
+    # Issue #1001: deferred action computed during resume that must be applied
+    # after `success`/`final_message` are initialized below. Default: no-op.
+    _resume_deferred_action: Optional[str] = None
 
     # Resume Logic
     if resume:
@@ -1575,11 +1657,35 @@ def run_agentic_e2e_fix_orchestrator(
 
             _check_staleness(loaded_state, cwd)
 
-            # If we finished a cycle but didn't exit, prepare for next cycle
+            # Issue #1001: If Step 9 was the last completed step, branch on its
+            # cached output rather than unconditionally advancing the cycle.
+            # Prefer the retry output (stored under "9_retry") when present —
+            # otherwise a retry that emitted ALL_TESTS_PASS but was interrupted
+            # before the post-Step-9 pause could be misread as a tokenless "9"
+            # and silently advance into a fresh cycle.
             if last_completed_step >= 9:
-                current_cycle += 1
-                last_completed_step = 0
-                step_outputs = {} # Clear outputs for new cycle
+                step9_cached = _resolve_cached_step9_output(step_outputs)
+                resume_action = _post_step9_resume_action(
+                    step9_cached, current_cycle, max_cycles, console
+                )
+                if resume_action == "ADVANCE_CYCLE":
+                    current_cycle += 1
+                    last_completed_step = 0
+                    step_outputs = {}  # Clear outputs for new cycle
+                elif resume_action == "MAX_CYCLES_REACHED":
+                    # Defer surfacing the failure until after `success` and
+                    # `final_message` are initialized below — mirrors the
+                    # path used by _apply_step9_resolved_token's
+                    # MAX_CYCLES_REACHED handler (final_message set, outer
+                    # loop skipped, post-loop failure handler runs).
+                    _resume_deferred_action = "MAX_CYCLES_REACHED"
+                elif resume_action == "SUCCESS_FALL_THROUGH":
+                    # Step 9 already declared success but workflow was
+                    # interrupted before commit/Step 11/Step 10. Defer
+                    # setting `success=True` until after its initialization
+                    # so we fall through to the success path (commit, code
+                    # cleanup, CI validation).
+                    _resume_deferred_action = "SUCCESS_FALL_THROUGH"
         else:
             # No state found, start fresh
             clear_workflow_state(cwd, issue_number, workflow_name, state_dir, repo_owner, repo_name, use_github_state)
@@ -1642,6 +1748,113 @@ def run_agentic_e2e_fix_orchestrator(
     import_error_retries = 0  # Global budget: max 1 retry across all cycles
     verification_failure_context = ""  # Injected into Step 1 prompt on retry
 
+    # Issue #1001 round 11: save-before-verify race.
+    # The inner-loop state save at line ~2049 persists step_outputs["9"] with
+    # the LLM's raw output BEFORE the independent verification at line ~2061 /
+    # _apply_step9_resolved_token at line ~2154 runs. A process pause in that
+    # window can leave disk state with ALL_TESTS_PASS even though verification
+    # would have failed. Re-run _verify_tests_independently on resume to close
+    # the race BEFORE treating the cycle as terminal. On failure, demote the
+    # resume action to ADVANCE_CYCLE (or MAX_CYCLES_REACHED if budget
+    # exhausted) and overwrite step_outputs["9"] with a
+    # FAILED: VERIFICATION_FAILED_ON_RESUME: prefix so the cached state
+    # reflects reality.
+    if _resume_deferred_action == "SUCCESS_FALL_THROUGH":
+        test_files = _extract_test_files(
+            issue_content, changed_files, cwd, initial_file_hashes
+        )
+        if test_files:
+            verified, verify_output = _verify_tests_independently(test_files, cwd)
+            # Mirror the cap-downgrade in _apply_step9_resolved_token for
+            # symmetry with the initial Step 9 verification path.
+            if _fallback_scan_was_capped and verified:
+                verified = False
+                verify_output += (
+                    f"\nFALLBACK_CAPPED: Only {len(test_files)} of potentially "
+                    "hundreds of test files were verified; cannot confirm full "
+                    "suite pass."
+                )
+            if not verified:
+                console.print(
+                    "[yellow]Resume re-verification: cached Step 9 success no "
+                    "longer verified by independent pytest run; advancing "
+                    "cycle.[/yellow]"
+                )
+                step_outputs["9"] = (
+                    f"FAILED: VERIFICATION_FAILED_ON_RESUME: {verify_output}"
+                )
+
+                # Issue #1001 round 12 (LOW): persist the FAILED marker BEFORE
+                # the ADVANCE_CYCLE branch clears step_outputs, otherwise the
+                # diagnostic is dead code — the inner-loop's first state save
+                # would only land after cycle advance with an empty step_outputs.
+                # Assemble the full state dict here (state_data is not yet in
+                # scope at this point in the function; it is first defined at
+                # the inner-loop site). The shape mirrors that site exactly so
+                # other fields (total_cost, dev_unit_states, initial_sha, etc.)
+                # are not clobbered on disk.
+                _state_data_resume = {
+                    "workflow": workflow_name,
+                    "issue_url": issue_url,
+                    "issue_number": issue_number,
+                    "current_cycle": current_cycle,
+                    "last_completed_step": last_completed_step,
+                    "step_outputs": step_outputs.copy(),
+                    "dev_unit_states": dev_unit_states.copy(),
+                    "total_cost": total_cost,
+                    "model_used": model_used,
+                    "changed_files": changed_files.copy(),
+                    "skipped_steps": {str(k): v for k, v in skipped_steps.items()},
+                    "last_saved_at": datetime.now().isoformat(),
+                    "github_comment_id": github_comment_id,
+                    "initial_file_hashes": dict(initial_file_hashes),
+                    "initial_sha": initial_sha,
+                }
+                try:
+                    new_gh_id = save_workflow_state(
+                        cwd,
+                        issue_number,
+                        workflow_name,
+                        _state_data_resume,
+                        state_dir,
+                        repo_owner,
+                        repo_name,
+                        use_github_state,
+                        github_comment_id,
+                    )
+                    if new_gh_id:
+                        github_comment_id = new_gh_id
+                except Exception as _save_exc:
+                    # Best-effort: the FAILED marker is still observable in
+                    # the in-memory step_outputs if we later save again
+                    # within the same cycle; don't crash resume on a save
+                    # transient.
+                    logger.debug(
+                        "Best-effort resume-reverify state save failed: %s",
+                        _save_exc,
+                        exc_info=True,
+                    )
+
+                if current_cycle < max_cycles:
+                    current_cycle += 1
+                    last_completed_step = 0
+                    step_outputs = {}  # ADVANCE_CYCLE: clear for new cycle
+                    _resume_deferred_action = None
+                else:
+                    _resume_deferred_action = "MAX_CYCLES_REACHED"
+        # else: no test files — match the initial-flow fallback (no
+        # independent verification possible). Trust the cached token, fall
+        # through to the existing SUCCESS_FALL_THROUGH handling below.
+
+    # Issue #1001: Apply deferred resume action now that `success` and
+    # `final_message` exist. Mirrors how the in-cycle Step 9 handler
+    # surfaces these tokens via _apply_step9_resolved_token.
+    if _resume_deferred_action == "SUCCESS_FALL_THROUGH":
+        success = True
+        final_message = "All tests passed after fixes (resumed)."
+    elif _resume_deferred_action == "MAX_CYCLES_REACHED":
+        final_message = "Max cycles reached."
+
     try:
         # Outer Loop
         if current_cycle == 0:

pdd_cli-0.0.241/pdd/auto_deps_main.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional, Tuple
+
+import click
+import filelock
+from rich.console import Console
+
+from . import DEFAULT_STRENGTH, DEFAULT_TIME
+from .construct_paths import construct_paths
+from .insert_includes import insert_includes
+from .validate_prompt_includes import sanitize_prompt_output
+from .auto_deps_architecture import merge_auto_deps_includes_from_cwd
+from .operation_log import (
+    infer_module_identity,
+    save_fingerprint,
+    clear_run_report,
+    get_run_report_path,
+)
+
+
+def auto_deps_main(
+    ctx: click.Context,
+    prompt_file: str,
+    directory_path: str,
+    auto_deps_csv_path: Optional[str],
+    output: Optional[str],
+    force_scan: Optional[bool] = False,
+    progress_callback: Optional[Callable[[int, int], None]] = None,
+    include_docs: bool = False,
+    no_dedup: bool = False,
+    concurrency: int = 1,
+    _skip_finalization: bool = False,
+) -> Tuple[str, float, str]:
+    """
+    CLI entry point for the `auto-deps` command.
+
+    Analyzes the given prompt file, discovers dependencies (and optionally docs)
+    in `directory_path`, inserts `<include>` directives, deduplicates redundant
+    inline content (unless disabled), writes the modified prompt + dependency
+    CSV, and finalizes per-module fingerprint metadata when overwriting the
+    canonical prompt in place.
+
+    Returns:
+        (cleaned_prompt, total_cost, model_name) on success.
+        ("", 0.0, f"Error: {exc}") on non-Abort failures so orchestrators can
+        continue gracefully.
+    """
+    console = Console()
+    quiet = ctx.obj.get("quiet", False) if ctx.obj else False
+
+    try:
+        # Build inputs for construct_paths
+        input_file_paths = {"prompt_file": prompt_file}
+        command_options = {"output": output, "csv": auto_deps_csv_path}
+
+        force = ctx.obj.get("force", False) if ctx.obj else False
+        context_override = ctx.obj.get("context") if ctx.obj else None
+        confirm_callback = ctx.obj.get("confirm_callback") if ctx.obj else None
+
+        resolved_config, input_strings, output_file_paths, _ = construct_paths(
+            input_file_paths=input_file_paths,
+            force=force,
+            quiet=quiet,
+            command="auto-deps",
+            command_options=command_options,
+            context_override=context_override,
+            confirm_callback=confirm_callback,
+        )
+
+        # Resolve CSV path with default fallback
+        csv_path = output_file_paths.get("csv", "project_dependencies.csv")
+
+        # Acquire exclusive lock for the entire operation
+        lock_path = Path(f"{csv_path}.lock")
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        lock = filelock.FileLock(f"{csv_path}.lock")
+        with lock:
+            # Force-scan: delete existing CSV if requested
+            if force_scan and Path(csv_path).exists():
+                if not quiet:
+                    console.print(
+                        f"[yellow]Removing existing CSV file due to --force-scan option: {csv_path}[/yellow]"
+                    )
+                try:
+                    Path(csv_path).unlink()
+                except OSError as exc:
+                    if not quiet:
+                        console.print(
+                            f"[yellow]Warning: Could not remove CSV file {csv_path}: {exc}[/yellow]"
+                        )
+
+            # LLM parameters
+            strength = ctx.obj.get("strength", DEFAULT_STRENGTH) if ctx.obj else DEFAULT_STRENGTH
+            temperature = ctx.obj.get("temperature", 0) if ctx.obj else 0
+            time_budget = ctx.obj.get("time", DEFAULT_TIME) if ctx.obj else DEFAULT_TIME
+            verbose = not quiet
+
+            # Run insert_includes
+            modified_prompt, csv_output, total_cost, model_name = insert_includes(
+                input_prompt=input_strings["prompt_file"],
+                directory_path=directory_path,
+                csv_filename=csv_path,
+                prompt_filename=prompt_file,
+                strength=strength,
+                temperature=temperature,
+                time=time_budget,
+                verbose=verbose,
+                progress_callback=progress_callback,
+                include_docs=include_docs,
+                dedup=(not no_dedup),
+                max_workers=concurrency,
+            )
+
+            # Sanitize prompt output before persisting (removes invalid <include>
+            # selectors so a later `pdd sync` does not trip on them).
+            output_path = output_file_paths["output"]
+            cleaned_prompt, invalid_includes = sanitize_prompt_output(
+                modified_prompt, output_path
+            )
+            if invalid_includes and not quiet:
+                console.print(
+                    f"[yellow]Warning: Cleaned {len(invalid_includes)} invalid "
+                    f"<include> tag(s) before saving {output_path}: "
+                    f"{invalid_includes}[/yellow]"
+                )
+
+            # Persist modified prompt
+            Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as fh:
+                fh.write(cleaned_prompt)
+
+            # Persist CSV if non-empty
+            if csv_output:
+                Path(csv_path).parent.mkdir(parents=True, exist_ok=True)
+                with open(csv_path, "w", encoding="utf-8") as fh:
+                    fh.write(csv_output)
+
+            # Merge architecture.json dependencies (if architecture.json exists in project root)
+            try:
+                merge_result = merge_auto_deps_includes_from_cwd(
+                    Path(output_path),
+                    old_prompt_text=input_strings["prompt_file"],
+                    new_prompt_text=cleaned_prompt,
+                )
+            except Exception as merge_exc:
+                if not quiet:
+                    console.print(
+                        f"[yellow]Warning: architecture.json merge failed: {merge_exc}[/yellow]"
+                    )
+            else:
+                # Non-exception failures must still reach the user; otherwise the
+                # CLI prints success while architecture.json was silently left
+                # unchanged. ``updated=False`` is also returned for legitimate
+                # no-ops (auto_deps_architecture.py:326 — nothing needed adding),
+                # so gate the warning on ``added_dependencies`` being non-empty:
+                # that distinguishes "we wanted to write X but couldn't" from
+                # "nothing to write."
+                if (
+                    isinstance(merge_result, dict)
+                    and not merge_result.get("updated", True)
+                    and merge_result.get("added_dependencies")
+                ):
+                    if not quiet:
+                        messages = merge_result.get("messages") or [
+                            "merge_auto_deps_includes_from_cwd reported updated=False"
+                        ]
+                        for msg in messages:
+                            console.print(
+                                f"[yellow]Warning: architecture.json not updated: {msg}[/yellow]"
+                            )
+
+            # Console reporting
+            if not quiet:
+                console.print(
+                    "[bold green]Successfully analyzed and inserted dependencies![/bold green]"
+                )
+                console.print(f"[bold]Model used:[/bold] {model_name}")
+                console.print(f"[bold]Total cost:[/bold] ${total_cost:.6f}")
+                console.print(f"[bold]Modified prompt saved to:[/bold] {output_path}")
+                console.print(f"[bold]Dependency information saved to:[/bold] {csv_path}")
+
+            # Metadata finalization for every successful auto-deps mutation
+            # (issue #989). Identity comes from the file that was actually
+            # written (``output_path``); in in-place mode this resolves to the
+            # canonical ``<basename>_<language>`` module, in the default CLI
+            # flow it resolves to the ``<basename>_<language>_with_deps``
+            # derivative. Errors are surfaced as warnings and never mask a
+            # successful auto-deps result.
+            #
+            # ``_skip_finalization=True`` is set by ``pdd sync`` because it
+            # invokes auto-deps with a temp ``<basename>_<language>_with_deps``
+            # output that it then ``shutil.move``s onto the canonical prompt;
+            # writing a fingerprint for that temp identity here would leave
+            # ``.pdd/meta/*_with_deps.json`` orphaned after the move, and the
+            # derivative's identity is the wrong target for run-report clears
+            # (sync owns the canonical fingerprint write and the canonical
+            # run-report clear on its side).
+            if _skip_finalization:
+                return cleaned_prompt, total_cost, model_name
+            try:
+                basename, language = infer_module_identity(Path(output_path))
+                if basename is None or language is None:
+                    if not quiet:
+                        console.print(
+                            f"[yellow]Warning: Could not infer module identity for "
+                            f"{output_path}; skipping fingerprint finalization.[/yellow]"
+                        )
+                else:
+                    # Clear stale run report; do not let its failure block fingerprint save
+                    try:
+                        clear_run_report(basename, language)
+                    except Exception as cr_exc:
+                        if not quiet:
+                            console.print(
+                                f"[yellow]Warning: Failed to clear run report for "
+                                f"{basename}_{language}: {cr_exc}[/yellow]"
+                            )
+                    # Defensive: clear_run_report() in pdd.operation_log silently swallows
+                    # OSError on the actual unlink, so verify the report is really gone.
+                    try:
+                        _stale_report_path = get_run_report_path(basename, language)
+                        if _stale_report_path.exists():
+                            if not quiet:
+                                console.print(
+                                    f"[yellow]Warning: clear_run_report did not remove "
+                                    f"{_stale_report_path}; downstream sync may still see "
+                                    f"stale results.[/yellow]"
+                                )
+                    except Exception as _vrf_exc:
+                        if not quiet:
+                            console.print(
+                                f"[yellow]Warning: could not verify run-report removal: "
+                                f"{_vrf_exc}[/yellow]"
+                            )
+                    try:
+                        save_fingerprint(
+                            basename=basename,
+                            language=language,
+                            operation="auto-deps",
+                            paths={"prompt": Path(output_path)},
+                            cost=total_cost,
+                            model=model_name,
+                        )
+                    except Exception as fp_exc:
+                        if not quiet:
+                            console.print(
+                                f"[yellow]Warning: Failed to save fingerprint for "
+                                f"{basename}_{language}: {fp_exc}[/yellow]"
+                            )
+            except Exception as meta_exc:
+                # Never mask a successful auto-deps result on metadata errors
+                if not quiet:
+                    console.print(
+                        f"[yellow]Warning: Metadata finalization encountered an error: {meta_exc}[/yellow]"
+                    )
+
+            return cleaned_prompt, total_cost, model_name
+
+    except click.Abort:
+        # Re-raise to allow orchestrators (e.g. pdd sync) to stop the loop
+        raise
+    except Exception as exc:
+        if not quiet:
+            console.print(f"[red]Error in auto-deps: {exc}[/red]")
+        return "", 0.0, f"Error: {exc}"