ref-agents 1.0.0__py3-none-any.whl

ref_agents/server.py

@@ -0,0 +1,1586 @@
+"""REF Agents Server.
+
+REF Agents is the AI-powered guidance layer for the Relay Engineering Framework (REF).
+Built on Anthropic's Model Context Protocol (MCP) for seamless AI assistant integration.
+
+This module defines the FastMCP server exposing REF agents, prompts, and tools.
+It manages session state for the active agent and provides tools for code compliance
+and codebase mapping.
+"""
+
+import re
+import sys
+from pathlib import Path
+from typing import Any, Callable, Literal, cast
+
+import structlog
+from fastmcp import FastMCP
+
+from ref_agents.auth import create_api_key_verifier
+from ref_agents.license_client import get_status, upgrade_message
+from ref_agents.constants import (
+    AGENT_CAPABILITIES,
+    AVAILABLE_AGENTS,
+    STORY_REQUIRED_AGENTS,
+    Status,
+)
+from ref_agents.prompts import start_agent
+from ref_agents.session import SessionManager
+from ref_agents.tool_names import TOOL_AGENT_ACTIVATE
+from ref_agents.tools import (
+    ai_pattern_detector,
+    codemap_freshness,
+    complexity,
+    context_manager,
+    context_tools,
+    cross_repo_linker,
+    dead_code_scanner,
+    debt_scanner,
+    dependency_graph,
+    docs_scanner,
+    external_detector,
+    flow_gap_detector,
+    flow_mapper,
+    guard_tools,
+    handoff_tools,
+    health_scanner,
+    hierarchy_manager,
+    migration_readiness_scanner,
+    pattern_learner,
+    security_audit_tool,
+    sequencing_engine,
+    summary_generator,
+    workflow_tools,
+)
+from ref_agents.utils import handoff_logger
+from ref_agents.workflow.state_machine import WorkflowManager
+
+# Setup - Route logs to stderr (stdout reserved for MCP JSON-RPC)
+structlog.configure(
+    processors=[structlog.processors.JSONRenderer()],
+    wrapper_class=structlog.make_filtering_bound_logger(30),  # WARNING+
+    logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+)
+logger = structlog.get_logger(__name__)
+
+# Module-level active agent tracking (also accessible via SessionManager)
+ACTIVE_AGENT: str | None = None
+
+
+auth_verifier = create_api_key_verifier()
+# auth_verifier is always returned (passthrough when no keys, real auth when keys configured)
+mcp = FastMCP("REF-Agents", auth=auth_verifier)
+
+
+# ── Prompt gate ──────────────────────────────────────────────────────────────
+# All persona prompts require a paid REF subscription.
+# Free tier: scanners + workflow tools remain ungated.
+
+
+def _require_paid(agent_name: str) -> str | None:
+    """Return upgrade message if not paid, None if access granted.
+
+    Args:
+        agent_name: Display name of the requested agent.
+
+    Returns:
+        Upgrade message string if free tier, None if paid access granted.
+    """
+    if not get_status().is_paid:
+        return upgrade_message(f"{agent_name} agent")
+    return None
+
+
+# --- Prompts (Agents) ---
+@mcp.prompt("activate_ref")
+def activate_ref_prompt() -> str:
+    """General entry point. Use this to start the REF session."""
+    gate = _require_paid("activate_ref")
+    if gate:
+        return gate
+    return context_tools._format_available_agents_numbered()
+
+
+@mcp.prompt("product_manager")
+def product_manager_prompt() -> str:
+    return _require_paid("Product Manager") or start_agent.get_product_manager_prompt()
+
+
+@mcp.prompt("architect")
+def architect_prompt() -> str:
+    return _require_paid("Architect") or start_agent.get_architect_prompt()
+
+
+@mcp.prompt("developer")
+def developer_prompt() -> str:
+    return _require_paid("Developer") or start_agent.get_developer_prompt()
+
+
+@mcp.prompt("tester")
+def tester_prompt() -> str:
+    return _require_paid("Tester") or start_agent.get_tester_prompt()
+
+
+@mcp.prompt("scrum_master")
+def scrum_master_prompt() -> str:
+    return _require_paid("Scrum Master") or start_agent.get_scrum_master_prompt()
+
+
+@mcp.prompt("security_owner")
+def security_owner_prompt() -> str:
+    return _require_paid("Security Owner") or start_agent.get_security_owner_prompt()
+
+
+@mcp.prompt("pr_reviewer")
+def pr_reviewer_prompt() -> str:
+    return _require_paid("PR Reviewer") or start_agent.get_pr_reviewer_prompt()
+
+
+@mcp.prompt("discovery")
+def discovery_prompt() -> str:
+    return _require_paid("Discovery") or start_agent.get_discovery_prompt()
+
+
+@mcp.prompt("qa_lead")
+def qa_lead_prompt() -> str:
+    return _require_paid("QA Lead") or start_agent.get_qa_lead_prompt()
+
+
+@mcp.prompt("specifier")
+def specifier_prompt() -> str:
+    return _require_paid("Specifier") or start_agent.get_specifier_prompt()
+
+
+@mcp.prompt("test_designer")
+def test_designer_prompt() -> str:
+    return _require_paid("Test Designer") or start_agent.get_test_designer_prompt()
+
+
+@mcp.prompt("impact_architect")
+def impact_architect_prompt() -> str:
+    return (
+        _require_paid("Impact Architect") or start_agent.get_impact_architect_prompt()  # type: ignore[attr-defined]
+    )
+
+
+@mcp.prompt("forensic_engineer")
+def forensic_engineer_prompt() -> str:
+    return (
+        _require_paid("Forensic Engineer") or start_agent.get_forensic_engineer_prompt()
+    )
+
+
+@mcp.prompt("strategist")
+def strategist_prompt() -> str:
+    return _require_paid("Strategist") or start_agent.get_strategist_prompt()
+
+
+@mcp.prompt("platform_engineer")
+def platform_engineer_prompt() -> str:
+    return (
+        _require_paid("Platform Engineer") or start_agent.get_platform_engineer_prompt()
+    )
+
+
+@mcp.prompt("migration_planner")
+def migration_planner_prompt() -> str:
+    return (
+        _require_paid("Migration Planner") or start_agent.get_migration_planner_prompt()
+    )
+
+
+@mcp.prompt("parity_tester")
+def parity_tester_prompt() -> str:
+    return _require_paid("Parity Tester") or start_agent.get_parity_tester_prompt()
+
+
+@mcp.prompt("cutover_engineer")
+def cutover_engineer_prompt() -> str:
+    return (
+        _require_paid("Cutover Engineer") or start_agent.get_cutover_engineer_prompt()
+    )
+
+
+# --- Context Tools (standalone) ---
+@mcp.tool()
+def set_project_root(path: str) -> str:
+    """Explicitly set the project root directory."""
+    return context_tools.set_project_root_impl(path)
+
+
+# --- Analysis Tools ---
+@mcp.tool()
+def generate_codemap(directory: str) -> str:
+    """Scans directory and generates CODE_MAP.md."""
+    return context_tools.generate_codemap_wrapper(directory)
+
+
+# --- Namespaced dispatchers (log.*, scan.*) ---
+LogEventAction = Literal[
+    "escalation", "ownership", "replan", "debt", "phase", "artifact"
+]
+ScanTargetAction = Literal[
+    "health",
+    "debt",
+    "dead_code",
+    "complexity",
+    "external",
+    "regression",
+    "docs",
+    "ai_patterns",
+    "security",
+    "codemap_freshness",
+    "migration_readiness",
+    "full_suite",
+]
+
+# Only health triggers auto-remediation — it is the only scan that writes
+# health_report.json which start_remediation() reads from disk.
+# security/ai_patterns/complexity can be manually remediated via
+# remediate(action="start") after their own scan runs.
+_AUTO_REMEDIATE_TARGETS: frozenset[str] = frozenset({"health"})
+
+# Severity counts are embedded in all scanner return strings in this format:
+# "Critical: N | High: N"
+_SEVERITY_PATTERN = re.compile(
+    r"\*{0,2}Critical:?\*{0,2}:?\s*(\d+).*?\*{0,2}High:?\*{0,2}:?\s*(\d+)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def _remediation_bootstrap(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    scan_result: str,
+    target: str,
+    story_id: str,
+    directory: str,
+    file_path: str,
+) -> str:
+    """Append remediation next-action block to scan output when violations warrant it.
+
+    Parses Critical/High counts from the scan result string. Appends a
+    remediate(action="start") call only for remediable targets with Critical
+    or High violations. Medium/Low violations produce an informational note only.
+    Informational targets (health, docs, external, regression) are never bootstrapped.
+
+    Args:
+        scan_result: Raw string returned by the scan tool.
+        target: Scan target name (e.g. "health").
+        story_id: Active story ID from session context, may be empty.
+        directory: Directory parameter passed to scan.
+        file_path: File path parameter passed to scan.
+
+    Returns:
+        Scan result string, optionally extended with remediation bootstrap block.
+    """
+    if target not in _AUTO_REMEDIATE_TARGETS:
+        return scan_result
+
+    match = _SEVERITY_PATTERN.search(scan_result)
+    critical = int(match.group(1)) if match else 0
+    high = int(match.group(2)) if match else 0
+
+    if critical == 0 and high == 0:
+        # Check for any violations at all (compliance tool uses different format)
+        if (
+            "⚠️ Issues Found" not in scan_result
+            and "issues found" not in scan_result.lower()
+        ):
+            return scan_result
+        # Has violations but couldn't parse severity — treat as high
+        high = 1
+
+    scope = file_path or directory or "."
+    sid = story_id or "<story_id>"
+
+    if critical > 0 or high > 0:
+        # Call start_remediation directly — do not leave this to the agent.
+        # start_remediation() reads health_report.json and writes a small session
+        # file. Fast, synchronous, safe inside MCP tool handler.
+        try:
+            from ref_agents.tools.compliance_remediation import start_remediation
+
+            remediation_plan = start_remediation(story_id=sid, directory=scope)
+            return (
+                scan_result
+                + "\n\n---\n"
+                + "## ⚡ Remediation Session Started\n"
+                + remediation_plan
+            )
+        except (ValueError, OSError, RuntimeError) as e:
+            logger.error("auto_remediation_failed", error=str(e))
+            return (
+                scan_result
+                + "\n\n---\n"
+                + f"⚠️ Auto-remediation failed: {e}\n"
+                + f'Run manually: remediate(action="start", story_id="{sid}", directory="{scope}")'
+            )
+    else:
+        return (
+            scan_result
+            + "\n\n---\n"
+            + "ℹ️ Medium/Low violations only. No immediate remediation required.\n"
+            + f'Log as debt: log(event="debt", debt_type=..., severity="medium", location="{scope}")'
+        )
+
+
+@mcp.tool()
+def log(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    event: LogEventAction,
+    story_id: str = "",
+    level: str = "",
+    reason: str = "",
+    to_agents: str = "",
+    to_owner: str = "",
+    trigger: str = "",
+    impact: str = "",
+    debt_type: str = "",
+    severity: str = "",
+    location: str = "",
+    phase: str = "",
+    outcome: str = "",
+    next_phase: str = "",
+    artifact: str = "",
+) -> str:
+    """Audit logging. event: escalation | ownership | replan | debt | phase | artifact.
+    escalation: level, reason, to_agents. ownership: to_owner, reason.
+    replan: trigger, impact. debt: debt_type, severity, location.
+    phase: phase, outcome, next_phase. artifact: artifact name (with story_id)."""
+    if event == "artifact":
+        return workflow_tools.mark_artifact_complete(
+            story_id=story_id, artifact=artifact
+        )
+    if event == "phase":
+        # G1 gate: block phase close if docs/ produces artifacts are missing.
+        # Applies only when outcome is "passed" — failures/skips bypass the gate.
+        if outcome == "passed" and story_id and phase:
+            from ref_agents.constants import PHASE_CONFIG
+
+            phase_key = next(
+                (k for k, v in PHASE_CONFIG.items() if v.get("primary_agent") == phase),
+                None,
+            )
+            if phase_key is None:
+                # Try matching by phase name string directly
+                phase_key = phase if phase in PHASE_CONFIG else None
+            if phase_key:
+                blocked = workflow_tools._check_produces_artifacts(story_id, phase_key)
+                if blocked:
+                    return blocked
+
+        # G4 (STORY-021..038): validator gate via shared phase_gate helper.
+        # Blocks phase-pass log when registered validator returns non-PASS.
+        # Gap 12: outcome="skipped" allowed but requires explicit reason text.
+        if outcome == "skipped" and not reason:
+            return (
+                f"{Status.ERROR} outcome='skipped' requires `reason=...` "
+                "explaining why this phase was bypassed."
+            )
+        if outcome == "passed" and phase:
+            try:
+                from ref_agents.tools.validators import phase_gate
+
+                allowed, msg, _report = phase_gate(role=phase, story_id=story_id)
+                if not allowed:
+                    return msg
+            except Exception as _exc:  # noqa: BLE001 — gate must not crash logging
+                logger.warning("validator_gate_failed", phase=phase, error=str(_exc))
+
+        # G3: auto-run audit_discovery after discovery phase passes.
+        if outcome == "passed" and phase == "discovery" and story_id:
+            try:
+                from ref_agents.session import SessionManager
+                from ref_agents.tools.discovery_audit import audit_discovery
+
+                root = str(SessionManager.get().project_root or ".")
+                audit_result = audit_discovery(root)
+                if "❌" in audit_result or "FAIL" in audit_result:
+                    return (
+                        f"{Status.ERROR} Discovery phase close blocked: audit_discovery failed.\n\n"
+                        f"{audit_result}\n\n"
+                        f"Fix all ❌ items above, then re-call:\n"
+                        f'  log(event="phase", story_id="{story_id}", phase="discovery", outcome="passed")'
+                    )
+            except (ValueError, OSError) as _e:
+                logger.warning("discovery_audit_auto_failed", error=str(_e))
+
+        workflow_tools._auto_capture_decision(
+            story_id=story_id,
+            phase=phase,
+            summary=f"[{outcome.upper()}] {phase} → {next_phase or 'blocked'}",
+        )
+    elif event in ("escalation", "replan"):
+        _event_text = reason[:100] if reason else (trigger[:100] if trigger else "")
+        workflow_tools._auto_capture_decision(  # type: ignore[call-arg]
+            story_id=story_id,
+            phase=event,
+            summary=f"{event.title()}: {_event_text}",
+            node_type="issue",
+        )
+    return handoff_tools.log_event(
+        event,
+        story_id=story_id,
+        level=level,
+        reason=reason,
+        to_agents=to_agents,
+        to_owner=to_owner,
+        trigger=trigger,
+        impact=impact,
+        debt_type=debt_type,
+        severity=severity,
+        location=location,
+        phase=phase,
+        outcome=outcome,
+        next_phase=next_phase,
+    )
+
+
+def _run_migration_detection(directory: str, mode: str) -> None:
+    """Run migration intent detection after health scan completes.
+
+    Reads ref-reports/platform_engineer/health_report.json (written by scan_health).
+    If migration intent detected or mode="migration", generates MIGRATION_MAP.md
+    and ref-reports/migration_map.json, and sets session migration mode.
+
+    Args:
+        directory: Project root directory.
+        mode: Scan mode string — "migration" activates explicit override.
+    """
+    import os
+    from pathlib import Path as _Path
+
+    explicit = mode == "migration" or os.environ.get("REF_MIGRATION_MODE") == "1"
+
+    try:
+        from ref_agents.tools.migration_mapper import (
+            MigrationMapper,
+            detect_migration_intent,
+        )
+    except ImportError:
+        return
+
+    try:
+        intent = detect_migration_intent(_Path(directory), explicit=explicit)
+
+        if intent.is_migration:
+            SessionManager.get().set_migration_mode(True)
+            mapper = MigrationMapper(_Path(directory))
+            assessments = mapper.assess_modules()
+            mapper.generate_map(intent, assessments)
+    except Exception as exc:  # noqa: BLE001  # migration detection must not crash MCP session — best-effort feature, mapper internals are third-party/dynamic
+        import structlog as _structlog
+
+        _structlog.get_logger(__name__).warning(
+            "migration_detection_failed", error=str(exc), directory=directory
+        )
+
+
+@mcp.tool()
+def scan(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    target: ScanTargetAction,
+    directory: str = "",
+    files: str = "",
+    file_path: str = "",
+    summary: bool = False,
+    mode: str = "",
+) -> str:
+    """Codebase analysis. target: health | debt | dead_code | complexity | external
+    | regression | docs | ai_patterns | security | codemap_freshness.
+    health/debt/dead_code/docs/security/codemap_freshness use directory.
+    complexity/regression use files. compliance/ai_patterns use file_path.
+    health is the primary entry point — runs all scanners and triggers remediation.
+    mode: pass "migration" with target="health" to activate migration intent detection."""
+    dispatch = {
+        "health": lambda: health_scanner.scan_health(directory or "."),
+        "debt": lambda: debt_scanner.scan_debt_tool(directory or ".", summary),
+        "dead_code": lambda: dead_code_scanner.scan_dead_code(
+            directory or ".", summary
+        ),
+        "complexity": lambda: complexity.scan_complexity_tool(files),
+        "external": lambda: external_detector.scan_and_report(directory or "."),
+        "regression": lambda: workflow_tools.scan_regression_risk_tool(files),
+        "docs": lambda: docs_scanner.validate_docs_tool(directory or "."),
+        "ai_patterns": lambda: ai_pattern_detector.detect_ai_patterns_tool(
+            file_path or directory or "."
+        ),
+        "security": lambda: security_audit_tool.run_security_audit(directory or ""),
+        "codemap_freshness": lambda: codemap_freshness.scan_codemap_freshness(
+            directory or "."
+        ),
+        "migration_readiness": lambda: migration_readiness_scanner.scan_migration_readiness(
+            directory or "."
+        ),
+        # STORY-TQ-002 full-suite execution gate. Server-side subprocess driver.
+        "full_suite": lambda: __import__(
+            "ref_agents.tools.full_suite_runner", fromlist=["run_full_suite"]
+        ).run_full_suite(directory or "."),
+    }
+    fn = dispatch.get(target)
+    if not fn:
+        return f"{Status.ERROR} Unknown scan target: {target}. Use: {list(dispatch.keys())}"
+
+    result = fn()
+
+    # Codemap auto-regeneration: health scan is the mandatory pre-completion gate,
+    # so regenerating here ensures codemap reflects every change that passed health checks.
+    if target == "health":
+        try:
+            from ref_agents.tools.workflow_tools import (
+                _auto_regenerate_codemap,  # type: ignore[attr-defined]
+            )
+
+            _auto_regenerate_codemap()
+        except (ImportError, OSError, RuntimeError):
+            pass
+
+        # Migration intent detection: runs after health scan writes health_report.json.
+        # Activated by mode="migration" param, REF_MIGRATION_MODE=1 env var, or auto-detection.
+        _run_migration_detection(directory or ".", mode)
+
+    # Retrieve story_id from active workflow state for remediation bootstrap (best-effort)
+    try:
+        from ref_agents.workflow.state_machine import WorkflowManager
+
+        story_id = WorkflowManager().get_active_story() or ""
+    except (ImportError, OSError, AttributeError):
+        story_id = ""
+
+    return _remediation_bootstrap(
+        scan_result=result,
+        target=target,
+        story_id=story_id,
+        directory=directory,
+        file_path=file_path,
+    )
+
+
+# --- workflow.* ---
+WorkflowAction = Literal[
+    "init",
+    "list",
+    "state",
+    "next",
+    "parallel_start",
+    "parallel_complete",
+    "fix_flow",
+    "complete_fix_flow",
+    "complete",
+    "validate_story_file",
+    "validate_and_advance",
+]
+
+
+def _workflow_fix_flow(
+    story_id: str, file_path: str, line_number: str, error_description: str
+) -> str:
+    """Start a fix-flow session and activate the forensic_engineer agent."""
+    global ACTIVE_AGENT
+    sid = (
+        story_id
+        or SessionManager.get().active_story
+        or WorkflowManager().get_active_story()
+        or "<story_id>"
+    )
+    result = workflow_tools.start_fix_flow(
+        story_id=sid,
+        file_path=file_path,
+        line_number=line_number,
+        error_description=error_description,
+    )
+    if result["error"]:
+        return f"{Status.ERROR} Fix flow failed: {result['error']}"
+    ACTIVE_AGENT = "forensic_engineer"
+    SessionManager.get().active_agent = "forensic_engineer"
+    handoff_logger.log_agent_activation("forensic_engineer")
+    logger.info("fix_flow_agent_activated", session_id=result["session_id"])
+    return (
+        f"{Status.SUCCESS} Fix Flow {result['session_id']} started.\n\n"
+        + result["forensic_prompt"]
+    )
+
+
+def _workflow_complete_fix_flow(story_id: str) -> str:
+    """Close a fix-flow session and activate the scrum_master agent."""
+    global ACTIVE_AGENT
+    sid = (
+        story_id
+        or SessionManager.get().active_story
+        or WorkflowManager().get_active_story()
+        or "<story_id>"
+    )
+    result = workflow_tools.complete_fix_flow(
+        session_id=story_id,
+        story_id=sid,
+        outcome="passed",
+    )
+    if result["error"]:
+        return f"{Status.ERROR} Fix flow close failed: {result['error']}"
+    ACTIVE_AGENT = "scrum_master"
+    SessionManager.get().active_agent = "scrum_master"
+    handoff_logger.log_agent_activation("scrum_master")
+    logger.info("fix_flow_scrum_master_activated")
+    return result["scrum_master_prompt"]
+
+
+@mcp.tool()
+def workflow(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    action: WorkflowAction,
+    story_id: str = "",
+    epic_id: str = "",
+    agent: str = "",
+    status: str = "passed",
+    notification: str = "",
+    completed_task: str = "",
+    file_path: str = "",
+    line_number: str = "",
+    error_description: str = "",
+    requirements_path: str = "",
+    next_phase: str = "",
+    artifact_path: str = "",
+) -> str:
+    """Workflow state machine. action: init | state | next | parallel_start | parallel_complete | fix_flow | complete_fix_flow | complete | validate_and_advance."""
+    _workflow_dispatch: dict[str, Callable[[], str]] = {
+        "init": lambda: workflow_tools.init_workflow(
+            story_id, epic_id, requirements_path
+        ),
+        "list": lambda: workflow_tools.list_stories(),
+        "state": lambda: workflow_tools.get_workflow_state(story_id),
+        "next": lambda: workflow_tools.suggest_next_agent(story_id, completed_task),
+        "parallel_start": lambda: workflow_tools.start_parallel_validation(story_id),
+        "parallel_complete": lambda: workflow_tools.complete_parallel_task(
+            story_id, agent, status, notification
+        ),
+        "complete": lambda: workflow_tools.close_workflow(story_id),
+        "fix_flow": lambda: _workflow_fix_flow(
+            story_id, file_path, line_number, error_description
+        ),
+        "complete_fix_flow": lambda: _workflow_complete_fix_flow(story_id),
+        "validate_story_file": lambda: workflow_tools.validate_story_file(story_id),
+        "validate_and_advance": lambda: workflow_tools.validate_and_advance(
+            story_id, next_phase, artifact_path
+        ),
+    }
+    handler = _workflow_dispatch.get(action)
+    if handler is None:
+        return f"{Status.ERROR} Unknown workflow action: {action!r}. Valid: {list(_workflow_dispatch)}"
+    return handler()
+
+
+# --- validate.* (STORY-021) ---
+
+
+@mcp.tool()
+def validate(role: str, artifact_id: str = "", artifact_path: str = "") -> str:
+    """Validate a role's output artifact.
+
+    Args:
+        role: Role name (e.g., "product_manager", "architect").
+        artifact_id: Story / artifact identifier.
+        artifact_path: Optional explicit path to artifact on disk.
+
+    Returns:
+        JSON-formatted ValidationReport.
+    """
+    import json as _json
+
+    from ref_agents.tools.validators import validate as _dispatch
+
+    report = _dispatch(role=role, artifact_id=artifact_id, artifact_path=artifact_path)
+    return _json.dumps(report.model_dump(mode="json"), indent=2)
+
+
+# --- agent.* ---
+AgentAction = Literal["list", "activate", "identify", "check"]
+
+
+def _set_active_agent_impl(agent_name: str) -> str:
+    """Validate, check prerequisites, set session, return prompt."""
+    target_agent = agent_name
+    if agent_name.isdigit():
+        agent_num = int(agent_name)
+        agents_list = list(AVAILABLE_AGENTS.keys())
+        if 1 <= agent_num <= len(agents_list):
+            target_agent = agents_list[agent_num - 1]
+        else:
+            return f"{Status.ERROR} Invalid number `{agent_name}`. Select 1-{len(agents_list)}."
+
+    if target_agent not in AVAILABLE_AGENTS:
+        valid_agents = ", ".join(AVAILABLE_AGENTS.keys())
+        return f"{Status.ERROR} Invalid agent `{target_agent}`. Valid agents: {valid_agents}"
+
+    if target_agent in ["product_manager", "architect", "developer", "pr_reviewer"]:
+        if not guard_tools._check_codemap_exists():
+            handoff_logger.log_escalation(
+                level="L1",
+                from_agent=target_agent,
+                to_agents=["discovery"],
+                reason="CODE_MAP.md missing - brownfield prerequisite not met",
+            )
+            return (
+                f"🔄 Cannot activate `{target_agent}`. CODE_MAP.md not found.\n\n"
+                "**This agent requires codebase context.**\n\n"
+                "**Option 1 - Set project path** (if CODE_MAP.md exists):\n"
+                "```\n"
+                "set_project_root('/path/to/your/project')\n"
+                "```\n\n"
+                "**Option 2 - Generate CODE_MAP** (recommended):\n"
+                "```\n"
+                f"{TOOL_AGENT_ACTIVATE.format(name='discovery')}\n"
+                "generate_codemap('/path/to/your/project')\n"
+                "```\n\n"
+                f"Then retry: `{TOOL_AGENT_ACTIVATE.format(name=target_agent)}`\n\n"
+                "**Ask the user** for their project path before proceeding."
+            )
+
+    # Story gate: implementation agents require an active story.
+    if target_agent in STORY_REQUIRED_AGENTS:
+        active_story_id = WorkflowManager().get_active_story()
+        if not active_story_id:
+            return (
+                f"⛔ Cannot activate `{target_agent}`. No active story.\n\n"
+                "**Map to an existing story or create a new one first:**\n\n"
+                "List stories:\n"
+                "```\n"
+                'workflow(action="list")\n'
+                "```\n\n"
+                "Then map (or create):\n"
+                "```\n"
+                'workflow(action="init", story_id="STORY-XXX", epic_id="EPIC-YYY")\n'
+                "```\n\n"
+                f"Then retry: `{TOOL_AGENT_ACTIVATE.format(name=target_agent)}`"
+            )
+        # Auto-sync in-process story context from disk state.
+        from ref_agents.tools.workflow_tools import _sync_story_context
+
+        wf_state = WorkflowManager().get_state(active_story_id)
+        epic_id = wf_state.epic_id if wf_state else ""
+        _sync_story_context(active_story_id, epic_id)
+
+    global ACTIVE_AGENT
+    ACTIVE_AGENT = target_agent
+    SessionManager.get().active_agent = target_agent
+    handoff_logger.log_agent_activation(target_agent)
+    logger.info("agent_activated", agent=target_agent)
+    agent_info = AVAILABLE_AGENTS.get(target_agent, target_agent)
+    duty = AGENT_CAPABILITIES.get(target_agent, {}).get("duty", "")
+    return (
+        f"{Status.SUCCESS} Agent: **{agent_info}**\n\n"
+        f"**Duty:** {duty}\n\n"
+        "**EXECUTION CONTRACT** (non-negotiable):\n"
+        "This is role-entry, NOT task completion. Your work begins now.\n\n"
+        "**If sufficient context exists → begin role duties immediately.**\n"
+        "Sufficient context means ALL of the following are present:\n"
+        "1. Active story ID visible in workflow state or prior messages.\n"
+        '2. Current phase known (from `workflow(action="state")` output or prior messages).\n'
+        "3. A concrete task, artifact path, or problem statement in prior messages.\n\n"
+        "**If any of the above is missing → ask for it explicitly. Do NOT await silently.**\n\n"
+        "Sequence: activate → embody role → execute duties → "
+        "write all `produces` artifacts to disk → "
+        "verify file exists at path (if missing: do NOT call log) → "
+        'log `event="phase"` complete → call `workflow(action="next")`.'
+    )
+
+
+@mcp.tool()
+def agent(
+    action: AgentAction,
+    name: str = "",
+    context: str = "",
+) -> str:
+    """Agent control. action: list | activate | identify | check."""
+    if action == "list":
+        return context_tools._format_available_agents_numbered()
+    if action == "activate":
+        if not name:
+            return f"{Status.ERROR} agent(action='activate') requires name=..."
+        return _set_active_agent_impl(name)
+    if action == "identify":
+        return context_tools.identify_agent_impl(context)
+    if action == "check":
+        if not name:
+            return f"{Status.ERROR} agent(action='check') requires name=..."
+        return guard_tools.check_agent_prerequisites_impl(name)
+    return f"{Status.ERROR} Unknown agent action: {action}"
+
+
+# --- context.* ---
+ContextAction = Literal[
+    "add",
+    "get",
+    "clear",
+    "graph_add",
+    "graph_related",
+    "graph_chain",
+    "graph_data",
+    "graph_populate",
+    "graph_query",
+    "graph_subgraph",
+    "graph_html",
+    "graph_watch",
+    "graph_watch_stop",
+]
+
+
+@mcp.tool()
+def context(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    action: ContextAction,
+    layer: str = "",
+    entry_type: str = "",
+    content: str = "",
+    identifier: str = "",
+    story_id: str = "",
+    epic_id: str = "",
+    node_id: str = "",
+    edge_types: str = "led_to,affects",
+    format: str = "json",
+    directory: str = "",
+    levels: str = "L1,L2",
+    include_git: bool = True,
+    include_llm: bool = True,
+    node_type: str = "",
+    links_to: str = "",
+    link_type: str = "led_to",
+    term: str = "",
+    depth: int = 2,
+) -> str:
+    """Session context. action: add|get|clear|graph_add|graph_related|graph_chain|graph_data|graph_populate|graph_query|graph_subgraph|graph_html|graph_watch|graph_watch_stop."""
+    _context_dispatch: dict[str, Callable[[], str]] = {
+        "add": lambda: context_manager.manage_context(
+            "add", layer, entry_type, content, identifier, story_id, epic_id
+        ),
+        "get": lambda: context_manager.manage_context(
+            "get", layer, entry_type, content, identifier, story_id, epic_id
+        ),
+        "clear": lambda: context_manager.manage_context(
+            "clear", layer, entry_type, content, identifier, story_id, epic_id
+        ),
+        "graph_add": lambda: _context_graph_add_node(
+            node_type, content, story_id, links_to, link_type
+        ),
+        "graph_related": lambda: _context_graph_get_related(node_id, edge_types),
+        "graph_chain": lambda: _context_graph_causality_chain(story_id),
+        "graph_data": lambda: _context_graph_data(format),
+        "graph_populate": lambda: _context_graph_populate(
+            directory, levels, include_git, include_llm
+        ),
+        "graph_query": lambda: _context_graph_query(term),
+        "graph_subgraph": lambda: _context_graph_subgraph(node_id, depth),
+        "graph_html": lambda: _context_graph_html(directory),
+        "graph_watch": lambda: _context_graph_watch(directory),
+        "graph_watch_stop": lambda: _context_graph_watch_stop(directory),
+    }
+    handler = _context_dispatch.get(action)
+    if handler is None:
+        return f"{Status.ERROR} Unknown context action: {action!r}. Valid: {list(_context_dispatch)}"
+    return handler()
+
+
+def _context_graph_add_node(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    node_type: str,
+    content: str,
+    story_id: str,
+    links_to: str,
+    link_type: str,
+) -> str:
+    from datetime import datetime, timezone
+
+    from ref_agents.tools.context_graph import (
+        VALID_EDGE_TYPES,
+        VALID_NODE_TYPES,
+        ContextNode,
+        EdgeType,
+        NodeType,
+        get_context_graph,
+    )
+
+    if node_type not in VALID_NODE_TYPES:
+        return (
+            f"{Status.ERROR} Invalid node_type: {node_type}. Valid: {VALID_NODE_TYPES}"
+        )
+    if links_to and link_type not in VALID_EDGE_TYPES:
+        return (
+            f"{Status.ERROR} Invalid link_type: {link_type}. Valid: {VALID_EDGE_TYPES}"
+        )
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+    node_id = f"{node_type}-{ts}"
+    graph = get_context_graph()
+    node = ContextNode(
+        id=node_id,
+        node_type=cast(NodeType, node_type),
+        content=content,
+        story_id=story_id,
+    )
+    graph.add_node(node)
+    edges_added = 0
+    if links_to:
+        for target_id in links_to.split(","):
+            target_id = target_id.strip()
+            if target_id and target_id in graph._graph:
+                try:
+                    graph.add_edge(node_id, target_id, cast(EdgeType, link_type))
+                    edges_added += 1
+                except ValueError:
+                    pass
+    graph.save()
+    result = f"{Status.SUCCESS} Node added: {node_id}"
+    if edges_added:
+        result += f" (+{edges_added} edges)"
+    return result
+
+
+def _context_graph_get_related(node_id: str, edge_types: str) -> str:
+    from ref_agents.tool_names import TOOL_CONTEXT_GRAPH_EMPTY_HINT
+    from ref_agents.tools.context_graph import get_context_graph
+
+    graph = get_context_graph()
+    if graph.node_count == 0:
+        return f"{Status.WARNING} Context graph is empty — greenfield project, no prior decisions. Run {TOOL_CONTEXT_GRAPH_EMPTY_HINT} after first story completes."
+    node = graph.get_node(node_id)
+    if not node:
+        return f"{Status.ERROR} Node not found: {node_id}"
+    types_list = [t.strip() for t in edge_types.split(",") if t.strip()]
+    related = graph.get_related(node_id, edge_types=types_list if types_list else None)
+    if not related:
+        return f"No related nodes found for {node_id} with edge types: {edge_types}"
+    lines = [f"## Related to {node_id}", ""]
+    for n in related:
+        lines.append(f"- **{n.id}** ({n.node_type}): {n.content[:80]}")
+        if n.story_id:
+            lines.append(f"  - Story: {n.story_id}")
+    return "\n".join(lines)
+
+
+def _context_graph_causality_chain(story_id: str) -> str:
+    from ref_agents.tools.context_graph import get_context_graph
+
+    graph = get_context_graph()
+    story_nodes = graph.get_nodes_by_story(story_id)
+    if not story_nodes:
+        return f"No context graph nodes found for story: {story_id}"
+    decisions = [n for n in story_nodes if n.node_type == "decision"]
+    if not decisions:
+        lines = [f"## Context for {story_id}", ""]
+        for n in story_nodes:
+            lines.append(f"- **{n.id}** ({n.node_type}): {n.content[:80]}")
+        return "\n".join(lines)
+    decisions.sort(key=lambda x: x.timestamp, reverse=True)
+    chain = graph.get_causality_chain(decisions[0].id)
+    lines = [f"## Decision Chain for {story_id}", ""]
+    for i, n in enumerate(chain):
+        prefix = "→ " if i > 0 else ""
+        lines.append(f"{prefix}**{n.id}**: {n.content[:80]}")
+    return "\n".join(lines)
+
+
+def _context_graph_data(format: str) -> str:
+    from ref_agents.tool_names import TOOL_CONTEXT_GRAPH_EMPTY_HINT
+    from ref_agents.tools.context_graph import get_context_graph
+
+    graph = get_context_graph()
+    if graph.node_count == 0:
+        return f"{Status.ERROR} Context graph is empty. Run {TOOL_CONTEXT_GRAPH_EMPTY_HINT} first."
+    if format == "viz":
+        return graph.to_visualization_json()
+    return graph.to_json()
+
+
+def _context_graph_query(term: str) -> str:
+    from ref_agents.tools.context_graph import get_context_graph
+
+    if not term:
+        return f"{Status.ERROR} 'term' required for graph_query"
+    graph = get_context_graph()
+    matches = graph.query_nodes(term)
+    if not matches:
+        return f"No nodes matching '{term}'"
+    total = len(matches)
+    shown = matches[:20]
+    header = f"## Graph query: '{term}' ({total} results"
+    header += ", showing first 20)" if total > 20 else ")"  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+    lines = [header + "\n"]
+    for n in shown:
+        lines.append(f"- **{n.id}** ({n.node_type}): {n.content[:100]}")
+    return "\n".join(lines)
+
+
+def _context_graph_subgraph(node_id: str, depth: int) -> str:
+    from ref_agents.tools.context_graph import get_context_graph
+
+    if not node_id:
+        return f"{Status.ERROR} 'node_id' required for graph_subgraph"
+    graph = get_context_graph()
+    nodes = graph.subgraph(node_id, depth)
+    if not nodes:
+        return f"{Status.ERROR} Node not found: {node_id}"
+
+    lines = [f"## Subgraph of '{node_id}' (depth={depth}, {len(nodes)} nodes)\n"]
+    for n in nodes:
+        lines.append(f"- **{n.id}** ({n.node_type}): {n.content[:100]}")
+    return "\n".join(lines)
+
+
+def _context_graph_html(directory: str) -> str:
+    from ref_agents.tools.context_graph import get_context_graph
+
+    root = Path(directory).resolve() if directory else None
+    if root is None:
+        root = SessionManager.get().project_root or Path.cwd()
+
+    # Use singleton — avoids dropping in-memory state that was never saved (RC8)
+    graph = get_context_graph()
+
+    # Auto-populate if empty — no need for a separate graph_populate call
+    if graph.node_count == 0:
+        try:
+            from ref_agents.tools.brownfield_populator import BrownfieldPopulator
+
+            populator = BrownfieldPopulator(root)
+            populator.populate(
+                levels=["L1", "L2"], include_git=False, include_llm=False
+            )
+            graph = get_context_graph()
+        except (OSError, ValueError, RuntimeError) as e:
+            logger.warning(
+                "graph_html_auto_populate_failed", root=str(root), error=str(e)
+            )
+
+    if graph.node_count == 0:
+        return f"{Status.ERROR} No graph data found. Run context(action='graph_populate', directory='{root}') first."
+
+    html = graph.to_html()
+    out_dir = root / "ref-reports"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "graph.html"
+    out_path.write_text(html, encoding="utf-8")
+    return f"{Status.SUCCESS} Graph viewer saved: `{out_path}` ({graph.node_count} nodes, {graph.edge_count} edges)"
+
+
+# Module-level observer registry — keyed by resolved root path string
+_ast_observers: dict[str, Any] = {}
+
+
+def _context_graph_watch(directory: str) -> str:
+    """Start watchdog file watcher for incremental AST re-extraction on file save."""
+    import threading
+
+    from watchdog.events import (  # type: ignore[import-untyped]
+        FileSystemEvent,
+        FileSystemEventHandler,
+    )
+    from watchdog.observers import Observer  # type: ignore[import-untyped]
+
+    from ref_agents.tools.brownfield_populator import BrownfieldPopulator
+
+    root = Path(directory).resolve() if directory else Path.cwd()
+    root_key = str(root)
+
+    if root_key in _ast_observers:
+        return f"{Status.SUCCESS} AST watcher already running for `{root}`"
+
+    # Instantiate once — reused across all on_modified calls to avoid repeated
+    # singleton churn and graph saves on every event.
+    populator = BrownfieldPopulator(root)
+
+    class _ASTRebuildHandler(FileSystemEventHandler):
+        _WATCHED_EXTS = {".py", ".ts", ".tsx", ".md"}
+
+        def on_modified(self, event: FileSystemEvent) -> None:
+            if event.is_directory:
+                return
+            p = Path(str(event.src_path))
+            if p.suffix not in self._WATCHED_EXTS:
+                return
+            try:
+                rel = str(p.relative_to(root))
+                populator._scan_structural_single(p, rel)
+                populator.graph.save()
+                logger.info("ast_graph_incremental_update", file=rel)
+            except (OSError, SyntaxError, ValueError) as e:
+                logger.warning("ast_watch_rebuild_failed", error=str(e))
+
+    observer = Observer()
+    observer.schedule(_ASTRebuildHandler(), root_key, recursive=True)
+    _ast_observers[root_key] = observer
+    t = threading.Thread(target=observer.start, daemon=True, name="ref-ast-watcher")
+    t.start()
+    return f"{Status.SUCCESS} AST file watcher started for `{root}` (daemon thread)"
+
+
+def _context_graph_watch_stop(directory: str = "") -> str:
+    """Stop a running AST file watcher. Pass 'all' to stop every active watcher."""
+    if directory == "all":
+        stopped: list[str] = []
+        for key, obs in list(_ast_observers.items()):
+            try:
+                obs.stop()
+                obs.join(timeout=5)
+                stopped.append(key)
+            except (RuntimeError, OSError):
+                pass
+        _ast_observers.clear()
+        return f"{Status.SUCCESS} Stopped {len(stopped)} watcher(s)"
+
+    root_key = str(Path(directory).resolve()) if directory else str(Path.cwd())
+    observer = _ast_observers.pop(root_key, None)
+    if observer is None:
+        return f"{Status.ERROR} No watcher running for `{root_key}`"
+    try:
+        observer.stop()
+        observer.join(timeout=5)
+    except (RuntimeError, OSError) as e:
+        return f"{Status.ERROR} Watcher stop failed: {e}"
+    return f"{Status.SUCCESS} AST file watcher stopped for `{root_key}`"
+
+
+def _context_graph_populate(
+    directory: str, levels: str, include_git: bool, include_llm: bool
+) -> str:
+    from ref_agents.tools.brownfield_populator import (
+        BrownfieldPopulator,
+        CriticalityLevel,
+    )
+
+    try:
+        path = Path(directory) if directory else None
+        populator = BrownfieldPopulator(path)
+        level_list: list[CriticalityLevel] = [
+            cast(CriticalityLevel, level.strip())
+            for level in levels.split(",")
+            if level.strip()
+        ]
+        stats = populator.populate(
+            levels=level_list, include_git=include_git, include_llm=include_llm
+        )
+        return _format_population_stats(populator.root, stats, list(level_list))
+    except (OSError, ValueError, RuntimeError) as e:
+        logger.error("brownfield_population_failed", error=str(e))
+        raise
+
+
+# --- story.* ---
+StoryAction = Literal["dependencies", "ready", "critical_path", "analysis"]
+
+
+@mcp.tool()
+def story(action: StoryAction, directory: str = "") -> str:
+    """Story sequencing. action: dependencies | ready | critical_path | analysis."""
+    if action == "dependencies":
+        return dependency_graph.generate_dependency_graph(directory or ".")
+    if action == "ready":
+        return sequencing_engine.get_next_ready_stories(directory or ".")
+    if action == "critical_path":
+        return sequencing_engine.get_critical_path_report(directory or ".")
+    if action == "analysis":
+        result = sequencing_engine.analyze_directory(directory or ".")
+        if result.errors:
+            return f"Errors: {result.errors}"
+        return result.to_json()
+    return f"{Status.ERROR} Unknown story action: {action}"
+
+
+# --- browser.* ---
+BrowserAction = Literal["check", "write_tests", "execute", "verify"]
+
+
+@mcp.tool()
+def browser(
+    action: BrowserAction,
+    story_id: str = "",
+    test_cases_json: str = "",
+) -> str:
+    """Browser/E2E testing. action: check | write_tests | execute | verify."""
+    if action == "check":
+        from ref_agents.tools.browser.playwright_mcp_client import (
+            check_browser_tools_available,
+        )
+
+        if check_browser_tools_available():
+            return "✅ Playwright MCP browser tools are available.\nReady for frontend E2E testing."
+        return (
+            "❌ Playwright MCP browser tools are NOT available.\n\n"
+            "To enable: Ensure Playwright MCP is enabled in Cursor settings, check MCP config, restart Cursor."
+        )
+    if action == "write_tests":
+        return workflow_tools.write_conceptual_tests_tool(story_id, test_cases_json)
+    if action == "execute":
+        from ref_agents.tools.browser.test_executor import (
+            execute_frontend_tests as exec_tests,
+        )
+
+        return exec_tests(story_id)
+    if action == "verify":
+        from ref_agents.tools.browser.evidence_verifier import (
+            verify_test_evidence as verify,
+        )
+
+        result = verify(story_id)
+        if result.valid:
+            return f"✅ Evidence verified for {story_id}\nScreenshots: {result.screenshot_count}\nLog entries: {result.log_entry_count}"
+        return (
+            f"❌ Evidence verification FAILED for {story_id}\nIssues: {result.issues}"
+        )
+    return f"{Status.ERROR} Unknown browser action: {action}"
+
+
+# --- Standalone workflow/context ---
+@mcp.tool()
+def check_testing_capabilities(story_id: str = "") -> str:
+    """Detects available testing tools (Playwright MCP, pytest) for story type."""
+    return workflow_tools.check_testing_capabilities(story_id)
+
+
+@mcp.tool()
+def defer_e2e_testing(story_id: str = "", reason: str = "") -> str:
+    """Defers E2E testing and logs to TECH_DEBT.md. Requires user confirmation."""
+    return workflow_tools.defer_e2e_testing(story_id, reason)
+
+
+@mcp.tool()
+def set_story_context(story_id: str, epic_id: str = "") -> str:
+    """Sets active story context for agent prompts and workflow tracking."""
+    start_agent.set_story_context(story_id, epic_id)
+    return f"{Status.SUCCESS} Context set: story={story_id}"
+
+
+@mcp.tool()
+def manage_context(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    action: str,
+    layer: str = "",
+    entry_type: str = "",
+    content: str = "",
+    identifier: str = "",
+    story_id: str = "",
+    epic_id: str = "",
+) -> str:
+    """Manages context. action: add | get | clear."""
+    return context_manager.manage_context(
+        action, layer, entry_type, content, identifier, story_id, epic_id
+    )
+
+
+@mcp.tool()
+def add_blocker(story_id: str, level: str, description: str, source_agent: str) -> str:
+    """Adds blocker to story. level: L1 | L2 | L3. Triggers escalation log."""
+    manager = WorkflowManager()
+    try:
+        state = manager.add_blocker(story_id, level, description, source_agent)
+        handoff_logger.log_escalation(level, source_agent, [], description, story_id)
+        return (
+            f"🛑 Blocker added to {story_id}\n"
+            f"Level: {level}\n"
+            f"Description: {description}\n"
+            f"Source: {source_agent}\n"
+            f"Total blockers: {len(state.blockers)}"
+        )
+    except ValueError as e:
+        return f"{Status.ERROR} Error: {e}"
+
+
+@mcp.tool()
+def resolve_blocker(story_id: str, index: int = -1) -> str:
+    """Resolves blocker by index (-1 for most recent). Updates workflow state."""
+    return workflow_tools.resolve_blocker_tool(story_id, index)
+
+
+@mcp.tool()
+def notify_background_agent(story_id: str, notification: str) -> str:
+    """Queues notification for primary agent from background agent."""
+    return workflow_tools.add_background_notification(story_id, notification)
+
+
+@mcp.tool()
+def request_debt_fix_approval(
+    debt_id: str, description: str, story_id: str = ""
+) -> str:
+    """Requests approval to fix tech debt. Logs L3 escalation. Halts for decision."""
+    return workflow_tools.request_debt_fix_approval_tool(debt_id, description, story_id)
+
+
+# --- Flow ---
+@mcp.tool()
+def generate_flow(directory: str, output: str = "diagram") -> str:
+    """Generates flow from requirements. output: diagram | summary."""
+    return flow_mapper.generate_flow(directory, output)
+
+
+@mcp.tool()
+def detect_flow_gaps(flows_file: str, req_directory: str, summary: bool = False) -> str:
+    """Detects flow gaps. Set summary=True for quick overview."""
+    return flow_gap_detector.detect_flow_gaps(flows_file, req_directory, summary)
+
+
+# --- External ---
+@mcp.tool()
+def validate_external_dependencies(registry_file: str, code_directory: str) -> str:
+    """Validates code uses only registered external APIs from EXTERNAL_APIS.md."""
+    return cross_repo_linker.validate_external_deps(registry_file, code_directory)
+
+
+@mcp.tool()
+def list_unregistered_dependencies(code_directory: str) -> str:
+    """Lists external API calls not registered in EXTERNAL_APIS.md."""
+    return cross_repo_linker.get_unregistered_deps(code_directory)
+
+
+# --- Pattern ---
+@mcp.tool()
+def pattern(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    action: str,
+    pattern_id: str = "",
+    name: str = "",
+    domain: str = "",
+    tech: str = "",
+    story_id: str = "",
+    story_title: str = "",
+    files: str = "",
+    snippet: str = "",
+    tags: str = "",
+    description: str = "",
+) -> str:
+    """Pattern management. action: capture | suggest | get | list."""
+    return pattern_learner.pattern_tool(
+        action,
+        pattern_id,
+        name,
+        domain,
+        tech,
+        story_id,
+        story_title,
+        files,
+        snippet,
+        tags,
+        description,
+    )
+
+
+# --- Other ---
+@mcp.tool()
+def generate_project_summary(directory: str = "") -> str:
+    """Generates executive-summary.json with score, debt, security, compliance."""
+    return summary_generator.generate_project_summary_tool(directory)
+
+
+# --- Discovery Artifact Tools ---
+@mcp.tool()
+def generate_features(directory: str) -> str:
+    """Infer FEATURES.md from codemap/ directory.
+
+    Analyzes codemap package maps to identify user-facing features
+    and generates a FEATURES.md file at project root.
+
+    Args:
+        directory: Path to project root (must have codemap/ first).
+
+    Returns:
+        Status with feature count and categories.
+    """
+    from ref_agents.tools.features_generator import generate_features_file
+
+    return generate_features_file(directory)
+
+
+@mcp.tool()
+def generate_agents_md(directory: str) -> str:
+    """Generate AGENTS.md with REF protocol and fix workflow.
+
+    Creates AGENTS.md at project root containing:
+    - REF-Agents MCP entry point requirement
+    - Communication style protocol
+    - Mandatory fix workflow (forensic_engineer -> strategist -> developer)
+
+    Args:
+        directory: Path to project root.
+
+    Returns:
+        Status message.
+    """
+    from ref_agents.tools.agents_generator import generate_agents_file
+
+    return generate_agents_file(directory)
+
+
+# --- hierarchy.* ---
+@mcp.tool()
+def create_story(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    story_id: str,
+    title: str,
+    user_story: str,
+    epic_id: str = "",
+    feature_id: str = "",
+    description: str = "",
+    requirements_text: str = "",
+) -> str:
+    """Create story doc at docs/requirements/STORY-XXX.md + JSON. Required before workflow init.
+
+    Pass requirements_text to persist inline terminal/chat requirements verbatim under
+    a '## Raw Requirements' section — ensures no input is lost if the user typed
+    requirements into the chat rather than supplying a document.
+    """
+    try:
+        story = hierarchy_manager.create_story(
+            story_id=story_id,
+            title=title,
+            user_story=user_story,
+            epic_id=epic_id or None,
+            feature_id=feature_id or None,
+            description=description,
+            requirements_text=requirements_text,
+        )
+        path = f"docs/requirements/{story_id}.md"
+        return (
+            f"{Status.SUCCESS} Story created: {path}\nEpic: {story.epic_id or 'None'}"
+        )
+    except OSError as e:
+        return f"{Status.ERROR} Failed to create story: {e}"
+
+
+@mcp.tool()
+def create_epic(
+    epic_id: str,
+    title: str,
+    description: str = "",
+) -> str:
+    """Create epic doc at docs/requirements/EPIC-XXX.md + JSON."""
+    try:
+        hierarchy_manager.create_epic(
+            epic_id=epic_id, title=title, description=description
+        )
+        path = f"docs/requirements/{epic_id}.md"
+        return f"{Status.SUCCESS} Epic created: {path}"
+    except OSError as e:
+        return f"{Status.ERROR} Failed to create epic: {e}"
+
+
+@mcp.tool()
+def create_feature(
+    feature_id: str,
+    epic_id: str,
+    title: str,
+    description: str = "",
+) -> str:
+    """Create feature doc at docs/requirements/FEAT-XXX.md + JSON."""
+    try:
+        hierarchy_manager.create_feature(
+            feature_id=feature_id,
+            epic_id=epic_id,
+            title=title,
+            description=description,
+        )
+        path = f"docs/requirements/{feature_id}.md"
+        return f"{Status.SUCCESS} Feature created: {path}"
+    except OSError as e:
+        return f"{Status.ERROR} Failed to create feature: {e}"
+
+
+@mcp.tool()
+def audit_discovery(directory: str) -> str:
+    """Audit discovery artifacts for completeness.
+
+    Post-completion verification checking:
+    - Artifact existence (codemap/, FEATURES.md, AGENTS.md, etc.)
+    - Placement validation (no misplaced files, no unknown/)
+    - Content validation (required sections present)
+
+    Args:
+        directory: Path to project root.
+
+    Returns:
+        Audit result with pass/fail checks and remediation steps.
+    """
+    from ref_agents.tools.discovery_audit import audit_discovery as run_audit
+
+    return run_audit(directory)
+
+
+def _format_population_stats(root: Path, stats: dict, levels: list[str]) -> str:
+    """Format population statistics."""
+    from ref_agents.constants import Status
+
+    lines = [
+        f"{Status.SUCCESS} Brownfield Population Complete",
+        "",
+        f"Root: {root}",
+        f"Levels: {', '.join(levels)}",
+        "",
+        "Stats:",
+        f"- Files Scanned: {stats.get('files_scanned', 0)}",
+        f"- Deep Analysis: {stats.get('deep_analysis_files', 0)}",
+        f"- Total Nodes: {stats.get('total_nodes', 0)}",
+        f"- Total Edges: {stats.get('total_edges', 0)}",
+    ]
+    return "\n".join(lines)
+
+
+RemediationTierLiteral = Literal["tier1", "tier2"]
+
+
+@mcp.tool()
+def remediate(  # noqa: PLR0913  # MCP tool signature — FastMCP interface constraint
+    action: Literal[
+        "start", "state", "execute", "approve", "defer", "update", "complete"
+    ],
+    session_id: str = "",
+    story_id: str = "",
+    directory: str = "",
+    scan_output: str = "",
+    tier: RemediationTierLiteral = "tier1",
+    violation_ids: list[str] | None = None,
+    violation_id: str = "",
+    status: str = "",
+    reason: str = "",
+    notes: str = "",
+) -> str:
+    """Autonomous compliance remediation. action: start | state | execute | approve | defer | update | complete.
+
+    start     — Parse scan output, classify violations into tiers, return plan.
+    state     — Show current session progress and pending decisions.
+    execute   — Return ordered work plan for tier1 (autonomous) or tier2 (approved).
+    approve   — Approve Tier 2 batch for execution (single gate for all Tier 2 fixes).
+    defer     — Defer a single violation to TECH_DEBT.md instead of fixing.
+    update    — Mark violations as auto_fixed | failed after agent completes fixes.
+    complete  — Close session after PR Reviewer gate passes.
+    """
+    from ref_agents.tools.compliance_remediation import (
+        approve_tier2_batch,
+        complete_remediation,
+        defer_violation,
+        execute_remediation,
+        get_remediation_state,
+        start_remediation,
+        update_violation_status,
+    )
+
+    _remediation_dispatch: dict[str, Callable[[], str]] = {
+        "start": lambda: start_remediation(
+            story_id=story_id, directory=directory, scan_output=scan_output
+        ),
+        "state": lambda: get_remediation_state(session_id=session_id),
+        "execute": lambda: execute_remediation(session_id=session_id, tier=tier),
+        "approve": lambda: approve_tier2_batch(session_id=session_id),
+        "defer": lambda: defer_violation(
+            session_id=session_id, violation_id=violation_id, reason=reason
+        ),
+        "update": lambda: update_violation_status(
+            session_id=session_id,
+            violation_ids=violation_ids or [],
+            status=status,
+            notes=notes,
+        ),
+        "complete": lambda: complete_remediation(session_id=session_id),
+    }
+    handler = _remediation_dispatch.get(action)
+    if handler is None:
+        return f"{Status.ERROR} Unknown remediation action: {action!r}. Valid: {list(_remediation_dispatch)}"
+    return handler()
+
+
+def main() -> None:
+    """Entry point for CLI execution via uvx/pip.
+
+    Uses stdio transport (works with Cursor, Claude Desktop, Windsurf).
+    Run via: `uvx ref-agents` (after publishing to PyPI)
+    """
+    mcp.run(show_banner=False)
+
+
+if __name__ == "__main__":
+    main()