@onlooker-community/ecosystem 0.14.0 → 0.15.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Observability substrate for Claude Code. Provides the shared ~/.onlooker/ storage root, canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
   "author": {
     "name": "Onlooker Community",

package/.github/workflows/release.yml

@@ -33,19 +33,23 @@ jobs:
       # Code marketplace, not npm — a release for a sibling alone must not
       # trigger `npm publish`, which would attempt to re-publish ecosystem at
       # its existing version and fail.
+      #
+      # We check paths_released (a JSON array) rather than the per-path output
+      # key `.--release_created` because keys starting with `.` are silently
+      # dropped when release-please-action writes them to $GITHUB_OUTPUT.
       - uses: actions/checkout@v4
-        if: ${{ steps.release.outputs['.--release_created'] }}
+        if: ${{ contains(fromJSON(steps.release.outputs.paths_released || '[]'), '.') }}
 
       - uses: actions/setup-node@v4
-        if: ${{ steps.release.outputs['.--release_created'] }}
+        if: ${{ contains(fromJSON(steps.release.outputs.paths_released || '[]'), '.') }}
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - run: npm ci
-        if: ${{ steps.release.outputs['.--release_created'] }}
+        if: ${{ contains(fromJSON(steps.release.outputs.paths_released || '[]'), '.') }}
 
       - run: npm publish
-        if: ${{ steps.release.outputs['.--release_created'] }}
+        if: ${{ contains(fromJSON(steps.release.outputs.paths_released || '[]'), '.') }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.release-please-manifest.json

@@ -1,6 +1,7 @@
 {
-  ".": "0.14.0",
+  ".": "0.15.1",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.0",
-  "plugins/echo": "0.2.0"
+  "plugins/echo": "0.2.0",
+  "plugins/cartographer": "0.2.0"
 }

package/CHANGELOG.md

@@ -7,6 +7,20 @@
 
 # Changelog
 
+## [0.15.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.15.0...ecosystem-v0.15.1) (2026-05-25)
+
+
+### Bug Fixes
+
+* **ci:** use paths_released to gate npm publish :rage: ([#37](https://github.com/onlooker-community/ecosystem/issues/37)) ([c62b17f](https://github.com/onlooker-community/ecosystem/commit/c62b17f7e1352cfe260a23c8f48be30f72edbbed))
+
+## [0.15.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.14.0...ecosystem-v0.15.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.14.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.13.0...ecosystem-v0.14.0) (2026-05-25)
 
 

package/README.md

@@ -16,6 +16,7 @@ The ecosystem is a **Claude Code plugin marketplace** built around a shared obse
 | [`archivist`](./plugins/archivist) | Structured session memory across context truncation. Extracts decisions, dead ends, and open questions; reinjects the most relevant items at the start of the next session. | Yes — disabled by default |
 | [`tribunal`](./plugins/tribunal) | Multi-agent quality gates. Wraps a task in an Actor → Jury → Meta-Judge → Gate loop; retries the Actor with critique until the gate passes or `max_iterations` is reached. | Yes — skill always available; Stop hook opt-in |
 | [`echo`](./plugins/echo) | Prompt-change regression detection. When a watched agent file is modified, runs a quality pass and reports whether the change improved, degraded, or had no measurable effect. | Yes — disabled by default |
+| [`cartographer`](./plugins/cartographer) | Proactive instruction-file auditor. Discovers all `CLAUDE.md`, `AGENTS.md`, and `.claude/rules/` files, maps their relationships, and surfaces contradictions, dead rules, stale references, and scope collisions before they cause agent misbehavior. | Yes — disabled by default |
 
 For how these fit together, see [docs/architecture.md](docs/architecture.md).
 

package/docs/architecture.md

@@ -4,28 +4,27 @@ This document describes how the Onlooker ecosystem fits together: the shared sub
 
 ## Overview
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Claude Code session                                            │
-│                                                                 │
-│  ┌─────────────┐  ┌───────────┐  ┌──────────┐  ┌──────────┐  │
-│  │  ecosystem  │  │ archivist │  │ tribunal │  │   echo   │  │
-│  │  (substrate)│  │  plugin   │  │  plugin  │  │  plugin  │  │
-│  └──────┬──────┘  └─────┬─────┘  └────┬─────┘  └────┬─────┘  │
-│         │               │             │              │         │
-│         └───────────────┴─────────────┴──────────────┘         │
-│                               │                                 │
-│                    ┌──────────▼──────────┐                     │
-│                    │  onlooker-event.mjs  │  schema-validated   │
-│                    │  (canonical emitter) │  event envelope     │
-│                    └──────────┬──────────┘                     │
-│                               │                                 │
-│                    ┌──────────▼──────────┐                     │
-│                    │  ~/.onlooker/logs/  │                     │
-│                    │  onlooker-events    │  append-only JSONL   │
-│                    │  .jsonl             │                     │
-│                    └─────────────────────┘                     │
-└─────────────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+    subgraph session["Claude Code session"]
+        ecosystem["ecosystem<br/>(substrate)"]
+        archivist["archivist<br/>plugin"]
+        tribunal["tribunal<br/>plugin"]
+        echo["echo<br/>plugin"]
+        cartographer["cartographer<br/>plugin"]
+
+        emitter["onlooker-event.mjs<br/>(canonical emitter)"]
+        log["~/.onlooker/logs/<br/>onlooker-events.jsonl"]
+
+        ecosystem --> emitter
+        archivist --> emitter
+        tribunal --> emitter
+        echo --> emitter
+        cartographer --> emitter
+
+        emitter -->|"schema-validated<br/>event envelope"| log
+        log -.->|"append-only JSONL"| log
+    end
 ```
 
 ## The substrate layer: `ecosystem`
@@ -51,11 +50,18 @@ Plugins are independent packages under `plugins/<name>/`. Each has its own:
 
 Plugins communicate by **emitting events**, not by calling each other directly. An Echo evaluation and a Tribunal jury run both write to the same JSONL log; a dashboard or downstream consumer can query across both.
 
+### Cartographer
+
+[Cartographer](../plugins/cartographer) is the only proactive plugin in the ecosystem. Rather than reacting to tool calls or session events, it runs a periodic background audit of your entire persistent instruction layer (`CLAUDE.md`, `AGENTS.md`, `.claude/rules/`). It surfaces four finding types — `contradiction`, `dead_rule`, `stale_ref`, and `scope_collision` — and emits each as a `cartographer.issue.found` event before the misbehavior they would cause ever occurs.
+
+Findings are stored in `~/.onlooker/cartographer/<project-key>/findings/` and delivered at-least-once (deduplicated on `payload.finding_hash`). The audit runs as a detached background process; your session is never blocked.
+
 ### Plugin dependency model
 
 All plugins depend on `ecosystem`. No plugin depends on another plugin at runtime. This means:
 - Tribunal does not require Archivist to be installed.
 - Echo does not require Tribunal to be installed (despite evaluating similar things — see [Echo ADR-002](../plugins/echo/docs/adr/002-direct-evaluation-vs-tribunal-pipeline.md)).
+- Cartographer does not require any other plugin — it reads instruction files directly and emits events independently.
 - You can install any subset of plugins and the others still work.
 
 ## The event bus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",

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`

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