devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/knowledge/wiki_read.py

@@ -0,0 +1,87 @@
+"""Read-only wiki page lookup shared by CLI and MCP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def wiki_dir_for(root: Path) -> Path:
+    from devcouncil.knowledge.wiki import wiki_dir_for as _wiki_dir_for
+
+    return _wiki_dir_for(root)
+
+
+def _summary(doc: Any) -> dict[str, object]:
+    return {
+        "page": doc.rel_path,
+        "type": doc.type,
+        "title": doc.title,
+        "description": doc.description,
+        "tags": doc.tags,
+    }
+
+
+def read_wiki_page(
+    root: Path,
+    *,
+    page: str | None = None,
+    query: str | None = None,
+) -> dict[str, object]:
+    """Return MCP/CLI-compatible payload for wiki listing, page fetch, or search."""
+    from devcouncil.knowledge.okf import read_bundle
+
+    wiki_dir = wiki_dir_for(root)
+    if not (wiki_dir / "index.md").is_file():
+        return {
+            "ok": False,
+            "error": "No codebase wiki has been generated. Run `dev wiki update` to create it.",
+            "code": "not_found",
+        }
+
+    bundle = read_bundle(wiki_dir)
+    pages = {
+        doc.rel_path: doc
+        for doc in bundle.documents
+        if doc.rel_path not in ("log.md",)
+    }
+
+    if page:
+        doc = pages.get(page.strip())
+        if doc is None:
+            return {
+                "ok": False,
+                "error": f"Wiki page {page!r} not found.",
+                "code": "not_found",
+                "available": sorted(pages),
+            }
+        return {"ok": True, **_summary(doc), "body": doc.body, "truncated": False}
+
+    if query:
+        terms = [term for term in query.lower().split() if term]
+        scored: list[tuple[int, Any]] = []
+        for doc in pages.values():
+            haystack = " ".join([doc.title, doc.description, " ".join(doc.tags), doc.rel_path]).lower()
+            hits = sum(1 for term in terms if term in haystack)
+            if hits:
+                scored.append((hits, doc))
+        scored.sort(key=lambda item: (-item[0], item[1].rel_path))
+        matches = [doc for _, doc in scored[:5]]
+        if not matches:
+            return {
+                "ok": True,
+                "query": query,
+                "matches": [],
+                "available": [_summary(doc) for doc in pages.values()],
+            }
+        top = matches[0]
+        return {
+            "ok": True,
+            "query": query,
+            "matches": [_summary(doc) for doc in matches],
+            **_summary(top),
+            "body": top.body,
+            "truncated": False,
+        }
+
+    return {"ok": True, "pages": [_summary(doc) for doc in pages.values()]}

package/src/devcouncil/live/cards.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 import hashlib
-import json
 import re
 from dataclasses import dataclass
 from pathlib import Path
 
 from devcouncil.live.models import AgentTurn, CardStatus, CritiqueCard, Verdict
+from devcouncil.utils.json_persist import read_model_json, write_model_json
 
 RISK_TERMS = (
     "skip tests",
@@ -239,7 +239,7 @@ def save_card(project_root: Path, card: CritiqueCard) -> Path:
     cards_dir = project_root / ".devcouncil" / "live" / "cards"
     cards_dir.mkdir(parents=True, exist_ok=True)
     path = cards_dir / f"{card.id}.json"
-    path.write_text(card.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    write_model_json(path, card)
     return path
 
 
@@ -254,7 +254,7 @@ def load_cards(project_root: Path) -> list[CritiqueCard]:
     cards: list[CritiqueCard] = []
     for path in sorted(cards_dir.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True):
         try:
-            cards.append(CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8"))))
+            cards.append(read_model_json(path, CritiqueCard))
         except Exception:
             continue
     return cards
@@ -305,7 +305,7 @@ def load_card_by_id(project_root: Path, card_id: str) -> CritiqueCard | None:
     if not path.exists():
         return None
     try:
-        return CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8")))
+        return read_model_json(path, CritiqueCard)
     except Exception:
         return None
 
@@ -319,9 +319,9 @@ def update_card_status(project_root: Path, card_id: str, status: CardStatus) ->
     path = cards_dir / f"{card_id}.json"
     if not path.exists():
         return None
-    card = CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8")))
+    card = read_model_json(path, CritiqueCard)
     updated = card.model_copy(update={"status": status})
-    path.write_text(updated.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    write_model_json(path, updated)
     return updated
 
 
@@ -334,7 +334,7 @@ def unresolved_blocking_cards(
     source = cards if cards is not None else load_cards(project_root)
     return [
         card for card in source
-        if card.status == "open" and card.verdict == "Critical Issues"
+        if card.status == "open" and card.blocks_completion
         and (task_id is None or card.task_id in {None, task_id})
     ]
 

package/src/devcouncil/live/models.py

@@ -53,10 +53,13 @@ class CritiqueCard(BaseModel):
     status: CardStatus = "open"
     created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
     source_path: str | None = None
+    # When False the card is advisory (``dev run``/``dev e2e``); only ``dev watch`` cards
+    # with blocks_gate=True may block verification.
+    blocks_gate: bool = True
 
     @property
     def blocks_completion(self) -> bool:
-        return self.verdict == "Critical Issues"
+        return self.verdict == "Critical Issues" and self.blocks_gate
 
 
 def session_id_from_path(path: Path) -> str:

package/src/devcouncil/live/reviewer.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import logging
 from pathlib import Path
 
@@ -23,12 +24,21 @@ class LiveReviewService:
         project_root: Path,
         client: str = "generic",
         use_llm: bool = False,
+        task_id: str | None = None,
     ) -> CritiqueCard:
-        fallback = review_turn(turn, project_root, client=client)
+        fallback = review_turn(turn, project_root, client=client, task_id=task_id)
         if not use_llm or self.router is None:
             logger.debug("Live review (deterministic) for %s turn=%s: %s", client, turn.turn_id, fallback.verdict)
             return fallback
 
+        # Ground the model in the task's RECORDED verification state. Without this
+        # the reviewer sees only the agent's prose and reliably hallucinates
+        # "provides no evidence of implementation" against code whose acceptance
+        # criteria DevCouncil has already proven with executed checks (observed:
+        # a benchmark task blocked at 4/4 hidden-test correctness because the
+        # ungrounded reviewer critiqued the agent's summary message).
+        grounding_block = self._grounding_block(project_root, task_id)
+
         prompt = f"""
 You are DevCouncil's live coding-agent reviewer.
 Review the latest assistant response before the developer follows it.
@@ -43,6 +53,14 @@ Return a critique card with:
 Do not praise. Do not review formatting. Focus on correctness, missing requirements, architectural drift,
 unsafe commands, weak evidence, and premature completion claims.
 
+Rules for the verdict:
+- The response text is a SUMMARY, not the work itself. Never conclude "no code change /
+  no evidence" from the response alone — the recorded verification state below (when
+  present) is the authoritative account of the work.
+- "Critical Issues" requires a concrete, checkable problem: a claim contradicted by the
+  recorded state, an unsafe command, or a missing requirement — never vagueness, brevity,
+  style, or your estimate of the agent's effort.
+{grounding_block}
 Client: {client}
 Session: {turn.session_id}
 Turn: {turn.turn_id}
@@ -51,30 +69,43 @@ Assistant response:
 {turn.content}
 """
         samples = self._samples(project_root)
-        cards: list[CritiqueCard] = []
-        for attempt in range(samples):
+
+        async def _one_sample(attempt: int) -> CritiqueCard | None:
+            if self.router is None:
+                return None
             # Vary temperature so independent samples actually differ (and so the router
             # cache returns distinct generations). Attempt 0 stays deterministic.
             temperature = 0.0 if attempt == 0 else min(0.8, 0.3 + 0.2 * attempt)
             try:
-                cards.append(await self.router.complete_structured(
+                return await self.router.complete_structured(
                     role=self.role,
                     messages=[{"role": "user", "content": prompt}],
                     schema=CritiqueCard,
                     temperature=temperature,
-                ))
+                )
             except ValueError:
                 try:
-                    cards.append(await self.router.complete_structured(
+                    return await self.router.complete_structured(
                         role="implementation_reviewer",
                         messages=[{"role": "user", "content": prompt}],
                         schema=CritiqueCard,
                         temperature=temperature,
-                    ))
+                    )
                 except Exception:
-                    continue
+                    return None
             except Exception:
-                continue
+                return None
+
+        # The samples are independent by construction (no sample reads another's
+        # output), so gather them concurrently instead of awaiting one at a time.
+        # Order is preserved (attempt 0's deterministic card stays first) and each
+        # sample keeps its own error handling above; return_exceptions only shields
+        # siblings from anything that still escapes, which the filter then drops.
+        results = await asyncio.gather(
+            *(_one_sample(attempt) for attempt in range(samples)),
+            return_exceptions=True,
+        )
+        cards: list[CritiqueCard] = [card for card in results if isinstance(card, CritiqueCard)]
 
         if not cards:
             logger.warning("Live review produced no cards for %s turn=%s; using deterministic fallback", client, turn.turn_id)
@@ -93,10 +124,58 @@ Assistant response:
             "source_path": fallback.source_path,
         })
 
+    @staticmethod
+    def _grounding_block(project_root: Path, task_id: str | None) -> str:
+        """Render the task's recorded verification state for the review prompt.
+
+        Best-effort: no task id / no DB / unknown task yields an empty block and
+        the model reviews ungrounded (the deterministic fallback stays grounded
+        via ``review_turn``)."""
+        try:
+            from devcouncil.live.cards import _load_task_grounding
+
+            grounding = _load_task_grounding(project_root, task_id)
+        except Exception:
+            grounding = None
+        if grounding is None:
+            return ""
+        if grounding.is_satisfied:
+            corroboration = (
+                "This state CORROBORATES a completion claim: do not demand further "
+                "evidence and do not raise Critical Issues about proof — the "
+                "executable evidence already exists in DevCouncil's records."
+            )
+        else:
+            corroboration = (
+                "This state does NOT yet corroborate a completion claim: if the "
+                "response claims success, that mismatch is the concern to raise "
+                "(cite the numbers above)."
+            )
+        return f"""
+Recorded verification state for task {grounding.task_id} (authoritative — measured from
+executed checks and the artifact graph, not taken from the agent's words):
+- task status: {grounding.status}
+- blocking gaps: {grounding.blocking_gaps}
+- failing verification commands: {grounding.failing_commands}
+- acceptance criteria with passing evidence: {grounding.acs_passing}/{grounding.acs_total}
+{corroboration}
+"""
+
     def _samples(self, project_root: Path) -> int:
         try:
-            from devcouncil.app.config import load_config
-            return max(1, load_config(project_root).verification.reviewer_checks.samples)
+            from devcouncil.app.config import load_config, role_runs_on_local_provider
+
+            cfg = load_config(project_root)
+            # Auto-tune by reviewer locality: a cost-free local (Ollama) reviewer votes
+            # over 3 independent samples (outvoting a lone mis-calibrated verdict); a
+            # paid cloud reviewer stays single-shot. Explicit config always wins —
+            # but an explicitly single-shot LOCAL reviewer is flagged, never silent.
+            local_reviewer = role_runs_on_local_provider(cfg, "live_reviewer")
+            from devcouncil.telemetry.logging_setup import warn_once
+
+            for warning in cfg.verification.reviewer_checks.unsafe_override_warnings(local_reviewer):
+                warn_once(logger, warning)  # _samples() runs per review; warn once
+            return cfg.verification.reviewer_checks.resolved(local_reviewer)
         except Exception:
             return 1
 

package/src/devcouncil/live/signals.py

@@ -8,6 +8,8 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
+from devcouncil.utils.json_persist import read_json, write_model_json
+
 
 class ReviewSignal(BaseModel):
     client: str = "generic"
@@ -47,7 +49,7 @@ def write_signal(project_root: Path, client: str, payload: dict[str, Any]) -> Pa
     digest = hashlib.sha256(key.encode("utf-8", errors="replace")).hexdigest()[:12]
     path = directory / f"{client.lower()}-{digest}.json"
     signal.path = str(path)
-    path.write_text(signal.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    write_model_json(path, signal)
     return path
 
 
@@ -58,7 +60,7 @@ def load_signals(project_root: Path) -> list[ReviewSignal]:
     signals: list[ReviewSignal] = []
     for path in sorted(directory.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True):
         try:
-            raw = json.loads(path.read_text(encoding="utf-8"))
+            raw = read_json(path)
             signal = ReviewSignal.model_validate(raw)
             signal.path = str(path)
             signals.append(signal)

package/src/devcouncil/live/tasks.py

@@ -3,16 +3,25 @@ from __future__ import annotations
 from pathlib import Path
 
 from devcouncil.storage.db import get_db
+from devcouncil.storage.native import TaskLeaseRepository
 from devcouncil.storage.repositories import TaskRepository
 
 
 def active_task_id(project_root: Path) -> str | None:
-    """Return the single running DevCouncil task ID, if one is unambiguous."""
+    """Return the single active DevCouncil task ID, if one is unambiguous.
+
+    Prefers a task in ``running`` status. When none are running, falls back to the
+    task behind exactly one non-expired active lease (``dev checkout`` path).
+    """
     db = get_db(project_root)
     if not db:
         return None
     with db.get_session() as session:
         running = [task for task in TaskRepository(session).get_all() if task.status == "running"]
-    if len(running) != 1:
+        if len(running) == 1:
+            return running[0].id
+        leases = TaskLeaseRepository(session).list_leases(active_only=True)
+        active = [lease for lease, expired in leases if not expired]
+        if len(active) == 1:
+            return active[0].task_id
         return None
-    return running[0].id

package/src/devcouncil/live/transcripts.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import json
+import shutil
 from pathlib import Path
 from typing import Any, Iterable, Literal
 
 from devcouncil.live.models import AgentSession, AgentTurn, session_id_from_path
+from devcouncil.utils.json_persist import read_json
 
 RoleName = Literal["user", "assistant", "system", "tool", "unknown"]
 KNOWN_ROLES: set[RoleName] = {"user", "assistant", "system", "tool"}
@@ -86,11 +88,76 @@ def latest_assistant_turn(path: Path, client: str = "generic") -> AgentTurn | No
     return result
 
 
+def claude_project_slug(project_root: Path | str) -> str:
+    """Encode a path the way Claude Code names dirs under ``~/.claude/projects/``."""
+    resolved = Path(project_root).expanduser().resolve()
+    return resolved.as_posix().replace("/", "-")
+
+
+def _read_claude_session_id(project_root: Path, task_id: str | None) -> str | None:
+    if not task_id:
+        return None
+    path = project_root / ".devcouncil" / "sessions" / f"{task_id}-claude.json"
+    if not path.is_file():
+        return None
+    try:
+        data = read_json(path) or {}
+    except (json.JSONDecodeError, OSError):
+        return None
+    session_id = str(data.get("session_id") or "").strip()
+    return session_id or None
+
+
+def claude_transcript_for_session(project_root: Path, session_id: str) -> Path | None:
+    """Return the native Claude JSONL for ``session_id`` in this project, if present."""
+    if not session_id:
+        return None
+    slug_dir = CLAUDE_TRANSCRIPT_ROOT / claude_project_slug(project_root)
+    direct = slug_dir / f"{session_id}.jsonl"
+    if direct.is_file():
+        return direct
+    for candidate in _claude_transcript_candidates(project_root):
+        if candidate.stem == session_id:
+            return candidate
+    return None
+
+
+def claude_transcript_for_task(project_root: Path, task_id: str) -> Path | None:
+    """Resolve the Claude transcript DevCouncil pinned for ``task_id``."""
+    session_id = _read_claude_session_id(project_root, task_id)
+    if session_id:
+        path = claude_transcript_for_session(project_root, session_id)
+        if path is not None:
+            return path
+    return None
+
+
+def mirror_claude_transcript(project_root: Path, session_id: str) -> Path | None:
+    """Copy the native Claude JSONL into ``.devcouncil/live/claude/`` for discovery.
+
+    Headless ``dev run``/``dev e2e`` pins a session id up front; mirroring the native
+    transcript into the project makes live review resilient even when Claude's global
+    project slug is slow to appear or ``discover_sessions`` would otherwise race."""
+    source = claude_transcript_for_session(project_root, session_id)
+    if source is None or not source.is_file():
+        return None
+    dest_dir = project_root / ".devcouncil" / "live" / "claude"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / f"{session_id}.jsonl"
+    try:
+        shutil.copy2(source, dest)
+    except OSError:
+        return None
+    return dest
+
+
 def _claude_transcript_candidates(project_root: Path) -> list[Path]:
     local_runtime = project_root / ".devcouncil" / "live" / "claude"
     candidates = list(local_runtime.glob("*.jsonl"))
     if CLAUDE_TRANSCRIPT_ROOT.exists():
-        candidates.extend(CLAUDE_TRANSCRIPT_ROOT.rglob("*.jsonl"))
+        slug_dir = CLAUDE_TRANSCRIPT_ROOT / claude_project_slug(project_root)
+        if slug_dir.is_dir():
+            candidates.extend(slug_dir.glob("*.jsonl"))
     # Dedup, then sort by path for a deterministic, stat-free order. discover_sessions
     # re-sorts the resulting sessions by mtime; because that sort is stable, giving it a
     # deterministic input keeps the tie-break (equal-mtime sessions) stable across runs —
@@ -144,7 +211,7 @@ def _role(raw: dict[str, Any]) -> RoleName:
         if isinstance(nested, str):
             return nested if nested in KNOWN_ROLES else "unknown"
     record_type = raw.get("type")
-    if record_type in KNOWN_ROLES:
+    if isinstance(record_type, str) and record_type in KNOWN_ROLES:
         return record_type
     return "unknown"
 

package/src/devcouncil/llm/cache.py

@@ -4,6 +4,7 @@ import logging
 from pathlib import Path
 from typing import Optional
 from devcouncil.llm.provider import LLMResponse
+from devcouncil.utils.json_persist import read_json, write_json
 
 logger = logging.getLogger(__name__)
 
@@ -33,10 +34,9 @@ class LLMCache:
         cache_file = self.cache_dir / f"{key}.json"
         if cache_file.exists():
             try:
-                with open(cache_file, "r") as f:
-                    data = json.load(f)
-                    logger.debug("LLM cache HIT model=%s key=%s", model, key[:12])
-                    return LLMResponse(**data)
+                data = read_json(cache_file)
+                logger.debug("LLM cache HIT model=%s key=%s", model, key[:12])
+                return LLMResponse(**data)
             except Exception as e:
                 logger.warning("LLM cache read failed for key=%s: %s", key[:12], e)
         logger.debug("LLM cache MISS model=%s key=%s", model, key[:12])
@@ -45,6 +45,5 @@ class LLMCache:
     def set(self, model: str, messages: list, temp: float, json_mode: bool, response: LLMResponse, provider_fingerprint: str = "", cache_key: Optional[str] = None):
         key = cache_key if cache_key is not None else self._get_key(model, messages, temp, json_mode, provider_fingerprint)
         cache_file = self.cache_dir / f"{key}.json"
-        with open(cache_file, "w") as f:
-            json.dump(response.model_dump(), f)
+        write_json(cache_file, response.model_dump())
         logger.debug("LLM cache STORE model=%s key=%s", model, key[:12])

package/src/devcouncil/llm/model_defaults.yaml

@@ -1,14 +1,14 @@
 openrouter:
-  spec_writer: anthropic/claude-sonnet-4.6
-  prompt_enhancer: anthropic/claude-sonnet-4.6
-  planner_a: anthropic/claude-sonnet-4.6
-  planner_b: google/gemini-2.5-pro
-  critic_a: openai/gpt-5.5
-  critic_b: anthropic/claude-opus-4.8
-  arbiter: openai/gpt-5.5
-  native_agent: anthropic/claude-sonnet-4.6
-  implementation_reviewer: openai/gpt-5.5
-  live_reviewer: openai/gpt-5.5
+  spec_writer: qwen/qwen3-max
+  prompt_enhancer: qwen/qwen3-max
+  planner_a: qwen/qwen3-max
+  planner_b: qwen/qwen3-max
+  critic_a: qwen/qwen3-max
+  critic_b: qwen/qwen3-max
+  arbiter: qwen/qwen3-max
+  native_agent: qwen/qwen3-max
+  implementation_reviewer: qwen/qwen3-max
+  live_reviewer: qwen/qwen3-max
 vertexai:
   spec_writer: google/gemini-2.5-flash
   prompt_enhancer: google/gemini-2.5-flash