policyflow 0.1.0__py3-none-any.whl

policyflow/__init__.py

@@ -0,0 +1,36 @@
+"""PolicyFlow lightweight governance validator."""
+
+from policyflow.api import (
+    WorkflowDocument,
+    WorkflowValidationError,
+    audit_workflows,
+    block_workflow_phase,
+    complete_workflow_phase,
+    get_workflow_status,
+    inspect_workflow,
+    record_workflow_handoff,
+    start_workflow_phase,
+    validate_github_approvals,
+    validate_pr_body,
+    validate_workflow,
+    validate_workflow_data,
+)
+
+__all__ = [
+    "WorkflowDocument",
+    "WorkflowValidationError",
+    "__version__",
+    "audit_workflows",
+    "block_workflow_phase",
+    "complete_workflow_phase",
+    "get_workflow_status",
+    "inspect_workflow",
+    "record_workflow_handoff",
+    "start_workflow_phase",
+    "validate_github_approvals",
+    "validate_pr_body",
+    "validate_workflow",
+    "validate_workflow_data",
+]
+
+__version__ = "0.1.0"

policyflow/agent_execution.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from policyflow.exceptions import WorkflowValidationError
+from policyflow.runtime import (
+    PHASE_AGENT_MAP,
+    block_phase,
+    complete_phase,
+    load_workflow_raw,
+    record_handoff,
+    save_workflow_raw,
+    start_phase,
+)
+from policyflow.validator import validate_workflow_data
+
+
+DEFAULT_RUNNER_CONFIG = Path("policyflow.runners.yml")
+PHASE_EVIDENCE_KEYS = {
+    "planning": "planning",
+    "architecture-check": "architecture-check",
+    "review": "review",
+    "qa": "qa",
+    "approval": "approval",
+}
+PHASE_CONTRACT_KEYS = {
+    "planning": "planning",
+    "architecture-check": "architecture-check",
+    "implementation": "implementation",
+    "review": "review",
+    "qa": "qa",
+}
+
+
+def run_phase_with_runner(
+    workflow_path: Path, phase: str, runner_config_path: Path | None = None
+) -> None:
+    if phase == "approval":
+        raise WorkflowValidationError(
+            ["Phase 'approval' remains human-driven and cannot be run via agent execution."]
+        )
+
+    config_path = runner_config_path or DEFAULT_RUNNER_CONFIG
+    runner_config = _load_runner_config(config_path)
+    runner_name = str(runner_config.get("default_runner", "")).strip()
+    runners = runner_config.get("runners")
+
+    if not runner_name:
+        raise WorkflowValidationError(["Runner config must declare default_runner."])
+    if not isinstance(runners, dict) or runner_name not in runners:
+        raise WorkflowValidationError(
+            [f"Runner config must declare runner settings for '{runner_name}'."]
+        )
+
+    runner = runners[runner_name]
+    if not isinstance(runner, dict):
+        raise WorkflowValidationError(
+            [f"Runner definition for '{runner_name}' must be a mapping."]
+        )
+
+    start_phase(workflow_path, phase)
+
+    try:
+        raw = load_workflow_raw(workflow_path)
+        payload = _build_execution_payload(raw, workflow_path, phase, runner, config_path)
+        result = _execute_runner(runner, payload, workflow_path, config_path)
+        _apply_runner_result(workflow_path, phase, result)
+    except WorkflowValidationError as exc:
+        _block_phase_on_failure(workflow_path, phase, exc.errors[0])
+        raise
+    except Exception as exc:  # pragma: no cover - defensive catch for subprocess/json edge cases
+        _block_phase_on_failure(workflow_path, phase, str(exc))
+        raise WorkflowValidationError([str(exc)]) from exc
+
+
+def _load_runner_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise WorkflowValidationError([f"Runner config file not found: {path}"])
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise WorkflowValidationError([f"Invalid runner config YAML: {exc}"]) from exc
+
+    if not isinstance(data, dict):
+        raise WorkflowValidationError(
+            ["Runner config file must contain a top-level YAML mapping."]
+        )
+
+    return data
+
+
+def _build_execution_payload(
+    raw: dict[str, Any],
+    workflow_path: Path,
+    phase: str,
+    runner: dict[str, Any],
+    config_path: Path,
+) -> dict[str, Any]:
+    handoffs = raw.get("handoffs") or []
+    inbound_handoff = None
+    for handoff in handoffs:
+        if (
+            isinstance(handoff, dict)
+            and handoff.get("to_phase") == phase
+            and handoff.get("status") in {"pending", "completed"}
+        ):
+            inbound_handoff = handoff
+            break
+
+    return {
+        "workflow_path": str(workflow_path),
+        "workflow": raw,
+        "phase": phase,
+        "owner_agent": PHASE_AGENT_MAP.get(phase),
+        "prompt_text": _load_phase_asset(runner, "prompt_paths", phase, config_path),
+        "agent_text": _load_phase_asset(runner, "agent_paths", phase, config_path),
+        "handoff": inbound_handoff,
+    }
+
+
+def _load_phase_asset(
+    runner: dict[str, Any], config_key: str, phase: str, config_path: Path
+) -> str | None:
+    phase_map = runner.get(config_key)
+    if not isinstance(phase_map, dict):
+        return None
+    configured_path = phase_map.get(phase)
+    if not isinstance(configured_path, str) or not configured_path.strip():
+        return None
+
+    candidate = Path(configured_path)
+    if candidate.exists():
+        return candidate.read_text(encoding="utf-8")
+
+    cwd_candidate = Path.cwd() / configured_path
+    if cwd_candidate.exists():
+        return cwd_candidate.read_text(encoding="utf-8")
+
+    config_candidate = config_path.parent / configured_path
+    if config_candidate.exists():
+        return config_candidate.read_text(encoding="utf-8")
+
+    raise WorkflowValidationError(
+        [f"Runner asset for phase '{phase}' not found: {configured_path}"]
+    )
+
+
+def _execute_runner(
+    runner: dict[str, Any],
+    payload: dict[str, Any],
+    workflow_path: Path,
+    config_path: Path,
+) -> dict[str, Any]:
+    command = runner.get("command")
+    if not isinstance(command, list) or not command:
+        raise WorkflowValidationError(["Runner command must be a non-empty list."])
+
+    with tempfile.TemporaryDirectory() as temp_dir_name:
+        temp_dir = Path(temp_dir_name)
+        input_path = temp_dir / "policyflow-agent-input.json"
+        output_path = temp_dir / "policyflow-agent-output.json"
+        input_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+        substitutions = {
+            "workflow_path": str(workflow_path),
+            "phase": payload["phase"],
+            "input_path": str(input_path),
+            "output_path": str(output_path),
+            "python_executable": sys.executable,
+        }
+
+        resolved_command = [
+            _format_command_token(token, substitutions) for token in command
+        ]
+
+        completed = subprocess.run(
+            resolved_command,
+            cwd=Path.cwd(),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        if completed.returncode != 0:
+            stderr = completed.stderr.strip()
+            stdout = completed.stdout.strip()
+            message = stderr or stdout or f"runner exited with code {completed.returncode}"
+            raise WorkflowValidationError([f"Agent runner failed: {message}"])
+
+        if not output_path.exists():
+            raise WorkflowValidationError(
+                [f"Agent runner did not produce output JSON: {output_path}"]
+            )
+
+        try:
+            result = json.loads(output_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise WorkflowValidationError(
+                [f"Agent runner produced invalid JSON: {exc}"]
+            ) from exc
+
+    if not isinstance(result, dict):
+        raise WorkflowValidationError(
+            ["Agent runner output must be a top-level JSON object."]
+        )
+
+    return result
+
+
+def _format_command_token(token: Any, substitutions: dict[str, str]) -> str:
+    if not isinstance(token, str):
+        raise WorkflowValidationError(["Runner command entries must be strings."])
+    return token.format(**substitutions)
+
+
+def _apply_runner_result(workflow_path: Path, phase: str, result: dict[str, Any]) -> None:
+    output_phase = str(result.get("phase", "")).strip()
+    if output_phase != phase:
+        raise WorkflowValidationError(
+            [f"Agent runner output phase must match requested phase: {phase}"]
+        )
+
+    output_owner = str(result.get("owner_agent", "")).strip()
+    expected_owner = PHASE_AGENT_MAP.get(phase)
+    if output_owner != expected_owner:
+        raise WorkflowValidationError(
+            [f"Agent runner output owner_agent must match expected owner: {expected_owner}"]
+        )
+
+    status = str(result.get("status", "")).strip()
+    if status not in {"completed", "blocked"}:
+        raise WorkflowValidationError(
+            ["Agent runner output status must be 'completed' or 'blocked'."]
+        )
+
+    if status == "blocked":
+        blockers = result.get("blockers")
+        if isinstance(blockers, list) and blockers:
+            reason = str(blockers[0])
+        else:
+            reason = str(result.get("summary", "")).strip() or "agent runner blocked phase"
+        _block_phase_on_failure(workflow_path, phase, reason)
+        raise WorkflowValidationError([f"Agent runner blocked phase '{phase}': {reason}"])
+
+    raw = load_workflow_raw(workflow_path)
+    updated = deepcopy(raw)
+    _apply_phase_updates(updated, phase, result)
+    validate_workflow_data(updated)
+    save_workflow_raw(workflow_path, updated)
+
+    complete_phase(workflow_path, phase)
+
+    handoff = result.get("handoff")
+    if isinstance(handoff, dict):
+        to_phase = handoff.get("to_phase")
+        required_inputs = handoff.get("required_inputs")
+        produced_outputs = handoff.get("produced_outputs")
+        if (
+            isinstance(to_phase, str)
+            and isinstance(required_inputs, list)
+            and isinstance(produced_outputs, list)
+        ):
+            record_handoff(
+                workflow_path,
+                phase,
+                to_phase,
+                [str(item) for item in required_inputs],
+                [str(item) for item in produced_outputs],
+                [],
+                [],
+            )
+
+
+def _apply_phase_updates(raw: dict[str, Any], phase: str, result: dict[str, Any]) -> None:
+    contract_key = PHASE_CONTRACT_KEYS.get(phase)
+    contract_updates = result.get("contract_updates")
+    if contract_key and isinstance(contract_updates, dict):
+        raw.setdefault("contracts", {})
+        raw["contracts"][contract_key] = contract_updates
+
+    evidence_key = PHASE_EVIDENCE_KEYS.get(phase)
+    evidence_updates = result.get("evidence_updates")
+    if evidence_key and isinstance(evidence_updates, dict):
+        raw.setdefault("evidence", {})
+        raw["evidence"][evidence_key] = evidence_updates
+
+
+def _block_phase_on_failure(workflow_path: Path, phase: str, reason: str) -> None:
+    try:
+        block_phase(workflow_path, phase, reason)
+    except WorkflowValidationError:
+        pass

policyflow/api.py

@@ -0,0 +1,125 @@
+"""Stable public Python API for PolicyFlow consumers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from policyflow.exceptions import WorkflowValidationError
+from policyflow.github_approval import validate_github_pr_approvals
+from policyflow.models import WorkflowDocument
+from policyflow.reporting import audit_directory, workflow_status
+from policyflow.runtime import (
+    block_phase,
+    complete_phase,
+    record_handoff,
+    start_phase,
+)
+from policyflow.validator import (
+    inspect_workflow_file,
+    validate_pull_request,
+    validate_workflow_data as _validate_workflow_data,
+    validate_workflow_file,
+)
+
+__all__ = [
+    "WorkflowDocument",
+    "WorkflowValidationError",
+    "audit_workflows",
+    "block_workflow_phase",
+    "complete_workflow_phase",
+    "get_workflow_status",
+    "inspect_workflow",
+    "record_workflow_handoff",
+    "start_workflow_phase",
+    "validate_github_approvals",
+    "validate_pr_body",
+    "validate_workflow",
+    "validate_workflow_data",
+]
+
+
+def inspect_workflow(path: str | Path) -> tuple[WorkflowDocument, list[str]]:
+    """Validate a workflow file and return the normalized document plus warnings."""
+
+    return inspect_workflow_file(path)
+
+
+def validate_workflow(path: str | Path) -> WorkflowDocument:
+    """Validate a workflow file and return its normalized workflow document."""
+
+    return validate_workflow_file(path)
+
+
+def validate_workflow_data(raw_data: dict[str, Any]) -> WorkflowDocument:
+    """Validate an in-memory workflow mapping."""
+
+    return _validate_workflow_data(raw_data)
+
+
+def validate_pr_body(
+    workflow_path: str | Path, pr_body_path: str | Path
+) -> WorkflowDocument:
+    """Validate a PR body markdown file against a workflow file."""
+
+    return validate_pull_request(workflow_path, pr_body_path)
+
+
+def validate_github_approvals(
+    workflow_path: str | Path, pr_body_path: str | Path, reviews_path: str | Path
+) -> WorkflowDocument:
+    """Validate GitHub review metadata against workflow approval requirements."""
+
+    return validate_github_pr_approvals(workflow_path, pr_body_path, reviews_path)
+
+
+def get_workflow_status(path: str | Path) -> dict[str, Any]:
+    """Return workflow status and merge-readiness data."""
+
+    return workflow_status(Path(path))
+
+
+def audit_workflows(directory: str | Path) -> dict[str, Any]:
+    """Return an audit payload for all workflow files under a directory."""
+
+    return audit_directory(Path(directory))
+
+
+def start_workflow_phase(path: str | Path, phase: str) -> None:
+    """Start a pending workflow phase and persist runtime state."""
+
+    start_phase(Path(path), phase)
+
+
+def complete_workflow_phase(path: str | Path, phase: str) -> None:
+    """Complete an in-progress workflow phase and persist runtime state."""
+
+    complete_phase(Path(path), phase)
+
+
+def block_workflow_phase(path: str | Path, phase: str, reason: str) -> None:
+    """Block a workflow phase with a reason and persist runtime state."""
+
+    block_phase(Path(path), phase, reason)
+
+
+def record_workflow_handoff(
+    path: str | Path,
+    from_phase: str,
+    to_phase: str,
+    required_inputs: list[str],
+    produced_outputs: list[str],
+    blockers: list[str] | None = None,
+    override_refs: list[str] | None = None,
+) -> None:
+    """Record a workflow phase handoff with concrete artifacts."""
+
+    record_handoff(
+        Path(path),
+        from_phase,
+        to_phase,
+        required_inputs,
+        produced_outputs,
+        blockers,
+        override_refs,
+    )

policyflow/assets/agents/architecture-agent.md

@@ -0,0 +1,50 @@
+# Architecture Agent
+
+## Purpose
+
+Protect architecture boundaries and keep the workflow aligned with the target project's operating model.
+
+## Responsibilities
+
+- review architecture context and boundaries
+- confirm risk and review depth
+- identify approval needs
+- define implementation constraints
+
+## Accepted Inputs
+
+- issue brief
+- acceptance criteria
+- non-goals
+- initial risk level
+- protected areas touched
+- confidence summary
+- escalation flags
+
+## Required Outputs
+
+- architecture assessment
+- approved scope
+- module boundaries
+- contract impact
+- risk review decision
+- required reviews
+- implementation constraints
+
+## Forbidden Actions
+
+- waive mandatory reviews
+- approve speculative architecture
+- normalize undocumented coupling
+
+## Escalation Triggers
+
+- contract ownership unclear
+- boundary conflict
+- protected area touched without approval path
+- risk needs upgrade
+
+## Handoff Target
+
+- senior-dev-agent
+- human approval first when required

policyflow/assets/agents/planning-agent.md

@@ -0,0 +1,46 @@
+# Planning Agent
+
+## Purpose
+
+Turn an approved request into a bounded workflow with clear scope, non-goals, risk, approvals, and handoffs.
+
+## Responsibilities
+
+- read target-project context first
+- classify risk
+- choose the smallest workflow that still satisfies governance rules
+- define scope, non-goals, affected modules, and escalation points
+
+## Accepted Inputs
+
+- approved issue or request
+- target-project context
+- relevant governance rules
+
+## Required Outputs
+
+- issue brief
+- acceptance criteria
+- non-goals
+- initial risk level
+- protected areas touched
+- confidence summary
+- escalation flags
+
+## Forbidden Actions
+
+- implement changes directly
+- downgrade risk to avoid review
+- reduce required reviews below the matrix
+
+## Escalation Triggers
+
+- risk unclear
+- protected area touched
+- conflicting architecture signals
+- scope ambiguity
+
+## Handoff Target
+
+- architecture-agent
+- senior-dev-agent on LOW-risk fast path only

policyflow/assets/agents/qa-agent.md

@@ -0,0 +1,46 @@
+# QA Agent
+
+## Purpose
+
+Validate acceptance criteria, evidence quality, and merge readiness.
+
+## Responsibilities
+
+- check scope and acceptance criteria against the actual diff
+- confirm validation evidence
+- confirm approval compliance
+- record residual risks and merge readiness
+
+## Accepted Inputs
+
+- review approval
+- residual risk
+- QA focus areas
+- test expectations
+- approval evidence when required
+
+## Required Outputs
+
+- QA report
+- quality gate status
+- unresolved risks
+- approval required
+- merge readiness
+
+## Forbidden Actions
+
+- declare success without evidence
+- bypass approval requirements
+- weaken quality gates to force completion
+
+## Escalation Triggers
+
+- validation evidence missing
+- approval ambiguity
+- confidence conflicts with evidence
+- unresolved critical risk remains
+
+## Handoff Target
+
+- human approval when required
+- merge readiness when all gates are satisfied

policyflow/assets/agents/review-agent.md

@@ -0,0 +1,51 @@
+# Review Agent
+
+## Purpose
+
+Review for regressions, scope drift, architecture issues, and missing validation.
+
+## Responsibilities
+
+- compare the diff with issue, workflow, and rules
+- check protected areas and contract safety
+- identify missing tests or documentation
+- decide whether the change returns for fixes or can move to QA
+
+## Accepted Inputs
+
+- implementation summary
+- changed files
+- test summary
+- docs updates
+- known limitations
+- unresolved questions
+
+## Required Outputs
+
+- review findings
+- required fixes
+- severity
+- approval status
+- review approval
+- residual risk
+- QA focus areas
+- test expectations
+
+## Forbidden Actions
+
+- rewrite scope during review
+- waive approvals
+- hand off to QA while blocking findings remain
+
+## Escalation Triggers
+
+- hidden protected-area impact
+- risk understated
+- evidence incomplete
+- fix loop does not converge
+
+## Handoff Target
+
+- senior-dev-agent
+- qa-agent
+- human approval if risk or approval path changes

policyflow/assets/agents/senior-dev-agent.md

@@ -0,0 +1,49 @@
+# Senior Dev Agent
+
+## Purpose
+
+Implement the smallest approved change while preserving reviewability and evidence.
+
+## Responsibilities
+
+- follow the approved workflow
+- keep changes local and explicit
+- add or update tests when approved logic changes require them
+- record assumptions and validation
+
+## Accepted Inputs
+
+- architecture assessment when required
+- approved scope
+- module boundaries
+- contract impact
+- risk review decision
+- required reviews
+- implementation constraints
+
+## Required Outputs
+
+- implementation summary
+- changed files
+- test summary
+- docs updates
+- known limitations
+- unresolved questions
+
+## Forbidden Actions
+
+- expand scope
+- bypass approval
+- change protected areas without authorization
+
+## Escalation Triggers
+
+- scope no longer fits approved workflow
+- protected area becomes implicated
+- validation blocked
+- architecture conflict appears during implementation
+
+## Handoff Target
+
+- review-agent
+- architecture-agent or human approval if governance conditions change