devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/execution/prompt_builder.py

@@ -1,5 +1,4 @@
 import ast
-import json
 import logging
 import re
 from pathlib import Path
@@ -8,6 +7,7 @@ from typing import List
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.task import Task
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+from devcouncil.utils.json_persist import read_json
 
 logger = logging.getLogger(__name__)
 
@@ -22,6 +22,24 @@ MAX_SYMBOLS_PER_FILE = 40
 # lowest-priority ones are dropped (with a marker) if the whole prompt would exceed this.
 MAX_PROMPT_CHARS = 60_000
 
+# Appended to the instructions when the task classifies as HARD (see
+# devcouncil.verification.difficulty). Tells the executor up front that the
+# anti-laziness gates will block, so it does not discover strict mode via a
+# failed verify + repair loop. Kept compact — it rides in the never-dropped core.
+_HARD_TASK_RIGOR_SECTION = """
+## Rigor (this task is classified HARD — verification is strict)
+- No stubs, placeholders, or TODO/FIXME markers in added code: the verifier scans the
+  diff and BLOCKS on them. Intentional scaffolding requires the task description to
+  mention "scaffolding" AND the line to carry `devcouncil: allow-stub` (declared stubs
+  are surfaced for human review even when suppressed).
+- Every acceptance criterion needs a passing behavioral check; changed lines must be
+  exercised by the tests you run (diff coverage is enforced).
+- Do not claim completion without running the expected tests and seeing them pass.
+- Never delete, skip, or weaken a test to get to green.
+- If part of the task is genuinely infeasible, say so explicitly and state what is
+  missing instead of stubbing around it.
+"""
+
 # Rough chars-per-token for English/code; deliberately conservative so the derived
 # budget under-fills the window rather than over-fills it.
 _CHARS_PER_TOKEN = 4
@@ -36,13 +54,15 @@ _MIN_PROMPT_CHARS = 8_000
 def _local_context_window_budget(project_root: Path, cfg=None) -> int | None:
     """Char budget derived from a constrained local context window, or ``None``.
 
-    When the run targets the local Ollama provider with an explicit ``OLLAMA_NUM_CTX``,
-    the server silently truncates anything past that window — so a char-only budget that
-    ignores it lets the carefully-assembled prompt get cut off mid-stream. Returns a char
-    budget that fits the window (minus completion headroom) so :meth:`build_task_prompt`
-    can cap itself. Returns ``None`` for cloud providers / unset windows, leaving the
-    default behavior (and the large cloud CLIs' big windows) untouched. Best-effort:
-    any error degrades to ``None``.
+    When the run targets the local Ollama provider, the server silently truncates
+    anything past its context window — so a char-only budget that ignores it lets the
+    carefully-assembled prompt get cut off mid-stream. Returns a char budget that fits
+    the window the provider will actually request (``OLLAMA_NUM_CTX``, else the
+    provider's raised ``DEFAULT_NUM_CTX``), minus completion headroom, so
+    :meth:`build_task_prompt` can cap itself. Returns ``None`` for cloud providers and
+    for an explicit ``OLLAMA_NUM_CTX=0`` opt-out (server-default window, unknowable
+    here), leaving the default behavior untouched. Best-effort: any error degrades
+    to ``None``.
 
     ``cfg`` may be a pre-loaded config (loaded once per task by ``build_task_prompt``); when
     ``None`` it is loaded here so other callers keep working."""
@@ -61,8 +81,8 @@ def _local_context_window_budget(project_root: Path, cfg=None) -> int | None:
 
     num_ctx = OllamaProvider._resolve_num_ctx()
     if not num_ctx:
-        # No explicit window: Ollama uses a small default, but DevCouncil cannot know it.
-        # `dev doctor` already warns to set OLLAMA_NUM_CTX; don't guess a cap here.
+        # Explicit OLLAMA_NUM_CTX=0 opt-out: the server-default window applies and
+        # DevCouncil cannot know it; don't guess a cap here.
         return None
     usable_tokens = num_ctx - _RESERVED_COMPLETION_TOKENS
     if usable_tokens <= 0:
@@ -81,6 +101,7 @@ _LANG_BY_EXT = {
 class PromptBuilder:
     def __init__(self, project_root: Path = Path(".")):
         self.project_root = project_root
+        self._file_text_cache: dict[str, str] = {}
 
     @staticmethod
     def _lang_for(path: str) -> str:
@@ -101,7 +122,7 @@ class PromptBuilder:
         ``path``) so that if the file's content differs between the two reads, the outline
         is recomputed from the current text rather than served stale — and using the text
         directly (rather than its hash) means there is no collision risk."""
-        cache = getattr(self, "_outline_cache", None)
+        cache: dict[tuple[str, str], List[str]] | None = getattr(self, "_outline_cache", None)
         key = (path, text)
         if cache is not None and key in cache:
             return cache[key]
@@ -231,6 +252,7 @@ class PromptBuilder:
         new files are shown as headers only."""
         from devcouncil.utils.redaction import redact_string
 
+        self._file_text_cache.clear()
         blocks: List[str] = []
         budget = MAX_FILE_CONTEXT_CHARS
         omitted = 0
@@ -248,6 +270,7 @@ class PromptBuilder:
             except Exception:
                 blocks.append(f"### `{pf.path}` [{label}] — [error reading file]\n")
                 continue
+            self._file_text_cache[pf.path.replace("\\", "/")] = raw
             content = redact_string(raw)
             cap = min(MAX_PER_FILE_CHARS, budget)
             truncated = len(content) > cap
@@ -287,7 +310,7 @@ class PromptBuilder:
         if not map_path.exists():
             return None
         try:
-            data = json.loads(map_path.read_text(encoding="utf-8"))
+            data = read_json(map_path)
             return data if isinstance(data, dict) else None
         except Exception:
             return None
@@ -440,6 +463,185 @@ class PromptBuilder:
             )
         return design_block, knowledge_block
 
+    # Impact block bounds: this is a short, always-on summary — keep it tight so it can
+    # never crowd out the detailed file bodies it complements.
+    _IMPACT_MAX_FILES = 8
+    _IMPACT_MAX_DEPS = 5
+    _IMPACT_MAX_NEIGHBORS = 4
+
+    def _impact_section(self, task: Task, data: dict | None) -> str:
+        """A short "changing X touches Y" block sourced purely from ``repo_map.json``.
+
+        Unlike the optional code-review-graph structural section (which only appears when
+        that CLI is installed and enabled), this is ALWAYS emitted whenever the repo map
+        carries dependents or subsystem neighbors — so an agent always sees the blast
+        radius of its edits (who imports each changed file, and which neighboring
+        subsystems the change reaches) even on the common keyless path. Complements the
+        detailed ``_dependents_section``/``_call_sites_section`` with a one-line-per-file
+        orientation. When a code graph exists, also appends symbol-level inbound blast
+        (depth 1) for planned modify paths. Bounded and best-effort; never raises."""
+        if not data:
+            return ""
+        from devcouncil.indexing.subsystem_map import (
+            area_for_path,
+            dependents_of,
+            neighbors_for_area,
+        )
+
+        lines: List[str] = []
+        for pf in task.planned_files[: self._IMPACT_MAX_FILES]:
+            path = pf.path.replace("\\", "/")
+            is_new = pf.allowed_change == "create"
+            importers = [] if is_new else dependents_of(path, data)
+            area = area_for_path(path, data)
+            neighbors = neighbors_for_area(area, data)
+            if not importers and not neighbors and not area and not is_new:
+                continue
+            parts: List[str] = []
+            if importers:
+                shown = importers[: self._IMPACT_MAX_DEPS]
+                more = f" (+{len(importers) - len(shown)})" if len(importers) > len(shown) else ""
+                parts.append(
+                    f"imported by {len(importers)} file(s): "
+                    + ", ".join(f"`{p}`" for p in shown) + more
+                )
+            elif is_new:
+                parts.append("new file — plan its importer before finishing")
+            if area:
+                neighbor_txt = ""
+                if neighbors:
+                    shown_n = neighbors[: self._IMPACT_MAX_NEIGHBORS]
+                    neighbor_txt = "; neighbors: " + ", ".join(f"`{n}`" for n in shown_n)
+                parts.append(f"subsystem `{area}`{neighbor_txt}")
+            if parts:
+                lines.append(f"- `{path}` → " + "; ".join(parts))
+
+        graph_lines = self._graph_impact_lines(task)
+        if not lines and not graph_lines:
+            return ""
+        body = "\n".join(lines) if lines else ""
+        if graph_lines:
+            extra = "\n".join(graph_lines)
+            body = f"{body}\n{extra}" if body else extra
+        return (
+            "\n## Impact (changing X touches Y)\n"
+            "_From the repo map — keep these call sites and neighboring subsystems working, "
+            "or update them in scope._\n"
+            + body
+            + "\n"
+        )
+
+    def _graph_impact_lines(self, task: Task) -> List[str]:
+        """Optional symbol-level inbound blast (depth 1) from the code graph."""
+        try:
+            from devcouncil.indexing.graph.build import load_code_graph
+            from devcouncil.indexing.graph.intel import diff_impact
+
+            graph = load_code_graph(self.project_root)
+            if graph is None:
+                return []
+            paths = [
+                pf.path.replace("\\", "/")
+                for pf in task.planned_files[: self._IMPACT_MAX_FILES]
+                if pf.allowed_change != "create"
+            ]
+            if not paths:
+                return []
+            result = diff_impact(
+                self.project_root, graph, paths=paths, use_diff=False, max_depth=1
+            )
+            out: List[str] = []
+            for item in result.get("paths") or []:
+                layers = (item.get("blast") or {}).get("layers") or []
+                depth1 = next((L for L in layers if L.get("depth") == 1), None)
+                nodes = (depth1 or {}).get("nodes") or []
+                if not nodes:
+                    continue
+                shown = nodes[: self._IMPACT_MAX_DEPS]
+                more = f" (+{len(nodes) - len(shown)})" if len(nodes) > len(shown) else ""
+                out.append(
+                    f"- `{item['path']}` symbol callers (depth 1): "
+                    + ", ".join(f"`{n}`" for n in shown)
+                    + more
+                )
+            return out
+        except Exception:
+            logger.debug("graph impact lines skipped", exc_info=True)
+            return []
+
+    def _liveness_debt_section(self, task: Task, data: dict | None) -> str:
+        """Surface map unwired/dead-symbol candidates that overlap the task's subsystems."""
+        if not data:
+            return ""
+        try:
+            from devcouncil.indexing.subsystem_map import (
+                area_for_path,
+                areas_touched,
+                dead_symbol_candidates_of,
+                unreachable_of,
+                unwired_candidates_of,
+            )
+
+            planned = [pf.path.replace("\\", "/") for pf in task.planned_files]
+            task_areas = set(areas_touched(planned, data))
+            if not task_areas:
+                return ""
+
+            unwired_hits: list[str] = []
+            for cand in unwired_candidates_of(data)[:40]:
+                area = area_for_path(cand, data)
+                if area and area in task_areas:
+                    unwired_hits.append(cand)
+                if len(unwired_hits) >= 6:
+                    break
+
+            unreachable_hits: list[str] = []
+            roots = data.get("entry_roots") or []
+            unreachable_unreliable = (
+                data.get("liveness_unreachable_unreliable") is True
+                or not isinstance(roots, list)
+                or not roots
+            )
+            if not unreachable_unreliable:
+                for cand in unreachable_of(data)[:40]:
+                    area = area_for_path(cand, data)
+                    if area and area in task_areas:
+                        unreachable_hits.append(cand)
+                    if len(unreachable_hits) >= 6:
+                        break
+
+            dead_hits: list[str] = []
+            for cand in dead_symbol_candidates_of(data)[:40]:
+                path = cand.split(":", 1)[0]
+                area = area_for_path(path, data)
+                if area and area in task_areas:
+                    dead_hits.append(cand)
+                if len(dead_hits) >= 6:
+                    break
+
+            if not unwired_hits and not unreachable_hits and not dead_hits:
+                return ""
+            lines = [
+                "\n## Nearby liveness debt (from repo map)",
+                "_Existing unwired / unreachable files and unused symbols near your "
+                "subsystems — do not add to this debt; wire what you create._",
+                "_Verify same-task island rule: a new file imported only by other files "
+                "added in this task still needs a pre-existing non-test caller._",
+                "_Prefer `dev graph dead --confidence extracted` + greps; treat inferred "
+                "as unconfirmed. If entry_roots are empty / liveness_unreachable_unreliable, "
+                "ignore unreachable_files and mass inferred dead._",
+            ]
+            for p in unwired_hits:
+                lines.append(f"- unwired: `{p}`")
+            for p in unreachable_hits:
+                lines.append(f"- unreachable: `{p}`")
+            for p in dead_hits:
+                lines.append(f"- dead symbol: `{p}`")
+            return "\n".join(lines) + "\n"
+        except Exception:
+            logger.debug("liveness debt section skipped", exc_info=True)
+            return ""
+
     def _dependents_section(self, task: Task, data: dict | None) -> str:
         """List, per planned file the agent will change, the files that import it — the
         blast radius. Sourced from repo_map.json's precomputed reverse-import index, so
@@ -447,6 +649,9 @@ class PromptBuilder:
         dependents = (data or {}).get("dependents") or {}
         if not isinstance(dependents, dict) or not dependents:
             return ""
+        totals = (data or {}).get("dependents_total") or {}
+        if not isinstance(totals, dict):
+            totals = {}
         lines: List[str] = []
         for pf in task.planned_files:
             # New files have no dependents yet; only existing code carries blast radius.
@@ -455,18 +660,22 @@ class PromptBuilder:
             # Normalize the planned path to posix before the lookup — the map keys are
             # always posix, so a backslash planned path on Windows would otherwise miss
             # and silently drop the whole blast-radius entry (see _repo_map_section).
-            importers = dependents.get(pf.path.replace("\\", "/")) or []
+            key = pf.path.replace("\\", "/")
+            importers = dependents.get(key) or []
             if not importers:
                 continue
             shown = importers[:8]
-            more = f" (+{len(importers) - len(shown)} more)" if len(importers) > len(shown) else ""
+            full_n = int(totals.get(key) or len(importers))
+            hidden = max(0, full_n - len(shown))
+            more = f" (+{hidden} more; {full_n} total)" if hidden else ""
             lines.append(f"- `{pf.path}` is imported by: " + ", ".join(f"`{p}`" for p in shown) + more)
         if not lines:
             return ""
         return (
             "\n## Dependents (blast radius)\n"
             "_These files import the files you're changing — keep their call sites working, "
-            "or update them in scope._\n"
+            "or update them in scope. Counts may exceed the listed sample when the map "
+            "truncated dependents._\n"
             + "\n".join(lines)
             + "\n"
         )
@@ -515,10 +724,13 @@ class PromptBuilder:
             if not importers:
                 continue
             src_path = self.project_root / pf.path
-            try:
-                src_text = src_path.read_text(encoding="utf-8", errors="replace")
-            except Exception:
-                continue
+            key = pf.path.replace("\\", "/")
+            src_text = self._file_text_cache.get(key)
+            if src_text is None:
+                try:
+                    src_text = src_path.read_text(encoding="utf-8", errors="replace")
+                except Exception:
+                    continue
             symbols = self._exported_symbol_names(pf.path, src_text)
             if not symbols:
                 continue
@@ -526,10 +738,13 @@ class PromptBuilder:
             for importer in importers[: self._CALL_SITES_MAX_DEP_FILES]:
                 if emitted >= self._CALL_SITES_MAX_TOTAL:
                     break
-                try:
-                    dep_text = (self.project_root / importer).read_text(encoding="utf-8", errors="replace")
-                except Exception:
-                    continue
+                importer_key = importer.replace("\\", "/")
+                dep_text = self._file_text_cache.get(importer_key)
+                if dep_text is None:
+                    try:
+                        dep_text = (self.project_root / importer).read_text(encoding="utf-8", errors="replace")
+                    except Exception:
+                        continue
                 hits = 0
                 for lineno, raw in enumerate(dep_text.splitlines(), start=1):
                     if hits >= self._CALL_SITES_MAX_LINES_PER_FILE or emitted >= self._CALL_SITES_MAX_TOTAL:
@@ -630,7 +845,7 @@ class PromptBuilder:
             max_chars = MAX_PROMPT_CHARS
         # Per-task outline cache so a planned file's symbol outline is computed once even
         # though both the planned-files section and the call-sites section consume it.
-        self._outline_cache: dict[str, List[str]] = {}
+        self._outline_cache: dict[tuple[str, str], List[str]] = {}
         # Load the project config once and share it with the helpers that need it, instead
         # of each independently re-reading + re-parsing it. Best-effort: if it fails the
         # helpers fall back to loading it themselves (and degrade the same way).
@@ -705,10 +920,28 @@ class PromptBuilder:
    acceptance criteria require. Do NOT remove, rename, or alter the signature of an
    existing public symbol the task did not ask you to touch — verification flags an
    unrequested public-API change as scope drift and blocks it.
-5. Run the allowed commands to verify your work.
-6. Provide evidence of passing tests.
+5. Wire every created file and every new public symbol into its intended caller
+   (import, register, or call it) before claiming done. A file nothing imports, or a
+   public function nothing calls, fails verification. If the caller is outside the
+   current planned files, append it with `dev scope update <task_id> --lease-token
+   <token> --planned-file <caller>` (modify-op only), then edit.
+6. Run the allowed commands to verify your work.
+7. Provide evidence of passing tests.
 """
 
+        # Hard-task rigor: when the task classifies as hard, verification runs in
+        # strict mode (stub/effort gates block, diff coverage enforced). Saying so
+        # up front is cheaper than a repair loop after the fact.
+        try:
+            rigor_enabled = True if cfg is None else bool(cfg.verification.rigor.enabled)
+            if rigor_enabled:
+                from devcouncil.verification.difficulty import estimate_difficulty
+
+                if estimate_difficulty(task, requirements) == "hard":
+                    instructions += _HARD_TASK_RIGOR_SECTION
+        except Exception:
+            logger.debug("hard-task rigor section skipped", exc_info=True)
+
         # --- Optional context: fitted within the remaining budget, dropped lowest-
         # priority first. Priority: file contents (1) > structural (2) ~ dependents (2)
         # > skills (3); display order keeps the original reading sequence. ---
@@ -738,39 +971,51 @@ class PromptBuilder:
                 "text": f"\n{self._NO_MAP_NOTE}",
             })
 
+        # Always-on impact block ("changing X touches Y") from the repo map — present
+        # even when the code-review-graph CLI is absent (the common case). High priority
+        # (1) and short, so it survives all but the tightest budgets; ordered right after
+        # structural context so the agent sees the blast radius before the file bodies.
+        impact_text = self._impact_section(task, repo_map_data)
+        if impact_text:
+            segments.append({"order": 2, "priority": 1, "name": "impact", "text": impact_text})
+
+        liveness_text = self._liveness_debt_section(task, repo_map_data)
+        if liveness_text:
+            segments.append({"order": 2, "priority": 2, "name": "liveness debt", "text": liveness_text})
+
         files_text = self._planned_files_section(task)
         if files_text:
-            segments.append({"order": 2, "priority": 1, "name": "file contents", "text": files_text})
+            segments.append({"order": 3, "priority": 1, "name": "file contents", "text": files_text})
 
         dependents_section = self._dependents_section(task, repo_map_data)
         if dependents_section:
             prefix = f"\n{self._STALE_MAP_NOTE}" if (repo_map_stale and not struct_has_stale_note) else ""
-            segments.append({"order": 3, "priority": 2, "name": "dependents", "text": prefix + dependents_section})
+            segments.append({"order": 4, "priority": 2, "name": "dependents", "text": prefix + dependents_section})
 
         skills_text = self._skills_section(task)
         if skills_text:
-            segments.append({"order": 4, "priority": 3, "name": "engineering skills", "text": skills_text})
+            segments.append({"order": 5, "priority": 3, "name": "engineering skills", "text": skills_text})
 
         # Design system (a hard constraint for UI work) and OKF project knowledge. The
         # design system rides just above skills; OKF knowledge alongside them. Both are
         # bounded by config char budgets in `_knowledge_sections`.
         design_text, knowledge_text = self._knowledge_sections(task, cfg=cfg)
         if design_text:
-            segments.append({"order": 4, "priority": 2, "name": "design system", "text": design_text})
+            segments.append({"order": 5, "priority": 2, "name": "design system", "text": design_text})
         if knowledge_text:
-            segments.append({"order": 4, "priority": 3, "name": "project knowledge", "text": knowledge_text})
+            segments.append({"order": 5, "priority": 3, "name": "project knowledge", "text": knowledge_text})
 
         # Lowest priority (4): the budget drops call sites first. It only adds value once
         # the file bodies + dependents are present anyway.
         call_sites_text = self._call_sites_section(task, repo_map_data)
         if call_sites_text:
-            segments.append({"order": 5, "priority": 4, "name": "call sites", "text": call_sites_text})
+            segments.append({"order": 6, "priority": 4, "name": "call sites", "text": call_sites_text})
 
         # Lowest priority (5): dependency risks are opt-in, advisory context — the
         # budget drops them first so they never displace structural/file context.
         dependency_risks_text = self._dependency_risks_section(repo_map_data)
         if dependency_risks_text:
-            segments.append({"order": 6, "priority": 5, "name": "dependency risks", "text": dependency_risks_text})
+            segments.append({"order": 7, "priority": 5, "name": "dependency risks", "text": dependency_risks_text})
 
         # The core + instructions are never dropped; if they alone exceed the budget the
         # model's server will truncate them, so warn loudly instead of failing silently.