arkaos 4.48.0 → 5.0.0

package/core/hooks/post_tool_use.py

@@ -685,7 +685,36 @@ def _enqueue_cognition_capture(session_id: str, tool_text: str) -> None:
 # ─── Section 10: metrics ─────────────────────────────────────────────────
 
 
-def _log_metrics(duration_ms: int) -> None:
+def _shadow_attribution() -> dict:
+    """PR-A5a: label this (delegated) run with the flag states. The
+    labels partition by FLAG STATE only — stateful-tool and error-turn
+    delegations carry the same flags — so the shadow-forced population
+    is isolated by combining them with the ``delegation`` field
+    (``_delegation_kind``): enforcement=false, shadow=true,
+    delegation="benign" is the flow-auth rescan population that only
+    reaches Python because of shadow-deny (engine.cjs Q6), plus the
+    negligible direct-invocation/fastpath-off runs. Empty on stripped
+    installs."""
+    try:
+        from core.workflow.flow_enforcer import _feature_flag_on, shadow_deny_on
+        return {"enforcement": _feature_flag_on(), "shadow": shadow_deny_on()}
+    except Exception:
+        return {}
+
+
+def _delegation_kind(stdin_json: dict, tool_name: str, benign: bool) -> str:
+    """Why this run reached Python, derived from the payload in the same
+    precedence the shim decides delegation (engine.cjs decidePost:
+    failure event, then the stateful set, then the error trigger —
+    everything else on this path is the Q6 flow-auth rescan)."""
+    if get_str(stdin_json, "hook_event_name") == "PostToolUseFailure":
+        return "error"
+    if tool_name in ("ExitPlanMode", "Task", "Agent"):
+        return "stateful"
+    return "benign" if benign else "error"
+
+
+def _log_metrics(duration_ms: int, attribution: dict | None = None) -> None:
     metrics_file = Path.home() / ".arkaos" / "hook-metrics.json"
     lock_file = Path.home() / ".arkaos" / "hook-metrics.lock"
     metrics_file.parent.mkdir(parents=True, exist_ok=True)
@@ -706,6 +735,7 @@ def _log_metrics(duration_ms: int) -> None:
                     "hook": "post-tool-use",
                     "duration_ms": duration_ms,
                     "timestamp": now,
+                    **(attribution or {}),
                 })
                 tmp = metrics_file.with_suffix(".json.tmp")
                 tmp.write_text(json.dumps(entries[-500:]), encoding="utf-8")
@@ -776,9 +806,17 @@ def main(stdin_json: dict | None = None) -> int:
             _record_pattern_stub(tool_text, prompt)
         _record_activation(subagent_type, session_id)
 
-    # Only process further if there was an error signal (same early exit
-    # as the bash version — violations/metrics only run on error turns).
+    # Only process violations/gotchas further on error turns (same early
+    # exit as the bash version). Metrics ARE logged here first: benign
+    # turns are exactly where the shadow-forced flow-auth delegations
+    # live — skipping them left the kill-switch population unrecorded
+    # (QG r2, Eduardo B1 + Francisca B3).
     if exit_code in ("0", "") and not _ERROR_TRIGGER_RE.search(tool_text):
+        _log_metrics(
+            int((time.monotonic() - start) * 1000),
+            {**_shadow_attribution(),
+             "delegation": _delegation_kind(stdin_json, tool_name, True)},
+        )
         print("{}")
         return 0
 
@@ -802,7 +840,11 @@ def main(stdin_json: dict | None = None) -> int:
     )
 
     _enqueue_cognition_capture(session_id, tool_text)
-    _log_metrics(int((time.monotonic() - start) * 1000))
+    _log_metrics(
+        int((time.monotonic() - start) * 1000),
+        {**_shadow_attribution(),
+         "delegation": _delegation_kind(stdin_json, tool_name, False)},
+    )
 
     if violation_msg:
         # The runtime drops context whose hookEventName differs from the

package/core/hooks/pre_tool_use.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 
 import contextlib
 import sys
+import time
 from pathlib import Path
 
 from core.hooks._shared import (
@@ -55,7 +56,8 @@ def _query_hint(tool_input: dict) -> str:
 
 
 class _MessagesOnce:
-    """Parse the transcript at most once, lazily, across both gates.
+    """Parse the transcript at most once, lazily, across the gates
+    (specialist, frontend and flow all consume the same instance).
 
     ``peek()`` never triggers a read — gates that have their own cheaper
     early-outs (feature flag off, marker-cache hit) pass ``peek()`` so the
@@ -67,6 +69,7 @@ class _MessagesOnce:
         self._path = transcript_path
         self._messages: list[str] | None = None
         self._sidechain: bool | None = None
+        self._load_ms: float = 0.0
 
     def peek(self) -> list[str] | None:
         return self._messages
@@ -75,8 +78,19 @@ class _MessagesOnce:
         """Scope of the most recent assistant record; None before load()."""
         return self._sidechain
 
+    def consume_load_ms(self) -> float:
+        """The parse cost in ms, claimable ONCE (PR-A5a shadow timing).
+
+        The parse a shadow evaluation forces happens here, outside every
+        gate's own timer — the first shadow caller claims it into its
+        Decision.shadow_ms; subsequent callers get 0.0 so the cost is
+        never double-attributed."""
+        elapsed, self._load_ms = self._load_ms, 0.0
+        return elapsed
+
     def load(self) -> list[str] | None:
         if self._messages is None:
+            start = time.perf_counter()
             try:
                 # Scope-aware since P0.2: the window counts MAIN-scope
                 # messages only, so interleaved subagent records cannot
@@ -88,6 +102,10 @@ class _MessagesOnce:
                 self._sidechain = split.active_sidechain
             except Exception:
                 return None
+            finally:
+                self._load_ms = round(
+                    (time.perf_counter() - start) * 1000, 3
+                )
         return self._messages
 
 
@@ -121,6 +139,17 @@ def _kb_gate(root: str, tool_name: str, session_id: str, query: str) -> int | No
     return None
 
 
+def _claim_parse_cost(decision, messages: _MessagesOnce) -> None:
+    """Attribute the parse a shadow evaluation forced (QG r1, Francisca
+    B2): the load ran outside the gate's timer, so the first shadow
+    decision claims it — consume_load_ms() returns 0.0 when another
+    gate already did, or when enforcement (not shadow) paid for it."""
+    if decision.shadow_reason:
+        decision.shadow_ms = round(
+            decision.shadow_ms + messages.consume_load_ms(), 3
+        )
+
+
 def _specialist_gate(
     root: str,
     tool_name: str,
@@ -137,6 +166,7 @@ def _specialist_gate(
     if not module_path.is_file():
         return None
     try:
+        from core.workflow.flow_enforcer import shadow_deny_on
         from core.workflow.specialist_enforcer import (
             _feature_flag_on,
             evaluate,
@@ -145,9 +175,11 @@ def _specialist_gate(
     except Exception:
         return None  # specialist-import-failed → allow
     # Load (and share) the transcript only when the gate will actually
-    # scan it — flag-off sessions keep the zero-read fast path.
+    # scan it — flag-off sessions with the shadow kill-switch thrown
+    # keep the zero-read fast path; shadow sessions share ONE parse
+    # across the specialist, frontend and flow gates (PR-A5a).
     shared = messages.peek()
-    if shared is None and _feature_flag_on():
+    if shared is None and (_feature_flag_on() or shadow_deny_on()):
         shared = messages.load()
     decision = evaluate(
         tool_name=tool_name,
@@ -158,6 +190,7 @@ def _specialist_gate(
         messages=shared,
         is_sidechain=messages.sidechain_active(),
     )
+    _claim_parse_cost(decision, messages)
     with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id,

package/core/workflow/flow_enforcer.py

@@ -16,12 +16,15 @@ Design contract:
 - Gated tool list is closed: anything outside it is always allowed.
 """
 
+import contextlib
 import json
 import os
 import re
+import time
 from contextlib import contextmanager
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from functools import lru_cache
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
@@ -51,10 +54,8 @@ def _locked_append(path: Path):
         yield fh
     finally:
         if _HAS_FLOCK:
-            try:
+            with contextlib.suppress(OSError):
                 fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-            except OSError:
-                pass
         fh.close()
 
 # PR11 v2.33.0 — Discovery vs Effect tool taxonomy (Conclave Phase 5).
@@ -107,7 +108,7 @@ _BASH_DISCOVERY_FIRST: frozenset[str] = frozenset({
     "shopt", "trap", "wait", "eval", "exec",
     # Test runners (read state but don't mutate canonical files)
     "pytest", "jest", "vitest", "phpunit", "pest", "rspec", "mocha",
-    "go", "cargo",
+    "cargo",
 })
 
 # Bash classifier — patterns that indicate mutation (anywhere in command).
@@ -182,10 +183,8 @@ def bash_is_effect(command: str) -> bool:
         first = first_tokens[0] if first_tokens else ""
     if not first:
         return False
-    if first in _BASH_DISCOVERY_FIRST:
-        return False
-    # Unknown command — default to requiring routing.
-    return True
+    # Unknown commands default to requiring routing.
+    return first not in _BASH_DISCOVERY_FIRST
 
 ROUTING_RE = re.compile(r"\[arka:routing\]\s*[\w-]+\s*->\s*\w+", re.IGNORECASE)
 TRIVIAL_RE = re.compile(r"\[arka:trivial\]\s*\S+", re.IGNORECASE)
@@ -227,6 +226,17 @@ class Decision:
     # Interaction Reform PR3 — plan-approval telemetry (WARN phase):
     # "approved" | "missing" | "no-plan" | "unknown" | "" (not gated).
     approval_state: str = ""
+    # PR-A5a shadow-deny: with hardEnforcement off, the gate still runs
+    # and records what it WOULD have decided. `would_block` is True when
+    # enforcement would have denied; `shadow_reason` carries the inner
+    # decision's reason (shadow ran iff it is non-empty); `shadow_ms`
+    # (float, sub-ms preserved) measures the added evaluation cost for
+    # the pre-side p90 kill-switch criterion — the post-side cost is
+    # attributed separately in hook-metrics.json (see wiki/16). All
+    # three stay at their defaults on enforced paths.
+    would_block: bool = False
+    shadow_reason: str = ""
+    shadow_ms: float = 0.0
 
     def to_stderr_message(self) -> str:
         if self.allow:
@@ -257,13 +267,37 @@ def _feature_flag_on() -> bool:
     return bool(data.get("hooks", {}).get("hardEnforcement", False))
 
 
+@lru_cache(maxsize=1)
+def shadow_deny_on() -> bool:
+    """``hooks.shadowDeny`` — the shadow-telemetry kill-switch (PR-A5a).
+
+    DEFAULT ON: a missing config file, corrupt or undecodable JSON, or a
+    missing key all mean ON (the telemetry that gates the A5b flip
+    collects by default); only an explicit falsy value turns it off.
+    Mirrored by engine.cjs ``shadowDenyOn`` via the gate manifest — keep
+    the two in lockstep. Cached per process (each hook invocation is a
+    fresh interpreter, so the cache scope is one tool call; tests call
+    ``shadow_deny_on.cache_clear()`` after rewriting the config).
+    """
+    if not CONFIG_PATH.exists():
+        return True
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return True
+    hooks = data.get("hooks") if isinstance(data, dict) else None
+    if not isinstance(hooks, dict) or "shadowDeny" not in hooks:
+        return True
+    return bool(hooks["shadowDeny"])
+
+
 def _bypass_env_active() -> bool:
     return os.environ.get("ARKA_BYPASS_FLOW", "").strip() == "1"
 
 
 def _audit_bypass(session_id: str, tool: str, cwd: str) -> None:
     entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": session_id,
         "tool": tool,
         "cwd": cwd,
@@ -278,7 +312,7 @@ def record_telemetry(
 ) -> None:
     """Append a structured record to the enforcement telemetry log."""
     entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": session_id,
         "tool": tool,
         "cwd": cwd,
@@ -407,7 +441,7 @@ def _annotate_plan_approval(decision: Decision, session_id: str) -> Decision:
             )
         else:
             decision.approval_state = "no-plan"
-    except Exception:  # noqa: BLE001 — annotation must never break a hook
+    except Exception:
         decision.approval_state = "unknown"
     return decision
 
@@ -462,11 +496,61 @@ def _evaluate_flow(
     if not is_gated:
         return Decision(allow=True, reason="tool-not-gated")
 
-    if not _feature_flag_on():
+    if _feature_flag_on():
+        return _decide_gated(
+            tool_name, transcript_path, session_id, cwd, messages
+        )
+    if not shadow_deny_on():
         return Decision(allow=True, reason="feature-flag-off")
+    return _shadow_decision(
+        tool_name, transcript_path, session_id, cwd, messages
+    )
+
+
+def _shadow_decision(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    messages: list[str] | None,
+) -> Decision:
+    """Run the gated chain in shadow (PR-A5a): allow regardless, record
+    what enforcement would have decided. Silent by construction — the
+    inner decision's warning/stderr never propagates."""
+    start = time.perf_counter()
+    inner = _decide_gated(
+        tool_name, transcript_path, session_id, cwd, messages, shadow=True
+    )
+    return Decision(
+        allow=True,
+        reason="feature-flag-off",
+        marker_found=inner.marker_found,
+        phase_observed=inner.phase_observed,
+        would_block=not inner.allow,
+        shadow_reason=inner.reason,
+        shadow_ms=round((time.perf_counter() - start) * 1000, 3),
+    )
+
+
+def _decide_gated(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    messages: list[str] | None,
+    shadow: bool = False,
+) -> Decision:
+    """The enforcement chain behind the feature flag.
 
+    ``shadow=True`` runs the identical chain for the telemetry-only
+    caller; the sole suppressed side effect is the bypass audit — an env
+    bypass of an inactive gate is not a bypass and must not pollute the
+    accountability log. State writes (confirm/grace) run in both modes
+    so the shadow would_block rate is the rate a flip would produce.
+    """
     if _bypass_env_active():
-        _audit_bypass(session_id, tool_name, cwd)
+        if not shadow:
+            _audit_bypass(session_id, tool_name, cwd)
         return Decision(allow=True, reason="env-bypass", bypass_used=True)
 
     if not _flow_required_for_session(session_id):
@@ -485,6 +569,11 @@ def _evaluate_flow(
         messages = _load_last_assistant_messages(
             transcript_path, ASSISTANT_WINDOW
         )
+    return _decide_from_markers(session_id, messages)
+
+
+def _decide_from_markers(session_id: str, messages: list[str]) -> Decision:
+    """Marker scan + persistent-auth fallback + grace ladder."""
     marker_found, phase_observed = _scan_markers(messages)
 
     if marker_found is not None:
@@ -511,12 +600,15 @@ def _evaluate_flow(
         return Decision(
             allow=True, reason="turn-grace", phase_observed=phase_observed
         )
+    return _decide_grace(session_id, phase_observed)
+
 
-    # First effect-tool of a turn with no confirmed auth. A hard deny here
-    # is a false positive (the assistant may have routed in this very
-    # message — invisible to us). Grace it with a warning; escalate to a
-    # real block only after GRACE_CAP consecutive graced turns without any
-    # confirmation (a normally-routing session confirms by turn 2).
+def _decide_grace(session_id: str, phase_observed: str | None) -> Decision:
+    """First effect-tool of a turn with no confirmed auth. A hard deny
+    here is a false positive (the assistant may have routed in this very
+    message — invisible to us). Grace it with a warning; escalate to a
+    real block only after GRACE_CAP consecutive graced turns without any
+    confirmation (a normally-routing session confirms by turn 2)."""
     grace = flow_authorization.register_grace(session_id)
     if grace.escalate:
         return Decision(
@@ -545,7 +637,7 @@ def mark_flow_required(session_id: str) -> None:
         return
     FLOW_REQUIRED_DIR.mkdir(parents=True, exist_ok=True)
     marker = FLOW_REQUIRED_DIR / safe
-    marker.write_text(datetime.now(timezone.utc).isoformat(), encoding="utf-8")
+    marker.write_text(datetime.now(UTC).isoformat(), encoding="utf-8")
 
 
 def clear_flow_required(session_id: str) -> None:

package/core/workflow/frontend_gate.py

@@ -35,8 +35,9 @@ from __future__ import annotations
 import json
 import os
 import re
+import time
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
@@ -44,6 +45,7 @@ from core.workflow import design_authorization
 from core.workflow.flow_enforcer import (
     TRIVIAL_RE,
     _load_last_assistant_messages,
+    shadow_deny_on,
 )
 from core.workflow.specialist_enforcer import _locked_append
 
@@ -93,6 +95,11 @@ class Decision:
     marker_found: str | None = None
     marker_kind: str = "none"   # structured | legacy | trivial | none
     ui_scope: str = "suffix"    # suffix | heuristic
+    # PR-A5a shadow-deny — see flow_enforcer.Decision: what hard mode
+    # WOULD have decided, recorded while warn/off modes keep allowing.
+    would_block: bool = False
+    shadow_reason: str = ""
+    shadow_ms: float = 0.0
 
     def to_stderr_message(self) -> str:
         if self.reason == "legacy-marker":
@@ -237,6 +244,51 @@ def _marker_decision(
                     ui_scope=ui_scope)
 
 
+def _shadow_off_decision(
+    session_id: str,
+    file_path: str,
+    ui_scope: str,
+    transcript_path: str,
+    messages: list[str] | None,
+) -> Decision:
+    """Off mode with shadow-deny on (PR-A5a): evaluate the marker chain
+    anyway and record what hard mode would have decided — silently
+    (reason "flag-off" produces no stderr message)."""
+    if os.environ.get("ARKA_BYPASS_DESIGN") == "1":
+        return Decision(allow=True, reason="flag-off", mode="off",
+                        target_file=file_path, ui_scope=ui_scope,
+                        shadow_reason="env-bypass")
+    start = time.perf_counter()
+    if messages is None:
+        messages = _load_last_assistant_messages(
+            transcript_path, ASSISTANT_WINDOW
+        )
+    marker, kind = _classify_marker(messages)
+    inner = _marker_decision(session_id, marker, kind, "hard", file_path, ui_scope)
+    return Decision(
+        allow=True, reason="flag-off", mode="off", target_file=file_path,
+        marker_found=inner.marker_found, marker_kind=inner.marker_kind,
+        ui_scope=ui_scope, would_block=not inner.allow,
+        shadow_reason=inner.reason,
+        shadow_ms=round((time.perf_counter() - start) * 1000, 3),
+    )
+
+
+def _annotate_warn_shadow(decision: Decision) -> Decision:
+    """Warn mode already evaluates the full chain — annotate what hard
+    mode would have denied (suffix scope, no structured/trivial/persisted
+    marker). Zero added transcript reads; gated on the same kill-switch."""
+    if (
+        decision.allow
+        and decision.ui_scope == "suffix"
+        and decision.reason in ("legacy-marker", "no-design-marker")
+        and shadow_deny_on()
+    ):
+        decision.would_block = True
+        decision.shadow_reason = decision.reason
+    return decision
+
+
 def evaluate(
     tool_name: str,
     transcript_path: str,
@@ -252,8 +304,12 @@ def evaluate(
         return Decision(allow=True, reason="not-ui-scope", target_file=file_path)
     mode = _mode()
     if mode == "off":
-        return Decision(allow=True, reason="flag-off", mode=mode,
-                        target_file=file_path, ui_scope=ui_scope)
+        if not shadow_deny_on():
+            return Decision(allow=True, reason="flag-off", mode=mode,
+                            target_file=file_path, ui_scope=ui_scope)
+        return _shadow_off_decision(
+            session_id, file_path, ui_scope, transcript_path, messages
+        )
     if os.environ.get("ARKA_BYPASS_DESIGN") == "1":
         return Decision(allow=True, reason="env-bypass", mode=mode,
                         target_file=file_path, ui_scope=ui_scope)
@@ -262,7 +318,10 @@ def evaluate(
             transcript_path, ASSISTANT_WINDOW
         )
     marker, kind = _classify_marker(messages)
-    return _marker_decision(session_id, marker, kind, mode, file_path, ui_scope)
+    decision = _marker_decision(session_id, marker, kind, mode, file_path, ui_scope)
+    if mode == "warn":
+        decision = _annotate_warn_shadow(decision)
+    return decision
 
 
 def record_telemetry(session_id: str, tool: str, decision: Decision) -> None:
@@ -275,7 +334,7 @@ def record_telemetry(session_id: str, tool: str, decision: Decision) -> None:
     if safe is None:
         return
     entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": safe,
         "tool": tool,
         **asdict(decision),

package/core/workflow/specialist_enforcer.py

@@ -39,8 +39,9 @@ flow-gate. Same Decision JSON contract as core.workflow.flow_enforcer.
 import contextlib
 import json
 import re
+import time
 from contextlib import contextmanager
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from datetime import UTC, datetime
 from functools import lru_cache
 from pathlib import Path
@@ -49,6 +50,7 @@ import yaml
 
 from core.shared import safe_session_id as _safe_session_id_module
 from core.workflow import specialist_authorization, transcript_scope
+from core.workflow.flow_enforcer import shadow_deny_on
 
 try:
     import fcntl  # POSIX only
@@ -138,6 +140,11 @@ class Decision:
     persona_source: str = ""
     is_sidechain: bool = False
     msgs_since_marker: int | None = None
+    # PR-A5a shadow-deny — see flow_enforcer.Decision: what enforcement
+    # WOULD have decided while hooks.specialistEnforcement stays off.
+    would_block: bool = False
+    shadow_reason: str = ""
+    shadow_ms: float = 0.0
 
     def to_stderr_message(self) -> str:
         """The message a blocked session reads.
@@ -432,10 +439,38 @@ def _check_tool_gated(ctx: _Ctx) -> Decision | None:
     return None
 
 
-def _check_feature_flag(ctx: _Ctx) -> Decision | None:
-    if not _feature_flag_on():
-        return Decision(allow=True, reason="feature-flag-off")
-    return None
+def _decide_populated(ctx: _Ctx) -> Decision:
+    """The enforcement pipeline behind the feature flag: populate the
+    context, run the late checks, resolve ownership."""
+    _populate_context(ctx)
+    for late_check in (_check_no_persona, _check_c_suite, _check_lead_allowed_file):
+        decision = late_check(ctx)
+        if decision is not None:
+            return decision
+    return _resolve_ownership_outcome(ctx)
+
+
+def _shadow_decision(ctx: _Ctx) -> Decision:
+    """Run the pipeline in shadow (PR-A5a): allow regardless, record what
+    enforcement would have decided, carrying the resolved persona and
+    ownership context into telemetry. Silent by construction — allow=True
+    means to_stderr_message() returns "". bypass_used/bypass_reason are
+    reset: a bypass of an inactive gate is not a bypass and must not
+    inflate the specialist-telemetry counter — shadow_reason still says
+    "bypass-with-reason", so no information is lost (QG r1, Francisca B1).
+    """
+    start = time.perf_counter()
+    inner = _decide_populated(ctx)
+    return replace(
+        inner,
+        allow=True,
+        reason="feature-flag-off",
+        bypass_used=False,
+        bypass_reason=None,
+        would_block=not inner.allow,
+        shadow_reason=inner.reason,
+        shadow_ms=round((time.perf_counter() - start) * 1000, 3),
+    )
 
 
 def _msgs_since_marker(messages: list[str]) -> int | None:
@@ -626,16 +661,14 @@ def evaluate(
         session_id=session_id, cwd=cwd, tool_input=tool_input or {},
         preloaded_messages=messages, is_sidechain=is_sidechain,
     )
-    for early_check in (_check_tool_gated, _check_feature_flag):
-        decision = early_check(ctx)
-        if decision is not None:
-            return decision
-    _populate_context(ctx)
-    for late_check in (_check_no_persona, _check_c_suite, _check_lead_allowed_file):
-        decision = late_check(ctx)
-        if decision is not None:
-            return decision
-    return _resolve_ownership_outcome(ctx)
+    decision = _check_tool_gated(ctx)
+    if decision is not None:
+        return decision
+    if _feature_flag_on():
+        return _decide_populated(ctx)
+    if not shadow_deny_on():
+        return Decision(allow=True, reason="feature-flag-off")
+    return _shadow_decision(ctx)
 
 
 def record_telemetry(

package/departments/kb/SKILL.md

@@ -24,6 +24,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | `/kb learn <url>` | Ingest content (YouTube, article, PDF) into KB | Enterprise |
 | `/kb research <topic>` | Research plan and execution with source evaluation | Focused |
 | `/kb ai-research <topic>` | AI-augmented research (Elicit, Perplexity, Claude) | Focused |
+| `/kb research-deep <question>` | Ladder over the operator's own corpus: Obsidian → NotebookLM (egress-guarded) → web, with vault write-back | Focused |
 | `/kb persona <name>` | Build or view a persona from the KB | Enterprise |
 | `/kb moc <cluster>` | Create/update Map of Content | Specialist |
 | `/kb zettelkasten <note>` | Process a note through Zettelkasten workflow | Specialist |