multi-forge 0.2.0__py3-none-any.whl

forge/guard/types.py

@@ -0,0 +1,125 @@
+"""Type definitions for the Policy Engine.
+
+All types are dataclasses for easy serialization and dacite compatibility.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+# Type aliases for clarity
+DecisionType = Literal["allow", "deny", "warn", "needs_review"]
+Severity = Literal["critical", "high", "medium", "low"]
+FailMode = Literal["open", "closed"]
+
+
+def extract_added_lines(diff_chunk: str) -> str:
+    """Extract only the added lines from a unified diff chunk.
+
+    Strips diff headers, context lines, and removed lines, returning only
+    the content of ``+`` lines (with the ``+`` prefix removed). This makes
+    on-demand diff content semantically consistent with hook-provided content
+    (i.e., "what's being introduced", not "what's being removed").
+    """
+    lines = []
+    for line in diff_chunk.splitlines():
+        if line.startswith("+") and not line.startswith("+++"):
+            lines.append(line[1:])
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    """Normalized view of what Claude Code is about to do.
+
+    This is the input to all policy evaluations. Built from hook payload.
+
+    Attributes:
+        event: Hook event type (e.g., "PreToolUse.Write")
+        tool_name: Tool being invoked (e.g., "Write", "Edit")
+        tool_args: Raw tool input arguments from Claude Code
+        repo_root: Absolute path to repository root
+        session_name: Current Forge session name
+        target_path: Normalized file path being modified (if applicable)
+        new_content: Content being introduced — new file content (Write), new_string
+            (Edit), or added lines extracted from a unified diff (on-demand check).
+            Regex policies match against this field.
+        raw_diff: Full unified diff chunk (on-demand checks only). Provides richer
+            context for LLM-based policies. None for hook-triggered evaluations.
+    """
+
+    event: str
+    tool_name: str
+    tool_args: dict[str, Any]
+    repo_root: str
+    session_name: str
+    target_path: str | None = None
+    new_content: str | None = None
+    raw_diff: str | None = None
+
+
+@dataclass
+class Violation:
+    """A single policy violation.
+
+    Attributes:
+        rule_id: Unique identifier (e.g., "tdd.tests-before-impl")
+        message: Human-readable explanation
+        severity: How serious this violation is
+        evidence: What triggered this violation (code snippet, etc.)
+        suggested_fix: How to resolve the violation
+        citations: For semantic policies, quoted plan sections that were violated
+    """
+
+    rule_id: str
+    message: str
+    severity: Severity
+    evidence: str | None = None
+    suggested_fix: str | None = None
+    citations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PolicyDecision:
+    """Result of a single policy evaluation.
+
+    Attributes:
+        decision: The policy's verdict. ``needs_review`` must be resolved by
+            semantic supervision before a hook allows the action.
+        policy_id: Which policy made this decision
+        violations: List of violations found (for deny/warn decisions)
+        warnings: Non-blocking warnings to display
+        intent: Why the policy exists (shown on deny to help models understand
+            the goal and surface conflicts instead of working around them)
+        cached: Whether this was a cached verdict (for debugging)
+        evaluated_at: ISO8601 timestamp when evaluated (for logging)
+    """
+
+    decision: DecisionType
+    policy_id: str
+    violations: list[Violation] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    intent: str | None = None
+    cached: bool = False
+    evaluated_at: str | None = None
+
+
+@dataclass
+class CompositeDecision:
+    """Result of composing multiple policies.
+
+    The PolicyEngine evaluates all applicable policies and composes
+    their decisions using the "any deny blocks" rule.
+
+    Attributes:
+        final_decision: Composed result (any deny → deny)
+        decisions: Individual policy decisions for debugging
+        blocking_violations: Violations that caused the deny
+        all_warnings: Accumulated warnings from all policies
+    """
+
+    final_decision: DecisionType
+    decisions: list[PolicyDecision] = field(default_factory=list)
+    blocking_violations: list[Violation] = field(default_factory=list)
+    all_warnings: list[str] = field(default_factory=list)

forge/guard/workflow/__init__.py

@@ -0,0 +1,17 @@
+"""WorkflowPolicy — composable tagger → branch → stage pipeline.
+
+Provides a configurable policy that classifies actions via cheap LLM triage,
+routes them through matching branches, and escalates through filter → checker →
+reviewer stages. Plugs into the existing PolicyEngine via bundle registration.
+"""
+
+from .config import BranchConfig, WorkflowConfig
+from .divergence import build_divergence_config
+from .policy import WorkflowPolicy
+
+__all__ = [
+    "BranchConfig",
+    "WorkflowConfig",
+    "WorkflowPolicy",
+    "build_divergence_config",
+]

forge/guard/workflow/branches.py

@@ -0,0 +1,67 @@
+"""Branch routing for WorkflowPolicy.
+
+A branch is a routing target selected by tag match. It contains
+optional stages (filter → checker → reviewer) that execute in order.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from forge.guard.types import ActionContext, PolicyDecision
+from forge.guard.workflow.config import BranchConfig
+from forge.guard.workflow.stages import CheckerStage, FilterStage, ReviewerStage
+
+
+@dataclass
+class Branch:
+    """A routing target selected by tag match."""
+
+    name: str
+    match_tags: list[str]
+    match_mode: str
+    filter: FilterStage | None
+    checker: CheckerStage | None
+    reviewer: ReviewerStage | None
+
+    @classmethod
+    def from_config(cls, config: BranchConfig) -> Branch:
+        """Instantiate stages from config."""
+        return cls(
+            name=config.name,
+            match_tags=config.match_tags,
+            match_mode=config.match_mode,
+            filter=FilterStage(config.filter) if config.filter else None,
+            checker=CheckerStage(config.checker) if config.checker else None,
+            reviewer=ReviewerStage(config.reviewer) if config.reviewer else None,
+        )
+
+    def matches(self, tags: list[str]) -> bool:
+        """Return True if tags match this branch."""
+        if not self.match_tags:
+            return False
+        if self.match_mode == "all":
+            return all(t in tags for t in self.match_tags)
+        return any(t in tags for t in self.match_tags)
+
+    def execute(self, context: ActionContext, tags: list[str], policy_id: str) -> PolicyDecision:
+        """Run stages in order: filter → checker → reviewer.
+
+        - filter fails (passes()=False) → allow
+        - checker returns allow → short-circuit
+        - checker returns None → continue to reviewer
+        - reviewer returns final decision
+        - No stages configured → allow
+        """
+        if self.filter and not self.filter.passes(context):
+            return PolicyDecision(decision="allow", policy_id=policy_id)
+
+        if self.checker:
+            result = self.checker.check(context, tags, policy_id)
+            if result is not None:
+                return result
+
+        if self.reviewer:
+            return self.reviewer.review(context, tags, policy_id)
+
+        return PolicyDecision(decision="allow", policy_id=policy_id)

forge/guard/workflow/config.py

@@ -0,0 +1,63 @@
+"""Configuration dataclasses for WorkflowPolicy.
+
+Deserialized from ``bundle_config["workflow"]["workflows"]`` dicts
+via ``dacite.from_dict(WorkflowConfig, data)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FilterConfig:
+    """Deterministic gating config for FilterStage."""
+
+    path_patterns: list[str] = field(default_factory=list)
+    exclude_patterns: list[str] = field(default_factory=list)
+    max_content_length: int | None = None
+
+
+@dataclass
+class CheckerConfig:
+    """Cheap LLM check config for CheckerStage."""
+
+    model: str = "gemini/gemini-2.0-flash"
+    prompt_template: str = ""
+    system_prompt: str | None = None
+
+
+@dataclass
+class ReviewerConfig:
+    """Deep LLM review config for ReviewerStage."""
+
+    model: str = "gemini/gemini-2.0-flash"
+    prompt_template: str = ""
+    system_prompt: str | None = None
+
+
+@dataclass
+class BranchConfig:
+    """Config for a single routing branch."""
+
+    name: str
+    match_tags: list[str]
+    match_mode: str = "any"
+    filter: FilterConfig | None = None
+    checker: CheckerConfig | None = None
+    reviewer: ReviewerConfig | None = None
+
+
+@dataclass
+class WorkflowConfig:
+    """Top-level config for a single WorkflowPolicy instance."""
+
+    name: str
+    description: str
+    intent: str = ""
+    tool_names: list[str] = field(default_factory=lambda: ["Write", "Edit"])
+    tagger_model: str = "gemini/gemini-2.0-flash"
+    tagger_prompt: str = ""
+    branches: list[BranchConfig] = field(default_factory=list)
+    throttle_seconds: int = 30
+    max_cache_entries: int = 50

forge/guard/workflow/divergence.py

@@ -0,0 +1,113 @@
+"""Divergence-from-mean workflow — first concrete WorkflowPolicy instance.
+
+Cost model: tagger (~$0.001) filters 80% → checker (~$0.001) short-circuits 80%
+→ only ~4% reach reviewer (~$0.05). Total: ~$0.32/100 changes vs $5.00 reviewing
+everything.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forge.guard.workflow.config import (
+    BranchConfig,
+    CheckerConfig,
+    FilterConfig,
+    ReviewerConfig,
+    WorkflowConfig,
+)
+
+DIVERGENCE_TAGGER_PROMPT = """\
+Classify this code change into exactly one category (respond with just the tag):
+
+- architectural: changes to module structure, public APIs, cross-cutting patterns
+- migration: database schema, data migration scripts
+- config: configuration files, environment setup
+- routine: standard implementation, bug fixes, test updates
+- trivial: whitespace, comments, import reordering
+
+Tool: {tool_name}
+File: {target_path}
+Content (truncated):
+{content}
+
+Tag:"""
+
+DIVERGENCE_CHECKER_PROMPT = """\
+Does this code change follow the project's established patterns?
+Tool: {tool_name}, File: {target_path}, Tags: {tags}
+
+Content:
+{content}
+
+Respond with JSON: {{"aligned": true/false, "reason": "one sentence"}}"""
+
+DIVERGENCE_REVIEWER_PROMPT = """\
+Review this code change for architectural consistency.
+Tool: {tool_name}, File: {target_path}, Tags: {tags}
+
+Content:
+{content}
+
+Evaluate whether this change aligns with the project's established patterns.
+If divergent, cite specific evidence and suggest corrections.
+
+Respond with JSON in a code fence:
+```json
+{{
+  "verdict": "aligned" | "divergent",
+  "confidence": 0.0-1.0,
+  "violations": [
+    {{
+      "severity": "high" | "medium" | "low",
+      "evidence": "what diverges from established patterns",
+      "suggested_fix": "what should be done instead",
+      "citations": ["specific pattern or convention being violated"]
+    }}
+  ]
+}}
+```"""
+
+
+def build_divergence_config(**overrides: Any) -> WorkflowConfig:
+    """Build the divergence-from-mean workflow config.
+
+    The "needs-review" branch triggers on architectural/migration tags,
+    filters out test files, runs a cheap checker, then a deep reviewer.
+    Routine/trivial actions don't match any branch and are allowed.
+
+    Args:
+        **overrides: Override any WorkflowConfig field (e.g., tagger_model).
+
+    Returns:
+        WorkflowConfig ready for WorkflowPolicy instantiation.
+    """
+    defaults: dict[str, Any] = {
+        "name": "divergence",
+        "description": "Flag code changes that diverge from established project patterns",
+        "intent": (
+            "Catch architectural drift early. Code changes that deviate from established "
+            "patterns need review to ensure they are intentional improvements, not accidental "
+            "divergence from project conventions."
+        ),
+        "tagger_model": "gemini/gemini-2.0-flash",
+        "tagger_prompt": DIVERGENCE_TAGGER_PROMPT,
+        "branches": [
+            BranchConfig(
+                name="needs-review",
+                match_tags=["architectural", "migration"],
+                match_mode="any",
+                filter=FilterConfig(
+                    exclude_patterns=[r"^tests/", r"^test_"],
+                ),
+                checker=CheckerConfig(
+                    prompt_template=DIVERGENCE_CHECKER_PROMPT,
+                ),
+                reviewer=ReviewerConfig(
+                    prompt_template=DIVERGENCE_REVIEWER_PROMPT,
+                ),
+            ),
+        ],
+    }
+    defaults.update(overrides)
+    return WorkflowConfig(**defaults)

forge/guard/workflow/policy.py

@@ -0,0 +1,87 @@
+"""WorkflowPolicy — composable tagger → branch → stage pipeline.
+
+Plugs into the existing PolicyEngine via bundle registration.
+Zero engine changes required.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from forge.core.reactive import ThrottleCache, compute_cache_key, tag_action
+from forge.guard.deterministic.base import StatefulDeterministicPolicy
+from forge.guard.types import ActionContext, PolicyDecision
+from forge.guard.workflow.branches import Branch
+from forge.guard.workflow.config import WorkflowConfig
+
+_log = logging.getLogger(__name__)
+
+
+class WorkflowPolicy(StatefulDeterministicPolicy):
+    """Composable tagger → branch → stage pipeline.
+
+    Pipeline:
+    1. Cache check (ThrottleCache) — reuse recent verdicts
+    2. Tag (tag_action) — classify action via cheap LLM
+    3. Route (Branch.matches) — first-match by tags
+    4. Execute (Branch.execute) — filter → checker → reviewer
+    5. Cache result (clean allows only)
+    """
+
+    def __init__(self, config: WorkflowConfig) -> None:
+        self._config = config
+        self._cache = ThrottleCache(
+            ttl_seconds=config.throttle_seconds,
+            max_entries=config.max_cache_entries,
+        )
+        self._branches = [Branch.from_config(b) for b in config.branches]
+
+    @property
+    def policy_id(self) -> str:
+        return f"workflow.{self._config.name}"
+
+    @property
+    def description(self) -> str:
+        return self._config.description
+
+    @property
+    def intent(self) -> str:
+        return self._config.intent
+
+    def applies_to(self, context: ActionContext) -> bool:
+        return context.tool_name in self._config.tool_names
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        cache_key = compute_cache_key(context.tool_name, context.target_path, context.new_content)
+
+        cached = self._cache.check(cache_key)
+        if cached is not None:
+            decision = self._allow()
+            decision.cached = True
+            return decision
+
+        tags = tag_action(
+            context,
+            model=self._config.tagger_model,
+            prompt_template=self._config.tagger_prompt,
+        )
+
+        for branch in self._branches:
+            if branch.matches(tags):
+                decision = branch.execute(context, tags, self.policy_id)
+                if decision.decision == "deny":
+                    decision.intent = self.intent
+                if decision.decision == "allow" and not decision.warnings:
+                    self._cache.update(cache_key, decision="allow", tags=tags)
+                return decision
+
+        # No branch matched → allow (not cached: tagger may have transiently
+        # failed, and caching would suppress re-evaluation after recovery)
+        return self._allow()
+
+    def get_state(self) -> dict[str, Any]:
+        return {"cache": self._cache.get_state()}
+
+    def set_state(self, state: dict[str, Any]) -> None:
+        self._cache.set_state(state.get("cache", {}))

forge/guard/workflow/stages.py

@@ -0,0 +1,205 @@
+"""Stage implementations for WorkflowPolicy branches.
+
+Stages are plain classes (not policies). They produce PolicyDecision objects
+but don't implement the Policy protocol — WorkflowPolicy owns that.
+
+UX constraint: Non-blocking findings go in ``PolicyDecision.warnings`` (printed
+by the hook), not ``violations`` (only shown on deny). Stages must return a
+resolved allow/warn/deny decision rather than emitting ``needs_review``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from forge.core.reactive.structured_output import extract_json_from_response
+from forge.guard.types import ActionContext, PolicyDecision, Severity, Violation
+from forge.guard.workflow.config import CheckerConfig, FilterConfig, ReviewerConfig
+
+_log = logging.getLogger(__name__)
+
+# Confidence threshold for blocking (same as supervisor)
+CONFIDENCE_THRESHOLD = 0.8
+
+_VALID_SEVERITIES: set[str] = {"critical", "high", "medium", "low"}
+
+
+def _normalize_severity(raw: str) -> Severity:
+    """Coerce arbitrary severity string to a valid Severity literal."""
+    normalized = raw.lower().strip()
+    if normalized in _VALID_SEVERITIES:
+        return normalized  # type: ignore[return-value]
+    return "medium"
+
+
+class FilterStage:
+    """Deterministic gating. Free (no LLM calls).
+
+    Compiles regexes in ``__init__`` so invalid patterns fail fast at engine
+    build time rather than silently allowing everything at evaluation time.
+    """
+
+    def __init__(self, config: FilterConfig) -> None:
+        self._path_patterns = [re.compile(p) for p in config.path_patterns]
+        self._exclude_patterns = [re.compile(p) for p in config.exclude_patterns]
+        self._max_content_length = config.max_content_length
+
+    def passes(self, context: ActionContext) -> bool:
+        """Return True if the action should proceed to later stages.
+
+        Check order:
+        1. exclude_patterns — any match → False (skip this branch)
+        2. path_patterns — at least one must match → True (if list is non-empty)
+        3. max_content_length — content exceeds limit → False
+        """
+        path = context.target_path or ""
+
+        for pattern in self._exclude_patterns:
+            if pattern.search(path):
+                return False
+
+        if self._path_patterns:
+            if not any(p.search(path) for p in self._path_patterns):
+                return False
+
+        if self._max_content_length is not None:
+            content_len = len(context.new_content or "")
+            if content_len > self._max_content_length:
+                return False
+
+        return True
+
+
+class CheckerStage:
+    """Cheap LLM intermediate check via SyncAdapter.ask()."""
+
+    def __init__(self, config: CheckerConfig) -> None:
+        self._config = config
+
+    def check(self, context: ActionContext, tags: list[str], policy_id: str) -> PolicyDecision | None:
+        """Quick LLM check.
+
+        Returns:
+            PolicyDecision(allow) to short-circuit (no reviewer needed), or
+            None to escalate to the reviewer stage.
+        """
+        try:
+            from forge.core.llm import SyncAdapter, get_client
+
+            prompt = self._config.prompt_template.format(
+                tool_name=context.tool_name,
+                target_path=context.target_path or "N/A",
+                content=(context.raw_diff or context.new_content or "")[:2000],
+                tags=", ".join(tags),
+            )
+
+            client = get_client(self._config.model)
+            adapter = SyncAdapter(client)
+            response = adapter.ask(prompt, system=self._config.system_prompt)
+
+            data = extract_json_from_response(response)
+            if data is None:
+                _log.debug("Checker could not parse response, escalating to reviewer")
+                return None
+
+            if data.get("aligned") is True:
+                return PolicyDecision(decision="allow", policy_id=policy_id)
+            return None
+
+        except Exception as e:
+            _log.warning("CheckerStage failed: %s", e)
+            return None
+
+
+class ReviewerStage:
+    """Deep LLM review via SyncAdapter.ask()."""
+
+    def __init__(self, config: ReviewerConfig) -> None:
+        self._config = config
+
+    def review(self, context: ActionContext, tags: list[str], policy_id: str) -> PolicyDecision:
+        """Deep review. Returns allow/deny/warn.
+
+        Verdict mapping (mirrors supervisor, configurable policy_id):
+        - aligned → allow
+        - divergent + high confidence (≥0.8) + citations → deny
+        - divergent + low confidence or no citations → warn
+        - parse failure → warn (fail-open)
+        """
+        try:
+            from forge.core.llm import SyncAdapter, get_client
+
+            prompt = self._config.prompt_template.format(
+                tool_name=context.tool_name,
+                target_path=context.target_path or "N/A",
+                content=(context.raw_diff or context.new_content or "")[:4000],
+                tags=", ".join(tags),
+            )
+
+            client = get_client(self._config.model)
+            adapter = SyncAdapter(client)
+            response = adapter.ask(prompt, system=self._config.system_prompt)
+
+            data = extract_json_from_response(response)
+            if data is None:
+                return PolicyDecision(
+                    decision="warn",
+                    policy_id=policy_id,
+                    warnings=["Reviewer could not parse LLM response"],
+                )
+
+            return _map_verdict(data, policy_id)
+
+        except Exception as e:
+            _log.warning("ReviewerStage failed: %s", e)
+            return PolicyDecision(
+                decision="warn",
+                policy_id=policy_id,
+                warnings=[f"Reviewer error: {e}, failing open"],
+            )
+
+
+def _map_verdict(data: dict[str, Any], policy_id: str) -> PolicyDecision:
+    """Map a JSON verdict dict to a PolicyDecision.
+
+    Non-blocking findings go in ``warnings`` (visible in hook UX).
+    Only high-confidence denials with citations use ``violations``.
+    """
+    verdict = data.get("verdict", "aligned")
+    confidence = float(data.get("confidence", 0.0))
+    raw_violations = data.get("violations", [])
+
+    if verdict == "aligned":
+        return PolicyDecision(decision="allow", policy_id=policy_id)
+
+    has_citations = any(v.get("citations") for v in raw_violations if isinstance(v, dict))
+
+    if confidence >= CONFIDENCE_THRESHOLD and has_citations:
+        violations = [
+            Violation(
+                rule_id=f"{policy_id}.reviewer",
+                severity=_normalize_severity(v.get("severity", "medium")),
+                message=v.get("evidence", "Divergent change detected"),
+                evidence=v.get("evidence"),
+                suggested_fix=v.get("suggested_fix"),
+                citations=v.get("citations", []),
+            )
+            for v in raw_violations
+            if isinstance(v, dict)
+        ]
+        return PolicyDecision(
+            decision="deny",
+            policy_id=policy_id,
+            violations=violations,
+        )
+
+    # Low confidence or no citations → warn (visible in hook UX)
+    reasons = [v.get("evidence", str(v)) for v in raw_violations if isinstance(v, dict)]
+    warnings = reasons if reasons else [f"Reviewer flagged as divergent (confidence={confidence:.2f})"]
+    return PolicyDecision(
+        decision="warn",
+        policy_id=policy_id,
+        warnings=warnings,
+    )