cowork-flow 0.0.37 → 0.0.39

package/template/.cowork-flow/scripts/common/gates/gates.py

@@ -1,71 +1,348 @@
 #!/usr/bin/env python3
-"""Shared gate result helpers for cowork-flow lifecycle commands."""
+"""Typed, fail-closed gate pipeline for lifecycle commands."""
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from collections.abc import Mapping
 from pathlib import Path
 
+from .models import (
+    GateContext,
+    GateDefinition,
+    GateExecution,
+    GateResult,
+    ValidatorBinding,
+    Violation,
+)
+from .registry import GateLoadError, GateRegistry
 
-@dataclass
-class GateResult:
-    """Normalized result returned by workflow gates."""
 
-    scope: str
-    task_dir: Path | None = None
-    violations: list[dict] = field(default_factory=list)
+STAGE_GATES = {
+    "task_start": ("runtime_rules",),
+    "task_review": (
+        "implementation",
+        "tdd_evidence",
+        "test_intent",
+        "runtime_rules",
+        "coding_standards",
+        "complexity",
+    ),
+    "task_complete": (
+        "tdd_evidence",
+        "test_intent",
+        "runtime_rules",
+        "coding_standards",
+        "complexity",
+    ),
+}
+
+
+def build_default_registry() -> GateRegistry:
+    registry = GateRegistry()
+    for binding in (
+        ValidatorBinding(
+            key="runtime_rules",
+            module="validate_rules",
+            function="validate_rules",
+            positional=("repo_root", "scope", "task_dir"),
+        ),
+        ValidatorBinding(
+            key="implementation",
+            module="validate_implementation",
+            function="validate_implementation",
+            positional=("repo_root", "task_dir"),
+            keyword={
+                "allow_spec_file_modifications": "allow_spec_file_modifications",
+            },
+        ),
+        ValidatorBinding(
+            key="tdd_evidence",
+            module="tdd_evidence",
+            function="validate_tdd_evidence",
+            positional=("task_dir",),
+        ),
+        ValidatorBinding(
+            key="test_intent",
+            module="test_intent",
+            function="validate_test_intent",
+            positional=("repo_root", "task_dir"),
+        ),
+        ValidatorBinding(
+            key="coding_standards",
+            module="validate_coding_standards",
+            function="validate_coding_standards",
+            positional=("repo_root", "task_dir"),
+        ),
+        ValidatorBinding(
+            key="complexity",
+            module="validate_coding_standards",
+            function="validate_complexity_signals",
+            positional=("repo_root", "task_dir"),
+        ),
+    ):
+        registry.register_validator(binding)
+
+    definitions = (
+        GateDefinition(
+            id="runtime_rules",
+            validator_key="runtime_rules",
+            required=True,
+            block_message="Spec enforcement blocked lifecycle transition",
+            log_violations=True,
+        ),
+        GateDefinition(
+            id="implementation",
+            validator_key="implementation",
+            required=True,
+            block_message="Implementation gate blocked task review",
+            warning_message="Implementation violations detected",
+        ),
+        GateDefinition(
+            id="tdd_evidence",
+            validator_key="tdd_evidence",
+            required=True,
+            block_message="TDD evidence gate blocked lifecycle transition",
+        ),
+        GateDefinition(
+            id="test_intent",
+            validator_key="test_intent",
+            required=True,
+            block_message="Test intent gate blocked lifecycle transition",
+            warning_message="Test intent review warnings",
+        ),
+        GateDefinition(
+            id="coding_standards",
+            validator_key="coding_standards",
+            required=True,
+            block_message="Coding standards gate blocked lifecycle transition",
+        ),
+        GateDefinition(
+            id="complexity",
+            validator_key="complexity",
+            required=False,
+            block_message="",
+            warning_message="Complexity review warnings",
+        ),
+    )
+    for definition in definitions:
+        registry.register_gate(definition)
+    return registry
+
+
+def _pipeline_violation(
+    *,
+    rule_id: str,
+    context: GateContext,
+    definition: GateDefinition,
+    message: str,
+    fix_hint: str,
+) -> dict:
+    severity = "block" if definition.required else "warn"
+    return Violation(
+        rule_id=rule_id,
+        type="gate_pipeline",
+        severity=severity,
+        message=message,
+        file=definition.validator_key,
+        fix_hint=fix_hint,
+        scope=context.scope,
+        gate_id=definition.id,
+        error_code=rule_id,
+    ).to_dict()
 
-    @classmethod
-    def from_violations(
-        cls,
-        scope: str,
-        violations: list[dict],
-        task_dir: Path | None = None,
-    ) -> "GateResult":
-        return cls(scope=scope, task_dir=task_dir, violations=list(violations))
 
-    @property
-    def blockers(self) -> list[dict]:
+def _normalize_violations(
+    raw_result: object,
+    context: GateContext,
+    definition: GateDefinition,
+) -> list[dict]:
+    if not isinstance(raw_result, list):
         return [
-            violation
-            for violation in self.violations
-            if violation.get("severity") == "block"
+            _pipeline_violation(
+                rule_id="GATE-PROTOCOL-001",
+                context=context,
+                definition=definition,
+                message=(
+                    f"Gate {definition.id} returned "
+                    f"{type(raw_result).__name__}; expected a list of violations"
+                ),
+                fix_hint="Return list[dict] from the registered gate validator.",
+            )
         ]
 
-    @property
-    def blocked(self) -> bool:
-        return bool(self.blockers)
-
-    @property
-    def exit_code(self) -> int:
-        return 1 if self.blocked else 0
+    normalized: list[dict] = []
+    for raw_violation in raw_result:
+        if not isinstance(raw_violation, Mapping):
+            normalized.append(
+                _pipeline_violation(
+                    rule_id="GATE-PROTOCOL-001",
+                    context=context,
+                    definition=definition,
+                    message=(
+                        f"Gate {definition.id} returned a non-object violation"
+                    ),
+                    fix_hint="Return violation dictionaries with stable metadata.",
+                )
+            )
+            continue
+        try:
+            normalized.append(
+                Violation.from_mapping(
+                    raw_violation,
+                    scope=context.scope,
+                    gate_id=definition.id,
+                ).to_dict()
+            )
+        except ValueError as error:
+            normalized.append(
+                _pipeline_violation(
+                    rule_id="GATE-PROTOCOL-001",
+                    context=context,
+                    definition=definition,
+                    message=f"Gate {definition.id} returned invalid metadata: {error}",
+                    fix_hint=(
+                        "Return violations with rule_id, severity, and message."
+                    ),
+                )
+            )
+    return normalized
 
 
-class GateRunner:
-    """Run existing validators through a common gate interface."""
+class GatePipeline:
+    """Execute the configured stage gates with fail-closed semantics."""
 
-    def __init__(self, repo_root: Path) -> None:
-        self.repo_root = Path(repo_root)
+    def __init__(self, registry: GateRegistry | None = None) -> None:
+        self.registry = registry or build_default_registry()
 
-    def run(self, scope: str, task_dir: Path | None = None) -> GateResult:
-        from .validate_rules import validate_rules
+    def run(self, context: GateContext) -> GateResult:
+        executions: list[GateExecution] = []
+        priority_violations: list[dict] = []
+        ordinary_violations: list[dict] = []
 
-        normalized_task_dir = Path(task_dir) if task_dir is not None else None
-        violations = validate_rules(self.repo_root, scope, normalized_task_dir)
-        if scope in {"task_review", "task_complete"}:
-            from .validate_coding_standards import validate_coding_standards
+        for gate_id in STAGE_GATES[context.scope]:
+            definition = self.registry.gate(gate_id)
+            try:
+                raw_result = self.registry.invoke(definition, context)
+            except GateLoadError as error:
+                violations = [
+                    _pipeline_violation(
+                        rule_id="GATE-LOAD-001",
+                        context=context,
+                        definition=definition,
+                        message=f"Gate {definition.id} could not load: {error}",
+                        fix_hint=(
+                            "Restore the required validator module and function."
+                        ),
+                    )
+                ]
+            except Exception as error:
+                violations = [
+                    _pipeline_violation(
+                        rule_id="GATE-EXEC-001",
+                        context=context,
+                        definition=definition,
+                        message=f"Gate {definition.id} failed during execution: {error}",
+                        fix_hint=(
+                            "Fix the validator exception; lifecycle gates fail closed."
+                        ),
+                    )
+                ]
+            else:
+                violations = _normalize_violations(
+                    raw_result,
+                    context,
+                    definition,
+                )
 
-            violations.extend(
-                validate_coding_standards(self.repo_root, normalized_task_dir)
+            gate_result = GateResult.from_violations(
+                context.scope,
+                violations,
+                context.task_dir,
+            )
+            executions.append(
+                GateExecution(
+                    definition=definition,
+                    result=gate_result,
+                )
             )
-            from .validate_coding_standards import validate_complexity_signals
+            for violation in gate_result.violations:
+                if str(violation.get("rule_id", "")).startswith("GATE-"):
+                    priority_violations.append(violation)
+                else:
+                    ordinary_violations.append(violation)
+
+        return GateResult(
+            scope=context.scope,
+            task_dir=context.task_dir,
+            violations=[*priority_violations, *ordinary_violations],
+            executions=executions,
+        )
+
 
-            violations.extend(
-                validate_complexity_signals(self.repo_root, normalized_task_dir)
+class GateRunner:
+    """Compatibility facade used by lifecycle commands and tests."""
+
+    def __init__(
+        self,
+        repo_root: Path,
+        registry: GateRegistry | None = None,
+    ) -> None:
+        self.repo_root = Path(repo_root)
+        self.pipeline = GatePipeline(registry)
+
+    def run(
+        self,
+        scope: str,
+        task_dir: Path | None = None,
+        *,
+        allow_spec_file_modifications: bool = False,
+    ) -> GateResult:
+        return self.pipeline.run(
+            GateContext(
+                repo_root=self.repo_root,
+                scope=scope,
+                task_dir=task_dir,
+                allow_spec_file_modifications=allow_spec_file_modifications,
             )
-        return GateResult.from_violations(scope, violations, normalized_task_dir)
+        )
+
+    def coding_standards_summary(self, task_dir: Path | None = None) -> str:
+        module = __import__(
+            "validate_coding_standards",
+            globals(),
+            locals(),
+            ["get_coding_standards_summary"],
+            1,
+        )
+        return module.get_coding_standards_summary(self.repo_root, task_dir)
 
     def log(self, result: GateResult) -> None:
-        from .validate_rules import log_violations
+        try:
+            module = __import__(
+                "validate_rules",
+                globals(),
+                locals(),
+                ["log_violations"],
+                1,
+            )
+        except ImportError:
+            return
+        module.log_violations(
+            result.violations,
+            result.scope,
+            result.task_dir,
+            self.repo_root,
+        )
+
 
-        log_violations(result.violations, result.scope, result.task_dir, self.repo_root)
+__all__ = [
+    "GateContext",
+    "GateDefinition",
+    "GateExecution",
+    "GatePipeline",
+    "GateRegistry",
+    "GateResult",
+    "GateRunner",
+    "Violation",
+    "build_default_registry",
+]

package/template/.cowork-flow/scripts/common/gates/models.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Typed models shared by the cowork-flow gate pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping
+
+
+GATE_SCOPES = frozenset({"task_start", "task_review", "task_complete"})
+GATE_SEVERITIES = frozenset({"block", "warn", "advisory"})
+
+
+@dataclass(frozen=True)
+class GateContext:
+    """Runtime inputs available to every gate validator."""
+
+    repo_root: Path
+    scope: str
+    task_dir: Path | None = None
+    allow_spec_file_modifications: bool = False
+
+    def __post_init__(self) -> None:
+        if self.scope not in GATE_SCOPES:
+            raise ValueError(f"unsupported gate scope: {self.scope}")
+        object.__setattr__(self, "repo_root", Path(self.repo_root))
+        if self.task_dir is not None:
+            object.__setattr__(self, "task_dir", Path(self.task_dir))
+
+
+@dataclass(frozen=True)
+class ValidatorBinding:
+    """Lazy module/function binding plus its GateContext argument mapping."""
+
+    key: str
+    module: str
+    function: str
+    positional: tuple[str, ...] = ()
+    keyword: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GateDefinition:
+    """Declarative gate definition registered once and reused by stages."""
+
+    id: str
+    validator_key: str
+    required: bool
+    block_message: str
+    warning_message: str | None = None
+    log_violations: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.id.strip():
+            raise ValueError("gate id must be non-empty")
+        if not self.validator_key.strip():
+            raise ValueError(f"gate {self.id} validator_key must be non-empty")
+        if self.required and not self.block_message.strip():
+            raise ValueError(f"required gate {self.id} needs a block message")
+
+
+@dataclass(frozen=True)
+class Violation:
+    """Stable typed representation of a validator failure."""
+
+    rule_id: str
+    type: str
+    severity: str
+    message: str
+    file: str
+    fix_hint: str
+    scope: str
+    gate_id: str
+    passed: bool = False
+    error_code: str | None = None
+    extra: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.rule_id.strip():
+            raise ValueError("violation rule_id must be non-empty")
+        if self.severity not in GATE_SEVERITIES:
+            raise ValueError(f"unsupported violation severity: {self.severity}")
+        if self.scope not in GATE_SCOPES:
+            raise ValueError(f"unsupported violation scope: {self.scope}")
+
+    @classmethod
+    def from_mapping(
+        cls,
+        raw: Mapping[str, object],
+        *,
+        scope: str,
+        gate_id: str,
+    ) -> "Violation":
+        rule_id = str(raw.get("rule_id") or raw.get("id") or "").strip()
+        severity = str(raw.get("severity") or "").strip()
+        message = str(raw.get("message") or "").strip()
+        if not rule_id or not severity or not message:
+            raise ValueError("validator violation must define rule_id, severity, and message")
+
+        known_fields = {
+            "rule_id",
+            "id",
+            "type",
+            "severity",
+            "message",
+            "file",
+            "fix_hint",
+            "scope",
+            "gate_id",
+            "passed",
+            "error_code",
+        }
+        extra = {key: value for key, value in raw.items() if key not in known_fields}
+        return cls(
+            rule_id=rule_id,
+            type=str(raw.get("type") or "gate"),
+            severity=severity,
+            message=message,
+            file=str(raw.get("file") or ""),
+            fix_hint=str(raw.get("fix_hint") or ""),
+            scope=scope,
+            gate_id=gate_id,
+            passed=bool(raw.get("passed", False)),
+            error_code=str(raw.get("error_code") or rule_id),
+            extra=extra,
+        )
+
+    def to_dict(self) -> dict:
+        result = {
+            "rule_id": self.rule_id,
+            "type": self.type,
+            "severity": self.severity,
+            "passed": self.passed,
+            "message": self.message,
+            "file": self.file,
+            "fix_hint": self.fix_hint,
+            "scope": self.scope,
+            "gate_id": self.gate_id,
+            "error_code": self.error_code or self.rule_id,
+        }
+        result.update(self.extra)
+        return result
+
+
+@dataclass
+class GateResult:
+    """Normalized aggregate or per-gate result."""
+
+    scope: str
+    task_dir: Path | None = None
+    violations: list[dict] = field(default_factory=list)
+    executions: list["GateExecution"] = field(default_factory=list)
+
+    @classmethod
+    def from_violations(
+        cls,
+        scope: str,
+        violations: list[dict],
+        task_dir: Path | None = None,
+    ) -> "GateResult":
+        normalized = []
+        for violation in violations:
+            item = dict(violation)
+            item.setdefault("scope", scope)
+            item.setdefault("error_code", item.get("rule_id") or item.get("id"))
+            normalized.append(item)
+        return cls(scope=scope, task_dir=task_dir, violations=normalized)
+
+    @property
+    def blockers(self) -> list[dict]:
+        return [
+            violation
+            for violation in self.violations
+            if violation.get("severity") == "block"
+        ]
+
+    @property
+    def blocked(self) -> bool:
+        return bool(self.blockers)
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if self.blocked else 0
+
+
+@dataclass(frozen=True)
+class GateExecution:
+    """One gate definition evaluated within a pipeline stage."""
+
+    definition: GateDefinition
+    result: GateResult
+
+    @property
+    def blocked(self) -> bool:
+        return self.result.blocked

package/template/.cowork-flow/scripts/common/gates/registry.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Gate definition and validator registry."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from collections.abc import Callable
+
+from .models import GateContext, GateDefinition, ValidatorBinding
+
+
+class GateRegistryError(ValueError):
+    """Raised when registry declarations are internally inconsistent."""
+
+
+class GateLoadError(RuntimeError):
+    """Raised when a registered validator cannot be loaded."""
+
+
+class GateRegistry:
+    """Register gate definitions and lazily resolve validator functions."""
+
+    def __init__(self) -> None:
+        self._bindings: OrderedDict[str, ValidatorBinding] = OrderedDict()
+        self._definitions: OrderedDict[str, GateDefinition] = OrderedDict()
+
+    def register_validator(self, binding: ValidatorBinding) -> None:
+        if not binding.key.strip():
+            raise GateRegistryError("validator key must be non-empty")
+        if binding.key in self._bindings:
+            raise GateRegistryError(f"duplicate validator key: {binding.key}")
+        self._bindings[binding.key] = binding
+
+    def register_gate(self, definition: GateDefinition) -> None:
+        if definition.id in self._definitions:
+            raise GateRegistryError(f"duplicate gate id: {definition.id}")
+        if definition.validator_key not in self._bindings:
+            raise GateRegistryError(
+                f"gate {definition.id} references unknown validator: "
+                f"{definition.validator_key}"
+            )
+        self._definitions[definition.id] = definition
+
+    def gate(self, gate_id: str) -> GateDefinition:
+        try:
+            return self._definitions[gate_id]
+        except KeyError as error:
+            raise GateRegistryError(f"unknown gate id: {gate_id}") from error
+
+    def invoke(self, definition: GateDefinition, context: GateContext) -> object:
+        binding = self._bindings[definition.validator_key]
+        validator = self._load(binding)
+        args = [getattr(context, name) for name in binding.positional]
+        kwargs = {
+            argument: getattr(context, context_field)
+            for argument, context_field in binding.keyword.items()
+        }
+        return validator(*args, **kwargs)
+
+    @staticmethod
+    def _load(binding: ValidatorBinding) -> Callable:
+        try:
+            module = __import__(
+                binding.module,
+                globals(),
+                locals(),
+                [binding.function],
+                1,
+            )
+            validator = getattr(module, binding.function)
+        except (ImportError, AttributeError) as error:
+            raise GateLoadError(
+                f"{binding.module}.{binding.function}: {error}"
+            ) from error
+        if not callable(validator):
+            raise GateLoadError(
+                f"{binding.module}.{binding.function} is not callable"
+            )
+        return validator