@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/test/bats/archivist-config.bats

@@ -0,0 +1,54 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/archivist"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/archivist-config.sh"
+}
+
+@test "config defaults from plugin config.json: disabled" {
+  archivist_config_load ""
+  run archivist_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json overlay can enable archivist" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"archivist":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  archivist_config_load ""
+  run archivist_config_enabled
+  [ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"archivist":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  local repo="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "${repo}/.claude"
+  printf '%s\n' '{"archivist":{"enabled":false}}' > "${repo}/.claude/settings.json"
+  archivist_config_load "$repo"
+  run archivist_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "injection.max_items defaults from config.json" {
+  archivist_config_load ""
+  local v
+  v=$(archivist_config_get '.archivist.injection.max_items')
+  [ "$v" = "8" ]
+}
+
+@test "settings overlay merges deeply (preserves unset defaults)" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"archivist":{"injection":{"max_items":3}}}' > "${HOME}/.claude/settings.json"
+  archivist_config_load ""
+  local overridden default_model
+  overridden=$(archivist_config_get '.archivist.injection.max_items')
+  default_model=$(archivist_config_get '.archivist.extraction.model')
+  [ "$overridden" = "3" ]
+  [ -n "$default_model" ]
+}

package/test/bats/archivist-inject.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/archivist"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  # Stand up a fake project repo so project-key resolution succeeds.
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/archivist-inject-test.git
+
+  # Compute the project key the hook will use.
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/archivist-project-key.sh"
+  PROJECT_KEY=$(archivist_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  # Seed an artifact on disk for this project.
+  local kind_dir="${ONLOOKER_DIR}/archivist/${PROJECT_KEY}/decisions"
+  mkdir -p "$kind_dir"
+  printf '%s\n' '{
+    "id": "01TESTTESTTESTTESTTESTTEST",
+    "kind": "decision",
+    "summary": "use git remote SHA256 as project key",
+    "detail": "remote URL is stable across machines; falls back to repo path",
+    "files": [],
+    "created_at": "2026-05-22T10:00:00Z",
+    "updated_at": "2026-05-22T10:00:00Z"
+  }' > "${kind_dir}/01TESTTESTTESTTESTTESTTEST.json"
+
+  # Project-scoped settings.json that enables archivist.
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"archivist":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+}
+
+@test "inject hook is a no-op when archivist is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  local input
+  input=$(jq -n --arg cwd "$PROJECT_REPO" '{cwd: $cwd, source: "startup", session_id: "s"}')
+  run bash -c "printf '%s' '$input' | '${PLUGIN_ROOT}/scripts/hooks/archivist-inject.sh'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "inject hook emits seeded artifact when enabled" {
+  local input
+  input=$(jq -n --arg cwd "$PROJECT_REPO" '{cwd: $cwd, source: "startup", session_id: "s"}')
+  run bash -c "printf '%s' '$input' | '${PLUGIN_ROOT}/scripts/hooks/archivist-inject.sh'"
+  [ "$status" -eq 0 ]
+
+  echo "$output" | jq -e '.hookSpecificOutput.hookEventName == "SessionStart"' >/dev/null
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"use git remote SHA256 as project key"* ]]
+  [[ "$ctx" == *"Archivist injected 1"* ]]
+}
+
+@test "inject hook skips when there is no git context" {
+  local non_git="${BATS_TEST_TMPDIR}/no-git"
+  mkdir -p "$non_git"
+  local input
+  input=$(jq -n --arg cwd "$non_git" '{cwd: $cwd, source: "startup", session_id: "s"}')
+  run bash -c "printf '%s' '$input' | '${PLUGIN_ROOT}/scripts/hooks/archivist-inject.sh'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/archivist"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/archivist-project-key.sh"
+}
+
+@test "non-git directory returns empty key" {
+  local d="${BATS_TEST_TMPDIR}/non-git"
+  mkdir -p "$d"
+  run archivist_project_key "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "git repo without remote falls back to repo-root hash" {
+  local d="${BATS_TEST_TMPDIR}/local-only-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name "Test"
+
+  local k1
+  k1=$(archivist_project_key "$d")
+  [ -n "$k1" ]
+  [ "${#k1}" -eq 12 ]
+
+  # Stability: a second call returns the same key.
+  local k2
+  k2=$(archivist_project_key "$d")
+  [ "$k1" = "$k2" ]
+}
+
+@test "git repo with remote uses remote hash and ignores local path" {
+  local a="${BATS_TEST_TMPDIR}/clone-a"
+  local b="${BATS_TEST_TMPDIR}/clone-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+    git -C "$d" remote add origin git@github.com:org/proj.git
+  done
+
+  local ka kb
+  ka=$(archivist_project_key "$a")
+  kb=$(archivist_project_key "$b")
+  [ -n "$ka" ]
+  [ "$ka" = "$kb" ]
+}
+
+@test "different remotes yield different keys" {
+  local a="${BATS_TEST_TMPDIR}/proj-a"
+  local b="${BATS_TEST_TMPDIR}/proj-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+  done
+  git -C "$a" remote add origin git@github.com:org/proj-a.git
+  git -C "$b" remote add origin git@github.com:org/proj-b.git
+
+  local ka kb
+  ka=$(archivist_project_key "$a")
+  kb=$(archivist_project_key "$b")
+  [ -n "$ka" ]
+  [ -n "$kb" ]
+  [ "$ka" != "$kb" ]
+}

package/test/bats/archivist-storage.bats

@@ -0,0 +1,119 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/archivist"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/archivist-storage.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/archivist-ulid.sh"
+
+  REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$REPO/src"
+  : > "$REPO/src/known.ts"
+  : > "$REPO/README.md"
+}
+
+@test "validate accepts an existing repo-relative path" {
+  run archivist_validate_repo_path "$REPO" "src/known.ts"
+  [ "$status" -eq 0 ]
+  [ "$output" = "src/known.ts" ]
+}
+
+@test "validate accepts an absolute path inside the repo" {
+  run archivist_validate_repo_path "$REPO" "${REPO}/src/known.ts"
+  [ "$status" -eq 0 ]
+  [ "$output" = "src/known.ts" ]
+}
+
+@test "validate rejects a path outside the repo" {
+  local outside="${BATS_TEST_TMPDIR}/outside.ts"
+  : > "$outside"
+  run archivist_validate_repo_path "$REPO" "$outside"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "validate rejects a ../ escape" {
+  run archivist_validate_repo_path "$REPO" "../escaped.ts"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "validate rejects a path that does not exist" {
+  run archivist_validate_repo_path "$REPO" "src/missing.ts"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "validate_paths_array strips invalid entries" {
+  local input='["src/known.ts","../escape.ts","src/missing.ts","README.md"]'
+  local cleaned compact
+  cleaned=$(archivist_validate_paths_array "$REPO" "$input")
+  compact=$(printf '%s' "$cleaned" | jq -c .)
+  [ "$compact" = '["src/known.ts","README.md"]' ]
+}
+
+@test "storage_init creates kind directories" {
+  local key="abc123def456"
+  archivist_storage_init "$key"
+  [ -d "${ONLOOKER_DIR}/archivist/${key}/decisions" ]
+  [ -d "${ONLOOKER_DIR}/archivist/${key}/dead_ends" ]
+  [ -d "${ONLOOKER_DIR}/archivist/${key}/open_questions" ]
+}
+
+@test "write_artifact creates a ULID-keyed file" {
+  local key="abc123def456"
+  local id
+  id=$(archivist_ulid)
+  local json='{"id":"'"$id"'","kind":"decision","summary":"hello"}'
+  run archivist_storage_write_artifact "$key" "decisions" "$id" "$json"
+  [ "$status" -eq 0 ]
+  [ -f "${ONLOOKER_DIR}/archivist/${key}/decisions/${id}.json" ]
+}
+
+@test "write_artifact rejects unknown kind" {
+  local key="abc123def456"
+  run archivist_storage_write_artifact "$key" "bogus_kind" "01J" '{}'
+  [ "$status" -ne 0 ]
+}
+
+@test "load_ranked sorts pinned items first" {
+  local key="abc123def456"
+  archivist_storage_init "$key"
+
+  # Write two decisions; pin the older one.
+  local older_id="01AAAAAAAAAAAAAAAAAAAAAAAA"
+  local newer_id="01ZZZZZZZZZZZZZZZZZZZZZZZZ"
+  printf '{"id":"%s","summary":"older","created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-01T00:00:00Z"}\n' "$older_id" \
+    > "${ONLOOKER_DIR}/archivist/${key}/decisions/${older_id}.json"
+  printf '{"id":"%s","summary":"newer","created_at":"2026-05-22T00:00:00Z","updated_at":"2026-05-22T00:00:00Z"}\n' "$newer_id" \
+    > "${ONLOOKER_DIR}/archivist/${key}/decisions/${newer_id}.json"
+  printf '{"ids":["%s"]}\n' "$older_id" > "${ONLOOKER_DIR}/archivist/${key}/pinned.json"
+
+  local ranked
+  ranked=$(archivist_storage_load_ranked "$key")
+  local first_id
+  first_id=$(printf '%s' "$ranked" | jq -r '.[0].id')
+  [ "$first_id" = "$older_id" ]
+}
+
+@test "load_ranked sorts non-pinned by recency desc" {
+  local key="abc123def456"
+  archivist_storage_init "$key"
+  local older_id="01AAAAAAAAAAAAAAAAAAAAAAAA"
+  local newer_id="01ZZZZZZZZZZZZZZZZZZZZZZZZ"
+  printf '{"id":"%s","summary":"older","created_at":"2026-05-01T00:00:00Z","updated_at":"2026-05-01T00:00:00Z"}\n' "$older_id" \
+    > "${ONLOOKER_DIR}/archivist/${key}/decisions/${older_id}.json"
+  printf '{"id":"%s","summary":"newer","created_at":"2026-05-22T00:00:00Z","updated_at":"2026-05-22T00:00:00Z"}\n' "$newer_id" \
+    > "${ONLOOKER_DIR}/archivist/${key}/decisions/${newer_id}.json"
+
+  local ranked
+  ranked=$(archivist_storage_load_ranked "$key")
+  local first_id
+  first_id=$(printf '%s' "$ranked" | jq -r '.[0].id')
+  [ "$first_id" = "$newer_id" ]
+}

package/test/bats/archivist-ulid.bats

@@ -0,0 +1,36 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+  # shellcheck disable=SC1091
+  source "${REPO_ROOT}/plugins/archivist/scripts/lib/archivist-ulid.sh"
+}
+
+@test "archivist_ulid returns a 26-char crockford base32 string" {
+  local id
+  id=$(archivist_ulid)
+  [ "${#id}" -eq 26 ]
+  [[ "$id" =~ ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ ]]
+}
+
+@test "two ULIDs minted apart are lexicographically ordered" {
+  local a b
+  a=$(archivist_ulid)
+  sleep 0.01
+  b=$(archivist_ulid)
+  [[ "$a" < "$b" ]] || [ "$a" = "$b" ]
+}
+
+@test "many ULIDs are unique" {
+  local seen="${BATS_TEST_TMPDIR}/ulids.txt"
+  : > "$seen"
+  local i
+  for ((i = 0; i < 50; i++)); do
+    printf '%s\n' "$(archivist_ulid)" >> "$seen"
+  done
+  local total unique
+  total=$(wc -l < "$seen" | tr -d ' ')
+  unique=$(sort -u "$seen" | wc -l | tr -d ' ')
+  [ "$total" = "$unique" ]
+}

package/test/bats/cartographer-config.bats

@@ -0,0 +1,107 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/cartographer"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/cartographer-config.sh"
+}
+
+@test "config defaults: disabled by default" {
+  cartographer_config_load ""
+  run cartographer_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable cartographer" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  run cartographer_config_enabled
+  [ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level enabled" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  local repo="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "${repo}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":false}}' > "${repo}/.claude/settings.json"
+  cartographer_config_load "$repo"
+  run cartographer_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "deep merge: user-level partial override preserves plugin defaults" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":12}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  local interval model
+  interval=$(cartographer_config_audit_interval_hours)
+  model=$(cartographer_config_model_extraction)
+  [ "$interval" = "12" ]
+  [ "$model" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "deep merge: repo overrides user but preserves user keys not in repo" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":6,"phase_timeout_seconds":30}}' > "${HOME}/.claude/settings.json"
+  local repo="${BATS_TEST_TMPDIR}/repo2"
+  mkdir -p "${repo}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":48}}' > "${repo}/.claude/settings.json"
+  cartographer_config_load "$repo"
+  local interval timeout_s
+  interval=$(cartographer_config_audit_interval_hours)
+  timeout_s=$(cartographer_config_phase_timeout)
+  [ "$interval" = "48" ]
+  [ "$timeout_s" = "30" ]
+}
+
+@test "model_extraction falls back to default when not configured" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_extraction)
+  [ "$v" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "model_synthesis falls back to default when not configured" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_synthesis)
+  [ "$v" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "model_extraction respects user-level override" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"extraction":{"model":"claude-sonnet-4-6"}}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_extraction)
+  [ "$v" = "claude-sonnet-4-6" ]
+}
+
+@test "phase_timeout_seconds defaults to 60" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_phase_timeout)
+  [ "$v" = "60" ]
+}
+
+@test "audit_interval_hours defaults to 24" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_audit_interval_hours)
+  [ "$v" = "24" ]
+}
+
+@test "exclude_paths defaults are non-empty JSON array" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_exclude_paths)
+  # Must be a non-empty JSON array containing node_modules
+  echo "$v" | jq -e 'type == "array" and length > 0' >/dev/null
+  echo "$v" | jq -e 'any(. == "node_modules")' >/dev/null
+}

package/test/bats/cartographer-lock.bats

@@ -0,0 +1,77 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+  # shellcheck disable=SC1091
+  source "${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-lock.sh"
+
+  LOCK_FILE="${BATS_TEST_TMPDIR}/test.lock"
+}
+
+teardown() {
+  cartographer_lock_release "$LOCK_FILE" 2>/dev/null || true
+}
+
+@test "acquire succeeds when lock is free" {
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "acquire fails immediately when lock is already held" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "release allows re-acquire" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  cartographer_lock_release "$LOCK_FILE"
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_held returns true while lock is held" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_held returns false after release" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  cartographer_lock_release "$LOCK_FILE"
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "release is idempotent (safe to call when not held)" {
+  run cartographer_lock_release "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "two independent lock paths do not interfere" {
+  local lock_a="${BATS_TEST_TMPDIR}/a.lock"
+  local lock_b="${BATS_TEST_TMPDIR}/b.lock"
+  cartographer_lock_acquire "$lock_a"
+  run cartographer_lock_acquire "$lock_b"
+  [ "$status" -eq 0 ]
+  cartographer_lock_release "$lock_a"
+  cartographer_lock_release "$lock_b"
+}
+
+@test "background child holds lock after parent releases its reference" {
+  # Acquire in a background subprocess, then verify is_held from this process.
+  bash -c "
+    source '${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-lock.sh'
+    cartographer_lock_acquire '${LOCK_FILE}'
+    sleep 2
+    cartographer_lock_release '${LOCK_FILE}'
+  " &
+  sleep 0.1
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+  # Second acquire from this process must fail while child holds it
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+  wait
+}

package/test/bats/cartographer-ulid.bats

@@ -0,0 +1,56 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+  # shellcheck disable=SC1091
+  source "${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-ulid.sh"
+}
+
+@test "cartographer_ulid returns a 26-char Crockford Base32 string" {
+  local id
+  id=$(cartographer_ulid)
+  [ "${#id}" -eq 26 ]
+  [[ "$id" =~ ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ ]]
+}
+
+@test "two ULIDs minted apart are lexicographically ordered" {
+  local a b
+  a=$(cartographer_ulid)
+  sleep 0.01
+  b=$(cartographer_ulid)
+  [[ "$a" < "$b" ]] || [ "$a" = "$b" ]
+}
+
+@test "many ULIDs are unique" {
+  local seen="${BATS_TEST_TMPDIR}/ulids.txt"
+  : > "$seen"
+  local i
+  for ((i = 0; i < 50; i++)); do
+    printf '%s\n' "$(cartographer_ulid)" >> "$seen"
+  done
+  local total unique
+  total=$(wc -l < "$seen" | tr -d ' ')
+  unique=$(sort -u "$seen" | wc -l | tr -d ' ')
+  [ "$total" = "$unique" ]
+}
+
+@test "random component is 16 chars (full 80-bit coverage)" {
+  local id
+  id=$(cartographer_ulid)
+  # Characters 10-25 (0-indexed) are the random component
+  local rand_part="${id:10:16}"
+  [ "${#rand_part}" -eq 16 ]
+}
+
+@test "timestamp component sorts ULIDs correctly across 10+ calls" {
+  local prev=""
+  local id
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    id=$(cartographer_ulid)
+    if [[ -n "$prev" ]]; then
+      [[ "$prev" < "$id" ]] || [ "$prev" = "$id" ]
+    fi
+    prev="$id"
+  done
+}

package/test/bats/config.bats

@@ -10,17 +10,15 @@ setup_file() {
   [ "$status" -eq 0 ]
 }
 
-@test "claude plugin versions match package.json" {
+@test "ecosystem plugin.json version matches package.json" {
   local pkg_ver
   pkg_ver=$(jq -r '.version' "${REPO_ROOT}/package.json")
 
+  # Claude Code reads version from plugin.json. marketplace.json should NOT
+  # carry plugins[].version (see plugins-reference: setting both is a drift
+  # hazard since plugin.json silently wins).
   run jq -e --arg v "$pkg_ver" '.version == $v' "${REPO_ROOT}/.claude-plugin/plugin.json"
   [ "$status" -eq 0 ]
-
-  run jq -e --arg v "$pkg_ver" \
-    '[.plugins[].version] | unique | length == 1 and .[0] == $v' \
-    "${REPO_ROOT}/.claude-plugin/marketplace.json"
-  [ "$status" -eq 0 ]
 }
 
 @test "hooks.json wildcard matcher references tool-sequence-tracker" {
@@ -97,17 +95,19 @@ setup_file() {
   [[ "$hook_cmd" == *tool-history-tracker.sh ]]
 }
 
-@test "hooks.json UserPromptSubmit references turn and session-duration trackers" {
-  run jq -e '.hooks.UserPromptSubmit[0].hooks | length == 2' "${REPO_ROOT}/hooks/hooks.json"
+@test "hooks.json UserPromptSubmit references turn, session-duration, and prompt-rule trackers" {
+  run jq -e '.hooks.UserPromptSubmit[0].hooks | length == 3' "${REPO_ROOT}/hooks/hooks.json"
   [ "$status" -eq 0 ]
 
-  local turn_cmd duration_cmd
+  local turn_cmd duration_cmd rule_cmd
   turn_cmd=$(jq -r '.hooks.UserPromptSubmit[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
   duration_cmd=$(jq -r '.hooks.UserPromptSubmit[0].hooks[1].command' "${REPO_ROOT}/hooks/hooks.json")
+  rule_cmd=$(jq -r '.hooks.UserPromptSubmit[0].hooks[2].command' "${REPO_ROOT}/hooks/hooks.json")
   [[ "$turn_cmd" == *turn-tracker.sh ]]
   [[ "$duration_cmd" == *session-duration-tracker.sh ]]
+  [[ "$rule_cmd" == *prompt-rule-injector.sh ]]
 
-  for hook_cmd in "$turn_cmd" "$duration_cmd"; do
+  for hook_cmd in "$turn_cmd" "$duration_cmd" "$rule_cmd"; do
     local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
     script_path="${script_path//\"/}"
     run test -x "$script_path"