devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/verification/diff_coverage.py

@@ -270,6 +270,157 @@ def measurable_python_changes(changed: Dict[str, Dict[int, str]]) -> Dict[str, D
     }
 
 
+_JS_SUFFIXES = (".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs")
+_GO_SUFFIX = ".go"
+
+
+def measurable_js_changes(changed: Dict[str, Dict[int, str]]) -> Dict[str, Dict[int, str]]:
+    """Filter to JS/TS source files c8/nyc can instrument."""
+    return {
+        path: lines
+        for path, lines in changed.items()
+        if path.endswith(_JS_SUFFIXES) and not is_test_path(path)
+    }
+
+
+def measurable_go_changes(changed: Dict[str, Dict[int, str]]) -> Dict[str, Dict[int, str]]:
+    """Filter to Go source files ``go test -coverprofile`` can measure."""
+    return {
+        path: lines
+        for path, lines in changed.items()
+        if path.endswith(_GO_SUFFIX) and not is_test_path(path)
+    }
+
+
+def parse_istanbul_json(data: dict, root: Path) -> CoverageData:
+    """Parse c8/nyc ``coverage-final.json`` into :class:`CoverageData`."""
+    executed: Dict[str, Set[int]] = {}
+    executable: Dict[str, Set[int]] = {}
+    if not isinstance(data, dict):
+        return CoverageData()
+    for raw_path, payload in data.items():
+        if not isinstance(payload, dict):
+            continue
+        rel = _relativize(raw_path, root) or _relativize(payload.get("path", raw_path), root)
+        if rel is None:
+            continue
+        stmt_map = payload.get("statementMap") or {}
+        hits = payload.get("s") or {}
+        run: Set[int] = set()
+        all_lines: Set[int] = set()
+        for sid, meta in stmt_map.items():
+            if not isinstance(meta, dict):
+                continue
+            start = meta.get("start") or {}
+            line = int(start.get("line", 0) or 0)
+            if line <= 0:
+                continue
+            all_lines.add(line)
+            if int(hits.get(sid, 0) or 0) > 0:
+                run.add(line)
+        if all_lines:
+            executed[rel] = run
+            executable[rel] = all_lines
+    return CoverageData(executed=executed, executable=executable)
+
+
+def parse_go_coverprofile(text: str, root: Path) -> CoverageData:
+    """Parse ``go tool cover`` profile text into :class:`CoverageData`."""
+    executed: Dict[str, Set[int]] = {}
+    executable: Dict[str, Set[int]] = {}
+    for raw in text.splitlines():
+        if not raw or raw.startswith("mode:"):
+            continue
+        parts = raw.split()
+        if len(parts) < 3:
+            continue
+        loc, count_str = parts[0], parts[2]
+        try:
+            hit = int(count_str)
+        except ValueError:
+            continue
+        file_part = loc.split(":")[0]
+        rel = _relativize(file_part, root)
+        if rel is None:
+            # go profiles often use module paths; try basename match later via intersect.
+            rel = file_part.replace("\\", "/")
+        span = loc.split(":")[-1] if ":" in loc else ""
+        if "," not in span:
+            continue
+        start = span.split(",")[0]
+        try:
+            line = int(start.split(".")[0])
+        except ValueError:
+            continue
+        executable.setdefault(rel, set()).add(line)
+        if hit > 0:
+            executed.setdefault(rel, set()).add(line)
+    return CoverageData(executed=executed, executable=executable)
+
+
+def merge_diff_coverage_results(results: List[DiffCoverageResult]) -> DiffCoverageResult:
+    """Combine per-language measurements into one result."""
+    measured = [r for r in results if r.measured]
+    if not measured:
+        reason = results[0].reason if results else "no measurable source changes in diff"
+        return DiffCoverageResult(measured=False, reason=reason)
+    total_exec = sum(r.changed_executable_lines for r in measured)
+    total_cov = sum(r.covered_changed_lines for r in measured)
+    uncovered: Dict[str, List[int]] = {}
+    absent: List[str] = []
+    tools: List[str] = []
+    for r in measured:
+        if r.tool:
+            tools.append(r.tool)
+        for path, lines in r.uncovered_by_file.items():
+            uncovered.setdefault(path, []).extend(lines)
+        absent.extend(r.absent_files)
+    for path in uncovered:
+        uncovered[path] = sorted(set(uncovered[path]))
+    return DiffCoverageResult(
+        measured=True,
+        tool="+".join(dict.fromkeys(tools)) or "coverage",
+        changed_executable_lines=total_exec,
+        covered_changed_lines=total_cov,
+        uncovered_by_file=uncovered,
+        absent_files=sorted(set(absent)),
+    )
+
+
+def c8_run_argv(command_argv: List[str], *, reports_dir: str) -> Optional[List[str]]:
+    """Wrap a Node/npm test command with c8 instrumentation."""
+    if not command_argv:
+        return None
+    head = Path(command_argv[0]).name.lower()
+    if head.endswith(".exe"):
+        head = head[:-4]
+    # npx c8 ... OR node/node_modules/.bin/c8
+    if head in {"npx", "pnpm", "yarn"}:
+        return [command_argv[0], "c8", "--reporter=json", f"--reports-dir={reports_dir}", *command_argv[1:]]
+    if head in {"npm", "node"}:
+        return ["npx", "c8", "--reporter=json", f"--reports-dir={reports_dir}", *command_argv]
+    return ["npx", "c8", "--reporter=json", f"--reports-dir={reports_dir}", *command_argv]
+
+
+def go_cover_run_argv(command_argv: List[str], profile_path: str) -> Optional[List[str]]:
+    """Inject ``-coverprofile`` into a ``go test`` invocation."""
+    if not command_argv:
+        return None
+    head = Path(command_argv[0]).name.lower()
+    if head.endswith(".exe"):
+        head = head[:-4]
+    if head != "go":
+        return None
+    args = list(command_argv)
+    if "test" not in args:
+        return None
+    if "-coverprofile" in args:
+        return args
+    # Insert after ``go test``.
+    idx = args.index("test") + 1
+    return [*args[:idx], f"-coverprofile={profile_path}", *args[idx:]]
+
+
 def coverage_run_argv(
     command_argv: List[str],
     python: str,

package/src/devcouncil/verification/difficulty.py

@@ -0,0 +1,296 @@
+"""Deterministic task-difficulty estimation and the rigor policy derived from it.
+
+DevCouncil's anti-laziness gates (stub detection, effort heuristics, coverage
+enforcement) are *advisory everywhere, blocking on hard tasks* by default. This
+module supplies the two pieces that policy needs:
+
+- :func:`estimate_difficulty` — a cheap, deterministic (no LLM) classifier of a
+  task as ``easy`` / ``normal`` / ``hard`` from its declared scope. A manual
+  ``Task.difficulty`` value always wins, so planners and humans can override.
+- :func:`resolve_rigor_policy` — folds the difficulty together with
+  ``verification.rigor`` config into a :class:`RigorPolicy` the verifier, prompt
+  builder, and repair loop can branch on without re-deriving anything.
+
+Everything here must stay side-effect free and never raise: rigor is a layer on
+top of verification, and a bug in it must degrade to "no extra enforcement",
+never to a crashed verify run.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional, cast
+
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+
+logger = logging.getLogger(__name__)
+
+Difficulty = Literal["easy", "normal", "hard"]
+
+# Keywords whose presence in the task/requirement text signals intrinsically hard
+# work (cross-cutting, stateful, or correctness-critical). Word-ish boundaries so
+# "author" does not match "auth". The whole keyword bucket contributes at most
+# _KEYWORD_CAP points — a wordy description must not outweigh structural signals.
+_HARD_KEYWORD_RE = re.compile(
+    r"\b(refactor\w*|migrat\w*|concurren\w*|async\w*|race|deadlock|protocol|parser|"
+    r"cache|caching|transaction\w*|auth(?:n|z|entication|orization)?|crypto\w*|"
+    r"distributed|backward[- ]compat\w*|thread\w*|lock(?:ing|s)?|schema)\b",
+    re.IGNORECASE,
+)
+_KEYWORD_CAP = 1
+
+_HARD_THRESHOLD = 4
+_NORMAL_THRESHOLD = 2
+
+
+def _linked_requirements(task: Task, requirements: Optional[List[Requirement]]) -> List[Requirement]:
+    if not requirements:
+        return []
+    wanted = set(task.requirement_ids)
+    return [r for r in requirements if r.id in wanted]
+
+
+def difficulty_score(task: Task, requirements: Optional[List[Requirement]] = None) -> int:
+    """The raw additive score behind :func:`estimate_difficulty` (exposed for tests
+    and for surfacing "why was this hard" in logs)."""
+    score = 0
+    writable = [pf for pf in task.planned_files if pf.allowed_change != "read_only"]
+    if len(writable) >= 5:
+        score += 2
+    elif len(writable) >= 3:
+        score += 1
+
+    ac_count = len(task.acceptance_criterion_ids)
+    if ac_count >= 5:
+        score += 2
+    elif ac_count >= 3:
+        score += 1
+
+    changes = {pf.allowed_change for pf in writable}
+    if "create" in changes and "modify" in changes:
+        score += 1
+
+    if len(task.depends_on) >= 2:
+        score += 1
+
+    linked = _linked_requirements(task, requirements)
+    text = " ".join(
+        [task.title, task.description]
+        + [r.title for r in linked]
+        + [r.description for r in linked]
+    )
+    if _HARD_KEYWORD_RE.search(text):
+        score += _KEYWORD_CAP
+
+    if any(r.priority in ("high", "critical") for r in linked):
+        score += 1
+
+    return score
+
+
+def estimate_difficulty(task: Task, requirements: Optional[List[Requirement]] = None) -> Difficulty:
+    """Classify a task's difficulty deterministically.
+
+    A manual ``Task.difficulty`` (set by a planner or a human) always wins. The
+    estimator never raises; any unexpected error degrades to ``"normal"``.
+    """
+    manual = getattr(task, "difficulty", None)
+    if manual in ("easy", "normal", "hard"):
+        return cast(Literal["easy", "normal", "hard"], manual)
+    try:
+        score = difficulty_score(task, requirements)
+    except Exception:  # pragma: no cover - defensive
+        logger.debug("difficulty_score failed for %s; defaulting to normal", getattr(task, "id", "?"), exc_info=True)
+        return "normal"
+    if score >= _HARD_THRESHOLD:
+        return "hard"
+    if score >= _NORMAL_THRESHOLD:
+        return "normal"
+    return "easy"
+
+
+@dataclass
+class RigorPolicy:
+    """Resolved enforcement decisions for one task's verification run.
+
+    ``*_enabled`` says whether a gate runs at all; ``*_blocking`` says whether its
+    findings block. ``applied`` lists the escalations that actually took effect so
+    the verification outcome can record "passed under strict gates" vs "passed".
+    """
+
+    difficulty: Difficulty = "normal"
+    stub_enabled: bool = True
+    stub_blocking: bool = False
+    effort_enabled: bool = True
+    effort_blocking: bool = False
+    coarse_acceptance_enabled: bool = True
+    coarse_acceptance_blocking: bool = False
+    unwired_enabled: bool = True
+    unwired_blocking: bool = False
+    dead_symbol_enabled: bool = True
+    dead_symbol_blocking: bool = False
+    liveness_ratchet_enabled: bool = True
+    liveness_ratchet_blocking: bool = False
+    stale_map_enabled: bool = True
+    stale_map_blocking: bool = False
+    corpus_stale_enabled: bool = True
+    corpus_stale_blocking: bool = False
+    doc_code_ref_enabled: bool = True
+    doc_code_ref_blocking: bool = False
+    acceptance_corpus_enabled: bool = True
+    acceptance_corpus_blocking: bool = False
+    enforce_coverage: bool = False
+    reviewer_required: bool = False
+    extra_repair_attempts: int = 0
+    min_added_lines_per_planned_file: int = 5
+    min_acceptance_samples: int = 0
+    applied: List[str] = field(default_factory=list)
+
+
+def _mode_flags(mode: str, is_hard: bool) -> tuple[bool, bool]:
+    """Map a config mode (``never``/``hard``/``always``) to (enabled, blocking)."""
+    normalized = (mode or "hard").strip().lower()
+    if normalized == "never":
+        return False, False
+    if normalized == "always":
+        return True, True
+    # "hard" (and anything unrecognized, defensively) -> run always, block on hard.
+    return True, is_hard
+
+
+def _soft_mode_flags(mode: str, is_hard: bool) -> tuple[bool, bool]:
+    """Map ``never`` / ``soft`` / ``hard`` / ``always`` to (enabled, blocking)."""
+    normalized = (mode or "soft").strip().lower()
+    if normalized == "never":
+        return False, False
+    if normalized == "always":
+        return True, True
+    if normalized == "hard":
+        return True, is_hard
+    # soft: run on all difficulties, block only on hard tasks
+    return True, is_hard
+
+
+def resolve_rigor_policy(
+    task: Task,
+    requirements: Optional[List[Requirement]] = None,
+    config=None,
+) -> RigorPolicy:
+    """Fold difficulty + ``verification.rigor`` config into a :class:`RigorPolicy`.
+
+    ``config`` is a loaded ``DevCouncilConfig`` or None (defaults apply). Never
+    raises; on any error it returns a policy with no blocking escalations.
+    """
+    try:
+        rigor_cfg = config.verification.rigor if config is not None else None
+    except Exception:
+        rigor_cfg = None
+
+    difficulty = estimate_difficulty(task, requirements)
+    policy = RigorPolicy(difficulty=difficulty)
+
+    try:
+        enabled = True if rigor_cfg is None else bool(rigor_cfg.enabled)
+        if not enabled:
+            policy.stub_enabled = False
+            policy.effort_enabled = False
+            policy.unwired_enabled = False
+            policy.dead_symbol_enabled = False
+            policy.liveness_ratchet_enabled = False
+            policy.stale_map_enabled = False
+            policy.corpus_stale_enabled = False
+            policy.doc_code_ref_enabled = False
+            policy.acceptance_corpus_enabled = False
+            return policy
+
+        is_hard = difficulty == "hard"
+        stub_mode = "hard" if rigor_cfg is None else getattr(rigor_cfg, "stub_detection", "hard")
+        effort_mode = "hard" if rigor_cfg is None else getattr(rigor_cfg, "effort_heuristics", "hard")
+        policy.stub_enabled, policy.stub_blocking = _mode_flags(stub_mode, is_hard)
+        policy.effort_enabled, policy.effort_blocking = _mode_flags(effort_mode, is_hard)
+        coarse_mode = "hard" if rigor_cfg is None else getattr(
+            rigor_cfg, "coarse_acceptance_proof", "hard"
+        )
+        policy.coarse_acceptance_enabled, policy.coarse_acceptance_blocking = _mode_flags(
+            coarse_mode, is_hard
+        )
+        unwired_mode = "hard" if rigor_cfg is None else getattr(rigor_cfg, "unwired_files", "hard")
+        dead_mode = "hard" if rigor_cfg is None else getattr(rigor_cfg, "dead_symbols", "hard")
+        ratchet_mode = "hard" if rigor_cfg is None else getattr(
+            rigor_cfg, "liveness_ratchet", "hard"
+        )
+        stale_mode = "hard" if rigor_cfg is None else getattr(rigor_cfg, "stale_map", "hard")
+        policy.unwired_enabled, policy.unwired_blocking = _mode_flags(unwired_mode, is_hard)
+        policy.dead_symbol_enabled, policy.dead_symbol_blocking = _mode_flags(dead_mode, is_hard)
+        policy.liveness_ratchet_enabled, policy.liveness_ratchet_blocking = _mode_flags(
+            ratchet_mode, is_hard
+        )
+        policy.stale_map_enabled, policy.stale_map_blocking = _mode_flags(stale_mode, is_hard)
+        corpus_mode = "soft" if rigor_cfg is None else getattr(rigor_cfg, "corpus_stale", "soft")
+        doc_ref_mode = "soft" if rigor_cfg is None else getattr(rigor_cfg, "doc_code_ref", "soft")
+        policy.corpus_stale_enabled, policy.corpus_stale_blocking = _soft_mode_flags(
+            corpus_mode, is_hard
+        )
+        policy.doc_code_ref_enabled, policy.doc_code_ref_blocking = _soft_mode_flags(
+            doc_ref_mode, is_hard
+        )
+        ac_corpus_mode = "soft" if rigor_cfg is None else getattr(
+            rigor_cfg, "acceptance_corpus", "soft"
+        )
+        policy.acceptance_corpus_enabled, policy.acceptance_corpus_blocking = _soft_mode_flags(
+            ac_corpus_mode, is_hard
+        )
+
+        enforce_cov_on_hard = True if rigor_cfg is None else bool(
+            getattr(rigor_cfg, "enforce_coverage_on_hard", True)
+        )
+        policy.enforce_coverage = is_hard and enforce_cov_on_hard
+
+        reviewer_on_hard = False if rigor_cfg is None else bool(
+            getattr(rigor_cfg, "reviewer_required_on_hard", False)
+        )
+        policy.reviewer_required = is_hard and reviewer_on_hard
+
+        extra = 1 if rigor_cfg is None else max(
+            0, int(getattr(rigor_cfg, "extra_repair_attempts_on_hard", 1))
+        )
+        policy.extra_repair_attempts = extra if is_hard else 0
+
+        policy.min_added_lines_per_planned_file = max(
+            1, int(getattr(rigor_cfg, "min_added_lines_per_planned_file", 5))
+        )
+
+        samples_on_hard = 2 if rigor_cfg is None else max(
+            1, int(getattr(rigor_cfg, "acceptance_samples_on_hard", 2))
+        )
+        policy.min_acceptance_samples = samples_on_hard if is_hard else 0
+
+        if policy.stub_blocking:
+            policy.applied.append("stub_detection_blocking")
+        if policy.effort_blocking:
+            policy.applied.append("effort_heuristics_blocking")
+        if policy.coarse_acceptance_blocking:
+            policy.applied.append("coarse_acceptance_proof_blocking")
+        if policy.unwired_blocking:
+            policy.applied.append("unwired_files_blocking")
+        if policy.dead_symbol_blocking:
+            policy.applied.append("dead_symbols_blocking")
+        if policy.liveness_ratchet_blocking:
+            policy.applied.append("liveness_ratchet_blocking")
+        if policy.stale_map_blocking:
+            policy.applied.append("stale_map_blocking")
+        if policy.enforce_coverage:
+            policy.applied.append("coverage_enforced")
+        if policy.reviewer_required:
+            policy.applied.append("reviewer_required")
+        if policy.extra_repair_attempts:
+            policy.applied.append(f"extra_repair_attempts:{policy.extra_repair_attempts}")
+        if policy.min_acceptance_samples > 1:
+            policy.applied.append(f"acceptance_samples:{policy.min_acceptance_samples}")
+    except Exception:  # pragma: no cover - defensive
+        logger.debug("resolve_rigor_policy failed; degrading to advisory-only", exc_info=True)
+        return RigorPolicy(difficulty=difficulty)
+    return policy

package/src/devcouncil/verification/effort_heuristics.py

@@ -0,0 +1,178 @@
+"""Effort/diff plausibility heuristics — is the diff big enough to be the work?
+
+Three deliberately conservative checks, each aimed at a known lazy-agent pattern:
+
+- **undersized diff**: the task plans substantial work (several writable files, or
+  file creation) but the diff adds only a handful of code lines.
+- **comment-only diff**: files changed, but no added line is actual code, while
+  the task has automatable acceptance criteria to prove.
+- **test deletion**: more test lines removed than added — the "make the suite
+  pass by deleting the test" move. Always high severity.
+
+These are heuristics, so outside hard tasks they surface as advisory
+``suspicious_effort`` gaps; the caller decides blocking via the rigor policy.
+Never raises.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.verification.stub_detector import added_lines_by_file
+
+logger = logging.getLogger(__name__)
+
+_AUTOMATABLE_METHODS = {"unit_test", "integration_test", "static_check"}
+
+_COMMENT_PREFIXES = ("#", "//", "/*", "*", "--", ";", "<!--")
+
+
+@dataclass
+class EffortFinding:
+    reason: str
+    detail: str
+    severity: str = "medium"
+    file: Optional[str] = None
+
+
+def _is_code_line(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return False
+    return not stripped.startswith(_COMMENT_PREFIXES)
+
+
+def _is_test_path(path: str) -> bool:
+    lowered = path.lower()
+    name = lowered.rsplit("/", 1)[-1]
+    return (
+        "/tests/" in f"/{lowered}"
+        or lowered.startswith("tests/")
+        or name.startswith("test_")
+        or re.search(r"(_test|\.test|\.spec)\.[a-z]+$", name) is not None
+    )
+
+
+def _removed_lines_by_file(diff_content: str) -> dict:
+    """``{old_path: removed_line_count}`` from a unified diff. Tolerant, never raises."""
+    out: dict = {}
+    current: Optional[str] = None
+    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
+            continue
+        if current is None:
+            continue
+        if raw.startswith("-") and not raw.startswith("---"):
+            out[current] = out.get(current, 0) + 1
+    return out
+
+
+def _automatable_criteria_present(task: Task, requirements: Optional[List[Requirement]]) -> bool:
+    if not task.acceptance_criterion_ids:
+        return False
+    if not requirements:
+        return True  # criteria exist; assume provable absent contrary evidence
+    wanted = set(task.acceptance_criterion_ids)
+    for req in requirements:
+        for ac in req.acceptance_criteria:
+            if ac.id in wanted and ac.verification_method in _AUTOMATABLE_METHODS:
+                return True
+    return False
+
+
+def detect_effort_anomalies(
+    task: Task,
+    diff_content: str,
+    requirements: Optional[List[Requirement]] = None,
+    *,
+    min_added_lines_per_planned_file: int = 5,
+) -> List[EffortFinding]:
+    """Run all effort heuristics over the task's diff. Never raises."""
+    try:
+        added = added_lines_by_file(diff_content)
+    except Exception:  # pragma: no cover - defensive
+        logger.debug("effort heuristics: diff parse failed", exc_info=True)
+        return []
+    if not added:
+        return []  # empty diff is the verifier's task_not_implemented gate, not ours
+
+    findings: List[EffortFinding] = []
+    writable = [pf for pf in task.planned_files if pf.allowed_change != "read_only"]
+    added_code_lines = sum(
+        1 for lines in added.values() for _, text in lines if _is_code_line(text)
+    )
+    # Declared-stub lines (devcouncil: allow-stub) do not count toward the
+    # undersized-diff threshold — scaffolding must not absorb the whole diff.
+    declared_stub_lines = sum(
+        1 for lines in added.values() for _, text in lines if "devcouncil: allow-stub" in text
+    )
+    effective_code_lines = max(0, added_code_lines - declared_stub_lines)
+
+    # 1. Undersized diff vs declared scope.
+    substantial_scope = len(writable) >= 3 or any(pf.allowed_change == "create" for pf in writable)
+    if substantial_scope and writable:
+        threshold = min_added_lines_per_planned_file * len(writable)
+        if effective_code_lines < threshold:
+            findings.append(EffortFinding(
+                reason="undersized_diff",
+                detail=(
+                    f"Task plans {len(writable)} writable file(s) but the diff adds only "
+                    f"{effective_code_lines} substantive code line(s) (< {threshold} expected; "
+                    f"{declared_stub_lines} declared-stub line(s) excluded). The "
+                    "implementation may be superficial or incomplete."
+                ),
+            ))
+
+    # 2. Comment/whitespace-only diff while automatable criteria exist.
+    if added_code_lines == 0 and _automatable_criteria_present(task, requirements):
+        findings.append(EffortFinding(
+            reason="comment_only_diff",
+            detail=(
+                "The diff adds no executable code (comments/blank lines only), but the "
+                "task has acceptance criteria that require behavioral changes."
+            ),
+        ))
+
+    # 3. Test deletion: more test lines removed than added in files referenced by
+    # expected_tests — the classic "make the suite pass by deleting the test".
+    removed = _removed_lines_by_file(diff_content)
+    expected = " ".join(task.expected_tests or [])
+    referenced_test_paths = {
+        path for path in removed if _is_test_path(path) and path in expected
+    }
+    if not referenced_test_paths and expected:
+        # Fall back: basename match when commands use paths like tests/test_a.py.
+        for path in removed:
+            if _is_test_path(path) and Path(path).name in expected:
+                referenced_test_paths.add(path)
+    test_removed = sum(removed[p] for p in referenced_test_paths)
+    test_added = sum(
+        len(lines) for path, lines in added.items()
+        if _is_test_path(path) and path in referenced_test_paths
+    )
+    if test_removed > 0 and test_removed > test_added:
+        worst = max(referenced_test_paths, key=lambda p: removed[p])
+        findings.append(EffortFinding(
+            reason="test_deletion",
+            detail=(
+                f"The diff removes {test_removed} line(s) from test file(s) referenced by "
+                f"expected_tests but adds only {test_added}. Weakening or deleting tests to "
+                "make verification pass is never acceptable; restore the tests or justify "
+                "the removal explicitly."
+            ),
+            severity="high",
+            file=worst,
+        ))
+
+    return findings

package/src/devcouncil/verification/gap_ids.py

@@ -0,0 +1,63 @@
+"""Deterministic gap IDs and stable ordering for verification runs."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Iterable, List
+
+from devcouncil.domain.gap import Gap
+
+_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+
+def stable_gap_id(task_id: str, kind: str, identity: str = "") -> str:
+    """Return a gap id that is stable across verify runs for the same finding."""
+    key = f"{task_id}|{kind}|{identity or kind}"
+    digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:10]
+    safe_kind = re.sub(r"[^A-Za-z0-9]", "", kind)[:16] or "GAP"
+    return f"GAP-{task_id}-{safe_kind}-{digest}"
+
+
+def gap_identity(gap: Gap) -> str:
+    """Stable dedup key for a gap (type + location + criterion + description)."""
+    return "|".join(
+        (
+            gap.gap_type,
+            gap.file or "",
+            str(gap.line or ""),
+            gap.acceptance_criterion_id or "",
+            gap.description.strip(),
+        )
+    )
+
+
+def normalize_verify_gaps(gaps: Iterable[Gap]) -> List[Gap]:
+    """Dedupe and sort gaps so persistence and reconnecting agents stay stable."""
+    seen: dict[str, Gap] = {}
+    for gap in gaps:
+        key = gap_identity(gap)
+        existing = seen.get(key)
+        if existing is None:
+            seen[key] = gap
+            continue
+        # Prefer blocking / higher severity when duplicates collide on identity.
+        if gap.blocking and not existing.blocking:
+            seen[key] = gap
+        elif gap.blocking == existing.blocking:
+            sev_new = _SEVERITY_ORDER.get(gap.severity, 9)
+            sev_old = _SEVERITY_ORDER.get(existing.severity, 9)
+            if sev_new < sev_old:
+                seen[key] = gap
+    return sorted(
+        seen.values(),
+        key=lambda g: (
+            not g.blocking,
+            _SEVERITY_ORDER.get(g.severity, 9),
+            g.gap_type,
+            g.file or "",
+            g.line or 0,
+            g.acceptance_criterion_id or "",
+            g.id,
+        ),
+    )