@onlooker-community/ecosystem 0.10.0 → 0.15.0

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/plugins/echo/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "echo",
+  "version": "0.2.0",
+  "description": "Prompt-change regression detection. When a watched agent file is modified, Echo runs a single-judge quality pass via claude -p and compares the score against a stored baseline to report improved, degraded, or neutral. 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": [],
+  "agents": []
+}

package/plugins/echo/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/echo-v0.1.0...echo-v0.2.0) (2026-05-25)
+
+
+### Features
+
+* **echo:** add prompt regression detection plugin ([#32](https://github.com/onlooker-community/ecosystem/issues/32)) ([65274d4](https://github.com/onlooker-community/ecosystem/commit/65274d4d8326950d6c998ca292fed13b1b8c493b))
+
+## [Unreleased]
+
+### Added
+
+- Initial plugin scaffold: `echo-stop-gate.sh` Stop hook
+- Config schema (`config.json`) with `watch_paths`, `exclude_paths`, `drift_threshold`, and `evaluation` model settings
+- `echo-config.sh`: config loading with `.claude/settings.json` override support
+- `echo-events.sh`: canonical `echo.*` event emission via `onlooker-event.mjs`
+- `echo-project-key.sh`: stable project key and test_id derivation
+- `echo-ulid.sh`: ULID generator for suite and test identifiers
+- Recursion guard (`ECHO_NESTED=1`) preventing subprocess re-entry
+- Baseline storage under `~/.onlooker/echo/<project-key>/baselines/`
+- Emits `echo.suite.started`, `echo.improvement.detected`, `echo.regression.detected`, `echo.suite.complete` against schema v2.2.0
+- `merge_recommended` derived from absence of regressions
+- `drift`, `baseline_score`, `score_after`, `drift_threshold` populated on `echo.suite.complete` when a prior baseline exists

package/plugins/echo/README.md

@@ -0,0 +1,110 @@
+# Echo
+
+Prompt-change regression detection for the Onlooker ecosystem.
+
+When a watched agent file is modified, Echo runs a single-judge quality pass on the file via `claude -p` and compares the score against a stored baseline. It reports whether the change **improved**, **degraded**, or had **no measurable effect** on prompt quality — giving every prompt edit a before/after signal instead of relying on intuition.
+
+Echo is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+Echo registers a **Stop hook** that fires at the end of every Claude Code session. When triggered:
+
+1. Detects which watched files changed (unstaged, staged, or untracked).
+2. Filters against configured `watch_paths` and `exclude_paths` patterns.
+3. For each matching file, builds a rubric prompt and calls `claude -p --max-turns 1` to score it on four criteria: role clarity, output format, criterion coverage, and internal consistency.
+4. Compares the score to a stored baseline (if one exists) and emits `echo.improvement.detected` or `echo.regression.detected`.
+5. Emits `echo.suite.complete` with aggregate drift, a `merge_recommended` flag, and duration.
+
+The hook always exits 0 — it never blocks a session from ending.
+
+## Activation
+
+Echo is **off by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "echo": {
+    "enabled": true
+  }
+}
+```
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "echo": {
+    "enabled": true,
+    "watch_paths": ["plugins/*/agents/*.md"],
+    "exclude_paths": [],
+    "drift_threshold": 0.05,
+    "evaluation": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout_seconds": 60
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any evaluation to run. |
+| `watch_paths` | `["plugins/*/agents/*.md"]` | Glob patterns (relative to repo root) of files to watch. Bash extended glob syntax. |
+| `exclude_paths` | `[]` | Patterns to exclude. `plugins/echo/**` is always excluded regardless of this setting. |
+| `drift_threshold` | `0.05` | Minimum absolute score delta to classify a change as improvement or regression. Deltas below this are reported as neutral. |
+| `evaluation.model` | `claude-haiku-4-5-20251001` | Model used for the quality pass. Haiku is fast and cheap; upgrade to Sonnet for higher-stakes repos. |
+| `evaluation.timeout_seconds` | `60` | Per-file wall-clock timeout passed to the `timeout` command. |
+
+## Scoring rubric
+
+Each watched file is scored 0.0–1.0 on four equally-weighted criteria:
+
+| Criterion | What it checks |
+|-----------|---------------|
+| **Role clarity** | Does the file clearly define what the agent is and what it must do? |
+| **Output format** | Are output format and schema requirements unambiguous? |
+| **Criterion coverage** | Are all evaluation dimensions specified with enough detail to apply consistently? |
+| **Internal consistency** | No contradictory instructions; no undefined terms. |
+
+A score ≥ 0.7 is considered "passed". A delta beyond `drift_threshold` in either direction is classified as improvement or regression.
+
+## Storage layout
+
+```text
+~/.onlooker/echo/<project-key>/
+├── baselines/
+│   └── <test-id>.json          # one per watched file (test-id = first 16 hex of SHA256 of path)
+└── run-<session-id>.json       # advisory summary written at end of each suite
+```
+
+Project key: first 12 hex chars of SHA256 of `git remote get-url origin`, falling back to a hash of the repo root realpath. This makes the key stable across directory moves and clones of the same repo.
+
+## Events emitted
+
+Echo emits the canonical `echo.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema) v2.2.0+. All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When |
+|-------|------|
+| `echo.suite.started` | Before the evaluation loop begins. Includes `test_count` and `changed_file`. |
+| `echo.improvement.detected` | A file's score increased beyond `drift_threshold`. |
+| `echo.regression.detected` | A file's score decreased beyond `drift_threshold`. |
+| `echo.suite.complete` | After all files are evaluated. Includes aggregate drift fields when a prior baseline exists. |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- `claude` CLI on `PATH` (the hook shells out to `claude -p` for evaluation passes).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `python3` for millisecond timestamps (standard on macOS and most Linux distributions).
+
+## Architecture decisions
+
+Key decisions made during initial design are recorded in [`docs/adr/`](docs/adr/):
+
+- [ADR-001](docs/adr/001-echo-as-separate-plugin.md) — Echo as a separate plugin, not an extension of Tribunal
+- [ADR-002](docs/adr/002-direct-evaluation-vs-tribunal-pipeline.md) — Direct `claude -p` evaluation vs. routing through Tribunal's full pipeline
+- [ADR-003](docs/adr/003-stop-hook-trigger.md) — Stop hook as the trigger mechanism

package/plugins/echo/config.json

@@ -0,0 +1,15 @@
+{
+  "plugin_name": "echo",
+  "storage_path": "~/.onlooker",
+  "echo": {
+    "enabled": false,
+    "watch_paths": ["plugins/*/agents/*.md"],
+    "exclude_paths": [],
+    "drift_threshold": 0.05,
+    "evaluation": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 512,
+      "timeout_seconds": 60
+    }
+  }
+}

package/plugins/echo/docs/adr/001-echo-as-separate-plugin.md

@@ -0,0 +1,33 @@
+# ADR-001: Echo as a Separate Plugin, Not an Extension of Tribunal
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Tribunal already exists as an evaluation engine in this ecosystem. When designing Echo's prompt-change regression detection, the first question was whether Echo should live inside Tribunal (as a sub-feature or mode) or stand alone as its own plugin.
+
+The Tribunal team ran a formal evaluation of this question using Tribunal itself. The final score across three iterations was 0.79 (above the 0.75 acceptance threshold), with outcome `exhausted_iterations` — the adversarial judge never passed, which is expected behavior for that judge type. The substantive conclusion from all three iterations was: Echo is architecturally sound as a standalone plugin.
+
+## Decision
+
+Echo is a separate, independent plugin under `plugins/echo/`.
+
+## Rationale
+
+**Separate concerns.** Tribunal is an orchestrator for arbitrary tasks. Echo is a specialized harness for prompt quality regression testing. Bundling Echo into Tribunal would couple two distinct concerns: general task evaluation and change-detection/baselining.
+
+**Different lifecycle.** Tribunal is always on (for `/tribunal` skill invocations) and opt-in for its Stop hook. Echo is opt-in by default (`"enabled": false`) and has no interactive skill surface — it only runs as a Stop hook. These are different activation patterns that would conflict if forced into the same plugin config namespace.
+
+**Independent versioning.** Echo and Tribunal can release, iterate, and break/fix independently. Echo v0.2 does not need to drag along a Tribunal major bump.
+
+**Composability.** Echo today calls `claude -p` directly. A future version could delegate to Tribunal for richer multi-judge evaluation (see ADR-002). That migration is easier when Echo is its own entry point.
+
+**Self-exclusion.** Echo must never trigger on its own files changing. This is simpler to enforce as a first-class concern in a standalone plugin (`plugins/echo/**` is always in `exclude_paths`) than as a special case inside Tribunal.
+
+## Consequences
+
+- Echo requires the ecosystem plugin but does **not** require Tribunal to be installed.
+- Echo gets its own `config.json`, `hooks.json`, `.claude-plugin/plugin.json`, CHANGELOG, and release-please track.
+- Any future Tribunal integration (e.g., Echo delegating multi-judge eval to Tribunal) will be an opt-in config option, not a hard dependency.
+- Marketplace listing and docs must be careful not to imply Tribunal is a prerequisite (an early draft of the description made this mistake; corrected before merge).