devcouncil 0.3.0 → 0.4.0

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

@@ -0,0 +1,98 @@
+"""Planned-file compliance checks extracted from Verifier."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, List
+
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+
+_DEP_FILES = {
+    "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
+    "requirements.txt", "pyproject.toml", "uv.lock", "Pipfile.lock",
+    "go.mod", "go.sum", "Cargo.toml", "Cargo.lock",
+}
+
+
+def dependency_files_changed(changed_files: List[str]) -> List[str]:
+    """Return changed dependency manifest paths."""
+    return [path for path in changed_files if Path(path).name in _DEP_FILES]
+
+
+def detect_no_work_gap(
+    *,
+    task: Task,
+    work_present: bool,
+    next_gap_id: Callable[[str, str], str],
+) -> Gap | None:
+    """Block when a task expects file changes but produced none."""
+    expects_change = any(pf.allowed_change != "read_only" for pf in task.planned_files)
+    if work_present or not expects_change:
+        return None
+    return Gap(
+        id=next_gap_id(task.id, "NODIFF"),
+        severity="high",
+        gap_type="task_not_implemented",
+        task_id=task.id,
+        description=(
+            f"Task {task.id} declares files to create or modify, but produced no "
+            "changes. Verification cannot prove work that does not exist."
+        ),
+        evidence=[f"planned files expecting change: {sorted(p.path for p in task.planned_files if p.allowed_change != 'read_only')}"],
+        recommended_fix=(
+            "Implement the planned changes so the diff is non-empty, then re-verify. "
+            "If you did make changes, ensure they are saved and visible to git "
+            "(not reverted, stashed, or written outside the project root)."
+        ),
+        blocking=True,
+    )
+
+
+def detect_planned_file_gaps(
+    *,
+    task: Task,
+    changed_files: List[str],
+    next_gap_id: Callable[[str, str], str],
+) -> List[Gap]:
+    """Advisory gaps for planned files that were not modified."""
+    gaps: List[Gap] = []
+    changed_set = set(changed_files)
+    for pf in task.planned_files:
+        if pf.path not in changed_set and pf.allowed_change != "read_only":
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"FILE-{pf.path}"),
+                severity="medium",
+                gap_type="planned_file_not_changed",
+                task_id=task.id,
+                description=f"Planned file {pf.path} was not modified.",
+                recommended_fix=f"Modify {pf.path} as planned or update the task.",
+                blocking=False,
+                file=pf.path,
+            ))
+    return gaps
+
+
+def detect_dependency_risk_gaps(
+    *,
+    task: Task,
+    changed_files: List[str],
+    planned_paths: set[str],
+    next_gap_id: Callable[[str, str], str],
+) -> List[Gap]:
+    """Blocking gaps for dependency manifest edits outside the plan."""
+    gaps: List[Gap] = []
+    for dep_file in dependency_files_changed(changed_files):
+        if dep_file not in planned_paths:
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"DEP-{dep_file}"),
+                severity="high",
+                gap_type="dependency_risk",
+                task_id=task.id,
+                description=f"Dependency file {dep_file} was modified without being in planned files.",
+                evidence=[dep_file],
+                recommended_fix=f"Justify the dependency change or revert {dep_file}.",
+                blocking=True,
+                file=dep_file,
+            ))
+    return gaps

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

@@ -0,0 +1,241 @@
+"""Semantic-index drift checks extracted from Verifier."""
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.utils.json_persist import read_json
+
+logger = logging.getLogger(__name__)
+
+
+def task_intent_text(task: Task, requirements: Optional[List[Requirement]]) -> str:
+    """Lowercased text describing what the task is meant to do."""
+    parts = [task.title or "", task.description or ""]
+    if requirements:
+        ac_ids = set(task.acceptance_criterion_ids)
+        for req in requirements:
+            for ac in req.acceptance_criteria:
+                if ac.id in ac_ids:
+                    parts.append(ac.description or "")
+    return " ".join(parts).lower()
+
+
+def import_top_level(statement: str) -> Optional[str]:
+    """Top-level package of an import statement, or None for relative/local/unparseable."""
+    s = (statement or "").strip()
+    if s.startswith("import "):
+        first = s[len("import "):].split(",")[0].strip()
+        top = first.split(" as ")[0].strip().split(".")[0].strip()
+        return top or None
+    if s.startswith("from "):
+        rest = s[len("from "):].lstrip()
+        if rest.startswith("."):
+            return None
+        mod = rest.split(" import ")[0].strip()
+        return (mod.split(".")[0].strip() or None) if mod else None
+    return None
+
+
+def stdlib_modules() -> frozenset[str]:
+    names = getattr(sys, "stdlib_module_names", None)
+    return frozenset(names) if names else frozenset()
+
+
+def load_project_dependencies(project_root: Path) -> set[str]:
+    """Lower-cased distribution names declared by the project."""
+    deps: set[str] = set()
+    split_re = r"[><=!~;\[\] ]"
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            import tomllib
+
+            data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+            project = data.get("project", {}) or {}
+            for dep in project.get("dependencies", []) or []:
+                pkg = re.split(split_re, dep.strip())[0].strip().lower()
+                if pkg:
+                    deps.add(pkg)
+            for group in (project.get("optional-dependencies", {}) or {}).values():
+                for dep in group or []:
+                    pkg = re.split(split_re, dep.strip())[0].strip().lower()
+                    if pkg:
+                        deps.add(pkg)
+        except Exception:
+            pass
+    requirements = project_root / "requirements.txt"
+    if requirements.exists():
+        try:
+            for line in requirements.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    pkg = re.split(split_re, line)[0].strip().lower()
+                    if pkg:
+                        deps.add(pkg)
+        except Exception:
+            pass
+    package_json = project_root / "package.json"
+    if package_json.exists():
+        try:
+            data = read_json(package_json)
+            for key in ("dependencies", "devDependencies", "optionalDependencies"):
+                deps.update(k.lower() for k in (data.get(key) or {}).keys())
+        except Exception:
+            pass
+    return deps
+
+
+def is_new_third_party_import(top: Optional[str], *, project_deps: set[str]) -> bool:
+    """True only when ``top`` is a genuinely new, undeclared third-party package."""
+    if not top:
+        return False
+    if top in stdlib_modules():
+        return False
+    if top.lower() in project_deps:
+        return False
+    try:
+        import importlib.util
+
+        if importlib.util.find_spec(top) is not None:
+            return False
+    except Exception:
+        return False
+    return True
+
+
+def detect_semantic_diff_gaps(
+    *,
+    project_root: Path,
+    task: Task,
+    requirements: Optional[List[Requirement]],
+    next_gap_id: Callable[[str, str], str],
+    project_deps: set[str],
+) -> List[Gap]:
+    """Run semantic-index drift checks when an after snapshot exists."""
+    gaps: List[Gap] = []
+    after_path = project_root / ".devcouncil" / "semantic" / task.id / "after.json"
+    if not after_path.exists():
+        return gaps
+    try:
+        from devcouncil.indexing.semantic_index import SemanticIndex
+
+        result = SemanticIndex(project_root).diff(task.id)
+    except Exception as exc:
+        logger.warning("Semantic diff check failed for %s; skipping semantic gaps: %s", task.id, exc)
+        return gaps
+
+    planned_paths = {pf.path for pf in task.planned_files}
+    classifications = result.get("classifications", [])
+    readded_public = {
+        item.get("name") for item in classifications
+        if item.get("type") == "exported_symbol_added" and item.get("name")
+    }
+    intent_text = task_intent_text(task, requirements)
+    for item in classifications:
+        change_type = item.get("type", "")
+        path = item.get("path", "")
+        if change_type == "exported_symbol_removed":
+            name = item.get("name", "")
+            moved = name in readded_public
+            intended = bool(name) and name.lower() in intent_text
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"DRIFT-{path}:{name}"),
+                severity="high",
+                gap_type="architecture_drift",
+                task_id=task.id,
+                description=(
+                    f"Public symbol '{name}' was removed from {path} — possible scope "
+                    "drift: the executor changed a public API the task did not call for."
+                ),
+                evidence=[f"{path}:{name}"],
+                recommended_fix=(
+                    "Restore the removed public symbol. If its removal IS part of this "
+                    "task, state that in the task description / acceptance criteria so the "
+                    "change is an intended, reviewed decision rather than silent drift."
+                ),
+                blocking=(not moved and not intended),
+                file=path,
+            ))
+        elif change_type == "public_api_change" and path not in planned_paths:
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"SEM-{path}"),
+                severity="high",
+                gap_type="architecture_drift",
+                task_id=task.id,
+                description=f"Unplanned public API change detected in {path}.",
+                evidence=[path],
+                recommended_fix="Add file to planned_files and document acceptance criteria.",
+                blocking=not bool(task.acceptance_criterion_ids),
+            ))
+        elif change_type == "public_api_change" and path in planned_paths:
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"SIGDRIFT-{path}:{item.get('name', '')}"),
+                severity="medium",
+                gap_type="architecture_drift",
+                task_id=task.id,
+                description=(
+                    f"Public API signature change in planned file {path}"
+                    + (f" ({item.get('name')})" if item.get("name") else "")
+                    + ". Confirm callers are updated and the change is intended."
+                ),
+                evidence=[f"{path}:{item.get('name', '')}"],
+                recommended_fix=(
+                    "If the signature change is part of this task, note it in the task "
+                    "description / acceptance criteria; otherwise revert it."
+                ),
+                blocking=False,
+            ))
+        elif change_type == "import_dependency_change":
+            statement = item.get("statement", "")
+            top = import_top_level(statement)
+            new_third_party = is_new_third_party_import(top, project_deps=project_deps)
+            if new_third_party:
+                gaps.append(Gap(
+                    id=next_gap_id(task.id, f"DEPADD-{path}:{top}"),
+                    severity="high",
+                    gap_type="dependency_risk",
+                    task_id=task.id,
+                    description=(
+                        f"New undeclared third-party dependency '{top}' imported in {path} "
+                        f"({statement.strip()}). Adding a dependency the task did not plan is "
+                        "supply-chain drift."
+                    ),
+                    evidence=[path, statement.strip()],
+                    recommended_fix=(
+                        f"Declare '{top}' in the project's dependencies and plan the change, "
+                        "or use an existing/standard-library alternative."
+                    ),
+                    blocking=True,
+                    file=path,
+                ))
+            elif path not in planned_paths:
+                gaps.append(Gap(
+                    id=next_gap_id(task.id, f"IMP-{path}"),
+                    severity="medium",
+                    gap_type="dependency_risk",
+                    task_id=task.id,
+                    description=f"Import dependency change in {path}.",
+                    evidence=[path],
+                    recommended_fix="Confirm dependency change is intentional.",
+                    blocking=False,
+                ))
+        elif change_type == "config_schema_dependency_change" and path not in planned_paths:
+            gaps.append(Gap(
+                id=next_gap_id(task.id, f"CFG-{path}"),
+                severity="high",
+                gap_type="dependency_risk",
+                task_id=task.id,
+                description=f"Config/schema change detected in {path}.",
+                evidence=[path],
+                recommended_fix="Plan the config change or revert it.",
+                blocking=True,
+            ))
+    return gaps

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

@@ -0,0 +1,80 @@
+"""Stale-map gate: flag when ``repo_map.json`` is missing or lags git HEAD.
+
+Missing map is always stale (fail-closed on hard rigor). Advisory on easy/normal;
+blocking on hard. Never raises.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Callable, List, Mapping, Optional
+
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+
+logger = logging.getLogger(__name__)
+
+
+def detect_stale_map_gaps(
+    *,
+    task: Task,
+    project_root: Path,
+    next_gap_id: Callable[[str, str], str],
+    stale_map_enabled: bool = True,
+    stale_map_blocking: bool = False,
+    repo_map: Optional[Mapping] = None,
+) -> List[Gap]:
+    """Emit a ``stale_map`` gap when the on-disk map no longer matches the repo."""
+    if not stale_map_enabled:
+        return []
+    try:
+        data = repo_map
+        if data is None:
+            map_path = project_root / ".devcouncil" / "repo_map.json"
+            if not map_path.is_file():
+                return [Gap(
+                    id=next_gap_id(task.id, "STALEMAP-MISSING"),
+                    severity="high" if stale_map_blocking else "medium",
+                    gap_type="stale_map",
+                    task_id=task.id,
+                    description=(
+                        "Repository map ``.devcouncil/repo_map.json`` is missing. "
+                        "Subsystem neighbors, dependents, and liveness gates cannot run."
+                    ),
+                    evidence=[".devcouncil/repo_map.json"],
+                    recommended_fix="Run `dev map` to generate the repository map, then re-verify.",
+                    blocking=stale_map_blocking,
+                    suggested_command="dev map",
+                )]
+            from devcouncil.utils.json_persist import read_json
+
+            loaded = read_json(map_path)
+            if not isinstance(loaded, dict):
+                return []
+            data = loaded
+
+        from devcouncil.indexing.repo_mapper import RepoMapper
+
+        if not RepoMapper(project_root).map_is_stale(dict(data)):
+            return []
+
+        stored_head = str(data.get("generated_head") or "") or "(unknown)"
+        return [Gap(
+            id=next_gap_id(task.id, "STALEMAP"),
+            severity="high" if stale_map_blocking else "medium",
+            gap_type="stale_map",
+            task_id=task.id,
+            description=(
+                "The repository map (``.devcouncil/repo_map.json``) is behind the "
+                f"current code (stored HEAD {stored_head}). Subsystem neighbors, "
+                "dependents, and liveness lists may be wrong until it is refreshed."
+            ),
+            evidence=[".devcouncil/repo_map.json", f"generated_head:{stored_head}"],
+            recommended_fix="Run `dev map` to regenerate the repository map, then re-verify.",
+            blocking=stale_map_blocking,
+            suggested_command="dev map",
+        )]
+    except Exception:
+        logger.debug("detect_stale_map_gaps failed; degrading to zero gaps", exc_info=True)
+        return []

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

@@ -0,0 +1,71 @@
+"""Stub detection helpers extracted from Verifier."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, List
+
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+from devcouncil.verification.stub_detector import (
+    detect_stub_declarations,
+    detect_stubs,
+    task_allows_scaffolding,
+)
+
+
+def detect_stub_gaps(
+    *,
+    task: Task,
+    diff_content: str,
+    project_root: Path,
+    stub_enabled: bool,
+    stub_blocking: bool,
+    next_gap_id: Callable[[str, str], str],
+) -> List[Gap]:
+    """Scan diff-added lines for stubs/TODOs and declared scaffolding markers."""
+    gaps: List[Gap] = []
+    if not stub_enabled or not diff_content:
+        return gaps
+    scaffolding_ok = task_allows_scaffolding(task)
+    for finding in detect_stubs(project_root, diff_content, honor_allow_stub=scaffolding_ok):
+        gaps.append(Gap(
+            id=next_gap_id(task.id, f"STUB-{finding.file}:{finding.line}"),
+            severity="high" if stub_blocking else "medium",
+            gap_type="stub_detected",
+            task_id=task.id,
+            description=(
+                f"Placeholder/incomplete code added at {finding.file}:{finding.line}: "
+                f"{finding.reason}."
+            ),
+            evidence=[f"{finding.file}:{finding.line}", finding.snippet],
+            recommended_fix=(
+                f"Replace the stub/placeholder at {finding.file}:{finding.line} with a "
+                "real implementation, then re-verify. Intentional scaffolding requires "
+                "the task description to mention 'scaffolding' and the line to carry "
+                "'devcouncil: allow-stub'."
+            ),
+            blocking=stub_blocking,
+            file=finding.file,
+            line=finding.line,
+        ))
+    for decl in detect_stub_declarations(diff_content):
+        gaps.append(Gap(
+            id=next_gap_id(task.id, f"STUBDECL-{decl.file}:{decl.line}"),
+            severity="medium",
+            gap_type="stub_declared",
+            task_id=task.id,
+            description=(
+                f"Intentional stub declared at {decl.file}:{decl.line} "
+                f"({decl.snippet[:80]})."
+            ),
+            evidence=[f"{decl.file}:{decl.line}", decl.snippet],
+            recommended_fix=(
+                "Review declared stubs before marking the task done; replace each "
+                "placeholder with a real implementation when scaffolding is complete."
+            ),
+            blocking=False,
+            file=decl.file,
+            line=decl.line,
+        ))
+    return gaps

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

@@ -0,0 +1,103 @@
+"""Advisory subsystem-boundary gate — architecture drift over the mapped area graph.
+
+The repo map already knows which subsystems are *neighbors* (they hand off to each
+other). A change that edits files in two subsystems the map does NOT consider neighbors,
+and that the task plan never declared it would span, is a candidate architecture-drift
+crossing: business logic leaking into a UI layer, a storage change reaching into the
+council prompts, etc.
+
+This gate flags those crossings. It is **advisory (non-blocking) by default** — an
+undeclared crossing is often legitimate, so it should inform review rather than halt the
+loop — but is ``blocking``-configurable for teams that want a hard architectural
+boundary. It reads only ``repo_map.json`` (no model calls, no subprocess) and degrades to
+a no-op when the map lacks ``subsystems``/``neighbors``.
+
+"Plan coverage": a crossing between areas A and B is covered when the task's *planned
+files* already live in both A and B — i.e. the plan declared the change would touch both
+subsystems. Only crossings that reach an area the plan did not declare are flagged.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable, List, Mapping, Sequence
+
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+from devcouncil.indexing.subsystem_map import (
+    area_for_path,
+    areas_touched,
+    cross_boundary_pairs,
+)
+
+logger = logging.getLogger(__name__)
+
+# Cap emitted crossings so a sprawling change can't flood the gap list.
+_MAX_CROSSINGS = 6
+
+
+def detect_subsystem_boundary_gaps(
+    *,
+    task: Task,
+    changed_files: Sequence[str],
+    repo_map: Mapping | None,
+    next_gap_id: Callable[[str, str], str],
+    blocking: bool = False,
+) -> List[Gap]:
+    """Flag edits that cross non-neighbor subsystem boundaries without plan coverage.
+
+    Returns advisory (or blocking, per ``blocking``) architecture-drift gaps — one per
+    undeclared crossing pair. Empty when the map is missing/degenerate, the change stays
+    within one area, or every crossing was already declared by the plan.
+    """
+    if not repo_map or not (repo_map.get("subsystems") if hasattr(repo_map, "get") else None):
+        return []
+
+    changed = [p.replace("\\", "/") for p in changed_files if p and p.strip()]
+    if len(areas_touched(changed, repo_map)) < 2:
+        return []
+
+    planned_paths = [pf.path.replace("\\", "/") for pf in task.planned_files]
+    planned_areas = set(areas_touched(planned_paths, repo_map))
+
+    crossings = cross_boundary_pairs(changed, repo_map)
+    if not crossings:
+        return []
+
+    gaps: List[Gap] = []
+    for area_a, area_b in crossings[:_MAX_CROSSINGS]:
+        # Covered when the plan declared files in BOTH areas of the crossing.
+        if area_a in planned_areas and area_b in planned_areas:
+            continue
+        undeclared = sorted({area_a, area_b} - planned_areas)
+        files_a = [f for f in changed if area_for_path(f, repo_map) == area_a]
+        files_b = [f for f in changed if area_for_path(f, repo_map) == area_b]
+        evidence = [f"{area_a}: " + ", ".join(files_a[:5])] if files_a else []
+        if files_b:
+            evidence.append(f"{area_b}: " + ", ".join(files_b[:5]))
+        gaps.append(Gap(
+            id=next_gap_id(task.id, f"BOUNDARY-{area_a}-{area_b}"),
+            severity="medium",
+            gap_type="architecture_drift",
+            task_id=task.id,
+            description=(
+                f"Change spans non-neighbor subsystems `{area_a}` and `{area_b}` "
+                f"but the plan did not declare it would touch {', '.join(f'`{a}`' for a in undeclared)}. "
+                "Cross-boundary edits between areas the repo map does not consider "
+                "adjacent are a common source of architecture drift."
+            ),
+            evidence=evidence or [f"{area_a} ⇄ {area_b}"],
+            recommended_fix=(
+                "If this crossing is intended, declare planned files in both subsystems "
+                "(or split the work into per-subsystem tasks); otherwise keep the edit "
+                "within its subsystem and route through the neighboring interface. "
+                "Run `dev map` if the subsystem neighbors are out of date."
+            ),
+            blocking=blocking,
+        ))
+    if gaps:
+        logger.info(
+            "subsystem-boundary gate: %d undeclared crossing(s) for task %s (blocking=%s)",
+            len(gaps), task.id, blocking,
+        )
+    return gaps