@cairnkeep/cli 1.0.2

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cairnkeep/cli",
+  "version": "1.0.2",
+  "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "cairn": "bin/cairn"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "templates/",
+    "claude/",
+    "opencode/",
+    "docs/",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "mcp-memory-server/dist/",
+    "mcp-memory-server/package.json",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "agentfs-sdk": "^0.6.4",
+    "zod": "^3.25.76"
+  },
+  "scripts": {
+    "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
+    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm test",
+    "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server ci && npm --prefix mcp-memory-server test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cairnkeep/cairnkeep.git"
+  },
+  "homepage": "https://github.com/cairnkeep/cairnkeep#readme",
+  "bugs": {
+    "url": "https://github.com/cairnkeep/cairnkeep/issues"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "agent",
+    "claude-code",
+    "opencode",
+    "context",
+    "rag"
+  ]
+}

package/scripts/bootstrap.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Cairnkeep project bootstrap (core). Scaffolds a project's .ai/ launchers and a
+# .planning/ derived-knowledge layer from the bundled templates. Generic and
+# provider-neutral; variants can wrap this and add their own launchers/env.
+set -euo pipefail
+
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+TPL="$CAIRN_ROOT/templates"
+
+untracked=0
+target="."
+for arg in "$@"; do
+  case "$arg" in
+    --untracked) untracked=1 ;;
+    -*)
+      echo "Unknown option: $arg" >&2
+      echo "Usage: bootstrap.sh [--untracked] [path]" >&2
+      exit 1
+      ;;
+    *) target="$arg" ;;
+  esac
+done
+if [[ ! -d "$target" ]]; then
+  echo "Bootstrap target is not a directory: $target" >&2
+  exit 1
+fi
+target=$(cd "$target" && pwd)
+
+# Contributor mode: keep the scaffold invisible to git via .git/info/exclude
+# (per-clone, never touches the repo's .gitignore). Resolve everything up
+# front so a non-repo target fails before any files are created.
+exclude_file=""
+exclude_prefix=""
+if [[ $untracked -eq 1 ]]; then
+  if ! exclude_file=$(cd "$target" && git rev-parse --git-path info/exclude 2>/dev/null); then
+    echo "--untracked requires the target to be inside a git repository: $target" >&2
+    exit 1
+  fi
+  [[ "$exclude_file" == /* ]] || exclude_file="$target/$exclude_file"
+  exclude_prefix=$(cd "$target" && git rev-parse --show-prefix)
+fi
+
+install_file() {
+  local src="$1" dest="$2" mode="$3"
+  if [[ -e "$dest" ]]; then
+    echo "skip (exists): ${dest#"$target"/}"
+    return 0
+  fi
+  mkdir -p "$(dirname "$dest")"
+  cp "$src" "$dest"
+  chmod "$mode" "$dest"
+  echo "created: ${dest#"$target"/}"
+}
+
+# .ai/ launchers + env
+install_file "$TPL/start-claude.sh.template"   "$target/.ai/start-claude.sh"   0755
+install_file "$TPL/start-opencode.sh.template" "$target/.ai/start-opencode.sh" 0755
+install_file "$TPL/env.example.template"       "$target/.ai/env.example"       0644
+
+# .planning/ derived-knowledge layer  (template : destination)
+planning_pairs=(
+  "planning-config.json.template:.planning/config.json"
+  "project-brief.md.template:.planning/PROJECT-BRIEF.md"
+  "wiki-index.md.template:.planning/wiki/index.md"
+  "wiki-policy.md.template:.planning/wiki/policy.md"
+  "wiki-contradictions.md.template:.planning/wiki/CONTRADICTIONS.md"
+  "wiki-log.md.template:.planning/wiki/LOG.md"
+  "alignment-policy.md.template:.planning/alignment/policy.md"
+  "alignment-gap-register.yaml.template:.planning/alignment/gap-register.yaml"
+  "graph-policy.md.template:.planning/graphs/policy.md"
+  "graphs-gitignore.template:.planning/graphs/.gitignore"
+  "security-policy.md.template:.planning/security/policy.md"
+)
+for pair in "${planning_pairs[@]}"; do
+  install_file "$TPL/${pair%%:*}" "$target/${pair#*:}" 0644
+done
+
+if [[ $untracked -eq 1 ]]; then
+  mkdir -p "$(dirname "$exclude_file")"
+  for entry in "/${exclude_prefix}.ai/" "/${exclude_prefix}.planning/"; do
+    if grep -qxF "$entry" "$exclude_file" 2>/dev/null; then
+      echo "skip (already excluded): $entry"
+    else
+      echo "$entry" >>"$exclude_file"
+      echo "excluded: $entry"
+    fi
+  done
+  echo "Contributor mode: scaffold is local-only (${exclude_file#"$target"/});"
+  echo "it is never committed, so it lives on this machine only."
+fi
+
+echo
+echo "Cairnkeep bootstrapped into $target"
+echo "Next steps (full guide: docs/operating.md):"
+echo "  1. cp .ai/env.example .ai/.env  and edit"
+echo "  2. Build + register the memory server: cd mcp-memory-server && npm install && npm run build,"
+echo "     then: claude mcp add cairn-memory -s user -- node \"\$PWD/dist/index.js\""
+echo "  3. Install the operating layer (commands/agents/hooks): scripts/sync-claude-assets.sh --apply"
+echo "  4. Launch: $target/.ai/start-claude.sh"

package/scripts/doctor.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# cairn doctor — post-bootstrap health check.
+#
+# Reports pass/warn/skip/fail for the pieces cairnkeep needs, reading only what
+# is already configured in ./.ai/.env (or the current environment). Unconfigured
+# optional dependencies are SKIPPED, never failed. Exits non-zero only if a
+# CONFIGURED dependency is unreachable, so a green run means "the things you
+# turned on actually work".
+set -uo pipefail
+
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+# Load the project's .ai/.env if present (does not override already-set env).
+if [[ -f "$PWD/.ai/.env" ]]; then
+  set -a
+  # shellcheck disable=SC1091
+  . "$PWD/.ai/.env"
+  set +a
+fi
+
+fails=0
+pass() { printf '  [PASS] %s\n' "$1"; }
+warn() { printf '  [WARN] %s\n' "$1"; }
+skip() { printf '  [SKIP] %s\n' "$1"; }
+fail() { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
+
+# curl returns 0 once the endpoint answers at all (any HTTP status counts as
+# reachable); a connect/timeout failure returns non-zero.
+reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
+
+echo "cairn doctor"
+
+# 1. Memory server built (local prerequisite; actionable warning, not a failure).
+if [[ -f "$CAIRN_ROOT/mcp-memory-server/dist/index.js" ]]; then
+  pass "memory server built (mcp-memory-server/dist/index.js)"
+else
+  warn "memory server not built — run: (cd \"$CAIRN_ROOT/mcp-memory-server\" && npm install && npm run build)"
+fi
+
+# 2. LLM extraction endpoint (optional; unset → substring-only memory search).
+if [[ -n "${CAIRN_LLM_API_URL:-}" ]]; then
+  if ! command -v curl >/dev/null 2>&1; then
+    skip "LLM endpoint: curl not installed, cannot probe ${CAIRN_LLM_API_URL}"
+  elif reachable "$CAIRN_LLM_API_URL"; then
+    pass "LLM endpoint reachable (${CAIRN_LLM_API_URL})"
+  else
+    fail "LLM endpoint unreachable (${CAIRN_LLM_API_URL})"
+  fi
+else
+  skip "LLM endpoint (CAIRN_LLM_API_URL unset — memory search degrades to substring)"
+fi
+
+# 3. Embedding endpoint (optional).
+if [[ -n "${CAIRN_MEMORY_EMBEDDING_URL:-}" ]]; then
+  if ! command -v curl >/dev/null 2>&1; then
+    skip "embedding endpoint: curl not installed, cannot probe ${CAIRN_MEMORY_EMBEDDING_URL}"
+  elif reachable "$CAIRN_MEMORY_EMBEDDING_URL"; then
+    pass "embedding endpoint reachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+  else
+    fail "embedding endpoint unreachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+  fi
+else
+  skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"
+fi
+
+# 4. Git provider (collaboration commands). Report configuration only — auth is
+#    provider- and host-specific and lives in the wrapper, not the core.
+case "${CAIRN_GIT_PROVIDER:-}" in
+  "" | none) skip "git provider (CAIRN_GIT_PROVIDER unset/none — collaboration commands off)" ;;
+  github | gitlab | codeberg | forgejo) pass "git provider configured: ${CAIRN_GIT_PROVIDER}" ;;
+  *) warn "git provider '${CAIRN_GIT_PROVIDER}' is not one of github|gitlab|codeberg|forgejo|none" ;;
+esac
+
+# 5. Memory store location (created on first write; report + writability).
+store_dir="${CAIRN_AGENTFS_BASE_DIR:-$HOME/.cairnkeep}"
+store_dir="${store_dir/#\~/$HOME}"
+if [[ -d "$store_dir" ]]; then
+  if [[ -w "$store_dir" ]]; then pass "memory store: $store_dir (exists, writable)"
+  else fail "memory store not writable: $store_dir"; fi
+else
+  parent=$(dirname "$store_dir")
+  if [[ -w "$parent" ]]; then pass "memory store: $store_dir (will be created on first write)"
+  else fail "memory store parent not writable: $parent"; fi
+fi
+
+echo
+if [[ "$fails" -gt 0 ]]; then
+  echo "cairn doctor: $fails configured dependency check(s) failed."
+  exit 1
+fi
+echo "cairn doctor: OK (configured dependencies healthy)."

package/scripts/install-audit-timer.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# install-audit-timer.sh — opt-in scheduler for memory-wiki-audit.sh.
+#
+# Renders a systemd user service + timer from templates/ and enables the timer,
+# so the deterministic memory/wiki invalidation audit runs on a schedule. A cron
+# alternative is printed for hosts without systemd.
+#
+# Usage: install-audit-timer.sh [--para-root PATH] [--on-calendar SPEC]
+#                               [--report PATH] [--render-only DIR]
+#   --para-root PATH    root the audit scans (default: $HOME/PARA)
+#   --on-calendar SPEC  systemd OnCalendar schedule (default: daily)
+#   --report PATH       where the audit writes its report
+#   --render-only DIR   render the unit files into DIR and exit (no systemctl)
+set -euo pipefail
+
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+TPL="$CAIRN_ROOT/templates"
+AUDIT_SCRIPT="$CAIRN_ROOT/scripts/memory-wiki-audit.sh"
+
+PARA_ROOT="${HOME}/PARA"
+ON_CALENDAR="daily"
+REPORT_PATH="${HOME}/.cairnkeep/memory-wiki-audit.report.md"
+RENDER_ONLY=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --para-root) PARA_ROOT="$2"; shift 2 ;;
+    --on-calendar) ON_CALENDAR="$2"; shift 2 ;;
+    --report) REPORT_PATH="$2"; shift 2 ;;
+    --render-only) RENDER_ONLY="$2"; shift 2 ;;
+    -h|--help) sed -n '2,16p' "$0"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+render() {
+  sed -e "s|@@AUDIT_SCRIPT@@|${AUDIT_SCRIPT}|g" \
+      -e "s|@@PARA_ROOT@@|${PARA_ROOT}|g" \
+      -e "s|@@REPORT_PATH@@|${REPORT_PATH}|g" \
+      -e "s|@@ON_CALENDAR@@|${ON_CALENDAR}|g" \
+      "$1"
+}
+
+cron_line="@daily ${AUDIT_SCRIPT} --para-root ${PARA_ROOT} --report ${REPORT_PATH}"
+
+if [[ -n "$RENDER_ONLY" ]]; then
+  mkdir -p "$RENDER_ONLY"
+  render "$TPL/memory-wiki-audit.service.template" > "$RENDER_ONLY/memory-wiki-audit.service"
+  render "$TPL/memory-wiki-audit.timer.template"   > "$RENDER_ONLY/memory-wiki-audit.timer"
+  echo "rendered unit files into $RENDER_ONLY"
+  exit 0
+fi
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "systemctl not found. Use --render-only DIR, or schedule via cron:" >&2
+  echo "  $cron_line" >&2
+  exit 1
+fi
+
+UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+mkdir -p "$UNIT_DIR"
+mkdir -p "$(dirname "$REPORT_PATH")"
+render "$TPL/memory-wiki-audit.service.template" > "$UNIT_DIR/memory-wiki-audit.service"
+render "$TPL/memory-wiki-audit.timer.template"   > "$UNIT_DIR/memory-wiki-audit.timer"
+systemctl --user daemon-reload
+systemctl --user enable --now memory-wiki-audit.timer
+echo "installed + enabled memory-wiki-audit.timer (OnCalendar=${ON_CALENDAR})"
+echo "cron alternative: ${cron_line}"

package/scripts/lib/assert-tool-event.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// scripts/lib/assert-tool-event.mjs
+//
+// Reads NDJSON (opencode `run --format json` style events) from stdin and
+// exits 0 the moment a genuine tool_use event matches TOOL_EVENT_REGEX (and,
+// if TOOL_EVENT_CANARY is set, whose part.state.output contains it); exits 1
+// otherwise. A narrated-but-unexecuted mention of a tool name inside a
+// "text" event's part.text never matches — only a real top-level
+// type === "tool_use" event with part.state.status === "completed" does
+// (D-08/D-09, 13-RESEARCH.md Pattern 2).
+//
+// TOOL_EVENT_REGEX and TOOL_EVENT_CANARY are read ONLY from process.env
+// (never argv string-interpolation), so an adversarial canary value can't
+// inject into the matcher — mirrors seed_canary()'s env-var-passing idiom
+// in scripts/verify-opencode-live-parity.sh.
+
+const toolEventRegexSource = process.env.TOOL_EVENT_REGEX;
+if (!toolEventRegexSource) {
+  process.stderr.write("assert-tool-event: TOOL_EVENT_REGEX env var is required\n");
+  process.exit(1);
+}
+const toolEventRegex = new RegExp(toolEventRegexSource);
+const canary = process.env.TOOL_EVENT_CANARY || "";
+
+let data = "";
+process.stdin.on("data", (c) => { data += c; });
+process.stdin.on("end", () => {
+  for (const line of data.split("\n")) {
+    if (!line.trim()) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      // Not a JSON line (e.g. interleaved log noise) — skip, never abort
+      // the scan on a malformed line (T-13-01).
+      continue;
+    }
+    if (
+      parsed.type === "tool_use" &&
+      toolEventRegex.test(parsed.part?.tool || "") &&
+      parsed.part?.state?.status === "completed"
+    ) {
+      if (canary && !String(parsed.part?.state?.output ?? "").includes(canary)) {
+        continue;
+      }
+      process.exit(0);
+    }
+  }
+  process.exit(1);
+});

package/scripts/memory-store.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# cairn memory <path|export|import> — relocate the durable memory store between
+# machines or backends.
+#
+# The store is one SQLite .db per scope under CAIRN_AGENTFS_BASE_DIR
+# (default ~/.cairnkeep). `export` takes a WAL-safe snapshot of every scope db
+# into a portable archive; `import` restores them on another machine; `path`
+# prints the store location so nothing has to guess where it lives.
+set -euo pipefail
+
+base="${CAIRN_AGENTFS_BASE_DIR:-$HOME/.cairnkeep}"
+base="${base/#\~/$HOME}"
+
+usage() {
+  cat <<'EOF'
+Usage: cairn memory <path|export|import>
+  path                 Print the memory store base directory.
+  export <file.tgz>    WAL-safe snapshot of every scope .db into a portable archive.
+  import <file.tgz>    Restore scope .db files from an archive (backs up existing).
+EOF
+}
+
+sub="${1:-help}"
+[[ $# -gt 0 ]] && shift
+
+case "$sub" in
+  path)
+    echo "$base"
+    ;;
+  export)
+    out="${1:?usage: cairn memory export <file.tgz>}"
+    command -v sqlite3 >/dev/null 2>&1 || { echo "sqlite3 is required for a WAL-safe export" >&2; exit 1; }
+    [[ -d "$base" ]] || { echo "no memory store directory at $base" >&2; exit 1; }
+    tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+    n=0
+    for db in "$base"/*.db; do
+      [[ -e "$db" ]] || continue
+      # .backup yields a consistent copy even while the store is in WAL mode.
+      sqlite3 "$db" ".backup '$tmp/$(basename "$db")'"
+      n=$((n + 1))
+    done
+    [[ $n -gt 0 ]] || { echo "no scope .db files under $base — nothing to export" >&2; exit 1; }
+    tar -C "$tmp" -czf "$out" .
+    echo "exported $n scope db file(s) from $base -> $out"
+    ;;
+  import)
+    in="${1:?usage: cairn memory import <file.tgz>}"
+    [[ -f "$in" ]] || { echo "no such archive: $in" >&2; exit 1; }
+    mkdir -p "$base"
+    tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+    tar -C "$tmp" -xzf "$in"
+    n=0
+    for db in "$tmp"/*.db; do
+      [[ -e "$db" ]] || continue
+      dest="$base/$(basename "$db")"
+      [[ -f "$dest" ]] && cp -f "$dest" "$dest.bak-pre-import"
+      cp -f "$db" "$dest"
+      n=$((n + 1))
+    done
+    [[ $n -gt 0 ]] || { echo "archive contained no scope .db files: $in" >&2; exit 1; }
+    echo "imported $n scope db file(s) -> $base"
+    ;;
+  help | -h | --help)
+    usage
+    ;;
+  *)
+    echo "Unknown: cairn memory $sub" >&2
+    usage >&2
+    exit 1
+    ;;
+esac

package/scripts/memory-wiki-audit.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# memory-wiki-audit.sh — periodic invalidation scanner for the memory + wiki layers.
+#
+# Scans every project under PARA_ROOT that has a .planning/wiki/ for:
+#   1. stale wiki source pages (Last reviewed older than STALE_DAYS)
+#   2. open hard contradictions in CONTRADICTIONS.md
+#   3. orphan source pages not linked from index.md
+#   4. unreviewed memory candidates staged longer than STALE_DAYS
+#
+# Output: a consolidated markdown report on stdout (and optionally to REPORT_PATH).
+# Designed for a systemd timer or cron. Pure bash/grep — no model round-trip, so
+# it is reliable and cheap. The model-driven deep lint (/wiki-lint) still needs
+# to run inside a session; this is the deterministic backstop that runs on a
+# schedule and tells you where to focus.
+#
+# Usage: memory-wiki-audit.sh [--para-root PATH] [--stale-days N] [--report PATH]
+#   --para-root PATH   root to scan (default: $HOME/PARA)
+#   --stale-days N     staleness threshold in days (default: 30)
+#   --report PATH      also write the report to this file
+set -euo pipefail
+
+PARA_ROOT="${HOME}/PARA"
+STALE_DAYS=30
+REPORT_PATH=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --para-root) PARA_ROOT="$2"; shift 2 ;;
+    --stale-days) STALE_DAYS="$2"; shift 2 ;;
+    --report) REPORT_PATH="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+cutoff_epoch="$(date -u -d "$STALE_DAYS days ago" +%s 2>/dev/null || date -u -v-${STALE_DAYS}d +%s 2>/dev/null || echo 0)"
+
+stale_total=0
+hard_open_total=0
+orphan_total=0
+staged_stale_total=0
+sections=()
+
+# Find every project with a wiki.
+while IFS= read -r wiki_dir; do
+  proj_dir="$(dirname "$(dirname "$wiki_dir")")"
+  proj_name="$(basename "$proj_dir")"
+  proj_findings=()
+
+  # 1. Stale source pages (Last reviewed older than cutoff).
+  stale_pages=()
+  if [[ -d "$wiki_dir/sources" ]]; then
+    while IFS= read -r page; do
+      [[ -n "$page" ]] || continue
+      lr="$(grep -m1 -iE '^[-*] \*?\*?Last reviewed\*?\*?:' "$page" 2>/dev/null | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' || true)"
+      if [[ -n "$lr" ]]; then
+        lr_epoch="$(date -u -d "$lr" +%s 2>/dev/null || echo 9999999999)"
+        if (( lr_epoch < cutoff_epoch )); then
+          stale_pages+=("$(basename "$page") (reviewed $lr)")
+        fi
+      fi
+    done < <(find "$wiki_dir/sources" -maxdepth 1 -name '*.md' -type f 2>/dev/null)
+  fi
+  if (( ${#stale_pages[@]} > 0 )); then
+    proj_findings+=("- stale source pages (${#stale_pages[@]}): ${stale_pages[*]}")
+    stale_total=$((stale_total + ${#stale_pages[@]}))
+  fi
+
+  # 2. Open hard contradictions.
+  contras="$wiki_dir/CONTRADICTIONS.md"
+  hard_open=0
+  if [[ -f "$contras" ]]; then
+    # Count open entries tagged hard in the Open section.
+    open_block="$(sed -n '/wiki:contradictions:open:start/,/wiki:contradictions:open:end/p' "$contras" 2>/dev/null || true)"
+    hard_open="$(printf '%s' "$open_block" | grep -ciE 'severity: hard|hard contradiction' 2>/dev/null || true)"
+    hard_open="$(printf '%s' "${hard_open:-0}" | tr -dc '0-9')"
+    hard_open="${hard_open:-0}"
+  fi
+  if (( hard_open > 0 )); then
+    proj_findings+=("- open HARD contradictions: $hard_open")
+    hard_open_total=$((hard_open_total + hard_open))
+  fi
+
+  # 3. Orphan source pages (in sources/ but not named in index.md).
+  orphans=()
+  if [[ -f "$wiki_dir/index.md" ]] && [[ -d "$wiki_dir/sources" ]]; then
+    while IFS= read -r page; do
+      [[ -n "$page" ]] || continue
+      base="$(basename "$page")"
+      grep -qF "$base" "$wiki_dir/index.md" 2>/dev/null || orphans+=("$base")
+    done < <(find "$wiki_dir/sources" -maxdepth 1 -name '*.md' -type f 2>/dev/null)
+  fi
+  if (( ${#orphans[@]} > 0 )); then
+    proj_findings+=("- orphan source pages (${#orphans[@]}): ${orphans[*]}")
+    orphan_total=$((orphan_total + ${#orphans[@]}))
+  fi
+
+  # 4. Unreviewed staged memory candidates older than threshold.
+  staging="$proj_dir/.planning/memory-staging"
+  staged_stale=0
+  if [[ -d "$staging" ]]; then
+    while IFS= read -r sf; do
+      [[ -n "$sf" ]] || continue
+      sf_epoch="$(stat -c %Y "$sf" 2>/dev/null || stat -f %m "$sf" 2>/dev/null || echo 9999999999)"
+      if (( sf_epoch < cutoff_epoch )); then
+        staged_stale=$((staged_stale + 1))
+      fi
+    done < <(find "$staging" -maxdepth 1 -name '*.json' -type f 2>/dev/null)
+  fi
+  if (( staged_stale > 0 )); then
+    proj_findings+=("- unreviewed staged memory candidates (>$STALE_DAYS days): $staged_stale")
+    staged_stale_total=$((staged_stale_total + staged_stale))
+  fi
+
+  if (( ${#proj_findings[@]} > 0 )); then
+    sections+=("### $proj_name" "" "${proj_findings[@]}" "")
+  fi
+done < <(find "$PARA_ROOT" -maxdepth 4 -type d -name wiki -path '*/.planning/wiki' 2>/dev/null)
+
+# Build report once, output to stdout (and REPORT_PATH if set).
+report_body="$(
+  {
+    echo "# Memory + Wiki Audit Report"
+    echo
+    echo "- Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo "- Scope: $PARA_ROOT (staleness threshold: $STALE_DAYS days)"
+    echo "- Stale source pages: $stale_total"
+    echo "- Open hard contradictions: $hard_open_total"
+    echo "- Orphan source pages: $orphan_total"
+    echo "- Unreviewed staged candidates: $staged_stale_total"
+    echo
+    if (( ${#sections[@]} > 0 )); then
+      echo "## Findings by project"
+      echo
+      printf '%s\n' "${sections[@]}"
+    else
+      echo "## No findings"
+      echo
+      echo "All scanned projects are within thresholds."
+    fi
+  }
+)"
+
+printf '%s\n' "$report_body"
+
+if [[ -n "$REPORT_PATH" ]]; then
+  mkdir -p "$(dirname "$REPORT_PATH")"
+  printf '%s\n' "$report_body" > "$REPORT_PATH"
+fi
+
+# Exit non-zero if there are actionable findings (useful for cron alerting).
+if (( stale_total + hard_open_total + orphan_total + staged_stale_total > 0 )); then
+  exit 3
+fi
+exit 0