devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/gating/checks/planned_files_check.py

@@ -2,31 +2,58 @@ from devcouncil.domain.task import Task
 from devcouncil.domain.gap import Gap
 
 class PlannedFilesCheck:
-    """Ensures a task has legitimate files planned for modification."""
-    
+    """Ensures a task has legitimate files planned for modification.
+
+    Calibration note: weak planner models routinely emit auxiliary process tasks
+    ("run linter checks", "verify the suite passes") that declare commands or
+    expected tests but no planned files. Hard-blocking those stalls the whole run
+    and surfaces as a false ``blocked`` verdict on correct code (seen directly in
+    the benchmark). A task that declares NOTHING actionable (no files, no commands,
+    no tests) still blocks — an executor genuinely cannot do anything with it —
+    but a command/verification-only task proceeds with an advisory, and is judged
+    on its actual output by the verify gate like any other task.
+    """
+
     def check(self, task: Task) -> list[Gap]:
         gaps = []
+        has_runnable_work = bool(task.allowed_commands or task.expected_tests)
         if not task.planned_files:
             gaps.append(Gap(
                 id=f"GAP-{task.id}-NO-FILES",
-                severity="high",
+                severity="high" if not has_runnable_work else "medium",
                 gap_type="task_not_implemented",
                 task_id=task.id,
-                description=f"Task {task.id} has no planned files. Agents won't know where to write code.",
-                recommended_fix="Update the task to include at least one planned file path.",
-                blocking=True
+                description=(
+                    f"Task {task.id} has no planned files. Agents won't know where to write code."
+                    if not has_runnable_work else
+                    f"Task {task.id} has no planned files but declares commands/tests; "
+                    "treating it as a command/verification-only task (advisory)."
+                ),
+                recommended_fix=(
+                    "Update the task to include at least one planned file path."
+                    if not has_runnable_work else
+                    "Add planned files if this task is meant to change code; otherwise this is fine."
+                ),
+                blocking=not has_runnable_work,
             ))
-        
+
         has_modify = any(pf.allowed_change in ["create", "modify", "delete"] for pf in task.planned_files)
         if task.planned_files and not has_modify:
+            # Read-only-only tasks are analysis tasks: they can still execute (read code,
+            # run commands) and are already surfaced as advisory at PLAN time by the
+            # plan-approval gate. Blocking them at readiness contradicted that and
+            # stalled runs whose planner emitted a legitimate analysis step.
             gaps.append(Gap(
                 id=f"GAP-{task.id}-READ-ONLY",
                 severity="medium",
                 gap_type="task_not_implemented",
                 task_id=task.id,
-                description=f"Task {task.id} only has read-only files. No changes can be made.",
-                recommended_fix="Grant 'modify' or 'create' permissions to at least one file.",
-                blocking=True
+                description=(
+                    f"Task {task.id} only has read-only files; it can analyze but not change code. "
+                    "Expected only if this is an analysis-only task."
+                ),
+                recommended_fix="Grant 'modify' or 'create' permissions to at least one file if this task should write code.",
+                blocking=False,
             ))
-            
+
         return gaps

package/src/devcouncil/gating/checks/secret_scan_check.py

@@ -36,8 +36,8 @@ class SecretScanner:
                     if pattern.search(line):
                         counter += 1
                         logger.warning(
-                            "Potential %s secret detected in %s:%d (task %s)",
-                            key_type, current_file, new_line_no, task_id,
+                            "Potential sensitive pattern detected in %s:%d (task %s)",
+                            current_file, new_line_no, task_id,
                         )
                         gaps.append(Gap(
                             id=f"GAP-{task_id}-SECRET-{key_type.upper()}-{new_line_no}-{counter}",

package/src/devcouncil/gating/policy.py

@@ -12,10 +12,32 @@ from devcouncil.domain.critique import CritiqueFinding
 from devcouncil.gating.checks.requirement_coverage import RequirementCoverageCheck
 from devcouncil.gating.checks.planned_files_check import PlannedFilesCheck
 from devcouncil.gating.checks.clean_git import CleanGitCheck
+from devcouncil.telemetry.stages import log_step
 
 logger = logging.getLogger(__name__)
 
 
+class MapPolicyError(Exception):
+    """Raised when repository mapping validation fails (fail-closed)."""
+
+
+class FailClosedMapPolicy:
+    """Fail-closed map policy: block execution when mapping is missing or invalid."""
+
+    def validate_repo_map(self, project_root: Path) -> None:
+        """Ensure the on-disk repo map exists and is readable (fail-closed)."""
+        map_path = project_root / ".devcouncil" / "repo_map.json"
+        if not map_path.is_file():
+            raise MapPolicyError(
+                "Repository map missing: .devcouncil/repo_map.json"
+            )
+        from devcouncil.utils.json_persist import read_json
+
+        loaded = read_json(map_path)
+        if not isinstance(loaded, dict):
+            raise MapPolicyError("Repository map is unreadable")
+
+
 def _log_gate(name: str, gaps: List[Gap], *, routine: bool = False, **context: Any) -> bool:
     """Log a gate decision and return whether it passed (no blocking gaps).
 
@@ -36,6 +58,13 @@ def _log_gate(name: str, gaps: List[Gap], *, routine: bool = False, **context: A
             name, suffix,
             "; ".join(f"{g.gap_type}: {g.description}" for g in blocking),
         )
+    log_step(
+        f"gate/{name}: {'PASSED' if passed else 'FAILED'}",
+        level=logging.INFO if passed else logging.WARNING,
+        blocking=len(blocking),
+        advisory=len(gaps) - len(blocking),
+        **context,
+    )
     return passed
 
 
@@ -108,6 +137,7 @@ class GatePolicy:
         self.req_coverage = RequirementCoverageCheck()
         self.planned_files = PlannedFilesCheck()
         self.clean_git = CleanGitCheck()
+        self.map_policy = FailClosedMapPolicy()
 
     def check_plan_approval(
         self,
@@ -307,7 +337,21 @@ class GatePolicy:
         # 2. Check planned files
         gaps.extend(self.planned_files.check(task))
 
-        # 3. Surface a missing execution/verification contract — but do NOT block
+        # 3. Fail-closed map policy — block when the repo map is missing/unreadable.
+        try:
+            self.map_policy.validate_repo_map(project_root)
+        except MapPolicyError as exc:
+            gaps.append(Gap(
+                id=f"GAP-{task.id}-MAP-POLICY",
+                severity="high",
+                gap_type="requirement_not_planned",
+                task_id=task.id,
+                description=f"Map policy blocked task readiness: {exc}",
+                recommended_fix="Run `dev map` to generate a valid repository map, then retry.",
+                blocking=True,
+            ))
+
+        # 4. Surface a missing execution/verification contract — but do NOT block
         # execution on it. The executor still needs to run to implement the code,
         # and the evidence requirement is genuinely enforced at verify time
         # (acceptance_criteria_unproven / NOAC gaps). Blocking here only prevents
@@ -366,4 +410,4 @@ class GatePolicy:
                 recommended_fix="Break the cycle so the tasks can be ordered and executed.",
                 blocking=True,
             ))
-        return gaps
+        return gaps

package/src/devcouncil/indexing/ast_matcher.py

@@ -29,7 +29,7 @@ class AstMatch:
 
 
 class AstMatcher:
-    """Tree-sitter-style structural search with optional tree_sitter and deterministic fallbacks."""
+    """Structural symbol search with tree-sitter when available, regex/AST fallbacks."""
 
     _EXT_LANGUAGE = {
         ".py": "python",
@@ -59,10 +59,11 @@ class AstMatcher:
 
     def _has_tree_sitter(self) -> bool:
         try:
-            import tree_sitter  # type: ignore[import-not-found]  # noqa: F401
+            from devcouncil.indexing.ts_imports import tree_sitter_available
+
+            return tree_sitter_available()
         except Exception:
             return False
-        return True
 
     def match(
         self,
@@ -118,6 +119,38 @@ class AstMatcher:
     def _match_file(self, rel: str, language: str, text: str, *, query: str, kind: str | None) -> list[AstMatch]:
         if language == "python":
             return self._match_python(rel, text, query=query, kind=kind)
+        if self.tree_sitter_available and language in self._SYMBOL_PATTERNS:
+            ts_hits = self._match_tree_sitter(rel, language, text, query=query, kind=kind)
+            if ts_hits is not None:
+                return ts_hits
+        return self._match_regex(rel, language, text, query=query, kind=kind)
+
+    def _match_tree_sitter(
+        self, rel: str, language: str, text: str, *, query: str, kind: str | None
+    ) -> list[AstMatch] | None:
+        try:
+            from devcouncil.indexing.ts_imports import extract_symbols
+
+            hits = extract_symbols(language, text)
+        except Exception:
+            return None
+        if hits is None:
+            return None
+        results: list[AstMatch] = []
+        q = query.lower() if query else ""
+        for symbol_kind, symbol_name, lineno, source in hits:
+            if kind and kind != symbol_kind:
+                continue
+            if q and q not in symbol_name.lower() and q not in source.lower():
+                continue
+            results.append(
+                AstMatch(rel, language, symbol_kind, symbol_name, lineno, source, "tree-sitter")
+            )
+        return sorted(results, key=lambda item: (item.path, item.line))
+
+    def _match_regex(
+        self, rel: str, language: str, text: str, *, query: str, kind: str | None
+    ) -> list[AstMatch]:
         pattern = self._SYMBOL_PATTERNS.get(language)
         if not pattern:
             return []
@@ -132,7 +165,9 @@ class AstMatcher:
                 continue
             if query and query.lower() not in symbol_name.lower() and query.lower() not in line.lower():
                 continue
-            results.append(AstMatch(rel, language, symbol_kind, symbol_name, lineno, line.strip(), self._engine()))
+            results.append(
+                AstMatch(rel, language, symbol_kind, symbol_name, lineno, line.strip(), self._engine())
+            )
         return results
 
     def _match_python(self, rel: str, text: str, *, query: str, kind: str | None) -> list[AstMatch]:
@@ -175,4 +210,6 @@ class AstMatcher:
         return "function"
 
     def _engine(self) -> str:
+        # Python always uses the stdlib AST; other languages report tree-sitter when
+        # the optional extra is installed even if a given file fell back to regex.
         return "tree-sitter-optional" if self.tree_sitter_available else "fallback-ast"

package/src/devcouncil/indexing/graph/__init__.py

@@ -0,0 +1,78 @@
+"""Symbol-level code knowledge graph for DevCouncil repo mapping.
+
+Public entry points: :func:`build_code_graph`, :func:`refresh_map_for_paths`,
+:func:`load_code_graph`, :func:`query_symbol`, :func:`trace_path`, plus
+graph intelligence (:func:`enrich_graph_intel`, :func:`diff_impact`, …).
+"""
+
+from __future__ import annotations
+
+from devcouncil.indexing.graph.build import (
+    build_code_graph,
+    load_code_graph,
+    refresh_map_for_paths,
+    write_code_graph,
+)
+from devcouncil.indexing.graph.export import (
+    build_code_graph_okf,
+    export_graphml,
+    file_doc_rel,
+    write_code_graph_okf,
+)
+from devcouncil.indexing.graph.intel import (
+    blast_radius,
+    circular_imports,
+    compute_communities,
+    diff_impact,
+    enrich_graph_intel,
+    extract_processes,
+    god_nodes,
+    graph_check,
+)
+from devcouncil.indexing.graph.query import query_symbol, trace_path
+from devcouncil.indexing.graph.schema import (
+    SCHEMA_VERSION,
+    CodeGraph,
+    Confidence,
+    DeadCodeEntry,
+    GraphEdge,
+    GraphNode,
+    NodeKind,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "CodeGraph",
+    "Confidence",
+    "DeadCodeEntry",
+    "GraphEdge",
+    "GraphNode",
+    "NodeKind",
+    "blast_radius",
+    "build_code_graph",
+    "build_code_graph_okf",
+    "circular_imports",
+    "compute_communities",
+    "diff_impact",
+    "enrich_graph_intel",
+    "export_graphml",
+    "extract_processes",
+    "file_doc_rel",
+    "god_nodes",
+    "graph_check",
+    "load_code_graph",
+    "query_symbol",
+    "refresh_map_for_paths",
+    "trace_path",
+    "write_code_graph",
+    "write_code_graph_okf",
+]
+
+
+def __getattr__(name: str):
+    """Lazy OKF facade symbols (avoid import cycles with repo_mapper)."""
+    if name in {"build_graph_okf_bundle", "export_graph_okf", "graph_to_graphml"}:
+        from devcouncil.indexing.graph import okf_export
+
+        return getattr(okf_export, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")