ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/compliance_remediation.py

@@ -0,0 +1,846 @@
+"""Compliance Remediation Workflow.
+
+Autonomous compliance fix pipeline with three-tier classification.
+
+Tier 1: ruff-delegated fixes. Executed directly by MCP server. No LLM required.
+Tier 2: Single approval gate. LLM agent executes with PR Reviewer gate.
+Tier 3: Always HALT. Architectural/security decisions require user.
+
+Design principles:
+- start_remediation() reads health_report.json from disk. Never parses summary strings.
+- execute_remediation(tier1) runs ruff fixes directly and returns verified results.
+- execute_remediation(tier2) returns structured work order for developer/architect agent.
+- All state persisted to .ref_cache/remediation/ as JSON.
+"""
+
+import json
+import re
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+import structlog
+
+from ref_agents.constants import Status
+from ref_agents.utils.git_utils import get_ref_cache_dir
+
+logger = structlog.get_logger(__name__)
+
+
+class RemediationTier(str, Enum):
+    TIER1 = "tier1"
+    TIER2 = "tier2"
+    TIER3 = "tier3"
+
+
+class ViolationStatus(str, Enum):
+    PENDING = "pending"
+    AUTO_FIXED = "auto_fixed"
+    AWAITING_APPROVAL = "awaiting_approval"
+    APPROVED = "approved"
+    DEFERRED = "deferred"
+    FAILED = "failed"
+
+
+class RemediationStatus(str, Enum):
+    INITIALISED = "initialised"
+    TIER1_RUNNING = "tier1_running"
+    TIER1_COMPLETE = "tier1_complete"
+    TIER2_AWAITING_APPROVAL = "tier2_awaiting_approval"
+    TIER2_RUNNING = "tier2_running"
+    TIER2_COMPLETE = "tier2_complete"
+    TIER3_HALTED = "tier3_halted"
+    COMPLETE = "complete"
+
+
+# Rule ID -> (tier, responsible_agent, fix_description)
+# Tier 1: ruff-fixable only. No custom AST transforms.
+VIOLATION_CLASSIFICATION: dict[str, tuple[RemediationTier, str, str]] = {
+    "bare_except": (
+        RemediationTier.TIER1,
+        "developer",
+        "ruff E722: replace bare except with specific exception",
+    ),
+    "print_statement": (
+        RemediationTier.TIER1,
+        "developer",
+        "ruff T201: remove print() statement",
+    ),
+    "unused_imports": (
+        RemediationTier.TIER1,
+        "developer",
+        "ruff F401: remove unused imports",
+    ),
+    "import_organisation": (
+        RemediationTier.TIER1,
+        "developer",
+        "ruff I001: reorder imports stdlib > third-party > local",
+    ),
+    "fstring_in_logger": (
+        RemediationTier.TIER1,
+        "developer",
+        "ruff G004: replace f-string in logger with structured args",
+    ),
+    "missing_type_hints": (
+        RemediationTier.TIER2,
+        "developer",
+        "Add type hints to function signatures",
+    ),
+    "missing_docstring": (
+        RemediationTier.TIER2,
+        "developer",
+        "Add Google-style docstring with Args/Returns sections",
+    ),
+    "standard_logging": (
+        RemediationTier.TIER2,
+        "developer",
+        "Replace logging.* with structlog",
+    ),
+    "complexity_violation": (
+        RemediationTier.TIER2,
+        "architect",
+        "Refactor function to reduce cyclomatic complexity below 15",
+    ),
+    "dead_code": (RemediationTier.TIER2, "developer", "Remove confirmed dead code"),
+    "ai_pattern": (RemediationTier.TIER2, "developer", "Refactor AI anti-pattern"),
+    "missing_zod_validation": (
+        RemediationTier.TIER2,
+        "developer",
+        "Add Zod schema for external input validation",
+    ),
+    "missing_test_coverage": (
+        RemediationTier.TIER2,
+        "tester",
+        "Write tests to bring coverage above 85%",
+    ),
+    "docstring_fluff": (
+        RemediationTier.TIER2,
+        "developer",
+        "Remove AI fluff phrases from docstring",
+    ),
+    "security_violation": (
+        RemediationTier.TIER3,
+        "security_owner",
+        "Security violation — HALT, user decision required",
+    ),
+    "complexity_critical": (
+        RemediationTier.TIER3,
+        "architect",
+        "Complexity > 30 — full redesign required, not refactor",
+    ),
+    "regression_risk_high": (
+        RemediationTier.TIER3,
+        "architect",
+        "High regression risk — architectural review required",
+    ),
+    "integration_boundary": (
+        RemediationTier.TIER3,
+        "architect",
+        "Touches external integration boundary",
+    ),
+    "cross_module_dependency": (
+        RemediationTier.TIER3,
+        "architect",
+        "Fix requires changes across module boundaries",
+    ),
+}
+
+# Scanner rule codes -> REF rule IDs
+SCANNER_RULE_MAP: dict[str, str] = {
+    "E001": "bare_except",
+    "E002": "bare_except",
+    "T001": "missing_type_hints",
+    "D001": "missing_docstring",
+    "D002": "missing_docstring",
+    "D003": "missing_docstring",
+    "D004": "missing_docstring",
+    "L001": "print_statement",
+    "L002": "standard_logging",
+    "L003": "fstring_in_logger",
+    "I001": "import_organisation",
+    "F401": "unused_imports",
+}
+
+COMPLEXITY_TIER3_THRESHOLD = 30
+
+
+@dataclass
+class Violation:
+    id: str
+    rule: str
+    file: str
+    line: int
+    message: str
+    severity: str
+    tier: RemediationTier
+    responsible_agent: str
+    fix_description: str
+    scanner: str = ""
+    status: ViolationStatus = ViolationStatus.PENDING
+    fix_notes: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            **asdict(self),
+            "tier": self.tier.value,
+            "status": self.status.value,
+        }
+
+
+@dataclass
+class Tier2Batch:
+    id: str
+    violations: list[str] = field(default_factory=list)
+    summary: str = ""
+    approved: bool = False
+    approved_at: str = ""
+
+
+@dataclass
+class RemediationSession:
+    session_id: str
+    story_id: str
+    directory: str
+    status: RemediationStatus = RemediationStatus.INITIALISED
+    violations: dict[str, dict] = field(default_factory=dict)
+    tier2_batch: dict | None = None
+    tier3_violations: list[str] = field(default_factory=list)
+    created_at: str = ""
+    updated_at: str = ""
+    stats: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        now = datetime.now().isoformat()
+        if not self.created_at:
+            self.created_at = now
+        self.updated_at = now
+
+
+def _session_path(session_id: str) -> Path:
+    cache = get_ref_cache_dir() / "remediation"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache / f"{session_id}.json"
+
+
+def _active_session_path() -> Path:
+    cache = get_ref_cache_dir() / "remediation"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache / "active.json"
+
+
+def _save_session(session: RemediationSession) -> None:
+    session.updated_at = datetime.now().isoformat()
+    data = asdict(session)
+    data["status"] = session.status.value
+    _session_path(session.session_id).write_text(
+        json.dumps(data, indent=2), encoding="utf-8"
+    )
+    _active_session_path().write_text(
+        json.dumps({"session_id": session.session_id, "story_id": session.story_id}),
+        encoding="utf-8",
+    )
+
+
+def _load_session(session_id: str) -> RemediationSession | None:
+    path = _session_path(session_id)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        data["status"] = RemediationStatus(data["status"])
+        return RemediationSession(**data)
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        logger.error("session_load_failed", session_id=session_id, error=str(e))
+        return None
+
+
+def _load_active_session() -> RemediationSession | None:
+    path = _active_session_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return _load_session(data["session_id"])
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def _find_health_report_json(directory: str) -> Path | None:
+    """Locate health_report.json for the given project directory."""
+    candidates = [
+        Path(directory) / "ref-reports" / "platform_engineer" / "health_report.json",
+    ]
+    try:
+        from ref_agents.session import SessionManager
+
+        root = SessionManager.get().project_root
+        if root:
+            candidates.append(
+                root / "ref-reports" / "platform_engineer" / "health_report.json"
+            )
+    except (ImportError, AttributeError):
+        pass
+    for path in candidates:
+        if path.exists():
+            logger.info("health_report_found", path=str(path))
+            return path
+    logger.warning("health_report_not_found", directory=directory)
+    return None
+
+
+def _load_violations_from_json(report_path: Path) -> list[dict]:
+    """Load structured findings from health_report.json."""
+    try:
+        data = json.loads(report_path.read_text(encoding="utf-8"))
+        findings = data.get("findings", [])
+        logger.info("findings_loaded", count=len(findings))
+        return findings
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error("health_report_read_failed", path=str(report_path), error=str(e))
+        return []
+
+
+def _classify_finding(finding: dict) -> tuple[RemediationTier, str, str]:
+    """Classify a health finding into a remediation tier."""
+    rule_code = finding.get("rule", "")
+    severity = finding.get("severity", "medium").lower()
+    scanner = finding.get("scanner", "")
+    message = finding.get("message", "").lower()
+
+    # Direct rule code mapping
+    ref_rule = SCANNER_RULE_MAP.get(rule_code)
+    if ref_rule and ref_rule in VIOLATION_CLASSIFICATION:
+        return VIOLATION_CLASSIFICATION[ref_rule]
+
+    # Complexity scanner
+    if scanner == "complexity":
+        score_match = re.search(r"complexity\s+(\d+)", message)
+        if score_match and int(score_match.group(1)) > COMPLEXITY_TIER3_THRESHOLD:
+            return VIOLATION_CLASSIFICATION["complexity_critical"]
+        return VIOLATION_CLASSIFICATION["complexity_violation"]
+
+    # Message heuristics
+    if "bare except" in message:
+        return VIOLATION_CLASSIFICATION["bare_except"]
+    if "print(" in message:
+        return VIOLATION_CLASSIFICATION["print_statement"]
+    if "unused import" in message:
+        return VIOLATION_CLASSIFICATION["unused_imports"]
+    if "import order" in message:
+        return VIOLATION_CLASSIFICATION["import_organisation"]
+    if "f-string" in message and "log" in message:
+        return VIOLATION_CLASSIFICATION["fstring_in_logger"]
+    if "type hint" in message or "return type" in message:
+        return VIOLATION_CLASSIFICATION["missing_type_hints"]
+    if "docstring" in message:
+        return VIOLATION_CLASSIFICATION["missing_docstring"]
+    if "security" in message or "vulnerabilit" in message:
+        return VIOLATION_CLASSIFICATION["security_violation"]
+    if "dead code" in message:
+        return VIOLATION_CLASSIFICATION["dead_code"]
+
+    # Severity fallback
+    if severity == "critical":
+        return (
+            RemediationTier.TIER3,
+            "architect",
+            "Critical violation — manual review required",
+        )
+    if severity == "high":
+        return (
+            RemediationTier.TIER2,
+            "developer",
+            "High severity violation — review before fixing",
+        )
+    return (
+        RemediationTier.TIER1,
+        "developer",
+        "Apply standard fix per REF quality protocol",
+    )
+
+
+def _get_ref_rule_id(finding: dict) -> str:
+    rule_code = finding.get("rule", "")
+    return SCANNER_RULE_MAP.get(rule_code, rule_code or "unknown")
+
+
+def start_remediation(
+    story_id: str,
+    directory: str,
+    scan_output: str = "",
+) -> str:
+    """Initialise a remediation session from health_report.json.
+
+    Reads violations from the JSON report on disk. Does not parse
+    the scan summary string.
+
+    Args:
+        story_id: Active story identifier.
+        directory: Project directory that was scanned.
+        scan_output: Ignored. Kept for API compatibility.
+
+    Returns:
+        Remediation plan with tier breakdown and session ID.
+    """
+    session_id = f"REM-{str(uuid.uuid4())[:8].upper()}"
+
+    report_path = _find_health_report_json(directory)
+    if not report_path:
+        return (
+            f"{Status.ERROR} health_report.json not found for: {directory}\n"
+            f'Run `scan(target="health", directory="{directory}")` first.'
+        )
+
+    raw_findings = _load_violations_from_json(report_path)
+    if not raw_findings:
+        return (
+            f"{Status.WARNING} No findings in health_report.json. Nothing to remediate."
+        )
+
+    classified: dict[str, dict] = {}
+    tier1_ids: list[str] = []
+    tier2_ids: list[str] = []
+    tier3_ids: list[str] = []
+
+    for finding in raw_findings:
+        tier, agent, fix_desc = _classify_finding(finding)
+        ref_rule = _get_ref_rule_id(finding)
+        vid = f"V-{str(uuid.uuid4())[:6].upper()}"
+        v = Violation(
+            id=vid,
+            rule=ref_rule,
+            file=finding.get("file", ""),
+            line=finding.get("line", 0),
+            message=finding.get("message", ""),
+            severity=finding.get("severity", "medium"),
+            tier=tier,
+            responsible_agent=agent,
+            fix_description=fix_desc,
+            scanner=finding.get("scanner", ""),
+        )
+        classified[vid] = v.to_dict()
+        if tier == RemediationTier.TIER1:
+            tier1_ids.append(vid)
+        elif tier == RemediationTier.TIER2:
+            tier2_ids.append(vid)
+        else:
+            tier3_ids.append(vid)
+
+    tier2_batch = None
+    if tier2_ids:
+        fix_counts: dict[str, int] = {}
+        for vid in tier2_ids:
+            desc = classified[vid]["fix_description"]
+            fix_counts[desc] = fix_counts.get(desc, 0) + 1
+        summary_lines = [f"- {count}x {desc}" for desc, count in fix_counts.items()]
+        tier2_batch = Tier2Batch(
+            id=f"BATCH-{str(uuid.uuid4())[:6].upper()}",
+            violations=tier2_ids,
+            summary="\n".join(summary_lines),
+        )
+
+    session = RemediationSession(
+        session_id=session_id,
+        story_id=story_id,
+        directory=directory,
+        violations=classified,
+        tier2_batch=asdict(tier2_batch) if tier2_batch else None,
+        tier3_violations=tier3_ids,
+        stats={
+            "total": len(classified),
+            "tier1": len(tier1_ids),
+            "tier2": len(tier2_ids),
+            "tier3": len(tier3_ids),
+        },
+    )
+    _save_session(session)
+
+    lines = [
+        f"{Status.SUCCESS} Remediation session {session_id} initialised.",
+        f"Directory: {directory} | Story: {story_id}",
+        f"Total findings: {len(classified)} from {report_path.name}",
+        "",
+        "## Tier Breakdown",
+        f"Tier 1 — ruff fixes (autonomous): {len(tier1_ids)}",
+        f"Tier 2 — developer/architect (one approval): {len(tier2_ids)}",
+        f"Tier 3 — HALT (user decision): {len(tier3_ids)}",
+        "",
+    ]
+
+    if tier3_ids:
+        lines.append("## Tier 3 — Resolve before proceeding")
+        for vid in tier3_ids[:10]:
+            v = classified[vid]
+            lines.append(
+                f"  [{v['severity'].upper()}] {v['rule']} — {v['file']}:{v['line']}"
+            )
+            lines.append(f"  {v['fix_description']}")
+        if len(tier3_ids) > 10:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            lines.append(f"  ... and {len(tier3_ids) - 10} more.")
+        lines.append("")
+
+    lines.append("## Next Step")
+    if tier1_ids:
+        lines.append(
+            f'`remediate(action="execute", session_id="{session_id}", tier="tier1")`'
+        )
+        lines.append("Runs ruff --fix directly. No approval needed.")
+    elif tier2_ids:
+        lines.append(f'`remediate(action="approve", session_id="{session_id}")`')
+    else:
+        lines.append("Review Tier 3 violations above.")
+
+    return "\n".join(lines)
+
+
+def get_remediation_state(session_id: str = "") -> str:
+    """Return current remediation session state."""
+    session = _load_session(session_id) if session_id else _load_active_session()
+    if not session:
+        return f"{Status.WARNING} No active remediation session."
+
+    stats = session.stats
+    pending = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.PENDING.value
+    )
+    fixed = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.AUTO_FIXED.value
+    )
+    deferred = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.DEFERRED.value
+    )
+    failed = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.FAILED.value
+    )
+
+    lines = [
+        f"## Remediation Session: {session.session_id}",
+        f"Story: {session.story_id} | Status: {session.status.value}",
+        f"Total: {stats.get('total', 0)} | Fixed: {fixed} | Pending: {pending} | Deferred: {deferred} | Failed: {failed}",
+        f"Tier 1: {stats.get('tier1', 0)} | Tier 2: {stats.get('tier2', 0)} | Tier 3: {stats.get('tier3', 0)}",
+    ]
+
+    if session.tier3_violations:
+        lines.append("\nTier 3 violations requiring your decision:")
+        for vid in session.tier3_violations:
+            v = session.violations.get(vid, {})
+            lines.append(f"  - {v.get('rule', vid)}: {v.get('fix_description', '')}")
+
+    return "\n".join(lines)
+
+
+def approve_tier2_batch(session_id: str = "") -> str:
+    """Approve the Tier 2 batch for execution."""
+    session = _load_session(session_id) if session_id else _load_active_session()
+    if not session:
+        return f"{Status.WARNING} No active remediation session found."
+    if not session.tier2_batch:
+        return f"{Status.WARNING} No Tier 2 batch in session {session.session_id}."
+
+    session.tier2_batch["approved"] = True
+    session.tier2_batch["approved_at"] = datetime.now().isoformat()
+    for vid in session.tier2_batch["violations"]:
+        if vid in session.violations:
+            session.violations[vid]["status"] = ViolationStatus.APPROVED.value
+    session.status = RemediationStatus.TIER2_RUNNING
+    _save_session(session)
+
+    count = len(session.tier2_batch["violations"])
+    return (
+        f"{Status.SUCCESS} Tier 2 batch approved. {count} violations queued.\n\n"
+        f'`remediate(action="execute", session_id="{session.session_id}", tier="tier2")`'
+    )
+
+
+def execute_remediation(
+    session_id: str = "",
+    tier: Literal["tier1", "tier2"] = "tier1",
+) -> str:
+    """Execute remediation for the specified tier.
+
+    Tier 1: Runs ruff --fix directly on files. Returns verified results.
+    Tier 2: Returns structured work order for developer/architect agent.
+    """
+    session = _load_session(session_id) if session_id else _load_active_session()
+    if not session:
+        return f"{Status.WARNING} No active remediation session found."
+    if tier == "tier1":
+        return _execute_tier1(session)
+    return _execute_tier2(session)
+
+
+def _execute_tier1(session: RemediationSession) -> str:
+    from ref_agents.tools.tier1_fixer import run_tier1_fixes, format_tier1_result
+    from ref_agents.utils.git_utils import find_project_root
+
+    pending = [
+        v
+        for v in session.violations.values()
+        if v["tier"] == RemediationTier.TIER1.value
+        and v["status"] == ViolationStatus.PENDING.value
+    ]
+    if not pending:
+        return f"{Status.WARNING} No pending Tier 1 violations in session {session.session_id}."
+
+    project_root = Path(session.directory)
+    if not project_root.exists():
+        git_root = find_project_root(Path(session.directory))
+        project_root = git_root or Path(session.directory)
+
+    session.status = RemediationStatus.TIER1_RUNNING
+    _save_session(session)
+
+    result = run_tier1_fixes(pending, project_root)
+
+    fixed_files: set[str] = set()
+    failed_files: set[str] = set()
+    for file_result in result.file_results:
+        if file_result.error:
+            failed_files.add(file_result.file)
+        elif file_result.violations_fixed > 0:
+            fixed_files.add(file_result.file)
+
+    for vid, v in session.violations.items():
+        if v["tier"] != RemediationTier.TIER1.value:
+            continue
+        if v["status"] != ViolationStatus.PENDING.value:
+            continue
+        file = v.get("file", "")
+        if file in fixed_files:
+            session.violations[vid]["status"] = ViolationStatus.AUTO_FIXED.value
+        elif file in failed_files:
+            session.violations[vid]["status"] = ViolationStatus.FAILED.value
+
+    session.status = RemediationStatus.TIER1_COMPLETE
+    _save_session(session)
+
+    try:
+        from ref_agents.utils import handoff_logger
+
+        handoff_logger.log_phase_complete(
+            story_id=session.story_id,
+            phase="remediation_tier1",
+            outcome="passed",
+            next_phase="remediation_tier2_or_complete",
+        )
+    except (OSError, ValueError):
+        pass
+
+    return format_tier1_result(result, session.session_id)
+
+
+def _execute_tier2(session: RemediationSession) -> str:
+    approved = [
+        v
+        for v in session.violations.values()
+        if v["tier"] == RemediationTier.TIER2.value
+        and v["status"] == ViolationStatus.APPROVED.value
+    ]
+    if not approved:
+        if session.tier2_batch and not session.tier2_batch.get("approved"):
+            return (
+                f"{Status.WARNING} Tier 2 batch not yet approved.\n"
+                f'`remediate(action="approve", session_id="{session.session_id}")`'
+            )
+        return f"{Status.WARNING} No approved Tier 2 violations in session {session.session_id}."
+
+    by_agent: dict[str, dict[str, list[dict]]] = {}
+    for v in approved:
+        by_agent.setdefault(v["responsible_agent"], {}).setdefault(
+            v["file"], []
+        ).append(v)
+
+    lines = [
+        f"{Status.SUCCESS} Tier 2 work order — {len(approved)} violations.",
+        f"Session: {session.session_id}",
+        "",
+        "Each agent applies fixes, runs ruff + pyright, confirms exit 0.",
+        "",
+    ]
+    step = 1
+    for agent, files in by_agent.items():
+        lines.append(f'### Step {step}: `agent(action="activate", name="{agent}")`')
+        for file, items in files.items():
+            lines.append(f"  File: `{file}`")
+            for v in items:
+                lines.append(f"  - [{v['id']}] {v['fix_description']}")
+                if v["message"]:
+                    lines.append(f"    {v['message'][:120]}")
+        lines.append("")
+        lines.append("  `ruff check --fix && ruff format && pyright`")
+        lines.append(
+            f'  `remediate(action="update", session_id="{session.session_id}", '
+            f'violation_ids=[...], status="auto_fixed")`'
+        )
+        lines.append("")
+        step += 1
+
+    lines.append('### Final: `agent(action="activate", name="pr_reviewer")`')
+    lines.append(f'`remediate(action="complete", session_id="{session.session_id}")`')
+    return "\n".join(lines)
+
+
+def defer_violation(session_id: str, violation_id: str, reason: str = "") -> str:
+    """Defer a violation to TECH_DEBT.md."""
+    session = _load_session(session_id) if session_id else _load_active_session()
+    if not session:
+        return f"{Status.WARNING} Session not found."
+    if violation_id not in session.violations:
+        return f"{Status.ERROR} Violation {violation_id} not found."
+    session.violations[violation_id]["status"] = ViolationStatus.DEFERRED.value
+    session.violations[violation_id]["fix_notes"] = reason or "Deferred to TECH_DEBT.md"
+    _save_session(session)
+    v = session.violations[violation_id]
+    return (
+        f"{Status.SUCCESS} {violation_id} deferred.\n"
+        f'`log(event="debt", debt_type="{v["rule"]}", severity="{v["severity"]}", location="{v["file"]}")`'
+    )
+
+
+def update_violation_status(
+    session_id: str,
+    violation_ids: list[str],
+    status: str,
+    notes: str = "",
+) -> str:
+    """Update status of one or more violations after fixing."""
+    session = _load_session(session_id)
+    if not session:
+        return f"{Status.ERROR} Session {session_id} not found."
+    updated = []
+    for vid in violation_ids:
+        if vid in session.violations:
+            session.violations[vid]["status"] = status
+            if notes:
+                session.violations[vid]["fix_notes"] = notes
+            updated.append(vid)
+    _save_session(session)
+    return f"{Status.SUCCESS} Updated {len(updated)} violations to '{status}'."
+
+
+def _group_tier3_violations(session: "RemediationSession") -> list[dict]:
+    """Group unresolved Tier 3 violations by file for fix_flow spawning.
+
+    Returns:
+        List of dicts: {file, count, violations, rule_summary, responsible_agent}
+        Sorted by count descending. Max 20 groups.
+    """
+    groups: dict[str, dict] = {}
+    for v in session.violations.values():
+        if v["tier"] != RemediationTier.TIER3.value:
+            continue
+        if v["status"] not in (
+            ViolationStatus.PENDING.value,
+            ViolationStatus.FAILED.value,
+        ):
+            continue
+        file = v.get("file", "unknown")
+        if file not in groups:
+            groups[file] = {
+                "file": file,
+                "count": 0,
+                "violations": [],
+                "rules": set(),
+                "responsible_agent": v.get("responsible_agent", "architect"),
+            }
+        groups[file]["count"] += 1
+        groups[file]["violations"].append(v)
+        groups[file]["rules"].add(v.get("rule", "unknown"))
+
+    result = []
+    for g in sorted(groups.values(), key=lambda x: x["count"], reverse=True)[:20]:
+        result.append(
+            {
+                "file": g["file"],
+                "count": g["count"],
+                "violations": g["violations"],
+                "rule_summary": ", ".join(sorted(g["rules"])),
+                "responsible_agent": g["responsible_agent"],
+            }
+        )
+    return result
+
+
+def complete_remediation(session_id: str = "") -> str:
+    """Mark remediation session complete after PR Reviewer gate passes."""
+    session = _load_session(session_id) if session_id else _load_active_session()
+    if not session:
+        return f"{Status.WARNING} No session found."
+    fixed = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.AUTO_FIXED.value
+    )
+    deferred = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.DEFERRED.value
+    )
+    failed = sum(
+        1
+        for v in session.violations.values()
+        if v["status"] == ViolationStatus.FAILED.value
+    )
+    session.status = RemediationStatus.COMPLETE
+    _save_session(session)
+    try:
+        from ref_agents.utils import handoff_logger
+
+        handoff_logger.log_phase_complete(
+            story_id=session.story_id,
+            phase="compliance_remediation",
+            outcome="passed",
+            next_phase="scrum_master",
+        )
+        handoff_logger.log_escalation(
+            level="L1",
+            from_agent="platform_engineer",
+            to_agents=["scrum_master"],
+            reason=f"Remediation {session.session_id} complete. Fixed: {fixed}, Deferred: {deferred}, Failed: {failed}",
+            story_id=session.story_id,
+        )
+    except (OSError, ValueError):
+        pass
+    # Surface Tier 3 groups with fix_flow instructions
+    tier3_groups = _group_tier3_violations(session)
+    if tier3_groups:
+        lines = [
+            f"{Status.SUCCESS} Remediation {session.session_id} complete.",
+            f"Fixed: {fixed} | Deferred: {deferred} | Failed: {failed}",
+            "",
+            f"{Status.HALT} {len(tier3_groups)} Tier 3 group(s) require investigation.",
+            "Confirm before spawning fix_flow: reply 'yes' to proceed, 'skip' to go straight to scrum_master.",
+            "",
+            "## Tier 3 Fix Flow Sessions (one per file group)",
+        ]
+        for i, g in enumerate(tier3_groups, 1):
+            desc = f"{g['rule_summary']} ({g['count']} violation(s))"
+            lines.append(f"{i}. {g['file']}")
+            lines.append(
+                f'   workflow(action="fix_flow", story_id="{session.story_id}", '
+                f'file_path="{g["file"]}", error_description="{desc}")'
+            )
+        lines += [
+            "",
+            "## After all fix_flow sessions complete:",
+            '`agent(action="activate", name="scrum_master")`',
+        ]
+        return "\n".join(lines)
+
+    return (
+        f"{Status.SUCCESS} Remediation {session.session_id} complete.\n"
+        f"Fixed: {fixed} | Deferred: {deferred} | Failed: {failed}\n\n"
+        f"Story audit required. Call:\n"
+        f'`agent(action="activate", name="scrum_master")`'
+    )