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

{pdd_cli-0.0.263 → 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.263/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.263
+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.263 → 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
@@ -694,14 +697,15 @@ Commands:
 - `pdd detect --stories` runs the validation suite.
 - `pdd change` runs story validation after prompt modifications and fails if any story fails.
 - `pdd fix user_stories/story__*.md` applies a single story to prompts and re-validates it.
-- `pdd test <prompt_1.prompt> [prompt_2.prompt ...]` generates a `story__*.md` file and links those prompts.
+- `pdd test --issue <url|number|issue.md> <prompt_1.prompt> [prompt_2.prompt ...]` generates a `story__*.md` file from the issue text and links those prompts.
 - `pdd test user_stories/story__*.md` updates prompt links for an existing story file.
 
 Story prompt linkage:
 - Stories may include optional metadata to scope validation to a subset of prompts:
   `<!-- pdd-story-prompts: prompts/a_python.prompt, prompts/b_python.prompt -->`
 - If metadata is missing, `pdd detect --stories` validates against the full prompt set.
-- In `--stories` mode, when `detect` identifies impacted prompts, PDD caches links back into the story metadata for future deterministic runs.
+- `pdd test --issue ... <*.prompt>` links the prompt files passed on the command line directly in story metadata; it does not run `detect_change` during story authoring.
+- In `--stories` mode, existing story metadata scopes validation; when metadata is missing, validation falls back to the full prompt set.
 
 Template:
 - See `user_stories/story__template.md` for a starter format.
@@ -1930,19 +1934,20 @@ When the prompt contains a `contract_rules` section, unit test generation uses t
 
 #### Story Mode
 
-Generate or update user stories and link them to touched prompts.
+Generate issue-derived user stories or update story prompt metadata.
 
 ```
-pdd [GLOBAL OPTIONS] test prompts/upload_python.prompt prompts/notify_python.prompt
+pdd [GLOBAL OPTIONS] test --issue https://github.com/myorg/myrepo/issues/789 prompts/upload_python.prompt prompts/notify_python.prompt
+pdd [GLOBAL OPTIONS] test --issue ./issues/upload.md prompts/upload_python.prompt
 pdd [GLOBAL OPTIONS] test user_stories/story__my_flow.md
 ```
 
 Behavior:
-- If input is one or more `.prompt` files, PDD generates `user_stories/story__<name>.md`.
-- During story generation, PDD runs prompt detection and auto-links touched prompts in `pdd-story-prompts` metadata.
-- If generation-time detection finds no touched prompts, metadata falls back to the provided prompt-file inputs.
-- If `pdd-story-prompts` metadata already exists and resolves cleanly, PDD keeps it unchanged.
-- If metadata is missing (or stale), PDD runs prompt detection and writes:
+- If input is one or more `.prompt` files, `--issue` is required. The issue source can be a GitHub issue/PR URL, an issue number resolvable from the current repo, or a local issue markdown file.
+- PDD resolves the issue first and authors `user_stories/story__<name>.md` from that issue text. Prompt file content is withheld from the story author so the story can catch prompt drift from the issue intent.
+- The prompt files passed on the command line are linked directly in `pdd-story-prompts` metadata. Story generation does not run `detect_change` or auto-detect touched prompts.
+- Missing/unresolvable issue sources or invalid LLM story output fail the command instead of writing a prompt-derived fallback story.
+- `pdd test user_stories/story__*.md` updates metadata for an existing story file. If metadata is missing or stale, PDD runs prompt detection and writes:
   `<!-- pdd-story-prompts: prompt_a_python.prompt, prompt_b_python.prompt -->`
 - This enables deterministic prompt-subset validation in `pdd detect --stories`.
 
@@ -2920,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.263 → pdd_cli-0.0.265}/architecture.json

@@ -470,7 +470,7 @@
     "dependencies": [],
     "priority": 18,
     "filename": "resurface_check_Python.prompt",
-    "filepath": "extensions/recruiting/resurface_check.py",
+    "filepath": "prompts/resurface_check_Python.prompt",
     "tags": [
       "backend",
       "api",
@@ -2865,8 +2865,8 @@
     "description": "Defines the prompt structure for agentic bug step4 reproduce. Invoked by the corresponding Python module to format LLM requests.",
     "dependencies": [],
     "priority": 75,
-    "filename": "agentic_bug_step4_reproduce_LLM.prompt",
-    "filepath": "prompts/agentic_bug_step4_reproduce_LLM.prompt",
+    "filename": "agentic_bug_step5_reproduce_LLM.prompt",
+    "filepath": "prompts/agentic_bug_step5_reproduce_LLM.prompt",
     "tags": [
       "agentic",
       "config",
@@ -2987,8 +2987,8 @@
     "description": "Step 10 (final step) of the agentic bug workflow. Creates a draft pull request with failing tests and links it to the GitHub issue. Includes pdd fix command for resolving the bug.",
     "dependencies": [],
     "priority": 80,
-    "filename": "agentic_bug_step10_pr_LLM.prompt",
-    "filepath": "prompts/agentic_bug_step10_pr_LLM.prompt",
+    "filename": "agentic_bug_step12_pr_LLM.prompt",
+    "filepath": "prompts/agentic_bug_step12_pr_LLM.prompt",
     "tags": [
       "agentic",
       "config",
@@ -3344,30 +3344,6 @@
       "y": 0
     }
   },
-  {
-    "reason": "LLM prompt template for extracting dependency includes from auto-include LLM output.",
-    "description": "Defines the prompt structure for extract auto include. Invoked by the corresponding Python module to format LLM requests.",
-    "dependencies": [],
-    "priority": 95,
-    "filename": "extract_auto_include_LLM.prompt",
-    "filepath": "prompts/extract_auto_include_LLM.prompt",
-    "tags": [
-      "config",
-      "extraction",
-      "llm",
-      "template"
-    ],
-    "interface": {
-      "type": "config",
-      "config": {
-        "keys": []
-      }
-    },
-    "position": {
-      "x": 1800,
-      "y": 0
-    }
-  },
   {
     "reason": "LLM prompt template for extract code operations.",
     "description": "Defines the prompt structure for extract code. Invoked by the corresponding Python module to format LLM requests.",
@@ -3957,7 +3933,7 @@
     "dependencies": [],
     "priority": 119,
     "filename": "pdd_theme_json.prompt",
-    "filepath": "pdd_theme.json",
+    "filepath": "prompts/pdd_theme_json.prompt",
     "tags": [
       "config"
     ],
@@ -4148,7 +4124,7 @@
     "dependencies": [],
     "priority": 124,
     "filename": "regression_analysis_log.prompt",
-    "filepath": "regression_analysis.log",
+    "filepath": "prompts/regression_analysis_log.prompt",
     "tags": [
       "config"
     ],
@@ -4169,7 +4145,7 @@
     "dependencies": [],
     "priority": 125,
     "filename": "regression_bash.prompt",
-    "filepath": "regression.sh",
+    "filepath": "prompts/regression_bash.prompt",
     "tags": [
       "cli",
       "shell"
@@ -4235,7 +4211,7 @@
     "dependencies": [],
     "priority": 127,
     "filename": "run_generated_python.prompt",
-    "filepath": "pdd/run_generated.py",
+    "filepath": "prompts/run_generated_python.prompt",
     "tags": [
       "generation",
       "module",
@@ -4937,7 +4913,7 @@
     "dependencies": [],
     "priority": 143,
     "filename": "prompt_tester_python.prompt",
-    "filepath": "pdd/prompt_tester.py",
+    "filepath": "prompts/prompt_tester_python.prompt",
     "tags": [
       "module",
       "python",
@@ -5395,7 +5371,8 @@
       "context_generator_main_python.prompt",
       "operation_log_python.prompt",
       "template_registry_python.prompt",
-      "track_cost_python.prompt"
+      "track_cost_python.prompt",
+      "user_story_tests_python.prompt"
     ],
     "priority": 234,
     "filename": "commands/generate_python.prompt",
@@ -5416,7 +5393,7 @@
           },
           {
             "name": "test",
-            "description": "Generate or enhance tests through agentic issue mode or manual prompt/code mode."
+            "description": "Generate or enhance unit tests, or generate/link prompt user stories."
           },
           {
             "name": "example",
@@ -5594,8 +5571,8 @@
     "description": "Step 5.5 of the agentic bug workflow. Classifies whether a bug root cause is in the code implementation or in the prompt specification itself.",
     "dependencies": [],
     "priority": 166,
-    "filename": "agentic_bug_step5_5_prompt_classification_LLM.prompt",
-    "filepath": "prompts/agentic_bug_step5_5_prompt_classification_LLM.prompt",
+    "filename": "agentic_bug_step7_prompt_classification_LLM.prompt",
+    "filepath": "prompts/agentic_bug_step7_prompt_classification_LLM.prompt",
     "tags": [
       "agentic",
       "config",
@@ -5618,8 +5595,8 @@
     "description": "Step 9 of the agentic bug workflow. Generates and runs end-to-end tests that verify a bug at the system integration level.",
     "dependencies": [],
     "priority": 167,
-    "filename": "agentic_bug_step9_e2e_test_LLM.prompt",
-    "filepath": "prompts/agentic_bug_step9_e2e_test_LLM.prompt",
+    "filename": "agentic_bug_step11_e2e_test_LLM.prompt",
+    "filepath": "prompts/agentic_bug_step11_e2e_test_LLM.prompt",
     "tags": [
       "agentic",
       "config",
@@ -7357,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",
@@ -7377,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",
@@ -7417,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"
+            ]
           }
         ]
       }
@@ -7546,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"
     ],
@@ -8137,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",
@@ -8259,7 +8256,7 @@
           },
           {
             "name": "getPromptTemplate",
-            "signature": "(name: string, language: string, description?: string)",
+            "signature": "function getPromptTemplate(name: string, language: string, description?: string): string",
             "returns": "string"
           }
         ]
@@ -9046,7 +9043,7 @@
         "functions": [
           {
             "name": "Job",
-            "signature": "(id, command, args, options, status, result, error, cost, ...)",
+            "signature": "dataclass Job(id: str, command: str, args: Dict[str, Any], options: Dict[str, Any], status: JobStatus, result: Optional[Any], error: Optional[str], cost: float, created_at: datetime, started_at: Optional[datetime], completed_at: Optional[datetime], live_stdout: str, live_stderr: str)",
             "returns": "Job"
           },
           {
@@ -9667,7 +9664,7 @@
         "functions": [
           {
             "name": "write_evidence_manifest",
-            "signature": "(*, command: str, prompt_file: Optional[str | Path] = None, output_files: Iterable[str | Path] = (), model: str = \"\", cost_usd: float = 0.0, temperature: Optional[float] = None, validation: Optional[Mapping[str, str]] = None, logs: Optional[Mapping[str, Optional[str]]] = None, basename: Optional[str] = None, project_root: Optional[str | Path] = None, context_snapshot: Optional[Mapping[str, Any]] = None, grounding: Optional[Dict[str, Any]] = None, reviewed: bool = False, compression: Optional[Mapping[str, Any]] = None, agentic_fallback: Optional[Mapping[str, Any]] = None, compress: bool = False) -> Path",
+            "signature": "(*, command: str, prompt_file: Optional[str | Path] = None, output_files: Iterable[str | Path] = (), model: str = \"\", cost_usd: float = 0.0, temperature: Optional[float] = None, validation: Optional[Mapping[str, str]] = None, logs: Optional[Mapping[str, Optional[str]]] = None, basename: Optional[str] = None, project_root: Optional[str | Path] = None, context_snapshot: Optional[Mapping[str, Any]] = None, grounding: Optional[Mapping[str, Any]] = None, reviewed: bool = False, compression: Optional[Mapping[str, Any]] = None, agentic_fallback: Optional[Mapping[str, Any]] = None, compress: bool = False) -> Path",
             "returns": "Path"
           },
           {
@@ -9677,7 +9674,7 @@
           },
           {
             "name": "resolve_generate_output_paths",
-            "signature": "(prompt_file, *, output=None, ...) -> list[str]",
+            "signature": "(prompt_file: str | Path, *, output: Optional[str] = None, context_override: Optional[str] = None, force: bool = True, quiet: bool = True) -> list[str]",
             "returns": "list[str]"
           }
         ]
@@ -9935,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",
@@ -9964,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.265/context/user_story_tests_example.py

@@ -0,0 +1,106 @@
+"""Example for generating and validating PDD user stories."""
+
+import os
+import sys
+from pathlib import Path
+
+from pdd.user_story_tests import (
+    discover_prompt_files,
+    generate_user_story,
+    run_user_story_tests,
+)
+
+# Check for required API key since user story validation requires LLM calls
+api_key = os.environ.get("OPENAI_API_KEY")
+if not api_key:
+    print("OPENAI_API_KEY not set. Set it to run this example.")
+    sys.exit(0)
+
+
+def main():  # pylint: disable=too-many-locals
+    """
+    Example of using the user_story_tests module to generate and validate user stories.
+    """
+    # Setup output directories
+    output_dir = Path("./output")
+    prompts_dir = output_dir / "prompts"
+    stories_dir = output_dir / "user_stories"
+    src_dir = output_dir / "src"
+
+    for directory in [prompts_dir, stories_dir, src_dir]:
+        directory.mkdir(parents=True, exist_ok=True)
+
+    # 1. Create a dummy prompt file and the issue text that should author the story.
+    prompt_path = prompts_dir / "hello_python.prompt"
+    prompt_path.write_text(
+        "# Hello World Prompt\n"
+        "## Covers\n"
+        "- R1: The generated code must print hello world.\n\n"
+        "Write a Python function that prints hello world.",
+        encoding="utf-8",
+    )
+    issue_path = output_dir / "issue.md"
+    issue_path.write_text(
+        "# Issue: Hello command\n\n"
+        "Users need a small command that prints 'hello world' so they can "
+        "confirm the Python runtime is wired correctly.",
+        encoding="utf-8",
+    )
+
+    # 2. Discover prompt files
+    print("Discovering prompt files...")
+    discovered_prompts = discover_prompt_files(str(prompts_dir))
+    print(f"Found prompts: {[p.name for p in discovered_prompts]}\n")
+
+    # 3. Generate a user story based on the issue.
+    # Prompt content is linked as metadata but is not shown to the story author.
+    print("Generating user story...")
+    success, message, cost, model, story_path, linked_refs = generate_user_story(
+        prompt_files=[str(prompt_path)],
+        issue=str(issue_path),
+        stories_dir=str(stories_dir),
+        prompts_dir=str(prompts_dir),
+        strength=0.0,      # Use low strength for faster/cheaper generation if LLM is used
+        temperature=0.0,
+        time=0.25,
+        verbose=True,
+    )
+
+    print(f"Success: {success}")
+    print(f"Message: {message}")
+    print(f"Cost: ${cost:.6f}")
+    print(f"Model: {model}")
+    print(f"Generated Story Path: {story_path}")
+    print(f"Linked Prompts: {linked_refs}\n")
+
+    if not success:
+        print("Skipping validation because story generation failed.")
+        return
+
+    # 4. Run user story validation tests
+    # This checks if the story requires changes to the prompt files.
+    print("Running user story tests...")
+    all_passed, results, total_cost, test_model = run_user_story_tests(
+        prompts_dir=str(prompts_dir),
+        stories_dir=str(stories_dir),
+        strength=0.0,
+        temperature=0.0,
+        time=0.25,
+        verbose=False,
+        quiet=False,
+        fail_fast=False,
+    )
+
+    print(f"\nAll Passed: {all_passed}")
+    print(f"Total Validation Cost: ${total_cost:.6f}")
+    print(f"Model Used: {test_model}")
+    print("Validation Results:")
+    for res in results:
+        print(
+            f" - Story: {res['story']}, Passed: {res['passed']}, "
+            f"Changes Detected: {len(res['changes'])}"
+        )
+
+
+if __name__ == "__main__":
+    main()

pdd_cli-0.0.265/docs/checkup_prompt_quality_gate.md

@@ -0,0 +1,121 @@
+# Prompt checkup quality gate
+
+PDD keeps you in **prompt space** until a prompt source-set is clear, covered,
+evidenced, and ready to generate from. Prompt checkup is the built-in quality
+gate that runs before code generation or change.
+
+## Manual prompt checkup
+
+Inspect any prompt source-set directly:
+
+```bash
+pdd checkup prompts/refund_payment_python.prompt
+pdd checkup prompts/
+pdd checkup refund_payment
+```
+
+These targets run a unified deterministic report that orchestrates existing
+engines:
+
+- `pdd checkup lint`
+- `pdd checkup contract check`
+- `pdd checkup coverage`
+- waiver / evidence readiness via `pdd checkup gate` (plus explicit `waivers` check in the unified report)
+- snapshot policy when nondeterministic tags exist
+- optional drift readiness note when an evidence manifest exists
+
+Focused subcommands remain unchanged for CI and debugging:
+
+```bash
+pdd checkup lint <target>
+pdd checkup contract check <target>
+pdd checkup coverage <target>
+pdd checkup gate <target>
+pdd checkup snapshot <target>
+pdd checkup drift <devunit>
+```
+
+GitHub issue and PR checkup modes are unchanged:
+
+```bash
+pdd checkup https://github.com/org/repo/issues/123
+pdd checkup --pr https://github.com/org/repo/pull/123
+```
+
+## Report schema
+
+Machine-readable output uses `--json` and conforms to
+`pdd.prompt_source_set_report.v1`:
+
+- `status`: `pass`, `warn`, or `fail`
+- `target`: the CLI target string
+- `checks[]`: per-engine status summary
+- `findings[]`: deterministic findings with `id`, `source_check`, `severity`,
+  `file`, `line`, `message`, `recommended_action`, and `fix_command`
+- `actions[]`: suggested next commands
+- `deterministic_exit_code`: 0 clean, 1 warnings, 2 errors (or strict warnings)
+
+`--strict` affects deterministic exit codes only (warnings become failures in
+strict mode, including automatic `--prompt-checkup strict`). `--explain` prints a
+read-only finding summary and never changes the exit code.
+
+## Workflow hook interface
+
+Automatic prompt checkup is invoked through `maybe_run_workflow_prompt_gate()` in
+`pdd/prompt_gate.py`. Current hook points:
+
+- `pdd generate` agentic and incremental PRD paths (after prompt files are written)
+- `pdd change` manual path (`change_main`, after prompt saves)
+- `pdd change` agentic issue path (`modify`, after `run_agentic_change`)
+
+Future prompt-sync workflows should call the same helper with the list of
+touched `.prompt` paths and honor `--prompt-checkup` / `--no-prompt-checkup`.
+
+## Automatic gate
+
+When PDD creates or modifies `.prompt` files during generate or change, prompt
+checkup can run automatically on the touched files only.
+
+Modes:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | No automatic checkup |
+| `warn` (default) | Report issues; do not block downstream work |
+| `strict` | Block code generation / change on deterministic failure (errors; warnings too when strict evaluation is active) |
+
+CLI:
+
+```bash
+pdd generate ... --prompt-checkup warn
+pdd generate ... --prompt-checkup strict
+pdd generate ... --no-prompt-checkup
+
+pdd change ... --prompt-checkup warn
+pdd change ... --prompt-checkup strict
+```
+
+Config (`.pddrc`, preferred):
+
+```yaml
+checkup:
+  prompt_gate: warn   # off | warn | strict
+```
+
+Fallback (`pyproject.toml`):
+
+```toml
+[tool.pdd.checkup]
+prompt_gate = "warn"   # off | warn | strict
+```
+
+CLI flags override config.
+
+Workflows with no `.prompt` changes are unaffected.
+
+## Related docs
+
+- [checkup_verifier.md](checkup_verifier.md) — verifier namespace overview
+- [prompt_lint.md](prompt_lint.md)
+- [coverage_contracts.md](coverage_contracts.md)
+- [evidence_manifest.md](evidence_manifest.md)