arkaos 4.22.0 → 4.24.0

package/core/governance/evidence_checks.py

@@ -23,6 +23,8 @@ CLI (for hooks/skills)::
 from __future__ import annotations
 
 import argparse
+import configparser
+import fnmatch
 import importlib.util
 import json
 import re
@@ -31,7 +33,7 @@ import shutil
 import subprocess
 import sys
 import time
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from pathlib import Path
 
 from core.shared.test_evidence import coverage_percent_from_xml
@@ -218,18 +220,22 @@ def _labelled(result: CheckResult, label: str) -> CheckResult:
     return result
 
 
-def _tool_cmd(tool: str) -> list[str] | None:
+def _tool_cmd(tool: str, module: str | None = None) -> list[str] | None:
     """Resolve a Python tool: PATH binary, else the interpreter's module.
 
     Operator machines install ruff/pytest into the ArkaOS venv with no
     PATH binary — keying on shutil.which alone silently downgraded
     Python lint to eslint over installer/*.js, a FALSE GREEN on a
     NON-NEGOTIABLE gate (QG findings, F1-B2/F1-C1 reviews).
+
+    ``module`` covers tools whose import name differs from the command
+    (codespell ships ``codespell_lib``); without it the module fallback
+    misses and the check skips forever on a venv install.
     """
     if shutil.which(tool):
         return [tool]
-    if importlib.util.find_spec(tool) is not None:
-        return [sys.executable, "-m", tool]
+    if importlib.util.find_spec(module or tool) is not None:
+        return [sys.executable, "-m", module or tool]
     return None
 
 
@@ -335,15 +341,59 @@ def _check_typecheck(
     return _skip("typecheck", "no typecheck configuration detected")
 
 
+def _project_pytest(project_dir: Path) -> list[str] | None:
+    """pytest belonging to the target project's own environment."""
+    for rel in (".venv/bin/pytest", "venv/bin/pytest"):
+        candidate = project_dir / rel
+        if candidate.is_file():
+            return [str(candidate)]
+    return None
+
+
+def _foreign_pytest_can_collect(
+    pytest_cmd: list[str], project_dir: Path, timeout: int,
+) -> bool:
+    """A PATH/venv-foreign pytest must prove it can import the project.
+
+    Running a foreign-env pytest blind produced false FAILs on projects
+    whose dependencies live in their own venv (import errors read as
+    test failures — issue #283, a blind gate on mandatory-qa). Exit 5
+    ("no tests collected") still counts as a working import path.
+    """
+    try:
+        probe = subprocess.run(
+            [*pytest_cmd, "--collect-only", "-q"], cwd=project_dir,
+            capture_output=True, text=True, timeout=min(timeout, 60),
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return probe.returncode in (0, 5)
+
+
 def _check_tests(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     if test_command:
         return _run("tests", shlex.split(test_command), project_dir, timeout)
-    pytest_cmd = _tool_cmd("pytest")
-    if _has_python(project_dir, changed) and pytest_cmd:
-        return _run("tests", [*pytest_cmd, "-q"], project_dir, timeout)
+    if _has_python(project_dir, changed):
+        local_pytest = _project_pytest(project_dir)
+        if local_pytest:
+            return _labelled(
+                _run("tests", [*local_pytest, "-q"], project_dir, timeout),
+                "tests(project-venv)",
+            )
+        pytest_cmd = _tool_cmd("pytest")
+        if pytest_cmd and _foreign_pytest_can_collect(
+            pytest_cmd, project_dir, timeout
+        ):
+            return _run("tests", [*pytest_cmd, "-q"], project_dir, timeout)
+        if pytest_cmd:
+            return _skip(
+                "tests",
+                "pytest resolved outside the project env cannot import "
+                "it — pin --test-command",
+            )
     if _package_json_script(project_dir, "test"):
         return _run(
             "tests", ["npm", "test", "--silent"], project_dir, timeout,
@@ -501,12 +551,54 @@ def _check_spellcheck(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
-    if not shutil.which("codespell"):
+    # Resolve like lint/tests do. A bare shutil.which lookup left this check
+    # dark on venv installs (the binary is not on the harness PATH), so three
+    # consecutive QG rounds shipped with NO machine spellcheck signal.
+    cmd = _tool_cmd("codespell", module="codespell_lib")
+    if cmd is None:
         return _skip("spellcheck", "codespell not installed")
     md_files = [f for f in changed or [] if f.endswith(".md")]
     if not md_files:
         return _skip("spellcheck", "no changed .md files")
-    return _run("spellcheck", ["codespell", *md_files], project_dir, timeout)
+    result = _run("spellcheck", [*cmd, *md_files], project_dir, timeout)
+    # codespell honours .codespellrc `skip` even for explicitly listed files,
+    # so a PASS here can cover far fewer files than were handed in. Reporting
+    # the raw count as coverage is how a narrowed scope reads as a full green
+    # (QG finding: 8 of 220 inspected, reported as 220). State both.
+    inspected = _spellcheck_inspected_count(project_dir, md_files)
+    scope = f"{inspected} of {len(md_files)} changed .md inspected"
+    if inspected < len(md_files):
+        scope += f"; {len(md_files) - inspected} excluded by .codespellrc skip"
+    summary = f"{scope}\n{result.summary}" if result.summary else scope
+    return replace(result, summary=summary)
+
+
+def _spellcheck_inspected_count(project_dir: Path, md_files: list[str]) -> int:
+    """How many of ``md_files`` codespell actually reads after `skip`.
+
+    Asks codespell itself (``--count`` on a per-file basis is too slow; a
+    skipped file simply produces no output for any planted probe), so instead
+    we replay its own glob semantics from the config.
+    """
+    patterns = _codespell_skip_globs(project_dir)
+    if not patterns:
+        return len(md_files)
+    return sum(
+        1 for f in md_files
+        if not any(fnmatch.fnmatch(f, p) or fnmatch.fnmatch(f"./{f}", p) for p in patterns)
+    )
+
+
+def _codespell_skip_globs(project_dir: Path) -> list[str]:
+    """`skip` globs from .codespellrc, or [] when unreadable/absent."""
+    cfg = project_dir / ".codespellrc"
+    try:
+        parser = configparser.ConfigParser()
+        parser.read(cfg, encoding="utf-8")
+        raw = parser.get("codespell", "skip", fallback="")
+    except (OSError, configparser.Error):
+        return []
+    return [p.strip() for p in raw.split(",") if p.strip()]
 
 
 def _check_ui_screenshot(

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)