@cairnkeep/cli 2.3.1 → 2.4.0

package/scripts/sync-opencode-graphify-assets.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 usage() {
   cat <<'EOF'
-Usage: sync-opencode-graphify-assets.sh [--check|--apply] [--live-root PATH]
+Usage: sync-opencode-graphify-assets.sh [--check|--apply] [--capability-overlay] [--live-root PATH]
 
 Compare or sync the repo-managed Graphify OpenCode command asset against the
 live OpenCode config tree.
@@ -11,12 +11,17 @@ live OpenCode config tree.
 Options:
   --check            Verify that the managed live asset matches the repo copy (default)
   --apply            Copy the repo-managed asset into the live OpenCode tree, then verify
+  --capability-overlay
+                     Select the guarded command overlay for a contract-enabled isolated root
   --live-root PATH   Override the live OpenCode root (default: $OPENCODE_CONFIG_DIR or $HOME/.config/opencode)
   -h, --help         Show this help text
 
 Notes:
   - The repo-managed source of truth lives under ./opencode/
   - This script manages only the /graphify command asset
+  - Plugin installation is delegated to sync-opencode-plugin-assets.sh;
+    --capability-overlay selects its native plugin only when the master switch is on
+  - The command asset always retains its legacy owner and bytes
 EOF
 }
 
@@ -24,6 +29,7 @@ ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 SOURCE_ROOT="$ROOT_DIR/opencode"
 LIVE_ROOT="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
 MODE="check"
+CAPABILITY_OVERLAY=0
 
 ASSETS=(
   "command/graphify.md"
@@ -39,6 +45,10 @@ while [[ $# -gt 0 ]]; do
       MODE="apply"
       shift
       ;;
+    --capability-overlay)
+      CAPABILITY_OVERLAY=1
+      shift
+      ;;
     --live-root)
       LIVE_ROOT="$2"
       shift 2
@@ -55,6 +65,11 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+source_for() {
+  local rel="$1"
+  printf '%s\n' "$SOURCE_ROOT/$rel"
+}
+
 ensure_source_assets_exist() {
   local rel
   local missing=0
@@ -79,7 +94,7 @@ check_asset_sync() {
   local -a mismatched=()
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     if [[ ! -f "$dst" ]]; then
@@ -125,7 +140,7 @@ run_apply() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     mkdir -p "$(dirname "$dst")"
@@ -150,3 +165,9 @@ case "$MODE" in
     run_apply
     ;;
 esac
+
+plugin_args=("--$MODE" "--live-root" "$LIVE_ROOT")
+if [[ "$CAPABILITY_OVERLAY" -eq 1 ]]; then
+  plugin_args+=("--capability-overlay")
+fi
+"$ROOT_DIR/scripts/sync-opencode-plugin-assets.sh" "${plugin_args[@]}"

package/scripts/sync-opencode-plugin-assets.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 usage() {
   cat <<'EOF'
-Usage: sync-opencode-plugin-assets.sh [--check|--apply] [--live-root PATH]
+Usage: sync-opencode-plugin-assets.sh [--check|--apply] [--capability-overlay] [--live-root PATH]
 
 Compare or sync the repo-managed OpenCode plugin assets against the live
 OpenCode config tree.
@@ -11,6 +11,8 @@ OpenCode config tree.
 Options:
   --check            Verify that the managed live assets match the repo copies (default)
   --apply            Copy the repo-managed assets into the live OpenCode tree, then verify
+  --capability-overlay
+                     Include the native capability plugin only when CAIRN_CAPABILITY_CONTRACT is enabled
   --live-root PATH   Override the live OpenCode root (default: $OPENCODE_CONFIG_DIR or $HOME/.config/opencode)
   -h, --help         Show this help text
 
@@ -24,6 +26,7 @@ ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 SOURCE_ROOT="$ROOT_DIR/opencode"
 LIVE_ROOT="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
 MODE="check"
+CAPABILITY_OVERLAY=0
 
 ASSETS=(
   "plugins/memory-wakeup.ts"
@@ -41,6 +44,10 @@ while [[ $# -gt 0 ]]; do
       MODE="apply"
       shift
       ;;
+    --capability-overlay)
+      CAPABILITY_OVERLAY=1
+      shift
+      ;;
     --live-root)
       LIVE_ROOT="$2"
       shift 2
@@ -57,6 +64,23 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+case "${CAIRN_CAPABILITY_CONTRACT:-}" in
+  1|true|TRUE|yes|YES|on|ON)
+    if [[ "$CAPABILITY_OVERLAY" -eq 1 ]]; then
+      ASSETS+=("plugins/capability-command.ts")
+    fi
+    ;;
+esac
+
+source_asset() {
+  local rel="$1"
+  if [[ "$rel" == "plugins/capability-command.ts" ]]; then
+    printf '%s\n' "$SOURCE_ROOT/capability-contract/plugins/capability-command.ts"
+  else
+    printf '%s\n' "$SOURCE_ROOT/$rel"
+  fi
+}
+
 render_asset() {
   local src="$1"
   sed "s|@@INFRA_ROOT@@|$ROOT_DIR|g" "$src"
@@ -67,8 +91,10 @@ ensure_source_assets_exist() {
   local missing=0
 
   for rel in "${ASSETS[@]}"; do
-    if [[ ! -f "$SOURCE_ROOT/$rel" ]]; then
-      echo "Missing repo-managed source asset: $SOURCE_ROOT/$rel" >&2
+    local src
+    src=$(source_asset "$rel")
+    if [[ ! -f "$src" ]]; then
+      echo "Missing repo-managed source asset: $src" >&2
       missing=1
     fi
   done
@@ -86,7 +112,7 @@ check_asset_sync() {
   local -a mismatched=()
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_asset "$rel")
     dst="$LIVE_ROOT/$rel"
 
     if [[ ! -f "$dst" ]]; then
@@ -133,7 +159,7 @@ run_apply() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_asset "$rel")
     dst="$LIVE_ROOT/$rel"
 
     mkdir -p "$(dirname "$dst")"

package/scripts/sync-opencode-security-assets.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 usage() {
   cat <<'EOF'
-Usage: sync-opencode-security-assets.sh [--check|--apply] [--live-root PATH]
+Usage: sync-opencode-security-assets.sh [--check|--apply] [--capability-overlay] [--live-root PATH]
 
 Compare or sync the repo-managed OpenCode security-audit assets against the live
 OpenCode config tree.
@@ -11,12 +11,17 @@ OpenCode config tree.
 Options:
   --check            Verify that the managed live assets match the repo copy (default)
   --apply            Copy the repo-managed assets into the live OpenCode tree, then verify
+  --capability-overlay
+                     Select guarded command/workflow overlays for a contract-enabled isolated root
   --live-root PATH   Override the live OpenCode root (default: $OPENCODE_CONFIG_DIR or $HOME/.config/opencode)
   -h, --help         Show this help text
 
 Notes:
   - The repo-managed source of truth lives under ./opencode/
   - This script manages only the security-audit OpenCode assets
+  - Plugin installation is delegated to sync-opencode-plugin-assets.sh;
+    --capability-overlay selects its native plugin only when the master switch is on
+  - Command and workflow assets always retain their legacy owners and bytes
   - --apply also removes the legacy gsd-overrides security-audit workflow/template files
 EOF
 }
@@ -25,6 +30,7 @@ ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 SOURCE_ROOT="$ROOT_DIR/opencode"
 LIVE_ROOT="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
 MODE="check"
+CAPABILITY_OVERLAY=0
 
 ASSETS=(
   "command/security-audit.md"
@@ -56,6 +62,10 @@ while [[ $# -gt 0 ]]; do
       MODE="apply"
       shift
       ;;
+    --capability-overlay)
+      CAPABILITY_OVERLAY=1
+      shift
+      ;;
     --live-root)
       LIVE_ROOT="$2"
       shift 2
@@ -72,6 +82,11 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+source_for() {
+  local rel="$1"
+  printf '%s\n' "$SOURCE_ROOT/$rel"
+}
+
 ensure_source_assets_exist() {
   local rel
   local missing=0
@@ -116,7 +131,7 @@ run_check() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     if [[ ! -f "$dst" ]]; then
@@ -160,7 +175,7 @@ run_apply() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     mkdir -p "$(dirname "$dst")"
@@ -193,3 +208,9 @@ case "$MODE" in
     run_apply
     ;;
 esac
+
+plugin_args=("--$MODE" "--live-root" "$LIVE_ROOT")
+if [[ "$CAPABILITY_OVERLAY" -eq 1 ]]; then
+  plugin_args+=("--capability-overlay")
+fi
+"$ROOT_DIR/scripts/sync-opencode-plugin-assets.sh" "${plugin_args[@]}"

package/scripts/sync-opencode-wiki-assets.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 usage() {
   cat <<'EOF'
-Usage: sync-opencode-wiki-assets.sh [--check|--apply] [--live-root PATH]
+Usage: sync-opencode-wiki-assets.sh [--check|--apply] [--capability-overlay] [--live-root PATH]
 
 Compare or sync the repo-managed OpenCode wiki assets against the live
 OpenCode config tree.
@@ -11,12 +11,17 @@ OpenCode config tree.
 Options:
   --check            Verify that the managed live assets match the repo copy (default)
   --apply            Copy the repo-managed assets into the live OpenCode tree, then verify
+  --capability-overlay
+                     Select guarded command/workflow overlays for a contract-enabled isolated root
   --live-root PATH   Override the live OpenCode root (default: $OPENCODE_CONFIG_DIR or $HOME/.config/opencode)
   -h, --help         Show this help text
 
 Notes:
   - The repo-managed source of truth lives under ./opencode/
   - This script manages only the wiki-specific OpenCode assets
+  - Plugin installation is delegated to sync-opencode-plugin-assets.sh;
+    --capability-overlay selects its native plugin only when the master switch is on
+  - Command and workflow assets always retain their legacy owners and bytes
   - Extra live wiki assets are reported as warnings but are not deleted automatically
   - --apply also removes the legacy gsd-overrides wiki workflow/template files
 EOF
@@ -26,6 +31,7 @@ ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 SOURCE_ROOT="$ROOT_DIR/opencode"
 LIVE_ROOT="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
 MODE="check"
+CAPABILITY_OVERLAY=0
 
 ASSETS=(
   "command/wiki-ingest.md"
@@ -68,6 +74,10 @@ while [[ $# -gt 0 ]]; do
       MODE="apply"
       shift
       ;;
+    --capability-overlay)
+      CAPABILITY_OVERLAY=1
+      shift
+      ;;
     --live-root)
       LIVE_ROOT="$2"
       shift 2
@@ -84,6 +94,11 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+source_for() {
+  local rel="$1"
+  printf '%s\n' "$SOURCE_ROOT/$rel"
+}
+
 collect_extra_live_assets() {
   local root="$1"
   local -A managed=()
@@ -174,7 +189,7 @@ run_check() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     if [[ ! -f "$dst" ]]; then
@@ -219,7 +234,7 @@ run_apply() {
   ensure_source_assets_exist
 
   for rel in "${ASSETS[@]}"; do
-    src="$SOURCE_ROOT/$rel"
+    src=$(source_for "$rel")
     dst="$LIVE_ROOT/$rel"
 
     mkdir -p "$(dirname "$dst")"
@@ -252,3 +267,9 @@ case "$MODE" in
     run_apply
     ;;
 esac
+
+plugin_args=("--$MODE" "--live-root" "$LIVE_ROOT")
+if [[ "$CAPABILITY_OVERLAY" -eq 1 ]]; then
+  plugin_args+=("--capability-overlay")
+fi
+"$ROOT_DIR/scripts/sync-opencode-plugin-assets.sh" "${plugin_args[@]}"

package/scripts/sync-pi-assets.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: sync-pi-assets.sh [--check|--apply] [--live-root PATH]
+
+Compare or sync the repo-managed Pi extension assets against the live Pi agent
+configuration tree.
+
+Options:
+  --check            Verify managed live assets match the rendered repo copies (default)
+  --apply            Install managed assets, then verify
+  --live-root PATH   Override the Pi agent root (default: $PI_CODING_AGENT_DIR or ~/.pi/agent)
+  -h, --help         Show this help text
+EOF
+}
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+SOURCE_ROOT="$ROOT_DIR/pi"
+LIVE_ROOT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+MODE="check"
+ASSET="extensions/cairnkeep-trajectory.ts"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check) MODE="check"; shift ;;
+    --apply) MODE="apply"; shift ;;
+    --live-root) LIVE_ROOT="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+render_asset() {
+  sed "s|@@INFRA_ROOT@@|$ROOT_DIR|g" "$SOURCE_ROOT/$ASSET"
+}
+
+check_asset() {
+  [[ -f "$SOURCE_ROOT/$ASSET" ]] || {
+    echo "Missing repo-managed source asset: $SOURCE_ROOT/$ASSET" >&2
+    return 2
+  }
+  [[ -f "$LIVE_ROOT/$ASSET" ]] || {
+    echo "Missing live Pi extension under $LIVE_ROOT: $ASSET" >&2
+    return 1
+  }
+  cmp -s <(render_asset) "$LIVE_ROOT/$ASSET" || {
+    echo "Out-of-sync live Pi extension under $LIVE_ROOT: $ASSET" >&2
+    return 1
+  }
+}
+
+if [[ "$MODE" == "apply" ]]; then
+  [[ -f "$SOURCE_ROOT/$ASSET" ]] || {
+    echo "Missing repo-managed source asset: $SOURCE_ROOT/$ASSET" >&2
+    exit 2
+  }
+  mkdir -p "$(dirname "$LIVE_ROOT/$ASSET")"
+  if [[ -f "$LIVE_ROOT/$ASSET" ]] && cmp -s <(render_asset) "$LIVE_ROOT/$ASSET"; then
+    echo "Applied 0 Pi extension asset(s); 1 already matched."
+  else
+    rendered_tmp=$(mktemp)
+    render_asset > "$rendered_tmp"
+    install -m 0644 "$rendered_tmp" "$LIVE_ROOT/$ASSET"
+    rm -f "$rendered_tmp"
+    echo "Applied 1 Pi extension asset(s); 0 already matched."
+  fi
+fi
+
+check_asset
+printf 'Pi extension assets are in sync under %s\n' "$LIVE_ROOT"

package/scripts/test-audit-timer.sh

@@ -26,4 +26,102 @@ grep -q "scripts/memory-wiki-audit.sh --para-root $tmp/PARA --report $tmp/audit.
 grep -q "OnCalendar=Mon \*-\*-\* 04:00:00" "$tmr" || fail "timer OnCalendar not substituted"
 grep -q "WantedBy=timers.target" "$tmr" || fail "timer missing [Install] WantedBy"
 
+# Scheduled note distillation stays in the same separate audit process and is
+# activated only by the effective note capability state.
+npm --prefix "$ROOT/mcp-memory-server" run build >/dev/null
+mkdir -p "$tmp/PARA/Projects/empty-project"
+[[ -x "$ROOT/scripts/memory-wiki-audit.sh" ]] || fail "audit script is not executable for systemd"
+CAIRN_AGENTFS_BASE_DIR="$tmp/store-off" env -u CAIRN_NOTE_DISTILLATION \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$tmp/PARA" >"$tmp/audit-off.md"
+[[ ! -e "$tmp/store-off/notes" ]] || fail "flag-off audit created note storage"
+CAIRN_AGENTFS_BASE_DIR="$tmp/store-on" CAIRN_NOTE_DISTILLATION=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$tmp/PARA" >"$tmp/audit-on.md"
+grep -q "Note distillation" "$tmp/audit-on.md" || fail "flag-on audit omitted note distillation status"
+
+managed="$tmp/managed"
+managed_para="$managed/PARA"
+mkdir -p "$managed_para/Projects/empty-project"
+
+# Master-off keeps the inherited compatibility path even when staged managed
+# state says otherwise.
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities enable notes.distill --json >/dev/null)
+(cd "$managed" && env -u CAIRN_CAPABILITY_CONTRACT -u CAIRN_NOTE_DISTILLATION -u CAIRN_CAPABILITY_NOTES_DISTILL \
+  CAIRN_AGENTFS_BASE_DIR="$tmp/store-master-off" \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-master-off.md")
+! grep -q "Note distillation" "$tmp/audit-master-off.md" || fail "master-off audit consumed staged managed state"
+
+# Project state and the derived environment override follow the central
+# environment > project > compatibility precedence.
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities disable notes.distill --json >/dev/null)
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_NOTE_DISTILLATION=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-managed-disabled.md")
+! grep -q "Note distillation" "$tmp/audit-managed-disabled.md" || fail "managed disable did not override compatibility enable"
+
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_CAPABILITY_NOTES_DISTILL=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-env-enabled.md")
+grep -q "Note distillation: completed" "$tmp/audit-env-enabled.md" || fail "environment enable did not override managed disable"
+
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities enable notes.distill --json >/dev/null)
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_CAPABILITY_NOTES_DISTILL=0 CAIRN_NOTE_DISTILLATION=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-env-disabled.md")
+! grep -q "Note distillation" "$tmp/audit-env-disabled.md" || fail "environment disable did not override managed enable"
+
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities reset notes.distill --json >/dev/null)
+(cd "$managed" && env -u CAIRN_NOTE_DISTILLATION CAIRN_CAPABILITY_CONTRACT=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-reset-off.md")
+! grep -q "Note distillation" "$tmp/audit-reset-off.md" || fail "reset did not restore inherited default-off state"
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_NOTE_DISTILLATION=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-reset-on.md")
+grep -q "Note distillation: completed" "$tmp/audit-reset-on.md" || fail "reset did not restore compatibility enable"
+
+# Disabled state performs no note or callback-store work even when logging and
+# trajectory capture are both consented.
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities disable notes.distill --json >/dev/null)
+(cd "$managed" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_CAPABILITY_LOGGING=1 CAIRN_TRAJECTORY_CAPTURE=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$managed_para" >"$tmp/audit-disabled-consented.md")
+[[ ! -e "$managed/.agentfs/trajectory.db" ]] || fail "disabled audit created callback storage"
+
+# Enabled jobs create callback metadata only when all three consents are on.
+logging="$tmp/logging"
+logging_para="$logging/PARA"
+mkdir -p "$logging_para/Projects/empty-project"
+(cd "$logging" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities enable notes.distill --json >/dev/null)
+(cd "$logging" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_CAPABILITY_LOGGING=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$logging_para" >"$tmp/audit-no-capture.md")
+[[ ! -e "$logging/.agentfs/trajectory.db" ]] || fail "capture-off audit created callback storage"
+(cd "$logging" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_TRAJECTORY_CAPTURE=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$logging_para" >"$tmp/audit-no-logging.md")
+[[ ! -e "$logging/.agentfs/trajectory.db" ]] || fail "logging-off audit created callback storage"
+(cd "$logging" && CAIRN_CAPABILITY_CONTRACT=1 CAIRN_CAPABILITY_LOGGING=1 CAIRN_TRAJECTORY_CAPTURE=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$logging_para" >"$tmp/audit-logged.md")
+PROJECT="$logging" node --input-type=module -e '
+  const { listCapabilityRecords } = await import("./mcp-memory-server/dist/capability-store.js");
+  const rows = (await listCapabilityRecords(process.env.PROJECT)).records;
+  if (rows.length !== 1 || rows[0].capability_id !== "notes.distill" || rows[0].outcome !== "success"
+      || rows[0].source !== "notes-cli" || rows[0].transport !== "local-process") process.exit(1);
+' || fail "all-consent audit did not create one exact note callback record"
+
+# A note child failure remains visible but cannot mask deterministic wiki
+# findings or change their established exit code.
+failure="$tmp/failure"
+failure_para="$failure/PARA"
+wiki="$failure_para/Projects/stale/.planning/wiki"
+mkdir -p "$wiki/sources" "$failure/fake-bin"
+printf '%s\n' '- Last reviewed: 2000-01-01' >"$wiki/sources/stale.md"
+printf '%s\n' '# Index' >"$wiki/index.md"
+(cd "$failure" && CAIRN_CAPABILITY_CONTRACT=1 "$ROOT/bin/cairn" capabilities enable notes.distill --json >/dev/null)
+real_node=$(command -v node)
+printf '%s\n' '#!/usr/bin/env bash' \
+  'if [[ "$1" == *"/note-cli.js" ]]; then exit 42; fi' \
+  'exec "$REAL_NODE" "$@"' >"$failure/fake-bin/node"
+chmod +x "$failure/fake-bin/node"
+set +e
+(cd "$failure" && REAL_NODE="$real_node" PATH="$failure/fake-bin:$PATH" CAIRN_CAPABILITY_CONTRACT=1 \
+  "$ROOT/scripts/memory-wiki-audit.sh" --para-root "$failure_para" >"$tmp/audit-failed-note.md")
+audit_status=$?
+set -e
+[[ "$audit_status" == 3 ]] || fail "note failure changed deterministic wiki audit exit status"
+grep -q "stale source pages" "$tmp/audit-failed-note.md" || fail "note failure masked deterministic wiki findings"
+grep -q "Note distillation: failed" "$tmp/audit-failed-note.md" || fail "note failure status was not reported"
+
 echo "PASS: audit-timer render (placeholders substituted, units well-formed)"

package/scripts/test-bootstrap-untracked.sh

@@ -11,6 +11,36 @@ fail() {
   exit 1
 }
 
+capability_env_keys='CAIRN_CAPABILITY_CONTRACT CAIRN_CAPABILITY_LOGGING CAIRN_CAPABILITY_MEMORY_WRITE CAIRN_CAPABILITY_MEMORY_SEARCH CAIRN_CAPABILITY_NOTES_DISTILL CAIRN_CAPABILITY_WIKI CAIRN_CAPABILITY_GRAPH CAIRN_CAPABILITY_SECURITY_AUDIT CAIRN_CAPABILITY_ROUTE_CHECK CAIRN_CAPABILITY_CONTEXT_EXPLORE'
+for key in $capability_env_keys; do
+  [[ $(grep -cxF "# $key=" "$ROOT/templates/env.example.template") -eq 1 ]] ||
+    fail "environment template must document exactly one commented $key entry"
+  if grep -q "^[[:space:]]*$key=" "$ROOT/templates/env.example.template"; then
+    fail "environment template enabled $key by default"
+  fi
+done
+node - "$ROOT/mcp-memory-server/src/capability-registry.ts" "$ROOT/templates/env.example.template" <<'NODE'
+const fs = require("fs");
+const [registryPath, templatePath] = process.argv.slice(2);
+const registry = fs.readFileSync(registryPath, "utf8");
+const template = fs.readFileSync(templatePath, "utf8");
+const ids = [...registry.matchAll(/^\s*id: "([^"]+)",$/gm)].map((match) => match[1]);
+const derived = ids.map((id) => `CAIRN_CAPABILITY_${id.toUpperCase().replaceAll(".", "_")}`);
+const documented = [...template.matchAll(/^# (CAIRN_CAPABILITY_[A-Z_]+)=$/gm)]
+  .map((match) => match[1])
+  .filter((name) => name !== "CAIRN_CAPABILITY_CONTRACT" && name !== "CAIRN_CAPABILITY_LOGGING");
+if (JSON.stringify(documented) !== JSON.stringify(derived)) process.exit(1);
+NODE
+grep -qF 'Strict booleans: 1 | true | yes | on; 0 | false | no | off.' "$ROOT/templates/env.example.template" ||
+  fail "environment template omitted strict capability boolean guidance"
+grep -qF 'CAIRN_NOTE_DISTILLATION remains a compatibility input' "$ROOT/templates/env.example.template" ||
+  fail "environment template omitted the existing note compatibility input"
+grep -qF 'CAIRN_TRAJECTORY_CAPTURE is separate required consent' "$ROOT/templates/env.example.template" ||
+  fail "environment template omitted independent trajectory consent"
+if grep -Eqi '(prisma|drizzle|typeorm|sequelize|db[[:space:]]+push|schema[[:space:]-]+push|migrat(e|ion))' "$ROOT/scripts/bootstrap.sh"; then
+  fail "bootstrap contains an ORM, schema-push, or migration path"
+fi
+
 # --untracked outside a git repo fails before creating anything
 mkdir "$tmp/plain"
 if "$ROOT/scripts/bootstrap.sh" --untracked "$tmp/plain" >/dev/null 2>&1; then
@@ -29,11 +59,28 @@ git -C "$tmp/repo" init -q
 grep -qxF "/.ai/" "$tmp/repo/.git/info/exclude" || fail "missing /.ai/ exclude entry"
 grep -qxF "/.planning/" "$tmp/repo/.git/info/exclude" || fail "missing /.planning/ exclude entry"
 grep -qxF "/.agentfs/" "$tmp/repo/.git/info/exclude" || fail "missing /.agentfs/ exclude entry"
+[[ -f "$tmp/repo/.ai/capabilities.json" ]] || fail "capability configuration missing"
+[[ ! -e "$tmp/repo/.agentfs/trajectory.db" ]] || fail "fresh bootstrap created a callback database"
+
+# Existing scaffold and operator configuration bytes are preserved on rerun.
+printf '%s\n' '{"schema_version":1,"capabilities":{"wiki":false},"logging":{"callbacks":true}}' >"$tmp/repo/.ai/capabilities.json"
+chmod 600 "$tmp/repo/.ai/capabilities.json"
+printf '%s\n' '# operator-owned environment' >"$tmp/repo/.ai/env.example"
+asset_paths='.ai/start-claude.sh .ai/start-opencode.sh .ai/start-pi.sh .ai/env.example .ai/trajectory-redaction.json .ai/capabilities.json .agentfs/.gitignore .planning/config.json .planning/wiki/index.md .planning/wiki/policy.md .planning/wiki/CONTRADICTIONS.md .planning/wiki/LOG.md .planning/alignment/policy.md .planning/alignment/gap-register.yaml .planning/graphs/policy.md .planning/graphs/.gitignore .planning/security/policy.md'
+mkdir -p "$tmp/assets-before"
+for path in $asset_paths; do
+  cp "$tmp/repo/$path" "$tmp/assets-before/${path//\//__}"
+done
 
 # Re-run is idempotent: no duplicate exclude entries
 "$ROOT/scripts/bootstrap.sh" --untracked "$tmp/repo" >/dev/null
 [[ $(grep -cxF "/.ai/" "$tmp/repo/.git/info/exclude") -eq 1 ]] || fail "duplicate exclude entries"
 [[ $(grep -cxF "/.agentfs/" "$tmp/repo/.git/info/exclude") -eq 1 ]] || fail "duplicate .agentfs exclude entry"
+for path in $asset_paths; do
+  [[ -e "$tmp/repo/$path" ]] || fail "bootstrap rerun deleted installed asset: $path"
+  cmp -s "$tmp/assets-before/${path//\//__}" "$tmp/repo/$path" || fail "bootstrap rerun rewrote installed asset: $path"
+done
+[[ ! -e "$tmp/repo/.agentfs/trajectory.db" ]] || fail "bootstrap rerun created a callback database"
 
 # Default mode is unchanged: scaffold stays visible to git
 mkdir "$tmp/repo2"
@@ -41,5 +88,6 @@ git -C "$tmp/repo2" init -q
 "$ROOT/scripts/bootstrap.sh" "$tmp/repo2" >/dev/null
 git -C "$tmp/repo2" status --porcelain | grep -q "\.ai/" || fail "default mode should leave the scaffold tracked"
 git -C "$tmp/repo2" status --porcelain | grep -q "\.agentfs/" || fail "default mode should track the memory ignore guard"
+[[ ! -e "$tmp/repo2/.agentfs/trajectory.db" ]] || fail "default bootstrap created a callback database"
 
 echo "PASS: bootstrap --untracked contributor mode"

package/scripts/test-cli-dispatch.sh

@@ -4,21 +4,60 @@ set -euo pipefail
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 fail() { echo "FAIL: $1" >&2; exit 1; }
 cairn="$ROOT/bin/cairn"
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 
 "$cairn" help | grep -q "cairn doctor" || fail "help missing doctor"
 "$cairn" help | grep -q "cairn memory" || fail "help missing memory"
 "$cairn" help | grep -q "cairn audit-timer" || fail "help missing audit-timer"
 "$cairn" help | grep -q "cairn sync" || fail "help missing sync"
+"$cairn" help | grep -q "cairn sync-pi" || fail "help missing sync-pi"
 "$cairn" help | grep -q "cairn memory-server" || fail "help missing memory-server"
+"$cairn" help | grep -q "cairn notes" || fail "help missing notes"
+"$cairn" help | grep -q "cairn artifact <list|show|delete|prune>" || fail "help missing artifact"
+"$cairn" help | grep -q "cairn capabilities <list|status|enable|disable|reset|logging>" || fail "help missing capabilities"
 "$cairn" sync --help >/dev/null 2>&1 || fail "cairn sync dispatch"
+"$cairn" sync-pi --help >/dev/null 2>&1 || fail "cairn sync-pi dispatch"
+env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "cairn notes dispatch"
+"$cairn" artifact --help | grep -q "cairn artifact list" || fail "cairn artifact dispatch"
+"$cairn" capabilities --help >"$tmp/capabilities-help" 2>/dev/null || fail "cairn capabilities dispatch"
+grep -qxF 'MCP capability changes require a memory-server restart. Operating capability' "$tmp/capabilities-help" || fail "capability help missing exact restart wording"
+grep -qxF 'changes apply on the next invocation.' "$tmp/capabilities-help" || fail "capability help missing exact invocation wording"
+if grep -Eq '^  cairn capabilities (guard|start|finish|doctor)' "$tmp/capabilities-help"; then
+  fail "capability help exposed a private operation"
+fi
 if "$cairn" not-a-command >/dev/null 2>&1; then
   fail "unknown command should exit non-zero"
 fi
 
-tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/prefix/bin" "$tmp/project"
+ln -s "$ROOT/bin/cairn" "$tmp/prefix/bin/cairn"
+(
+  cd "$tmp/project"
+  env -u CAIRN_CAPABILITY_CONTRACT "$tmp/prefix/bin/cairn" capabilities status --json >"$tmp/status-one.json"
+  env -u CAIRN_CAPABILITY_CONTRACT "$tmp/prefix/bin/cairn" capabilities status --json >"$tmp/status-two.json"
+)
+cmp -s "$tmp/status-one.json" "$tmp/status-two.json" || fail "installed capability status JSON is unstable"
+node - "$tmp/status-one.json" <<'NODE'
+const fs = require("fs");
+const value = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const ids = ["memory.write", "memory.search", "notes.distill", "wiki", "graph", "security.audit", "route.check", "context.explore"];
+if (value.schema_version !== 1 || value.contract_enabled !== false) process.exit(1);
+if (JSON.stringify(value.capabilities.map(({ id }) => id)) !== JSON.stringify(ids)) process.exit(1);
+if (!/^[0-9a-f]{64}$/.test(value.configuration_digest)) process.exit(1);
+NODE
+set +e
+(cd "$tmp/project" && "$tmp/prefix/bin/cairn" capabilities PHASE18_RAW_SENTINEL) >"$tmp/unknown.out" 2>"$tmp/unknown.err"
+unknown_status=$?
+set -e
+[[ "$unknown_status" -eq 2 ]] || fail "unknown capability operation should exit 2"
+[[ ! -s "$tmp/unknown.out" ]] || fail "unknown capability operation wrote stdout"
+grep -qxF 'cairn capabilities: invalid command, arguments, or managed state.' "$tmp/unknown.err" || fail "unknown capability operation was not value-free"
+if grep -qF 'PHASE18_RAW_SENTINEL' "$tmp/unknown.out" "$tmp/unknown.err"; then
+  fail "unknown capability operation exposed its raw value"
+fi
 CAIRN_AGENTFS_BASE_DIR="$tmp/store" "$cairn" memory path | grep -qx "$tmp/store" || fail "cairn memory path dispatch"
 ( cd "$tmp" && "$cairn" doctor ) >/dev/null || fail "cairn doctor dispatch (clean env should exit 0)"
 "$cairn" audit-timer --render-only "$tmp/u" >/dev/null || fail "cairn audit-timer dispatch"
 [[ -f "$tmp/u/memory-wiki-audit.timer" ]] || fail "audit-timer render via cairn produced no units"
 
-echo "PASS: cairn dispatch (doctor, memory, audit-timer)"
+echo "PASS: cairn dispatch (doctor, memory, artifact, audit-timer)"