@onlooker-community/ecosystem 0.28.1 → 0.29.1

package/test/bats/archivist-project-key.bats

@@ -73,3 +73,82 @@ setup() {
   [ -n "$kb" ]
   [ "$ka" != "$kb" ]
 }
+
+@test "archivist_project_remote_url prints origin url when set" {
+  local d="${BATS_TEST_TMPDIR}/remote-set"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" remote add origin https://example.com/x.git
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ "$output" = "https://example.com/x.git" ]
+}
+
+@test "archivist_project_remote_url returns empty when repo has no remote" {
+  local d="${BATS_TEST_TMPDIR}/remote-none"
+  mkdir -p "$d"
+  git -C "$d" init -q
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_remote_url returns empty for a non-git directory" {
+  local d="${BATS_TEST_TMPDIR}/remote-non-git"
+  mkdir -p "$d"
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_remote_url returns empty for a nonexistent path" {
+  run archivist_project_remote_url "${BATS_TEST_TMPDIR}/does-not-exist"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_repo_root prints the repo toplevel realpath" {
+  local d="${BATS_TEST_TMPDIR}/root-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+
+  # Physical path: matches the function's pwd -P resolution on platforms
+  # (e.g. macOS) where the temp dir is reached through a symlink.
+  local expected
+  expected="$(cd "$d" && pwd -P)"
+
+  run archivist_project_repo_root "$d"
+  [ "$status" -eq 0 ]
+  [ "$output" = "$expected" ]
+}
+
+@test "archivist_project_repo_root resolves toplevel from a subdirectory" {
+  local d="${BATS_TEST_TMPDIR}/root-repo-sub"
+  mkdir -p "$d/nested/deep"
+  git -C "$d" init -q
+
+  local expected
+  expected="$(cd "$d" && pwd -P)"
+
+  run archivist_project_repo_root "$d/nested/deep"
+  [ "$status" -eq 0 ]
+  [ "$output" = "$expected" ]
+}
+
+@test "archivist_project_repo_root returns empty for a non-git directory" {
+  local d="${BATS_TEST_TMPDIR}/root-non-git"
+  mkdir -p "$d"
+
+  run archivist_project_repo_root "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_repo_root returns empty for a nonexistent path" {
+  run archivist_project_repo_root "${BATS_TEST_TMPDIR}/root-missing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/test/bats/archivist-storage.bats

@@ -117,3 +117,82 @@ setup() {
   first_id=$(printf '%s' "$ranked" | jq -r '.[0].id')
   [ "$first_id" = "$newer_id" ]
 }
+
+@test "storage_root prints the archivist dir under ONLOOKER_DIR" {
+  run archivist_storage_root
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist" ]
+}
+
+@test "project_dir prints root joined with the key" {
+  local key="abc123def456"
+  run archivist_project_dir "$key"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}" ]
+}
+
+@test "kind_dir prints the per-kind subdir under the project dir" {
+  local key="abc123def456"
+  run archivist_kind_dir "$key" "decisions"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}/decisions" ]
+}
+
+@test "kind_dir honors an arbitrary kind name" {
+  local key="abc123def456"
+  run archivist_kind_dir "$key" "dead_ends"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}/dead_ends" ]
+}
+
+@test "write_manifest creates manifest.json under the project dir" {
+  local key="abc123def456"
+  run archivist_storage_write_manifest "$key" "git@github.com:org/repo.git" "$REPO"
+  [ "$status" -eq 0 ]
+  [ -f "${ONLOOKER_DIR}/archivist/${key}/manifest.json" ]
+}
+
+@test "write_manifest records the project_key, remote_url, and repo_root" {
+  local key="abc123def456"
+  local remote="git@github.com:org/repo.git"
+  archivist_storage_write_manifest "$key" "$remote" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.project_key' "$manifest")" = "$key" ]
+  [ "$(jq -r '.remote_url' "$manifest")" = "$remote" ]
+  [ "$(jq -r '.repo_root' "$manifest")" = "$REPO" ]
+  [ "$(jq -r '.source' "$manifest")" = "local" ]
+}
+
+@test "write_manifest stamps an ISO-8601 last_compact_at timestamp" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "remote" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  local ts
+  ts=$(jq -r '.last_compact_at' "$manifest")
+  [[ "$ts" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]]
+}
+
+@test "write_manifest stores null for an empty remote_url" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.remote_url' "$manifest")" = "null" ]
+  [ "$(jq '.remote_url == null' "$manifest")" = "true" ]
+}
+
+@test "write_manifest stores null for an empty repo_root" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "remote" ""
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.repo_root' "$manifest")" = "null" ]
+  [ "$(jq '.repo_root == null' "$manifest")" = "true" ]
+}
+
+@test "write_manifest rejects an empty key" {
+  run archivist_storage_write_manifest "" "remote" "$REPO"
+  [ "$status" -ne 0 ]
+}

package/test/bats/compact-tracker.bats

@@ -71,3 +71,128 @@ setup() {
 @test "compact_tracker_estimate_tokens estimates from string length" {
   [ "$(compact_tracker_estimate_tokens "abcdefghij" false)" -eq 2 ]
 }
+
+@test "compact_tracker_state_file prints path under compact trackers dir" {
+  local session_id="unit-state-file"
+  local result
+  result=$(compact_tracker_state_file "$session_id")
+  [ "$result" = "${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}" ]
+}
+
+@test "compact_tracker_record_pre creates state file with pending and compact_count 1" {
+  local session_id="unit-record-pre-1"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+
+  [ -f "$state_file" ]
+  jq -e '.pending == true
+    and .trigger == "manual"
+    and .compact_count == 1
+    and (.started_ms | type) == "number"' \
+    "$state_file" >/dev/null
+}
+
+@test "compact_tracker_record_pre increments compact_count on second call" {
+  local session_id="unit-record-pre-2"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+  jq -e '.compact_count == 1' "$state_file" >/dev/null
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+  jq -e '.compact_count == 2' "$state_file" >/dev/null
+}
+
+@test "compact_tracker_record_pre preserves custom_instructions when present" {
+  local session_id="unit-record-pre-3"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" \
+    '{"trigger":"manual","transcript_path":"","custom_instructions":"keep the API design notes"}'
+
+  jq -e '.custom_instructions == "keep the API design notes"' "$state_file" >/dev/null
+}
+
+@test "compact_tracker_append_summary appends a JSONL record" {
+  local session_id="unit-append-1"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  compact_tracker_append_summary "$session_id" \
+    '{"trigger":"manual","compact_summary":"first summary"}'
+
+  [ -f "$summary_file" ]
+  # Records are written as a JSON stream; count objects rather than physical lines.
+  [ "$(jq -s 'length' "$summary_file")" -eq 1 ]
+  jq -se '.[0].compact_summary == "first summary" and .[0].trigger == "manual"' "$summary_file" >/dev/null
+}
+
+@test "compact_tracker_append_summary appends a second line on second call" {
+  local session_id="unit-append-2"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  compact_tracker_append_summary "$session_id" '{"trigger":"manual","compact_summary":"one"}'
+  compact_tracker_append_summary "$session_id" '{"trigger":"auto","compact_summary":"two"}'
+
+  [ "$(jq -s 'length' "$summary_file")" -eq 2 ]
+  [ "$(jq -s -r '.[0].compact_summary' "$summary_file")" = "one" ]
+  [ "$(jq -s -r '.[1].trigger' "$summary_file")" = "auto" ]
+}
+
+@test "compact_tracker_append_summary is a no-op when compact_summary is empty" {
+  local session_id="unit-append-3"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  run compact_tracker_append_summary "$session_id" '{"trigger":"manual","compact_summary":""}'
+  [ "$status" -eq 0 ]
+  [ ! -f "$summary_file" ]
+}
+
+@test "compact_tracker_build_compact_payload uses tokens_before from state file" {
+  local session_id="unit-build-payload"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  printf '%s\n' '{"tokens_before":1000}' >"$state_file"
+
+  local payload
+  payload=$(compact_tracker_build_compact_payload "$session_id" \
+    '{"compact_summary":"a short compacted summary of the prior context"}')
+
+  echo "$payload" | jq -e '.tokens_before == 1000
+    and (.tokens_after | type) == "number"
+    and (.compression_ratio | type) == "number"' >/dev/null
+}
+
+@test "compact_tracker_record_post finalizes state and resets turn_tool_seq" {
+  local session_id="unit-record-post-1"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+
+  printf '%s\n' '{"pending":true,"started_ms":1700000000000,"compact_count":1}' >"$state_file"
+  printf '%s\n' '{"turn_number":3,"turn_tool_seq":5}' >"$tracker_file"
+
+  compact_tracker_record_post "$session_id" '{"trigger":"manual","compact_summary":"done"}'
+
+  jq -e '.pending == false and (.completed_ms | type) == "number"' "$state_file" >/dev/null
+  jq -e '.turn_tool_seq == 0 and .turn_number == 3' "$tracker_file" >/dev/null
+}
+
+@test "compact_tracker_record_post falls back to create state when none exists" {
+  local session_id="unit-record-post-2"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file" "$tracker_file"
+
+  compact_tracker_record_post "$session_id" '{"trigger":"auto","compact_summary":"recovered"}'
+
+  [ -f "$state_file" ]
+  jq -e '.pending == false
+    and (.completed_ms | type) == "number"
+    and .compact_count == 1' \
+    "$state_file" >/dev/null
+}

package/test/bats/compass-config.bats

@@ -0,0 +1,65 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/compass"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+}
+
+@test "compass is disabled by default" {
+	compass_config_load ""
+	run compass_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable compass" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"compass":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	compass_config_load ""
+	run compass_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"compass":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"compass":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	compass_config_load "$repo"
+	run compass_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "shipped defaults survive a partial overlay" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' \
+		'{"compass":{"enabled":true,"evaluator":{"n":7}}}' \
+		> "${HOME}/.claude/settings.json"
+	compass_config_load ""
+	# Overlay key is picked up.
+	[ "$(compass_config_get '.compass.evaluator.n')" = "7" ]
+	# Defaults under the same parent key survive the deep merge.
+	[ "$(compass_config_get '.compass.evaluator.temperature')" = "0.3" ]
+	[ "$(compass_config_get '.compass.confidence_threshold')" = "0.65" ]
+	[ "$(compass_config_get '.compass.stddev_threshold')" = "0.2" ]
+}
+
+@test "config_get_json returns skip_globs array" {
+	compass_config_load ""
+	run compass_config_get_json '.compass.skip_globs'
+	[ "$status" -eq 0 ]
+	printf '%s' "$output" \
+		| jq -e 'index("**/*.lock") != null and index("**/.git/**") != null' >/dev/null
+}
+
+@test "transcript block no longer carries the obsolete transcript_max_age_seconds knob" {
+	compass_config_load ""
+	# Future readers should not find the removed knob — see ADR-001 (read by
+	# transcript_path from hook JSON, no event-log fallback).
+	[ -z "$(compass_config_get '.compass.transcript.transcript_max_age_seconds')" ]
+}

package/test/bats/compass-gate.bats

@@ -0,0 +1,129 @@
+#!/usr/bin/env bats
+
+# Covers compass_run_gate's pre-evaluator rules: skip sentinel,
+# skip_globs, dir+stem cooldown, turn budget, context minimum. These are
+# the cheap gating steps that run before any LLM call.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/compass"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+	# Source the libs the gate depends on.
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-events.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-sanitizer.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-transcript.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-evaluator.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-gate.sh"
+
+	# Enable compass and load config.
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"compass":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	compass_config_load ""
+
+	# Seed a session-state file so the gate's state lookups succeed.
+	export SESSION_ID="test-session-bats"
+	mkdir -p "${ONLOOKER_DIR}/compass/sessions"
+	cat > "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json" <<-EOF
+		{
+		  "session_id": "${SESSION_ID}",
+		  "turn_check_count": 0,
+		  "cooldown": [],
+		  "circuit_breaker": {"state":"closed","consecutive_failures":0,"opened_at":null}
+		}
+	EOF
+
+	# Stub compass_evaluate so the gate never shells out to claude -p
+	# during tests. The stub always reports a pass — tests that need to
+	# verify pre-evaluator rules check that the evaluator is short-circuited
+	# before it would run.
+	compass_evaluate() {
+		printf '{"decision":"pass","confidence":0.95,"stddev":0.03,"primary_concern":"none","rationale":"stub","sample_count":5}'
+		return 0
+	}
+	export -f compass_evaluate
+}
+
+@test "skip sentinel [compass:skip] in file path lets the write through" {
+	run compass_run_gate "Write" "/tmp/foo[compass:skip].txt" "write" \
+		"$(printf 'x%.0s' {1..200})" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	# Nothing written to stdout: no block decision.
+	[ -z "$output" ]
+}
+
+@test "skip sentinel [compass:skip] in context lets the write through" {
+	local ctx
+	ctx="[compass:skip] $(printf 'y%.0s' {1..200})"
+	run compass_run_gate "Write" "/tmp/foo.txt" "write" "$ctx" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "skip_glob match (*.lock) lets the write through" {
+	run compass_run_gate "Write" "/tmp/package-lock.lock" "write" \
+		"$(printf 'x%.0s' {1..200})" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "writes under .git/ are skipped" {
+	run compass_run_gate "Write" "/tmp/repo/.git/HEAD" "write" \
+		"$(printf 'x%.0s' {1..200})" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "context shorter than min_context_chars is skipped (insufficient_context)" {
+	run compass_run_gate "Write" "/tmp/short.txt" "write" \
+		"tiny" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "exhausted turn budget skips subsequent checks" {
+	# Force the budget to be already maxed out.
+	jq '.turn_check_count = 99' \
+		"${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json" \
+		> "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json.new"
+	mv "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json.new" \
+		"${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json"
+	run compass_run_gate "Write" "/tmp/over-budget.txt" "write" \
+		"$(printf 'x%.0s' {1..200})" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "dir+stem cooldown skips a re-write of the same file" {
+	# Pre-seed the cooldown table with a fresh entry.
+	local now
+	now=$(date +%s)
+	jq --argjson ts "$now" '
+		.cooldown = [{"identity":"/tmp/cool/foo","path":"/tmp/cool/foo.txt","ts":$ts}]
+	' "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json" \
+		> "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json.new"
+	mv "${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json.new" \
+		"${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json"
+	run compass_run_gate "Write" "/tmp/cool/foo.txt" "write" \
+		"$(printf 'x%.0s' {1..200})" "$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "evaluator pass emits no block decision on stdout" {
+	# Sufficient context, no skip rules apply — evaluator stub returns pass.
+	run compass_run_gate "Write" "/tmp/new-file.txt" "write" \
+		"$(printf 'we are writing a clearly described feature flag toggle module %.0s' {1..3})" \
+		"$SESSION_ID" "" ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}

package/test/bats/compass-sanitizer.bats

@@ -0,0 +1,69 @@
+#!/usr/bin/env bats
+
+# Covers the sanitization pipeline: control-character removal, XML
+# delimiter stripping, and truncation. The strip sequences contain '<',
+# '/', '|', and '[' — locks in correct escaping so a single sequence
+# can't blank the entire input.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/compass"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-sanitizer.sh"
+}
+
+@test "plain text passes through unchanged" {
+	run compass_sanitize "rename User to Account" 240
+	[ "$status" -eq 0 ]
+	[ "$output" = "rename User to Account" ]
+}
+
+@test "prior_assistant_turn delimiter is stripped" {
+	local out
+	out=$(compass_sanitize "evil <prior_assistant_turn> payload" 240)
+	[[ "$out" == *"[STRIPPED]"* ]]
+	[[ "$out" == *"payload"* ]]
+	[[ "$out" != *"<prior_assistant_turn>"* ]]
+}
+
+@test "all four pair-slot delimiters are stripped" {
+	local out
+	out=$(compass_sanitize "<context_excerpt>x</context_excerpt><tool_input>y</tool_input>" 240)
+	[[ "$out" != *"<context_excerpt>"* ]]
+	[[ "$out" != *"</context_excerpt>"* ]]
+	[[ "$out" != *"<tool_input>"* ]]
+	[[ "$out" != *"</tool_input>"* ]]
+}
+
+@test "non-evaluator delimiters are also stripped" {
+	local out
+	out=$(compass_sanitize "<<SYS>>x<</SYS>> [INST] y [/INST] <| z" 240)
+	[[ "$out" != *"<<SYS>>"* ]]
+	[[ "$out" != *"<</SYS>>"* ]]
+	[[ "$out" != *"[INST]"* ]]
+	[[ "$out" != *"[/INST]"* ]]
+	[[ "$out" != *"<|"* ]]
+}
+
+@test "null bytes and control chars are stripped, tab and newline preserved" {
+	local input
+	input=$(printf 'a\tb\nc\x00d\x01e')
+	local out
+	out=$(compass_sanitize "$input" 240)
+	[[ "$out" == *"a"* && "$out" == *"b"* && "$out" == *"c"* ]]
+	[[ "$out" == *"d"* && "$out" == *"e"* ]]
+	[ "${out}" = "$(printf 'a\tb\ncde')" ]
+}
+
+@test "truncation caps to max_chars" {
+	run compass_sanitize "0123456789abcdef" 8
+	[ "$output" = "01234567" ]
+}
+
+@test "max_chars=0 disables truncation" {
+	run compass_sanitize "0123456789abcdef" 0
+	[ "$output" = "0123456789abcdef" ]
+}

package/test/bats/compass-symbolic-skip.bats

@@ -0,0 +1,88 @@
+#!/usr/bin/env bats
+
+# Covers the symbolic skip layer: cheap pattern check that short-circuits
+# to a pass when the prior assistant turn is an enumerated question and
+# the current context is a clean option reference. See ADR-001.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/compass"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+	# Source the libs the gate depends on so _compass_symbolic_skip is in scope.
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-events.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-sanitizer.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-transcript.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-evaluator.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/compass-gate.sh"
+}
+
+@test "skips when prior turn is enumerated question and reply is an ordinal" {
+	local prior='Which API should we touch?
+1. the internal one
+2. the public one'
+	run _compass_symbolic_skip "$prior" "the first one"
+	[ "$status" -eq 0 ]
+}
+
+@test "skips on a bare digit option reference" {
+	local prior='1. test_one
+2. test_two
+Which one?'
+	run _compass_symbolic_skip "$prior" "2"
+	[ "$status" -eq 0 ]
+}
+
+@test "skips on a clean affirmation" {
+	local prior='1. left
+2. right
+which side?'
+	run _compass_symbolic_skip "$prior" "both"
+	[ "$status" -eq 0 ]
+}
+
+@test "does NOT skip when the prior turn has no enumerated list" {
+	local prior='Should we proceed with the refactor?'
+	run _compass_symbolic_skip "$prior" "yes"
+	[ "$status" -ne 0 ]
+}
+
+@test "does NOT skip when the prior turn has no question mark" {
+	local prior='Here are the options:
+1. A
+2. B'
+	run _compass_symbolic_skip "$prior" "1"
+	[ "$status" -ne 0 ]
+}
+
+@test "does NOT skip when prior turn is empty" {
+	run _compass_symbolic_skip "" "yes"
+	[ "$status" -ne 0 ]
+}
+
+@test "does NOT skip on a hedged affirmation (qualifier clause present)" {
+	skip "hedged-qualifier rejection not yet implemented in _compass_symbolic_skip"
+	local prior='1. delete now
+2. archive first
+Which one?'
+	# A qualifier clause means the reply is not a clean option reference.
+	run _compass_symbolic_skip "$prior" "both, but only if it's easy"
+	[ "$status" -ne 0 ]
+}
+
+@test "does NOT skip on a free-form reply with no option shape" {
+	local prior='1. one
+2. two
+Pick?'
+	run _compass_symbolic_skip "$prior" "Actually I think we should refactor the whole thing"
+	[ "$status" -ne 0 ]
+}