@cairnkeep/cli 1.0.2

package/scripts/test-doctor.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Smoke test for `cairn doctor`: unconfigured deps SKIP (exit 0); a configured
+# but unreachable endpoint FAILs (exit non-zero).
+set -uo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+doctor="$ROOT/scripts/doctor.sh"
+# Clean the inherited env so the test controls what is "configured".
+unset CAIRN_LLM_API_URL CAIRN_MEMORY_EMBEDDING_URL CAIRN_GIT_PROVIDER CAIRN_AGENTFS_BASE_DIR
+
+# 1. Nothing configured → only SKIP/PASS/WARN, exit 0.
+proj="$tmp/clean"; mkdir -p "$proj"
+( cd "$proj" && "$doctor" ) >"$tmp/out1" 2>&1 || fail "doctor exited non-zero with nothing configured:\n$(cat "$tmp/out1")"
+grep -q "\[SKIP\]" "$tmp/out1" || fail "expected SKIP lines when nothing is configured"
+
+# 2. A configured but unreachable endpoint → FAIL + non-zero exit.
+if command -v curl >/dev/null 2>&1; then
+  proj2="$tmp/broken"; mkdir -p "$proj2/.ai"
+  echo 'CAIRN_LLM_API_URL=http://127.0.0.1:1' > "$proj2/.ai/.env"
+  if ( cd "$proj2" && "$doctor" ) >"$tmp/out2" 2>&1; then
+    fail "doctor should exit non-zero for an unreachable configured endpoint:\n$(cat "$tmp/out2")"
+  fi
+  grep -q "\[FAIL\] LLM endpoint unreachable" "$tmp/out2" || fail "expected a FAIL line for the unreachable endpoint"
+else
+  echo "  (curl absent — skipped the unreachable-endpoint case)"
+fi
+
+echo "PASS: cairn doctor (skip unconfigured, fail configured-unreachable)"

package/scripts/test-launcher-hooks.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Smoke test for the launcher wrapper seams: .ai/pre-launch.sh (source + abort),
+# CAIRN_EXTRA_SETTINGS layering, and .ai/post-exit.sh.
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+# A git repo scaffolded with the real templates.
+repo="$tmp/repo"; mkdir "$repo"; git -C "$repo" init -q
+"$ROOT/scripts/bootstrap.sh" "$repo" >/dev/null
+launcher="$repo/.ai/start-claude.sh"
+[[ -x "$launcher" ]] || fail "launcher not scaffolded"
+
+# Fake `claude` on PATH: records its args + a marker env var, exits FAKE_EXIT.
+mkdir "$tmp/bin"
+cat > "$tmp/bin/claude" <<'FAKE'
+#!/usr/bin/env bash
+{ echo "args:$*"; echo "prelaunch:${PRELAUNCH_RAN:-0}"; } > "$CLAUDE_LOG"
+exit "${FAKE_EXIT:-0}"
+FAKE
+chmod +x "$tmp/bin/claude"
+export PATH="$tmp/bin:$PATH"
+export CLAUDE_LOG="$tmp/claude.log"
+
+# 1. No hooks: launcher execs claude with the passed args (baseline unchanged).
+rm -f "$CLAUDE_LOG"
+"$launcher" --foo bar >/dev/null 2>&1 || fail "baseline launch failed"
+grep -qx "args:--foo bar" "$CLAUDE_LOG" || fail "baseline did not pass args through"
+grep -qx "prelaunch:0" "$CLAUDE_LOG" || fail "prelaunch marker leaked without a hook"
+
+# 2. pre-launch.sh is sourced (can export env) + CAIRN_EXTRA_SETTINGS layers in.
+rm -f "$CLAUDE_LOG"
+cat > "$repo/.ai/pre-launch.sh" <<EOF
+export PRELAUNCH_RAN=1
+export CAIRN_EXTRA_SETTINGS="$tmp/settings.json"
+EOF
+echo '{}' > "$tmp/settings.json"
+"$launcher" >/dev/null 2>&1 || fail "launch with pre-launch failed"
+grep -qx "prelaunch:1" "$CLAUDE_LOG" || fail "pre-launch env not visible to harness"
+grep -q -- "--settings $tmp/settings.json" "$CLAUDE_LOG" || fail "CAIRN_EXTRA_SETTINGS not passed as --settings"
+
+# 3. pre-launch.sh non-zero aborts the launch before the harness runs.
+rm -f "$CLAUDE_LOG"
+cat > "$repo/.ai/pre-launch.sh" <<'EOF'
+echo "pre-launch says no" >&2
+return 1
+EOF
+if "$launcher" >/dev/null 2>&1; then fail "non-zero pre-launch should abort the launch"; fi
+[[ ! -f "$CLAUDE_LOG" ]] || fail "harness ran despite pre-launch abort"
+rm -f "$repo/.ai/pre-launch.sh"
+
+# 4. post-exit.sh runs after the harness with $CAIRN_EXIT_STATUS.
+rm -f "$CLAUDE_LOG" "$tmp/post.log"
+cat > "$repo/.ai/post-exit.sh" <<EOF
+echo "post:\${CAIRN_EXIT_STATUS}" > "$tmp/post.log"
+EOF
+FAKE_EXIT=7 "$launcher" >/dev/null 2>&1 && fail "launcher should propagate harness exit code"
+status=$?
+[[ "$status" -eq 7 ]] || fail "expected exit 7 from launcher, got $status"
+grep -qx "post:7" "$tmp/post.log" || fail "post-exit hook did not see CAIRN_EXIT_STATUS"
+
+echo "PASS: launcher hook seams (pre-launch source/abort, settings layering, post-exit)"

package/scripts/test-memory-store.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Round-trip test for `cairn memory export/import/path`.
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+mem="$ROOT/scripts/memory-store.sh"
+
+# path prints the resolved base dir.
+CAIRN_AGENTFS_BASE_DIR="$tmp/store" "$mem" path | grep -qx "$tmp/store" \
+  || fail "path did not print the resolved base dir"
+
+if ! command -v sqlite3 >/dev/null 2>&1; then
+  echo "  (sqlite3 absent — skipped export/import round-trip)"
+  echo "PASS: cairn memory path (export/import skipped)"
+  exit 0
+fi
+
+# Seed a store with two scopes and known rows.
+mkdir -p "$tmp/store"
+sqlite3 "$tmp/store/identity.db" "CREATE TABLE m(k TEXT, v TEXT); INSERT INTO m VALUES('alpha','one');"
+sqlite3 "$tmp/store/work-memory.db" "CREATE TABLE m(k TEXT, v TEXT); INSERT INTO m VALUES('beta','two');"
+
+# Export from store A.
+CAIRN_AGENTFS_BASE_DIR="$tmp/store" "$mem" export "$tmp/export.tgz" >/dev/null
+[[ -f "$tmp/export.tgz" ]] || fail "export archive not created"
+
+# Import into a fresh store B and verify both scopes + rows survived.
+CAIRN_AGENTFS_BASE_DIR="$tmp/store2" "$mem" import "$tmp/export.tgz" >/dev/null
+[[ -f "$tmp/store2/identity.db" ]] || fail "identity.db missing after import"
+[[ -f "$tmp/store2/work-memory.db" ]] || fail "work-memory.db missing after import"
+got=$(sqlite3 "$tmp/store2/identity.db" "SELECT v FROM m WHERE k='alpha';")
+[[ "$got" == "one" ]] || fail "identity row not preserved (got '$got')"
+got=$(sqlite3 "$tmp/store2/work-memory.db" "SELECT v FROM m WHERE k='beta';")
+[[ "$got" == "two" ]] || fail "work-memory row not preserved (got '$got')"
+
+# Import over an existing store backs up the prior file.
+CAIRN_AGENTFS_BASE_DIR="$tmp/store2" "$mem" import "$tmp/export.tgz" >/dev/null
+[[ -f "$tmp/store2/identity.db.bak-pre-import" ]] || fail "existing store not backed up on re-import"
+
+echo "PASS: cairn memory export/import round-trip + path"

package/scripts/test-remember-recall-assertions.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Offline fixture test for scripts/lib/assert-tool-event.mjs (D-08/D-09,
+# T-13-01). Proves the NDJSON tool-event matcher distinguishes a genuine
+# tool_use event from a narrated-but-unexecuted text-event mention, with
+# and without canary linkage, and that it never crashes on malformed/empty
+# input. Fixtures are the verbatim live-captured NDJSON lines from
+# 13-RESEARCH.md's Code Examples section, embedded inline (single-quoted,
+# no shell interpolation) so this test is self-contained and runs offline.
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+MATCHER="$ROOT_DIR/scripts/lib/assert-tool-event.mjs"
+
+# Verbatim live capture, 13-RESEARCH.md Pattern 2:
+# `opencode run "remember that the test canary value is XYZ123" --format json --auto`
+WRITE_EVENT='{"type":"tool_use","timestamp":1783468394936,"sessionID":"ses_0c1000285ffeB3LgTc2lL6lpX7","part":{"type":"tool","tool":"cairn-memory_memory_write","callID":"call_00_HwYj7yo6GPefkOwdragE3435","state":{"status":"completed","input":{"scope":"work","key":"test-canary","value":"The test canary value is XYZ123."},"output":"{\n  \"ok\": true,\n  \"scope\": \"work\",\n  \"key\": \"test-canary\",\n  \"collisions\": []\n}","metadata":{"truncated":false},"title":"","time":{"start":1783468394919,"end":1783468394935}},"id":"prt_f3f000825001ZCly3HCQBHAmWC","sessionID":"ses_0c1000285ffeB3LgTc2lL6lpX7","messageID":"msg_f3efffdec001R3DoelYr4jBzyz"}}'
+
+# Verbatim live capture, 13-RESEARCH.md Pattern 2:
+# `opencode run "search your memory for the test canary value..." --format json --auto`
+# Its part.state.output (a JSON-encoded string) contains the literal substring
+# "XYZ123" — the D-09 canary-linkage fixture.
+SEARCH_EVENT='{"type":"tool_use","timestamp":1783468410962,"sessionID":"ses_0c0ffc42fffean1LIPrMRiv0Gj","part":{"type":"tool","tool":"cairn-memory_memory_search","callID":"call_00_ojFUlRfeg7RdkhxkZudF4674","state":{"status":"completed","input":{"scope":"work","query":"test canary value"},"output":"{\n  \"mode\": \"substring\",\n  \"count\": 1,\n  \"results\": [\n    {\n      \"scope\": \"work\",\n      \"key\": \"test-canary\",\n      \"value\": \"The test canary value is XYZ123.\",\n      \"score\": 1\n    }\n  ]\n}","metadata":{"truncated":false},"title":"","time":{"start":1783468410951,"end":1783468410961}},"id":"prt_f3f004761001QGw1GlWtp0nfgx","sessionID":"ses_0c0ffc42fffean1LIPrMRiv0Gj","messageID":"msg_f3f003c45001tYJ94eWqStsR7W"}}'
+
+# Synthesized (not live-captured): a "text" event whose part.text merely
+# narrates the write tool name in prose. Top-level type is "text", not
+# "tool_use" — must NOT match (the D-08 narrated-but-unexecuted case).
+TEXT_NARRATION_EVENT='{"type":"text","timestamp":1783468394000,"sessionID":"ses_test0000000000000000000","part":{"id":"prt_test0000000000000000001","messageID":"msg_test0000000000000000001","sessionID":"ses_test0000000000000000000","type":"text","text":"I will now call cairn-memory_memory_write to remember this fact.","time":{"start":1,"end":2}}}'
+
+failures=0
+
+# check(name, expected_exit, input, env_assignments...)
+check() {
+  local name="$1" expected_exit="$2" input="$3"
+  shift 3
+  local actual_exit=0
+  printf '%s' "$input" | env "$@" node "$MATCHER" >/dev/null 2>&1 || actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "[test-remember-recall-assertions] PASS: $name"
+  else
+    echo "[test-remember-recall-assertions] FAIL: $name (expected exit $expected_exit, got $actual_exit)" >&2
+    failures=1
+  fi
+}
+
+check "genuine write tool_use event, no canary required -> exit 0" \
+  0 "$WRITE_EVENT" \
+  TOOL_EVENT_REGEX='cairn-memory_memory_(write|supersede)'
+
+check "genuine search tool_use event with matching canary -> exit 0" \
+  0 "$SEARCH_EVENT" \
+  TOOL_EVENT_REGEX='cairn-memory_memory_(search|read)' TOOL_EVENT_CANARY='XYZ123'
+
+check "genuine search tool_use event with a canary absent from output -> exit 1" \
+  1 "$SEARCH_EVENT" \
+  TOOL_EVENT_REGEX='cairn-memory_memory_(search|read)' TOOL_EVENT_CANARY='CANARY-NOT-PRESENT-ANYWHERE'
+
+check "narrated-only text event (D-08 false-positive class) -> exit 1" \
+  1 "$TEXT_NARRATION_EVENT" \
+  TOOL_EVENT_REGEX='cairn-memory_memory_(write|supersede)'
+
+check "empty stdin -> exit 1" \
+  1 "" \
+  TOOL_EVENT_REGEX='cairn-memory_memory_(write|supersede)'
+
+if [[ "$failures" -ne 0 ]]; then
+  echo "[test-remember-recall-assertions] FAIL: one or more fixture cases failed" >&2
+  exit 1
+fi
+echo "[test-remember-recall-assertions] PASS: all 5 fixture cases passed"

package/scripts/transcript-to-text.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// transcript-to-text.mjs — read a Claude/OpenCode JSONL transcript and emit a
+// readable plain-text stream of the conversation (user + assistant text only,
+// tool calls/results trimmed). Piped into `mcp-memory-server extract` so the
+// extraction model sees what actually happened in the session.
+//
+// Usage: node transcript-to-text.mjs <transcript.jsonl> [max-chars]
+//   max-chars defaults to 12000; keeps the most recent turns when truncating.
+'use strict';
+import { readFileSync } from 'node:fs';
+
+const [, , transcriptPath, maxCharsArg] = process.argv;
+const maxChars = parseInt(maxCharsArg ?? '12000', 10);
+
+if (!transcriptPath) {
+  process.stderr.write('transcript-to-text: no transcript path given\n');
+  process.exit(0);
+}
+
+let raw;
+try {
+  raw = readFileSync(transcriptPath, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+const lines = raw.split('\n').filter(Boolean);
+const turns = [];
+for (const line of lines) {
+  let obj;
+  try { obj = JSON.parse(line); } catch { continue; }
+  const role = obj.type || obj.role || obj.message?.role;
+  // Extract text content from common transcript shapes.
+  let text = '';
+  const content = obj.message?.content ?? obj.content;
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .filter((b) => typeof b === 'object' && b && (b.type === 'text' || typeof b.text === 'string'))
+      .map((b) => b.text ?? '')
+      .join('\n');
+  }
+  text = text.trim();
+  if (!text) continue;
+  // Skip pure tool-result noise and system reminders.
+  if (role === 'user' || role === 'human') turns.push(`USER: ${text}`);
+  else if (role === 'assistant' || role === 'ai') turns.push(`ASSISTANT: ${text}`);
+}
+
+let out = turns.join('\n\n');
+if (out.length > maxChars) out = out.slice(-maxChars);
+process.stdout.write(out);

package/scripts/verify-docs-parity.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Docs-vs-code parity checker (SC-02; D-10). Two one-directional checks --
+# code surface must be documented; doc-only names are allowed (e.g.
+# CAIRN_GIT_PROVIDER is read by the CLI/provider layer, not the server, and
+# script-local vars like CAIRN_GUARD_DENYLIST/CAIRN_ROUTE_BINARY are never
+# server config -- neither is a failure):
+#
+#   1. Env-key check: every CAIRN_[A-Z_]+/MCP_HTTP_[A-Z_]+ token read in
+#      mcp-memory-server/src/*.ts (the runtime server config surface --
+#      NOT scripts/ or bin/) must be named somewhere in docs/operating.md
+#      or README.md. `comm -23` on two sorted lists -- code-keys-not-in-
+#      docs -- not a symmetric diff.
+#   2. Command check: every claude/commands/*.md basename must appear in
+#      docs/operating.md.
+#
+# Reports both check results even when the first fails, so a single run
+# surfaces the full drift set. Exits non-zero on any drift, 0 on none.
+
+usage() {
+  cat <<'EOF'
+Usage: verify-docs-parity.sh
+       verify-docs-parity.sh -h|--help
+
+Checks that every CAIRN_*/MCP_HTTP_* env key read by the cairn-memory MCP
+server (mcp-memory-server/src/*.ts) is named in docs/operating.md or
+README.md, and that every claude/commands/*.md command is named in
+docs/operating.md. One-directional: doc-only names are not a failure.
+Prints every missing key/command by name, then exits non-zero on any
+drift, or 0 if the docs are fully in sync with the shipped code.
+EOF
+}
+
+ENV_KEY_PATTERN='(CAIRN_[A-Z_]+|MCP_HTTP_[A-Z_]+)'
+
+# check_env_keys(): comm -23 of sorted code-keys vs sorted doc-keys --
+# code-keys-not-in-docs only (one-directional, per D-10).
+check_env_keys() {
+  local code_keys doc_keys missing
+
+  code_keys=$(grep -ohE "\\b${ENV_KEY_PATTERN}\\b" mcp-memory-server/src/*.ts | sort -u)
+  doc_keys=$(grep -ohE "\\b${ENV_KEY_PATTERN}\\b" docs/operating.md README.md | sort -u)
+
+  missing=$(comm -23 <(printf '%s\n' "$code_keys") <(printf '%s\n' "$doc_keys"))
+
+  if [[ -n "$missing" ]]; then
+    echo "FATAL: env keys read in mcp-memory-server/src but undocumented:" >&2
+    while IFS= read -r key; do
+      [[ -n "$key" ]] && echo "  - $key" >&2
+    done <<<"$missing"
+    return 1
+  fi
+
+  echo "[env-keys] OK: every mcp-memory-server/src env key is named in docs/operating.md or README.md"
+  return 0
+}
+
+# check_commands(): every claude/commands/*.md basename must appear as a
+# documented command reference in docs/operating.md -- either backtick-
+# quoted (the "N commands" enumeration, e.g. `graphify`) or slash-prefixed
+# (the workflow section, e.g. `/remember <fact>`). A bare substring match
+# is too loose: "context-explore" appears in docs/operating.md today only
+# inside an unrelated sync-script filename comment, not as a documented
+# command -- that incidental mention must not count as "documented".
+check_commands() {
+  local failed=0
+  local file name
+
+  for file in claude/commands/*.md; do
+    name=$(basename "$file" .md)
+    if ! grep -qF "\`${name}\`" docs/operating.md && ! grep -qF "/${name}" docs/operating.md; then
+      echo "FATAL: command '$name' (claude/commands/${name}.md) is not named in docs/operating.md" >&2
+      failed=1
+    fi
+  done
+
+  if [[ "$failed" -ne 0 ]]; then
+    return 1
+  fi
+
+  echo "[commands] OK: every claude/commands/*.md command is named in docs/operating.md"
+  return 0
+}
+
+main() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        usage >&2
+        exit 2
+        ;;
+    esac
+  done
+
+  local failed=0
+  check_env_keys || failed=1
+  check_commands || failed=1
+
+  if [[ "$failed" -ne 0 ]]; then
+    echo "FATAL: docs-parity check found drift (see above) -- SC-02 not yet satisfied" >&2
+    exit 1
+  fi
+
+  echo "[parity] OK: docs match shipped code -- no drift found"
+}
+
+main "$@"

package/scripts/verify-explore-maturation.sh

@@ -0,0 +1,288 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Phase 12 composed end-to-end proof: context_explore maturation
+# (CTX-08 cross-referencing, CTX-09 pre-task hook auto-invoke,
+# CTX-10 result caching).
+#
+# Fully offline (no network, no real token_miser) -- every stage drives the
+# real `explore` CLI subcommand or the real hook script against a fake
+# token_miser fixture binary, so it runs in CI. Mirrors
+# verify-token-savings-ab.sh's wrapper/logging-binary technique for proving
+# "the binary was NOT invoked" on a cache hit, and reuses Plan 01/02's
+# smoke-test fixtures (fake-tokenmiser-logging.sh, fake-tokenmiser-crossref.sh)
+# and temp-git-repo + XDG_CACHE_HOME isolation setup.
+#
+# Stages:
+#   --crossref  CTX-08: a seeded memory/wiki entry produces memory_refs/
+#               wiki_refs on the matching citation; the non-matching citation
+#               and a fully unseeded repo stay plain (D-02/D-03/D-04).
+#   --cache     CTX-10: a second identical call returns cached:true and the
+#               binary's invocation counter does NOT increment; a repo change
+#               (tracked-file edit or new untracked file) forces cached:false
+#               and re-invokes the binary.
+#   --hook      CTX-09: a scripted UserPromptSubmit JSON piped through
+#               claude/hooks/context-explore-pretask.sh emits
+#               hookSpecificOutput.additionalContext when double-opted-in
+#               with citations found, and stays silent when gated off or the
+#               prompt is low-signal.
+#   (no stage flag) runs all three stages in sequence.
+#
+# Exits non-zero if any check in any run stage failed.
+
+usage() {
+  cat <<'EOF'
+Usage: verify-explore-maturation.sh [--crossref|--cache|--hook] [-h|--help]
+
+Composed, offline, re-runnable proof of Phase 12's three context_explore
+maturation success criteria: citation cross-referencing (CTX-08), result
+caching (CTX-10), and pre-task hook auto-invoke (CTX-09). Drives the real
+`explore` CLI subcommand and the real hook script against fake token_miser
+fixture binaries -- no network, no live binary required.
+
+Options:
+  --crossref   Run only the CTX-08 cross-reference stage.
+  --cache      Run only the CTX-10 cache stage.
+  --hook       Run only the CTX-09 hook stage.
+  (default)    Run all three stages.
+  -h, --help   Show this help text.
+
+Prerequisite: mcp-memory-server must already be built
+(`cd mcp-memory-server && npm install && npm run build`).
+EOF
+}
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+SERVER_DIR="$ROOT_DIR/mcp-memory-server"
+SERVER_ENTRY="$SERVER_DIR/dist/index.js"
+HOOK_SRC="$ROOT_DIR/claude/hooks/context-explore-pretask.sh"
+FIXTURES_DIR="$SERVER_DIR/scripts/fixtures"
+
+FAILURES=0
+TMP_PATHS=()
+
+cleanup() {
+  local p
+  for p in "${TMP_PATHS[@]:-}"; do
+    [[ -n "$p" ]] && rm -rf "$p"
+  done
+}
+trap cleanup EXIT
+
+mktmp() {
+  local p
+  p=$(mktemp -d)
+  TMP_PATHS+=("$p")
+  printf '%s' "$p"
+}
+
+# check(name, ok): ok is a shell "true"/"false" 0/1-style status string.
+check() {
+  local name="$1" status="$2"
+  if [[ "$status" -eq 0 ]]; then
+    echo "ok: $name"
+  else
+    echo "FAIL: $name" >&2
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
+require_build() {
+  if [[ ! -f "$SERVER_ENTRY" ]]; then
+    echo "FATAL: $SERVER_ENTRY not found -- build the server first:" >&2
+    echo "  cd mcp-memory-server && npm install && npm run build" >&2
+    exit 1
+  fi
+}
+
+git_init_repo() {
+  local repo="$1"
+  git -C "$repo" init -q
+  git -C "$repo" config user.email "verify@example.com"
+  git -C "$repo" config user.name "verify"
+  echo "one" > "$repo/a.txt"
+  git -C "$repo" add a.txt
+  git -C "$repo" commit -q -m init
+}
+
+# seed_memory_wiki(repoRoot, stem): seeds .agentfs/project.db (via a
+# short-lived node subprocess, so the db is unlocked before any later
+# consumer opens it) and a .planning/wiki/sources page mentioning $stem.
+seed_memory_wiki() {
+  local repo="$1" stem="$2"
+  mkdir -p "$repo/.agentfs"
+  node -e "
+    const { AgentFS } = require('$SERVER_DIR/node_modules/agentfs-sdk');
+    (async () => {
+      const agent = await AgentFS.open({ id: 'project', path: '$repo/.agentfs/project.db' });
+      await agent.kv.set('patterns/${stem}-handling', 'notes about ${stem} module behavior');
+      await agent.close();
+    })();
+  " >/dev/null
+  mkdir -p "$repo/.planning/wiki/sources"
+  printf '# %s notes\n\n- **%s module behavior is documented here.**\n' "$stem" "$stem" \
+    > "$repo/.planning/wiki/sources/${stem}-notes.md"
+}
+
+# --- Stage: CTX-08 cross-reference ---
+stage_crossref() {
+  echo "=== CTX-08: citation cross-referencing ==="
+  local fixture="$FIXTURES_DIR/fake-tokenmiser-crossref.sh"
+  chmod +x "$fixture"
+
+  local seeded bare xdg out widget gadget st
+  seeded=$(mktmp)
+  git_init_repo "$seeded"
+  seed_memory_wiki "$seeded" "widget"
+  xdg=$(mktmp)
+
+  # The CLI takes the query as argv[3]; repo_root is resolved from
+  # CAIRN_EXPLORE_REPO_ROOT (no --repo-root flag on the CLI subcommand).
+  out=$(XDG_CACHE_HOME="$xdg" CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_CACHE=0 \
+    CAIRN_EXPLORE_REPO_ROOT="$seeded" node "$SERVER_ENTRY" explore "anything" 2>/dev/null || true)
+
+  [[ "$(echo "$out" | jq -r '.ok // false')" == "true" ]]; check "seeded run is ok:true" $?
+  widget=$(echo "$out" | jq -c '.citations[] | select(.path == "src/widget.rs")')
+  gadget=$(echo "$out" | jq -c '.citations[] | select(.path == "src/gadget.rs")')
+
+  [[ "$(echo "$widget" | jq -r '(.memory_refs // []) | length')" -gt 0 ]]; check "matching citation (src/widget.rs) has non-empty memory_refs" $?
+  [[ "$(echo "$widget" | jq -r '(.wiki_refs // []) | length')" -gt 0 ]]; check "matching citation (src/widget.rs) has non-empty wiki_refs" $?
+  [[ "$(echo "$gadget" | jq -r 'has("memory_refs")')" == "false" ]]; check "non-matching citation (src/gadget.rs) has no memory_refs" $?
+  [[ "$(echo "$gadget" | jq -r 'has("wiki_refs")')" == "false" ]]; check "non-matching citation (src/gadget.rs) has no wiki_refs" $?
+
+  bare=$(mktmp)
+  git_init_repo "$bare"
+  out=$(XDG_CACHE_HOME="$xdg" CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_CACHE=0 \
+    CAIRN_EXPLORE_REPO_ROOT="$bare" node "$SERVER_ENTRY" explore "anything" 2>/dev/null || true)
+  [[ "$(echo "$out" | jq -r '.ok // false')" == "true" ]]; check "bare (no-seed) run is ok:true" $?
+  [[ "$(echo "$out" | jq -r '[.citations[] | (has("memory_refs") or has("wiki_refs"))] | any')" == "false" ]]
+  check "bare run: no citation has memory_refs/wiki_refs (fail-open, byte-identical output)" $?
+}
+
+# --- Stage: CTX-10 cache ---
+stage_cache() {
+  echo "=== CTX-10: result cache ==="
+  local fixture="$FIXTURES_DIR/fake-tokenmiser-logging.sh"
+  chmod +x "$fixture"
+
+  local repo xdg hitlog
+  repo=$(mktmp)
+  git_init_repo "$repo"
+  xdg=$(mktmp)
+  hitlog="$(mktmp)/hits.log"
+
+  run_explore() {
+    XDG_CACHE_HOME="$xdg" CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_REPO_ROOT="$repo" \
+      EXPLORE_HIT_LOG="$hitlog" node "$SERVER_ENTRY" explore "find the foo function" 2>/dev/null
+  }
+  invocation_count() {
+    [[ -f "$hitlog" ]] && grep -c . "$hitlog" || echo 0
+  }
+
+  local first second third
+  first=$(run_explore)
+  [[ "$(echo "$first" | jq -r '.ok // false')" == "true" ]]; check "first call is ok:true" $?
+  [[ "$(echo "$first" | jq -r '.cached')" == "false" ]]; check "first call is cached:false (cache miss)" $?
+  [[ "$(invocation_count)" -eq 1 ]]; check "first call spawned the binary exactly once" $?
+
+  second=$(run_explore)
+  [[ "$(echo "$second" | jq -r '.cached')" == "true" ]]; check "second identical call is cached:true" $?
+  [[ "$(invocation_count)" -eq 1 ]]; check "second identical call did NOT re-spawn the binary" $?
+
+  echo "two" > "$repo/a.txt"
+  third=$(run_explore)
+  [[ "$(echo "$third" | jq -r '.cached')" == "false" ]]; check "call after a tracked-file edit is cached:false" $?
+  [[ "$(invocation_count)" -eq 2 ]]; check "call after a tracked-file edit re-spawns the binary" $?
+
+  echo "one" > "$repo/a.txt"
+  echo "new" > "$repo/untracked.txt"
+  local untracked_call
+  untracked_call=$(run_explore)
+  [[ "$(echo "$untracked_call" | jq -r '.cached')" == "false" ]]; check "call after a new untracked file is cached:false" $?
+  [[ "$(invocation_count)" -eq 3 ]]; check "call after a new untracked file re-spawns the binary" $?
+}
+
+# --- Stage: CTX-09 pre-task hook ---
+stage_hook() {
+  echo "=== CTX-09: pre-task auto-invoke hook ==="
+  local fixture="$FIXTURES_DIR/fake-tokenmiser-crossref.sh"
+  chmod +x "$fixture"
+
+  local rendered repo xdg
+  rendered=$(mktmp)/hook.sh
+  mkdir -p "$(dirname "$rendered")"
+  sed "s|@@INFRA_ROOT@@|$ROOT_DIR|g" "$HOOK_SRC" > "$rendered"
+  chmod +x "$rendered"
+
+  repo=$(mktmp)
+  git_init_repo "$repo"
+  xdg=$(mktmp)
+
+  local prompt='where is the widget module implemented in this repo'
+  local stdin_json
+  stdin_json=$(jq -n --arg prompt "$prompt" '{prompt: $prompt}')
+
+  local gated_on
+  gated_on=$(CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_AUTOINVOKE=1 CAIRN_EXPLORE_CACHE=0 \
+    CAIRN_EXPLORE_REPO_ROOT="$repo" XDG_CACHE_HOME="$xdg" \
+    bash -c "printf '%s' '$stdin_json' | bash '$rendered'")
+  [[ -n "$gated_on" ]] && echo "$gated_on" | jq -e '.hookSpecificOutput.additionalContext | length > 0' >/dev/null 2>&1
+  check "gated-on high-signal prompt injects hookSpecificOutput.additionalContext" $?
+
+  local gated_off
+  gated_off=$(CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_CACHE=0 \
+    CAIRN_EXPLORE_REPO_ROOT="$repo" XDG_CACHE_HOME="$xdg" \
+    bash -c "printf '%s' '$stdin_json' | bash '$rendered'")
+  [[ -z "$gated_off" ]]; check "gated-off (CAIRN_EXPLORE_AUTOINVOKE unset) stays silent" $?
+
+  local low_signal_json low_signal_out
+  low_signal_json=$(jq -n '{prompt: "ok"}')
+  low_signal_out=$(CAIRN_EXPLORE_BINARY="$fixture" CAIRN_EXPLORE_AUTOINVOKE=1 CAIRN_EXPLORE_CACHE=0 \
+    CAIRN_EXPLORE_REPO_ROOT="$repo" XDG_CACHE_HOME="$xdg" \
+    bash -c "printf '%s' '$low_signal_json' | bash '$rendered'")
+  [[ -z "$low_signal_out" ]]; check "low-signal prompt (bare ack) stays silent even when gated on" $?
+}
+
+main() {
+  local stage=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --crossref|--cache|--hook)
+        stage="$1"
+        shift
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        usage >&2
+        exit 2
+        ;;
+    esac
+  done
+
+  require_build
+
+  case "$stage" in
+    --crossref) stage_crossref ;;
+    --cache) stage_cache ;;
+    --hook) stage_hook ;;
+    "")
+      stage_crossref
+      stage_cache
+      stage_hook
+      ;;
+  esac
+
+  if [[ "$FAILURES" -ne 0 ]]; then
+    echo "" >&2
+    echo "FATAL: $FAILURES check(s) failed" >&2
+    exit 1
+  fi
+  echo ""
+  echo "All Phase 12 context_explore maturation checks passed (CTX-08/09/10)."
+}
+
+main "$@"