arkaos 4.0.2 → 4.1.0

package/core/workflow/gate_checkpoint.py

@@ -0,0 +1,149 @@
+"""Gate checkpoint persistence for the 4-gate evidence flow (v4.1.0).
+
+Invoked by the Stop hook once per assistant turn. Scans recent assistant
+messages for `[arka:gate:N]` markers and persists the furthest gate
+observed to BOTH stores:
+
+- ``~/.arkaos/workflow-state.json`` via :mod:`core.workflow.state`
+- ``~/.arkaos/sessions/<id>/workflow-state.json`` via
+  :class:`core.memory.session_store.SessionStore` (consumed by
+  :mod:`core.memory.rehydrator` at SessionStart)
+
+This is what makes a rate-limit or context-exhaustion interruption
+resumable at the correct gate instead of restarting the flow. See ADR
+``docs/adr/2026-07-04-evidence-flow.md``.
+
+Never raises: checkpointing must not break a Stop hook.
+"""
+
+import json
+import re
+import sys
+
+from core.memory.session_store import SessionStore, WorkflowSnapshot
+from core.shared.safe_session_id import safe_session_id
+from core.workflow import state
+from core.workflow.flow_enforcer import _load_last_assistant_messages
+
+GATES: tuple[str, ...] = (
+    "gate-1-context",
+    "gate-2-plan",
+    "gate-3-execute",
+    "gate-4-review",
+)
+
+GATE_MARKER_RE = re.compile(r"\[arka:gate:([1-4])\]", re.IGNORECASE)
+GATE3_EVIDENCE_RE = re.compile(
+    r"\[arka:gate:3\]\s*evidence:\s*(?P<evidence>.+)", re.IGNORECASE
+)
+
+_SCAN_WINDOW = 20
+
+
+def extract_latest_gate(messages: list[str]) -> int | None:
+    """Return the highest gate number observed across the messages."""
+    latest: int | None = None
+    for text in messages:
+        for match in GATE_MARKER_RE.finditer(text):
+            number = int(match.group(1))
+            if latest is None or number > latest:
+                latest = number
+    return latest
+
+
+def extract_gate3_evidence(messages: list[str]) -> str | None:
+    """Return the most recent Gate-3 evidence line, if any."""
+    evidence: str | None = None
+    for text in messages:
+        for match in GATE3_EVIDENCE_RE.finditer(text):
+            evidence = match.group("evidence").strip()
+    return evidence
+
+
+def _phase_statuses(latest: int) -> dict[str, str]:
+    """Map each gate to completed/in_progress/pending given the latest gate."""
+    statuses: dict[str, str] = {}
+    for index, gate in enumerate(GATES, start=1):
+        if index < latest:
+            statuses[gate] = "completed"
+        elif index == latest:
+            statuses[gate] = "in_progress"
+        else:
+            statuses[gate] = "pending"
+    return statuses
+
+
+def _persist_global_state(latest: int, project: str, evidence: str | None) -> None:
+    current = state.get_state()
+    if current is None or current.get("workflow") != "evidence-flow":
+        state.init_workflow("evidence-flow", project, list(GATES))
+    for gate, status in _phase_statuses(latest).items():
+        artifact = None
+        if gate == GATES[2] and evidence:
+            artifact = evidence
+        state.update_phase(gate, status, artifact=artifact)
+
+
+def _persist_session_snapshot(
+    session_id: str, latest: int, evidence: str | None
+) -> None:
+    safe = safe_session_id(session_id)
+    if safe is None:
+        return
+    store = SessionStore(safe)
+    snapshot = WorkflowSnapshot(
+        workflow_id=safe,
+        workflow_name="evidence-flow",
+        current_phase=GATES[latest - 1],
+        phases=_phase_statuses(latest),
+        artifacts=[evidence] if evidence else [],
+    )
+    store.save_workflow_snapshot(snapshot)
+
+
+def checkpoint(
+    transcript_path: str,
+    session_id: str,
+    project: str = "",
+    messages: list[str] | None = None,
+) -> dict | None:
+    """Persist the furthest observed gate. Returns a summary dict or None.
+
+    ``messages`` (PR-6 hook consolidation): pre-parsed assistant messages;
+    when None the transcript is read from ``transcript_path``.
+    """
+    try:
+        if messages is None:
+            messages = _load_last_assistant_messages(
+                transcript_path, _SCAN_WINDOW
+            )
+        else:
+            messages = messages[-_SCAN_WINDOW:]
+        latest = extract_latest_gate(messages)
+        if latest is None:
+            return None
+        evidence = extract_gate3_evidence(messages)
+        _persist_global_state(latest, project, evidence)
+        _persist_session_snapshot(session_id, latest, evidence)
+        return {
+            "gate": latest,
+            "current_phase": GATES[latest - 1],
+            "evidence": evidence,
+        }
+    except Exception:  # noqa: BLE001 — a Stop hook must never break the turn
+        return None
+
+
+def main(argv: list[str]) -> int:
+    """CLI: gate_checkpoint <transcript_path> <session_id> [project]."""
+    if len(argv) < 2:
+        return 0
+    project = argv[2] if len(argv) > 2 else ""
+    result = checkpoint(argv[0], argv[1], project)
+    if result is not None:
+        print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/core/workflow/research_gate.py

@@ -2,7 +2,8 @@
 
 Intercepts calls to Context7, WebSearch, WebFetch and Firecrawl MCP tools.
 Runs AFTER flow_enforcer in the PreToolUse hook chain. Independent gate:
-both must pass. Feature-flagged behind `hooks.kbFirst` (default false).
+both must pass. Feature-flagged behind `hooks.kbFirst` (default TRUE
+since v4.1 — see `_feature_flag_on`).
 
 Behaviour contract (plan 2026-04-20-intelligence-v2, §Épico B):
     1. Tool not in RESEARCH_EXTERNAL_TOOLS   → allow.
@@ -106,13 +107,24 @@ _safe_session_id = _safe_session_id_module.safe_session_id
 
 
 def _feature_flag_on() -> bool:
+    """Resolve the `hooks.kbFirst` flag.
+
+    Default-when-missing semantics (operator decision, PR-3 v4.1):
+    KB-first is ON out of the box. The installer template
+    (installer/config-seed.js) seeds `hooks.kbFirst = true`, so a missing
+    config file or a missing key now defaults to TRUE — matching the
+    seeded template instead of contradicting it. An explicit
+    `"kbFirst": false` in the user's config always wins. A corrupt/
+    unreadable config returns False (fail-open): the gate must never
+    deny tool calls based on intent it could not read.
+    """
     if not CONFIG_PATH.exists():
-        return False
+        return True
     try:
         data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return False
-    return bool(data.get("hooks", {}).get("kbFirst", False))
+    return bool(data.get("hooks", {}).get("kbFirst", True))
 
 
 def _bypass_env_active() -> bool: