arkaos 4.22.0 → 4.23.0

package/core/governance/kb_cite_check.py

@@ -20,6 +20,15 @@ from dataclasses import dataclass
 
 _WIKILINK_PATTERN: re.Pattern[str] = re.compile(r"\[\[([^\[\]]+)\]\]")
 _KNOWLEDGE_PATTERN: re.Pattern[str] = re.compile(r"\[knowledge:", re.IGNORECASE)
+# Graphify knowledge-graph citation: the `[graph:` marker ONLY (parallel to
+# `[knowledge:`), which stands for a node actually returned by the graph.
+# The tool NAME is deliberately excluded: naming a tool is narration, not
+# evidence, and the literal `mcp__graphify__query_graph` appears in the
+# KB-first pointer of every migrated SKILL.md — crediting it would let any
+# response that merely echoes the doctrine self-certify. Same asymmetry as
+# `mcp__obsidian`, which is a topic keyword and earns credit only via a real
+# `[[wikilink]]`.
+_GRAPHIFY_PATTERN: re.Pattern[str] = re.compile(r"\[graph:", re.IGNORECASE)
 # File:line — requires at least one path separator. Quantifiers are bounded
 # to prevent catastrophic backtracking on pathological input (PR18 security
 # review: unbounded variant blew past Stop's 5s budget by ~8x on 100KB of
@@ -41,8 +50,8 @@ _ARKAOS_KEYWORDS: frozenset[str] = frozenset({
     "ines", "rafael", "beatriz", "miguel", "rodrigo",
     "non-negotiable", "tier 0", "squad lead",
     "core/governance", "core/synapse", "core/cognition",
-    "core/workflow", "mcp__obsidian", "kb-first",
-    "departments/", "agent yaml", "obsidian vault",
+    "core/workflow", "mcp__obsidian", "mcp__graphify", "kb-first",
+    "departments/", "agent yaml", "obsidian vault", "graphify",
 })
 
 _BYPASS_DEFAULTS: tuple[str, ...] = ("[arka:trivial]",)
@@ -50,8 +59,8 @@ _TRIVIAL_WORD_THRESHOLD: int = 15
 _TOPIC_THRESHOLD: float = 0.4
 _SUGGESTION_TEXT: str = (
     "KB-first — last response had no citation on ArkaOS topic. "
-    "Use @[[note-name]], /kb search, or mcp__obsidian__search_notes "
-    "to ground the next answer."
+    "Use @[[note-name]], /kb search, mcp__obsidian__search_notes, or "
+    "mcp__graphify__query_graph to ground the next answer."
 )
 
 
@@ -111,13 +120,14 @@ def _is_trivial_length(text: str) -> bool:
 def _count_citations(text: str) -> int:
     # Truncate to _MAX_SCAN_CHARS first; the file-line regex is the only
     # backtracking-prone pattern and the bounded quantifiers (capped at 8
-    # segments × 64 chars each) combined with this slice make all three
+    # segments x 64 chars each) combined with this slice make all three
     # patterns safe to run unconditionally below.
     scan = text if len(text) <= _MAX_SCAN_CHARS else text[:_MAX_SCAN_CHARS]
     wikilinks = len(_WIKILINK_PATTERN.findall(scan))
     knowledge = 1 if _KNOWLEDGE_PATTERN.search(scan) else 0
+    graphify = 1 if _GRAPHIFY_PATTERN.search(scan) else 0
     files = len(_FILE_LINE_PATTERN.findall(scan))
-    return wikilinks + knowledge + files
+    return wikilinks + knowledge + graphify + files
 
 
 def _compute_topic_score(text: str, keywords: frozenset[str]) -> float:

package/core/governance/stop_lint.py

@@ -84,6 +84,29 @@ def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess | None:
         return None
 
 
+def _porcelain_entries(stdout: str) -> list[tuple[str, str]]:
+    """(status, path) pairs from ``git status --porcelain -z`` output.
+
+    ``-z`` terminates entries with NUL and never quotes paths (the
+    line-based form octal-escapes non-ASCII and quoted names, which
+    broke path matching). Rename/copy entries carry a second
+    NUL-separated field — the original path — which is skipped.
+    """
+    entries: list[tuple[str, str]] = []
+    tokens = stdout.split("\0")
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        index += 1
+        if len(token) < 4:
+            continue
+        status, path = token[:2], token[3:]
+        if status[0] in "RC":
+            index += 1  # skip the original-path field
+        entries.append((status, path))
+    return entries
+
+
 def changed_files(project_dir: Path) -> list[str]:
     """Repo-relative files changed vs the merge-base, plus untracked."""
     try:
@@ -93,15 +116,15 @@ def changed_files(project_dir: Path) -> list[str]:
     if base is None:
         return []
     out: list[str] = []
-    diff = _git(["diff", "--name-only", base], project_dir)
+    diff = _git(["diff", "--name-only", "-z", base], project_dir)
     if diff is not None and diff.returncode == 0:
-        out.extend(f.strip() for f in diff.stdout.splitlines() if f.strip())
-    status = _git(["status", "--porcelain"], project_dir)
+        out.extend(f for f in diff.stdout.split("\0") if f.strip())
+    status = _git(["status", "--porcelain", "-z"], project_dir)
     if status is not None and status.returncode == 0:
         out.extend(
-            line[3:].strip()
-            for line in status.stdout.splitlines()
-            if line.startswith("??") and line[3:].strip()
+            path
+            for entry_status, path in _porcelain_entries(status.stdout)
+            if entry_status == "??" and path.strip()
         )
     seen: set[str] = set()
     return [f for f in out if not (f in seen or seen.add(f))]
@@ -109,7 +132,7 @@ def changed_files(project_dir: Path) -> list[str]:
 
 def _fingerprint(project_dir: Path) -> str | None:
     head = _git(["rev-parse", "HEAD"], project_dir)
-    status = _git(["status", "--porcelain"], project_dir)
+    status = _git(["status", "--porcelain", "-z"], project_dir)
     if head is None or head.returncode != 0 or status is None:
         return None
     digest = hashlib.sha1()
@@ -117,9 +140,9 @@ def _fingerprint(project_dir: Path) -> str | None:
     # Porcelain alone only says WHICH files are dirty — editing an
     # already-dirty file leaves it unchanged. Fold in mtime+size so
     # content edits re-arm the worker.
-    for line in sorted(status.stdout.splitlines()):
-        digest.update(line.encode("utf-8", "replace"))
-        digest.update(_stat_token(project_dir / line[3:].strip()))
+    for entry_status, path in sorted(_porcelain_entries(status.stdout)):
+        digest.update(f"{entry_status} {path}".encode("utf-8", "replace"))
+        digest.update(_stat_token(project_dir / path))
     return digest.hexdigest()
 
 
@@ -151,9 +174,13 @@ def _remember_fingerprint(state_file: Path, fingerprint: str) -> None:
     prev_umask = os.umask(0o077)
     try:
         state_file.parent.mkdir(parents=True, exist_ok=True)
-        state_file.write_text(
+        # Atomic tmp+replace: a crash mid-write must never leave a
+        # truncated state file behind (the reorganizer report pattern).
+        tmp_file = state_file.with_suffix(f".tmp-{os.getpid()}")
+        tmp_file.write_text(
             json.dumps({"fingerprint": fingerprint}), encoding="utf-8"
         )
+        os.replace(tmp_file, state_file)
     except OSError:
         pass
     finally:

package/core/governance/stop_lint_telemetry.py

@@ -34,7 +34,9 @@ class StopLintSummary:
     runs: int
     skipped_runs: int
     lint_pass_rate: float
-    typecheck_pass_rate: float
+    # None when no run observed the check (typecheck is opt-in) —
+    # distinct from 0.0, which means "observed and failing".
+    typecheck_pass_rate: float | None
     would_block_rate: float
     corrupt_line_count: int = 0
 
@@ -119,7 +121,7 @@ def _build_summary(
         runs=len(rows),
         skipped_runs=len(rows) - len(observed),
         lint_pass_rate=_true_rate(observed, "lint_passed"),
-        typecheck_pass_rate=_true_rate(observed, "typecheck_passed"),
+        typecheck_pass_rate=_true_rate_or_none(observed, "typecheck_passed"),
         would_block_rate=_true_rate(observed, "would_block"),
         corrupt_line_count=corrupt,
     )
@@ -130,3 +132,10 @@ def _true_rate(rows: list[dict[str, Any]], key: str) -> float:
     if not observed:
         return 0.0
     return sum(1 for r in observed if r[key] is True) / len(observed)
+
+
+def _true_rate_or_none(rows: list[dict[str, Any]], key: str) -> float | None:
+    """Like ``_true_rate`` but honest about zero observations."""
+    if not any(isinstance(r.get(key), bool) for r in rows):
+        return None
+    return _true_rate(rows, key)

package/core/hooks/user_prompt_submit.py

@@ -36,7 +36,6 @@ import subprocess
 import time
 from pathlib import Path
 
-from core.shared.temp_paths import arkaos_temp_dir
 from core.hooks._shared import (
     ensure_root_on_path,
     get_str,
@@ -45,6 +44,7 @@ from core.hooks._shared import (
     resolve_arkaos_root,
     safe_session_id,
 )
+from core.shared.temp_paths import arkaos_temp_dir
 
 _CACHE_DIR = arkaos_temp_dir("arkaos-context-cache")
 _CACHE_TTL = 300  # Constitution cache: 5 minutes
@@ -89,13 +89,14 @@ _WF_VERB_PATTERN = (
 )
 _WF_VERB_RE = re.compile(rf"\b{_WF_VERB_PATTERN}\b", re.IGNORECASE)
 
-_STOPWORDS = frozenset(
-    "the a an and or but if then of for to in on at by with from is are was "
-    "were be been being do does did have has had this that these those it "
-    "its as i you we they he she them my your our their so not no yes can "
-    "will would could should may might must need want fix make use get set "
-    "add remove".split()
-)
+_STOPWORDS = frozenset([
+    "the", "a", "an", "and", "or", "but", "if", "then", "of", "for", "to", "in", "on",
+    "at", "by", "with", "from", "is", "are", "was", "were", "be", "been", "being", "do",
+    "does", "did", "have", "has", "had", "this", "that", "these", "those", "it", "its",
+    "as", "i", "you", "we", "they", "he", "she", "them", "my", "your", "our", "their",
+    "so", "not", "no", "yes", "can", "will", "would", "could", "should", "may", "might",
+    "must", "need", "want", "fix", "make", "use", "get", "set", "add", "remove"
+])
 
 _VAGUE_PHRASES = (
     "fix the bug", "that file", "the error",
@@ -228,7 +229,14 @@ def _run_bridge(root: str, user_input: str, session_id: str, cwd: str = "") -> s
                 payload["cwd"] = cwd
             output, code = module.run_bridge(payload, Path(root))
         if code == 0:
-            return str(output.get("context_string", ""))
+            parts = [str(output.get("context_string", ""))]
+            # Full-text blocks follow the compact tag line. A tag such as
+            # `[kb-context:5 +graph]` announces an injection; without these
+            # the announcement was all the model ever received.
+            blocks = output.get("content_blocks") or []
+            if isinstance(blocks, list):
+                parts.extend(str(b) for b in blocks if b)
+            return "\n".join(p for p in parts if p)
     except Exception:
         pass
     return ""
@@ -251,10 +259,6 @@ def _workflow_tag() -> str:
     workflow = str(state.get("workflow", "") or "")
     branch = str(state.get("branch", "") or "")
     violations = len(state.get("violations", []) or [])
-    total = len(phases)
-    completed = sum(
-        1 for p in phases.values() if p.get("status") == "completed"
-    )
     current = next(
         (k for k, p in phases.items() if p.get("status") == "in_progress"),
         "none",
@@ -334,10 +338,8 @@ def _l0_constitution() -> str:
                 return cache_file.read_text(encoding="utf-8")
     except OSError:
         pass
-    try:
+    with contextlib.suppress(OSError):
         cache_file.write_text(_L0_FALLBACK, encoding="utf-8")
-    except OSError:
-        pass
     return _L0_FALLBACK
 
 
@@ -501,10 +503,8 @@ def _one_shot_nudge(subdir: str, session_id: str) -> str:
             nudge = f"[arka:suggest] {suggestion}"
     except (OSError, json.JSONDecodeError, ValueError):
         pass
-    try:
+    with contextlib.suppress(OSError):
         nudge_file.unlink(missing_ok=True)
-    except OSError:
-        pass
     return nudge
 
 
@@ -548,10 +548,8 @@ def main(stdin_json: dict | None = None, raw: str = "") -> int:
 
     root = resolve_arkaos_root()
     ensure_root_on_path(root)
-    try:
+    with contextlib.suppress(OSError):
         _CACHE_DIR.mkdir(parents=True, exist_ok=True)
-    except OSError:
-        pass
 
     # Claude Code sends the user's text under "prompt" (UserPromptSubmit
     # hook schema); "userInput"/"message" cover other runtimes. Missing
@@ -683,4 +681,4 @@ if __name__ == "__main__":
     except Exception:
         # Fail open with the minimal constitution context.
         print(json.dumps({"additionalContext": _L0_FALLBACK}))
-        raise SystemExit(0)
+        raise SystemExit(0) from None

package/core/synapse/engine.py

@@ -13,8 +13,8 @@ import time
 from dataclasses import dataclass, field
 from typing import Any
 
-from core.synapse.layers import Layer, LayerResult, PromptContext
 from core.synapse.cache import LayerCache
+from core.synapse.layers import Layer, LayerResult, PromptContext
 
 
 @dataclass
@@ -27,6 +27,12 @@ class SynapseResult:
     total_tokens_est: int  # Estimated total tokens injected
     cache_stats: dict  # Cache hit/miss statistics
     layers_skipped: int  # Layers that returned empty results
+    # Full-text blocks from layers whose content is richer than their tag
+    # (L2.5 KB context, graph context). Kept separate from context_string so
+    # the compact tag line stays compact; the hook appends these after it.
+    # Before this existed, LayerResult.content had NO consumer — every block a
+    # layer built was discarded while its tag still advertised the injection.
+    content_blocks: list[str] = field(default_factory=list)
 
 
 class SynapseEngine:
@@ -44,11 +50,11 @@ class SynapseEngine:
     def register_layer(self, layer: Layer) -> None:
         """Register a context layer. Layers execute in priority order."""
         self._layers.append(layer)
-        self._layers.sort(key=lambda l: l.priority)
+        self._layers.sort(key=lambda x: x.priority)
 
     def remove_layer(self, layer_id: str) -> None:
         """Remove a layer by ID."""
-        self._layers = [l for l in self._layers if l.id != layer_id]
+        self._layers = [x for x in self._layers if x.id != layer_id]
 
     def get_layer(self, layer_id: str) -> Layer | None:
         """Get a layer by ID."""
@@ -70,10 +76,13 @@ class SynapseEngine:
         results: list[LayerResult] = []
         skipped = 0
 
+        block_layers: set[str] = set()
         for layer in self._layers:
             result = self._compute_layer(layer, ctx)
             if result.tag or result.content:
                 results.append(result)
+                if layer.emits_block:
+                    block_layers.add(layer.id)
             else:
                 skipped += 1
 
@@ -81,6 +90,15 @@ class SynapseEngine:
         tags = [r.tag for r in results if r.tag]
         context_string = " ".join(tags)
 
+        # Full-text blocks — OPT-IN via Layer.emits_block. Collecting on
+        # `content != tag` instead swept up every layer whose content is its
+        # tag's value ("dev", "active", "feat/plan-canvas"), injecting stray
+        # unlabeled lines into every prompt for zero added information.
+        content_blocks = [
+            r.content for r in results
+            if r.content and r.layer_id in block_layers
+        ]
+
         total_tokens = sum(r.tokens_est for r in results)
         total_ms = int((time.time() - start) * 1000)
 
@@ -105,6 +123,7 @@ class SynapseEngine:
             total_tokens_est=total_tokens,
             cache_stats=self._cache.stats,
             layers_skipped=skipped,
+            content_blocks=content_blocks,
         )
 
     def _compute_layer(self, layer: Layer, ctx: PromptContext) -> LayerResult:
@@ -125,15 +144,23 @@ class SynapseEngine:
             session_id = (ctx.extra or {}).get("session_id", "default")
             cache_key += f":{session_id}"
 
-        # Check cache
+        # Check cache. The stored value is `tag` alone, or `tag\x00content`
+        # whenever content differs from tag: replaying the tag as the content
+        # would feed a marker to the model in place of what it advertises.
+        # This condition is deliberately WIDER than `emits_block` — the cache
+        # round-trips content faithfully for every layer (AgentLayer stores
+        # `[agent:x disc:y]\x00x` and is no block at all); only the block
+        # channel in inject() is opt-in.
         if layer.cache_ttl > 0:
             cached = self._cache.get(cache_key)
             if cached is not None:
+                tag, _, content = cached.partition("\x00")
+                content = content or tag
                 return LayerResult(
                     layer_id=layer.id,
-                    tag=cached,
-                    content=cached,
-                    tokens_est=len(cached.split()),
+                    tag=tag,
+                    content=content,
+                    tokens_est=len(content.split()),
                     compute_ms=0,
                     cached=True,
                 )
@@ -143,7 +170,10 @@ class SynapseEngine:
 
         # Cache if TTL > 0 and result is non-empty
         if layer.cache_ttl > 0 and result.tag:
-            self._cache.set(cache_key, result.tag, layer.cache_ttl)
+            stored = result.tag
+            if result.content and result.content != result.tag:
+                stored = f"{result.tag}\x00{result.content}"
+            self._cache.set(cache_key, stored, layer.cache_ttl)
 
         return result
 
@@ -188,21 +218,21 @@ def create_default_engine(
     Returns:
         Configured SynapseEngine ready to use.
     """
+    from core.synapse.agent_experiences_layer import AgentExperiencesLayer
+    from core.synapse.graph_context_layer import GraphContextLayer
     from core.synapse.layers import (
-        ConstitutionLayer,
-        DepartmentLayer,
         AgentLayer,
-        ProjectLayer,
         BranchLayer,
         CommandHintsLayer,
-        QualityGateLayer,
-        KnowledgeRetrievalLayer,
-        KBContextLayer,
+        ConstitutionLayer,
+        DepartmentLayer,
         ForgeContextLayer,
+        KBContextLayer,
+        KnowledgeRetrievalLayer,
+        ProjectLayer,
+        QualityGateLayer,
         SessionContextLayer,
     )
-    from core.synapse.agent_experiences_layer import AgentExperiencesLayer
-    from core.synapse.graph_context_layer import GraphContextLayer
     from core.synapse.pattern_library_layer import PatternLibraryLayer
     from core.synapse.recipe_layer import RecipeLayer
     from core.synapse.routing_feedback_layer import RoutingFeedbackLayer

package/core/synapse/graph_context_layer.py

@@ -26,7 +26,7 @@ import json
 import os
 import time
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from core.synapse.layers import Layer, LayerResult, PromptContext
 from core.synapse.pattern_library_layer import _extract_keywords
@@ -58,7 +58,7 @@ def _graph_flag_on() -> bool:
     return bool(synapse_cfg.get("graphContext", True))
 
 
-def _locate_graph(cwd: str) -> Optional[Path]:
+def _locate_graph(cwd: str) -> Path | None:
     """Find ``graphify-out/graph.json`` in cwd or up to 3 parent dirs."""
     if not cwd:
         return None
@@ -149,6 +149,11 @@ class GraphContextLayer(Layer):
     def cache_ttl(self) -> int:
         return 30
 
+    @property
+    def emits_block(self) -> bool:
+        """Content is the self-naming [arka:graph-context:N] block."""
+        return True
+
     @property
     def priority(self) -> int:
         return 26  # right after L2.5 KBContext (25), before ProjectLayer (30)

package/core/synapse/kb_cache.py

@@ -20,6 +20,7 @@ Turn-scoped marker (record_obsidian_query / read_obsidian_query):
       as core.workflow.marker_cache).
 """
 
+import contextlib
 import hashlib
 import json
 import os
@@ -27,12 +28,11 @@ import threading
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from core.shared import safe_session_id as _safe_session_id_module
 from core.shared.temp_paths import arkaos_temp_dir
 
-
 # Re-export for backward compatibility with any external importers.
 SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
 KB_QUERY_MARKER_DIR = arkaos_temp_dir("arkaos-kb-query")
@@ -147,8 +147,8 @@ class KBSessionCache:
     def __init__(
         self,
         session_id: str,
-        project_path: Optional[str] = None,
-        cache_dir: Optional[str] = None,
+        project_path: str | None = None,
+        cache_dir: str | None = None,
         max_entries: int = 150,
         ttl_seconds: int = 5400,
     ) -> None:
@@ -278,8 +278,8 @@ class KBSessionCache:
 
     def retrieve(
         self,
-        query: Optional[str] = None,
-        topics: Optional[set[str]] = None,
+        query: str | None = None,
+        topics: set[str] | None = None,
         threshold: float = 0.3,
     ) -> list[dict]:
         """Retrieve cached knowledge by query or topic overlap.
@@ -433,11 +433,44 @@ def _kb_query_dir() -> Path:
     return KB_QUERY_MARKER_DIR
 
 
-def _kb_query_path(session_id: str) -> Optional[Path]:
+def _kb_query_path(session_id: str, kind: str = "obsidian") -> Path | None:
+    """Turn-scoped marker path for one KB source.
+
+    ``kind`` separates the sources so a graphify consult cannot satisfy a
+    check that asked about Obsidian, or vice versa. "obsidian" keeps the
+    historical unsuffixed filename so existing records stay readable.
+    """
     safe = _safe_session_id_module.safe_session_id(session_id)
     if safe is None:
         return None
-    return _kb_query_dir() / f"{safe}.json"
+    suffix = "" if kind == "obsidian" else f".{kind}"
+    return _kb_query_dir() / f"{safe}{suffix}.json"
+
+
+def record_graphify_query(session_id: str, query: str, hit_count: int = 0) -> None:
+    """Record that a Graphify graph query ran in this turn.
+
+    Counterpart to :func:`record_obsidian_query`. Without it the ``[graph:``
+    citation marker is pure narration — anyone can type ``[graph: MadeUpNode]``
+    and earn credit (QG review). A consumer that wants evidence rather than a
+    claim should require :func:`graphify_queried_this_turn` alongside it.
+    """
+    _record_query(session_id, query, hit_count, kind="graphify")
+
+
+def read_graphify_query(session_id: str) -> dict | None:
+    """Return the turn-scoped Graphify-query record, or None if absent."""
+    return _read_query(session_id, kind="graphify")
+
+
+def graphify_queried_this_turn(session_id: str) -> bool:
+    """True iff ``record_graphify_query`` was called since turn start."""
+    return read_graphify_query(session_id) is not None
+
+
+def invalidate_graphify_query(session_id: str) -> None:
+    """Clear the per-turn Graphify consult marker. Idempotent."""
+    _invalidate_query(session_id, kind="graphify")
 
 
 def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> None:
@@ -455,7 +488,12 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         query: The query string that was executed.
         hit_count: Number of notes returned (0 means search ran but empty).
     """
-    path = _kb_query_path(session_id)
+    _record_query(session_id, query, hit_count, kind="obsidian")
+
+
+def _record_query(session_id: str, query: str, hit_count: int, kind: str) -> None:
+    """Shared writer for every KB source marker. Atomic tmp+rename."""
+    path = _kb_query_path(session_id, kind)
     if path is None:
         return
     safe_query = (query or "")[:_MAX_QUERY_LEN]
@@ -464,7 +502,7 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
     except (TypeError, ValueError):
         hits = 0
     now = time.time()
-    existing = read_obsidian_query(session_id) or {}
+    existing = _read_query(session_id, kind) or {}
     queries_raw = existing.get("queries")
     queries = list(queries_raw) if isinstance(queries_raw, list) else []
     queries.append({"query": safe_query, "hit_count": hits, "ts": now})
@@ -472,6 +510,7 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         queries = queries[-_MAX_QUERIES_PER_TURN:]
     record = {
         "session_id": session_id,
+        "kind": kind,
         "queries": queries,
         "last_query_ts": now,
         "last_hit_count": hits,
@@ -483,15 +522,18 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         tmp.write_text(json.dumps(record), encoding="utf-8")
         os.replace(tmp, path)
     except OSError:
-        try:
+        with contextlib.suppress(FileNotFoundError):
             tmp.unlink()
-        except FileNotFoundError:
-            pass
 
 
-def read_obsidian_query(session_id: str) -> Optional[dict]:
+def read_obsidian_query(session_id: str) -> dict | None:
     """Return the turn-scoped Obsidian-query record, or None if absent."""
-    path = _kb_query_path(session_id)
+    return _read_query(session_id, kind="obsidian")
+
+
+def _read_query(session_id: str, kind: str) -> dict | None:
+    """Shared reader for every KB source marker."""
+    path = _kb_query_path(session_id, kind)
     if path is None or not path.exists():
         return None
     try:
@@ -510,7 +552,12 @@ def obsidian_queried_this_turn(session_id: str) -> bool:
 
 def invalidate_obsidian_query(session_id: str) -> None:
     """Clear the per-turn KB consult marker. Idempotent."""
-    path = _kb_query_path(session_id)
+    _invalidate_query(session_id, kind="obsidian")
+
+
+def _invalidate_query(session_id: str, kind: str) -> None:
+    """Shared invalidator for every KB source marker."""
+    path = _kb_query_path(session_id, kind)
     if path is None:
         return
     try: