@onlooker-community/ecosystem 0.14.0 → 0.15.1

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# cartographer-project-key.sh — stable 12-char hex project key.
+#
+# Derives a key that survives repo renames, clones, and worktrees.
+# Algorithm:
+#   1. git remote get-url origin → sha256("remote:" + url)[0:12]
+#   2. Fallback: git rev-parse --show-toplevel → sha256("root:" + path)[0:12]
+#   3. Non-git: sha256("cwd:" + pwd)[0:12]
+#
+# Usage:
+#   key=$(cartographer_project_key <cwd>)
+#   root=$(cartographer_project_repo_root <cwd>)
+
+_cartographer_sha256_first12() {
+	local input="$1"
+	if command -v sha256sum &>/dev/null; then
+		printf '%s' "$input" | sha256sum | cut -c1-12
+	elif command -v shasum &>/dev/null; then
+		printf '%s' "$input" | shasum -a 256 | cut -c1-12
+	else
+		printf '%s' "$input" | python3 -c \
+			'import sys,hashlib; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:12])'
+	fi
+}
+
+cartographer_project_repo_root() {
+	local cwd="${1:-$(pwd)}"
+	local root
+	root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null) && printf '%s' "$root" && return 0
+	printf '%s' "$cwd"
+}
+
+cartographer_project_remote_url() {
+	local cwd="${1:-$(pwd)}"
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+cartographer_project_key() {
+	local cwd="${1:-$(pwd)}"
+	local remote
+	remote=$(cartographer_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_cartographer_sha256_first12 "remote:${remote}"
+		return 0
+	fi
+
+	local root
+	root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)
+	if [[ -n "$root" ]]; then
+		_cartographer_sha256_first12 "root:${root}"
+		return 0
+	fi
+
+	_cartographer_sha256_first12 "cwd:${cwd}"
+}

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# cartographer-ulid.sh — ULID generation for Cartographer.
+#
+# Generates Universally Unique Lexicographically Sortable Identifiers:
+# 10-char Crockford Base32 timestamp + 16-char random component = 26 chars.
+#
+# Usage:
+#   id=$(cartographer_ulid)
+
+_CARTOGRAPHER_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_cartographer_ulid_encode() {
+	local n="${1:-0}"
+	local len="${2:-10}"
+	local result=""
+	local i
+	for (( i = 0; i < len; i++ )); do
+		result="${_CARTOGRAPHER_ULID_ALPHABET:$(( n & 31 )):1}${result}"
+		n=$(( n >> 5 ))
+	done
+	printf '%s' "$result"
+}
+
+cartographer_ulid() {
+	local ts_ms
+	if date +%s%3N &>/dev/null && [[ "$(date +%s%3N)" =~ ^[0-9]{13}$ ]]; then
+		ts_ms=$(date +%s%3N)
+	else
+		ts_ms=$(python3 -c 'import time; print(int(time.time() * 1000))')
+	fi
+
+	local ts_encoded
+	ts_encoded=$(_cartographer_ulid_encode "$ts_ms" 10)
+
+	local rand_hex
+	rand_hex=$(openssl rand -hex 10 2>/dev/null) \
+		|| rand_hex=$(printf '%020x' $(( (RANDOM * RANDOM & 0xFFFFF) * 0x100000 + (RANDOM * RANDOM & 0xFFFFF) )))
+
+	# Bash integers are 63-bit signed, so split the 80-bit random across two 40-bit halves.
+	local rand_hi rand_lo
+	rand_hi=$(( 16#${rand_hex:0:10} ))
+	rand_lo=$(( 16#${rand_hex:10:10} ))
+	local rand_encoded
+	rand_encoded="$(_cartographer_ulid_encode "$rand_hi" 8)$(_cartographer_ulid_encode "$rand_lo" 8)"
+
+	printf '%s%s' "$ts_encoded" "$rand_encoded"
+}

package/plugins/cartographer/scripts/run-audit.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# run-audit.sh — Cartographer audit pipeline (5 phases).
+#
+# Intended to run as a detached background process launched by the SessionStart
+# hook. Also called directly by the /cartographer skill (foreground).
+#
+# Phases:
+#   1. discover   — collect all auditable files
+#   2. extract    — per-file content hash (incremental cache key)
+#   3. relate     — contradiction + dead_rule analysis (LLM)
+#   4. synthesize — stale_ref + scope_collision + finding hash computation
+#   5. emit       — persist findings atomically, emit events for new findings
+#
+# Environment:
+#   CARTOGRAPHER_DIR    — state directory (~/.onlooker/cartographer/<project_key>)
+#   CARTOGRAPHER_TRIGGER — "session_start_interval" | "session_start_first_run" | "post_tool_use" | "manual"
+#   CARTOGRAPHER_TARGET_FILE — (optional) single file for targeted post-write audit
+#   CLAUDE_PLUGIN_ROOT  — plugin root directory
+#
+# Invariant: last_audit_at is written ONLY on full successful completion of all
+# phases. Partial runs leave last_audit_at unchanged so the next session retries.
+
+set -uo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-ulid.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
+
+CARTOGRAPHER_DIR="${CARTOGRAPHER_DIR:?CARTOGRAPHER_DIR must be set}"
+TRIGGER="${CARTOGRAPHER_TRIGGER:-manual}"
+TARGET_FILE="${CARTOGRAPHER_TARGET_FILE:-}"
+REPO_ROOT="${CARTOGRAPHER_REPO_ROOT:-$(pwd)}"
+AUDIT_ID=$(cartographer_ulid)
+START_TS=$(date +%s)
+
+_TIMEOUT_CMD=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || printf 'timeout')
+
+FINDINGS_DIR="$CARTOGRAPHER_DIR/findings"
+DEDUP_DIR="$CARTOGRAPHER_DIR/dedup"
+RUNS_DIR="$CARTOGRAPHER_DIR/runs"
+mkdir -p "$FINDINGS_DIR" "$DEDUP_DIR" "$RUNS_DIR"
+
+PHASES_COMPLETED=()
+PHASES_FAILED=()
+ALL_FINDINGS="[]"
+
+_phase_timeout=$(cartographer_config_phase_timeout)
+_total_timeout=$(cartographer_config_total_timeout)
+log() { printf '[cartographer] %s\n' "$*" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1; }
+[[ "$_total_timeout" -lt $(( _phase_timeout * 3 )) ]] && \
+	log "warning: total_timeout_seconds=${_total_timeout} is less than 3× phase_timeout_seconds=${_phase_timeout}; phases may be killed early"
+_model_extraction=$(cartographer_config_model_extraction)
+_model_synthesis=$(cartographer_config_model_synthesis)
+_max_tokens_extraction=$(cartographer_config_max_output_tokens_extraction)
+_max_tokens_synthesis=$(cartographer_config_max_output_tokens_synthesis)
+_exclude_json=$(cartographer_config_exclude_paths)
+
+emit_safe() {
+	cartographer_emit_event "$1" "$2" 2>>"$CARTOGRAPHER_DIR/audit.log" || true
+}
+
+# ── Phase 1: Discover ──────────────────────────────────────────────────────────
+run_discover() {
+	log "phase=discover starting"
+	local repo_root="$REPO_ROOT"
+
+	if [[ -n "$TARGET_FILE" ]]; then
+		# Targeted post-write audit: only the modified file
+		DISCOVERED_FILES=$(jq -n --arg f "$TARGET_FILE" '[$f]')
+		GLOBAL_FILES="[]"
+	else
+		local raw_files
+		raw_files=$(cartographer_collect_files "$repo_root" "$_exclude_json" 5)
+		DISCOVERED_FILES=$(printf '%s\n' "$raw_files" | grep -v '^$' | jq -R . | jq -s .)
+		local raw_global
+		raw_global=$(cartographer_collect_global_files)
+		GLOBAL_FILES=$(printf '%s\n' "$raw_global" | grep -v '^$' | jq -R . | jq -s .)
+	fi
+
+	local file_count
+	file_count=$(printf '%s' "$DISCOVERED_FILES" | jq 'length')
+	log "phase=discover files=${file_count}"
+	PHASES_COMPLETED+=("discover")
+}
+
+# ── Phase 2: Extract ───────────────────────────────────────────────────────────
+run_extract() {
+	log "phase=extract starting"
+	local cached=0 computed=0
+
+	EXTRACT_CACHE="{}"
+	while IFS= read -r fpath; do
+		[[ -z "$fpath" || ! -f "$fpath" ]] && continue
+		local fhash
+		fhash=$(cartographer_file_content_hash "$fpath") || continue
+		local cache_file="$CARTOGRAPHER_DIR/extracts/${fhash}.json"
+
+		if [[ -f "$cache_file" ]]; then
+			(( cached++ )) || true
+		else
+			mkdir -p "$CARTOGRAPHER_DIR/extracts"
+			printf '{"path":"%s","hash":"%s"}' "$fpath" "$fhash" >"${cache_file}.tmp"
+			mv -f "${cache_file}.tmp" "$cache_file"
+			(( computed++ )) || true
+		fi
+		EXTRACT_CACHE=$(printf '%s' "$EXTRACT_CACHE" \
+			| jq --arg p "$fpath" --arg h "$fhash" '.[$p]=$h')
+	done < <(printf '%s' "$DISCOVERED_FILES" | jq -r '.[]' 2>/dev/null)
+
+	log "phase=extract cached=${cached} computed=${computed}"
+	PHASES_COMPLETED+=("extract")
+}
+
+# ── Phase 3: Relate (contradiction + dead_rule) ────────────────────────────────
+run_relate() {
+	log "phase=relate starting"
+	local findings
+	findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_contradiction '$DISCOVERED_FILES' \
+		   '$_model_extraction' '$_max_tokens_extraction' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || {
+		log "phase=relate timeout or error"
+		PHASES_FAILED+=("relate")
+		return 1
+	}
+	RELATE_FINDINGS="${findings:-[]}"
+	local count
+	count=$(printf '%s' "$RELATE_FINDINGS" | jq 'length' 2>/dev/null || printf '0')
+	log "phase=relate findings=${count}"
+	PHASES_COMPLETED+=("relate")
+}
+
+# ── Phase 4: Synthesize (stale_ref + scope_collision + hash) ──────────────────
+run_synthesize() {
+	log "phase=synthesize starting"
+
+	local stale_findings scope_findings
+	stale_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_stale_ref '$DISCOVERED_FILES' '$REPO_ROOT' \
+		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || stale_findings="[]"
+
+	scope_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_scope_collision '$GLOBAL_FILES' '$DISCOVERED_FILES' \
+		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || scope_findings="[]"
+
+	# Merge all raw findings
+	local raw_all
+	raw_all=$(jq -n \
+		--argjson relate "${RELATE_FINDINGS:-[]}" \
+		--argjson stale "${stale_findings:-[]}" \
+		--argjson scope "${scope_findings:-[]}" \
+		'$relate + $stale + $scope')
+
+	# Add finding_hash to each finding
+	ALL_FINDINGS="[]"
+	local idx=0
+	while IFS= read -r finding; do
+		[[ -z "$finding" ]] && continue
+		local ftype ffile_a fexcerpt_a ffile_b fexcerpt_b
+		ftype=$(printf '%s' "$finding" | jq -r '.type // "unknown"')
+		ffile_a=$(printf '%s' "$finding" | jq -r '.file_a // ""')
+		fexcerpt_a=$(printf '%s' "$finding" | jq -r '.excerpt_a // ""')
+		ffile_b=$(printf '%s' "$finding" | jq -r '.file_b // ""')
+		fexcerpt_b=$(printf '%s' "$finding" | jq -r '.excerpt_b // ""')
+
+		local fhash
+		fhash=$(cartographer_finding_hash \
+			"$ftype" "$ffile_a" "$fexcerpt_a" "$ffile_b" "$fexcerpt_b")
+
+		local enriched
+		enriched=$(printf '%s' "$finding" \
+			| jq --arg h "$fhash" --arg aid "$AUDIT_ID" \
+			  '. + {"finding_hash":$h,"audit_id":$aid}')
+		ALL_FINDINGS=$(printf '%s' "$ALL_FINDINGS" \
+			| jq --argjson f "$enriched" '. + [$f]')
+		(( idx++ )) || true
+	done < <(printf '%s' "$raw_all" | jq -c '.[]' 2>/dev/null)
+
+	log "phase=synthesize total_findings=$(printf '%s' "$ALL_FINDINGS" | jq 'length')"
+	PHASES_COMPLETED+=("synthesize")
+}
+
+# ── Phase 5: Emit ──────────────────────────────────────────────────────────────
+run_emit() {
+	log "phase=emit starting"
+	local new_count=0 known_count=0
+
+	while IFS= read -r finding; do
+		[[ -z "$finding" ]] && continue
+		local fhash
+		fhash=$(printf '%s' "$finding" | jq -r '.finding_hash')
+		[[ -z "$fhash" ]] && continue
+
+		local finding_file="$FINDINGS_DIR/${fhash}.json"
+		local dedup_sentinel="$DEDUP_DIR/${fhash}"
+		local now
+		now=$(date +%s)
+
+		if [[ -f "$dedup_sentinel" ]]; then
+			# Known finding — update last_seen_at atomically, no bus event
+			(( known_count++ )) || true
+			if [[ -f "$finding_file" ]]; then
+				local updated
+				updated=$(jq --argjson ts "$now" '.last_seen_at=$ts' "$finding_file" 2>/dev/null) || true
+				[[ -n "$updated" ]] && printf '%s\n' "$updated" >"${finding_file}.tmp" \
+					&& mv -f "${finding_file}.tmp" "$finding_file"
+			fi
+		else
+			# New finding — write file atomically, emit bus event, then mark dedup
+			local with_ts
+			with_ts=$(printf '%s' "$finding" \
+				| jq --argjson ts "$now" '. + {"first_seen_at":$ts,"last_seen_at":$ts,"resolved":false}')
+			printf '%s\n' "$with_ts" >"${finding_file}.tmp"
+			mv -f "${finding_file}.tmp" "$finding_file"
+
+			local ftype fseverity ffile_a ffile_b fdesc
+			ftype=$(printf '%s' "$finding" | jq -r '.type // "unknown"')
+			fseverity=$(printf '%s' "$finding" | jq -r '.severity // "warning"')
+			ffile_a=$(printf '%s' "$finding" | jq -r '.file_a // ""')
+			ffile_b=$(printf '%s' "$finding" | jq -r '.file_b // null')
+			fdesc=$(printf '%s' "$finding" | jq -r '.description // ""')
+
+			emit_safe "cartographer.issue.found" "$(jq -n \
+				--arg audit_id "$AUDIT_ID" \
+				--arg finding_hash "$fhash" \
+				--arg finding_type "$ftype" \
+				--arg severity "$fseverity" \
+				--argjson affected_files "$(jq -n --arg a "$ffile_a" --arg b "$ffile_b" \
+					'if $b == "null" or $b == "" then [$a] else [$a,$b] end')" \
+				--arg summary "$fdesc" \
+				'{"audit_id":$audit_id,"finding_hash":$finding_hash,"finding_type":$finding_type,"severity":$severity,"affected_files":$affected_files,"summary":$summary}')"
+
+			touch "$dedup_sentinel"
+			(( new_count++ )) || true
+		fi
+	done < <(printf '%s' "$ALL_FINDINGS" | jq -c '.[]' 2>/dev/null)
+
+	log "phase=emit new=${new_count} known=${known_count}"
+
+	local end_ts duration_ms total_count
+	end_ts=$(date +%s)
+	duration_ms=$(( (end_ts - START_TS) * 1000 ))
+	total_count=$(printf '%s' "$ALL_FINDINGS" | jq 'length')
+
+	# Write run record
+	local run_file="$RUNS_DIR/audit-${AUDIT_ID}.json"
+	jq -n \
+		--arg audit_id "$AUDIT_ID" \
+		--arg trigger "$TRIGGER" \
+		--argjson new_finding_count "$new_count" \
+		--argjson known_finding_count "$known_count" \
+		--argjson total_finding_count "$total_count" \
+		--argjson duration_ms "$duration_ms" \
+		--argjson phases_completed "$(printf '%s\n' "${PHASES_COMPLETED[@]}" | jq -R . | jq -s .)" \
+		--argjson phases_failed "$(printf '%s\n' "${PHASES_FAILED[@]:-}" | jq -R . | jq -s .)" \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"known_finding_count":$known_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms,"phases_completed":$phases_completed,"phases_failed":$phases_failed}' \
+		>"${run_file}.tmp" && mv -f "${run_file}.tmp" "$run_file"
+
+	emit_safe "cartographer.audit.complete" "$(jq -n \
+		--arg audit_id "$AUDIT_ID" \
+		--arg trigger "$TRIGGER" \
+		--argjson new_finding_count "$new_count" \
+		--argjson total_finding_count "$total_count" \
+		--argjson duration_ms "$duration_ms" \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms}')"
+
+	PHASES_COMPLETED+=("emit")
+}
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+main() {
+	log "audit_id=${AUDIT_ID} trigger=${TRIGGER} starting"
+
+	run_discover || { log "discover failed"; exit 1; }
+	run_extract  || { log "extract failed (non-fatal, continuing)"; }
+	run_relate   || { log "relate phase failed"; PHASES_FAILED+=("relate"); }
+	run_synthesize || { log "synthesize phase failed"; PHASES_FAILED+=("synthesize"); }
+	run_emit || { log "emit phase failed"; exit 1; }
+
+	# Only advance last_audit_at for full (non-targeted) audits with no failures.
+	# Targeted post-write audits cover only a single file and must not reset the
+	# interval gate — the next session start would otherwise skip a needed full run.
+	if [[ "${#PHASES_FAILED[@]}" -eq 0 && -z "$TARGET_FILE" ]]; then
+		printf '%d' "$(date +%s)" >"$CARTOGRAPHER_DIR/last_audit_at"
+		log "audit_id=${AUDIT_ID} completed successfully"
+	elif [[ "${#PHASES_FAILED[@]}" -gt 0 ]]; then
+		log "audit_id=${AUDIT_ID} partial — last_audit_at not advanced (failed: ${PHASES_FAILED[*]})"
+	else
+		log "audit_id=${AUDIT_ID} targeted audit complete — last_audit_at not advanced"
+	fi
+}
+
+main "$@"

package/plugins/cartographer/skills/cartographer/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: cartographer
+description: Audit CLAUDE.md, AGENTS.md, and .claude/rules/ instruction files for contradictions, stale references, dead rules, and scope collisions. Runs a full audit in the foreground (with lock). Use when the user explicitly invokes /cartographer, or when they want immediate feedback after editing an instruction file. Supports --scope, --phase, --verbose, --status, and --force flags.
+---
+
+# Cartographer Skill
+
+Cartographer audits the persistent instruction layer of the current project and reports findings in the conversation. The automated SessionStart path handles periodic background audits; this skill is for on-demand use.
+
+## Setup
+
+```bash
+set -uo pipefail
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
+```
+
+Load config and resolve project context:
+
+```bash
+REPO_ROOT=$(cartographer_project_repo_root "$(pwd)")
+cartographer_config_load "$REPO_ROOT"
+
+if ! cartographer_config_enabled; then
+  echo "Cartographer is disabled. Set cartographer.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+
+PROJECT_KEY=$(cartographer_project_key "$(pwd)")
+CARTOGRAPHER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}/cartographer/$PROJECT_KEY"
+mkdir -p "$CARTOGRAPHER_DIR"
+```
+
+## Invocation Modes
+
+### `/cartographer` — full audit
+
+Runs all phases in the foreground. Acquires the audit lock (non-blocking).
+
+```bash
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+
+if ! cartographer_lock_acquire "$LOCK_FILE"; then
+  echo "An audit is already in progress."
+  echo "Run \`/cartographer --status\` to follow it, or \`/cartographer --force\` to restart."
+  exit 0
+fi
+
+export CARTOGRAPHER_DIR CARTOGRAPHER_TRIGGER="manual" ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
+bash "$PLUGIN_ROOT/scripts/run-audit.sh"
+cartographer_lock_release "$LOCK_FILE"
+```
+
+After the audit completes, read findings and render them to the conversation grouped by severity (see Rendering section).
+
+### `/cartographer --verbose` — all findings
+
+Shows ALL known findings (new + previously seen) from `$CARTOGRAPHER_DIR/findings/`. Does NOT re-emit bus events — renders to in-conversation output only.
+
+```bash
+echo "## Known Cartographer Findings"
+echo ""
+for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
+  [[ -f "$f" ]] || continue
+  jq -r '"**[\(.severity | ascii_upcase)]** \(.type) — \(.description)\n  Files: \(.file_a // "n/a") / \(.file_b // "n/a")\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null
+done
+```
+
+### `/cartographer --status` — audit status
+
+Reports the running state and last completion time. No LLM calls.
+
+```bash
+echo "## Cartographer Status"
+if cartographer_lock_is_held "$CARTOGRAPHER_DIR/audit.lock"; then
+  pid=$(cat "$CARTOGRAPHER_DIR/audit.lock" 2>/dev/null)
+  echo "Audit running (PID $pid)"
+else
+  echo "No audit in progress"
+fi
+
+if [[ -f "$CARTOGRAPHER_DIR/last_audit_at" ]]; then
+  ts=$(cat "$CARTOGRAPHER_DIR/last_audit_at")
+  echo "Last completed: $(date -r "$ts" 2>/dev/null || date -d "@$ts" 2>/dev/null || echo "$ts")"
+fi
+
+runs=$(ls "$CARTOGRAPHER_DIR/runs/" 2>/dev/null | wc -l | tr -d ' ')
+total=$(ls "$CARTOGRAPHER_DIR/findings/" 2>/dev/null | wc -l | tr -d ' ')
+echo "Total findings on disk: $total"
+echo "Audit runs recorded: $runs"
+```
+
+### `/cartographer --force` — force restart
+
+Kills the running audit (if any) and starts fresh.
+
+```bash
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+if cartographer_lock_is_held "$LOCK_FILE"; then
+  pid=$(cat "$LOCK_FILE" 2>/dev/null)
+  if [[ -n "$pid" ]]; then
+    kill "$pid" 2>/dev/null || true
+    sleep 1
+  fi
+  rm -f "$LOCK_FILE"
+fi
+# Then proceed as a normal full audit
+```
+
+### `/cartographer --phase=<phase>` — single phase
+
+Runs only one analysis phase: `contradiction`, `stale_ref`, `dead_rule`, or `scope_collision`.
+Pass `CARTOGRAPHER_PHASE_FILTER` to run-audit.sh (the script checks this env var and skips other phases).
+
+### `/cartographer --scope=<path>` — scoped audit
+
+Limits discovery to files under `<path>`. Set `CARTOGRAPHER_SCOPE_PATH` before running.
+
+## Rendering Findings
+
+After a manual audit completes, render findings grouped by severity:
+
+```bash
+echo "## Cartographer Findings"
+echo ""
+
+for severity in error warning informational; do
+  count=0
+  output=""
+  for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
+    [[ -f "$f" ]] || continue
+    fsev=$(jq -r '.severity // "warning"' "$f" 2>/dev/null)
+    [[ "$fsev" != "$severity" ]] && continue
+    (( count++ )) || true
+    output+=$(jq -r '"- **\(.type)**: \(.description)\n  `\(.file_a // "n/a")`\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null)
+    output+=$'\n'
+  done
+  if [[ "$count" -gt 0 ]]; then
+    echo "### ${severity^} ($count)"
+    printf '%s\n' "$output"
+  fi
+done
+```
+
+## Event Contract
+
+- `cartographer.issue.found` — emitted for NEW findings only (not in dedup store). Downstream consumers must deduplicate on `payload.finding_hash`.
+- `cartographer.audit.complete` — emitted when all phases complete (or partial with `status: "partial"`).
+- Manual `--verbose` renders known findings as in-conversation output only — no bus events.

package/release-please-config.json

@@ -62,6 +62,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/cartographer": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-bump-minor-pre-major": false,
+      "component": "cartographer",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"