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

pcp/discovery/graph.py

@@ -0,0 +1,110 @@
+"""Build import dependency graph from source files."""
+
+import ast
+import re
+from pathlib import Path
+
+
+def extract_imports_python(path: Path, root: Path) -> list[str]:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"))
+    except SyntaxError:
+        return []
+
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                imports.append(node.module.split(".")[0])
+    return imports
+
+
+def extract_imports_ts_js(path: Path, root: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    # import ... from '...' or require('...')
+    patterns = [
+        r'from\s+[\'"]([^\'"\s]+)[\'"]',
+        r'require\s*\(\s*[\'"]([^\'"\s]+)[\'"]\s*\)',
+        r'import\s*\(\s*[\'"]([^\'"\s]+)[\'"]\s*\)',
+    ]
+    imports = []
+    for pattern in patterns:
+        for match in re.finditer(pattern, text):
+            imp = match.group(1)
+            if imp.startswith("."):
+                # relative — resolve to a sibling file/dir name
+                resolved = (path.parent / imp).resolve()
+                try:
+                    imp = str(resolved.relative_to(root)).split("/")[0]
+                except ValueError:
+                    continue
+            else:
+                imp = imp.split("/")[0].lstrip("@")
+            imports.append(imp)
+    return imports
+
+
+def extract_imports_rust(path: Path, root: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    imports = []
+    for match in re.finditer(r'\buse\s+([\w:]+)', text):
+        crate = match.group(1).split("::")[0]
+        imports.append(crate)
+    for match in re.finditer(r'\bextern\s+crate\s+(\w+)', text):
+        imports.append(match.group(1))
+    return imports
+
+
+def extract_imports_go(path: Path, root: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    imports = []
+    for match in re.finditer(r'"([^"]+)"', text):
+        pkg = match.group(1)
+        parts = pkg.split("/")
+        # local package = last path component
+        imports.append(parts[-1])
+    return imports
+
+
+EXTRACTORS = {
+    ".py": extract_imports_python,
+    ".ts": extract_imports_ts_js,
+    ".tsx": extract_imports_ts_js,
+    ".js": extract_imports_ts_js,
+    ".jsx": extract_imports_ts_js,
+    ".rs": extract_imports_rust,
+    ".go": extract_imports_go,
+}
+
+
+def build_dependency_graph(files: list[Path], root: Path) -> dict[str, set[str]]:
+    """
+    Returns adjacency dict: {file_key: {imported_file_key, ...}}
+    file_key = path relative to root, using '/' separator
+    Only edges between files in the project (not external packages).
+    """
+    file_keys = {f: str(f.relative_to(root)) for f in files}
+    # index by stem and by relative path for resolution
+    stem_index: dict[str, str] = {}
+    for f, key in file_keys.items():
+        stem_index[f.stem] = key
+        stem_index[str(f.relative_to(root))] = key
+
+    graph: dict[str, set[str]] = {key: set() for key in file_keys.values()}
+
+    for f, key in file_keys.items():
+        extractor = EXTRACTORS.get(f.suffix)
+        if not extractor:
+            continue
+        imports = extractor(f, root)
+        for imp in imports:
+            # resolve to a known file key
+            target = stem_index.get(imp) or stem_index.get(imp + ".py") or \
+                     stem_index.get(imp + ".ts") or stem_index.get(imp + ".js")
+            if target and target != key:
+                graph[key].add(target)
+
+    return graph

pcp/discovery/scanner.py

@@ -0,0 +1,109 @@
+"""Stack detection and file inventory for brownfield import."""
+
+import re
+from pathlib import Path
+
+
+STACK_SIGNALS = {
+    "python": ["pyproject.toml", "setup.py", "requirements.txt", "Pipfile"],
+    "typescript": ["tsconfig.json", "package.json"],
+    "javascript": ["package.json"],
+    "rust": ["Cargo.toml"],
+    "swift": ["Package.swift", "*.xcodeproj"],
+    "go": ["go.mod"],
+    "java": ["pom.xml", "build.gradle"],
+    "ruby": ["Gemfile"],
+}
+
+SOURCE_EXTENSIONS = {
+    "python": [".py"],
+    "typescript": [".ts", ".tsx"],
+    "javascript": [".js", ".jsx"],
+    "rust": [".rs"],
+    "swift": [".swift"],
+    "go": [".go"],
+    "java": [".java"],
+    "ruby": [".rb"],
+}
+
+IGNORE_DIRS = {
+    ".git", ".pcp", "node_modules", "__pycache__", ".venv", "venv",
+    "dist", "build", ".build", "target", ".next", ".nuxt", "coverage",
+    ".tox", "eggs", "*.egg-info",
+}
+
+
+def detect_stack(root: Path) -> list[str]:
+    detected = []
+    for lang, signals in STACK_SIGNALS.items():
+        for signal in signals:
+            if signal.startswith("*"):
+                if list(root.glob(f"**/{signal}")):
+                    detected.append(lang)
+                    break
+            else:
+                if (root / signal).exists():
+                    detected.append(lang)
+                    break
+    # deduplicate: ts implies js, prefer ts
+    if "typescript" in detected and "javascript" in detected:
+        detected.remove("javascript")
+    return detected or ["unknown"]
+
+
+def collect_source_files(root: Path, stack: list[str]) -> list[Path]:
+    extensions = set()
+    for lang in stack:
+        extensions.update(SOURCE_EXTENSIONS.get(lang, []))
+    if not extensions:
+        extensions = {".py", ".ts", ".tsx", ".js", ".jsx", ".rs", ".swift", ".go"}
+
+    files = []
+    for path in root.rglob("*"):
+        if any(part in IGNORE_DIRS or part.endswith(".egg-info") for part in path.parts):
+            continue
+        if path.suffix in extensions and path.is_file():
+            files.append(path)
+    return sorted(files)
+
+
+def detect_entry_points(root: Path, stack: list[str]) -> list[str]:
+    entries = []
+    candidates = [
+        "main.py", "app.py", "server.py", "wsgi.py", "asgi.py",
+        "index.ts", "index.js", "main.ts", "server.ts", "app.ts",
+        "src/main.rs", "src/lib.rs",
+        "main.go", "cmd/main.go",
+        "Sources/*/main.swift",
+    ]
+    for c in candidates:
+        matches = list(root.glob(c))
+        entries.extend(str(m.relative_to(root)) for m in matches)
+    return entries
+
+
+def read_manifest_deps(root: Path) -> dict[str, list[str]]:
+    deps = {}
+    pkg = root / "package.json"
+    if pkg.exists():
+        import json
+        try:
+            data = json.loads(pkg.read_text())
+            deps["dependencies"] = list(data.get("dependencies", {}).keys())
+            deps["devDependencies"] = list(data.get("devDependencies", {}).keys())
+        except Exception:
+            pass
+
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text()
+        matches = re.findall(r'^\s*"([a-zA-Z0-9_\-]+)[>=<!\[]', text, re.MULTILINE)
+        deps["python"] = matches
+
+    cargo = root / "Cargo.toml"
+    if cargo.exists():
+        text = cargo.read_text()
+        matches = re.findall(r'^([a-zA-Z0-9_\-]+)\s*=', text, re.MULTILINE)
+        deps["rust"] = [m for m in matches if m not in ("package", "lib", "bin", "dependencies", "features")]
+
+    return deps

pcp/escalations.py

@@ -0,0 +1,193 @@
+"""Escalation ledger + staleness watchdog.
+
+Closes the "Escalation Failure" mode (a human never actually sees the
+escalation) — PCP has lived this exact incident once: a slack-notify SSL
+failure silently fell back to log-only and a security STOP sat unread for
+8 days. Recording an escalation is not the same thing as a human seeing it.
+
+v2 (2026-07-17, PagerDuty/incident.io reference patterns):
+- ACK and RESOLVE are separate states with separate timers. "Acknowledged"
+  (a human saw it — `pcp escalations --ack module/criterion`) is distinct
+  from "resolved" (the criterion actually left pending). An acked-but-stalled
+  escalation re-screams after 2x the threshold — a glance at Slack must not
+  silence the watchdog permanently.
+- Stakes-scaled timeout: a module that other modules depend on blocks future
+  waves — its escalations go stale at HALF the normal threshold
+  (incident.io's SLO-derived-timeout pattern, deterministic here).
+- MTTA: median time-to-acknowledge across acked entries, surfaced in
+  provenance — the feedback loop proving the ledger is actually watched.
+- Failure category (memory/planning/action/system, from the AgentDebug
+  taxonomy arXiv:2509.25370) recorded per escalation, keyword-classified
+  deterministically from the block findings — sharpens human routing.
+
+`.pcp/escalations.yaml` is a plain append list (operational record, not
+hash-chained — same posture as prune_log.yaml). Resolution stays the
+deterministic proxy: criterion no longer pending in acceptance.yaml.
+"""
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+ESCALATIONS_FILE = "escalations.yaml"
+DEFAULT_STALE_HOURS = 24
+_TS_FMT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def _stale_hours() -> float:
+    return float(os.environ.get("PCP_ESCALATION_STALE_HOURS", str(DEFAULT_STALE_HOURS)))
+
+
+def classify_failure(findings: list[str]) -> str:
+    """Deterministic keyword classification into the AgentDebug taxonomy —
+    advisory routing signal, not ground truth."""
+    text = " ".join(findings).lower()
+    if "timeout" in text or "killed" in text or "exited with" in text or "errored" in text:
+        return "system"
+    if "test suite" in text or "lint" in text or "sast" in text or "scope guard" in text:
+        return "action"
+    if "alignment" in text or "architect" in text or "regression" in text or "coverage" in text:
+        return "planning"
+    if "context" in text or "session" in text:
+        return "memory"
+    return "uncategorized"
+
+
+def record(pcp_dir: Path, module: str, criterion_id: str, route: str = "human",
+           findings: list[str] | None = None) -> None:
+    """Append one escalation entry. Never raises — an escalation must not be
+    lost because the ledger write failed, the console/notify path still runs."""
+    path = pcp_dir / ESCALATIONS_FILE
+    entry = {
+        "module": module,
+        "criterion_id": criterion_id,
+        "route": route,
+        "category": classify_failure(findings or []),
+        "timestamp": datetime.now(timezone.utc).strftime(_TS_FMT),
+        "acknowledged_at": None,
+        "findings_count": len(findings or []),
+        "findings_preview": (findings or [])[:3],
+    }
+    try:
+        entries = load(pcp_dir)
+        entries.append(entry)
+        path.write_text(yaml.dump({"escalations": entries}, default_flow_style=False))
+    except Exception:
+        pass
+
+
+def load(pcp_dir: Path) -> list[dict]:
+    path = pcp_dir / ESCALATIONS_FILE
+    if not path.exists():
+        return []
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return []
+    entries = data.get("escalations", [])
+    return entries if isinstance(entries, list) else []
+
+
+def acknowledge(pcp_dir: Path, module: str, criterion_id: str) -> int:
+    """Stamp acknowledged_at on all un-acked entries for module/criterion.
+    Returns count acked."""
+    entries = load(pcp_dir)
+    now = datetime.now(timezone.utc).strftime(_TS_FMT)
+    count = 0
+    for e in entries:
+        if e.get("module") == module and e.get("criterion_id") == criterion_id and not e.get("acknowledged_at"):
+            e["acknowledged_at"] = now
+            count += 1
+    if count:
+        (pcp_dir / ESCALATIONS_FILE).write_text(yaml.dump({"escalations": entries}, default_flow_style=False))
+    return count
+
+
+def _criterion_still_pending(pcp_dir: Path, module: str, criterion_id: str) -> bool:
+    af = pcp_dir / "strategy" / "modules" / module / "acceptance.yaml"
+    if not af.exists():
+        return False
+    try:
+        data = yaml.safe_load(af.read_text()) or {}
+    except yaml.YAMLError:
+        return False
+    for c in data.get("criteria", []):
+        if c.get("id") == criterion_id:
+            return c.get("status", "pending") != "complete"
+    return False
+
+
+def _module_has_dependents(pcp_dir: Path, module: str) -> bool:
+    """True if any OTHER module declares this one as a dependency — its
+    failure blocks future waves, so its escalations get half the stale
+    window (stakes-scaled timeout)."""
+    modules_dir = pcp_dir / "strategy" / "modules"
+    if not modules_dir.exists():
+        return False
+    for spec_path in modules_dir.glob("*/spec.yaml"):
+        if spec_path.parent.name == module:
+            continue
+        try:
+            spec = yaml.safe_load(spec_path.read_text()) or {}
+        except yaml.YAMLError:
+            continue
+        if module in (spec.get("dependencies") or []):
+            return True
+    return False
+
+
+def _parse_ts(value: str) -> datetime | None:
+    try:
+        return datetime.strptime(value, _TS_FMT).replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return None
+
+
+def find_stale(pcp_dir: Path, now: datetime | None = None) -> list[dict]:
+    """Unresolved escalations needing a scream. Two states:
+    - state="unacked": no ack, older than the (stakes-scaled) threshold
+    - state="acked-stalled": acked, but criterion still pending past 2x
+      threshold since the ack — seen is not fixed."""
+    now = now or datetime.now(timezone.utc)
+    base_sec = _stale_hours() * 3600
+    stale = []
+    for e in load(pcp_dir):
+        ts = _parse_ts(e.get("timestamp", ""))
+        if ts is None:
+            continue
+        if not _criterion_still_pending(pcp_dir, e.get("module", ""), e.get("criterion_id", "")):
+            continue
+        threshold_sec = base_sec / 2 if _module_has_dependents(pcp_dir, e.get("module", "")) else base_sec
+        ack_ts = _parse_ts(e.get("acknowledged_at") or "")
+        e = dict(e)
+        if ack_ts is None:
+            age_sec = (now - ts).total_seconds()
+            if age_sec >= threshold_sec:
+                e["state"] = "unacked"
+                e["age_hours"] = round(age_sec / 3600, 1)
+                stale.append(e)
+        else:
+            since_ack = (now - ack_ts).total_seconds()
+            if since_ack >= 2 * threshold_sec:
+                e["state"] = "acked-stalled"
+                e["age_hours"] = round(since_ack / 3600, 1)
+                stale.append(e)
+    return stale
+
+
+def mtta_hours(pcp_dir: Path) -> float | None:
+    """Median time-to-acknowledge in hours across acked entries — the
+    'is anyone actually watching this ledger' metric (PagerDuty Escalation
+    Policy Insights pattern). None when nothing has ever been acked."""
+    deltas = []
+    for e in load(pcp_dir):
+        ts, ack = _parse_ts(e.get("timestamp", "")), _parse_ts(e.get("acknowledged_at") or "")
+        if ts and ack:
+            deltas.append((ack - ts).total_seconds() / 3600)
+    if not deltas:
+        return None
+    deltas.sort()
+    mid = len(deltas) // 2
+    return round(deltas[mid] if len(deltas) % 2 else (deltas[mid - 1] + deltas[mid]) / 2, 2)

pcp/evidence.py

@@ -0,0 +1,30 @@
+"""Full raw QA-proof storage.
+
+telemetry.jsonl records a verdict (pass/block/skip/etc) plus a truncated
+error summary — enough to see WHAT happened, not enough to independently
+verify it happened the way claimed. This module stores the untruncated raw
+artifact (full test output, full lint/SAST finding list, full architect-
+review/gate judge response) under .pcp/evidence/<module>/<criterion_id>/
+attempt_<n>/<check>.txt, and telemetry records the path instead of
+embedding truncated text — proof, not just a verdict.
+
+Always stores, on pass as well as block — "nothing to see, it passed" is
+exactly the case proof is missing for today (a PASS currently records
+nothing beyond the word "pass").
+"""
+
+from pathlib import Path
+
+
+def _evidence_dir(pcp_dir: Path, module: str, criterion_id: str | None, attempt: int) -> Path:
+    return Path(pcp_dir) / "evidence" / (module or "?") / (criterion_id or "?") / f"attempt_{attempt}"
+
+
+def store(pcp_dir: Path, module: str, criterion_id: str | None, attempt: int, check: str, content: str) -> str:
+    """Writes raw content, returns its path relative to pcp_dir (so telemetry
+    can reference it without duplicating the content inline)."""
+    directory = _evidence_dir(pcp_dir, module, criterion_id, attempt)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{check}.txt"
+    path.write_text("" if content is None else str(content))
+    return str(path.relative_to(pcp_dir))

pcp/evidence_chain.py

@@ -0,0 +1,56 @@
+"""Hash-chaining for append-only evidence logs (telemetry.jsonl,
+decision_log.jsonl, bypass_log.yaml).
+
+Each record's own hash covers its content plus the previous record's hash,
+so retroactively editing an earlier entry breaks every hash after it. This
+is tamper-EVIDENCE, not tamper-prevention: nothing stops someone editing the
+file directly, but doing so without also recomputing every downstream hash
+is now detectable by `verify_chain()` — and recomputing every downstream
+hash to hide a change is a much louder, more deliberate act than quietly
+editing one line, which is the actual threat model plain JSON-lines-append
+had no defense against at all.
+"""
+
+import hashlib
+import json
+
+
+def _canonical_hash(fields: dict) -> str:
+    return hashlib.sha256(json.dumps(fields, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def chain_entry(prev_hash: str | None, fields: dict) -> dict:
+    """Returns fields with prev_hash/entry_hash added. entry_hash covers the
+    full entry INCLUDING prev_hash, so it's a real link, not two independent
+    hashes that happen to sit in the same record."""
+    entry = {**fields, "prev_hash": prev_hash or "genesis"}
+    entry["entry_hash"] = _canonical_hash(entry)
+    return entry
+
+
+def verify_chain(records: list[dict]) -> list[dict]:
+    """Returns a list of break descriptions — empty means the chain is
+    intact. Checks, per record: (1) its own entry_hash matches a fresh
+    recompute of its content, (2) its prev_hash matches the actual previous
+    record's entry_hash (catches reordering/deletion, not just edits)."""
+    breaks = []
+    prev_hash = None
+    for i, r in enumerate(records):
+        claimed_hash = r.get("entry_hash")
+        claimed_prev = r.get("prev_hash")
+        content = {k: v for k, v in r.items() if k != "entry_hash"}
+        expected_hash = _canonical_hash(content)
+        expected_prev = prev_hash or "genesis"
+
+        if claimed_prev != expected_prev:
+            breaks.append({
+                "index": i, "issue": "prev_hash mismatch (reordered or deleted entry)",
+                "expected": expected_prev, "found": claimed_prev,
+            })
+        if claimed_hash != expected_hash:
+            breaks.append({
+                "index": i, "issue": "entry_hash mismatch (content altered after the fact)",
+                "expected": expected_hash, "found": claimed_hash,
+            })
+        prev_hash = claimed_hash
+    return breaks

pcp/impact.py

@@ -0,0 +1,164 @@
+"""Impacted-module test selection.
+
+2026-07-21 finding: qa.py's test-suite gate ran the FULL project-wide suite
+on every build attempt (up to 3x/criterion), deliberately never scoped --
+real cost as a project's suite grows, and the thing that turned a real
+2026-07-21 Project O incident (a squatted DB port) into an
+undiagnosable "timed out" for hours. Ganesh's direction: full-suite runs
+should be rare, and scoping should reuse PCP's own module dependency graph
+(coupling.py's build_dependency_graph, the same graph validate-strategy
+already trusts for coupling_score) rather than a bespoke file-level AST
+import analyzer -- one graph, one source of truth, not two competing ones.
+
+Two-stage, both deterministic, no ML:
+1. Module-level blast radius: which module(s) does the changed file belong
+   to (via each module's acceptance.yaml `target` fields), then every
+   module that transitively DEPENDS ON those modules (nx.ancestors on the
+   same graph coupling.py builds -- edge A->B means "A depends on B", so a
+   change to B can only break A's callers if A is broken, not the reverse;
+   ancestors of B are exactly "everything that could be affected if B
+   changes").
+2. File-level: within the blast-radius modules, resolve their declared
+   `target` files to candidate test files via common naming conventions
+   (test_<stem>.py, near the target or under tests/). This layer is
+   inherently a heuristic -- PCP doesn't mandate a test-file-location
+   convention -- so it degrades safely: any step that can't confidently
+   narrow returns None, and the caller MUST fall back to the full suite
+   rather than silently running zero tests. Never a hard requirement.
+"""
+
+from pathlib import Path
+
+import networkx as nx
+
+from pcp.coupling import build_dependency_graph
+from pcp.schema.validator import load_yaml
+
+
+def _load_modules_for_impact(pcp_dir: Path) -> dict[str, dict]:
+    modules_dir = pcp_dir / "strategy" / "modules"
+    modules: dict[str, dict] = {}
+    if not modules_dir.exists():
+        return modules
+    for spec_path in sorted(modules_dir.glob("*/spec.yaml")):
+        spec = load_yaml(spec_path) or {}
+        if not spec.get("deprecated"):
+            modules[spec_path.parent.name] = spec
+    return modules
+
+
+def _module_target_files(pcp_dir: Path, module_name: str) -> set[str]:
+    """Files this module's acceptance criteria declare as `target`."""
+    acc_path = pcp_dir / "strategy" / "modules" / module_name / "acceptance.yaml"
+    if not acc_path.exists():
+        return set()
+    data = load_yaml(acc_path) or {}
+    return {c["target"] for c in data.get("criteria", []) if c.get("target")}
+
+
+def _name_variants(module_name: str) -> set[str]:
+    """`web-server` also appears on disk as `web_server`."""
+    return {module_name, module_name.replace("-", "_")}
+
+
+def _owns_by_path_convention(module_name: str, changed_files: list[str]) -> bool:
+    """Does a changed file sit under a directory named for this module?
+
+    Attribution used to rely solely on criteria declaring `target`. Measured
+    2026-07-27 on Project O: only 51 of 382 criteria declare one, so
+    attribution returned an empty set for real changed files, scoping resolved
+    to None, and the gate fell back to the full 1,098-test suite on EVERY
+    criterion attempt -- roughly 7m46s each, about 13 hours of pure test time
+    across the remaining work, re-running the same tests every time.
+
+    Path convention covers what declarations do not: 18 of that project's 27
+    modules have a matching directory. Deterministic and documented, not a
+    guess -- a path SEGMENT must equal the module name (or its underscored
+    form), so `web-server` matches `src/app/web_server/routes.py` and never
+    matches `src/web_server_helpers.py`.
+    """
+    variants = _name_variants(module_name)
+    for f in changed_files:
+        if variants & set(Path(f).parts):
+            return True
+    return False
+
+
+def changed_files_to_modules(pcp_dir: Path, modules: dict[str, dict], changed_files: list[str]) -> set[str]:
+    """Which module(s) own at least one of changed_files.
+
+    Two signals, both deterministic: a criterion's declared `target`, and the
+    directory convention above. Declared targets alone left this inert on real
+    projects (see _owns_by_path_convention)."""
+    changed = set(changed_files)
+    return {
+        name for name in modules
+        if (_module_target_files(pcp_dir, name) & changed)
+        or _owns_by_path_convention(name, changed_files)
+    }
+
+
+def blast_radius_modules(modules: dict[str, dict], changed_module_names: set[str]) -> set[str]:
+    """changed_module_names plus every module that transitively depends on
+    any of them -- reuses coupling.py's own graph, not a second one."""
+    G = build_dependency_graph(modules)
+    radius = set(changed_module_names)
+    for m in changed_module_names:
+        if m in G:
+            radius |= nx.ancestors(G, m)
+    return radius
+
+
+def blast_radius_test_paths(pcp_dir: Path, project_root: Path, changed_files: list[str]) -> list[str] | None:
+    """Returns test file paths (relative to project_root) scoped to the
+    modules impacted by changed_files, or None if scoping can't be
+    determined with confidence -- caller must fall back to the full suite,
+    never silently run zero tests."""
+    modules = _load_modules_for_impact(pcp_dir)
+    if not modules:
+        return None
+
+    changed_modules = changed_files_to_modules(pcp_dir, modules, changed_files)
+    if not changed_modules:
+        return None  # can't attribute the change to a declared module -- don't guess
+
+    radius = blast_radius_modules(modules, changed_modules)
+
+    candidates: set[Path] = set()
+    for name in radius:
+        for target in _module_target_files(pcp_dir, name):
+            p = Path(target)
+            stem = p.stem
+            parent = p.parent
+            for cand in (
+                project_root / "tests" / f"test_{stem}.py",
+                project_root / parent / f"test_{stem}.py",
+                project_root / parent / "tests" / f"test_{stem}.py",
+            ):
+                if cand.exists():
+                    candidates.add(cand)
+            if stem.startswith("test_") and (project_root / target).exists():
+                candidates.add(project_root / target)  # the agent wrote the test as the "target" itself
+
+    # Per-module test DIRECTORIES (`tests/web_server/`) are how real projects
+    # actually lay this out; the file patterns above only find
+    # `tests/test_<stem>.py`. Without this the function returned None on
+    # Project O despite 18 of 27 modules having exactly such a directory.
+    for name in radius:
+        for variant in _name_variants(name):
+            d = project_root / "tests" / variant
+            if d.is_dir():
+                candidates.add(d)
+
+    if not candidates:
+        return None  # narrowed to real modules but found no matching test files -- fall back, don't run zero
+
+    # Modularity drop-tests always run, whatever the radius. They are the
+    # module-boundary guarantee -- "every module is a guest, it can leave
+    # without drama" -- so a change that quietly couples two modules must fail
+    # HERE, at the criterion, not survive until the wave merge.
+    for d in (project_root / "tests" / "modularity", project_root / "tests" / "test_modularity"):
+        if d.is_dir():
+            candidates.add(d)
+
+    return sorted(str(c.relative_to(project_root)) for c in candidates)