devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/verification/rigor_analytics.py

@@ -0,0 +1,130 @@
+"""Cross-run rigor analytics — tune thresholds from evidence, not guesses.
+
+Aggregates persisted verification gaps and correction manifests to surface
+recurring stub/effort failures and rough false-positive rates for advisory gaps.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List
+
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import GapRepository, TaskRepository
+from devcouncil.utils.json_persist import read_json
+
+
+@dataclass
+class RigorAnalyticsReport:
+    """Summary of rigor-gap patterns across all persisted verification runs."""
+
+    total_gaps: int = 0
+    by_gap_type: Dict[str, int] = field(default_factory=dict)
+    stub_by_task: Dict[str, int] = field(default_factory=dict)
+    effort_by_task: Dict[str, int] = field(default_factory=dict)
+    stub_declared_count: int = 0
+    tasks_with_repair_attempts: int = 0
+    avg_repair_attempts: float = 0.0
+    recurring_stub_tasks: List[str] = field(default_factory=list)
+    notes: List[str] = field(default_factory=list)
+
+    def to_markdown(self) -> str:
+        lines = [
+            "# Rigor analytics",
+            "",
+            f"- Total gaps recorded: **{self.total_gaps}**",
+            f"- Stub declarations (allow-stub audit): **{self.stub_declared_count}**",
+            f"- Tasks with repair manifests: **{self.tasks_with_repair_attempts}** "
+            f"(avg attempts: {self.avg_repair_attempts:.1f})",
+            "",
+            "## Gap counts by type",
+        ]
+        for gap_type, count in sorted(self.by_gap_type.items(), key=lambda x: -x[1]):
+            lines.append(f"- `{gap_type}`: {count}")
+        if self.recurring_stub_tasks:
+            lines.extend(["", "## Tasks recurring on stub gaps", ""])
+            for tid in self.recurring_stub_tasks:
+                lines.append(f"- {tid} ({self.stub_by_task.get(tid, 0)} stub gap(s))")
+        if self.notes:
+            lines.extend(["", "## Notes", ""])
+            lines.extend(f"- {n}" for n in self.notes)
+        return "\n".join(lines) + "\n"
+
+
+def _manifest_attempts(project_root: Path) -> List[int]:
+    runs_dir = project_root / ".devcouncil" / "runs"
+    if not runs_dir.exists():
+        return []
+    attempts: List[int] = []
+    for run_dir in runs_dir.iterdir():
+        path = run_dir / "correction-manifest.json"
+        if not path.exists():
+            continue
+        try:
+            data = read_json(path)
+            attempts.append(int(data.get("prior_failed_attempts", 0)) + 1)
+        except Exception:
+            continue
+    return attempts
+
+
+def build_rigor_report(project_root: Path) -> RigorAnalyticsReport:
+    """Aggregate rigor-related gaps and repair history. Never raises."""
+    report = RigorAnalyticsReport()
+    db = get_db(project_root)
+    if db is None:
+        report.notes.append("No DevCouncil state database — nothing to analyze.")
+        return report
+
+    with db.get_session() as session:
+        gaps = GapRepository(session).get_all()
+        tasks = {t.id: t for t in TaskRepository(session).get_all()}
+
+    report.total_gaps = len(gaps)
+    report.by_gap_type = dict(Counter(g.gap_type for g in gaps))
+
+    stub_counts: Counter[str] = Counter()
+    effort_counts: Counter[str] = Counter()
+    for gap in gaps:
+        if gap.gap_type == "stub_detected" and gap.task_id:
+            stub_counts[gap.task_id] += 1
+        elif gap.gap_type == "suspicious_effort" and gap.task_id:
+            effort_counts[gap.task_id] += 1
+        elif gap.gap_type == "stub_declared":
+            report.stub_declared_count += 1
+
+    report.stub_by_task = dict(stub_counts)
+    report.effort_by_task = dict(effort_counts)
+    report.recurring_stub_tasks = sorted(
+        tid for tid, n in stub_counts.items() if n >= 2
+    )
+
+    manifest_attempts = _manifest_attempts(project_root)
+    if manifest_attempts:
+        report.tasks_with_repair_attempts = len(manifest_attempts)
+        report.avg_repair_attempts = sum(manifest_attempts) / len(manifest_attempts)
+
+    effort_total = report.by_gap_type.get("suspicious_effort", 0)
+    verified_tasks = sum(1 for t in tasks.values() if t.status in ("verified", "done"))
+    if effort_total and verified_tasks:
+        # Rough advisory false-positive proxy: effort gaps on tasks that still verified.
+        verified_with_effort = sum(
+            1 for tid in effort_counts if tid in tasks and tasks[tid].status in ("verified", "done")
+        )
+        if verified_with_effort:
+            rate = verified_with_effort / max(1, len(effort_counts))
+            report.notes.append(
+                f"suspicious_effort advisory gaps on later-verified tasks: "
+                f"{verified_with_effort}/{len(effort_counts)} ({rate:.0%}) — "
+                "tune min_added_lines_per_planned_file if this is high."
+            )
+
+    if report.recurring_stub_tasks:
+        report.notes.append(
+            f"{len(report.recurring_stub_tasks)} task(s) hit stub_detected more than once — "
+            "review repair prompts or raise stub_detection to 'always' for those areas."
+        )
+
+    return report

package/src/devcouncil/verification/sandbox.py

@@ -35,6 +35,34 @@ class VerificationSandbox:
         raise NotImplementedError
 
 
+def _command_timeout(config: DevCouncilConfig) -> float:
+    """Per-command ceiling for sandboxed verification commands.
+
+    Reuses ``execution.command_timeout`` (same knob the task runner applies to
+    the commands it executes) so one config value bounds both surfaces."""
+    try:
+        return float(config.execution.command_timeout)
+    except Exception:
+        return 300.0
+
+
+def _run_sandboxed(argv: list[str], *, cwd: Path | None = None, timeout: float) -> subprocess.CompletedProcess:
+    """subprocess.run with capture + timeout; a timeout surfaces as returncode 124
+    (consistent with utils.proc.run_git) so callers' exit-code checks fail loudly
+    instead of the sandbox hanging verification forever."""
+    try:
+        return subprocess.run(
+            argv,
+            cwd=str(cwd) if cwd is not None else None,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        logger.warning("Sandbox command timed out after %.0fs: %s", timeout, " ".join(argv))
+        return subprocess.CompletedProcess(argv, returncode=124, stdout="", stderr=f"timed out after {timeout}s")
+
+
 def _save_run(
     project_root: Path,
     task: Task,
@@ -91,11 +119,11 @@ class DockerSandbox(VerificationSandbox):
         image = self.config.verification.sandbox.docker_image
         setup = self.config.verification.sandbox.docker_setup_commands
         results: list[dict] = []
+        timeout = _command_timeout(self.config)
         for setup_cmd in setup:
-            proc = subprocess.run(
+            proc = _run_sandboxed(
                 ["docker", "run", "--rm", "-v", f"{self.project_root}:/work", "-w", "/work", image, "sh", "-c", setup_cmd],
-                capture_output=True,
-                text=True,
+                timeout=timeout,
             )
             results.append({"command": setup_cmd, "exit_code": proc.returncode})
             if proc.returncode != 0:
@@ -103,10 +131,9 @@ class DockerSandbox(VerificationSandbox):
                 _save_run(self.project_root, task, "docker", result.environment, result.commands, result.status)
                 return result
         for cmd in commands:
-            proc = subprocess.run(
+            proc = _run_sandboxed(
                 ["docker", "run", "--rm", "-v", f"{self.project_root}:/work", "-w", "/work", image, "sh", "-c", cmd],
-                capture_output=True,
-                text=True,
+                timeout=timeout,
             )
             results.append({"command": cmd, "exit_code": proc.returncode})
             if proc.returncode != 0:
@@ -135,12 +162,12 @@ class NixSandbox(VerificationSandbox):
             return result
         attr = self.config.verification.sandbox.nix_flake_attr or "devShells.default"
         results: list[dict] = []
+        timeout = _command_timeout(self.config)
         for cmd in commands:
-            proc = subprocess.run(
+            proc = _run_sandboxed(
                 ["nix", "develop", f".#{attr}", "-c", "sh", "-c", cmd],
                 cwd=self.project_root,
-                capture_output=True,
-                text=True,
+                timeout=timeout,
             )
             results.append({"command": cmd, "exit_code": proc.returncode})
             if proc.returncode != 0:
@@ -162,9 +189,9 @@ def _environment_metadata(project_root: Path) -> dict[str, str]:
         "platform": platform.platform(),
     }
     try:
-        uv = subprocess.check_output(["uv", "--version"], text=True).strip()
+        uv = subprocess.check_output(["uv", "--version"], text=True, timeout=10).strip()
         env["uv"] = uv
-    except (FileNotFoundError, subprocess.CalledProcessError, OSError):
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError):
         pass
     lock = project_root / "uv.lock"
     if lock.exists():

package/src/devcouncil/verification/stub_detector.py

@@ -0,0 +1,369 @@
+"""Stub/TODO detection over the lines a task's diff *added*.
+
+Catches the classic lazy-agent moves before they reach "verified": placeholder
+bodies (``pass`` / ``...`` / ``raise NotImplementedError``), TODO/FIXME markers,
+neutered or skipped tests, assert-free test functions, and per-language "not
+implemented" idioms. Scanning is restricted to lines the diff added, so
+pre-existing debt in the repo never blocks a task that did not touch it.
+
+Escape hatch: a line containing ``devcouncil: allow-stub`` suppresses stub
+findings on that line **only when the task description mentions scaffolding**
+(see :func:`task_allows_scaffolding`). Every newly added allow-stub marker is
+still surfaced separately via :func:`detect_stub_declarations` so a human can
+audit intentional placeholders — agents cannot silently blanket-suppress stubs.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from devcouncil.domain.task import Task
+
+logger = logging.getLogger(__name__)
+
+ALLOW_MARKER = "devcouncil: allow-stub"
+
+# Documentation files: TODO lists in docs are normal writing, not lazy code.
+_DOC_SUFFIXES = {".md", ".rst", ".txt"}
+
+_SCAFFOLDING_RE = re.compile(r"\bscaffold(?:ing)?\b", re.IGNORECASE)
+
+# Shouty markers are matched case-sensitively so prose like "hack" in a comment
+# does not fire; ``stub`` and the explicit "not implemented"/"implement later"
+# phrases are matched case-insensitively.
+_SHOUTY_MARKER_RE = re.compile(r"\b(TODO|FIXME|XXX|HACK)\b")
+_STUB_MARKER_RE = re.compile(r"\bstub\b", re.IGNORECASE)
+_PHRASE_MARKER_RE = re.compile(r"\b(not implemented|implement (?:this|later|me))\b", re.IGNORECASE)
+
+# Comment delimiters used to isolate the COMMENT portion of a line. The bare
+# ``stub`` word is only a laziness signal when a human wrote it as an annotation
+# ("# stub implementation for now") — in CODE it is a legitimate identifier
+# (``class StubProvider``, ``def stub_response()``, test doubles) and flagging it
+# produced blocking false positives on hard tasks. Shouty TODO/FIXME markers and
+# the explicit "not implemented" phrases still match anywhere on the line.
+_COMMENT_DELIMS = ("#", "//", "/*", "--", ";;", "<!--")
+
+
+def _comment_segment(text: str) -> str:
+    """The portion of ``text`` from the first comment delimiter onward ('' if none)."""
+    first = -1
+    for delim in _COMMENT_DELIMS:
+        idx = text.find(delim)
+        if idx != -1 and (first == -1 or idx < first):
+            first = idx
+    return text[first:] if first != -1 else ""
+
+# Commented-out assert lines in test files — neutered verification.
+_COMMENTED_ASSERT_RE = re.compile(r"^\s*#+\s*assert\b", re.IGNORECASE)
+
+# Empty exported function bodies added in JS/TS/Go (added lines only).
+_EMPTY_EXPORTED_FN_RE = re.compile(
+    r"^\s*(?:export\s+)?(?:async\s+)?function\s+\w+\s*\([^)]*\)\s*\{\s*\}\s*;?\s*$"
+)
+
+_SKIPPED_TEST_RES: Tuple[Tuple[re.Pattern, str], ...] = (
+    (re.compile(r"@pytest\.mark\.skip\b"), "pytest test skipped"),
+    (re.compile(r"@pytest\.mark\.skipif\(\s*True"), "pytest test skipped unconditionally"),
+    (re.compile(r"@unittest\.skip\b"), "unittest test skipped"),
+    (re.compile(r"\b(?:it|test|describe)\.skip\s*\("), "JS test skipped"),
+    (re.compile(r"\bx(?:it|describe|test)\s*\("), "JS test disabled (xit/xdescribe)"),
+    (re.compile(r"assert\s+True\s*(#.*(placeholder|stub|todo).*)?$", re.IGNORECASE), "placeholder assertion (assert True)"),
+)
+
+_LANG_STUB_RES: Tuple[Tuple[re.Pattern, str], ...] = (
+    (re.compile(r"throw\s+new\s+Error\(\s*['\"](?:not implemented|todo|unimplemented)", re.IGNORECASE), "JS/TS not-implemented throw"),
+    (re.compile(r"\btodo!\s*\("), "Rust todo!()"),
+    (re.compile(r"\bunimplemented!\s*\("), "Rust unimplemented!()"),
+    (re.compile(r"panic\(\s*[\"'](?:TODO|not implemented|unimplemented)", re.IGNORECASE), "Go not-implemented panic"),
+    (re.compile(r"raise\s+NotImplementedError\b"), "NotImplementedError raised"),
+)
+
+# JS/TS assert-free test: test/it blocks with no expect/assert.
+_JS_ASSERT_FREE_RE = re.compile(
+    r"^\s*(?:it|test)\s*\([^)]*\)\s*(?:=>)?\s*\{[^}]*\}\s*;?\s*$"
+)
+
+_HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+
+@dataclass
+class StubFinding:
+    file: str
+    line: int
+    reason: str
+    snippet: str
+
+
+def task_allows_scaffolding(task: Task | None) -> bool:
+    """True when the task explicitly declares scaffolding work."""
+    if task is None:
+        return False
+    text = f"{task.title} {task.description}"
+    return bool(_SCAFFOLDING_RE.search(text))
+
+
+def added_lines_by_file(diff_content: str) -> Dict[str, List[Tuple[int, str]]]:
+    """Parse a unified diff into ``{new_path: [(new_lineno, added_text), ...]}``.
+
+    Only ``+`` lines are collected. Deleted files (``+++ /dev/null``) are skipped.
+    Tolerant of malformed hunks — it never raises.
+    """
+    out: Dict[str, List[Tuple[int, str]]] = {}
+    current: str | None = None
+    lineno = 0
+    in_hunk = False
+    for raw in diff_content.splitlines():
+        if raw.startswith("+++ "):
+            target = raw[4:].strip()
+            if target == "/dev/null":
+                current = None
+            else:
+                current = target[2:] if target.startswith(("a/", "b/")) else target
+            in_hunk = False
+            continue
+        if raw.startswith("@@"):
+            m = _HUNK_RE.match(raw)
+            if m and current is not None:
+                lineno = int(m.group(1))
+                in_hunk = True
+            else:
+                in_hunk = False
+            continue
+        if not in_hunk or current is None:
+            continue
+        if raw.startswith("+"):
+            out.setdefault(current, []).append((lineno, raw[1:]))
+            lineno += 1
+        elif raw.startswith("-"):
+            continue
+        elif raw.startswith("\\"):  # ""
+            continue
+        else:
+            lineno += 1
+    return out
+
+
+def detect_stub_declarations(diff_content: str) -> List[StubFinding]:
+    """Every newly added ``devcouncil: allow-stub`` marker (always advisory)."""
+    findings: List[StubFinding] = []
+    try:
+        by_file = added_lines_by_file(diff_content)
+    except Exception:  # pragma: no cover
+        return []
+    for path, added in by_file.items():
+        if Path(path).suffix.lower() in _DOC_SUFFIXES:
+            continue
+        for lineno, text in added:
+            if ALLOW_MARKER in text:
+                findings.append(StubFinding(
+                    path, lineno,
+                    "intentional stub declared (allow-stub)",
+                    text.strip()[:160],
+                ))
+    return findings
+
+
+def _scan_added_line(
+    path: str,
+    lineno: int,
+    text: str,
+    *,
+    honor_allow_stub: bool,
+) -> List[StubFinding]:
+    findings: List[StubFinding] = []
+    if honor_allow_stub and ALLOW_MARKER in text:
+        return findings
+    snippet = text.strip()[:160]
+    is_testish = "test" in Path(path).name.lower() or "/tests/" in f"/{path}"
+    # ``stub`` only counts as a marker inside a comment, and never in test files —
+    # test doubles ("stub provider") are standard practice, not laziness. TODO/FIXME
+    # and "not implemented" phrases keep matching anywhere.
+    stub_marker = not is_testish and _STUB_MARKER_RE.search(_comment_segment(text))
+    if _SHOUTY_MARKER_RE.search(text) or stub_marker or _PHRASE_MARKER_RE.search(text):
+        findings.append(StubFinding(path, lineno, "TODO/placeholder marker in added code", snippet))
+    for pattern, reason in _LANG_STUB_RES:
+        if pattern.search(text):
+            findings.append(StubFinding(path, lineno, reason, snippet))
+    if is_testish:
+        for pattern, reason in _SKIPPED_TEST_RES:
+            if pattern.search(text):
+                findings.append(StubFinding(path, lineno, reason, snippet))
+        if _COMMENTED_ASSERT_RE.search(text):
+            findings.append(StubFinding(path, lineno, "commented-out assert in test", snippet))
+        # Single-line JS test with empty body and no expect/assert.
+        if path.endswith((".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs")):
+            lowered = text.lower()
+            if ("test(" in lowered or "it(" in lowered) and "expect(" not in lowered and "assert" not in lowered:
+                if _JS_ASSERT_FREE_RE.search(text):
+                    findings.append(StubFinding(path, lineno, "test with no assertions", snippet))
+    if _EMPTY_EXPORTED_FN_RE.search(text):
+        findings.append(StubFinding(path, lineno, "empty exported function body", snippet))
+    return findings
+
+
+def _function_has_assertions(node: ast.AST) -> bool:
+    """Return True if the function body contains any verification statement."""
+    for child in ast.walk(node):
+        if isinstance(child, ast.Assert):
+            return True
+        if isinstance(child, ast.Call):
+            func = child.func
+            if isinstance(func, ast.Attribute):
+                name = func.attr
+                if name in {"assertEqual", "assertTrue", "assertFalse", "assertRaises", "assertIn", "assertNotIn"}:
+                    return True
+                if name == "raises" and isinstance(func.value, ast.Name) and func.value.id == "pytest":
+                    return True
+            if isinstance(func, ast.Name) and func.id == "raises":
+                return True
+    return False
+
+
+def _is_test_function(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    if node.name.startswith("test_"):
+        return True
+    for dec in node.decorator_list:
+        target = dec
+        if isinstance(dec, ast.Call):
+            target = dec.func
+        if isinstance(target, ast.Attribute) and target.attr in {"test", "parametrize"}:
+            return True
+        if isinstance(target, ast.Name) and target.id in {"pytest_mark", "unittest"}:
+            return True
+    return False
+
+
+def _python_assert_free_tests(
+    project_root: Path,
+    rel_path: str,
+    added: List[Tuple[int, str]],
+) -> List[StubFinding]:
+    """Flag added/changed test functions whose body contains no assertions."""
+    full = project_root / rel_path
+    try:
+        source = full.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except Exception:
+        return []
+    added_linenos = {ln for ln, _ in added}
+    source_lines = source.splitlines()
+    findings: List[StubFinding] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not _is_test_function(node):
+            continue
+        end = getattr(node, "end_lineno", node.lineno)
+        span = set(range(node.lineno, end + 1))
+        if not (span & added_linenos):
+            continue
+        if any(
+            0 <= ln - 1 < len(source_lines) and ALLOW_MARKER in source_lines[ln - 1]
+            for ln in span
+        ):
+            continue
+        if _function_has_assertions(node):
+            continue
+        # Docstring-only bodies with no asserts still count as assert-free.
+        findings.append(StubFinding(
+            rel_path, node.lineno,
+            f"test function '{node.name}' has no assertions",
+            f"def {node.name}(...)",
+        ))
+    return findings
+
+
+def _python_stub_bodies(
+    project_root: Path,
+    rel_path: str,
+    added: List[Tuple[int, str]],
+    *,
+    honor_allow_stub: bool,
+) -> List[StubFinding]:
+    """AST pass: flag functions whose (added) body is only pass/.../docstring."""
+    full = project_root / rel_path
+    try:
+        source = full.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except Exception:
+        return []
+    added_linenos = {ln for ln, _ in added}
+    source_lines = source.splitlines()
+    findings: List[StubFinding] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        body = node.body
+        stmts = list(body)
+        first = stmts[0] if stmts else None
+        if isinstance(first, ast.Expr):
+            val = first.value
+            if isinstance(val, ast.Constant) and isinstance(val.value, str):
+                stmts = stmts[1:]  # drop docstring
+        if not stmts:
+            trivial = True
+        else:
+            trivial = all(
+                isinstance(s, ast.Pass)
+                or (isinstance(s, ast.Expr) and isinstance(s.value, ast.Constant) and s.value.value is Ellipsis)
+                for s in stmts
+            )
+        if not trivial:
+            continue
+        end = getattr(node, "end_lineno", node.lineno)
+        span = set(range(node.lineno, end + 1))
+        if not (span & added_linenos):
+            continue
+        if honor_allow_stub and any(
+            0 <= ln - 1 < len(source_lines) and ALLOW_MARKER in source_lines[ln - 1]
+            for ln in span
+        ):
+            continue
+        findings.append(StubFinding(
+            rel_path, node.lineno,
+            f"function '{node.name}' has a placeholder body (pass/...)",
+            f"def {node.name}(...)",
+        ))
+    return findings
+
+
+def detect_stubs(
+    project_root: Path,
+    diff_content: str,
+    *,
+    honor_allow_stub: bool = False,
+) -> List[StubFinding]:
+    """All stub/TODO findings in the diff's added lines. Never raises."""
+    try:
+        by_file = added_lines_by_file(diff_content)
+    except Exception:  # pragma: no cover - defensive
+        logger.debug("stub detection: diff parse failed", exc_info=True)
+        return []
+    findings: List[StubFinding] = []
+    for path, added in by_file.items():
+        if Path(path).suffix.lower() in _DOC_SUFFIXES:
+            continue
+        for lineno, text in added:
+            findings.extend(_scan_added_line(path, lineno, text, honor_allow_stub=honor_allow_stub))
+        if path.endswith(".py"):
+            try:
+                findings.extend(_python_stub_bodies(
+                    project_root, path, added, honor_allow_stub=honor_allow_stub,
+                ))
+                findings.extend(_python_assert_free_tests(project_root, path, added))
+            except Exception:  # pragma: no cover - defensive
+                logger.debug("stub detection: AST pass failed for %s", path, exc_info=True)
+    seen = set()
+    unique: List[StubFinding] = []
+    for f in findings:
+        key = (f.file, f.line, f.reason)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(f)
+    return unique

package/src/devcouncil/verification/test_resolver.py

@@ -20,8 +20,30 @@ class EvidenceSuggestion(BaseModel):
 class TestResolver:
     __test__ = False
 
-    def __init__(self, project_root: Path):
+    def __init__(self, project_root: Path, repo_map: dict | None = None):
         self.project_root = project_root.resolve()
+        repo_map = repo_map or {}
+        # file -> the files that import it (reverse import edges from `dev map`).
+        # A test that imports the changed file is direct evidence it exercises
+        # that file — a far stronger signal than guessing a test from its name.
+        self._dependents: dict[str, list[str]] = repo_map.get("dependents", {}) or {}
+        self._known_files: set[str] = {
+            f["path"] for f in (repo_map.get("files") or []) if f.get("path")
+        }
+        # file -> subsystem area, and area -> its declared test files
+        # (role_files["tests"]), so a change with no direct test importer can fall
+        # back to its subsystem's tests instead of the whole-package default.
+        self._area_by_file: dict[str, str] = {
+            f["path"]: f["area"]
+            for f in (repo_map.get("files") or [])
+            if f.get("path") and f.get("area")
+        }
+        self._tests_by_area: dict[str, list[str]] = {}
+        for sub in repo_map.get("subsystems") or []:
+            area = sub.get("area")
+            tests = (sub.get("role_files") or {}).get("tests") or []
+            if area and tests:
+                self._tests_by_area[area] = list(tests)
 
     def suggest_for_task(
         self,
@@ -34,6 +56,21 @@ class TestResolver:
 
         for path in files:
             normalized = path.replace("\\", "/")
+            # Repo-map-derived tests first: a test that imports the changed file
+            # (or, failing that, its subsystem's declared tests) actually
+            # exercises it, so it outranks the name-based guesses below.
+            for command, confidence, reason in self._map_candidates(normalized):
+                if command in seen:
+                    continue
+                seen.add(command)
+                suggestions.append(
+                    EvidenceSuggestion(
+                        command=command,
+                        confidence=confidence,
+                        reason=reason,
+                        paths=[normalized],
+                    )
+                )
             for candidate in self._candidates_for_path(normalized):
                 if candidate in seen:
                     continue
@@ -49,6 +86,35 @@ class TestResolver:
                 )
         return suggestions
 
+    @staticmethod
+    def _looks_like_test(path: str) -> bool:
+        base = path.rsplit("/", 1)[-1]
+        return base.startswith("test_") or base.endswith("_test.py")
+
+    def _file_exists(self, rel: str) -> bool:
+        return rel in self._known_files or (self.project_root / rel).exists()
+
+    def _map_candidates(self, path: str) -> list[tuple[str, Literal["high", "medium", "low"], str]]:
+        """Test commands grounded in the repo map, strongest signal first."""
+        out: list[tuple[str, Literal["high", "medium", "low"], str]] = []
+        # 1. Tests that directly import the changed file (real coverage evidence).
+        for importer in self._dependents.get(path, []):
+            imp = importer.replace("\\", "/")
+            if self._looks_like_test(imp) and self._file_exists(imp):
+                out.append(
+                    (f"pytest {imp}", "high", "Test imports the changed file (repo map dependents)")
+                )
+        # 2. Fallback: the subsystem's declared tests for this file's area.
+        if not out:
+            area = self._area_by_file.get(path)
+            for test_file in self._tests_by_area.get(area or "", []):
+                tf = test_file.replace("\\", "/")
+                if self._file_exists(tf):
+                    out.append(
+                        (f"pytest {tf}", "medium", f"Subsystem '{area}' test file (repo map role_files)")
+                    )
+        return out
+
     def _candidates_for_path(self, path: str) -> list[str]:
         candidates: list[str] = []
         if path.startswith("src/") and path.endswith(".py"):