program-context-protocol 0.12.4__py3-none-any.whl

pcp/commands/watch.py

@@ -0,0 +1,372 @@
+"""pcp watch — continuous CI/deploy monitoring.
+
+Polls every N seconds (default 270, per docs/greenfield.md) for a new CI run
+result and deploy health. On failure: fetches logs, spawns a fresh coding
+agent to diagnose+fix+commit+push, notifies via slack-notify if available.
+The fix isn't verified here — the next poll cycle re-checks CI for it, same
+as a human would push a fix and watch CI pick it up.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.commands.doctor import load_integrations, check_environment
+from pcp.commands.build import check_agent_depth_or_exit
+from pcp.llm.client import _claude_bin
+
+console = Console()
+
+DEFAULT_INTERVAL = 270
+
+
+def _default_max_iterations() -> int:
+    """Overall poll-loop ceiling — a daemon left running for days should stop
+    on its own, not rely on someone remembering it's up. Default ~15h at the
+    default 270s interval. Override with PCP_WATCH_MAX_ITERATIONS."""
+    return int(os.environ.get("PCP_WATCH_MAX_ITERATIONS", "200"))
+
+
+def _max_consecutive_auto_fix_attempts() -> int:
+    """Regression-loop breaker: if auto-fix keeps getting attempted without a
+    CI success in between, a fresh agent is likely re-diagnosing from scratch
+    each time and could be fixing X by breaking Y, then fixing Y by breaking X.
+    After this many consecutive attempts with no success, stop auto-fixing
+    and just report — a human needs to look. Override with
+    PCP_WATCH_MAX_CONSECUTIVE_FIXES."""
+    return int(os.environ.get("PCP_WATCH_MAX_CONSECUTIVE_FIXES", "3"))
+
+
+def _watch_agent_max_budget_usd() -> str:
+    """Per-attempt dollar cap passed to `claude -p --max-budget-usd` for
+    watch's auto-fix agent -- same mechanism build.py already uses for its
+    own coding-agent subprocess, applied here since this is the same shape of
+    call and had no cap at all until now. Doesn't add a new retry pathway:
+    an attempt that hits this cap without finishing is indistinguishable
+    from any other incomplete attempt, and already falls under the existing
+    PCP_WATCH_MAX_CONSECUTIVE_FIXES ceiling below -- it just bounds the cost
+    of each individual attempt within that ceiling instead of leaving it open.
+    Override with PCP_WATCH_AGENT_MAX_BUDGET_USD."""
+    return os.environ.get("PCP_WATCH_AGENT_MAX_BUDGET_USD", "5")
+
+
+def get_latest_ci_run(project_root: Path) -> dict | None:
+    if not shutil.which("gh"):
+        return None
+    try:
+        result = subprocess.run(
+            ["gh", "run", "list", "--limit", "1", "--json", "status,conclusion,databaseId,headBranch,name,url"],
+            capture_output=True, text=True, cwd=project_root, timeout=30,
+        )
+    except subprocess.TimeoutExpired:
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        runs = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+    return runs[0] if runs else None
+
+
+def get_failed_logs(project_root: Path, run_id) -> str:
+    try:
+        result = subprocess.run(
+            ["gh", "run", "view", str(run_id), "--log-failed"],
+            capture_output=True, text=True, cwd=project_root, timeout=60,
+        )
+    except subprocess.TimeoutExpired:
+        return "(timed out fetching logs)"
+    return (result.stdout + result.stderr)[-8000:]
+
+
+def check_deploy_health(health_url: str | None) -> bool | None:
+    """True/False if checked, None if no URL configured."""
+    if not health_url:
+        return None
+    try:
+        import urllib.request
+        req = urllib.request.Request(health_url, method="GET")
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return 200 <= resp.status < 300
+    except Exception:
+        return False
+
+
+# Heartbeat file for the dead-man's-switch below. Set by watch() at startup;
+# notify() records every attempt + every success so a checker can detect
+# "attempts happening, successes not" — the failure class an in-process
+# try/except structurally cannot catch about itself (lived incident: SSL cert
+# error silently fell back to log-only for 8 days).
+_HEARTBEAT_DIR: Path | None = None
+
+
+def set_heartbeat_dir(pcp_dir: Path) -> None:
+    global _HEARTBEAT_DIR
+    _HEARTBEAT_DIR = pcp_dir
+
+
+def _heartbeat_record(field: str) -> None:
+    if _HEARTBEAT_DIR is None:
+        return
+    try:
+        import yaml
+        path = _HEARTBEAT_DIR / "notify_heartbeat.yaml"
+        data = {}
+        if path.exists():
+            data = yaml.safe_load(path.read_text()) or {}
+        data[field] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        path.write_text(yaml.dump(data))
+    except Exception:
+        pass
+
+
+def check_notify_heartbeat(pcp_dir: Path, lag_hours: float = 1.0) -> str | None:
+    """Dead-man's-switch: if notification attempts keep happening but the last
+    SUCCESS lags the last attempt by more than lag_hours, the pipeline is
+    failing persistently — return a warning string (caller screams on console;
+    notifying about a broken notifier is structurally pointless)."""
+    try:
+        import yaml
+        path = pcp_dir / "notify_heartbeat.yaml"
+        if not path.exists():
+            return None
+        data = yaml.safe_load(path.read_text()) or {}
+        attempt, success = data.get("last_attempt"), data.get("last_success")
+        if not attempt:
+            return None
+        fmt = "%Y-%m-%dT%H:%M:%SZ"
+        attempt_ts = time.mktime(time.strptime(attempt, fmt))
+        success_ts = time.mktime(time.strptime(success, fmt)) if success else 0
+        if attempt_ts - success_ts > lag_hours * 3600:
+            return (
+                f"Notification pipeline appears BROKEN: last successful delivery "
+                f"{'never' if not success else success}, but attempts continue (last {attempt}). "
+                "Humans are NOT being reached — check slack-notify."
+            )
+    except Exception:
+        return None
+    return None
+
+
+def notify(message: str) -> None:
+    """Send via slack-notify if available; NEVER fail silently. A delivery
+    failure downgrading to console-only without saying so is a lived incident
+    class here (an SSL cert error once silently fell back to log-only and a
+    security STOP sat unread for 8 days) — if delivery fails, say so loudly
+    so the console record itself shows the human was probably NOT reached."""
+    delivered = False
+    if shutil.which("slack-notify"):
+        _heartbeat_record("last_attempt")
+        try:
+            result = subprocess.run(["slack-notify", message], capture_output=True, text=True, timeout=15)
+            delivered = result.returncode == 0
+            if delivered:
+                _heartbeat_record("last_success")
+            if not delivered:
+                console.print(
+                    f"[red bold]Notification delivery FAILED[/red bold] "
+                    f"(slack-notify exit {result.returncode}: {(result.stderr or result.stdout).strip()[:200]}) "
+                    "— message below reached the console ONLY, a human has likely not seen it."
+                )
+        except subprocess.TimeoutExpired:
+            console.print(
+                "[red bold]Notification delivery FAILED[/red bold] (slack-notify timed out) "
+                "— message below reached the console ONLY, a human has likely not seen it."
+            )
+    console.print(f"[dim]Notify: {message}[/dim]")
+
+
+def check_stale_escalations(pcp_dir: Path, already_reported: set) -> None:
+    """Escalation-acknowledgment watchdog: an escalation recorded but never
+    acted on (criterion still pending past PCP_ESCALATION_STALE_HOURS,
+    default 24h) gets re-surfaced — recording an escalation is not the same
+    fact as a human having seen it. Each stale entry is re-notified once per
+    watch run, not once per poll (notification fatigue is its own failure
+    mode: a team trained to ignore pings misses the real one)."""
+    from pcp import escalations
+    for e in escalations.find_stale(pcp_dir):
+        key = (e.get("module"), e.get("criterion_id"), e.get("timestamp"))
+        if key in already_reported:
+            continue
+        already_reported.add(key)
+        state = e.get("state", "unacked")
+        detail = (
+            "no human has acknowledged it" if state == "unacked"
+            else "acknowledged but still unresolved (seen is not fixed)"
+        )
+        msg = (
+            f"pcp watch: STALE ESCALATION [{state}] — {e.get('module')}/{e.get('criterion_id')} "
+            f"({e.get('category', 'uncategorized')}) waiting {e.get('age_hours')}h; {detail}. "
+            f"Ack with: pcp escalations --ack {e.get('module')}/{e.get('criterion_id')}"
+        )
+        console.print(f"[red bold]{msg}[/red bold]")
+        notify(msg)
+
+
+def attempt_auto_fix(pcp_dir: Path, failure_context: str, session_id: str, is_first_attempt: bool) -> bool:
+    """Spawn a claude -p session instructed to diagnose+fix+commit+push.
+
+    session_id ties consecutive auto-fix attempts within the same failure
+    streak together: is_first_attempt=True opens a fresh session with
+    --session-id, subsequent consecutive attempts --resume it instead of
+    cold-restarting -- the same fix build.py already applies to its own
+    per-criterion retries (a cold restart re-explores the whole repo and
+    re-pastes context for every attempt). The caller resets to a new
+    session_id once CI succeeds, so a genuinely new failure never resumes
+    stale context from an unrelated one.
+
+    Returns True if the agent ran without a process-level error — not a
+    guarantee the fix worked, the next poll cycle re-checks CI for that."""
+    prompt = (
+        "A CI run failed on this repository. FIRST classify the failure from the log below "
+        "as exactly one of: CODE (a real defect in application/test logic), FLAKY (test "
+        "passes/fails non-deterministically — timing, ordering, network, shared state), or "
+        "INFRA (runner/tooling/dependency-resolution problem outside the code). State the "
+        "classification and your evidence for it before doing anything else.\n"
+        "- CODE: fix the underlying defect, commit, and push to the current branch.\n"
+        "- FLAKY: do NOT patch application code to make the symptom go away — masking an "
+        "unreliable test with application changes creates debt and hides the real problem. "
+        "Quarantine the test instead (mark it skipped/xfail with a comment naming the "
+        "flakiness evidence), commit that, and say clearly a human needs to fix the test's "
+        "underlying non-determinism.\n"
+        "- INFRA: do NOT change application code. Fix the workflow/tooling config only if "
+        "the cause is unambiguous from the log; otherwise change nothing and report what "
+        "you found.\n"
+        "Follow this project's CLAUDE.md and ci_rules.yaml.\n\n"
+        f"## CI Failure Log\n```\n{failure_context}\n```\n"
+    )
+    session_flag = ["--session-id", session_id] if is_first_attempt else ["--resume", session_id]
+    cmd = [
+        _claude_bin(), "-p",
+        "--permission-mode", "acceptEdits",
+        "--output-format", "json",
+        "--max-budget-usd", _watch_agent_max_budget_usd(),
+        *session_flag,
+    ]
+    build_model = os.environ.get("PCP_BUILD_MODEL")
+    if build_model:
+        cmd += ["--model", build_model]
+    try:
+        result = subprocess.run(
+            cmd, input=prompt, text=True, capture_output=True, cwd=pcp_dir.parent, timeout=600,
+        )
+    except subprocess.TimeoutExpired:
+        return False
+    return result.returncode == 0
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--interval", default=DEFAULT_INTERVAL, show_default=True, help="Poll interval in seconds.")
+@click.option("--once", is_flag=True, help="Single pass, no loop/sleep — for testing or one-shot checks.")
+@click.option("--max-iterations", default=None, type=int, help="Stop after N polls (default: PCP_WATCH_MAX_ITERATIONS env or 200).")
+@click.option("--report-only", is_flag=True,
+              help="Report + notify on failures but never spawn a fix agent. Recommended first "
+                   "phase on a new project — measure diagnosis signal quality before granting "
+                   "auto-fix. Also enabled via PCP_WATCH_REPORT_ONLY=1.")
+def watch(project_path: str | None, interval: int, once: bool, max_iterations: int | None, report_only: bool):
+    """Continuously monitor CI + deploy health, auto-diagnose and fix failures."""
+    try:
+        pcp_dir = find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+
+    project_root = pcp_dir.parent
+    check_environment(pcp_dir, fatal_on_missing_required=False)
+    check_agent_depth_or_exit()
+    integrations = load_integrations(pcp_dir)
+    health_url = (integrations.get("deploy") or {}).get("health_check_url")
+
+    if not shutil.which("gh") and not health_url:
+        console.print("[yellow]Neither `gh` CLI nor a configured health-check URL found — nothing to watch.[/yellow]")
+        console.print("[dim]Run `pcp doctor` to configure a deploy health-check URL.[/dim]")
+        sys.exit(0)
+
+    set_heartbeat_dir(pcp_dir)
+    hb_warning = check_notify_heartbeat(pcp_dir)
+    if hb_warning:
+        console.print(f"[red bold]{hb_warning}[/red bold]")
+
+    report_only = report_only or os.environ.get("PCP_WATCH_REPORT_ONLY", "") in ("1", "true", "yes")
+    if report_only:
+        console.print("[cyan]Report-only mode: failures will be reported/notified, no fix agent will be spawned.[/cyan]")
+
+    max_iterations = max_iterations or _default_max_iterations()
+    max_consecutive_fixes = _max_consecutive_auto_fix_attempts()
+    last_seen_run_id = None
+    iteration = 0
+    consecutive_fix_attempts = 0
+    auto_fix_disabled = False
+    fix_session_id = None
+    stale_escalations_reported: set = set()
+
+    while True:
+        iteration += 1
+        console.print(f"[dim]Watch poll #{iteration}/{max_iterations} ({time.strftime('%H:%M:%S')})...[/dim]")
+
+        run = get_latest_ci_run(project_root)
+        if run and run.get("databaseId") != last_seen_run_id:
+            last_seen_run_id = run.get("databaseId")
+            if run.get("status") == "completed" and run.get("conclusion") not in ("success", None):
+                console.print(f"[red]CI run failed:[/red] {run.get('name')} — {run.get('url')}")
+                if report_only:
+                    notify(f"pcp watch (report-only): CI run failed — {run.get('name')} {run.get('url')}")
+                elif auto_fix_disabled:
+                    notify(f"pcp watch: CI still failing after {max_consecutive_fixes} auto-fix attempts — auto-fix paused, needs human attention. {run.get('url')}")
+                else:
+                    from pcp import spend
+                    allowed, spend_reason = spend.check_ceiling(pcp_dir)
+                    if not allowed:
+                        console.print(f"[red bold]Project spend ceiling reached:[/red bold] {spend_reason}")
+                        notify(f"pcp watch: CI failed but auto-fix skipped — {spend_reason}. {run.get('url')}")
+                    else:
+                        logs = get_failed_logs(project_root, run["databaseId"])
+                        console.print("[dim]Attempting auto-fix...[/dim]")
+                        is_first_attempt = fix_session_id is None
+                        if is_first_attempt:
+                            fix_session_id = str(uuid.uuid4())
+                        fixed = attempt_auto_fix(pcp_dir, logs, fix_session_id, is_first_attempt)
+                        consecutive_fix_attempts += 1
+                        if fixed:
+                            notify(f"pcp watch: auto-fix attempted for failed CI run {run.get('url')} — pushed, awaiting next CI result.")
+                        else:
+                            notify(f"pcp watch: CI run failed and auto-fix attempt errored — needs human attention. {run.get('url')}")
+                        if consecutive_fix_attempts >= max_consecutive_fixes:
+                            auto_fix_disabled = True
+                            notify(
+                                f"pcp watch: {consecutive_fix_attempts} consecutive auto-fix attempts without a CI success — "
+                                "pausing auto-fix (possible regression loop). Still watching and reporting status."
+                            )
+            elif run.get("status") == "completed" and run.get("conclusion") == "success":
+                console.print(f"[green]CI run succeeded:[/green] {run.get('name')}")
+                consecutive_fix_attempts = 0
+                auto_fix_disabled = False
+                fix_session_id = None
+
+        check_stale_escalations(pcp_dir, stale_escalations_reported)
+
+        if health_url:
+            healthy = check_deploy_health(health_url)
+            if healthy is False:
+                console.print(f"[red]Deploy health check FAILED:[/red] {health_url}")
+                notify(f"pcp watch: deploy health check failing at {health_url}")
+            elif healthy is True:
+                console.print(f"[green]Deploy healthy:[/green] {health_url}")
+
+        if once:
+            break
+        if iteration >= max_iterations:
+            console.print(f"[yellow]Reached max iterations ({max_iterations}) — stopping. Override with --max-iterations or PCP_WATCH_MAX_ITERATIONS.[/yellow]")
+            break
+        time.sleep(interval)

pcp/config_audit.py

@@ -0,0 +1,141 @@
+"""Agent-config surface audit — deterministic, no LLM, no external tool.
+
+PCP's QA gates scan the *built code* (SAST/secret-scan via semgrep), but
+nothing audited the project's *agent-facing configuration* — the surface an
+agent actually executes from: `.claude/settings.json` hooks (arbitrary shell
+commands), `.mcp.json` servers (which `pcp doctor` itself now scaffolds for
+Context7), and instruction files (CLAUDE.md/AGENTS.md). Reference-pattern
+from ECC's AgentShield (affaan-m/ECC), scoped down to a deterministic scan:
+secret literals, and hook/server commands that fetch-and-execute remote code.
+
+Advisory only — surfaced by `pcp doctor`, never blocks. A finding here is a
+signal for human review, same posture as `pcp audit`'s dead-code findings.
+"""
+
+import json
+import re
+from pathlib import Path
+
+# Anchored to real token shapes, not bare prefixes — `sk-` alone would flag
+# prose. Patterns matched against raw file text.
+SECRET_PATTERNS: list[tuple[str, str]] = [
+    ("Anthropic API key", r"sk-ant-[A-Za-z0-9_-]{20,}"),
+    ("OpenAI-style API key", r"sk-[A-Za-z0-9]{20,}"),
+    ("GitHub token", r"gh[pousr]_[A-Za-z0-9]{36,}"),
+    ("GitHub fine-grained PAT", r"github_pat_[A-Za-z0-9_]{22,}"),
+    ("AWS access key", r"AKIA[0-9A-Z]{16}"),
+    ("Slack token", r"xox[bpoas]-[0-9A-Za-z-]{10,}"),
+    ("Google API key", r"AIza[0-9A-Za-z_-]{35}"),
+    ("Private key block", r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
+]
+
+SUSPICIOUS_COMMAND_PATTERNS: list[tuple[str, str]] = [
+    ("remote script piped to shell", r"(curl|wget)[^|;&\n]*\|\s*(ba|z)?sh"),
+    ("base64-decoded payload piped to shell", r"base64\s+(-d|--decode)[^|\n]*\|\s*(ba|z)?sh"),
+    ("recursive delete from root/home", r"rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)\s+[/~]"),
+]
+
+INSTRUCTION_FILES = ("CLAUDE.md", "AGENTS.md", "GEMINI.md")
+SETTINGS_FILES = (".claude/settings.json", ".claude/settings.local.json")
+
+
+def _finding(file: str, category: str, detail: str) -> dict:
+    return {"file": file, "category": category, "detail": detail}
+
+
+def _scan_text_for_secrets(text: str, rel_path: str) -> list[dict]:
+    findings = []
+    for name, pattern in SECRET_PATTERNS:
+        for m in re.finditer(pattern, text):
+            token = m.group(0)
+            findings.append(_finding(
+                rel_path, "secret",
+                f"{name} literal ({token[:8]}…{token[-4:]}) — move to an env var/secret store",
+            ))
+    return findings
+
+
+def _scan_text_for_suspicious_commands(text: str, rel_path: str, context: str) -> list[dict]:
+    findings = []
+    for name, pattern in SUSPICIOUS_COMMAND_PATTERNS:
+        if re.search(pattern, text):
+            findings.append(_finding(
+                rel_path, "suspicious-command",
+                f"{name} in {context} — an agent session executes this without review",
+            ))
+    return findings
+
+
+def _iter_hook_commands(settings: dict):
+    """Yield every command string from Claude Code's hooks structure:
+    {"hooks": {"<Event>": [{"hooks": [{"type": "command", "command": "..."}]}]}}"""
+    for event_entries in (settings.get("hooks") or {}).values():
+        if not isinstance(event_entries, list):
+            continue
+        for entry in event_entries:
+            for h in (entry.get("hooks") or []) if isinstance(entry, dict) else []:
+                if isinstance(h, dict) and h.get("command"):
+                    yield str(h["command"])
+
+
+def _audit_settings_file(project_root: Path, rel_path: str) -> list[dict]:
+    path = project_root / rel_path
+    if not path.exists():
+        return []
+    text = path.read_text(errors="replace")
+    findings = _scan_text_for_secrets(text, rel_path)
+    try:
+        settings = json.loads(text)
+    except json.JSONDecodeError:
+        findings.append(_finding(rel_path, "unparseable", "not valid JSON — hooks could not be audited"))
+        return findings
+    for cmd in _iter_hook_commands(settings):
+        findings.extend(_scan_text_for_suspicious_commands(cmd, rel_path, "a hook command"))
+    return findings
+
+
+def _audit_mcp_config(project_root: Path) -> list[dict]:
+    path = project_root / ".mcp.json"
+    if not path.exists():
+        return []
+    text = path.read_text(errors="replace")
+    findings = _scan_text_for_secrets(text, ".mcp.json")
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        findings.append(_finding(".mcp.json", "unparseable", "not valid JSON — servers could not be audited"))
+        return findings
+    for server_name, server in (data.get("mcpServers") or {}).items():
+        if not isinstance(server, dict):
+            continue
+        blob = " ".join([str(server.get("command", ""))] + [str(a) for a in server.get("args", [])])
+        findings.extend(_scan_text_for_suspicious_commands(
+            blob, ".mcp.json", f"MCP server '{server_name}' launch command"))
+        for env_key, env_val in (server.get("env") or {}).items():
+            for name, pattern in SECRET_PATTERNS:
+                if re.fullmatch(pattern, str(env_val)):
+                    findings.append(_finding(
+                        ".mcp.json", "secret",
+                        f"MCP server '{server_name}' env {env_key} holds an inline {name} — "
+                        "reference an environment variable instead",
+                    ))
+    return findings
+
+
+def audit_agent_config(project_root: Path) -> list[dict]:
+    """Full sweep. Returns findings, deduplicated, stable order."""
+    findings: list[dict] = []
+    for rel in SETTINGS_FILES:
+        findings.extend(_audit_settings_file(project_root, rel))
+    findings.extend(_audit_mcp_config(project_root))
+    for rel in INSTRUCTION_FILES:
+        path = project_root / rel
+        if path.exists():
+            findings.extend(_scan_text_for_secrets(path.read_text(errors="replace"), rel))
+    seen, unique = set(), []
+    for f in findings:
+        key = (f["file"], f["category"], f["detail"])
+        if key not in seen:
+            seen.add(key)
+            unique.append(f)
+    return unique

pcp/context_map.py

@@ -0,0 +1,124 @@
+"""Deterministic context routing — scenario → files an agent should read.
+
+2026-07-18, from the context-contamination review. PCP already routed agent
+context in code (prompt builders pointing at specific files per scenario),
+but the routing was scattered and unauditable. `.pcp/context_map.yaml` makes
+it one declarative, reviewable, drift-checkable table.
+
+Principles (the review's three amendments, enforced by design):
+- Scenario detection stays rung-1: scenarios are keyed off schema fields
+  (logic_tier present, UI keyword match, module name) — never an LLM call.
+- Intent files are routed WHOLE (objective/spec) — fragmenting spec content
+  measurably collapses agent faithfulness (SLUMP, arXiv:2603.17104).
+- Sliced state is always a GENERATED projection of a canonical source
+  (module docs/built.md is regenerated from acceptance.yaml), never a
+  hand-maintained copy — divergence is structurally impossible.
+
+A missing context_map.yaml falls back to the built-in defaults below, so
+projects scaffolded before this feature keep working unchanged.
+"""
+
+from pathlib import Path
+
+import yaml
+
+CONTEXT_MAP_FILE = "context_map.yaml"
+
+# Built-in defaults — mirror the routing the prompt builders used before the
+# table existed. `{module}` is substituted at resolve time. `fallback` is
+# used only when none of the primary files exist.
+DEFAULT_ROUTES: dict[str, dict] = {
+    "always": {
+        "files": [".pcp/objective.md", ".pcp/architecture.md", ".pcp/architect_persona.md"],
+    },
+    "module_state": {
+        # The module's own generated state slice — NOT program-wide
+        # current_state.md, which on a many-module project is mostly other
+        # modules' context (the contamination the review named).
+        "files": [".pcp/strategy/modules/{module}/docs/built.md"],
+        "fallback": [".pcp/current_state.md"],
+    },
+    "ui_facing": {
+        "files": [".pcp/design_system.md"],
+    },
+    "logic_tier_declared": {
+        "files": [".pcp/logic_tier_guide.md"],
+    },
+}
+
+
+def load(pcp_dir: Path) -> dict[str, dict]:
+    path = pcp_dir / CONTEXT_MAP_FILE
+    if not path.exists():
+        return DEFAULT_ROUTES
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return DEFAULT_ROUTES
+    routes = data.get("routes")
+    if not isinstance(routes, dict) or not routes:
+        return DEFAULT_ROUTES
+    return routes
+
+
+def resolve(pcp_dir: Path, scenario: str, module: str | None = None) -> list[str]:
+    """Project-root-relative paths that exist for this scenario. Primary
+    files first; fallback only when NO primary file exists."""
+    routes = load(pcp_dir)
+    route = routes.get(scenario)
+    if not route:
+        return []
+    project_root = pcp_dir.parent
+
+    def _expand(paths: list) -> list[str]:
+        out = []
+        for p in paths or []:
+            p = str(p)
+            if "{module}" in p:
+                if not module:
+                    continue
+                p = p.replace("{module}", module)
+            if (project_root / p).exists():
+                out.append(p)
+        return out
+
+    primary = _expand(route.get("files", []))
+    if primary:
+        return primary
+    return _expand(route.get("fallback", []))
+
+
+def validate(pcp_dir: Path, known_modules: list[str] | None = None) -> list[str]:
+    """Staleness check (CTRL-021): every routed path must resolve to at least
+    one existing file (for {module} templates: for at least one known module,
+    or via fallback). A route pointing at nothing silently starves agents of
+    context — worse and less visible than over-feeding."""
+    findings = []
+    routes = load(pcp_dir)
+    project_root = pcp_dir.parent
+    modules = known_modules or [p.name for p in (pcp_dir / "strategy" / "modules").glob("*") if p.is_dir()]
+
+    for scenario, route in routes.items():
+        if not isinstance(route, dict):
+            findings.append(f"context_map: route '{scenario}' is not a mapping")
+            continue
+        all_paths = list(route.get("files", [])) + list(route.get("fallback", []))
+        if not all_paths:
+            findings.append(f"context_map: route '{scenario}' lists no files")
+            continue
+        any_exists = False
+        for p in all_paths:
+            p = str(p)
+            if "{module}" in p:
+                if any((project_root / p.replace("{module}", m)).exists() for m in modules):
+                    any_exists = True
+                    break
+            elif (project_root / p).exists():
+                any_exists = True
+                break
+        if not any_exists:
+            findings.append(
+                f"context_map: route '{scenario}' resolves to zero existing files "
+                f"({', '.join(str(p) for p in all_paths[:3])}) — agents routed here get nothing"
+            )
+    return findings