galangal-orchestrate 0.2.11__py3-none-any.whl

galangal/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation system."""
+
+from galangal.validation.runner import ValidationRunner, ValidationResult
+
+__all__ = ["ValidationRunner", "ValidationResult"]

galangal/validation/runner.py

@@ -0,0 +1,395 @@
+"""
+Config-driven validation runner.
+"""
+
+import fnmatch
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from galangal.config.loader import get_project_root, get_config
+from galangal.config.schema import StageValidation, ValidationCommand, PreflightCheck
+from galangal.core.artifacts import artifact_exists, read_artifact, write_artifact
+
+
+@dataclass
+class ValidationResult:
+    """Result of a validation check."""
+
+    success: bool
+    message: str
+    output: Optional[str] = None
+    rollback_to: Optional[str] = None  # Stage to rollback to on failure
+
+
+class ValidationRunner:
+    """Run config-driven validation for stages."""
+
+    def __init__(self):
+        self.config = get_config()
+        self.project_root = get_project_root()
+
+    def validate_stage(
+        self,
+        stage: str,
+        task_name: str,
+    ) -> ValidationResult:
+        """Run validation for a stage based on config."""
+        stage_lower = stage.lower()
+
+        # Get stage validation config
+        validation_config = self.config.validation
+        stage_config: Optional[StageValidation] = getattr(
+            validation_config, stage_lower, None
+        )
+
+        if stage_config is None:
+            # No config for this stage - use defaults
+            return self._validate_with_defaults(stage, task_name)
+
+        # Check skip conditions
+        if stage_config.skip_if:
+            if self._should_skip(stage_config.skip_if, task_name):
+                self._write_skip_artifact(stage, task_name, "Condition met")
+                return ValidationResult(True, f"{stage} skipped (condition met)")
+
+        # SECURITY stage: if checklist says APPROVED, skip validation commands
+        # (the AI has already run scans and documented waivers)
+        if stage_lower == "security":
+            if artifact_exists("SECURITY_CHECKLIST.md", task_name):
+                checklist = read_artifact("SECURITY_CHECKLIST.md", task_name) or ""
+                if "APPROVED" in checklist.upper():
+                    return ValidationResult(True, "Security review approved")
+                if "REJECTED" in checklist.upper() or "BLOCKED" in checklist.upper():
+                    return ValidationResult(
+                        False, "Security review found blocking issues", rollback_to="DEV"
+                    )
+
+        # Run preflight checks (for PREFLIGHT stage)
+        if stage_config.checks:
+            result = self._run_preflight_checks(stage_config.checks, task_name)
+            if not result.success:
+                return result
+
+        # Run validation commands
+        for cmd_config in stage_config.commands:
+            result = self._run_command(cmd_config, task_name, stage_config.timeout)
+            if not result.success:
+                if cmd_config.optional:
+                    continue
+                if cmd_config.allow_failure:
+                    # Log but don't fail
+                    continue
+                return result
+
+        # Check for pass/fail markers in artifacts (for AI-driven stages)
+        if stage_config.artifact and stage_config.pass_marker:
+            result = self._check_artifact_markers(stage_config, task_name)
+            if not result.success:
+                return result
+
+        # Check required artifacts
+        for artifact_name in stage_config.artifacts_required:
+            if not artifact_exists(artifact_name, task_name):
+                return ValidationResult(
+                    False,
+                    f"{artifact_name} not found",
+                    rollback_to="DEV",
+                )
+
+        return ValidationResult(True, f"{stage} validation passed")
+
+    def _should_skip(self, skip_condition, task_name: str) -> bool:
+        """Check if skip condition is met."""
+        if skip_condition.no_files_match:
+            # Check if any files match the glob pattern in git diff
+            try:
+                result = subprocess.run(
+                    ["git", "diff", "--name-only", "main...HEAD"],
+                    cwd=self.project_root,
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+                changed_files = result.stdout.strip().split("\n")
+                pattern = skip_condition.no_files_match
+
+                for f in changed_files:
+                    if fnmatch.fnmatch(f, pattern):
+                        return False  # Found a match, don't skip
+
+                return True  # No matches, skip
+            except Exception:
+                return False  # On error, don't skip
+
+        return False
+
+    def _write_skip_artifact(self, stage: str, task_name: str, reason: str) -> None:
+        """Write a skip marker artifact."""
+        from datetime import datetime, timezone
+
+        content = f"""# {stage} Stage Skipped
+
+Date: {datetime.now(timezone.utc).isoformat()}
+Reason: {reason}
+"""
+        write_artifact(f"{stage.upper()}_SKIP.md", content, task_name)
+
+    def _run_preflight_checks(
+        self, checks: list[PreflightCheck], task_name: str
+    ) -> ValidationResult:
+        """Run preflight environment checks."""
+        from datetime import datetime, timezone
+
+        results: dict[str, dict] = {}
+        all_ok = True
+
+        for check in checks:
+            if check.path_exists:
+                path = self.project_root / check.path_exists
+                exists = path.exists()
+                results[check.name] = {"status": "OK" if exists else "Missing"}
+                if not exists and not check.warn_only:
+                    all_ok = False
+
+            elif check.command:
+                try:
+                    result = subprocess.run(
+                        check.command,
+                        shell=True,
+                        cwd=self.project_root,
+                        capture_output=True,
+                        text=True,
+                        timeout=30,
+                    )
+                    output = result.stdout.strip()
+
+                    if check.expect_empty:
+                        # Filter out task-related files for git status
+                        if output:
+                            filtered = self._filter_task_files(output, task_name)
+                            ok = not filtered
+                        else:
+                            ok = True
+                    else:
+                        ok = result.returncode == 0
+
+                    status = "OK" if ok else ("Warning" if check.warn_only else "Failed")
+                    results[check.name] = {
+                        "status": status,
+                        "output": output[:200] if output else "",
+                    }
+                    if not ok and not check.warn_only:
+                        all_ok = False
+
+                except Exception as e:
+                    results[check.name] = {"status": "Error", "error": str(e)}
+                    if not check.warn_only:
+                        all_ok = False
+
+        # Generate report
+        status = "READY" if all_ok else "NOT_READY"
+        report = f"""# Preflight Report
+
+## Summary
+- **Status:** {status}
+- **Date:** {datetime.now(timezone.utc).isoformat()}
+
+## Checks
+"""
+        for name, result in results.items():
+            status_val = result.get("status", "Unknown")
+            if status_val == "OK":
+                status_icon = "✓"
+            elif status_val == "Warning":
+                status_icon = "⚠"
+            else:
+                status_icon = "✗"
+            report += f"\n### {status_icon} {name}\n"
+            report += f"- Status: {result.get('status', 'Unknown')}\n"
+            if result.get("output"):
+                report += f"- Output: {result['output']}\n"
+            if result.get("error"):
+                report += f"- Error: {result['error']}\n"
+
+        write_artifact("PREFLIGHT_REPORT.md", report, task_name)
+
+        if all_ok:
+            return ValidationResult(True, "Preflight checks passed", output=report)
+        return ValidationResult(
+            False,
+            "Preflight checks failed - fix environment issues",
+            output=report,
+        )
+
+    def _filter_task_files(self, git_status: str, task_name: str) -> str:
+        """Filter out task-related files from git status output."""
+        config = get_config()
+        tasks_dir = config.tasks_dir
+
+        filtered_lines = []
+        for line in git_status.split("\n"):
+            file_path = line[3:] if len(line) > 3 else line
+            # Skip task artifacts directory
+            if file_path.startswith(f"{tasks_dir}/"):
+                continue
+            filtered_lines.append(line)
+
+        return "\n".join(filtered_lines)
+
+    def _run_command(
+        self, cmd_config: ValidationCommand, task_name: str, default_timeout: int
+    ) -> ValidationResult:
+        """Run a single validation command."""
+        command = cmd_config.command.replace("{task_dir}", str(get_project_root() / get_config().tasks_dir / task_name))
+        timeout = cmd_config.timeout if cmd_config.timeout is not None else default_timeout
+
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+
+            if result.returncode == 0:
+                return ValidationResult(
+                    True,
+                    f"{cmd_config.name}: passed",
+                    output=result.stdout,
+                )
+            else:
+                return ValidationResult(
+                    False,
+                    f"{cmd_config.name}: failed",
+                    output=result.stdout + result.stderr,
+                    rollback_to="DEV",
+                )
+
+        except subprocess.TimeoutExpired:
+            return ValidationResult(
+                False,
+                f"{cmd_config.name}: timed out",
+                rollback_to="DEV",
+            )
+        except Exception as e:
+            return ValidationResult(
+                False,
+                f"{cmd_config.name}: error - {e}",
+                rollback_to="DEV",
+            )
+
+    def _check_artifact_markers(
+        self, stage_config: StageValidation, task_name: str
+    ) -> ValidationResult:
+        """Check for pass/fail markers in an artifact."""
+        artifact_name = stage_config.artifact
+        if not artifact_name:
+            return ValidationResult(True, "No artifact to check")
+
+        content = read_artifact(artifact_name, task_name)
+        if not content:
+            return ValidationResult(
+                False,
+                f"{artifact_name} not found or empty",
+                rollback_to="DEV",
+            )
+
+        content_upper = content.upper()
+
+        if stage_config.pass_marker and stage_config.pass_marker in content_upper:
+            return ValidationResult(True, f"{artifact_name}: approved")
+
+        if stage_config.fail_marker and stage_config.fail_marker in content_upper:
+            return ValidationResult(
+                False,
+                f"{artifact_name}: changes requested",
+                rollback_to="DEV",
+            )
+
+        return ValidationResult(
+            False,
+            f"{artifact_name}: unclear result - must contain {stage_config.pass_marker} or {stage_config.fail_marker}",
+        )
+
+    def _validate_with_defaults(
+        self, stage: str, task_name: str
+    ) -> ValidationResult:
+        """Validate using default logic when no config is provided."""
+        stage_upper = stage.upper()
+
+        # PM stage - check for SPEC.md and PLAN.md
+        if stage_upper == "PM":
+            if not artifact_exists("SPEC.md", task_name):
+                return ValidationResult(False, "SPEC.md not found")
+            if not artifact_exists("PLAN.md", task_name):
+                return ValidationResult(False, "PLAN.md not found")
+            return ValidationResult(True, "PM stage validated")
+
+        # DESIGN stage - check for DESIGN.md or skip marker
+        if stage_upper == "DESIGN":
+            if artifact_exists("DESIGN_SKIP.md", task_name):
+                return ValidationResult(True, "Design skipped")
+            if not artifact_exists("DESIGN.md", task_name):
+                return ValidationResult(False, "DESIGN.md not found")
+            return ValidationResult(True, "Design stage validated")
+
+        # DEV stage - just check Claude completed
+        if stage_upper == "DEV":
+            return ValidationResult(True, "DEV stage completed - QA will validate")
+
+        # TEST stage - check for TEST_PLAN.md
+        if stage_upper == "TEST":
+            if not artifact_exists("TEST_PLAN.md", task_name):
+                return ValidationResult(False, "TEST_PLAN.md not found")
+            return ValidationResult(True, "Test stage validated")
+
+        # QA stage - check for QA_REPORT.md
+        if stage_upper == "QA":
+            if not artifact_exists("QA_REPORT.md", task_name):
+                return ValidationResult(False, "QA_REPORT.md not found")
+            report = read_artifact("QA_REPORT.md", task_name) or ""
+            if "PASS" in report.upper() and "FAIL" not in report.upper():
+                return ValidationResult(True, "QA passed")
+            return ValidationResult(False, "QA failed", rollback_to="DEV")
+
+        # SECURITY stage - check for SECURITY_CHECKLIST.md with APPROVED
+        if stage_upper == "SECURITY":
+            if artifact_exists("SECURITY_SKIP.md", task_name):
+                return ValidationResult(True, "Security skipped")
+            if not artifact_exists("SECURITY_CHECKLIST.md", task_name):
+                return ValidationResult(False, "SECURITY_CHECKLIST.md not found")
+            checklist = read_artifact("SECURITY_CHECKLIST.md", task_name) or ""
+            if "APPROVED" in checklist.upper():
+                return ValidationResult(True, "Security review approved")
+            if "REJECTED" in checklist.upper() or "BLOCKED" in checklist.upper():
+                return ValidationResult(
+                    False, "Security review found blocking issues", rollback_to="DEV"
+                )
+            # Checklist exists but no clear marker - pass with warning
+            return ValidationResult(True, "Security checklist created")
+
+        # REVIEW stage - check for REVIEW_NOTES.md with APPROVE
+        if stage_upper == "REVIEW":
+            if not artifact_exists("REVIEW_NOTES.md", task_name):
+                return ValidationResult(False, "REVIEW_NOTES.md not found")
+            notes = read_artifact("REVIEW_NOTES.md", task_name) or ""
+            if "APPROVE" in notes.upper():
+                return ValidationResult(True, "Review approved")
+            if "REQUEST_CHANGES" in notes.upper():
+                return ValidationResult(
+                    False, "Review requested changes", rollback_to="DEV"
+                )
+            return ValidationResult(False, "Review result unclear")
+
+        # DOCS stage - check for DOCS_REPORT.md
+        if stage_upper == "DOCS":
+            if not artifact_exists("DOCS_REPORT.md", task_name):
+                return ValidationResult(False, "DOCS_REPORT.md not found")
+            return ValidationResult(True, "Docs stage validated")
+
+        # Default: pass
+        return ValidationResult(True, f"{stage} completed")

galangal_orchestrate-0.2.11.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: galangal-orchestrate
+Version: 0.2.11
+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
+Project-URL: Issues, https://github.com/Galangal-Media/galangal-orchestrate/issues
+Author: Galangal Media
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,development,orchestrator,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.40.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Galangal Orchestrate
+
+AI-driven development workflow orchestrator. A deterministic workflow system that guides AI assistants through structured development stages.
+
+**Note:** Currently designed for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with a Claude Pro or Max subscription. Support for other AI backends (Gemini, etc.) is planned for future releases.
+
+## Features
+
+- **Structured Workflow**: PM → DESIGN → DEV → TEST → QA → SECURITY → REVIEW → DOCS
+- **Multi-Framework Support**: Python, TypeScript, PHP, Go, Rust - configure multiple stacks per project
+- **Config-Driven**: All validation, prompts, and behavior customizable via YAML
+- **AI Backend Abstraction**: Built for Claude CLI, ready for Gemini and others
+- **Approval Gates**: Human-in-the-loop for plans and designs
+- **Automatic Rollback**: Failed stages roll back to appropriate fix points
+- **TUI Progress Display**: Real-time progress visualization
+
+## Installation
+
+```bash
+pip install galangal-orchestrate
+```
+
+Or with pipx for isolated global install (recommended):
+
+```bash
+pipx install galangal-orchestrate
+```
+
+### Updating
+
+```bash
+# If installed with pip
+pip install --upgrade galangal-orchestrate
+
+# If installed with pipx
+pipx upgrade galangal-orchestrate
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project
+cd your-project
+galangal init
+
+# Start a new task
+galangal start "Add user authentication feature"
+
+# Resume after a break
+galangal resume
+
+# Check status
+galangal status
+```
+
+## Workflow Stages
+
+| Stage | Purpose | Artifacts |
+|-------|---------|-----------|
+| PM | Requirements & planning | SPEC.md, PLAN.md |
+| DESIGN | Architecture design | DESIGN.md |
+| PREFLIGHT | Environment checks | PREFLIGHT_REPORT.md |
+| DEV | Implementation | (code changes) |
+| MIGRATION* | DB migration validation | MIGRATION_REPORT.md |
+| TEST | Test implementation | TEST_PLAN.md |
+| CONTRACT* | API contract validation | CONTRACT_REPORT.md |
+| QA | Quality assurance | QA_REPORT.md |
+| BENCHMARK* | Performance validation | BENCHMARK_REPORT.md |
+| SECURITY | Security review | SECURITY_CHECKLIST.md |
+| REVIEW | Code review | REVIEW_NOTES.md |
+| DOCS | Documentation updates | DOCS_REPORT.md |
+
+*Conditional stages - auto-skipped if conditions not met
+
+## Task Types
+
+Different task types skip certain stages:
+
+| Type | Skips |
+|------|-------|
+| Feature | (full workflow) |
+| Bug Fix | DESIGN, BENCHMARK |
+| Refactor | DESIGN, MIGRATION, CONTRACT, BENCHMARK, SECURITY |
+| Chore | DESIGN, MIGRATION, CONTRACT, BENCHMARK |
+| Docs | Most stages |
+| Hotfix | DESIGN, BENCHMARK |
+
+## Configuration
+
+After `galangal init`, customize `.galangal/config.yaml`:
+
+```yaml
+project:
+  name: "My Project"
+  stacks:
+    - language: python
+      framework: fastapi
+      root: backend/
+    - language: typescript
+      framework: vite
+      root: frontend/
+
+stages:
+  skip:
+    - BENCHMARK
+  timeout: 14400
+  max_retries: 5
+
+validation:
+  qa:
+    timeout: 3600
+    commands:
+      - name: "Lint"
+        command: "./scripts/lint.sh"
+        timeout: 600
+      - name: "Tests"
+        command: "pytest"
+
+pr:
+  codex_review: true
+  base_branch: main
+
+prompt_context: |
+  ## Project Patterns
+  - Use repository pattern for data access
+  - API responses use api_success() / api_error()
+```
+
+## Customizing Prompts
+
+Galangal uses a layered prompt system:
+
+1. **Base prompts** - Generic, language-agnostic prompts built into the package
+2. **Project prompts** - Your customizations in `.galangal/prompts/`
+
+### Prompt Modes
+
+Project prompts support two modes:
+
+#### Supplement Mode (Recommended)
+
+Add project-specific content that gets prepended to the base prompt. Include the `# BASE` marker where you want the base prompt inserted:
+
+```markdown
+<!-- .galangal/prompts/dev.md -->
+
+## My Project CLI Scripts
+
+Use these commands for testing:
+- `./scripts/test.sh` - Run tests
+- `./scripts/lint.sh` - Run linter
+
+## My Project Patterns
+
+- Always use `api_success()` for responses
+- Never use raw SQL queries
+
+# BASE
+```
+
+The `# BASE` marker tells galangal to insert the generic base prompt at that location. Your project-specific content appears first, followed by the standard instructions.
+
+#### Override Mode
+
+To completely replace a base prompt, simply omit the `# BASE` marker:
+
+```markdown
+<!-- .galangal/prompts/preflight.md -->
+
+# Custom Preflight
+
+This completely replaces the default preflight prompt.
+
+[Your custom instructions here...]
+```
+
+### Available Prompts
+
+Create any of these files in `.galangal/prompts/` to customize:
+
+| File | Stage |
+|------|-------|
+| `pm.md` | Requirements & planning |
+| `design.md` | Architecture design |
+| `preflight.md` | Environment checks |
+| `dev.md` | Implementation |
+| `test.md` | Test writing |
+| `qa.md` | Quality assurance |
+| `security.md` | Security review |
+| `review.md` | Code review |
+| `docs.md` | Documentation |
+
+### Config-Based Context
+
+You can also inject context via `config.yaml` without creating prompt files:
+
+```yaml
+# .galangal/config.yaml
+
+# Injected into ALL stage prompts
+prompt_context: |
+  ## Project Rules
+  - Use TypeScript strict mode
+  - All APIs must be documented
+
+# Injected into specific stages only
+stage_context:
+  dev: |
+    ## Dev Environment
+    - Run `npm run dev` for hot reload
+  test: |
+    ## Test Setup
+    - Use vitest for unit tests
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `galangal init` | Initialize in current project |
+| `galangal start "desc"` | Start new task |
+| `galangal list` | List all tasks |
+| `galangal switch <name>` | Switch active task |
+| `galangal status` | Show task status |
+| `galangal resume` | Continue active task |
+| `galangal pause` | Pause for break |
+| `galangal approve` | Approve plan |
+| `galangal approve-design` | Approve design |
+| `galangal skip-design` | Skip design stage |
+| `galangal skip-to <stage>` | Jump to stage |
+| `galangal complete` | Finalize & create PR |
+| `galangal reset` | Delete active task |
+
+## Requirements
+
+- Python 3.10+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed (`claude` command available)
+- Claude Pro or Max subscription
+- Git
+
+## License
+
+MIT License - see LICENSE file.