devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/utils/git_snapshot.py

@@ -0,0 +1,112 @@
+"""Batch git worktree queries into a minimal set of subprocess calls.
+
+Verifier hot paths previously invoked ``git diff``, ``git diff --name-only``, and
+``git ls-files --others`` independently (and sometimes repeatedly within one
+``verify_task``).  ``GitWorktreeSnapshot.capture`` runs at most three plumbing
+commands — ``rev-parse``, ``diff HEAD`` (when HEAD exists), and
+``status --porcelain -z`` — and caches the parsed results for the rest of the
+verification pass.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Union
+
+from devcouncil.utils.proc import GIT_TIMEOUT, git_output, run_git
+
+PathLike = Union[str, Path]
+
+
+@dataclass
+class GitWorktreeSnapshot:
+    """Cached worktree state from a single batched git probe."""
+
+    has_head: bool
+    tracked_diff: str = ""
+    tracked_changed_files: List[str] = field(default_factory=list)
+    untracked_files: List[str] = field(default_factory=list)
+    cached_diff: str = ""
+    working_diff: str = ""
+    status_paths: List[str] = field(default_factory=list)
+
+    @classmethod
+    def capture(cls, root: PathLike, *, timeout: float = GIT_TIMEOUT) -> GitWorktreeSnapshot:
+        root = Path(root)
+        has_head = (
+            run_git(["rev-parse", "--verify", "HEAD"], root, timeout=timeout).returncode == 0
+        )
+        status_entries = _parse_status(root, timeout=timeout)
+        untracked = [e.path for e in status_entries if e.xy == "??"]
+        status_paths = [e.path for e in status_entries]
+
+        if has_head:
+            tracked_diff = git_output(["diff", "HEAD"], root, timeout=timeout, default="")
+            tracked_changed = sorted({e.path for e in status_entries if e.xy != "??"})
+            if not tracked_changed and tracked_diff.strip():
+                name_out = git_output(
+                    ["diff", "HEAD", "--name-only"], root, timeout=timeout, default=""
+                )
+                tracked_changed = [p.replace("\\", "/") for p in name_out.splitlines() if p.strip()]
+            return cls(
+                has_head=True,
+                tracked_diff=tracked_diff,
+                tracked_changed_files=tracked_changed,
+                untracked_files=sorted(set(untracked)),
+                status_paths=status_paths,
+            )
+
+        cached_diff = git_output(["diff", "--cached"], root, timeout=timeout, default="")
+        working_diff = git_output(["diff"], root, timeout=timeout, default="")
+        if not untracked:
+            untracked = _ls_untracked(root, timeout=timeout)
+        if not status_paths:
+            status_paths = sorted(set(untracked))
+        return cls(
+            has_head=False,
+            cached_diff=cached_diff,
+            working_diff=working_diff,
+            untracked_files=sorted(set(untracked)),
+            status_paths=status_paths,
+        )
+
+
+@dataclass(frozen=True)
+class _StatusEntry:
+    xy: str
+    path: str
+
+
+def _parse_status(root: Path, *, timeout: float) -> List[_StatusEntry]:
+    result = run_git(["status", "--porcelain", "-z", "-u"], root, timeout=timeout)
+    if result.returncode != 0 or not result.stdout:
+        return []
+    entries: List[_StatusEntry] = []
+    parts = result.stdout.split("\0")
+    i = 0
+    while i < len(parts):
+        entry = parts[i]
+        if not entry or len(entry) < 3:
+            i += 1
+            continue
+        xy = entry[:2]
+        rest = entry[3:].replace("\\", "/")
+        if "R" in xy:
+            if i + 1 < len(parts) and parts[i + 1]:
+                entries.append(_StatusEntry(xy=xy, path=parts[i + 1].replace("\\", "/")))
+                i += 2
+                continue
+        entries.append(_StatusEntry(xy=xy, path=rest))
+        i += 1
+    return entries
+
+
+def _ls_untracked(root: Path, *, timeout: float) -> List[str]:
+    out = git_output(
+        ["ls-files", "--others", "--exclude-standard"],
+        root,
+        timeout=timeout,
+        default="",
+    )
+    return [p.replace("\\", "/") for p in out.splitlines() if p.strip()]

package/src/devcouncil/utils/json_persist.py

@@ -0,0 +1,53 @@
+"""Central JSON read/write helpers built on atomic fsio writes."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypeVar, Union
+
+from pydantic import BaseModel
+
+from devcouncil.utils.fsio import atomic_write_json, atomic_write_text
+
+PathLike = Union[str, Path]
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+def write_json(path: PathLike, payload: Any, *, indent: int = 2, sort_keys: bool = False) -> None:
+    """Atomically serialize ``payload`` to JSON at ``path``."""
+    atomic_write_json(path, payload, indent=indent, sort_keys=sort_keys)
+
+
+def write_model_json(
+    path: PathLike,
+    model: BaseModel,
+    *,
+    indent: int | None = 2,
+    exclude_none: bool = False,
+) -> None:
+    """Atomically write a Pydantic model as JSON.
+
+    Pass ``indent=None`` for compact (minified) output.
+    """
+    atomic_write_text(
+        path,
+        model.model_dump_json(indent=indent, exclude_none=exclude_none) + "\n",
+    )
+
+
+def read_json(path: PathLike) -> Any:
+    """Load JSON from ``path``; raises ``FileNotFoundError`` / ``json.JSONDecodeError``."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def read_model_json(path: PathLike, model_type: type[ModelT]) -> ModelT:
+    """Load and validate JSON as a Pydantic model."""
+    return model_type.model_validate_json(Path(path).read_text(encoding="utf-8"))
+
+
+def dump_json(payload: Any, *, indent: int | None = None, sort_keys: bool = False, separators: tuple[str, str] | None = None) -> str:
+    """Serialize ``payload`` to a JSON string (stdout / DB columns)."""
+    if separators is not None:
+        return json.dumps(payload, indent=indent, sort_keys=sort_keys, separators=separators)
+    return json.dumps(payload, indent=indent, sort_keys=sort_keys)

package/src/devcouncil/utils/proc.py

@@ -0,0 +1,89 @@
+"""Shared subprocess helpers with consistent timeouts and error handling.
+
+Every git/tool invocation in DevCouncil should go through these helpers (or at
+minimum pass an explicit ``timeout=``) so a hung child process can never hang a
+verification run or the CLI. Defaults are deliberately generous: they exist to
+convert "hangs forever" into "fails loudly", not to race fast commands.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import List, Optional, Sequence, Union
+
+logger = logging.getLogger(__name__)
+
+# Default ceiling for git plumbing commands (status/diff/ls-files/rev-parse).
+GIT_TIMEOUT: float = 60.0
+# Default ceiling for generic tool invocations when the caller has no better bound.
+DEFAULT_TIMEOUT: float = 120.0
+
+Cmd = Sequence[str]
+PathLike = Union[str, Path]
+
+
+def run_git(
+    args: Cmd,
+    cwd: PathLike,
+    *,
+    timeout: float = GIT_TIMEOUT,
+    check: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run a git command with a timeout, capturing decoded text output.
+
+    Never raises ``TimeoutExpired``: a timeout is logged and surfaced as a
+    ``CompletedProcess`` with returncode 124 so existing ``returncode``/stdout
+    checks keep working. Raises ``CalledProcessError`` only when ``check=True``
+    and the command failed (mirroring ``subprocess.run``).
+    """
+    cmd: List[str] = ["git", *args] if args and args[0] != "git" else list(args)
+    try:
+        return subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            check=check,
+        )
+    except subprocess.TimeoutExpired:
+        logger.warning("git command timed out after %.0fs: %s (cwd=%s)", timeout, " ".join(cmd), cwd)
+        return subprocess.CompletedProcess(cmd, returncode=124, stdout="", stderr=f"timed out after {timeout}s")
+
+
+def git_output(
+    args: Cmd,
+    cwd: PathLike,
+    *,
+    timeout: float = GIT_TIMEOUT,
+    default: Optional[str] = None,
+) -> str:
+    """Return stdout of a git command, or ``default`` on any failure.
+
+    When ``default`` is None a failure raises ``CalledProcessError`` /
+    ``TimeoutExpired`` for the caller's existing except paths; otherwise the
+    failure is logged at debug level and ``default`` is returned.
+    """
+    cmd: List[str] = ["git", *args] if args and args[0] != "git" else list(args)
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+        if result.returncode != 0:
+            raise subprocess.CalledProcessError(result.returncode, cmd, result.stdout, result.stderr)
+        return result.stdout
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError) as e:
+        if default is not None:
+            logger.debug("git command failed (%s): %s (cwd=%s)", e, " ".join(cmd), cwd)
+            return default
+        raise

package/src/devcouncil/verification/acceptance_compiler.py

@@ -10,6 +10,7 @@ text and the code under review, then maps each check 1:1 to its criterion.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 from typing import Dict, List
@@ -92,9 +93,17 @@ class AcceptanceTestCompiler:
             return {}
 
         if per_criterion and len(target) > 1:
+            # Independent per-criterion compiles: run them CONCURRENTLY. Each call is
+            # independent (own prompt, own criterion), so wall-clock drops from N
+            # sequential model calls to max-of-N — the difference between minutes and
+            # tens of minutes on a slow local monitor. A server that processes
+            # requests serially just queues them (no worse than before).
+            results = await asyncio.gather(
+                *(self._sample_checks([ac], code_context, samples) for ac in target)
+            )
             out: Dict[str, List[str]] = {}
-            for ac in target:
-                out.update(await self._sample_checks([ac], code_context, samples))
+            for result in results:
+                out.update(result)
             return out
         return await self._sample_checks(target, code_context, samples)
 
@@ -104,21 +113,29 @@ class AcceptanceTestCompiler:
         """Generate up to ``samples`` independent check commands for ``target`` criteria."""
         valid_ids = {ac.id for ac in target}
         out: Dict[str, List[str]] = {}
+
         # Independent attempts. Each varies temperature + an attempt marker so the router
         # cache keys differ (otherwise an identical prompt+temp returns the cached answer
         # and every "sample" is the same command). Attempt 0 stays deterministic (temp 0).
-        for attempt in range(max(1, samples)):
+        async def _one_attempt(attempt: int) -> "CompiledChecks":
             temperature = 0.0 if attempt == 0 else min(0.8, 0.3 + 0.2 * attempt)
-            try:
-                result = await self.router.complete_structured(
-                    role=self.role,
-                    messages=[{"role": "user", "content": self._compile_prompt(target, code_context, attempt)}],
-                    schema=CompiledChecks,
-                    temperature=temperature,
-                    fallback=CompiledChecks(checks=[]),
-                )
-            except Exception as e:
-                logger.warning("Acceptance-check compile attempt %d failed: %s", attempt, e)
+            return await self.router.complete_structured(
+                role=self.role,
+                messages=[{"role": "user", "content": self._compile_prompt(target, code_context, attempt)}],
+                schema=CompiledChecks,
+                temperature=temperature,
+                fallback=CompiledChecks(checks=[]),
+            )
+
+        # Attempts are independent by construction (distinct prompts/temperatures), so
+        # run them concurrently; results are merged in attempt order to keep candidate
+        # ordering deterministic. A failed attempt costs only itself.
+        results = await asyncio.gather(
+            *(_one_attempt(a) for a in range(max(1, samples))), return_exceptions=True
+        )
+        for attempt, result in enumerate(results):
+            if isinstance(result, BaseException):
+                logger.warning("Acceptance-check compile attempt %d failed: %s", attempt, result)
                 continue
             for check in result.checks:
                 cmd = (check.command or "").strip()
@@ -228,6 +245,12 @@ Rules — the commands are executed verbatim by the verifier:
   python -c "import m; \\ntry: m.f([])\\nexcept ValueError: pass\\nelse: raise SystemExit(1)"
   (real newlines are fine; never put try/if/for after a ';').
 - Use the actual module name implied by the code (e.g. file 'stats.py' -> import stats).
+- Choose DISCRIMINATING inputs: pick the input a plausible-but-lazy implementation
+  would get WRONG, not the easiest happy-path example (which often passes on broken
+  code and proves nothing). Examples: to prove "comment lines are skipped", the
+  comment must CONTAIN the delimiter ('# c=3'); to prove "split on the first X",
+  the value must itself contain X; to prove sorting/ordering, the input must start
+  unsorted; to prove a boundary, test AT the boundary.
 
 HARD PROHIBITIONS — a command that does any of these is INVALID; omit the
 criterion instead of emitting such a command:

package/src/devcouncil/verification/ad_hoc_check.py

@@ -45,6 +45,7 @@ class AdHocCheckResult:
     diff_coverage: Optional[DiffCoverageEvidence] = None
     passed: bool = True
     reason: str = ""
+    verification_mode: str = "coarse"
 
     def to_dict(self) -> dict:
         return {
@@ -53,6 +54,7 @@ class AdHocCheckResult:
             "requirement": self.requirement,
             "changed_files": self.changed_files,
             "reason": self.reason,
+            "verification_mode": self.verification_mode,
             "gap_count": len(self.gaps),
             "blocking_gap_count": len([g for g in self.gaps if g.blocking]),
             "gaps": [g.model_dump() for g in self.gaps],
@@ -61,13 +63,79 @@ class AdHocCheckResult:
         }
 
 
+def _load_verify_router(project_root: Path) -> Optional[ModelRouter]:
+    """Best-effort router for compiled acceptance checks during ad-hoc verify."""
+    try:
+        from devcouncil.app.config import get_api_key, load_config
+        from devcouncil.llm.provider import create_provider, validate_model_provider
+
+        config = load_config(project_root)
+        validate_model_provider(config.models.provider)
+        api_key = get_api_key(config.models.provider, project_root)
+        provider = create_provider(
+            config.models.provider,
+            api_key,
+            project_root=project_root,
+            provider_prefs=config.provider,
+        )
+        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+        return ModelRouter(provider, role_config, project_root=project_root)
+    except Exception as exc:
+        logger.debug("Ad-hoc check: no model router (%s)", exc)
+        return None
+
+
+def _persist_ad_hoc_result(
+    project_root: Path,
+    *,
+    requirement: Requirement,
+    task: Task,
+    gaps: List[Gap],
+    evidence: list,
+) -> None:
+    """Write CHECK task gaps/evidence so ``dev report`` can export CI artifacts."""
+    from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+    from devcouncil.storage.db import get_db
+    from devcouncil.storage.repositories import (
+        EvidenceRepository,
+        GapRepository,
+        RequirementRepository,
+        TaskRepository,
+    )
+
+    db = get_db(project_root)
+    if not db:
+        return
+    with db.get_session() as session:
+        RequirementRepository(session).save(requirement)
+        gap_repo = GapRepository(session)
+        ev_repo = EvidenceRepository(session)
+        gap_repo.delete_for_task(task.id)
+        ev_repo.delete_for_task(task.id)
+        for gap in gaps:
+            gap_repo.save(gap)
+        for ev in evidence:
+            if isinstance(ev, CommandResult):
+                ev_repo.save_command_result(task.id, ev)
+            elif isinstance(ev, DiffCoverageEvidence):
+                ev_repo.save_diff_coverage_evidence(ev)
+            elif isinstance(ev, DiffEvidence):
+                ev_repo.save_diff_evidence(ev)
+            elif isinstance(ev, TestEvidence):
+                ev_repo.save_test_evidence(ev, task.id)
+        task.status = "blocked" if any(g.blocking for g in gaps) else "verified"
+        TaskRepository(session).save(task)
+
+
 def run_working_tree_check(
     project_root: Path,
     requirement: Optional[str] = None,
     *,
+    base: Optional[str] = None,
     test_commands: Optional[List[str]] = None,
     enforce_coverage: bool = False,
     min_ratio: float = 0.0,
+    persist: bool = False,
     router: Optional[ModelRouter] = None,
     verifier: Optional[Verifier] = None,
 ) -> AdHocCheckResult:
@@ -77,14 +145,25 @@ def run_working_tree_check(
     result is about evidence, not scope noise) and whose expected tests are
     ``test_commands``. Diff coverage is always measured; pass ``enforce_coverage`` (or a
     positive ``min_ratio``) to make an unexercised diff blocking.
+
+    When ``base`` is set, the diff is ``git diff <base>`` (PR/base scope) instead of
+    uncommitted changes vs HEAD. Pass ``persist=True`` to write gaps/evidence for
+    ``dev report`` artifact export (typical in CI).
     """
-    verifier = verifier or Verifier(project_root, router=router)
+    verifier = verifier or Verifier(project_root, router=router or _load_verify_router(project_root))
+    if base:
+        verifier._git_fallback.diff_base = base
 
     diff = verifier.get_diff()
     changed_files = verifier.get_changed_files()
     if not diff or not changed_files:
-        logger.info("Ad-hoc check: no working-tree changes; passing trivially")
-        return AdHocCheckResult(requirement="", passed=True, reason="no_changes")
+        scope = f"against {base}" if base else "in working tree"
+        logger.info("Ad-hoc check: no changes %s; passing trivially", scope)
+        return AdHocCheckResult(
+            requirement=requirement or "",
+            passed=True,
+            reason="no_changes",
+        )
     logger.info("Ad-hoc check: %d changed file(s), enforce_coverage=%s", len(changed_files), enforce_coverage or min_ratio > 0)
 
     criterion = requirement or _DEFAULT_CRITERION
@@ -114,6 +193,7 @@ def run_working_tree_check(
             for path in changed_files
         ],
         expected_tests=list(test_commands or []),
+        difficulty="easy",
     )
 
     # Always measure diff coverage in lite mode; block on it only when asked. A positive
@@ -124,6 +204,17 @@ def run_working_tree_check(
     gaps, evidence = asyncio.run(verifier.verify_task(task, [req]))
     coverage = next((ev for ev in evidence if isinstance(ev, DiffCoverageEvidence)), None)
     blocking = [g for g in gaps if g.blocking]
+    outcome_mode = verifier.last_outcome.mode if verifier.last_outcome else (
+        "compiled" if verifier.acceptance_compiler else "coarse"
+    )
+    if persist:
+        _persist_ad_hoc_result(
+            project_root,
+            requirement=req,
+            task=task,
+            gaps=gaps,
+            evidence=evidence,
+        )
     logger.info("Ad-hoc check result: passed=%s (%d gap(s), %d blocking)", not blocking, len(gaps), len(blocking))
     return AdHocCheckResult(
         requirement=criterion,
@@ -132,4 +223,5 @@ def run_working_tree_check(
         next_actions=build_next_actions(gaps),
         diff_coverage=coverage,
         passed=not blocking,
+        verification_mode=outcome_mode,
     )

package/src/devcouncil/verification/checks/__init__.py

@@ -0,0 +1,41 @@
+"""Verification check helpers."""
+
+from devcouncil.verification.checks.acceptance import coarse_proven_acceptance_ids, unproven_acceptance_ids
+from devcouncil.verification.checks.command_evidence import run_verification_commands
+from devcouncil.verification.checks.corpus_verification import (
+    detect_acceptance_corpus_gaps,
+    detect_corpus_stale_gaps,
+    detect_doc_code_ref_gaps,
+)
+from devcouncil.verification.checks.dead_symbols import detect_dead_symbol_gaps
+from devcouncil.verification.checks.diff_coverage_gate import DiffCoverageGateResult, run_diff_coverage_gate
+from devcouncil.verification.checks.liveness_ratchet import detect_liveness_regressions
+from devcouncil.verification.checks.orphan_diff import detect_orphan_diff_gaps
+from devcouncil.verification.checks.planned_files import (
+    detect_dependency_risk_gaps,
+    detect_no_work_gap,
+    detect_planned_file_gaps,
+)
+from devcouncil.verification.checks.stale_map import detect_stale_map_gaps
+from devcouncil.verification.checks.stub_scan import detect_stub_gaps
+from devcouncil.verification.checks.wiring import detect_unwired_file_gaps
+
+__all__ = [
+    "DiffCoverageGateResult",
+    "detect_acceptance_corpus_gaps",
+    "detect_corpus_stale_gaps",
+    "detect_doc_code_ref_gaps",
+    "coarse_proven_acceptance_ids",
+    "detect_dead_symbol_gaps",
+    "detect_dependency_risk_gaps",
+    "detect_liveness_regressions",
+    "detect_no_work_gap",
+    "detect_orphan_diff_gaps",
+    "detect_planned_file_gaps",
+    "detect_stale_map_gaps",
+    "detect_stub_gaps",
+    "detect_unwired_file_gaps",
+    "run_diff_coverage_gate",
+    "run_verification_commands",
+    "unproven_acceptance_ids",
+]

package/src/devcouncil/verification/checks/acceptance.py

@@ -0,0 +1,39 @@
+"""Acceptance-criteria evidence helpers extracted from Verifier."""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Iterable, List, Set
+
+
+def coarse_proven_acceptance_ids(
+    *,
+    task_acceptance_ids: Iterable[str],
+    successful_commands: List[str],
+    command_can_prove: Callable[[str, str], bool],
+) -> Set[str]:
+    """Return AC ids coarse-proven by any passing acceptance-capable command."""
+    if not task_acceptance_ids or not successful_commands:
+        return set()
+    if not any(command_can_prove("expected", cmd) for cmd in successful_commands):
+        return set()
+    return set(task_acceptance_ids)
+
+
+def unproven_acceptance_ids(
+    *,
+    task_acceptance_ids: Iterable[str],
+    compiled_pass: Dict[str, bool],
+    coarse_proven: Set[str],
+    inconclusive: Set[str],
+) -> List[str]:
+    """AC ids still lacking decisive proof after compiled + coarse passes."""
+    unproven: List[str] = []
+    for ac_id in task_acceptance_ids:
+        if ac_id in inconclusive:
+            continue
+        if compiled_pass.get(ac_id):
+            continue
+        if ac_id in coarse_proven:
+            continue
+        unproven.append(ac_id)
+    return unproven