devcouncil 0.2.0 → 0.3.0

package/src/devcouncil/knowledge/sources.py

@@ -0,0 +1,239 @@
+"""Knowledge sources: discover and select OKF / design.md context for prompts.
+
+A :class:`KnowledgeSource` is the prompt-facing view of an ingested knowledge file. It
+mirrors :class:`devcouncil.skills.registry.Skill` — same frontmatter contract, same
+trigger-based selection and relevance ranking — so OKF bundles and a project design system
+flow into planning/council/task prompts through the existing budget-aware machinery.
+
+On-disk layout (under the project root)::
+
+    .devcouncil/knowledge/
+        design/design.md        # one design system, always selected
+        okf/*.md                # ingested OKF documents, selected by trigger/keyword
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from devcouncil.knowledge.frontmatter import split_frontmatter
+from devcouncil.skills.registry import SkillTriggers, _keyword_in_text
+
+KNOWLEDGE_DIR = ".devcouncil/knowledge"
+
+Kind = Literal["okf", "design"]
+
+
+class KnowledgeSource(BaseModel):
+    name: str
+    kind: Kind
+    description: str = ""
+    always: bool = False
+    triggers: SkillTriggers = Field(default_factory=SkillTriggers)
+    body: str = ""
+    priority: int = 50
+    source_path: Path | None = None
+
+    def _match_and_score(self, goal_lower: str) -> tuple[bool, int]:
+        """Whether this source applies to ``goal_lower`` and its relevance rank, in one
+        keyword scan. Unlike a Skill, ``matches`` is NOT equivalent to ``score > 0`` here:
+        OKF sources have a nonzero ``priority`` floor, so the two must be returned together."""
+        if self.always:
+            return True, 1_000_000 + self.priority
+        hits = sum(1 for kw in self.triggers.keywords if _keyword_in_text(kw, goal_lower))
+        return hits > 0, self.priority + 5 * hits
+
+    def matches(self, goal: str) -> bool:
+        """True if this source applies to the given goal text.
+
+        Design systems are always-on (a coding agent should always honor them); OKF
+        knowledge is matched on goal keywords like a domain skill.
+        """
+        return self._match_and_score(goal.lower())[0]
+
+    def relevance_score(self, goal: str) -> int:
+        return self._match_and_score(goal.lower())[1]
+
+    def render(self) -> str:
+        """A titled markdown block for inclusion in a prompt preamble."""
+        header = f"## {self.description or self.name}".rstrip()
+        return f"{header}\n\n{self.body.strip()}".strip()
+
+
+# Parsed-source cache keyed on (resolved path, mtime_ns, kind, always, priority). Knowledge
+# discovery runs once per task during planning (and repeatedly via MCP), so without this an
+# N-task plan re-reads + re-parses every knowledge file N times. Keyed on mtime so an edited
+# or freshly-ingested file is re-parsed; the args are in the key because they shape the
+# resulting source. Cached sources are read-only (callers only match/score/render them).
+_source_cache: dict[tuple[str, int, str, bool, int], KnowledgeSource] = {}
+_SOURCE_CACHE_MAX = 512
+
+# Directory-scan cache for discover_knowledge_sources(). The glob/rglob filesystem walk
+# repeats 5-30x per planning session (once per task, plus MCP calls) over a directory tree
+# that almost never changes mid-session, while per-file PARSING is already memoized by
+# _source_cache. This caches the discovered source *list* keyed on the call's shaping args.
+# Each entry also stores a signature: the sorted set of (resolved-path, mtime_ns) for every
+# scanned file. On the next call we recompute that signature (a cheap stat per file vs. the
+# directory walk + frontmatter parse) and invalidate if it differs, so a freshly written,
+# edited, added or removed file is picked up. Keying on the path set (not just mtimes) means
+# add/remove is detected even if the filesystem's mtime granularity is too coarse to notice
+# an in-place rewrite within the same tick. Cached lists are read-only to callers.
+_DiscoverKey = tuple[str, str, bool, int, int]
+_DiscoverSig = tuple[tuple[str, int], ...]
+_discover_cache: dict[_DiscoverKey, tuple[_DiscoverSig, list[KnowledgeSource]]] = {}
+_DISCOVER_CACHE_MAX = 256
+
+
+def clear_knowledge_caches() -> None:
+    """Drop the cached parsed knowledge sources (useful in long-running processes/tests)."""
+    _source_cache.clear()
+    _discover_cache.clear()
+
+
+def _source_from_file(path: Path, kind: Kind, always: bool, priority: int) -> KnowledgeSource:
+    try:
+        key: tuple[str, int, str, bool, int] | None = (
+            str(path.resolve()), path.stat().st_mtime_ns, kind, always, priority,
+        )
+    except OSError:
+        key = None
+    if key is not None:
+        cached = _source_cache.get(key)
+        if cached is not None:
+            return cached
+    source = _parse_source_file(path, kind, always, priority)
+    if key is not None:
+        if len(_source_cache) >= _SOURCE_CACHE_MAX:
+            _source_cache.clear()
+        _source_cache[key] = source
+    return source
+
+
+def _parse_source_file(path: Path, kind: Kind, always: bool, priority: int) -> KnowledgeSource:
+    meta, body = split_frontmatter(path.read_text(encoding="utf-8"))
+    triggers = meta.get("triggers") or {}
+    # Derive keywords from explicit triggers and, for OKF, the document's tags — so an
+    # OKF doc tagged [sales, revenue] fires on goals mentioning those domains for free.
+    keywords = list(triggers.get("keywords") or [])
+    if kind == "okf":
+        tags = meta.get("tags") or []
+        if isinstance(tags, str):
+            tags = [tags]
+        keywords.extend(str(t) for t in tags)
+    description = str(meta.get("description") or meta.get("title") or meta.get("type") or path.stem)
+    return KnowledgeSource(
+        name=str(meta.get("name") or path.stem),
+        kind=kind,
+        description=description,
+        always=always,
+        triggers=SkillTriggers(keywords=keywords, globs=list(triggers.get("globs") or [])),
+        body=body.strip(),
+        priority=priority,
+        source_path=path,
+    )
+
+
+def discover_knowledge_sources(
+    project_root: Path,
+    directory: str = KNOWLEDGE_DIR,
+    design_always: bool = True,
+    design_priority: int = 80,
+    okf_priority: int = 50,
+) -> list[KnowledgeSource]:
+    """Find ingested knowledge under ``<project_root>/<directory>/{design,okf}``."""
+    base = project_root / directory
+    # Collect the files to ingest (the directory walk we want to cache), as
+    # (path, kind, always, priority) in stable order, before parsing any of them.
+    scanned: list[tuple[Path, Kind, bool, int]] = []
+    design_dir = base / "design"
+    if design_dir.exists():
+        for path in sorted(design_dir.glob("*.md")):
+            scanned.append((path, "design", design_always, design_priority))
+    okf_dir = base / "okf"
+    if okf_dir.exists():
+        for path in sorted(okf_dir.rglob("*.md")):
+            # Skip OKF index files: they are navigation, not knowledge worth injecting.
+            if path.name.lower() == "index.md":
+                continue
+            scanned.append((path, "okf", False, okf_priority))
+
+    # Signature of the current scan: (resolved path, mtime_ns) for each file. A miss here
+    # (file added/removed/edited) invalidates the cached list for this key.
+    sig_parts: list[tuple[str, int]] = []
+    for path, _kind, _always, _priority in scanned:
+        try:
+            sig_parts.append((str(path.resolve()), path.stat().st_mtime_ns))
+        except OSError:
+            # Vanished between glob and stat: skip from the signature; parsing handles it.
+            continue
+    signature: _DiscoverSig = tuple(sig_parts)
+
+    key: _DiscoverKey = (
+        str(project_root.resolve()), directory, design_always, design_priority, okf_priority,
+    )
+    cached = _discover_cache.get(key)
+    if cached is not None and cached[0] == signature:
+        return cached[1]
+
+    sources = [
+        _source_from_file(path, kind, always, priority)
+        for path, kind, always, priority in scanned
+    ]
+    if len(_discover_cache) >= _DISCOVER_CACHE_MAX:
+        _discover_cache.clear()
+    _discover_cache[key] = (signature, sources)
+    return sources
+
+
+def select_knowledge_sources(
+    goal: str = "",
+    project_root: Path | None = None,
+    directory: str = KNOWLEDGE_DIR,
+    design_always: bool = True,
+) -> list[KnowledgeSource]:
+    """Select and rank the knowledge sources that apply to ``goal``.
+
+    Always-on design sources sort first; OKF sources follow, ranked by relevance. Returns
+    an empty list when nothing is ingested.
+    """
+    if project_root is None:
+        return []
+    sources = discover_knowledge_sources(project_root, directory, design_always=design_always)
+    # One goal.lower() + one keyword scan per source (match and rank computed together).
+    goal_lower = goal.lower()
+    scored: list[tuple[KnowledgeSource, int]] = []
+    for source in sources:
+        ok, score = source._match_and_score(goal_lower)
+        if ok:
+            scored.append((source, score))
+    scored.sort(key=lambda item: (not item[0].always, -item[1], item[0].name))
+    return [source for source, _ in scored]
+
+
+def render_knowledge_preamble(
+    sources: list[KnowledgeSource],
+    max_chars: int = 6000,
+    kind: Kind | None = None,
+) -> str:
+    """Concatenate source bodies (optionally filtered to one ``kind``) into a single
+    preamble, bounded to ``max_chars`` total. Sources are taken in the order given (so the
+    most relevant survive the budget); the first source is always included."""
+    separator = "\n\n---\n\n"
+    chosen = [s for s in sources if kind is None or s.kind == kind]
+    blocks: list[str] = []
+    total = 0
+    for source in chosen:
+        block = source.render()
+        if not block:
+            continue
+        # Count the separator that will join this block to the previous one, so the budget
+        # bounds the *rendered* preamble length, not just the sum of block bodies.
+        extra = len(separator) if blocks else 0
+        if blocks and total + extra + len(block) > max_chars:
+            break
+        blocks.append(block)
+        total += extra + len(block)
+    return separator.join(blocks).strip()

package/src/devcouncil/live/cards.py

@@ -299,11 +299,19 @@ def filter_cards(
     return filtered, None, None
 
 
+def load_card_by_id(project_root: Path, card_id: str) -> CritiqueCard | None:
+    """Read a single card directly by id, avoiding a scan of every card file."""
+    path = card_path(project_root, card_id)
+    if not path.exists():
+        return None
+    try:
+        return CritiqueCard.model_validate(json.loads(path.read_text(encoding="utf-8")))
+    except Exception:
+        return None
+
+
 def get_card(project_root: Path, card_id: str) -> CritiqueCard | None:
-    for card in load_cards(project_root):
-        if card.id == card_id:
-            return card
-    return None
+    return load_card_by_id(project_root, card_id)
 
 
 def update_card_status(project_root: Path, card_id: str, status: CardStatus) -> CritiqueCard | None:
@@ -317,9 +325,15 @@ def update_card_status(project_root: Path, card_id: str, status: CardStatus) ->
     return updated
 
 
-def unresolved_blocking_cards(project_root: Path, task_id: str | None = None) -> list[CritiqueCard]:
+def unresolved_blocking_cards(
+    project_root: Path,
+    task_id: str | None = None,
+    *,
+    cards: list[CritiqueCard] | None = None,
+) -> list[CritiqueCard]:
+    source = cards if cards is not None else load_cards(project_root)
     return [
-        card for card in load_cards(project_root)
+        card for card in source
         if card.status == "open" and card.verdict == "Critical Issues"
         and (task_id is None or card.task_id in {None, task_id})
     ]

package/src/devcouncil/live/repair_prompt.py

@@ -8,8 +8,16 @@ from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import RequirementRepository, TaskRepository
 
 
-def build_live_repair_prompt(project_root: Path, card: CritiqueCard) -> str:
-    """Build a ready-to-paste repair prompt for a live-review critique card."""
+def build_live_repair_prompt(
+    project_root: Path,
+    card: CritiqueCard,
+    requirements: list | None = None,
+) -> str:
+    """Build a ready-to-paste repair prompt for a live-review critique card.
+
+    ``requirements`` may be pre-fetched (e.g. by the bulk builder) to avoid
+    re-querying every requirement once per card. ``None`` fetches them as before.
+    """
     prompt = [
         f"# Repair Live Review Card {card.id}",
         "",
@@ -34,7 +42,7 @@ def build_live_repair_prompt(project_root: Path, card: CritiqueCard) -> str:
     if card.message_for_agent:
         prompt.extend(["", "## Message For Agent", card.message_for_agent])
 
-    task_prompt = _task_prompt(project_root, card.task_id)
+    task_prompt = _task_prompt(project_root, card.task_id, requirements=requirements)
     if task_prompt:
         prompt.extend(["", "## Original DevCouncil Task Contract", task_prompt])
 
@@ -59,17 +67,31 @@ def build_bulk_live_repair_prompt(project_root: Path, cards: list[CritiqueCard])
         "",
         f"DevCouncil found {len(cards)} blocking live-review card(s). Address each card below.",
     ]
+    requirements = _load_all_requirements(project_root)
     for index, card in enumerate(cards, start=1):
         sections.extend([
             "",
             f"---\n\n## Card {index}: {card.id}",
             "",
-            build_live_repair_prompt(project_root, card).strip(),
+            build_live_repair_prompt(project_root, card, requirements=requirements).strip(),
         ])
     return "\n".join(sections).rstrip() + "\n"
 
 
-def _task_prompt(project_root: Path, task_id: str | None) -> str | None:
+def _load_all_requirements(project_root: Path) -> list | None:
+    """Fetch all requirements once; returns None when no DB is available."""
+    db = get_db(project_root)
+    if not db:
+        return None
+    with db.get_session() as session:
+        return RequirementRepository(session).get_all()
+
+
+def _task_prompt(
+    project_root: Path,
+    task_id: str | None,
+    requirements: list | None = None,
+) -> str | None:
     if not task_id:
         return None
     db = get_db(project_root)
@@ -79,5 +101,6 @@ def _task_prompt(project_root: Path, task_id: str | None) -> str | None:
         task = TaskRepository(session).get_by_id(task_id)
         if not task:
             return None
-        requirements = RequirementRepository(session).get_all()
+        if requirements is None:
+            requirements = RequirementRepository(session).get_all()
     return PromptBuilder(project_root).build_task_prompt(task, requirements)

package/src/devcouncil/live/reviewer.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 
 from devcouncil.live.cards import review_turn
 from devcouncil.live.models import AgentTurn, CritiqueCard
 from devcouncil.llm.router import ModelRouter
 
+logger = logging.getLogger(__name__)
+
 
 class LiveReviewService:
     """Reviews coding-agent responses with deterministic or model-backed critique cards."""
@@ -23,6 +26,7 @@ class LiveReviewService:
     ) -> CritiqueCard:
         fallback = review_turn(turn, project_root, client=client)
         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
 
         prompt = f"""
@@ -46,21 +50,41 @@ Turn: {turn.turn_id}
 Assistant response:
 {turn.content}
 """
-        try:
-            reviewed = await self.router.complete_structured(
-                role=self.role,
-                messages=[{"role": "user", "content": prompt}],
-                schema=CritiqueCard,
-            )
-        except ValueError:
-            reviewed = await self.router.complete_structured(
-                role="implementation_reviewer",
-                messages=[{"role": "user", "content": prompt}],
-                schema=CritiqueCard,
-            )
-        except Exception:
+        samples = self._samples(project_root)
+        cards: list[CritiqueCard] = []
+        for attempt in range(samples):
+            # 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(
+                    role=self.role,
+                    messages=[{"role": "user", "content": prompt}],
+                    schema=CritiqueCard,
+                    temperature=temperature,
+                ))
+            except ValueError:
+                try:
+                    cards.append(await self.router.complete_structured(
+                        role="implementation_reviewer",
+                        messages=[{"role": "user", "content": prompt}],
+                        schema=CritiqueCard,
+                        temperature=temperature,
+                    ))
+                except Exception:
+                    continue
+            except Exception:
+                continue
+
+        if not cards:
+            logger.warning("Live review produced no cards for %s turn=%s; using deterministic fallback", client, turn.turn_id)
             return fallback
 
+        reviewed = self._vote(cards)
+        logger.info(
+            "Live review (LLM, %d sample(s)) for %s turn=%s: %s",
+            len(cards), client, turn.turn_id, reviewed.verdict,
+        )
         return reviewed.model_copy(update={
             "id": fallback.id,
             "session_id": turn.session_id,
@@ -68,3 +92,38 @@ Assistant response:
             "client": client,
             "source_path": fallback.source_path,
         })
+
+    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)
+        except Exception:
+            return 1
+
+    @staticmethod
+    def _vote(cards: list[CritiqueCard]) -> CritiqueCard:
+        """Majority-vote the verdict across independent reviews, then return a card whose
+        verdict matches the vote (so its concerns/evidence are consistent).
+
+        A single review is returned as-is. With several, the BLOCKING verdict
+        ("Critical Issues") is chosen only on a strict majority, and "Approved" likewise;
+        anything else de-escalates to the non-blocking "Concerns". This prevents a lone
+        mis-calibrated reviewer from blocking, without ever auto-approving a real concern."""
+        if len(cards) == 1:
+            return cards[0]
+        from collections import Counter
+
+        counts = Counter(card.verdict for card in cards)
+        threshold = len(cards) / 2
+        if counts.get("Critical Issues", 0) > threshold:
+            verdict = "Critical Issues"
+        elif counts.get("Approved", 0) > threshold:
+            verdict = "Approved"
+        else:
+            verdict = "Concerns"
+        # Return a representative card with the voted verdict so concerns/evidence align;
+        # fall back to the first card if none matches (then override just the verdict).
+        for card in cards:
+            if card.verdict == verdict:
+                return card
+        return cards[0].model_copy(update={"verdict": verdict})

package/src/devcouncil/live/summary.py

@@ -12,8 +12,21 @@ def live_review_summary(project_root: Path, task_id: str | None = None) -> dict:
     signals = load_signals(project_root)
     active_id = active_task_id(project_root)
     scoped_task_id = task_id or active_id
-    blockers = unresolved_blocking_cards(project_root, task_id=scoped_task_id)
+    blockers = unresolved_blocking_cards(project_root, task_id=scoped_task_id, cards=cards)
     pending_signal_items = [signal.model_dump() for signal in signals]
+    open_count = 0
+    resolved_count = 0
+    ignored_count = 0
+    critical_open_count = 0
+    for card in cards:
+        if card.status == "open":
+            open_count += 1
+            if card.verdict == "Critical Issues":
+                critical_open_count += 1
+        elif card.status == "resolved":
+            resolved_count += 1
+        elif card.status == "ignored":
+            ignored_count += 1
     return {
         "active_task_id": active_id,
         "scope_task_id": scoped_task_id,
@@ -21,13 +34,10 @@ def live_review_summary(project_root: Path, task_id: str | None = None) -> dict:
         "pending_signal_items": pending_signal_items[:10],
         "cards": {
             "total": len(cards),
-            "open": len([card for card in cards if card.status == "open"]),
-            "resolved": len([card for card in cards if card.status == "resolved"]),
-            "ignored": len([card for card in cards if card.status == "ignored"]),
-            "critical_open": len([
-                card for card in cards
-                if card.status == "open" and card.verdict == "Critical Issues"
-            ]),
+            "open": open_count,
+            "resolved": resolved_count,
+            "ignored": ignored_count,
+            "critical_open": critical_open_count,
         },
         "blocking_cards": [card.model_dump() for card in blockers],
         "recent_cards": [card.model_dump() for card in cards[:5]],

package/src/devcouncil/live/transcripts.py

@@ -31,9 +31,19 @@ def discover_sessions(project_root: Path, client: str = "claude") -> list[AgentS
             client=client,
             transcript_path=str(path),
             updated_at=str(stat.st_mtime),
-            turns=sum(1 for _ in _safe_lines(path)),
+            # len() over the already-materialized splitlines list avoids a
+            # second Python-level pass and matches the previous line count.
+            turns=len(_safe_lines(path)),
         ))
-    return sorted(sessions, key=lambda item: item.updated_at or "", reverse=True)
+    def _updated_key(item: AgentSession) -> float:
+        # updated_at is a stringified mtime; sort numerically so timestamps with
+        # different digit counts (string sort would misorder them) compare correctly.
+        try:
+            return float(item.updated_at or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+
+    return sorted(sessions, key=_updated_key, reverse=True)
 
 
 def load_turns(path: Path, client: str = "generic") -> list[AgentTurn]:
@@ -50,22 +60,45 @@ def load_turns(path: Path, client: str = "generic") -> list[AgentTurn]:
     return turns
 
 
-def latest_assistant_turn(path: Path, client: str = "generic") -> AgentTurn | None:
+# mtime-keyed cache: reloading and reversing every turn just to find the last
+# assistant message is wasteful when the transcript hasn't changed.
+_LATEST_ASSISTANT_CACHE: dict[str, tuple[float, AgentTurn | None]] = {}
+
+
+def _scan_latest_assistant_turn(path: Path, client: str) -> AgentTurn | None:
     for turn in reversed(load_turns(path, client=client)):
         if turn.role == "assistant":
             return turn
     return None
 
 
+def latest_assistant_turn(path: Path, client: str = "generic") -> AgentTurn | None:
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return _scan_latest_assistant_turn(path, client)
+    key = f"{path}\x00{client}"
+    cached = _LATEST_ASSISTANT_CACHE.get(key)
+    if cached is not None and cached[0] == mtime:
+        return cached[1]
+    result = _scan_latest_assistant_turn(path, client)
+    _LATEST_ASSISTANT_CACHE[key] = (mtime, result)
+    return result
+
+
 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"))
-    return sorted(set(candidates), key=lambda path: path.stat().st_mtime if path.exists() else 0, reverse=True)
+    # 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 —
+    # whereas an unordered set would let ties reorder run to run.
+    return sorted(set(candidates))
 
 
-def _safe_lines(path: Path) -> Iterable[str]:
+def _safe_lines(path: Path) -> list[str]:
     try:
         return path.read_text(encoding="utf-8", errors="replace").splitlines()
     except OSError:

package/src/devcouncil/llm/cache.py

@@ -1,9 +1,12 @@
 import json
 import hashlib
+import logging
 from pathlib import Path
 from typing import Optional
 from devcouncil.llm.provider import LLMResponse
 
+logger = logging.getLogger(__name__)
+
 class LLMCache:
     def __init__(self, project_root: Path):
         self.cache_dir = project_root / ".devcouncil" / "cache" / "llm"
@@ -23,20 +26,25 @@ class LLMCache:
         s = json.dumps(data, sort_keys=True)
         return hashlib.sha256(s.encode("utf-8")).hexdigest()
 
-    def get(self, model: str, messages: list, temp: float, json_mode: bool, provider_fingerprint: str = "") -> Optional[LLMResponse]:
-        key = self._get_key(model, messages, temp, json_mode, provider_fingerprint)
+    def get(self, model: str, messages: list, temp: float, json_mode: bool, provider_fingerprint: str = "", cache_key: Optional[str] = None) -> Optional[LLMResponse]:
+        # Hashing the JSON payload is non-trivial; let callers compute the key once
+        # (via ``_get_key``) and pass it to both get() and set() to avoid recomputing.
+        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"
         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)
-            except Exception:
-                pass
+            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])
         return None
 
-    def set(self, model: str, messages: list, temp: float, json_mode: bool, response: LLMResponse, provider_fingerprint: str = ""):
-        key = self._get_key(model, messages, temp, json_mode, provider_fingerprint)
+    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)
+        logger.debug("LLM cache STORE model=%s key=%s", model, key[:12])