multi-forge 0.2.0__py3-none-any.whl

forge/guard/deterministic/tdd.py

@@ -0,0 +1,171 @@
+"""TDD bundle policies.
+
+Enforces test-driven development workflow:
+- tests-before-impl: Must touch tests before implementing in src/
+- no-skip-tests: Blocks adding pytest.skip or similar patterns
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forge.guard.deterministic.base import (
+    DeterministicPolicy,
+    StatefulDeterministicPolicy,
+)
+from forge.guard.types import ActionContext, PolicyDecision, Violation
+
+# Patterns that indicate test skipping
+SKIP_PATTERNS = [
+    r"pytest\.skip\(",
+    r"@pytest\.mark\.skip\b",
+    r"@pytest\.mark\.skipif\b",
+    r"unittest\.skip\b",
+    r"@unittest\.skip\b",
+]
+
+
+class TDDEnforcementPolicy(StatefulDeterministicPolicy):
+    """Enforce that tests are touched before implementation code.
+
+    State tracking:
+    - When Write/Edit targets tests/, record path in tests_touched
+    - When Write/Edit targets src/ and tests_touched is empty, deny (or warn)
+
+    This policy is stateful because it needs to remember across hook invocations
+    which test files have been touched in the current session.
+    """
+
+    def __init__(self, *, strict: bool = True) -> None:
+        """Initialize the policy.
+
+        Args:
+            strict: If True, deny impl without tests. If False, warn only.
+        """
+        self.strict = strict
+        self._tests_touched: set[str] = set()
+
+    @property
+    def policy_id(self) -> str:
+        return "tdd.tests-before-impl"
+
+    @property
+    def description(self) -> str:
+        mode = "strict" if self.strict else "permissive"
+        return f"Require test changes before implementation changes ({mode} mode)"
+
+    @property
+    def intent(self) -> str:
+        return (
+            "Test-driven development: write tests first to define expected behavior, "
+            "then implement. This catches design issues early and ensures every change "
+            "has test coverage from the start."
+        )
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Apply to Write/Edit on tests/ or src/ paths."""
+        if context.tool_name not in ("Write", "Edit"):
+            return False
+
+        path = context.target_path
+        if path is None:
+            return False
+
+        # Only care about tests/ and src/ directories
+        return self._is_under_directory(path, "tests") or self._is_under_directory(path, "src")
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Evaluate the TDD workflow.
+
+        Logic:
+        1. If writing to tests/, record the path and allow
+        2. If writing to src/ and no tests touched, deny (strict) or warn (permissive)
+        3. Otherwise, allow
+        """
+        path = context.target_path
+        if path is None:
+            return self._allow()
+
+        # Touching a test file - record it and allow
+        if self._is_under_directory(path, "tests"):
+            self._tests_touched.add(path)
+            return self._allow()
+
+        # Touching implementation - check if tests were touched first
+        if self._is_under_directory(path, "src"):
+            if not self._tests_touched:
+                violation = Violation(
+                    rule_id=self.policy_id,
+                    message="Implementation changes require test changes first",
+                    severity="high",
+                    evidence=f"Writing to {path} without touching any test files",
+                    suggested_fix="Write or update tests in tests/ directory before modifying src/ code",
+                )
+
+                if self.strict:
+                    return self._deny([violation])
+                else:
+                    return self._warn([violation.message])
+
+        return self._allow()
+
+    def get_state(self) -> dict[str, Any]:
+        """Return current state for persistence."""
+        return {"tests_touched": list(self._tests_touched)}
+
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Restore state from persisted data."""
+        self._tests_touched = set(state.get("tests_touched", []))
+
+
+class NoSkipTestsPolicy(DeterministicPolicy):
+    """Block adding test skip patterns.
+
+    Prevents:
+    - pytest.skip()
+    - @pytest.mark.skip
+    - @pytest.mark.skipif
+    - unittest.skip
+    """
+
+    @property
+    def policy_id(self) -> str:
+        return "tdd.no-skip-tests"
+
+    @property
+    def description(self) -> str:
+        return "Block adding pytest.skip or similar test-skipping patterns"
+
+    @property
+    def intent(self) -> str:
+        return (
+            "Skipped tests hide broken functionality. Every test should either pass or "
+            "be deleted. If a test cannot run, fix the environment or the code rather "
+            "than skipping it."
+        )
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Apply to Write/Edit with content that might contain skip patterns."""
+        if context.tool_name not in ("Write", "Edit"):
+            return False
+
+        # Only check if there's content to analyze
+        return context.new_content is not None
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Check for skip patterns in content."""
+        matched = self._matches_any_pattern(context.new_content, SKIP_PATTERNS)
+
+        if matched:
+            violations = [
+                Violation(
+                    rule_id=self.policy_id,
+                    message="Test skip patterns are not allowed",
+                    severity="high",
+                    evidence=f"Found skip pattern(s): {', '.join(matched)}",
+                    suggested_fix="Remove the skip pattern and fix the underlying issue",
+                )
+            ]
+            return self._deny(violations)
+
+        return self._allow()

forge/guard/engine.py

@@ -0,0 +1,216 @@
+"""Policy composition engine.
+
+The PolicyEngine evaluates multiple policies against an action and
+composes their decisions using the "any deny blocks" rule.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from forge.core.state import now_iso
+from forge.guard.protocols import Policy, StatefulPolicy
+from forge.guard.types import (
+    ActionContext,
+    CompositeDecision,
+    DecisionType,
+    FailMode,
+    PolicyDecision,
+)
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass
+class PolicyEngine:
+    """Composes multiple policies and produces a unified decision.
+
+    Composition rules:
+    - Policies are evaluated in registration order
+    - Any deny blocks the action (unless fail_mode is "open" and it's an error)
+    - needs_review is resolved by semantic supervisor when it participates
+    - Warnings accumulate from all policies
+    - State is collected from stateful policies for persistence
+
+    Attributes:
+        policies: List of registered policies
+        fail_mode: Default behavior on policy errors ("open" = allow, "closed" = deny)
+    """
+
+    policies: list[Policy] = field(default_factory=list)
+    fail_mode: FailMode = "open"
+
+    # Collected state from stateful policies (for persistence)
+    _collected_state: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def register(self, policy: Policy) -> None:
+        """Register a policy with the engine."""
+        self.policies.append(policy)
+        _log.debug("Registered policy: %s", policy.policy_id)
+
+    def restore_state(self, persisted_state: dict[str, Any] | None) -> None:
+        """Restore state to all stateful policies.
+
+        Called at the start of evaluation to restore state from the session manifest.
+
+        Args:
+            persisted_state: Dict mapping policy_id to state dict
+        """
+        if persisted_state is None:
+            return
+
+        for policy in self.policies:
+            if isinstance(policy, StatefulPolicy):
+                policy_state = persisted_state.get(policy.policy_id)
+                if policy_state is not None:
+                    try:
+                        policy.set_state(policy_state)
+                        _log.debug("Restored state for %s", policy.policy_id)
+                    except Exception as e:
+                        _log.warning("Failed to restore state for %s: %s", policy.policy_id, e)
+
+    def get_collected_state(self) -> dict[str, dict[str, Any]]:
+        """Get collected state from all stateful policies.
+
+        Called after evaluation to persist state to the session manifest.
+
+        Returns:
+            Dict mapping policy_id to state dict
+        """
+        return self._collected_state.copy()
+
+    def evaluate(self, context: ActionContext) -> CompositeDecision:
+        """Evaluate all applicable policies and compose results.
+
+        Args:
+            context: The action being evaluated
+
+        Returns:
+            CompositeDecision with:
+            - final_decision: allow/deny/warn/needs_review based on composition
+            - decisions: individual policy decisions for debugging
+            - blocking_violations: violations that caused deny
+            - all_warnings: accumulated warnings
+        """
+        decisions: list[PolicyDecision] = []
+        blocking_violations: list = []
+        all_warnings: list[str] = []
+        needs_review = False
+
+        for policy in self.policies:
+            # Check if policy applies
+            try:
+                if not policy.applies_to(context):
+                    _log.debug(
+                        "Policy %s does not apply to %s",
+                        policy.policy_id,
+                        context.tool_name,
+                    )
+                    continue
+            except Exception as e:
+                _log.warning("Policy %s.applies_to() failed: %s", policy.policy_id, e)
+                if self.fail_mode == "closed":
+                    decisions.append(
+                        PolicyDecision(
+                            decision="deny",
+                            policy_id=policy.policy_id,
+                            warnings=[f"Policy applies_to() failed (fail-closed): {e}"],
+                        )
+                    )
+                continue
+
+            # Evaluate policy
+            try:
+                decision = policy.evaluate(context)
+                decision.evaluated_at = now_iso()
+                decisions.append(decision)
+
+                _log.debug(
+                    "Policy %s evaluated: %s (%d violations)",
+                    policy.policy_id,
+                    decision.decision,
+                    len(decision.violations),
+                )
+
+            except Exception as e:
+                _log.warning("Policy %s.evaluate() failed: %s", policy.policy_id, e)
+                if self.fail_mode == "open":
+                    decisions.append(
+                        PolicyDecision(
+                            decision="allow",
+                            policy_id=policy.policy_id,
+                            warnings=[f"Policy evaluation failed (fail-open): {e}"],
+                        )
+                    )
+                else:
+                    decisions.append(
+                        PolicyDecision(
+                            decision="deny",
+                            policy_id=policy.policy_id,
+                            warnings=[f"Policy evaluation failed (fail-closed): {e}"],
+                        )
+                    )
+                continue
+
+            # Collect state from stateful policies
+            if isinstance(policy, StatefulPolicy):
+                try:
+                    self._collected_state[policy.policy_id] = policy.get_state()
+                except Exception as e:
+                    _log.warning("Failed to get state from %s: %s", policy.policy_id, e)
+
+        # Compose decisions
+        final_decision: DecisionType = "allow"
+
+        for d in decisions:
+            all_warnings.extend(d.warnings)
+
+            if d.decision == "deny":
+                final_decision = "deny"
+                blocking_violations.extend(d.violations)
+            elif d.decision == "needs_review":
+                needs_review = True
+            elif d.decision == "warn" and final_decision == "allow":
+                final_decision = "warn"
+
+        review_resolved = any(d.policy_id == "semantic.supervisor" and d.decision != "needs_review" for d in decisions)
+
+        # If any policy needs review and no supervisor resolved it, escalate.
+        if needs_review and not review_resolved and final_decision not in ("deny",):
+            final_decision = "needs_review"
+
+        return CompositeDecision(
+            final_decision=final_decision,
+            decisions=decisions,
+            blocking_violations=blocking_violations,
+            all_warnings=all_warnings,
+        )
+
+
+def build_engine(
+    bundles: list[str],
+    fail_mode: FailMode = "open",
+    bundle_config: dict[str, dict[str, Any]] | None = None,
+) -> PolicyEngine:
+    """Build a PolicyEngine with policies from the specified bundles.
+
+    Args:
+        bundles: List of bundle names (e.g., ["tdd", "coding_standards"])
+        fail_mode: Behavior on policy errors
+        bundle_config: Per-bundle configuration (e.g., {"tdd": {"strict": False}}).
+
+    Returns:
+        Configured PolicyEngine
+    """
+    from forge.guard.deterministic.registry import get_bundle_policies
+
+    engine = PolicyEngine(fail_mode=fail_mode)
+
+    for bundle in bundles:
+        config = bundle_config.get(bundle) if bundle_config else None
+        for policy in get_bundle_policies(bundle, config=config):
+            engine.register(policy)
+
+    return engine

forge/guard/protocols.py

@@ -0,0 +1,91 @@
+"""Policy protocol definitions.
+
+All policies (deterministic and semantic) implement these protocols,
+enabling uniform composition in the PolicyEngine.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from forge.guard.types import ActionContext, PolicyDecision
+
+
+@runtime_checkable
+class Policy(Protocol):
+    """Interface all policies must implement.
+
+    Policies are evaluated against an ActionContext and return a PolicyDecision.
+    The `applies_to` method enables filtering/short-circuiting before evaluation.
+
+    Example:
+        class MyPolicy:
+            @property
+            def policy_id(self) -> str:
+                return "my-bundle.my-rule"
+
+            def applies_to(self, context: ActionContext) -> bool:
+                return context.tool_name == "Write"
+
+            def evaluate(self, context: ActionContext) -> PolicyDecision:
+                # Check something and return decision
+                return PolicyDecision(decision="allow", policy_id=self.policy_id)
+    """
+
+    @property
+    def policy_id(self) -> str:
+        """Unique identifier for this policy (e.g., 'tdd.tests-before-impl')."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Human-readable description of what this policy enforces."""
+        ...
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Return True if this policy should evaluate the given action.
+
+        Used for filtering/throttling before full evaluation. Policies that
+        don't apply to the action should return False to skip evaluation.
+        """
+        ...
+
+    def evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Evaluate the action and return a decision.
+
+        For deterministic policies: synchronous, fast.
+        For semantic policies: may invoke LLM (should be throttled).
+        """
+        ...
+
+
+@runtime_checkable
+class StatefulPolicy(Policy, Protocol):
+    """Protocol for policies that track state across actions.
+
+    Stateful policies (e.g., TDD's "tests touched before impl") need to
+    persist state across hook invocations. Since hooks are short-lived
+    processes, state is persisted to the session manifest.
+
+    The PolicyEngine calls get_state() after evaluation to persist state,
+    and set_state() at the start to restore it.
+
+    Example:
+        class TDDEnforcementPolicy:
+            def __init__(self):
+                self._tests_touched: set[str] = set()
+
+            def get_state(self) -> dict[str, Any]:
+                return {"tests_touched": list(self._tests_touched)}
+
+            def set_state(self, state: dict[str, Any]) -> None:
+                self._tests_touched = set(state.get("tests_touched", []))
+    """
+
+    def get_state(self) -> dict[str, Any]:
+        """Return current policy state for persistence."""
+        ...
+
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Restore policy state from persisted data."""
+        ...

forge/guard/queries.py

@@ -0,0 +1,96 @@
+"""Read-only queries about supervisor relationships and session policy state.
+
+Used by both the CLI (``forge guard status``) and direct commands
+(``%guard status``) to display supervisor metadata and discover
+supervised sessions.
+"""
+
+from __future__ import annotations
+
+import re
+
+from forge.session import SessionStore
+from forge.session.effective import compute_effective_intent
+from forge.session.models import SessionState
+
+_UUID_RE = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+
+
+def read_scoped_supervisor_target(
+    resume_id: str,
+    supervisor_forge_root: str | None,
+    fallback_forge_root: str | None,
+) -> SessionState | None:
+    """Return supervisor target state, preferring the supervisor's stored scope.
+
+    Handles both session-name and raw-UUID resume_id values. UUIDs are
+    resolved via the index's reverse lookup (find_session_by_uuid).
+    """
+    try:
+        from forge.session.manager import SessionManager
+
+        mgr = SessionManager()
+        fr = supervisor_forge_root or fallback_forge_root
+
+        # Try name-based lookup first (common case)
+        if not _UUID_RE.fullmatch(resume_id):
+            return mgr.get_session(resume_id, forge_root=fr)
+
+        # UUID: reverse lookup through the index
+        result = mgr.index_store.find_session_by_uuid(resume_id)
+        if result is None:
+            return None
+        display_name, entry_fr = result
+        return mgr.get_session(display_name, forge_root=entry_fr)
+    except Exception:
+        return None
+
+
+def find_sessions_supervised_by(
+    target_name: str,
+    target_uuid: str | None,
+    target_forge_root: str | None,
+) -> list[str]:
+    """Find repo-scoped sessions whose supervisor points to the target.
+
+    Matches on session name or Claude UUID. Verifies forge_root alignment
+    when set to prevent false matches from duplicate names across projects.
+    Best-effort: skips broken manifests, never crashes.
+
+    Cost: O(N) manifest reads where N = repo-scoped sessions. Acceptable
+    for typical workflows (2-10 sessions per repo).
+    """
+    try:
+        from forge.session.manager import SessionManager
+
+        mgr = SessionManager()
+        if not target_forge_root:
+            return []
+        project_root = mgr.resolve_project_root(target_forge_root)
+        siblings = mgr.list_sessions(project_root_filter=project_root)
+    except Exception:
+        return []
+
+    supervised: list[str] = []
+    for sib_name, sib_entry in siblings:
+        if sib_name == target_name:
+            continue
+        try:
+            sib_store = SessionStore(sib_entry.forge_root or sib_entry.worktree_path, sib_name)
+            sib_state = sib_store.read()
+            effective = compute_effective_intent(sib_state)
+            if not effective.policy or not effective.policy.supervisor:
+                continue
+            sup = effective.policy.supervisor
+            if not sup.resume_id:
+                continue
+            matched = sup.resume_id == target_name or (target_uuid and sup.resume_id == target_uuid)
+            if not matched:
+                continue
+            if sup.forge_root and target_forge_root and sup.forge_root != target_forge_root:
+                continue
+            supervised.append(sib_name)
+        except Exception:
+            continue
+
+    return supervised

forge/guard/semantic/__init__.py

@@ -0,0 +1,34 @@
+"""Semantic policies for the Policy Engine.
+
+Semantic policies use LLM-based evaluation for nuanced judgment calls
+that cannot be expressed as deterministic rules. The primary use case
+is the Supervisor pattern:
+
+1. Planning session creates and approves a plan (ExitPlanMode)
+2. Session is forked and promoted to supervisor role
+3. Executor actions are validated against the plan by the supervisor
+4. Supervisor returns structured verdicts (aligned/divergent + confidence)
+
+Throttling and caching prevent excessive LLM calls:
+- Cache key: sha256(tool_name + file_path + content_hash)[:16]
+- Cached verdicts reused within throttle_seconds window
+- Fail-open on timeout/error (configurable)
+"""
+
+from forge.guard.semantic.supervisor import (
+    SemanticSupervisorPolicy,
+    invoke_supervisor,
+)
+from forge.guard.semantic.verdict import (
+    SupervisorVerdict,
+    parse_supervisor_verdict,
+    verdict_to_decision,
+)
+
+__all__ = [
+    "SemanticSupervisorPolicy",
+    "SupervisorVerdict",
+    "invoke_supervisor",
+    "parse_supervisor_verdict",
+    "verdict_to_decision",
+]

forge/guard/semantic/promotion.py

@@ -0,0 +1,18 @@
+"""Supervisor promotion flow (deferred).
+
+The full "CLI-Fork Supervision" pattern from design.md §4.1.2 involves:
+1. Forking the planning session via SessionManager
+2. Establishing supervisor session UUID via claude --fork-session
+3. Recording supervisor configuration in the executor session
+
+The --fork-session flag is available since Claude Code v2.1.77+. The automated
+promotion flow (creating a dedicated supervisor session) is not yet implemented.
+
+Preferred approach (available now):
+    forge session fork planner --name executor --supervise   # At fork time
+    forge guard supervise planner                            # On existing session
+    %guard supervise planner                                 # In-session
+
+Manual approach (still works):
+    forge session set policy.supervisor.resume_id <name-or-uuid>
+"""