Bump version

Author: gltanaka

.pddrc

@@ -104,12 +104,12 @@ contexts:
   pdd_cli:
     paths: ["pdd/**", "*.py", "prompts/**", "tests/**"]
     defaults:
-      generate_output_path: "pdd/"
-      test_output_path: "tests/"
-      example_output_path: "context/"
+      generate_output_path: "pdd"
+      test_output_path: "tests"
+      example_output_path: "context"
       default_language: "python"
       target_coverage: 80.0
       strength: 1
       temperature: 0.0
       budget: 10.0
-      max_attempts: 3
+      max_attempts: 3

CHANGELOG.md

@@ -1,12 +1,44 @@
+## v0.0.101 (2026-01-03)
+
+### Feat
+
+- Enhance agentic bug investigation prompts and regression testing
+- Enhance agentic bug investigation workflow and testing
+- Implement agentic bug investigation workflow with orchestrator
+- Add agentic bug workflow with 8-step GitHub issue investigation (#153)
+- add ONBOARDING.md to sync patterns
+- Introduce sync configuration for bidirectional repository synchronization
+- Enhance cloud execution support for `pdd crash` and `pdd verify` commands
+
+### Fix
+
+- Improve error handling in analysis commands
+- Refactor output handling in analysis_example.py
+- Enhance analysis command examples and output handling
+- Update analysis prompts to include function namespaces
+- escape tag examples in preprocess_python.prompt (from pdd_cap PR #11)
+- remove root ONBOARDING.md from sync (use docs/*.md instead)
+- update Firecrawl API for 4.0+ compatibility
+- use git config for CAP_REPO_TOKEN auth
+
 ## v0.0.100 (2026-01-02)
 
 ### Feat
 
-- Add cloud execution support for pdd crash and pdd verify commands
+- **Cloud Execution for `pdd crash` and `pdd verify` Commands (PR #218):** Added cloud-first execution with automatic local fallback for both commands. Uses JWT authentication via `CloudConfig.get_jwt_token()` and posts to the `crashCode` and `verifyCode` endpoints. Supports hybrid mode for loop iterations—local program execution with cloud LLM calls. Set `PDD_CLOUD_ONLY=1` or `PDD_NO_LOCAL_FALLBACK=1` to disable fallback. Non-recoverable errors (401/402/403/400) raise `UsageError`; recoverable errors (5xx, timeouts) fall back to local.
+
+### Docs
+
+- Updated `crash_main_python.prompt` and `fix_verification_main_python.prompt` with cloud execution strategy documentation.
+
+### Tests
+
+- Added 374+ lines of tests in `test_crash_main.py` covering cloud success paths, fallback scenarios, and hybrid loop mode.
+- Added 221+ lines of tests in `test_fix_main.py` for cloud execution coverage.
 
 ### Fix
 
-- Address valid Copilot suggestions - fix patch target and remove outdated comment
+- Fixed patch target in test mocking and removed outdated comment.
 
 ## v0.0.99 (2026-01-01)
 

Makefile

@@ -64,11 +64,11 @@ PUBLIC_PDD_REMOTE ?= https://github.com/promptdriven/pdd.git
 # CAP public repo (optional second destination)
 PUBLIC_PDD_CAP_REPO_DIR ?= staging/public/pdd_cap
 PUBLIC_PDD_CAP_REMOTE ?= https://github.com/promptdriven/pdd_cap.git
-# Top-level files to publish if present
-PUBLIC_ROOT_FILES ?= LICENSE CHANGELOG.md CONTRIBUTING.md requirements.txt pyproject.toml .env.example README.md .gitignore SETUP_WITH_GEMINI.md Makefile pdd-local.sh .pddrc
+# Top-level files to publish if present (read from .sync-config.yml)
+PUBLIC_ROOT_FILES ?= $(shell python scripts/get_sync_patterns.py root_files 2>/dev/null || echo "LICENSE README.md requirements.txt pyproject.toml")
 # Include core unit tests by default
 PUBLIC_COPY_TESTS ?= 1
-PUBLIC_TEST_INCLUDE ?= tests/test_*.py tests/__init__.py tests/conftest.py
+PUBLIC_TEST_INCLUDE ?= $(shell python scripts/get_sync_patterns.py test_patterns 2>/dev/null || echo "tests/test_*.py tests/__init__.py tests/conftest.py")
 PUBLIC_TEST_EXCLUDE ?= tests/regression* tests/sync_regression* tests/**/regression* tests/**/sync_regression* tests/**/*.ipynb tests/csv/**
 PUBLIC_COPY_CONTEXT ?= 1
 PUBLIC_CONTEXT_INCLUDE ?= context/**/*_example.py
@@ -846,6 +846,9 @@ publish-public-cap:
 	@echo "Copying VS Code extension to CAP public repo"
 	@mkdir -p $(PUBLIC_PDD_CAP_REPO_DIR)/utils
 	@cp -r ./utils/vscode_prompt $(PUBLIC_PDD_CAP_REPO_DIR)/utils/
+	@echo "Copying python preamble to CAP public repo"
+	@mkdir -p $(PUBLIC_PDD_CAP_REPO_DIR)/context
+	@cp context/python_preamble.prompt $(PUBLIC_PDD_CAP_REPO_DIR)/context/
 	@echo "Copying selected top-level files to CAP public repo (if present): $(PUBLIC_ROOT_FILES)"
 	@set -e; for f in $(PUBLIC_ROOT_FILES); do \
 		if [ -f "$$f" ]; then \

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.100-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.101-blue) [![Discord](https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord&logoColor=white)](https://discord.gg/Yp4RTh8bG7)
 
 ## Introduction
 
@@ -285,7 +285,7 @@ export PDD_TEST_OUTPUT_PATH=/path/to/tests/
 
 ## Version
 
-Current version: 0.0.100
+Current version: 0.0.101
 
 To check your installed version, run:
 ```
@@ -458,7 +458,7 @@ Here is a brief overview of the main commands provided by PDD. Click the command
 - **[`conflicts`](#11-conflicts)**: Finds and suggests resolutions for conflicts between two prompt files.
 - **[`crash`](#12-crash)**: Fixes errors in a code module and its calling program that caused a crash. Includes an agentic fallback mode for complex errors.
 - **[`trace`](#13-trace)**: Finds the corresponding line number in a prompt file for a given code line.
-- **[`bug`](#14-bug)**: Generates a unit test based on observed vs. desired program outputs.
+- **[`bug`](#14-bug)**: Generates a unit test from a GitHub issue via an agentic workflow that analyzes, reproduces, and creates failing tests.
 - **[`auto-deps`](#15-auto-deps)**: Analyzes and inserts needed dependencies into a prompt file.
 - **[`verify`](#16-verify)**: Verifies functional correctness by running a program and judging its output against the prompt's intent using an LLM.
 
@@ -1395,7 +1395,7 @@ Options:
 
 #### XML-like Tags
 
-PDD supports the following XML-like tags in prompt files:
+PDD supports the following XML-like tags in prompt files. Note: XML-like tags (`<include>`, `<include-many>`, `<shell>`, `<web>`) are left untouched inside fenced code blocks (``` or ~~~) or inline single backticks so documentation examples remain literal.
 
 1. **`include`**: Includes the content of the specified file in the prompt. The tag is replaced directly with the file content.
    ```xml
@@ -1802,26 +1802,46 @@ This will print out the line number in the prompt file for the associated the co
 
 ### 14. bug
 
-Generate a unit test based on observed and desired outputs, given the original prompt and code.
+Generate a unit test from a GitHub issue. The issue serves as the source of truth for both the error output and expected behavior. An agentic workflow analyzes the issue, reproduces the bug, and creates a failing test.
 
 ```
-pdd [GLOBAL OPTIONS] bug [OPTIONS] PROMPT_FILE CODE_FILE PROGRAM_FILE CURRENT_OUTPUT_FILE DESIRED_OUTPUT_FILE
+pdd [GLOBAL OPTIONS] bug <github-issue-url>
+pdd [GLOBAL OPTIONS] bug --manual PROMPT_FILE CODE_FILE PROGRAM_FILE CURRENT_OUTPUT DESIRED_OUTPUT
 ```
 
+**How it works (step-by-step with GitHub comments):**
+
+1. **Duplicate check** - Search for existing issues describing the same problem. If found, merge content and close the duplicate. Posts comment with findings.
+
+2. **Documentation check** - Review repo documentation to determine if this is a bug or user error. Posts comment with findings.
+
+3. **Reproduce** - Attempt to reproduce the issue locally. Posts comment confirming reproduction (or failure to reproduce).
+
+4. **Root cause analysis** - Run experiments to identify the root cause. Posts comment explaining the root cause.
+
+5. **Test plan** - Design a plan for creating tests to detect the problem. Posts comment with the test plan.
+
+6. **Generate test** - Create the failing unit test. Posts comment with the generated test code.
+
+7. **Verify detection** - Confirm the test successfully detects the bug. Posts comment confirming verification.
+
+8. **Create draft PR** - Create a draft pull request with the failing test and link it to the issue. Posts comment with PR link.
+
 Arguments:
-- `PROMPT_FILE`: Filename of the prompt file that generated the code.
-- `CODE_FILE`: Filename of the code file being tested.
-- `PROGRAM_FILE`: Filename of the program used to run the code under test.
-- `CURRENT_OUTPUT_FILE`: File containing the current (incorrect) output of the program.
-- `DESIRED_OUTPUT_FILE`: File containing the desired (correct) output of the program.
+- `ISSUE_URL`: GitHub issue URL (e.g., https://github.com/owner/repo/issues/123)
 
 Options:
-- `--output LOCATION`: Specify where to save the generated unit test. The default file name is `test_<basename>_bug.<language_extension>`. If an output file with the specified name already exists, a new file with a numbered suffix (e.g., `test_calculator_bug_1.py`) will be created instead of overwriting.
-- `--language`: Specify the programming language for the unit test (default is "Python").
+- `--manual`: Use legacy mode with explicit file arguments (PROMPT_FILE, CODE_FILE, PROGRAM_FILE, CURRENT_OUTPUT, DESIRED_OUTPUT)
+- `--output LOCATION`: Specify where to save the generated unit test. Default: `test_<module>_bug.py`
+- `--language LANG`: Specify the programming language for the unit test (default is "Python").
 
 Example:
-```
-pdd [GLOBAL OPTIONS] bug --output tests/test_factorial_calculator_bug.py factorial_calculator_python.prompt src/factorial_calculator.py main_program.py current_output.txt desired_output.txt
+```bash
+# Agentic mode (recommended)
+pdd bug https://github.com/myorg/myrepo/issues/42
+
+# Manual mode (legacy)
+pdd bug --manual prompt.prompt code.py main.py current.txt desired.txt
 ```
 
 ### 15. auto-deps
@@ -2014,6 +2034,10 @@ PDD automatically detects the appropriate context based on:
 - `budget`: Default budget for iterative commands
 - `max_attempts`: Default maximum attempts for fixing operations
 
+**Path Behavior**:
+- Paths ending with `/` are treated as explicit directories and do **not** preserve subdirectory basenames (e.g., `commands/analysis` -> `pdd/analysis.py`).
+- Paths without trailing `/` preserve subdirectory basenames when the path is an existing directory (e.g., `commands/analysis` -> `pdd/commands/analysis.py`).
+
 **Usage Examples**:
 ```bash
 # Auto-detect context from current directory

context/agentic_bug_example.py

@@ -0,0 +1,52 @@
+"""Example showing how to use run_agentic_bug for GitHub issue-based bug investigation."""
+
+import sys
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+# Add the project root to sys.path
+project_root = Path(__file__).resolve().parent.parent
+sys.path.append(str(project_root))
+
+from pdd.agentic_bug import run_agentic_bug
+
+
+def main():
+    """Demonstrate the agentic bug workflow with a mocked GitHub issue."""
+
+    # Example GitHub issue URL
+    issue_url = "https://github.com/example/repo/issues/42"
+
+    print(f"Running agentic bug investigation for: {issue_url}")
+    print("-" * 60)
+
+    # Mock the agentic task execution to avoid real API calls
+    with patch("pdd.agentic_bug.run_agentic_bug_orchestrator") as mock_orchestrator:
+        # Simulate successful 8-step workflow
+        mock_orchestrator.return_value = (
+            True,  # success
+            "Investigation complete. Created test_calculator_bug.py",  # message
+            2.50,  # total_cost across all 8 steps
+            "anthropic",  # model/provider used
+            ["tests/test_calculator_bug.py"]  # changed_files
+        )
+
+        # --- EXECUTE THE MODULE ---
+        success, message, cost, model, changed_files = run_agentic_bug(
+            issue_url=issue_url,
+            verbose=True,
+            quiet=False
+        )
+
+    # Output the results
+    print("\n--- Result Summary ---")
+    print(f"Success       : {success}")
+    print(f"Model Used    : {model}")
+    print(f"Cost          : ${cost:.2f}")
+    print(f"Changed Files : {changed_files}")
+    print("-" * 30)
+    print(f"Message       : {message}")
+
+
+if __name__ == "__main__":
+    main()

context/agentic_bug_orchestrator_example.py

@@ -0,0 +1,120 @@
+"""
+Example usage of the agentic_bug_orchestrator module.
+
+This script demonstrates how to invoke the `run_agentic_bug_orchestrator` function.
+Since the orchestrator relies on internal modules like `run_agentic_task` and `load_prompt_template`,
+this example mocks those dependencies to simulate a successful bug investigation workflow
+without making actual LLM calls or requiring a real GitHub issue.
+
+Scenario:
+    We simulate an issue where a user reports a "ZeroDivisionError" in a calculator app.
+    The orchestrator will step through the 9-step process, finding the bug, generating a test,
+    and creating a fix.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+# Ensure the project root is in sys.path so we can import the module
+# Adjust this path based on your actual project structure relative to this script
+project_root = Path(__file__).resolve().parent.parent
+sys.path.append(str(project_root))
+
+try:
+    # Import the module to be tested
+    # Note: We assume the file is at pdd/agentic_bug_orchestrator.py
+    from pdd.agentic_bug_orchestrator import run_agentic_bug_orchestrator
+except ImportError:
+    print("Error: Could not import 'pdd.agentic_bug_orchestrator'.")
+    print("Ensure your PYTHONPATH is set correctly or the file structure matches.")
+    sys.exit(1)
+
+
+def mock_load_prompt_template(template_name: str) -> str:
+    """
+    Mock implementation of load_prompt_template.
+    Returns a dummy prompt string based on the requested template name.
+    """
+    return f"MOCK PROMPT FOR: {template_name}\nContext: {{issue_content}}"
+
+
+def mock_run_agentic_task(instruction: str, cwd: Path, verbose: bool, quiet: bool, label: str):
+    """
+    Mock implementation of run_agentic_task.
+    Simulates the output of an LLM agent for each step of the workflow.
+    """
+    step_num = label.replace("step", "")
+    
+    # Default return values
+    success = True
+    cost = 0.15  # Simulated cost per step
+    provider = "gpt-4-mock"
+    files = []
+    output = ""
+
+    if step_num == "1":
+        output = "No duplicate issues found. Proceeding."
+    elif step_num == "2":
+        output = "Checked documentation. This behavior is not documented, likely a bug."
+    elif step_num == "3":
+        output = "Sufficient information provided in the issue description."
+    elif step_num == "4":
+        output = "Successfully reproduced the ZeroDivisionError with input (10, 0)."
+    elif step_num == "5":
+        output = "Root cause identified: 'divide' function lacks check for denominator == 0."
+    elif step_num == "6":
+        output = "Plan: Create a test case 'test_divide_zero' asserting ValueError is raised."
+    elif step_num == "7":
+        output = "Generated file 'tests/test_calculator_bug.py'."
+        files = ["tests/test_calculator_bug.py"]
+    elif step_num == "8":
+        output = "Verification successful: The new test fails as expected against current code."
+    elif step_num == "9":
+        output = "Created draft PR #101 linking to issue #42."
+    else:
+        output = "Unknown step executed."
+
+    return success, output, cost, provider, files
+
+
+def main():
+    """Main function to run the agentic bug orchestrator simulation."""
+    # Define dummy issue data
+    issue_data = {
+        "issue_url": "https://github.com/example/calculator/issues/42",
+        "issue_content": "When I divide by zero, the app crashes instead of raising a clean error.",
+        "repo_owner": "example",
+        "repo_name": "calculator",
+        "issue_number": 42,
+        "issue_author": "bug_hunter_99",
+        "issue_title": "Crash on division by zero",
+        "cwd": Path("./temp_workspace"),
+        "verbose": True,
+        "quiet": False
+    }
+
+    print("Starting Agentic Bug Orchestrator Simulation...")
+    print("-" * 60)
+
+    # Patch the internal dependencies
+    # We patch where they are imported IN the orchestrator module, not where they are defined
+    with patch("pdd.agentic_bug_orchestrator.load_prompt_template", side_effect=mock_load_prompt_template), \
+         patch("pdd.agentic_bug_orchestrator.run_agentic_task", side_effect=mock_run_agentic_task):
+
+        # Run the orchestrator
+        success, final_msg, total_cost, model, changed_files = run_agentic_bug_orchestrator(
+            **issue_data
+        )
+
+    print("-" * 60)
+    print("Simulation Complete.")
+    print(f"Success: {success}")
+    print(f"Final Message: {final_msg}")
+    print(f"Total Cost: ${total_cost:.2f}")
+    print(f"Model Used: {model}")
+    print(f"Changed Files: {changed_files}")
+
+
+if __name__ == "__main__":
+    main()