arkaos 2.17.1 → 2.17.4

package/core/governance/quality_api.py

@@ -0,0 +1,280 @@
+"""Quality Gate API — submit deliverables, query status, record verdicts.
+
+Provides a simple programmatic interface for the Quality Gate system:
+- submit() — submit a deliverable for review
+- query() — check status of a submission
+- verdict() — record a reviewer's verdict
+- list_pending() — get all pending reviews
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from core.governance.quality_router import (
+    QualityRouter,
+    ReviewAssignment,
+    ReviewerType,
+    DeliverableType,
+    ReviewPriority,
+    route_deliverable,
+)
+from core.governance.review_workflow import (
+    ReviewWorkflowEngine,
+    ReviewWorkflow,
+    ReviewPhase,
+    Verdict,
+    ReviewerOpinion,
+)
+
+
+_STATE_DIR = Path.home() / ".arkaos" / "quality-gate"
+_QUEUE_FILE = _STATE_DIR / "queue.json"
+_WORKFLOWS_FILE = _STATE_DIR / "workflows.json"
+
+
+def _ensure_state_dir() -> None:
+    _STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load_queue() -> list[dict]:
+    _ensure_state_dir()
+    if not _QUEUE_FILE.exists():
+        return []
+    try:
+        return json.loads(_QUEUE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def _save_queue(queue: list[dict]) -> None:
+    _ensure_state_dir()
+    _QUEUE_FILE.write_text(json.dumps(queue, indent=2))
+
+
+def _load_workflows() -> list[dict]:
+    _ensure_state_dir()
+    if not _WORKFLOWS_FILE.exists():
+        return []
+    try:
+        return json.loads(_WORKFLOWS_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def _save_workflows(workflows: list[dict]) -> None:
+    _ensure_state_dir()
+    _WORKFLOWS_FILE.write_text(json.dumps(workflows, indent=2))
+
+
+def submit(
+    title: str,
+    description: str,
+    deliverable_type: str | None = None,
+    submitter: str = "unknown",
+    metadata: dict | None = None,
+) -> dict[str, Any]:
+    """Submit a deliverable for Quality Gate review.
+
+    Args:
+        title: Deliverable title
+        description: Brief description
+        deliverable_type: Type as string (auto-detected if None)
+        submitter: Agent ID of submitter
+        metadata: Additional context
+
+    Returns:
+        Dict with submission_id, reviewers, priority, and estimated_sla
+    """
+    detype = DeliverableType(deliverable_type) if deliverable_type else None
+
+    router = QualityRouter()
+    assignment = router.route(title, description, detype, submitter, metadata)
+
+    queue = _load_queue()
+    queue.append(
+        {
+            "id": assignment.id,
+            "title": assignment.title,
+            "deliverable_type": assignment.deliverable_type.value,
+            "submitter": assignment.submitter,
+            "reviewers": [r.value for r in assignment.reviewers],
+            "priority": assignment.priority.value,
+            "status": assignment.status,
+            "submitted_at": assignment.submitted_at,
+            "sla_due": assignment.sla_due,
+        }
+    )
+    _save_queue(queue)
+
+    return {
+        "submission_id": assignment.id,
+        "reviewers": [r.value for r in assignment.reviewers],
+        "priority": assignment.priority.value,
+        "estimated_sla": assignment.sla_due,
+        "deliverable_type": assignment.deliverable_type.value,
+    }
+
+
+def query(submission_id: str) -> dict[str, Any] | None:
+    """Query the status of a submission.
+
+    Args:
+        submission_id: ID returned from submit()
+
+    Returns:
+        Status dict or None if not found
+    """
+    queue = _load_queue()
+    for item in queue:
+        if item["id"] == submission_id:
+            return item
+
+    workflows = _load_workflows()
+    for wf in workflows:
+        if wf["id"] == submission_id:
+            return wf
+
+    return None
+
+
+def record_verdict(
+    submission_id: str,
+    reviewer: str,
+    verdict: str,
+    feedback: str = "",
+    flagged_rules: list[str] | None = None,
+) -> bool:
+    """Record a reviewer's verdict for a submission.
+
+    Args:
+        submission_id: ID of the submission
+        reviewer: Agent ID of reviewer
+        verdict: APPROVED, REJECTED, REQUEST_CHANGES, or ESCALATE
+        feedback: Feedback for the submitter
+        flagged_rules: List of Constitution rules violated
+
+    Returns:
+        True if verdict recorded successfully
+    """
+    reviewer_type = ReviewerType(reviewer) if reviewer in [r.value for r in ReviewerType] else None
+
+    queue = _load_queue()
+    for item in queue:
+        if item["id"] == submission_id:
+            item["status"] = "reviewed"
+            item["verdict"] = verdict
+            item["feedback"] = feedback
+            item["flagged_rules"] = flagged_rules or []
+            _save_queue(queue)
+            return True
+
+    return False
+
+
+def list_pending(reviewer: str | None = None) -> list[dict]:
+    """List all pending submissions.
+
+    Args:
+        reviewer: If set, only show items pending for this reviewer
+
+    Returns:
+        List of pending submission dicts
+    """
+    queue = _load_queue()
+    pending = [item for item in queue if item["status"] == "pending"]
+
+    if reviewer:
+        pending = [item for item in pending if reviewer in item.get("reviewers", [])]
+
+    return pending
+
+
+def list_approved(limit: int = 10) -> list[dict]:
+    """List recently approved submissions.
+
+    Args:
+        limit: Maximum number to return
+
+    Returns:
+        List of approved submission dicts
+    """
+    queue = _load_queue()
+    approved = [
+        item
+        for item in queue
+        if item.get("status") == "reviewed" and item.get("verdict") == "APPROVED"
+    ]
+    return approved[:limit]
+
+
+def clear_resolved(older_than_days: int = 7) -> int:
+    """Remove resolved submissions older than specified days.
+
+    Args:
+        older_than_days: Remove items resolved more than this many days ago
+
+    Returns:
+        Number of items removed
+    """
+    from datetime import datetime, timedelta, timezone
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=older_than_days)
+    queue = _load_queue()
+    original_count = len(queue)
+
+    remaining = []
+    for item in queue:
+        if item["status"] == "pending":
+            remaining.append(item)
+            continue
+
+        verdict_at = item.get("verdict_at", item.get("submitted_at", ""))
+        try:
+            dt = datetime.fromisoformat(verdict_at.replace("Z", "+00:00"))
+            if dt > cutoff:
+                remaining.append(item)
+        except (ValueError, TypeError, AttributeError):
+            remaining.append(item)
+
+    _save_queue(remaining)
+    return original_count - len(remaining)
+
+
+class QualityGateAPI:
+    """Class-based API for Quality Gate operations."""
+
+    def __init__(self):
+        _ensure_state_dir()
+
+    def submit(
+        self,
+        title: str,
+        description: str,
+        deliverable_type: str | None = None,
+        submitter: str = "unknown",
+        metadata: dict | None = None,
+    ) -> dict[str, Any]:
+        return submit(title, description, deliverable_type, submitter, metadata)
+
+    def query(self, submission_id: str) -> dict[str, Any] | None:
+        return query(submission_id)
+
+    def record_verdict(
+        self,
+        submission_id: str,
+        reviewer: str,
+        verdict: str,
+        feedback: str = "",
+        flagged_rules: list[str] | None = None,
+    ) -> bool:
+        return record_verdict(submission_id, reviewer, verdict, feedback, flagged_rules)
+
+    def list_pending(self, reviewer: str | None = None) -> list[dict]:
+        return list_pending(reviewer)
+
+    def list_approved(self, limit: int = 10) -> list[dict]:
+        return list_approved(limit)
+
+    def clear_resolved(self, older_than_days: int = 7) -> int:
+        return clear_resolved(older_than_days)

package/core/governance/quality_router.py

@@ -0,0 +1,304 @@
+"""Quality Gate Router — auto-routes deliverables to appropriate reviewers.
+
+Routes deliverables to:
+- Marta (CQO): Architecture, security, technical decisions
+- Eduardo (Copy): All text, copy, documentation, content
+- Francisca (Tech UX): UI/UX, frontend, user-facing code
+
+Features:
+- Automatic routing based on deliverable type
+- Priority queuing
+- SLA tracking (24h default)
+- Escalation on BLOCK violations
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class ReviewerType(str, Enum):
+    CQO = "cqo-marta"  # Marta - Chief Quality Officer
+    COPY = "copy-eduardo"  # Eduardo - Copy Director
+    TECH_UX = "tech-francisca"  # Francisca - Tech UX
+
+
+class DeliverableType(str, Enum):
+    CODE = "code"  # Backend/API code
+    FRONTEND = "frontend"  # UI/UX, Vue/React
+    ARCHITECTURE = "architecture"  # ADRs, system design
+    SECURITY = "security"  # Security audits, auth
+    COPY = "copy"  # Text, docs, content
+    DOCUMENTATION = "documentation"  # Docs, READMEs
+    STRATEGY = "strategy"  # Plans, roadmaps
+    DATA = "data"  # Models, migrations
+
+
+class ReviewPriority(str, Enum):
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    URGENT = "urgent"
+
+
+@dataclass
+class ReviewAssignment:
+    """A deliverable assigned for review."""
+
+    id: str
+    deliverable_type: DeliverableType
+    title: str
+    description: str
+    submitter: str
+    submitted_at: str
+    reviewers: list[ReviewerType]
+    priority: ReviewPriority = ReviewPriority.NORMAL
+    status: str = "pending"
+    verdict: str = ""
+    feedback: str = ""
+    sla_due: str = ""
+    metadata: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.sla_due:
+            self.sla_due = (datetime.now(timezone.utc) + timedelta(hours=24)).isoformat()
+
+
+@dataclass
+class RoutingRule:
+    """A rule for routing deliverables to reviewers."""
+
+    deliverable_types: list[DeliverableType]
+    keywords: list[str]
+    file_extensions: list[str]
+    reviewers: list[ReviewerType]
+    priority: ReviewPriority = ReviewPriority.NORMAL
+
+
+DEFAULT_ROUTING_RULES: list[RoutingRule] = [
+    RoutingRule(
+        deliverable_types=[DeliverableType.ARCHITECTURE],
+        keywords=["architecture", "adr", "system design", "decision"],
+        file_extensions=[".md"],
+        reviewers=[ReviewerType.CQO],
+        priority=ReviewPriority.HIGH,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.SECURITY],
+        keywords=["security", "auth", "permission", "oauth", "jwt"],
+        file_extensions=[],
+        reviewers=[ReviewerType.CQO, ReviewerType.TECH_UX],
+        priority=ReviewPriority.URGENT,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.FRONTEND],
+        keywords=["vue", "react", "ui", "component", "tailwind", "css"],
+        file_extensions=[".vue", ".tsx", ".jsx"],
+        reviewers=[ReviewerType.TECH_UX],
+        priority=ReviewPriority.NORMAL,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.CODE],
+        keywords=["api", "backend", "service", "model", "controller"],
+        file_extensions=[".py", ".php", ".java", ".go"],
+        reviewers=[ReviewerType.CQO],
+        priority=ReviewPriority.NORMAL,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.COPY],
+        keywords=["copy", "headline", "cta", "landing", "sales"],
+        file_extensions=[],
+        reviewers=[ReviewerType.COPY],
+        priority=ReviewPriority.NORMAL,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.DOCUMENTATION],
+        keywords=["doc", "readme", "guide", "docs"],
+        file_extensions=[".md", ".txt"],
+        reviewers=[ReviewerType.COPY, ReviewerType.TECH_UX],
+        priority=ReviewPriority.LOW,
+    ),
+    RoutingRule(
+        deliverable_types=[DeliverableType.STRATEGY],
+        keywords=["roadmap", "strategy", "plan", "okr", "kpi"],
+        file_extensions=[".md"],
+        reviewers=[ReviewerType.CQO, ReviewerType.COPY],
+        priority=ReviewPriority.HIGH,
+    ),
+]
+
+
+class QualityRouter:
+    """Routes deliverables to appropriate Quality Gate reviewers."""
+
+    def __init__(self, rules: list[RoutingRule] | None = None):
+        self.rules = rules or DEFAULT_ROUTING_RULES
+        self._queue: list[ReviewAssignment] = []
+
+    def route(
+        self,
+        title: str,
+        description: str,
+        deliverable_type: DeliverableType | None = None,
+        submitter: str = "unknown",
+        metadata: dict | None = None,
+    ) -> ReviewAssignment:
+        """Route a deliverable to appropriate reviewers.
+
+        Args:
+            title: Deliverable title
+            description: Brief description
+            deliverable_type: Explicit type (auto-detected if None)
+            submitter: Agent ID of submitter
+            metadata: Additional context
+
+        Returns:
+            ReviewAssignment with assigned reviewers
+        """
+        if deliverable_type is None:
+            deliverable_type = self._detect_type(title, description, metadata)
+
+        reviewers = self._find_reviewers(deliverable_type, title, description, metadata)
+        priority = self._find_priority(deliverable_type, title, description)
+
+        assignment = ReviewAssignment(
+            id=str(uuid.uuid4()),
+            deliverable_type=deliverable_type,
+            title=title,
+            description=description,
+            submitter=submitter,
+            submitted_at=datetime.now(timezone.utc).isoformat(),
+            reviewers=reviewers,
+            priority=priority,
+            metadata=metadata or {},
+        )
+
+        self._queue.append(assignment)
+        return assignment
+
+    def _detect_type(
+        self,
+        title: str,
+        description: str,
+        metadata: dict | None,
+    ) -> DeliverableType:
+        """Auto-detect deliverable type from content."""
+        text = f"{title} {description}".lower()
+        metadata = metadata or {}
+
+        if any(kw in text for kw in ["security", "auth", "permission", "oauth"]):
+            return DeliverableType.SECURITY
+        if any(kw in text for kw in ["architecture", "adr", "system design"]):
+            return DeliverableType.ARCHITECTURE
+        if any(kw in text for kw in ["vue", "react", "ui", "component", "frontend"]):
+            return DeliverableType.FRONTEND
+        if any(kw in text for kw in ["api", "backend", "service", "model"]):
+            return DeliverableType.CODE
+        if any(kw in text for kw in ["copy", "headline", "cta", "sales", "landing"]):
+            return DeliverableType.COPY
+        if any(kw in text for kw in ["doc", "readme", "guide"]):
+            return DeliverableType.DOCUMENTATION
+        if any(kw in text for kw in ["roadmap", "strategy", "plan"]):
+            return DeliverableType.STRATEGY
+
+        if metadata.get("file_path"):
+            ext = Path(metadata["file_path"]).suffix.lower()
+            if ext in [".vue", ".tsx", ".jsx"]:
+                return DeliverableType.FRONTEND
+            if ext in [".py", ".php", ".java", ".go"]:
+                return DeliverableType.CODE
+
+        return DeliverableType.CODE
+
+    def _find_reviewers(
+        self,
+        deliverable_type: DeliverableType,
+        title: str,
+        description: str,
+        metadata: dict | None,
+    ) -> list[ReviewerType]:
+        """Find appropriate reviewers for this deliverable."""
+        for rule in self.rules:
+            if deliverable_type in rule.deliverable_types:
+                return rule.reviewers
+
+        return [ReviewerType.CQO]
+
+    def _find_priority(
+        self,
+        deliverable_type: DeliverableType,
+        title: str,
+        description: str,
+    ) -> ReviewPriority:
+        """Determine review priority."""
+        text = f"{title} {description}".lower()
+
+        if any(kw in text for kw in ["urgent", "asap", "critical", "blocker"]):
+            return ReviewPriority.URGENT
+
+        for rule in self.rules:
+            if deliverable_type in rule.deliverable_types:
+                return rule.priority
+
+        return ReviewPriority.NORMAL
+
+    def get_queue(self) -> list[ReviewAssignment]:
+        """Get current review queue."""
+        return self._queue.copy()
+
+    def get_pending_for_reviewer(self, reviewer: ReviewerType) -> list[ReviewAssignment]:
+        """Get pending items for a specific reviewer."""
+        return [a for a in self._queue if reviewer in a.reviewers and a.status == "pending"]
+
+    def get_assignment(self, assignment_id: str) -> ReviewAssignment | None:
+        """Get a specific assignment by ID."""
+        for a in self._queue:
+            if a.id == assignment_id:
+                return a
+        return None
+
+    def update_verdict(
+        self,
+        assignment_id: str,
+        verdict: str,
+        feedback: str,
+        reviewer: ReviewerType,
+    ) -> ReviewAssignment | None:
+        """Record a verdict for an assignment."""
+        assignment = self.get_assignment(assignment_id)
+        if not assignment:
+            return None
+
+        if reviewer not in assignment.reviewers:
+            return None
+
+        assignment.verdict = verdict
+        assignment.feedback = feedback
+        assignment.status = "reviewed"
+        return assignment
+
+    def is_sla_breached(self, assignment: ReviewAssignment) -> bool:
+        """Check if an assignment has breached SLA."""
+        try:
+            due = datetime.fromisoformat(assignment.sla_due)
+            return datetime.now(timezone.utc) > due
+        except (ValueError, TypeError):
+            return False
+
+    def get_breached_items(self) -> list[ReviewAssignment]:
+        """Get all assignments that have breached SLA."""
+        return [a for a in self._queue if self.is_sla_breached(a) and a.status == "pending"]
+
+
+def route_deliverable(
+    title: str,
+    description: str,
+    deliverable_type: DeliverableType | None = None,
+    submitter: str = "unknown",
+) -> ReviewAssignment:
+    """Convenience function to route a deliverable."""
+    router = QualityRouter()
+    return router.route(title, description, deliverable_type, submitter)