devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/verification/verify_orchestration.py

@@ -0,0 +1,610 @@
+"""Core verify_task gate orchestration extracted from Verifier."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Literal, TYPE_CHECKING, cast
+
+from devcouncil.domain.evidence import CommandResult, DiffEvidence
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.live.cards import unresolved_blocking_cards
+from devcouncil.telemetry.stages import log_step
+from devcouncil.verification.checks.acceptance_evidence import map_acceptance_criteria_evidence
+from devcouncil.verification.checks.compiled_acceptance import (
+    promote_demoted_failures_when_compiler_incomplete,
+    run_compiled_acceptance_checks,
+)
+from devcouncil.verification.checks.command_evidence import run_verification_commands
+from devcouncil.verification.checks.diff_coverage_gate import run_diff_coverage_gate
+from devcouncil.verification.checks.planned_files import (
+    detect_dependency_risk_gaps,
+    detect_no_work_gap,
+    detect_planned_file_gaps,
+)
+from devcouncil.verification.checks.orphan_diff import detect_orphan_diff_gaps
+from devcouncil.verification.checks.stub_scan import detect_stub_gaps
+from devcouncil.verification.effort_heuristics import detect_effort_anomalies
+from devcouncil.verification.verify_setup import VerifyRunContext
+
+if TYPE_CHECKING:
+    from devcouncil.verification.verifier import Verifier
+
+logger = logging.getLogger(__name__)
+
+
+def _verification_mode_label(evidence_to_save: list[Any], *, compiler_active: bool) -> str:
+    """Derive reported verification mode from TestEvidence proof modes, not compiler presence."""
+    from devcouncil.domain.evidence import TestEvidence
+
+    test_evidence = [item for item in evidence_to_save if isinstance(item, TestEvidence)]
+    if not test_evidence:
+        return "compiled" if compiler_active else "coarse"
+    modes = {item.mode for item in test_evidence if item.mode}
+    if modes & {"compiled", "vote"}:
+        return "compiled"
+    if "coarse" in modes:
+        return "compiled" if compiler_active else "coarse"
+    return "compiled" if compiler_active else "coarse"
+
+
+async def run_verify_orchestration(
+    verifier: "Verifier",
+    task: Task,
+    requirements: List[Requirement],
+    ctx: VerifyRunContext,
+    compile_future: Any,
+    review_future: Any,
+) -> tuple[list[Gap], list[Any]]:
+    """Run all verification gates and return gaps plus evidence to persist."""
+    gaps: list[Gap] = []
+    evidence_to_save: list[Any] = []
+    _cfg = ctx.config
+    rigor = ctx.rigor
+    ac_repair_attempts = ctx.ac_repair_attempts
+    changed_files = ctx.changed_files
+    diff_content = ctx.diff_content
+    diff_empty = ctx.diff_empty
+    coverage_measured = False
+    coverage_skipped_reason: str | None = None
+
+    work_present = (not diff_empty) or verifier._task_produced_changes(task.id)
+
+    no_work_gap = detect_no_work_gap(
+        task=task,
+        work_present=work_present,
+        next_gap_id=verifier._next_gap_id,
+    )
+    if no_work_gap is not None:
+        gaps.append(no_work_gap)
+
+    if diff_content:
+        added_files, deleted_files = verifier._classify_change_paths(changed_files)
+        diff_ev = DiffEvidence(
+            task_id=task.id,
+            changed_files=changed_files,
+            added_files=added_files,
+            deleted_files=deleted_files,
+            diff_summary=f"Diff captured for {len(changed_files)} files.",
+        )
+        evidence_to_save.append(diff_ev)
+
+    planned_paths = {pf.path for pf in task.planned_files}
+    gaps.extend(detect_planned_file_gaps(
+        task=task,
+        changed_files=changed_files,
+        next_gap_id=verifier._next_gap_id,
+    ))
+
+    gaps.extend(detect_orphan_diff_gaps(
+        task=task,
+        changed_files=changed_files,
+        planned_paths=planned_paths,
+        diff_content=diff_content,
+        project_root=verifier.project_root,
+        get_untracked_files=verifier._get_untracked_files,
+        next_gap_id=verifier._next_gap_id,
+        classify_fn=verifier._classify_change_paths,
+    ))
+
+    log_step(
+        "verify/3: planned-file and orphan-diff checks",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        gaps_so_far=len(gaps),
+    )
+    gaps.extend(verifier._check_semantic_diff(task, requirements))
+
+    gaps.extend(detect_dependency_risk_gaps(
+        task=task,
+        changed_files=changed_files,
+        planned_paths=planned_paths,
+        next_gap_id=verifier._next_gap_id,
+    ))
+
+    # Advisory architecture-drift gate: flag edits that cross non-neighbor subsystem
+    # boundaries the plan never declared. Non-blocking by default, reads only the repo
+    # map, and degrades to a no-op when the map is absent/stale.
+    boundary_cfg = getattr(getattr(_cfg, "verification", None), "subsystem_boundary", None)
+    if changed_files and (boundary_cfg is None or boundary_cfg.enabled):
+        from devcouncil.verification.checks.subsystem_boundary import (
+            detect_subsystem_boundary_gaps,
+        )
+
+        gaps.extend(detect_subsystem_boundary_gaps(
+            task=task,
+            changed_files=changed_files,
+            repo_map=verifier._load_repo_map(),
+            next_gap_id=verifier._next_gap_id,
+            blocking=bool(getattr(boundary_cfg, "blocking", False)),
+        ))
+
+    # Stale-map gate: advisory on easy/normal, blocking on hard. Runs before
+    # map-consuming gates so agents refresh before trusting neighbors/dependents.
+    if rigor.stale_map_enabled:
+        try:
+            from devcouncil.verification.checks.stale_map import detect_stale_map_gaps
+
+            gaps.extend(detect_stale_map_gaps(
+                task=task,
+                project_root=verifier.project_root,
+                next_gap_id=verifier._next_gap_id,
+                stale_map_enabled=rigor.stale_map_enabled,
+                stale_map_blocking=rigor.stale_map_blocking,
+                repo_map=verifier._load_repo_map(),
+            ))
+        except Exception:
+            logger.warning("stale-map gate failed; skipping", exc_info=True)
+            if rigor.stale_map_blocking:
+                gaps.append(Gap(
+                    id=verifier._next_gap_id(task.id, "QGFAIL-stale_map"),
+                    severity="medium",
+                    gap_type="quality_gate_failed",
+                    task_id=task.id,
+                    description="Stale-map verification gate crashed; results are incomplete.",
+                    evidence=["gate:stale_map"],
+                    recommended_fix="Re-run verify after fixing the gate error; do not treat this pass as proven.",
+                    blocking=False,
+                ))
+
+    if rigor.corpus_stale_enabled or rigor.doc_code_ref_enabled:
+        try:
+            from devcouncil.verification.checks.corpus_stale import (
+                detect_corpus_stale_gaps,
+                refresh_corpus_on_verify_if_needed,
+            )
+
+            refresh_corpus_on_verify_if_needed(verifier.project_root)
+            gaps.extend(detect_corpus_stale_gaps(
+                task=task,
+                project_root=verifier.project_root,
+                changed_files=changed_files,
+                next_gap_id=verifier._next_gap_id,
+                corpus_stale_enabled=rigor.corpus_stale_enabled,
+                corpus_stale_blocking=rigor.corpus_stale_blocking,
+            ))
+        except Exception:
+            logger.warning("corpus-stale gate failed; skipping", exc_info=True)
+        try:
+            from devcouncil.verification.checks.doc_code_ref import detect_doc_code_ref_gaps
+
+            gaps.extend(detect_doc_code_ref_gaps(
+                task=task,
+                project_root=verifier.project_root,
+                changed_files=changed_files,
+                diff_content=diff_content,
+                next_gap_id=verifier._next_gap_id,
+                doc_code_ref_enabled=rigor.doc_code_ref_enabled,
+                doc_code_ref_blocking=rigor.doc_code_ref_blocking,
+            ))
+        except Exception:
+            logger.warning("doc-code-ref gate failed; skipping", exc_info=True)
+    if rigor.acceptance_corpus_enabled:
+        try:
+            from devcouncil.verification.checks.acceptance_corpus import (
+                detect_acceptance_corpus_gaps,
+            )
+
+            gaps.extend(detect_acceptance_corpus_gaps(
+                task=task,
+                requirements=requirements,
+                project_root=verifier.project_root,
+                changed_files=changed_files,
+                diff_content=diff_content,
+                next_gap_id=verifier._next_gap_id,
+                acceptance_corpus_enabled=rigor.acceptance_corpus_enabled,
+                acceptance_corpus_blocking=rigor.acceptance_corpus_blocking,
+            ))
+        except Exception:
+            logger.warning("acceptance-corpus gate failed; skipping", exc_info=True)
+
+    log_step(
+        "verify/4: semantic diff and dependency checks",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        gaps_so_far=len(gaps),
+    )
+    gaps.extend(detect_stub_gaps(
+        task=task,
+        diff_content=diff_content,
+        project_root=verifier.project_root,
+        stub_enabled=rigor.stub_enabled,
+        stub_blocking=rigor.stub_blocking,
+        next_gap_id=verifier._next_gap_id,
+    ))
+
+    # Unwired-file + dead-symbol gates (liveness): run right after placeholder scan so
+    # reachability findings sit next to incomplete-code findings in the repair loop.
+    # Failures on hard rigor emit an advisory quality_gate_failed so agents see
+    # the swallow instead of a silent pass.
+    unwired_files_flagged: set[str] = set()
+    liveness_baseline_status: str | None = None
+    try:
+        from devcouncil.verification.checks.wiring import detect_unwired_file_gaps
+
+        unwired_gaps = detect_unwired_file_gaps(
+            task=task,
+            project_root=verifier.project_root,
+            changed_files=changed_files,
+            diff_content=diff_content,
+            get_untracked_files=verifier._get_untracked_files,
+            next_gap_id=verifier._next_gap_id,
+            unwired_enabled=rigor.unwired_enabled,
+            unwired_blocking=rigor.unwired_blocking,
+            classify_fn=verifier._classify_change_paths,
+        )
+        for g in unwired_gaps:
+            if g.file and g.gap_type == "unwired_file":
+                unwired_files_flagged.add(g.file)
+        gaps.extend(unwired_gaps)
+    except Exception:
+        logger.warning("unwired-file gate failed; skipping", exc_info=True)
+        if rigor.unwired_blocking:
+            gaps.append(Gap(
+                id=verifier._next_gap_id(task.id, "QGFAIL-unwired_file"),
+                severity="medium",
+                gap_type="quality_gate_failed",
+                task_id=task.id,
+                description="Unwired-file verification gate crashed; results are incomplete.",
+                evidence=["gate:unwired_file"],
+                recommended_fix="Re-run verify after fixing the gate error; do not treat this pass as proven.",
+                blocking=False,
+            ))
+
+    try:
+        from devcouncil.verification.checks.dead_symbols import detect_dead_symbol_gaps
+
+        gaps.extend(detect_dead_symbol_gaps(
+            task=task,
+            project_root=verifier.project_root,
+            diff_content=diff_content,
+            next_gap_id=verifier._next_gap_id,
+            dead_symbol_enabled=rigor.dead_symbol_enabled,
+            dead_symbol_blocking=rigor.dead_symbol_blocking,
+            requirements=requirements,
+            unwired_files=unwired_files_flagged,
+        ))
+    except Exception:
+        logger.warning("dead-symbol gate failed; skipping", exc_info=True)
+        if rigor.dead_symbol_blocking:
+            gaps.append(Gap(
+                id=verifier._next_gap_id(task.id, "QGFAIL-dead_symbol"),
+                severity="medium",
+                gap_type="quality_gate_failed",
+                task_id=task.id,
+                description="Dead-symbol verification gate crashed; results are incomplete.",
+                evidence=["gate:dead_symbol"],
+                recommended_fix="Re-run verify after fixing the gate error; do not treat this pass as proven.",
+                blocking=False,
+            ))
+
+    # Liveness ratchet: existing code newly stranded vs checkout baseline.
+    if rigor.liveness_ratchet_enabled:
+        try:
+            from devcouncil.indexing.repo_mapper import RepoMapper
+            from devcouncil.verification.checks.liveness_ratchet import (
+                detect_liveness_regressions,
+                load_liveness_baseline,
+            )
+            from devcouncil.verification.checks.wiring import collect_added_files
+            from devcouncil.verification.stub_detector import added_lines_by_file
+
+            baseline = load_liveness_baseline(verifier.project_root, task.id)
+            if baseline is None:
+                liveness_baseline_status = "missing"
+            else:
+                liveness_baseline_status = "ok"
+                mapper = RepoMapper(verifier.project_root)
+                current = mapper.liveness_snapshot()
+                added = collect_added_files(
+                    project_root=verifier.project_root,
+                    changed_files=changed_files,
+                    diff_content=diff_content,
+                    get_untracked_files=verifier._get_untracked_files,
+                    classify_fn=verifier._classify_change_paths,
+                )
+                by_file = added_lines_by_file(diff_content or "")
+                diff_lines = {
+                    path: {ln for ln, _ in lines}
+                    for path, lines in by_file.items()
+                }
+                gaps.extend(detect_liveness_regressions(
+                    baseline,
+                    current,
+                    added,
+                    task=task,
+                    next_gap_id=verifier._next_gap_id,
+                    blocking=rigor.liveness_ratchet_blocking,
+                    diff_added_lines=diff_lines,
+                ))
+        except Exception:
+            logger.warning("liveness-ratchet gate failed; skipping", exc_info=True)
+            if rigor.liveness_ratchet_blocking:
+                gaps.append(Gap(
+                    id=verifier._next_gap_id(task.id, "QGFAIL-liveness_ratchet"),
+                    severity="medium",
+                    gap_type="quality_gate_failed",
+                    task_id=task.id,
+                    description="Liveness-ratchet verification gate crashed; results are incomplete.",
+                    evidence=["gate:liveness_ratchet"],
+                    recommended_fix="Re-run verify after fixing the gate error; do not treat this pass as proven.",
+                    blocking=False,
+                ))
+
+    if rigor.effort_enabled and diff_content:
+        for eff in detect_effort_anomalies(
+            task, diff_content, requirements,
+            min_added_lines_per_planned_file=rigor.min_added_lines_per_planned_file,
+        ):
+            gaps.append(Gap(
+                id=verifier._next_gap_id(task.id, f"EFFORT-{eff.file or eff.reason[:40]}"),
+                severity=cast(Literal["low", "medium", "high", "critical"], eff.severity),
+                gap_type="suspicious_effort",
+                task_id=task.id,
+                description=eff.detail,
+                evidence=[eff.reason],
+                recommended_fix=(
+                    "Review whether the implementation actually fulfills the task scope; "
+                    "complete the planned work (or restore removed tests), then re-verify."
+                ),
+                blocking=rigor.effort_blocking,
+                file=eff.file,
+            ))
+
+    compiler_active = bool(verifier.acceptance_compiler and diff_content and task.acceptance_criterion_ids)
+    log_step(
+        "verify/5: stub and effort heuristics",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        compiler_active=compiler_active,
+        gaps_so_far=len(gaps),
+    )
+
+    cmd_run = run_verification_commands(
+        task=task,
+        commands_for_task=verifier._commands_for_task(task),
+        compiler_active=compiler_active,
+        command_applicable=verifier._command_applicable,
+        run_command=lambda cmd: verifier._run_command(cmd, task_id=task.id),
+        command_can_prove_acceptance=verifier._command_can_prove_acceptance,
+        command_is_malformed=verifier._command_is_malformed,
+        failure_location=verifier._failure_location,
+        is_quality_only_command=verifier._is_quality_only_command,
+        next_gap_id=verifier._next_gap_id,
+        retry_flaky=bool(_cfg.verification.retry_flaky) if _cfg is not None else True,
+    )
+    gaps.extend(cmd_run.gaps)
+    command_results: list[CommandResult] = list(cmd_run.command_results)
+    evidence_results: list[CommandResult] = list(cmd_run.evidence_results)
+    genuine_failure = cmd_run.genuine_failure
+    had_unrunnable = cmd_run.had_unrunnable
+    demoted_failures: list[Gap] = list(cmd_run.demoted_failures)
+    evidence_to_save.extend(command_results)
+
+    log_step(
+        "verify/6: verification commands",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        commands_run=len(command_results),
+        gaps_so_far=len(gaps),
+    )
+    _repair_fn = getattr(verifier.acceptance_compiler, "repair", None)
+    compiled_run = await run_compiled_acceptance_checks(
+        task=task,
+        requirements=requirements,
+        compile_future=compile_future,
+        diff_content=diff_content,
+        ac_repair_attempts=ac_repair_attempts,
+        acceptance_compiler=verifier.acceptance_compiler,
+        command_applicable=verifier._command_applicable,
+        run_command=lambda cmd: verifier._run_command(cmd, task_id=task.id),
+        command_is_malformed=verifier._command_is_malformed,
+        failure_location=verifier._failure_location,
+        next_gap_id=verifier._next_gap_id,
+        repair_command=_repair_fn,
+        had_unrunnable=had_unrunnable,
+        genuine_failure=genuine_failure,
+    )
+    gaps.extend(compiled_run.gaps)
+    command_results.extend(compiled_run.command_results)
+    evidence_to_save.extend(compiled_run.evidence)
+    had_unrunnable = compiled_run.had_unrunnable
+    genuine_failure = compiled_run.genuine_failure
+    compiled_pass = compiled_run.compiled_pass
+    compiled_cmds_by_ac = compiled_run.compiled_cmds_by_ac
+    failing_results_by_ac = compiled_run.failing_results_by_ac
+    compiled_vote = compiled_run.compiled_vote
+    inconclusive_acs = compiled_run.inconclusive_acs
+    genuine_failure = promote_demoted_failures_when_compiler_incomplete(
+        task=task,
+        compiler_active=compiler_active,
+        compiled_cmds_by_ac=compiled_cmds_by_ac,
+        demoted_failures=demoted_failures,
+        genuine_failure=genuine_failure,
+    )
+
+    log_step(
+        "verify/7: compiled acceptance checks",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        compiled_criteria=len(compiled_pass),
+        gaps_so_far=len(gaps),
+    )
+    ac_evidence = map_acceptance_criteria_evidence(
+        task=task,
+        requirements=requirements,
+        evidence_results=evidence_results,
+        compiled_pass=compiled_pass,
+        compiled_cmds_by_ac=compiled_cmds_by_ac,
+        failing_results_by_ac=failing_results_by_ac,
+        compiled_vote=compiled_vote,
+        inconclusive_acs=inconclusive_acs,
+        work_present=work_present,
+        genuine_failure=genuine_failure,
+        had_unrunnable=had_unrunnable,
+        rigor=rigor,
+        is_quality_only_command=verifier._is_quality_only_command,
+        next_gap_id=verifier._next_gap_id,
+    )
+    gaps.extend(ac_evidence.gaps)
+    evidence_to_save.extend(ac_evidence.evidence)
+
+    log_step(
+        "verify/8: acceptance-criteria evidence mapping",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        gaps_so_far=len(gaps),
+    )
+    measure_cov, enforce_cov, min_ratio = verifier._diff_coverage_settings()
+    if rigor.enforce_coverage:
+        enforce_cov = True
+    any_passing = any(
+        result.exit_code == 0 and not verifier._is_quality_only_command(result.command)
+        for result in evidence_results
+    ) or any(compiled_pass.values())
+    dc_result = run_diff_coverage_gate(
+        task=task,
+        diff_content=diff_content,
+        any_passing=any_passing,
+        enforce_cov=enforce_cov,
+        measure_cov=measure_cov,
+        min_ratio=min_ratio,
+        measure_diff_coverage=verifier.measure_diff_coverage,
+        coverage_target_commands=verifier._coverage_target_commands,
+        next_gap_id=verifier._next_gap_id,
+    )
+    gaps.extend(dc_result.gaps)
+    evidence_to_save.extend(dc_result.evidence)
+    coverage_measured = dc_result.coverage_measured
+    coverage_skipped_reason = dc_result.coverage_skipped_reason
+
+    log_step(
+        "verify/9: diff coverage",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        coverage_measured=coverage_measured,
+        gaps_so_far=len(gaps),
+    )
+    if diff_content:
+        gaps.extend(verifier.secret_scanner.scan_diff(diff_content, task.id))
+
+    log_step(
+        "verify/10: secret scan",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        gaps_so_far=len(gaps),
+    )
+    if review_future is not None:
+        try:
+            review_result = await review_future
+            for finding in review_result.findings:
+                review_key = (
+                    f"{getattr(finding, 'file', '') or ''}:"
+                    f"{getattr(finding, 'line', '') or ''}:"
+                    f"{finding.description[:48]}"
+                )
+                finding.id = verifier._next_gap_id(task.id, f"REVIEW-{review_key}")
+                finding.blocking = bool(
+                    rigor.reviewer_required and finding.severity == "critical"
+                )
+                gaps.append(finding)
+        except Exception as exc:
+            logger.error("Implementation review failed: %s", exc)
+
+    log_step(
+        "verify/11: implementation review",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        gaps_so_far=len(gaps),
+    )
+    for card in unresolved_blocking_cards(verifier.project_root, task_id=task.id):
+        gaps.append(Gap(
+            id=verifier._next_gap_id(task.id, f"LIVE-{card.id}"),
+            severity="critical",
+            gap_type="architecture_drift",
+            task_id=task.id,
+            description=f"Open critical live-review card remains: {card.summary}",
+            evidence=[card.id, card.message_for_agent],
+            recommended_fix=(
+                f"Address the critique card, then run `dev watch resolve {card.id}` "
+                "or mark it ignored with justification outside the verification gate."
+            ),
+            blocking=True,
+        ))
+
+    # Post-step: a change spanning many subsystems / files likely stales the codebase
+    # wiki. Flag the stale pages (or auto-refresh, per config). Best-effort and never
+    # blocking — an orientation aid, not a gate.
+    wiki_refresh_outcome = None
+    try:
+        from devcouncil.verification.wiki_refresh import (
+            evaluate_wiki_refresh,
+            wiki_refresh_advisory_gap,
+        )
+
+        wiki_cfg = getattr(_cfg.verification, "wiki_refresh", None) if _cfg is not None else None
+        if changed_files and (wiki_cfg is None or wiki_cfg.enabled):
+            wiki_refresh_outcome = evaluate_wiki_refresh(
+                verifier.project_root,
+                changed_files,
+                repo_map=verifier._load_repo_map(),
+                config=wiki_cfg,
+            )
+            advisory = wiki_refresh_advisory_gap(
+                wiki_refresh_outcome,
+                task_id=task.id,
+                gap_id=verifier._next_gap_id(task.id, "WIKI"),
+            )
+            if advisory is not None:
+                gaps.append(advisory)
+    except Exception as exc:
+        logger.debug("wiki refresh post-step skipped: %s", exc)
+
+    from devcouncil.verification.gap_ids import normalize_verify_gaps
+    from devcouncil.verification.verifier import VerificationOutcome
+
+    gaps = normalize_verify_gaps(gaps)
+    blocking_count = len([g for g in gaps if g.blocking])
+    log_step(
+        "verify/complete",
+        project_root=verifier.project_root,
+        task_id=task.id,
+        total_gaps=len(gaps),
+        blocking_gaps=blocking_count,
+        evidence_items=len(evidence_to_save),
+        trace=True,
+    )
+
+    verifier.last_outcome = VerificationOutcome(
+        mode=_verification_mode_label(evidence_to_save, compiler_active=compiler_active),
+        compiler_active=compiler_active,
+        diff_empty=diff_empty,
+        coverage_measured=coverage_measured,
+        coverage_skipped_reason=coverage_skipped_reason,
+        difficulty=rigor.difficulty,
+        rigor_applied=list(rigor.applied),
+        wiki_refresh=wiki_refresh_outcome.to_dict() if wiki_refresh_outcome is not None else None,
+        liveness_baseline=liveness_baseline_status,
+    )
+    return gaps, evidence_to_save