@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/cartographer/README.md

@@ -0,0 +1,113 @@
+# Cartographer
+
+Proactive, periodic auditor of the persistent instruction layer shaping every Claude Code session.
+
+Cartographer discovers all `CLAUDE.md`, `AGENTS.md`, and `.claude/rules/` files in your project, builds a semantic map of their relationships, and surfaces contradictions, stale references, dead rules, and scope collisions — before they cause expensive agent misbehavior.
+
+Every other Onlooker plugin is reactive. Cartographer is the exception.
+
+## What it detects
+
+| Finding type | Description |
+|---|---|
+| `contradiction` | Two rules that cannot both be satisfied simultaneously |
+| `dead_rule` | A rule fully subsumed by a more specific rule elsewhere |
+| `stale_ref` | A reference to a file path, tool, or command that no longer exists |
+| `scope_collision` | A project rule that duplicates or silently overrides a global `~/.claude/CLAUDE.md` rule |
+
+## Installation
+
+Cartographer is part of the Onlooker ecosystem monorepo. It requires the ecosystem plugin to be installed first.
+
+## Activation
+
+Cartographer is **disabled by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "cartographer": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json` to audit all projects.
+
+## Usage
+
+### Automatic (SessionStart)
+
+Once enabled, Cartographer audits automatically every 24 hours (configurable). The audit runs as a detached background process — your session is not blocked.
+
+Findings appear in the next `/cartographer` invocation or in any event log consumer subscribed to `cartographer.issue.found`.
+
+### On-demand
+
+```
+/cartographer              # full audit, foreground
+/cartographer --verbose    # show all known findings (no bus events)
+/cartographer --status     # running state + last completion time
+/cartographer --force      # kill running audit and restart
+/cartographer --phase=contradiction   # single-phase audit
+/cartographer --scope=src/            # scoped to a subdirectory
+```
+
+## Configuration
+
+All options are optional. Defaults shown:
+
+```json
+{
+  "cartographer": {
+    "enabled": false,
+    "audit_interval_hours": 24,
+    "phase_timeout_seconds": 60,
+    "total_timeout_seconds": 600,
+    "extraction": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 2048
+    },
+    "synthesis": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 2048
+    },
+    "exclude_paths": [
+      "node_modules", ".git", "vendor", ".venv",
+      "dist", ".next", ".nuxt", "build", "__pycache__"
+    ]
+  }
+}
+```
+
+**Note:** Overriding `exclude_paths` replaces the entire list. Repeat the defaults plus your additions if you want to extend rather than replace.
+
+## Privacy
+
+- All analysis uses `claude -p` via your existing Claude Code session — no separate API key, no new data recipient.
+- Findings are stored only in `~/.onlooker/cartographer/<project-key>/` on your local machine.
+- The event log (`~/.onlooker/logs/onlooker-events.jsonl`) contains finding excerpts (capped in the payload) but never full file contents.
+
+## Storage
+
+```
+~/.onlooker/cartographer/<project-key>/
+├── last_audit_at          # unix epoch of last completed audit
+├── audit.lock             # flock target or PID file
+├── audit.log              # background audit stdout/stderr
+├── extracts/              # per-file content hash cache
+├── findings/              # one JSON file per unique finding (atomic writes)
+└── dedup/                 # empty sentinel per emitted finding hash
+```
+
+## Event delivery
+
+`cartographer.issue.found` events are delivered at-least-once. If the audit process crashes between emitting an event and writing the dedup sentinel, the finding is re-emitted once on the next run. Downstream consumers must deduplicate on `payload.finding_hash`.
+
+## Non-goals
+
+Cartographer will not:
+- Modify any instruction file
+- Block Write or Edit tool calls
+- Enforce rule priority or style
+- Operate across machines (findings are local)
+- Replace human review of instruction files

package/plugins/cartographer/config.json

@@ -0,0 +1,21 @@
+{
+  "plugin_name": "cartographer",
+  "storage_path": "~/.onlooker",
+  "cartographer": {
+    "enabled": false,
+    "audit_interval_hours": 24,
+    "phase_timeout_seconds": 60,
+    "total_timeout_seconds": 600,
+    "extraction": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 2048,
+      "chunk_size_files": 10,
+      "chunk_overlap_pct": 10
+    },
+    "synthesis": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 2048
+    },
+    "exclude_paths": ["node_modules", ".git", "vendor", ".venv", "dist", ".next", ".nuxt", "build", "__pycache__"]
+  }
+}

package/plugins/cartographer/docs/adr/001-background-audit-launch.md

@@ -0,0 +1,28 @@
+# ADR-001: Background Audit Launch via nohup+setsid
+
+**Status:** Accepted
+
+## Context
+
+Claude Code SessionStart hooks run synchronously and block session readiness until they exit. The Cartographer audit pipeline makes multiple `claude -p` calls and can take 1–10 minutes on large repos. Blocking the session for that duration is unacceptable.
+
+## Decision
+
+The SessionStart hook (`cartographer-session-start.sh`) performs only three fast operations before returning:
+1. Read `last_audit_at` from a single JSON field.
+2. Acquire a non-blocking lock (`flock -n` or PID-file fallback).
+3. Launch `run-audit.sh` via `nohup setsid ... &`, then write the child PID and exit.
+
+`nohup` prevents SIGHUP from reaching the child when the hook's process group is reaped. `setsid` creates a new session so the child is not in the hook's process group at all. Together they ensure the audit survives the hook exit.
+
+## Consequences
+
+- The hook returns in under 2 seconds regardless of repo size.
+- Audit progress is visible only in `~/.onlooker/cartographer/<key>/audit.log`.
+- The user has no immediate signal that an audit started; findings surface at the next `/cartographer` invocation or via event log consumers.
+
+## Alternatives Considered
+
+- **Synchronous with short timeout:** Limits audit depth; users would see partial results inconsistently.
+- **Cron/launchd/systemd timer:** Requires out-of-process scheduler setup; breaks the "install the plugin, no other config required" contract.
+- **PreCompact hook (like Archivist):** Archivist uses PreCompact because compaction is a natural checkpoint. Cartographer is file-change driven, not conversation-length driven — SessionStart is the better trigger.

package/plugins/cartographer/docs/adr/002-flock-pid-file-fallback.md

@@ -0,0 +1,30 @@
+# ADR-002: flock with PID-File Fallback for Cross-Session Locking
+
+**Status:** Accepted
+
+## Context
+
+Multiple Claude Code sessions can open in the same project directory simultaneously (multiple terminal windows, split panes, worktrees pointing to the same project key). Without coordination, concurrent sessions can each decide an audit is due and spawn competing `claude -p` subprocesses that race on `findings/<hash>.json` writes and `last_audit_at`.
+
+## Decision
+
+`cartographer-lock.sh` implements a two-tier lock:
+
+1. **`flock --nonblock`** on `audit.lock` — kernel-level, atomic, preferred. Available on Linux without extra tooling.
+2. **PID-file fallback** — reads PID from `audit.lock`, checks with `kill -0`. Used on macOS where `flock` requires `brew install flock` (coreutils) and may not be present.
+
+Both tiers use non-blocking acquisition: the second session exits cleanly rather than queuing. The `/cartographer --force` flag kills the existing audit PID before acquiring the lock for manual override.
+
+**Known limitation:** The PID-file fallback has a TOCTOU window between `kill -0` and writing the new PID. On single-machine developer workstations this is an acceptable risk; we are protecting against simultaneous sessions, not adversarial concurrent writes. This is documented in CLAUDE.md.
+
+## Consequences
+
+- Most Linux users get atomic kernel-level locking.
+- macOS users without coreutils get a best-effort fallback with documented limitations.
+- No mandatory external dependency beyond a standard shell.
+
+## Alternatives Considered
+
+- **Require `flock` as a mise dep:** Adds a dependency users must install; breaks the zero-config install story.
+- **Use a socket/lockfile via `mkdir` (atomic on POSIX):** `mkdir` creates atomically; the lock is the directory existence. More portable than PID files but does not provide stale-lock recovery.
+- **Accept duplicate concurrent audits:** Duplicate findings are eventually deduplicated by hash; correctness is preserved but wastes resources.

package/plugins/cartographer/docs/adr/003-at-least-once-event-delivery.md

@@ -0,0 +1,32 @@
+# ADR-003: At-Least-Once Event Delivery with finding_hash Deduplication
+
+**Status:** Accepted
+
+## Context
+
+Cartographer emits `cartographer.issue.found` events for new findings, then writes a sentinel file to `dedup/<hash>` to mark them as known. If the process crashes between the event emission and the sentinel write, the same finding is re-emitted on the next audit run.
+
+We must choose between:
+- **Exactly-once:** write sentinel first, then emit event. If the process crashes after writing the sentinel but before emitting, the event is permanently lost.
+- **At-least-once:** emit event first, then write sentinel. If the process crashes between, the event is re-emitted once on the next run.
+
+## Decision
+
+Use **at-least-once delivery**. Findings carry a `finding_hash` in their event payload. Downstream consumers (event log aggregators, Linear integrations, dashboards) must deduplicate on `payload.finding_hash` in their own stores.
+
+**Rationale:** A missed finding (exactly-once failure) silently suppresses a real issue. A duplicate finding (at-least-once failure) is visible and correctable. For an advisory tool, false negatives are worse than false positives.
+
+**At-most-once per process run** is still guaranteed: within a single `run-audit.sh` invocation, the dedup sentinel is checked before emitting, so the same finding is emitted at most once per run.
+
+The delivery contract is documented in SKILL.md and the plugin CLAUDE.md.
+
+## Consequences
+
+- Downstream consumers must implement `finding_hash`-keyed deduplication.
+- A crash during `run_emit` will re-emit at most N findings on the next run (where N is the number of new findings after the crash point).
+- The behavior is deterministic: re-emissions carry the same `finding_hash` as the original, so dedup is always possible.
+
+## Alternatives Considered
+
+- **Write-then-emit (exactly-once attempt):** Simpler logic, but loses findings on crash. Unacceptable for an advisory auditor.
+- **Two-phase commit (journal):** Write an intent log, emit, mark complete. Correct but complex for a shell script; deferred to v0.2 if needed.

package/plugins/cartographer/docs/adr/004-exclude-paths-replace-semantics.md

@@ -0,0 +1,27 @@
+# ADR-004: exclude_paths Uses Replace Semantics
+
+**Status:** Accepted
+
+## Context
+
+The `exclude_paths` config key lists directory name substrings that `find` should skip. Users may want to customize this list — adding project-specific directories like `fixtures/` or `testdata/`. Two approaches:
+
+1. **Replace semantics:** Overriding `exclude_paths` replaces the entire list. Users who want to extend must repeat the defaults plus their additions.
+2. **Append semantics via `exclude_paths_extra`:** A separate key for user additions; the defaults are always present.
+
+## Decision
+
+Use **replace semantics** for v0.1. The default list (`node_modules`, `.git`, `vendor`, `.venv`, `dist`, `.next`, `.nuxt`, `build`, `__pycache__`) is shipped in `config.json`. When a user overrides `exclude_paths` in `.claude/settings.json`, they replace the entire list.
+
+**Rationale:** The layered config merge (`jq * merge`) already uses replace semantics for arrays — this is consistent with how other plugin config arrays work (e.g., tribunal's `judge_types`). Introducing a separate `exclude_paths_extra` key adds surface area without clear demand in v0.1.
+
+**Documented limitation:** Users who override `exclude_paths` and forget to include `node_modules` or `.git` will audit those directories. This is documented in the configuration reference.
+
+## Consequences
+
+- Config behavior is consistent with other plugin array keys.
+- Users who want to extend must copy-paste the defaults plus their additions. This is mildly annoying but rare.
+
+## Future Option
+
+If users consistently request append behavior, `exclude_paths_extra` (a supplementary array that merges with the defaults) can be added in v0.2 without breaking existing configs.

package/plugins/cartographer/hooks/hooks.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/cartographer-session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/cartographer-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/cartographer-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/cartographer-post-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/cartographer/scripts/hooks/cartographer-post-write.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# cartographer-post-write.sh — PostToolUse hook for Write / Edit / MultiEdit.
+#
+# Triggers a targeted single-file re-audit when a CLAUDE.md file is modified.
+# Uses exact basename matching — editor swap files are excluded by definition.
+# Always exits 0 (never blocks the tool call).
+
+set -uo pipefail
+
+# Recursion guard — prevents a claude -p subprocess spawned by run-audit.sh
+# from re-triggering this hook.
+[[ "${CARTOGRAPHER_NESTED:-0}" == "1" ]] && exit 0
+export CARTOGRAPHER_NESTED=1
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+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"
+
+HOOK_INPUT=$(cat)
+CWD=$(printf '%s' "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+_HOOK_SESSION_ID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+export _HOOK_SESSION_ID
+
+[[ -z "$CWD" ]] && exit 0
+
+# Extract the written file path from tool input
+TOOL_TARGET=$(printf '%s' "$HOOK_INPUT" \
+	| jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+[[ -z "$TOOL_TARGET" ]] && exit 0
+
+# Canonicalize the path (resolve symlinks where possible)
+if command -v realpath &>/dev/null; then
+	CANONICAL=$(realpath "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+elif command -v readlink &>/dev/null; then
+	CANONICAL=$(readlink -f "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+else
+	CANONICAL="$TOOL_TARGET"
+fi
+
+# Exact basename match — swap files (.swp, ~, .#) are excluded by this check
+TARGET_BASENAME=$(basename "$CANONICAL")
+[[ "$TARGET_BASENAME" != "CLAUDE.md" ]] && exit 0
+
+REPO_ROOT=$(cartographer_project_repo_root "$CWD")
+cartographer_config_load "$REPO_ROOT"
+
+cartographer_config_enabled || exit 0
+
+PROJECT_KEY=$(cartographer_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
+CARTOGRAPHER_DIR="$ONLOOKER_DIR/cartographer/$PROJECT_KEY"
+mkdir -p "$CARTOGRAPHER_DIR"
+
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+
+# Non-blocking lock — if a full scheduled audit is running, skip.
+# portable-lock.sh uses atomic mkdir so no fd lifetime concerns.
+cartographer_lock_acquire "$LOCK_FILE" || exit 0
+
+export CARTOGRAPHER_DIR
+export CARTOGRAPHER_TRIGGER="post_tool_use"
+export CARTOGRAPHER_TARGET_FILE="$CANONICAL"
+export CARTOGRAPHER_REPO_ROOT="$REPO_ROOT"
+export ONLOOKER_DIR
+
+if command -v setsid &>/dev/null; then
+	nohup setsid bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+else
+	nohup bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+fi
+
+exit 0

package/plugins/cartographer/scripts/hooks/cartographer-session-start.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# cartographer-session-start.sh — SessionStart hook.
+#
+# Fast path: reads one JSON field, acquires a lock, and launches the audit
+# pipeline as a detached background process. Returns in under 2 seconds.
+#
+# Invariant: this script NEVER calls claude -p or traverses the filesystem.
+# All heavy work runs in run-audit.sh as an orphaned child.
+
+set -uo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+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"
+
+# Parse hook input
+HOOK_INPUT=$(cat)
+CWD=$(printf '%s' "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+_HOOK_SESSION_ID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+export _HOOK_SESSION_ID
+
+[[ -z "$CWD" ]] && exit 0
+
+REPO_ROOT=$(cartographer_project_repo_root "$CWD")
+cartographer_config_load "$REPO_ROOT"
+
+cartographer_config_enabled || exit 0
+
+PROJECT_KEY=$(cartographer_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
+CARTOGRAPHER_DIR="$ONLOOKER_DIR/cartographer/$PROJECT_KEY"
+mkdir -p "$CARTOGRAPHER_DIR"
+
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+STATE_FILE="$CARTOGRAPHER_DIR/last_audit_at"
+
+# Determine if an audit is due
+INTERVAL_HOURS=$(cartographer_config_audit_interval_hours)
+FIRST_RUN_TRIGGER="session_start_first_run"
+INTERVAL_TRIGGER="session_start_interval"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+	TRIGGER="$FIRST_RUN_TRIGGER"
+elif [[ -f "$STATE_FILE" ]]; then
+	LAST=$(cat "$STATE_FILE" 2>/dev/null || printf '0')
+	NOW=$(date +%s)
+	ELAPSED=$(( NOW - LAST ))
+	THRESHOLD=$(( INTERVAL_HOURS * 3600 ))
+	if [[ "$ELAPSED" -lt "$THRESHOLD" ]]; then
+		exit 0
+	fi
+	TRIGGER="$INTERVAL_TRIGGER"
+fi
+
+# Acquire lock non-blocking — skip if another session's audit is running.
+# portable-lock.sh uses atomic mkdir so no fd lifetime concerns.
+cartographer_lock_acquire "$LOCK_FILE" || exit 0
+
+# Launch the audit detached — hook must return immediately.
+# setsid detaches from the controlling terminal so SIGHUP on session close
+# does not kill the background audit (ADR-001). Falls back to nohup-only on
+# macOS where setsid requires coreutils.
+export CARTOGRAPHER_DIR
+export CARTOGRAPHER_TRIGGER="$TRIGGER"
+export CARTOGRAPHER_REPO_ROOT="$REPO_ROOT"
+export ONLOOKER_DIR
+
+if command -v setsid &>/dev/null; then
+	nohup setsid bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+else
+	nohup bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+fi
+
+exit 0