galangal-orchestrate 0.6.0__tar.gz → 0.12.1__tar.gz

{galangal_orchestrate-0.6.0 → galangal_orchestrate-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: galangal-orchestrate
-Version: 0.6.0
+Version: 0.12.1
 Summary: AI-driven development workflow orchestrator
 Project-URL: Homepage, https://github.com/Galangal-Media/galangal-orchestrate
 Project-URL: Repository, https://github.com/Galangal-Media/galangal-orchestrate
@@ -97,7 +97,7 @@ galangal status
 | **PREFLIGHT** | Environment validation | PREFLIGHT_REPORT.md |
 | **DEV** | Implementation | Code changes |
 | **MIGRATION*** | Database migration checks | MIGRATION_REPORT.md |
-| **TEST** | Test implementation | TEST_PLAN.md |
+| **TEST** | Test implementation | TEST_PLAN.md, TEST_SUMMARY.md |
 | **CONTRACT*** | API contract validation | CONTRACT_REPORT.md |
 | **QA** | Quality assurance | QA_REPORT.md |
 | **BENCHMARK*** | Performance validation | BENCHMARK_REPORT.md |
@@ -107,6 +107,15 @@ galangal status
 
 *Conditional stages - skipped automatically if not relevant
 
+### Validation Artifacts
+
+When validation commands run (tests, linters, etc.), Galangal creates debugging artifacts:
+
+- **VALIDATION_REPORT.md** - Full output from all validation commands, useful for debugging failures
+- **TEST_SUMMARY.md** - Concise test results (pass/fail counts, failed test names, coverage) included in downstream stage prompts
+
+These artifacts help you understand what failed without digging through logs, and give downstream stages (QA, REVIEW) context about test results without bloating prompts with verbose output.
+
 ## Task Types
 
 Choose the right workflow for your task:
@@ -167,6 +176,32 @@ After analyzing your task, the PM stage outputs a `STAGE_PLAN.md` recommending w
 
 The progress bar updates dynamically to show only relevant stages.
 
+### Workflow Preview
+
+After PM approval, you'll see a preview showing exactly which stages will run and why others are skipped:
+
+```
+Workflow Preview
+
+Stages to run:
+  PM → DESIGN → PREFLIGHT → DEV → TEST → QA → REVIEW → DOCS
+
+Skipping:
+  MIGRATION (no files match: **/migrations/*)
+  CONTRACT (no files match: **/api/*, **/openapi.*)
+  BENCHMARK (task type: bug_fix)
+  SECURITY (PM: simple UI change, no security impact)
+
+Controls during execution:
+  ^N Skip stage  ^B Back  ^E Pause for edit  ^I Interrupt
+```
+
+Skip reasons include:
+- **Task type** - Based on the workflow template (e.g., bug fixes skip DESIGN)
+- **Config** - Stages listed in `stages.skip` configuration
+- **PM recommendation** - From STAGE_PLAN.md analysis
+- **skip_if condition** - No changed files match the glob pattern
+
 ## Commands
 
 | Command | Description |
@@ -403,6 +438,9 @@ validation:
       - name: "Integration tests"
         command: "pytest tests/integration"
         optional: true         # Don't fail if integration tests missing
+      # Use array form for paths with spaces or special characters
+      - name: "Task-specific tests"
+        command: ["pytest", "{task_dir}/tests"]  # {task_dir} is substituted
 
   # Contract stage (API compatibility)
   contract:
@@ -458,21 +496,37 @@ ai:
   # Default backend to use
   default: claude
 
-  # Available backends
+  # Available backends with customizable CLI flags
   backends:
     claude:
-      command: claude
-      args:
-        - "-p"
-        - "{prompt}"
+      command: claude          # CLI command to invoke
+      args:                    # Arguments with {placeholder} substitution
         - "--output-format"
         - "stream-json"
         - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"        # Replaced with max_turns value
+        - "--permission-mode"
+        - "acceptEdits"
       max_turns: 200           # Maximum conversation turns per stage
+      read_only: false         # If true, backend cannot write files
+
+    codex:
+      command: codex
+      args:
+        - "exec"
+        - "--full-auto"
+        - "--output-schema"
+        - "{schema_file}"      # Replaced with schema file path
+        - "-o"
+        - "{output_file}"      # Replaced with output file path
+      max_turns: 50
+      read_only: true          # Codex runs in read-only sandbox
 
   # Use different backends for specific stages
   stage_backends:
-    # qa: gemini              # Use Gemini for QA stage (when supported)
+    REVIEW: codex              # Use Codex for code review
+    # QA: gemini               # Use Gemini for QA (when supported)
 
 # =============================================================================
 # DOCUMENTATION CONFIGURATION
@@ -569,6 +623,112 @@ stage_context:
     - Secrets must use environment variables
 ```
 
+## AI Backend Customization
+
+Galangal invokes AI backends (like Claude Code CLI) using configurable commands and arguments. This allows you to customize CLI flags without modifying code.
+
+### Default Behavior
+
+By default, Galangal invokes Claude with:
+```bash
+cat prompt.txt | claude --output-format stream-json --verbose --max-turns 200 --permission-mode acceptEdits
+```
+
+### Customizing CLI Flags
+
+Override any flags in `.galangal/config.yaml`:
+
+```yaml
+ai:
+  backends:
+    claude:
+      command: claude
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"
+        - "--permission-mode"
+        - "acceptEdits"
+        - "--model"              # Add custom flags
+        - "opus"
+      max_turns: 300             # Increase max turns
+```
+
+### Placeholder Reference
+
+Arguments can include placeholders that are substituted at runtime:
+
+| Placeholder | Backend | Description |
+|-------------|---------|-------------|
+| `{max_turns}` | claude | Maximum conversation turns |
+| `{schema_file}` | codex | Path to JSON schema file |
+| `{output_file}` | codex | Path for structured output |
+
+### Common Customizations
+
+**Use a specific model:**
+```yaml
+ai:
+  backends:
+    claude:
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--model"
+        - "sonnet"           # Use Sonnet instead of default
+        - "--max-turns"
+        - "{max_turns}"
+```
+
+**Increase turn limit for complex tasks:**
+```yaml
+ai:
+  backends:
+    claude:
+      max_turns: 500         # Default is 200
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--max-turns"
+        - "{max_turns}"      # Will use 500
+```
+
+**Use different backends per stage:**
+```yaml
+ai:
+  default: claude
+  stage_backends:
+    REVIEW: codex            # Use Codex for code review
+```
+
+### Adding a Custom Backend
+
+Define any CLI tool as a backend:
+
+```yaml
+ai:
+  backends:
+    my-backend:
+      command: my-ai-tool
+      args:
+        - "--prompt-file"
+        - "-"                # Read from stdin
+        - "--json-output"
+      max_turns: 100
+      read_only: true        # Cannot write files directly
+```
+
+Then use it:
+```yaml
+ai:
+  default: my-backend
+  # Or per-stage:
+  stage_backends:
+    QA: my-backend
+```
+
 ## Customizing Prompts
 
 Galangal uses a layered prompt system:
@@ -630,6 +790,45 @@ Create any of these in `.galangal/prompts/`:
 
 ## Troubleshooting
 
+### Debug Mode
+
+When something goes wrong and you need to see what happened:
+
+```bash
+# Enable debug logging (writes to logs/galangal_debug.log)
+galangal --debug start "task description"
+galangal --debug resume
+
+# Alternative: set environment variable
+GALANGAL_DEBUG=1 galangal start "task description"
+```
+
+Debug mode creates two log files:
+- `logs/galangal_debug.log` - Human-readable debug trace with timestamps
+- `logs/galangal.jsonl` - Structured JSON logs for programmatic analysis
+
+**Example debug log:**
+```
+[14:32:15.123] GitHub integration failed: HTTPError: 401 Unauthorized
+[14:32:15.124] Traceback:
+  File "/path/to/start.py", line 138, in task_creation_thread
+    check = ensure_github_ready()
+  ...
+```
+
+### Structured Logging Configuration
+
+Enable structured logging in `.galangal/config.yaml`:
+
+```yaml
+logging:
+  enabled: true        # Enable logging
+  level: debug         # debug, info, warning, error
+  file: logs/galangal.jsonl
+  json_format: true    # JSON for parsing, false for console format
+  console: false       # Also output to stderr
+```
+
 ### Tests Hang at TEST Stage
 
 Test frameworks must run non-interactively. Common issues:
@@ -673,10 +872,50 @@ If the TEST stage keeps retrying instead of rolling back to DEV:
 2. If tests fail due to implementation bugs, the AI should report FAIL (not try to fix the code)
 3. Check that test commands exit with proper exit codes (0 for success, non-zero for failure)
 
+**Note:** As of v0.12.0, when artifact markers are unclear (missing PASS/FAIL), Galangal prompts you to manually approve or reject instead of retrying indefinitely. You'll see the artifact content and can make the decision yourself.
+
 ### "Galangal has not been initialized" Error
 
 Run `galangal init` in your project root before using other commands.
 
+### Task Exits Without Error Message
+
+If a task quits unexpectedly with no visible error:
+
+1. **Enable debug mode** and re-run:
+   ```bash
+   galangal --debug start "your task"
+   ```
+
+2. **Check the debug log** for the actual error:
+   ```bash
+   tail -50 logs/galangal_debug.log
+   ```
+
+3. **Common causes**:
+   - GitHub authentication failed (run `gh auth status`)
+   - Network timeout fetching issues
+   - Missing permissions for the repository
+   - Invalid issue number or no issues with `galangal` label
+
+### GitHub Integration Fails Silently
+
+If `galangal start` from a GitHub issue exits without creating a task:
+
+```bash
+# Check GitHub CLI is working
+gh auth status
+gh repo view
+
+# Try with debug mode
+galangal --debug start --issue 123
+```
+
+Check `logs/galangal_debug.log` for specific errors like:
+- `401 Unauthorized` - Re-authenticate with `gh auth login`
+- `404 Not Found` - Issue doesn't exist or wrong repo
+- `No issues with 'galangal' label` - Add the label to an issue first
+
 ## License
 
 MIT License - see LICENSE file.

{galangal_orchestrate-0.6.0 → galangal_orchestrate-0.12.1}/README.md

@@ -61,7 +61,7 @@ galangal status
 | **PREFLIGHT** | Environment validation | PREFLIGHT_REPORT.md |
 | **DEV** | Implementation | Code changes |
 | **MIGRATION*** | Database migration checks | MIGRATION_REPORT.md |
-| **TEST** | Test implementation | TEST_PLAN.md |
+| **TEST** | Test implementation | TEST_PLAN.md, TEST_SUMMARY.md |
 | **CONTRACT*** | API contract validation | CONTRACT_REPORT.md |
 | **QA** | Quality assurance | QA_REPORT.md |
 | **BENCHMARK*** | Performance validation | BENCHMARK_REPORT.md |
@@ -71,6 +71,15 @@ galangal status
 
 *Conditional stages - skipped automatically if not relevant
 
+### Validation Artifacts
+
+When validation commands run (tests, linters, etc.), Galangal creates debugging artifacts:
+
+- **VALIDATION_REPORT.md** - Full output from all validation commands, useful for debugging failures
+- **TEST_SUMMARY.md** - Concise test results (pass/fail counts, failed test names, coverage) included in downstream stage prompts
+
+These artifacts help you understand what failed without digging through logs, and give downstream stages (QA, REVIEW) context about test results without bloating prompts with verbose output.
+
 ## Task Types
 
 Choose the right workflow for your task:
@@ -131,6 +140,32 @@ After analyzing your task, the PM stage outputs a `STAGE_PLAN.md` recommending w
 
 The progress bar updates dynamically to show only relevant stages.
 
+### Workflow Preview
+
+After PM approval, you'll see a preview showing exactly which stages will run and why others are skipped:
+
+```
+Workflow Preview
+
+Stages to run:
+  PM → DESIGN → PREFLIGHT → DEV → TEST → QA → REVIEW → DOCS
+
+Skipping:
+  MIGRATION (no files match: **/migrations/*)
+  CONTRACT (no files match: **/api/*, **/openapi.*)
+  BENCHMARK (task type: bug_fix)
+  SECURITY (PM: simple UI change, no security impact)
+
+Controls during execution:
+  ^N Skip stage  ^B Back  ^E Pause for edit  ^I Interrupt
+```
+
+Skip reasons include:
+- **Task type** - Based on the workflow template (e.g., bug fixes skip DESIGN)
+- **Config** - Stages listed in `stages.skip` configuration
+- **PM recommendation** - From STAGE_PLAN.md analysis
+- **skip_if condition** - No changed files match the glob pattern
+
 ## Commands
 
 | Command | Description |
@@ -367,6 +402,9 @@ validation:
       - name: "Integration tests"
         command: "pytest tests/integration"
         optional: true         # Don't fail if integration tests missing
+      # Use array form for paths with spaces or special characters
+      - name: "Task-specific tests"
+        command: ["pytest", "{task_dir}/tests"]  # {task_dir} is substituted
 
   # Contract stage (API compatibility)
   contract:
@@ -422,21 +460,37 @@ ai:
   # Default backend to use
   default: claude
 
-  # Available backends
+  # Available backends with customizable CLI flags
   backends:
     claude:
-      command: claude
-      args:
-        - "-p"
-        - "{prompt}"
+      command: claude          # CLI command to invoke
+      args:                    # Arguments with {placeholder} substitution
         - "--output-format"
         - "stream-json"
         - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"        # Replaced with max_turns value
+        - "--permission-mode"
+        - "acceptEdits"
       max_turns: 200           # Maximum conversation turns per stage
+      read_only: false         # If true, backend cannot write files
+
+    codex:
+      command: codex
+      args:
+        - "exec"
+        - "--full-auto"
+        - "--output-schema"
+        - "{schema_file}"      # Replaced with schema file path
+        - "-o"
+        - "{output_file}"      # Replaced with output file path
+      max_turns: 50
+      read_only: true          # Codex runs in read-only sandbox
 
   # Use different backends for specific stages
   stage_backends:
-    # qa: gemini              # Use Gemini for QA stage (when supported)
+    REVIEW: codex              # Use Codex for code review
+    # QA: gemini               # Use Gemini for QA (when supported)
 
 # =============================================================================
 # DOCUMENTATION CONFIGURATION
@@ -533,6 +587,112 @@ stage_context:
     - Secrets must use environment variables
 ```
 
+## AI Backend Customization
+
+Galangal invokes AI backends (like Claude Code CLI) using configurable commands and arguments. This allows you to customize CLI flags without modifying code.
+
+### Default Behavior
+
+By default, Galangal invokes Claude with:
+```bash
+cat prompt.txt | claude --output-format stream-json --verbose --max-turns 200 --permission-mode acceptEdits
+```
+
+### Customizing CLI Flags
+
+Override any flags in `.galangal/config.yaml`:
+
+```yaml
+ai:
+  backends:
+    claude:
+      command: claude
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--verbose"
+        - "--max-turns"
+        - "{max_turns}"
+        - "--permission-mode"
+        - "acceptEdits"
+        - "--model"              # Add custom flags
+        - "opus"
+      max_turns: 300             # Increase max turns
+```
+
+### Placeholder Reference
+
+Arguments can include placeholders that are substituted at runtime:
+
+| Placeholder | Backend | Description |
+|-------------|---------|-------------|
+| `{max_turns}` | claude | Maximum conversation turns |
+| `{schema_file}` | codex | Path to JSON schema file |
+| `{output_file}` | codex | Path for structured output |
+
+### Common Customizations
+
+**Use a specific model:**
+```yaml
+ai:
+  backends:
+    claude:
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--model"
+        - "sonnet"           # Use Sonnet instead of default
+        - "--max-turns"
+        - "{max_turns}"
+```
+
+**Increase turn limit for complex tasks:**
+```yaml
+ai:
+  backends:
+    claude:
+      max_turns: 500         # Default is 200
+      args:
+        - "--output-format"
+        - "stream-json"
+        - "--max-turns"
+        - "{max_turns}"      # Will use 500
+```
+
+**Use different backends per stage:**
+```yaml
+ai:
+  default: claude
+  stage_backends:
+    REVIEW: codex            # Use Codex for code review
+```
+
+### Adding a Custom Backend
+
+Define any CLI tool as a backend:
+
+```yaml
+ai:
+  backends:
+    my-backend:
+      command: my-ai-tool
+      args:
+        - "--prompt-file"
+        - "-"                # Read from stdin
+        - "--json-output"
+      max_turns: 100
+      read_only: true        # Cannot write files directly
+```
+
+Then use it:
+```yaml
+ai:
+  default: my-backend
+  # Or per-stage:
+  stage_backends:
+    QA: my-backend
+```
+
 ## Customizing Prompts
 
 Galangal uses a layered prompt system:
@@ -594,6 +754,45 @@ Create any of these in `.galangal/prompts/`:
 
 ## Troubleshooting
 
+### Debug Mode
+
+When something goes wrong and you need to see what happened:
+
+```bash
+# Enable debug logging (writes to logs/galangal_debug.log)
+galangal --debug start "task description"
+galangal --debug resume
+
+# Alternative: set environment variable
+GALANGAL_DEBUG=1 galangal start "task description"
+```
+
+Debug mode creates two log files:
+- `logs/galangal_debug.log` - Human-readable debug trace with timestamps
+- `logs/galangal.jsonl` - Structured JSON logs for programmatic analysis
+
+**Example debug log:**
+```
+[14:32:15.123] GitHub integration failed: HTTPError: 401 Unauthorized
+[14:32:15.124] Traceback:
+  File "/path/to/start.py", line 138, in task_creation_thread
+    check = ensure_github_ready()
+  ...
+```
+
+### Structured Logging Configuration
+
+Enable structured logging in `.galangal/config.yaml`:
+
+```yaml
+logging:
+  enabled: true        # Enable logging
+  level: debug         # debug, info, warning, error
+  file: logs/galangal.jsonl
+  json_format: true    # JSON for parsing, false for console format
+  console: false       # Also output to stderr
+```
+
 ### Tests Hang at TEST Stage
 
 Test frameworks must run non-interactively. Common issues:
@@ -637,10 +836,50 @@ If the TEST stage keeps retrying instead of rolling back to DEV:
 2. If tests fail due to implementation bugs, the AI should report FAIL (not try to fix the code)
 3. Check that test commands exit with proper exit codes (0 for success, non-zero for failure)
 
+**Note:** As of v0.12.0, when artifact markers are unclear (missing PASS/FAIL), Galangal prompts you to manually approve or reject instead of retrying indefinitely. You'll see the artifact content and can make the decision yourself.
+
 ### "Galangal has not been initialized" Error
 
 Run `galangal init` in your project root before using other commands.
 
+### Task Exits Without Error Message
+
+If a task quits unexpectedly with no visible error:
+
+1. **Enable debug mode** and re-run:
+   ```bash
+   galangal --debug start "your task"
+   ```
+
+2. **Check the debug log** for the actual error:
+   ```bash
+   tail -50 logs/galangal_debug.log
+   ```
+
+3. **Common causes**:
+   - GitHub authentication failed (run `gh auth status`)
+   - Network timeout fetching issues
+   - Missing permissions for the repository
+   - Invalid issue number or no issues with `galangal` label
+
+### GitHub Integration Fails Silently
+
+If `galangal start` from a GitHub issue exits without creating a task:
+
+```bash
+# Check GitHub CLI is working
+gh auth status
+gh repo view
+
+# Try with debug mode
+galangal --debug start --issue 123
+```
+
+Check `logs/galangal_debug.log` for specific errors like:
+- `401 Unauthorized` - Re-authenticate with `gh auth login`
+- `404 Not Found` - Issue doesn't exist or wrong repo
+- `No issues with 'galangal' label` - Add the label to an issue first
+
 ## License
 
 MIT License - see LICENSE file.

{galangal_orchestrate-0.6.0 → galangal_orchestrate-0.12.1}/docs/local-development/README.md

@@ -72,6 +72,41 @@ galangal start "my test task" --type bug_fix
 
 This is useful when you want to quickly run a command without activating the environment, or when you have a global install and want to explicitly use the local version.
 
+## Global Install from Local Code
+
+If you want to replace your global pipx install with the local development version (so `galangal` works everywhere without activating a venv):
+
+### Install globally in editable mode
+
+```bash
+# Uninstall the PyPI version first
+pipx uninstall galangal-orchestrate
+
+# Install from local code in editable mode
+pipx install -e /path/to/galangal-orchestrate
+```
+
+Now `galangal` is available globally and uses your local source code. Any changes you make take effect immediately.
+
+### Verify it's using local code
+
+```bash
+# Should show your local path
+pipx list | grep galangal
+
+# Test the CLI
+galangal --help
+```
+
+### Switch back to PyPI version
+
+When you want to go back to the released version:
+
+```bash
+pipx uninstall galangal-orchestrate
+pipx install galangal-orchestrate
+```
+
 ## Testing Changes
 
 ### Using a sandbox directory

{galangal_orchestrate-0.6.0 → galangal_orchestrate-0.12.1}/src/galangal/__init__.py

@@ -19,7 +19,7 @@ from galangal.logging import (
     workflow_logger,
 )
 
-__version__ = "0.6.0"
+__version__ = "0.12.1"
 
 __all__ = [
     # Exceptions