pdd-cli 0.0.264__tar.gz → 0.0.265__tar.gz

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/.github/workflows/release.yml

@@ -202,9 +202,9 @@ jobs:
       #                                artifact:read, distribution:package,
       #                                distribution:publish). A project-locked
       #                                token (e.g. an e2e profile) will NOT work.
-      #   vars.PDS_CLI_PACKAGE         install spec for the private
-      #                                @promptdriven/pds CLI — an npm spec once
-      #                                published, or an https/tarball URL.
+      #   vars.PDS_CLI_PACKAGE         install spec for the @promptdriven/pds
+      #                                CLI, for example @promptdriven/pds@latest
+      #                                or a pinned version.
       #   vars.PDS_API_URL             PDS backend (default the CLI's built-in).
       #   vars.RELEASE_VIDEO_PROJECT_ID  optional stable PDS project to reuse
       #                                across releases (else a per-release

{pdd_cli-0.0.264/pdd_cli.egg-info → pdd_cli-0.0.265}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdd-cli
-Version: 0.0.264
+Version: 0.0.265
 Summary: PDD (Prompt-Driven Development) Command Line Interface
 Author: Greg Tanaka
 Author-email: glt@alumni.caltech.edu

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/README.md

@@ -58,6 +58,9 @@ For pre-merge prompt and user-story quality (vague terms, vocabulary, optional L
 For deterministic contract-section lint (`<contract_rules>`, `<coverage>`, waivers, story `## Covers`), see [docs/contract_check.md](docs/contract_check.md).
 
 For a rule-to-story/test coverage matrix (`pdd checkup coverage`), see [docs/coverage_contracts.md](docs/coverage_contracts.md).
+
+For non-interactive bounded prompt repair after a failed prompt source-set checkup, see [docs/prompt_repair.md](docs/prompt_repair.md).
+
 ## Installation
 
 ### Prerequisites for macOS
@@ -2922,9 +2925,13 @@ Options:
 - `--continue-on-reviewer-limit`: Report provider, rate, context-window, timeout, auth, network, sandbox, permission, and non-zero-exit reviewer failures as `degraded` instead of `failed`. Degraded reviewers are still not clean unless a configured fallback reviewer completes successfully and takes over as the active reviewer.
 - `--fallback-reviewer-on-failure`: When the primary reviewer ends in `failed` or `missing` (not `degraded`), run a second review pass using the fixer's identity as a fallback reviewer. On a clean fallback the rendered `reviewer-status:` line shows the primary as `clean` so the cloud verdict adapter's real-reviewer-clean rule can fire, while the primary's original failure detail is preserved in the `### Reviewer Diagnostics` subsection of the final report with a `superseded_by_fallback` marker. Off by default to preserve existing CI expectations.
 - `--no-gates`: Disable the deterministic local gates (`git diff --check` against the PR range, `doc-contract`, `prettier --check`, `npx --no-install tsc --noEmit`, a non-mutating Python syntax check via the builtin `compile()`, `ruff check`/`ruff format --check`/`black --check`/`mypy`) that otherwise run before any `clean` verdict in `--review-loop`. **`ruff format --check`** is opt-in: it fires only when **either** `[tool.ruff.format]` is declared in `pyproject.toml`, **or** a literal `ruff format` / `ruff-format` reference appears in `.pre-commit-config.yaml`, `cloudbuild-*-ci.yaml`, or `.github/workflows/*.{yml,yaml}` (canonical pre-commit hook id matches the hyphenated form). Touched CI files are excluded from the signal scan to defend against PR-poisoned opt-in. The Python syntax gate routes through `compile()` rather than `python -m py_compile` so it never writes `__pycache__/*.pyc` into the worktree; the TypeScript gate uses `--no-install` so it never hits the npm registry. Gate subprocesses resolve `git` and tool binaries through a sanitized PATH so a PR cannot provide worktree-local shims via `PATH=.:$PATH`. Default: gates are enabled. The flag exists only as a diagnostic/emergency escape hatch — under normal operation a failing gate must block the PR from being declared clean even when the LLM reviewer says clean. Issue #1092.
-- `doc-contract` repo config: non-PDD projects can declare documentation contracts in `.pdd/doc_contract.json` or `.pdd/doc-contract.json` with `version: 1` and `rules` containing `source_globs`, `added_regex`, and `docs`/`doc_paths`. Each captured added surface must be documented in the configured docs/sections; optional `doc_regex` can tie named captures together, such as requiring an operation and its new skip condition to appear in the same documented contract. In PR mode the base branch’s config is authoritative, so a PR cannot bypass the gate by weakening its own config. For prompt-level regression testing, changed non-LLM `.prompt` files must also be covered by at least one `user_stories/story__*.md` link, making `pdd detect --stories` the executable prompt test for those prompt changes.
+- `doc-contract` repo config: non-PDD projects can declare documentation contracts in `.pdd/doc_contract.json` or `.pdd/doc-contract.json` with `version: 1` and `rules` containing `source_globs`, `added_regex`, and `docs`/`doc_paths`. Each captured added surface must be documented in the configured docs/sections; optional `doc_regex` can tie named captures together, such as requiring an operation and its new skip condition to appear in the same documented contract. In PR mode the base branch’s config is authoritative, so a PR cannot bypass the gate by weakening its own config.
 - `--gate-timeout FLOAT`: Per-gate timeout in seconds (default: 60). Applies to every discovered gate; the runner kills the subprocess and surfaces the gate as a `runner-error` blocker finding when the timeout fires.
 - `--gate-allow GATE`: Repeatable allowlist token forwarded to `discover_gates` as `extra_allow`. Reserved for future versions to opt extra gate names into the discovery set; the current default discovery is allowlist-only and the argument is accepted but does not widen it. Useful primarily as a forward-compat plumbing hook for CI configurations.
+- `--prompt-repair MODE`: Non-interactive prompt repair mode when automatic prompt checkup fails. Accepted values: `off` (default, no repair), `best-effort` (repair and continue even if issues remain after repair), `strict` (block on unresolved issues after repair). Overrides the `prompt_repair` setting in `[tool.pdd.checkup]` in `pyproject.toml`.
+- `--max-prompt-repair-rounds INT`: Maximum repair-and-recheck iterations per prompt file (default: 1).
+- `--max-prompt-token-growth INT`: Maximum token increase allowed during a single repair pass (default: 1000).
+- `--max-prompt-repair-seconds FLOAT`: Wall-clock timeout for the entire prompt repair loop in seconds (default: 120.0).
 
 **Deterministic-gate coverage limits (issue #1092)**: The default gate set is intentionally conservative because PR contents are untrusted on fork PRs. As a result the following workflows do NOT block a clean verdict and you should still rely on CI / human review for them:
 - **JS/TS PRs that change any `.js` / `.cjs` / `.mjs` file (anywhere in the worktree)**: prettier and eslint script gates are skipped because their configs can `require()` arbitrary local JavaScript (including subdirectory plugin modules) and the require chain is undecidable without running the very code we are trying to gate. A PR-sized JS formatting/lint regression on such a PR will only be caught by CI.

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/architecture.json

@@ -7334,11 +7334,12 @@
     }
   },
   {
-    "reason": "Entry point for the agentic checkup workflow \u2014 fetches the GitHub issue when one is provided (optional in PR mode), loads project context, and dispatches to the checkup orchestrator or PR review-loop.",
-    "description": "Accepts an optional GitHub issue URL; when one is provided it fetches issue content and comments, otherwise (PR mode only) it threads empty issue context so the PR is reviewed on its own merits. Loads architecture.json and .pddrc, then invokes the multi-step checkup orchestrator, the PR-mode primary-reviewer/fixer review loop, or (final_gate) the canonical two-layer final PR gate (issue #1406): Layer 1 PR-scoped checkup then Layer 2 review-loop on the resulting head, returning a real ship verdict derived from the review-loop final-state.json. PR review-loop context is bounded and includes PR body, changed files, comments, and submitted reviews.",
+    "reason": "Entry point for the agentic checkup workflow; in PR mode the linked issue is optional (own-merits review).",
+    "description": "Accepts an optional GitHub issue URL; when one is provided it fetches issue content and comments, otherwise (PR mode only) it threads empty issue context so the PR is reviewed on its own merits. Loads architecture.json and .pddrc, optionally runs a bounded non-interactive prompt repair loop on changed .prompt files, then invokes the multi-step checkup orchestrator, the PR-mode primary-reviewer/fixer review loop, or (final_gate) the canonical two-layer final PR gate (issue #1406): Layer 1 PR-scoped checkup then Layer 2 review-loop on the resulting head, returning a real ship verdict derived from the review-loop final-state.json. PR review-loop context is bounded and includes PR body, changed files, comments, and submitted reviews.",
     "dependencies": [
       "agentic_common_python.prompt",
-      "checkup_review_loop_python.prompt"
+      "checkup_review_loop_python.prompt",
+      "prompt_repair_python.prompt"
     ],
     "priority": 217,
     "filename": "agentic_checkup_python.prompt",
@@ -7354,7 +7355,7 @@
         "functions": [
           {
             "name": "run_agentic_checkup",
-            "signature": "(issue_url: Optional[str] = None, *, verbose: bool, quiet: bool, no_fix: bool, timeout_adder: float, use_github_state: bool, reasoning_time: Optional[float], pr_url: Optional[str], review_loop: bool, final_gate: bool, review_only: bool, reviewers: str, reviewer: Optional[str], fixer: Optional[str], reviewer_fallback: Optional[str], fixer_fallback: Optional[str], max_review_rounds: int, max_review_cost: float, max_review_minutes: float, require_all_reviewers_clean: bool, continue_on_reviewer_limit: bool, require_final_fresh_review: bool, blocking_severities: Optional[str], clean_reviewer_states: Optional[str], fallback_reviewer_on_failure: bool, enable_gates: bool = True, gate_timeout: float = 60.0, gate_allow: Tuple[str, ...] = (), start_step_override: Optional[Union[int, float]] = None, cwd: Optional[Path] = None) -> Tuple[bool, str, float, str]",
+            "signature": "(issue_url: Optional[str] = None, *, verbose: bool = False, quiet: bool = False, no_fix: bool = False, timeout_adder: float = 0.0, use_github_state: bool = True, reasoning_time: Optional[float] = None, pr_url: Optional[str] = None, review_loop: bool = False, final_gate: bool = False, review_only: bool = False, reviewers: str = \"codex,claude\", reviewer: Optional[str] = None, fixer: Optional[str] = None, reviewer_fallback: Optional[str] = None, fixer_fallback: Optional[str] = None, max_review_rounds: int = 5, max_review_cost: float = 50.0, max_review_minutes: float = 90.0, require_all_reviewers_clean: bool = True, continue_on_reviewer_limit: bool = False, require_final_fresh_review: bool = True, blocking_severities: Optional[str] = None, clean_reviewer_states: Optional[str] = None, fallback_reviewer_on_failure: bool = False, enable_gates: bool = True, gate_timeout: float = 60.0, gate_allow: Tuple[str, ...] = (), start_step_override: Optional[Union[int, float]] = None, cwd: Optional[Path] = None, prompt_repair: str = \"off\", max_prompt_repair_rounds: int = 1, max_prompt_token_growth: int = 1000, max_prompt_repair_seconds: float = 120.0) -> Tuple[bool, str, float, str]",
             "returns": "Tuple[bool, str, float, str]",
             "sideEffects": [
               "Fetches the GitHub issue (when provided) and PR context via gh api",
@@ -7394,6 +7395,22 @@
             "sideEffects": [
               "Reads PR metadata, changed files, PR comments, and PR reviews with gh api"
             ]
+          },
+          {
+            "name": "_discover_prompt_paths",
+            "signature": "(cwd: Path) -> List[Path]",
+            "returns": "List[Path]",
+            "sideEffects": [
+              "Runs git diff to detect tracked/new .prompt files; falls back to glob"
+            ]
+          },
+          {
+            "name": "_review_loop_ship_verdict",
+            "signature": "(final_state: Optional[Dict[str, Any]], *, has_issue: bool) -> bool",
+            "returns": "bool",
+            "sideEffects": [
+              "None"
+            ]
           }
         ]
       }
@@ -7523,7 +7540,7 @@
   },
   {
     "reason": "Enforces deterministic-gate checks (linter, syntax, and doc-contract gates) in checkup review loops.",
-    "description": "Discovers and executes a conservative, allowlisted set of repo-local checks (PR-range git diff --check, doc-contract, prettier --check via package.json, a non-mutating Python syntax check via the builtin compile() builtin per changed .py file, optional ruff/black/mypy when configured in pyproject.toml, optional `npx --no-install tsc --noEmit` when typescript is declared AND node_modules/typescript/bin/tsc is on disk). The doc-contract gate supports repo-declared `.pdd/doc_contract.json` / `.pdd/doc-contract.json` rules for non-PDD projects; when a base-tree config exists it is authoritative so a reviewed PR cannot weaken its own documentation contract. It also enforces prompt-level story coverage for changed non-LLM `.prompt` files by requiring a linked `user_stories/story__*.md`, so user stories serve as the prompt regression-test artifact for `pdd detect --stories` (issue #560 bridge). Per-file gates pass POSIX `--` end-of-options separator so paths cannot be parsed as flags. Each gate runs as a list-form subprocess with bounded timeout, output truncation, PDD_* env scrubbing, sanitized PATH, and secret redaction; gate discovery and changed-file git probes resolve a trusted absolute git binary outside the PR worktree so PATH=.:$PATH cannot run a PR-shipped ./git. Failing gates are converted into synthetic blocker ReviewFinding rows with reviewer prefix 'gate:' so the review loop refuses the clean verdict and routes the deterministic failure through the fixer.",
+    "description": "Discovers and executes a conservative, allowlisted set of repo-local checks (PR-range git diff --check, doc-contract, prettier --check via package.json, a non-mutating Python syntax check via the builtin compile() builtin per changed .py file, optional ruff/black/mypy when configured in pyproject.toml, optional `npx --no-install tsc --noEmit` when typescript is declared AND node_modules/typescript/bin/tsc is on disk). The doc-contract gate supports repo-declared `.pdd/doc_contract.json` / `.pdd/doc-contract.json` rules for non-PDD projects; when a base-tree config exists it is authoritative so a reviewed PR cannot weaken its own documentation contract. Per-file gates pass POSIX `--` end-of-options separator so paths cannot be parsed as flags. Each gate runs as a list-form subprocess with bounded timeout, output truncation, PDD_* env scrubbing, sanitized PATH, and secret redaction; gate discovery and changed-file git probes resolve a trusted absolute git binary outside the PR worktree so PATH=.:$PATH cannot run a PR-shipped ./git. Failing gates are converted into synthetic blocker ReviewFinding rows with reviewer prefix 'gate:' so the review loop refuses the clean verdict and routes the deterministic failure through the fixer.",
     "dependencies": [
       "checkup_review_loop_python.prompt"
     ],
@@ -8114,10 +8131,13 @@
     }
   },
   {
-    "reason": "Registers the pdd checkup CLI command for project health checks and lint dispatch.",
+    "reason": "Registers the pdd checkup CLI command, which orchestrates project-wide health checks and fixes.",
     "description": "Defines the checkup Click command including pdd checkup lint dispatch, validate-arch-includes, and agentic checkup integration. In PR mode (--pr) the --issue option is optional (PR reviewed on its own merits when omitted); --pr stays mutually exclusive with the positional TARGET, and --issue without --pr is rejected.",
     "dependencies": [
-      "agentic_checkup_python.prompt"
+      "agentic_checkup_python.prompt",
+      "commands/prompt_python.prompt",
+      "commands/contracts_python.prompt",
+      "commands/gate_python.prompt"
     ],
     "priority": 236,
     "filename": "commands/checkup_python.prompt",
@@ -9912,7 +9932,7 @@
   },
   {
     "reason": "Single blocking pre-checkup gate that drift-syncs and build/smoke-verifies a PR before handing off to checkup --pr.",
-    "description": "A blocking pre-checkup quality gate invoked by both the change/feature and fix/bug e2e orchestrators immediately before `pdd checkup --pr`. Runs two ordered phases against the PR worktree and returns a single hard pass/fail the caller uses to block the handoff. Phase 1 (drift-sync) brings code, prompt, architecture.json and .pdd/meta into sync in the worktree via run_metadata_sync / sync_all_prompts_to_architecture / detect_drift+heal_module, then re-detects to confirm. .pdd/meta fingerprints written here via run_metadata_sync cover prompt+code only (example/test hashes are null), so canonical fingerprint finalization belongs to the post-merge sync (#1317): BOTH orchestrator paths defer it — the fix path filters .pdd/** from its commit, the change path restores tracked .pdd/meta after the gate — so the PR tree may still show fingerprint drift until the post-merge sync completes it. Phase 2 (build/smoke) runs deterministic per-file checks (py_compile/ruff/tsc) plus a project smoke layer (import changed modules, route/router-object probe, caller-compatibility sweep over both from-import and alias-import call sites, git-diff-targeted unit tests including directly-changed test files) and hard-blocks on any red result. Closes the vacuous-pass hole in run_ci_validation_loop by running its own checks rather than only polling GitHub required checks; preserves the fork-PR-RCE constraint by delegating to checkup_gates._script_is_acceptable, which runs only validated, safe package.json scripts (never build scripts) and skips the npm-family path entirely when the PR touches package.json / a package-manager config; the gate adds no command execution of its own beyond that allowlist. Docs-only diffs short-circuit; strict mode reuses PDD_STRICT_DOC_SYNC (issue #1293).",
+    "description": "A blocking pre-checkup quality gate invoked by both the change/feature and fix/bug e2e orchestrators immediately before `pdd checkup --pr`. Runs two ordered phases against the PR worktree and returns a single hard pass/fail the caller uses to block the handoff. Phase 1 (drift-sync) brings code, prompt, architecture.json and .pdd/meta into sync in the worktree via run_metadata_sync / sync_all_prompts_to_architecture / detect_drift+heal_module, then re-detects to confirm. .pdd/meta fingerprints written here via run_metadata_sync cover prompt+code only (example/test hashes are null), so canonical fingerprint finalization belongs to the post-merge sync (#1317): BOTH orchestrator paths defer it \u2014 the fix path filters .pdd/** from its commit, the change path restores tracked .pdd/meta after the gate \u2014 so the PR tree may still show fingerprint drift until the post-merge sync completes it. Phase 2 (build/smoke) runs deterministic per-file checks (py_compile/ruff/tsc) plus a project smoke layer (import changed modules, route/router-object probe, caller-compatibility sweep over both from-import and alias-import call sites, git-diff-targeted unit tests including directly-changed test files) and hard-blocks on any red result. Closes the vacuous-pass hole in run_ci_validation_loop by running its own checks rather than only polling GitHub required checks; preserves the fork-PR-RCE constraint by delegating to checkup_gates._script_is_acceptable, which runs only validated, safe package.json scripts (never build scripts) and skips the npm-family path entirely when the PR touches package.json / a package-manager config; the gate adds no command execution of its own beyond that allowlist. Docs-only diffs short-circuit; strict mode reuses PDD_STRICT_DOC_SYNC (issue #1293).",
     "dependencies": [
       "checkup_gates_python.prompt",
       "ci_drift_heal_python.prompt",
@@ -9941,5 +9961,33 @@
         ]
       }
     }
+  },
+  {
+    "reason": "Non-interactive prompt source-set repair orchestrator using the internal change() contract.",
+    "description": "Implements run_prompt_repair_loop(): consumes pdd.prompt_source_set_report.v1 findings and supporting context, synthesizes bounded change instructions, applies the complete prompt through pdd.change.change(), enforces token growth, rebuilds the full source-set report after each round, and writes an audit artifact to .pdd/evidence/prompt_repair/.",
+    "dependencies": [
+      "change_python.prompt",
+      "checkup_prompt_main_python.prompt",
+      "prompt_lint_python.prompt"
+    ],
+    "priority": 250,
+    "filename": "prompt_repair_python.prompt",
+    "filepath": "pdd/prompt_repair.py",
+    "tags": [
+      "module",
+      "python"
+    ],
+    "interface": {
+      "type": "module",
+      "module": {
+        "functions": [
+          {
+            "name": "run_prompt_repair_loop",
+            "signature": "(path: Path, config: PromptRepairConfig, *, context: Optional[Dict[str, str]] = None, cwd: Optional[Path] = None) -> RepairResult",
+            "returns": "RepairResult"
+          }
+        ]
+      }
+    }
   }
 ]

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/docs/prompt_lint.md

@@ -55,7 +55,11 @@ To achieve maximum velocity and specification quality in Prompt-Driven Developme
 ```mermaid
 graph TD
     A["1. Write Draft Prompt (.prompt)"] --> B["2. Run 'pdd checkup lint'"]
-    B -->|Flagged Ambiguities| C["Refine Prose & Add <vocabulary>"]
+    B -->|"Flagged Ambiguities (repair=off)"| C["Refine Prose & Add <vocabulary>"]
+    B -->|"Flagged Ambiguities (repair=best-effort)"| R["Non-interactive prompt repair"]
+    R --> B2["Re-run checkup lint"]
+    B2 -->|"Still failing"| C
+    B2 -->|"Linter Passes"| D
     C --> B
     B -->|Linter Passes| D["3. Generate Code ('pdd generate')"]
     D --> E["4. Verify Code ('make test')"]
@@ -75,6 +79,8 @@ pdd checkup lint prompts/my_feature_python.prompt --llm
 ```
 Review the advisory warnings, refine any vague terms, and build a precise `<vocabulary>` block in the prompt to define what ambiguous terms mean in your domain. Rerun the linter until the scan is clean.
 
+When `prompt_repair = "best-effort"` is set in `pyproject.toml` `[tool.pdd.checkup]` (or `--prompt-repair best-effort` is passed), a failed prompt source-set checkup automatically triggers a bounded, non-interactive repair pass — adding missing vocabulary definitions, normalizing contract rule IDs, filling coverage gaps — before re-running the full source-set check. See [docs/prompt_repair.md](prompt_repair.md) for configuration and safety details.
+
 ### Step 3: Generate Code
 Once the prompt contract is clean and deterministic, generate the initial implementation:
 ```bash

pdd_cli-0.0.265/docs/prompt_repair.md

@@ -0,0 +1,114 @@
+# Non-Interactive Prompt Repair Loop
+
+When automatic prompt checkup fails, PDD can run a **bounded, non-interactive repair pass**, re-run checkup, then continue or report remaining issues.
+
+Keeps PDD in prompt space: improve the prompt before code-level debugging.
+
+## Workflow
+
+```text
+PDD creates/modifies prompt
+     ↓
+deterministic prompt checkup
+     ↓
+pass → continue to code generation/change
+fail → non-interactive prompt repair
+     ↓
+prompt checkup again
+     ↓
+pass/warn → continue | else report remaining issues (strict may block)
+```
+
+## Usage
+
+```bash
+# Disable repair (default)
+pdd checkup ... --prompt-repair off
+
+# Best-effort repair (continues even if issues remain after repair)
+pdd checkup ... --prompt-repair best-effort
+```
+
+## What the Repair Loop Fixes
+
+The repair brief consumes prompt-fixable findings from the structured source-set
+report: lint, contract, and coverage (for example unchecked requirements or missing
+contract rules). External-only findings such as gate `missing_evidence`, drift
+readiness notes, and snapshot policy failures that require evidence capture do
+not drive automated repair. The loop applies the smallest coherent prompt-only
+update through the internal `pdd change` implementation, then rebuilds the
+complete report.
+
+The repair loop does **not** edit generated code, tests, stories, or other files.
+
+## Configuration
+
+```toml
+# pyproject.toml
+[tool.pdd.checkup]
+prompt_repair = "best-effort"   # off | best-effort | strict
+max_prompt_repair_rounds = 1
+max_prompt_token_growth = 1000
+max_prompt_repair_seconds = 120
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `prompt_repair` | `off` | Repair mode: `off` disables; `best-effort` repairs and continues on failure; `strict` blocks on unresolved issues after repair |
+| `max_prompt_repair_rounds` | `1` | Maximum repair-and-recheck iterations |
+| `max_prompt_token_growth` | `1000` | Maximum token increase allowed during repair |
+| `max_prompt_repair_seconds` | `120` | Wall-clock timeout for the entire repair loop |
+
+## CLI Flags
+
+The following flags can be passed to `pdd checkup` (and related commands that invoke checkup) to override `pyproject.toml [tool.pdd.checkup]` defaults:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--prompt-repair MODE` | `off` | Non-interactive repair mode: `off`, `best-effort`, or `strict` |
+| `--max-prompt-repair-rounds INT` | `1` | Maximum repair-and-recheck iterations |
+| `--max-prompt-token-growth INT` | `1000` | Maximum token increase allowed during repair |
+| `--max-prompt-repair-seconds FLOAT` | `120.0` | Wall-clock timeout for the entire repair loop |
+
+## Token Delta Reporting
+
+After repair, PDD reports the token impact:
+
+```
+Prompt token delta: +312 tokens
+Note: 240 tokens are reusable contract preamble.
+```
+
+A warning is emitted if growth exceeds `max_prompt_token_growth`.
+
+## Safety
+
+- Deterministic source-set checkup remains the authority after every repair round
+- Prompt changes use `pdd.change.change()` and its modified-prompt delimiter contract
+- No generated code edits
+- Audit note written under `.pdd/evidence/prompt_repair/<slug>-<timestamp>.json`
+
+## Evidence
+
+Each repair run writes a record to the run's evidence manifest:
+
+```json
+{
+  "run_id": "...",
+  "prompt_path": "prompts/my_module_python.prompt",
+  "tokens_before": 412,
+  "tokens_after": 724,
+  "token_delta": 312,
+  "rounds_used": 1,
+  "issues_before": 3,
+  "issues_after": 0,
+  "status": "repaired"
+}
+```
+
+## Non-goals
+
+- No separate `pdd checkup coach` command
+- No interactive questions (deferred to a later issue in the stack)
+- No CI interactive mode
+- No unbounded agentic repo search

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/pdd/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.264'
-__version_tuple__ = version_tuple = (0, 0, 264)
+__version__ = version = '0.0.265'
+__version_tuple__ = version_tuple = (0, 0, 265)
 
-__commit_id__ = commit_id = 'gd5df6afb9'
+__commit_id__ = commit_id = 'g93284a16a'

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/pdd/agentic_checkup.py

@@ -9,10 +9,11 @@ fixes them — one step per LLM call for reliability.
 from __future__ import annotations
 
 import json
+import logging
 import math
 import re
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 from rich.console import Console
 
@@ -35,8 +36,15 @@ from .checkup_review_loop import (
     run_checkup_review_loop,
 )
 from .agentic_sync import _find_project_root, _load_architecture_json
+from .prompt_repair import (
+    PromptRepairConfig,
+    discover_prompt_paths,
+    format_token_delta_summary,
+    run_prompt_repair_loop,
+)
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _extract_json_from_text(text: str) -> Optional[Dict[str, Any]]:
@@ -406,6 +414,10 @@ def run_agentic_checkup(
     gate_allow: Tuple[str, ...] = (),
     start_step_override: Optional[Union[int, float]] = None,
     cwd: Optional[Path] = None,
+    prompt_repair: str = "off",
+    max_prompt_repair_rounds: int = 1,
+    max_prompt_token_growth: int = 1000,
+    max_prompt_repair_seconds: float = 120.0,
 ) -> Tuple[bool, str, float, str]:
     """Run agentic checkup workflow from a GitHub issue URL.
 
@@ -546,6 +558,84 @@ def run_agentic_checkup(
     if not quiet:
         console.print("[bold]Running agentic checkup...[/bold]")
 
+    # check → repair → recheck cycle for changed prompt files (Issue #1422).
+    # Uses the full pdd.prompt_source_set_report.v1 structured report as the
+    # repair oracle (not just lint), then re-verifies before the orchestrator runs.
+    if prompt_repair != "off":
+        from .checkup_prompt_main import build_prompt_source_set_report  # pylint: disable=import-outside-toplevel
+
+        repair_config = PromptRepairConfig(
+            mode=prompt_repair,
+            max_rounds=max_prompt_repair_rounds,
+            max_token_growth=max_prompt_token_growth,
+            max_seconds=max_prompt_repair_seconds,
+        )
+        # Base context from issue/PR content (oracle enrichment)
+        issue_context: Dict[str, str] = {}
+        if raw_full_content.strip():
+            issue_context["issue"] = raw_full_content
+        if pr_url and pr_owner and pr_repo and pr_number is not None:
+            issue_context["pr"] = _fetch_pr_context(pr_owner, pr_repo, pr_number)
+
+        strict_failures: List[str] = []
+        work_cwd = cwd if cwd is not None else Path.cwd()
+        # Forward strictness so warnings are treated as errors consistently in
+        # all three phases (initial check, repair loop re-checks, post-repair
+        # check).  Mirrors the commands/checkup.py path which passes strict=strict.
+        is_strict = prompt_repair == "strict"
+        for prompt_path in discover_prompt_paths(work_cwd):
+            # Step 1: run the full structured checkup to decide if repair is needed
+            src_report = build_prompt_source_set_report(
+                prompt_path,
+                target=str(prompt_path),
+                project_root=project_root,
+                strict=is_strict,
+            )
+            if src_report.status == "pass":
+                continue  # no repair needed for this prompt
+            # Step 2: repair using the structured report + issue context as oracle
+            repair_context = dict(issue_context)
+            repair_context["source_set_report"] = json.dumps(src_report.as_dict(), indent=2)
+            repair_context["recommended_actions"] = "\n".join(src_report.recommended_actions())
+            repair_result = run_prompt_repair_loop(
+                prompt_path,
+                repair_config,
+                context=repair_context,
+                cwd=project_root,
+                verbose=verbose,
+                quiet=quiet,
+                strict=is_strict,
+            )
+            summary = format_token_delta_summary(repair_result)
+            if summary:
+                logger.info("%s: %s", prompt_path, summary.replace("\n", "; "))
+                if not quiet:
+                    console.print(f"[cyan]{summary}[/cyan]")
+            # Step 3: re-check with the structured report after repair
+            post_report = build_prompt_source_set_report(
+                prompt_path,
+                target=str(prompt_path),
+                project_root=project_root,
+                strict=is_strict,
+            )
+            if post_report.status != "pass" and prompt_repair == "strict":
+                strict_failures.append(str(prompt_path))
+            elif post_report.status != "pass":
+                logger.warning(
+                    "Prompt repair left issues in %s: %s",
+                    prompt_path,
+                    ", ".join(f.code for f in post_report.findings),
+                )
+
+        if strict_failures:
+            paths = ", ".join(strict_failures)
+            return (
+                False,
+                f"Prompt repair strict mode: unresolved issues in {paths}",
+                0.0,
+                "",
+            )
+
     # Layer 2 (review-loop) runner, shared by ``--review-loop`` (Layer 2 only)
     # and the canonical ``--final-gate`` (Layer 1 then Layer 2). Defined as a
     # closure so it captures the already-fetched issue/PR context instead of

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/pdd/checkup_gates.py

@@ -3313,14 +3313,6 @@ _DOC_CONTRACT_CONFIG_PATHS: Tuple[str, ...] = (
     ".pdd/doc_contract.json",
     ".pdd/doc-contract.json",
 )
-_STORY_PROMPTS_METADATA_RE = re.compile(
-    r"<!--\s*pdd-story-prompts:\s*(?P<prompts>.*?)\s*-->",
-    flags=re.IGNORECASE,
-)
-_STORY_PROMPT_REFERENCE_RE = re.compile(
-    r"(?P<ref>[A-Za-z0-9_./-]+\.prompt)\b",
-    flags=re.IGNORECASE,
-)
 
 
 def _git_show_doc_contract_text(
@@ -3610,67 +3602,6 @@ def _doc_contract_should_scan_added_file(file_path: str) -> bool:
     return True
 
 
-def _doc_contract_should_require_prompt_story(file_path: str, lines: List[str]) -> bool:
-    """Return True when a changed prompt should be covered by a user story."""
-    normalized = file_path.replace("\\", "/")
-    return (
-        bool(lines)
-        and normalized.endswith(".prompt")
-        and not normalized.lower().endswith("_llm.prompt")
-        and _doc_contract_should_scan_added_file(normalized)
-    )
-
-
-def _prompt_story_reference_candidates(prompt_path: str) -> Set[str]:
-    """Return story-link spellings that can identify ``prompt_path``."""
-    normalized = prompt_path.replace("\\", "/").strip("/")
-    candidates = {normalized, Path(normalized).name}
-    parts = normalized.split("/")
-    if "prompts" in parts:
-        idx = len(parts) - 1 - list(reversed(parts)).index("prompts")
-        rel_from_prompts = "/".join(parts[idx + 1:])
-        if rel_from_prompts:
-            candidates.add(rel_from_prompts)
-    return {candidate.lower() for candidate in candidates if candidate}
-
-
-def _story_prompt_refs(story_content: str) -> Set[str]:
-    """Extract prompt refs from story metadata and prose."""
-    refs: Set[str] = set()
-    metadata = _STORY_PROMPTS_METADATA_RE.search(story_content)
-    if metadata:
-        for entry in metadata.group("prompts").split(","):
-            entry = entry.strip()
-            if entry:
-                refs.add(entry.replace("\\", "/").lower())
-    for match in _STORY_PROMPT_REFERENCE_RE.finditer(story_content):
-        refs.add(match.group("ref").replace("\\", "/").lower())
-    return refs
-
-
-def _prompt_has_story_coverage(worktree: Path, prompt_path: str) -> bool:
-    """Return True when a user story links to ``prompt_path``.
-
-    This is the deterministic bridge for issue #560: changed prompts must have
-    a story-test artifact. The LLM-backed `pdd detect --stories` command remains
-    the executable prompt test; this gate enforces that the test exists.
-    """
-    story_paths = sorted(worktree.rglob("user_stories/story__*.md"))
-    if not story_paths:
-        return False
-    candidates = _prompt_story_reference_candidates(prompt_path)
-    for story_path in story_paths:
-        if not story_path.is_file():
-            continue
-        try:
-            refs = _story_prompt_refs(story_path.read_text(encoding="utf-8"))
-        except (OSError, UnicodeDecodeError):
-            continue
-        if candidates & refs:
-            return True
-    return False
-
-
 def _condition_doc_tokens(cond: str) -> List[str]:
     """Return the documentation spellings that satisfy a skip condition.
 
@@ -3824,7 +3755,6 @@ def run_doc_contract_check(
     # undocumented. The condition is normalized to its snake_case identifier.
     added_skip_contracts: set = set()
     added_env_vars = set()
-    changed_prompt_files = set()
 
     # .pddrc keys
     pddrc_keys_now = set()
@@ -3862,9 +3792,6 @@ def run_doc_contract_check(
 
     # Click options, Skip behaviors, and Env vars
     for file_path, lines in added_lines_by_file.items():
-        normalized_file = file_path.replace("\\", "/")
-        if _doc_contract_should_require_prompt_story(normalized_file, lines):
-            changed_prompt_files.add(normalized_file)
         if not _doc_contract_should_scan_added_file(file_path):
             continue
         if file_path.endswith(".py"):
@@ -4006,15 +3933,6 @@ def run_doc_contract_check(
                 f"Environment variable '{env}' is not documented in README.md under 'Environment Variables' section."
             )
 
-    for prompt_path in sorted(changed_prompt_files):
-        if not _prompt_has_story_coverage(worktree, prompt_path):
-            errors.append(
-                f"Prompt '{prompt_path}' changed but is not covered by any "
-                "user_stories/story__*.md file. Add or update a user story with "
-                "pdd-story-prompts metadata so `pdd detect --stories` can test "
-                "the prompt."
-            )
-
     if errors:
         for err in errors:
             print(f"Doc Contract Failure: {err}", file=sys.stderr)

{pdd_cli-0.0.264 → pdd_cli-0.0.265}/pdd/checkup_prompt_main.py

@@ -17,6 +17,7 @@ from .coverage_contracts import (
     CoverageResult,
     build_coverage,
 )
+from .construct_paths import _strip_language_suffix
 from .gate_main import GateResult, run_gate_policy
 from .prompt_lint import LintResult, scan_prompt
 from .source_set_model import resolve_prompt_targets
@@ -150,12 +151,12 @@ class PromptSourceSetReport:
                 )
         if self.gate and not self.gate.passed:
             actions.append(
-                f"pdd checkup gate {self.prompt_path.stem.removesuffix('_python')}"
+                f"pdd checkup gate {_strip_language_suffix(self.prompt_path)}"
             )
         if any(finding.source_check == "snapshot" for finding in self.findings):
             actions.append(f"pdd checkup snapshot {_display_path(self.prompt_path)}")
         if any(finding.source_check == "drift" for finding in self.findings):
-            basename = self.prompt_path.stem.removesuffix("_python")
+            basename = _strip_language_suffix(self.prompt_path)
             actions.append(f"pdd checkup drift {basename}")
         if not actions:
             actions.append("Source set looks ready to generate from.")
@@ -326,9 +327,7 @@ def build_prompt_source_set_report(
                 )
         _record_check(report, "coverage", status=coverage_status)
 
-    basename = prompt_path.stem
-    if basename.endswith("_python"):
-        basename = basename[: -len("_python")]
+    basename = _strip_language_suffix(prompt_path)
 
     from .evidence_store import devunits_dir, resolve_prompt_path
 
@@ -340,15 +339,33 @@ def build_prompt_source_set_report(
     )
 
     if latest_manifest.is_file():
-        report.gate = run_gate_policy(
-            root,
-            target=basename,
-            stories_dir=stories_dir,
-            tests_dir=tests_dir,
-        )
-        gate_status = "pass" if report.gate.passed else "fail"
-        _record_check(report, "gate", status=gate_status)
-        for index, failure in enumerate(report.gate.failures):
+        try:
+            report.gate = run_gate_policy(
+                root,
+                target=basename,
+                stories_dir=stories_dir,
+                tests_dir=tests_dir,
+            )
+        except (ValueError, OSError) as exc:
+            logger.warning("Gate policy check failed for %s: %s", basename, exc)
+            _record_check(report, "gate", status="fail")
+            report.findings.append(
+                SourceSetFinding(
+                    finding_id=_finding_id("gate", prompt_path, 0, "gate_error"),
+                    source_check="gate",
+                    severity="error",
+                    file=prompt_path,
+                    message=f"Gate check failed (manifest may be corrupt): {exc}",
+                    recommended_action="Re-capture evidence or delete the corrupt manifest.",
+                    fix_command=f"pdd --evidence generate {basename}",
+                    code="gate_error",
+                )
+            )
+            report.gate = None
+        if report.gate is not None:
+            gate_status = "pass" if report.gate.passed else "fail"
+            _record_check(report, "gate", status=gate_status)
+        for index, failure in enumerate((report.gate.failures if report.gate else [])):
             severity = "error"
             report.findings.append(
                 SourceSetFinding(