@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/archivist/scripts/hooks/archivist-inject.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# Archivist SessionStart injection hook.
+#
+# Triggered by SessionStart (matcher: *). Loads ranked artifacts for the
+# current project key and emits them as invisible `additionalContext` in the
+# hook output, within configured budgets.
+#
+# Ranking: pinned items first (in their pinned order), then everything else by
+# updated_at descending. Items are dropped from the bottom of the list once
+# either max_items or max_chars is exhausted.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits valid hookSpecificOutput JSON, even if there's nothing to inject.
+#   - Skips work if archivist.enabled is not true.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+fi
+
+# shellcheck source=../lib/archivist-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-project-key.sh"
+# shellcheck source=../lib/archivist-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-storage.sh"
+# shellcheck source=../lib/archivist-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-config.sh"
+
+# Emit a hookSpecificOutput JSON object with the given additionalContext string.
+# Empty string is fine — it just means "nothing to add".
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '
+		{
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: $ctx
+			}
+		}
+	'
+}
+
+INPUT=$(cat)
+
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SOURCE=$(printf '%s' "$INPUT" | jq -r '.source // "startup"' 2>/dev/null) || SOURCE="startup"
+
+REPO_ROOT=$(archivist_project_repo_root "$CWD")
+PROJECT_KEY=$(archivist_project_key "$CWD")
+
+archivist_config_load "$REPO_ROOT"
+
+if ! archivist_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+MAX_ITEMS=$(archivist_config_get '.archivist.injection.max_items')
+[[ -z "$MAX_ITEMS" || "$MAX_ITEMS" == "null" ]] && MAX_ITEMS=8
+
+MAX_CHARS=$(archivist_config_get '.archivist.injection.max_chars')
+[[ -z "$MAX_CHARS" || "$MAX_CHARS" == "null" ]] && MAX_CHARS=2400
+
+INCLUDE_DEAD_ENDS=$(archivist_config_get '.archivist.injection.include_dead_ends')
+INCLUDE_OPEN_QUESTIONS=$(archivist_config_get '.archivist.injection.include_open_questions')
+
+RANKED=$(archivist_storage_load_ranked "$PROJECT_KEY")
+TOTAL_ITEMS=$(printf '%s' "$RANKED" | jq 'length' 2>/dev/null) || TOTAL_ITEMS=0
+
+if [[ "$TOTAL_ITEMS" -eq 0 ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Filter out kinds the user disabled.
+if [[ "$INCLUDE_DEAD_ENDS" != "true" ]]; then
+	RANKED=$(printf '%s' "$RANKED" | jq 'map(select(.kind != "dead_ends"))')
+fi
+if [[ "$INCLUDE_OPEN_QUESTIONS" != "true" ]]; then
+	RANKED=$(printf '%s' "$RANKED" | jq 'map(select(.kind != "open_questions"))')
+fi
+
+# Build the rendered context one item at a time, respecting both budgets.
+HEADER="Archivist — carried over from prior sessions in this repo (kind | summary):"
+RENDERED="$HEADER"
+RUNNING_CHARS=${#HEADER}
+EMITTED=0
+
+COUNT=$(printf '%s' "$RANKED" | jq 'length')
+for ((i = 0; i < COUNT; i++)); do
+	[[ "$EMITTED" -ge "$MAX_ITEMS" ]] && break
+
+	ITEM=$(printf '%s' "$RANKED" | jq ".[$i]")
+	KIND=$(printf '%s' "$ITEM" | jq -r '.kind // ""')
+	SUMMARY=$(printf '%s' "$ITEM" | jq -r '.summary // ""')
+	DETAIL=$(printf '%s' "$ITEM" | jq -r '.detail // ""')
+	PINNED=$(printf '%s' "$ITEM" | jq -r '.pinned // false')
+	FILES=$(printf '%s' "$ITEM" | jq -r '(.files // []) | join(", ")')
+
+	[[ -z "$SUMMARY" ]] && continue
+
+	# Map directory-style kinds to human-readable labels.
+	LABEL="$KIND"
+	case "$KIND" in
+		decisions) LABEL="decision" ;;
+		dead_ends) LABEL="dead-end" ;;
+		open_questions) LABEL="open-question" ;;
+	esac
+
+	LINE=""
+	if [[ "$PINNED" == "true" ]]; then
+		LINE="- [pinned ${LABEL}] ${SUMMARY}"
+	else
+		LINE="- [${LABEL}] ${SUMMARY}"
+	fi
+	if [[ -n "$DETAIL" && "$DETAIL" != "null" ]]; then
+		LINE="${LINE}"$'\n'"  ${DETAIL}"
+	fi
+	if [[ -n "$FILES" ]]; then
+		LINE="${LINE}"$'\n'"  files: ${FILES}"
+	fi
+
+	LINE_LEN=$((${#LINE} + 1))
+	if (( RUNNING_CHARS + LINE_LEN > MAX_CHARS )); then
+		break
+	fi
+
+	RENDERED="${RENDERED}"$'\n'"${LINE}"
+	RUNNING_CHARS=$((RUNNING_CHARS + LINE_LEN))
+	EMITTED=$((EMITTED + 1))
+done
+
+if [[ "$EMITTED" -eq 0 ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Trailer with provenance + how to disable (helps future-you debug).
+RENDERED="${RENDERED}"$'\n\n'"(Archivist injected ${EMITTED}/${TOTAL_ITEMS} items for project key ${PROJECT_KEY}. Set archivist.enabled=false to disable. Source: ${SOURCE}.)"
+
+_emit "$RENDERED"
+exit 0

package/plugins/archivist/scripts/lib/archivist-config.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Config resolution for Archivist.
+#
+# Reads three layers, latest wins:
+#   1. plugins/archivist/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   archivist_config_load <repo_root>    # populates _ARCHIVIST_CONFIG (JSON)
+#   archivist_config_get <jq-path>       # echoes string value (empty if unset)
+#   archivist_config_enabled             # 0 if archivist.enabled is true
+#
+# Settings overlay only touches the `archivist.*` subtree of settings.json so it
+# coexists with other plugins' configuration.
+
+_ARCHIVIST_CONFIG="{}"
+
+archivist_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ archivist: (.archivist // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		merged=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) || true
+	done
+
+	_ARCHIVIST_CONFIG="$merged"
+}
+
+# Read a value from the loaded config. Usage:
+#   archivist_config_get '.archivist.injection.max_items'
+archivist_config_get() {
+	local path="$1"
+	printf '%s' "$_ARCHIVIST_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+# Returns 0 if archivist.enabled is true, 1 otherwise.
+archivist_config_enabled() {
+	local v
+	v=$(archivist_config_get '.archivist.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/archivist/scripts/lib/archivist-project-key.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Project key derivation for Archivist.
+#
+# A project key is a stable 12-char hex identifier that survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works (caller decides whether to skip or treat as a non-repo session).
+
+# Portable SHA256 helper. Prefers shasum (BSD/macOS), falls back to sha256sum.
+_archivist_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+# Resolve git remote URL for the given cwd. Empty string if no remote.
+archivist_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Resolve repository toplevel (worktree-aware: uses common-dir to get the main
+# repo path so worktrees share a key with their parent).
+archivist_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	# git-common-dir may be relative; resolve relative to cwd.
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		# common_dir is typically the .git dir of the main repo; its parent is
+		# the repo root.
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty string.
+# Usage: key=$(archivist_project_key "$CWD")
+archivist_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(archivist_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_archivist_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(archivist_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_archivist_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	# No git context at all — return empty so the caller skips archivist work.
+	return 0
+}

package/plugins/archivist/scripts/lib/archivist-storage.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Storage layout and path-validation helpers for Archivist.
+#
+# Layout (under $ONLOOKER_DIR/archivist/<project-key>/):
+#   manifest.json              project metadata: remote_url, repo_root, last_compact_at
+#   decisions/<ulid>.json      one decision per file
+#   dead_ends/<ulid>.json      one dead-end per file
+#   open_questions/<ulid>.json one question per file
+#   pinned.json                { "ids": ["01J...", ...] } -- always reinject first
+#
+# All paths inside artifacts are stored RELATIVE to the repo root. Validation
+# happens before write: anything resolving outside the repo (or that does not
+# exist) is dropped. This is the second line of defense against cross-project
+# contamination after project-key isolation.
+
+# ============================================================================
+# Path helpers
+# ============================================================================
+
+# Root directory for archivist artifacts. Honors $ONLOOKER_DIR if set so tests
+# can isolate writes.
+archivist_storage_root() {
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	printf '%s/archivist' "$base"
+}
+
+archivist_project_dir() {
+	local key="$1"
+	printf '%s/%s' "$(archivist_storage_root)" "$key"
+}
+
+archivist_kind_dir() {
+	local key="$1"
+	local kind="$2"
+	printf '%s/%s' "$(archivist_project_dir "$key")" "$kind"
+}
+
+# Ensure the directory tree exists for a given project key.
+archivist_storage_init() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	local project_dir
+	project_dir=$(archivist_project_dir "$key")
+	mkdir -p \
+		"$project_dir/decisions" \
+		"$project_dir/dead_ends" \
+		"$project_dir/open_questions" 2>/dev/null
+}
+
+# Write or update the project manifest.
+# Usage: archivist_storage_write_manifest <key> <remote_url> <repo_root>
+archivist_storage_write_manifest() {
+	local key="$1"
+	local remote_url="$2"
+	local repo_root="$3"
+	[[ -z "$key" ]] && return 1
+
+	archivist_storage_init "$key" || return 1
+
+	local manifest_path
+	manifest_path="$(archivist_project_dir "$key")/manifest.json"
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	jq -n \
+		--arg key "$key" \
+		--arg remote "$remote_url" \
+		--arg root "$repo_root" \
+		--arg now "$now" \
+		'{
+			project_key: $key,
+			remote_url: (if $remote == "" then null else $remote end),
+			repo_root: (if $root == "" then null else $root end),
+			last_compact_at: $now,
+			source: "local"
+		}' > "$manifest_path" 2>/dev/null
+}
+
+# ============================================================================
+# Path validation (drop entries pointing outside the repo)
+# ============================================================================
+
+# Given a repo root and a path string (possibly absolute, possibly relative,
+# possibly with ../), echo the path relativized to the repo root iff it resolves
+# inside the repo AND the file exists. Otherwise echo nothing.
+#
+# Worktrees: an absolute path that lives in a checked-out worktree of the same
+# repo is considered "in repo" — we resolve against the worktree's toplevel.
+archivist_validate_repo_path() {
+	local repo_root="$1"
+	local candidate="$2"
+	[[ -z "$repo_root" || -z "$candidate" ]] && return 0
+	[[ ! -d "$repo_root" ]] && return 0
+
+	local abs_root
+	abs_root=$(cd "$repo_root" 2>/dev/null && pwd -P) || return 0
+
+	local resolved
+	if [[ "$candidate" == /* ]]; then
+		resolved="$candidate"
+	else
+		resolved="$repo_root/$candidate"
+	fi
+
+	# Resolve to a physical path so symlinks (e.g. macOS /var -> /private/var)
+	# don't cause a false-negative against abs_root. realpath handles
+	# nonexistent leaf names via strict=False so we can still emit the
+	# canonical form and let the -e check below decide.
+	resolved=$(python3 -c '
+import os, sys
+print(os.path.realpath(sys.argv[1]))
+' "$resolved" 2>/dev/null) || return 0
+
+	# Must live under repo root and exist on disk.
+	case "$resolved" in
+		"$abs_root"|"$abs_root"/*) : ;;
+		*) return 0 ;;
+	esac
+
+	[[ -e "$resolved" ]] || return 0
+
+	# Echo relative form (strip "$abs_root/" prefix).
+	if [[ "$resolved" == "$abs_root" ]]; then
+		printf '.'
+	else
+		printf '%s' "${resolved#"$abs_root/"}"
+	fi
+}
+
+# Given a JSON array of file path strings, return a JSON array containing only
+# the paths that pass validation, relativized to the repo root.
+# Usage: cleaned=$(archivist_validate_paths_array "$repo_root" "$paths_json")
+archivist_validate_paths_array() {
+	local repo_root="$1"
+	local paths_json="$2"
+	[[ -z "$paths_json" || "$paths_json" == "null" ]] && { echo '[]'; return 0; }
+
+	local out='[]'
+	local count i candidate cleaned
+	count=$(printf '%s' "$paths_json" | jq 'length' 2>/dev/null) || count=0
+	for ((i = 0; i < count; i++)); do
+		candidate=$(printf '%s' "$paths_json" | jq -r ".[$i]" 2>/dev/null) || continue
+		[[ -z "$candidate" || "$candidate" == "null" ]] && continue
+		cleaned=$(archivist_validate_repo_path "$repo_root" "$candidate")
+		[[ -z "$cleaned" ]] && continue
+		out=$(printf '%s' "$out" | jq --arg p "$cleaned" '. + [$p]')
+	done
+	printf '%s' "$out"
+}
+
+# ============================================================================
+# Artifact write
+# ============================================================================
+
+# Write a single artifact file. Returns the path written on success.
+# Usage: archivist_storage_write_artifact <key> <kind> <id> <json>
+archivist_storage_write_artifact() {
+	local key="$1"
+	local kind="$2"
+	local id="$3"
+	local json="$4"
+	[[ -z "$key" || -z "$kind" || -z "$id" || -z "$json" ]] && return 1
+
+	case "$kind" in
+		decisions|dead_ends|open_questions) : ;;
+		*) return 1 ;;
+	esac
+
+	archivist_storage_init "$key" || return 1
+	local out_path
+	out_path="$(archivist_kind_dir "$key" "$kind")/${id}.json"
+	printf '%s\n' "$json" > "$out_path" 2>/dev/null && printf '%s' "$out_path"
+}
+
+# ============================================================================
+# Artifact read (for injection)
+# ============================================================================
+
+# Read all artifacts for a given project key as a single JSON array, with each
+# entry augmented with a `kind` field. Output is sorted by `updated_at`
+# descending. Pinned IDs (from pinned.json) come first regardless of recency.
+#
+# Usage: items=$(archivist_storage_load_ranked <key>)
+archivist_storage_load_ranked() {
+	local key="$1"
+	[[ -z "$key" ]] && { echo '[]'; return 0; }
+
+	local project_dir
+	project_dir=$(archivist_project_dir "$key")
+	[[ ! -d "$project_dir" ]] && { echo '[]'; return 0; }
+
+	local pinned_file="$project_dir/pinned.json"
+	local pinned_json='{"ids":[]}'
+	[[ -f "$pinned_file" ]] && pinned_json=$(cat "$pinned_file" 2>/dev/null) || true
+
+	local kind file all='[]'
+	for kind in decisions dead_ends open_questions; do
+		[[ -d "$project_dir/$kind" ]] || continue
+		for file in "$project_dir/$kind"/*.json; do
+			[[ -f "$file" ]] || continue
+			local item
+			item=$(jq --arg k "$kind" '. + {kind: $k}' "$file" 2>/dev/null) || continue
+			all=$(printf '%s' "$all" | jq --argjson item "$item" '. + [$item]')
+		done
+	done
+
+	printf '%s' "$all" | jq --argjson pinned "$pinned_json" '
+		($pinned.ids // []) as $pids
+		| map(. + { pinned: (.id as $id | $pids | index($id) != null) })
+		| sort_by([
+			(if .pinned then 0 else 1 end),
+			-((.updated_at // .created_at // "") | sub("[^0-9]"; ""; "g") | tonumber? // 0)
+		])
+	'
+}

package/plugins/archivist/scripts/lib/archivist-ulid.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Archivist artifact IDs.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+#
+# We do not need monotonicity across rapid bursts inside a single ms (the spec's
+# optional monotonic mode), since archivist artifacts are written infrequently.
+
+_ARCHIVIST_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+# Encode a decimal integer to a fixed-length Crockford Base32 string (uppercase).
+# Usage: _archivist_ulid_encode <integer> <length>
+_archivist_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_ARCHIVIST_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+# Generate one ULID. Prints 26 chars (timestamp + randomness).
+archivist_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	# 80 bits of randomness, split into two 40-bit halves so we stay inside
+	# bash arithmetic (signed 64-bit).
+	local rand_hi rand_lo
+	rand_hi=$((RANDOM * 32768 + RANDOM))
+	rand_lo=$((RANDOM * 32768 + RANDOM))
+	rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+
+	local ts_part hi_part lo_part
+	ts_part=$(_archivist_ulid_encode "$now_ms" 10)
+	hi_part=$(_archivist_ulid_encode "$rand_hi" 8)
+	lo_part=$(_archivist_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/cartographer/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "cartographer",
+  "version": "0.2.0",
+  "description": "Proactive periodic auditor of the persistent instruction layer (CLAUDE.md, AGENTS.md, .claude/rules/). Discovers all instruction files in the repo, extracts semantic maps, and surfaces contradictions, shadowing, gaps, and drift before they cause expensive agent misbehavior. Builds on the Onlooker ecosystem plugin.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": ["./skills/cartographer"],
+  "agents": []
+}

package/plugins/cartographer/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to the Cartographer plugin are documented here.
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/cartographer-v0.1.0...cartographer-v0.2.0) (2026-05-25)
+
+
+### Features
+
+* **cartographer:** add proactive instruction-file audit plugin :mag: ([#35](https://github.com/onlooker-community/ecosystem/issues/35)) ([387d00a](https://github.com/onlooker-community/ecosystem/commit/387d00ad04da5aae91048254ad0526bb674ed498))
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/releases/tag/cartographer-v0.1.0) (2026-05-25)
+
+### Added
+
+- SessionStart hook with interval gate and non-blocking background audit launch (`nohup setsid`)
+- PostToolUse hook on Write/Edit/MultiEdit with exact `basename(realpath(...))` matching for CLAUDE.md files
+- Five-phase audit pipeline: discover → extract → relate → synthesize → emit
+- LLM-assisted analysis for contradictions, stale references, dead rules, and scope collisions
+- `flock`-based cross-session audit lock with PID-file fallback for macOS
+- Commutative `finding_hash` (SHA256) for stable finding identity across audit runs
+- Atomic finding writes (`*.tmp` + `mv -f`) and `dedup/<hash>` sentinel store
+- At-least-once `cartographer.issue.found` event delivery; documented dedup contract
+- `/cartographer` skill with `--verbose`, `--status`, `--force`, `--scope`, and `--phase` flags
+- Four ADRs documenting key design decisions
+- Default `exclude_paths` covering `node_modules`, `.git`, `vendor`, `.venv`, and common build dirs
+- `enabled: false` default — opt-in activation via `.claude/settings.json`