@onlooker-community/ecosystem 0.10.0 → 0.14.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,6 @@
       "name": "ecosystem",
       "source": "./",
       "description": "Fill this out",
-      "version": "0.10.0",
       "author": {
         "name": "Onlooker Community"
       },
@@ -21,6 +20,45 @@
       "license": "MIT",
       "keywords": [],
       "tags": []
+    },
+    {
+      "name": "archivist",
+      "source": "./plugins/archivist",
+      "description": "Structured session memory across context truncation. Extracts decisions, dead ends, and open questions on PreCompact and reinjects the most important items at SessionStart. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["memory", "compaction", "context", "session"],
+      "tags": ["memory", "context-engineering"]
+    },
+    {
+      "name": "tribunal",
+      "source": "./plugins/tribunal",
+      "description": "Multi-agent execution with LLM-as-a-Judge quality gates. An Actor performs work; a jury of typed Judges scores it against a project-overridable rubric; a Meta-Judge reviews the jury for bias; the gate decides accept, retry, or exhaust. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["agents", "evaluation", "quality-gates", "multi-agent", "llm-judge"],
+      "tags": ["agents", "evaluation"]
+    },
+    {
+      "name": "echo",
+      "source": "./plugins/echo",
+      "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. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["evaluation", "regression", "prompt-engineering", "testing", "quality"],
+      "tags": ["evaluation", "testing"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ecosystem",
-  "version": "0.10.0",
-  "description": "TODO fill this out",
+  "version": "0.14.0",
+  "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",
     "url": "https://onlooker.dev"

package/.github/copilot-instructions.md

@@ -0,0 +1,46 @@
+# Copilot review guidance for the Onlooker ecosystem
+
+This file shapes Copilot's review comments and chat suggestions. Keep it tight and prescriptive — Copilot weights every line.
+
+## Repository shape
+
+This is a Claude Code plugin marketplace, not a typical npm package. The default plugin (`ecosystem`) lives at the repo root and provides the observability substrate; sibling plugins live under `plugins/<name>/` and assume `~/.onlooker/` exists. Every sibling plugin has its own `.claude-plugin/plugin.json` and may have its own `hooks/hooks.json` and `scripts/`.
+
+When reviewing changes:
+
+* Treat `marketplace.json` and per-plugin `plugin.json` as governed by [Claude Code's plugin schema](https://code.claude.com/docs/en/plugins-reference). `version` belongs in `plugin.json` only — never in marketplace entries. Flag any PR that puts `version` on `marketplace.json plugins[]`.
+* `scripts/lint/check-manifests.mjs` and `scripts/lint/check-references.mjs` are the source of truth for what's "valid." If a PR seems to violate a manifest invariant, point at those linters.
+* Hooks must never block the host session. They exit 0 even on internal error, and they log failures to `~/.onlooker/logs/hook-health.jsonl` instead of throwing.
+
+## Locking, concurrency, portability
+
+* Cross-process file locking goes through `lock_acquire` / `lock_release` in `scripts/lib/portable-lock.sh`. **Do not introduce new `flock` calls** — mkdir-based mutex is the convention because the hooks run on macOS without util-linux.
+* Avoid bash 4+ features (associative arrays especially). macOS ships bash 3.2 by default and the hooks need to run there.
+* Hooks use `set -uo pipefail`, not `set -e`. Failing fast in a hook is worse than degrading gracefully.
+
+## Style + tooling
+
+* American English everywhere — commits, comments, identifiers, docs. (`color`, `behavior`, `normalize`, `analyze`.)
+* Conventional Commits with a mood emoji that reflects *this* change, not the type label. Don't mechanically pair `feat: :sparkles:` or `fix: :bug:`.
+* Lint stack: `biome` (JS), `shellcheck -S error -x` (bash), `markdownlint` (md). Add new shell files to the `test:shellcheck` script.
+* Tests live under `test/bats/` (shell) and `test/node/` (mjs, using `node:test`). Every new helper function deserves a bats test by name — `scripts/coverage/bash-coverage.mjs` measures this and surfaces it in the PR coverage comment.
+* No new runtime deps without a paragraph in the PR explaining why a stdlib-only solution doesn't fit. The validators are deliberately dependency-free.
+
+## Things that almost always indicate a bug
+
+* A hook that returns non-zero on its happy path.
+* A bash function definition not at column 0 (the coverage analyzer assumes top-level only).
+* A markdown skill/command/agent missing `name` and `description` frontmatter (the reference linter will fail).
+* A new plugin without an entry in `marketplace.json` (or with one carrying a `version` field).
+* `git config --global` calls in scripts or workflows (we never want to mutate the developer's signing/auth setup).
+* Writes to `~/.onlooker/` that don't honor `$ONLOOKER_DIR` overrides (breaks bats isolation).
+
+## Release flow
+
+`release-please` drives versioning. Each plugin's `plugin.json.version` is bumped from its own commit history; `marketplace.json` is *not* version-bumped. `release.yml` only publishes the root ecosystem package to npm — sibling plugins are distributed via the marketplace, not npm.
+
+## What to focus on in reviews
+
+In order of importance: correctness over elegance, smallest-possible-diff over architectural rewrites, evidence of testing (especially: did the PR add a bats test, a node test, or update fixtures?), and naming hygiene (kebab-case for plugin/command/skill names; snake_case for bash functions; camelCase for JS).
+
+When in doubt about a convention, say so explicitly rather than guessing.

package/.github/workflows/coverage.yml

@@ -0,0 +1,78 @@
+name: Coverage
+
+# Runs both coverage signals on every PR + push to main:
+#   - node --test --experimental-test-coverage for .mjs (real line/branch/funcs)
+#   - bash function-reference heuristic for scripts/lib/*.sh and plugins/*/scripts/lib/*.sh
+#
+# On pull requests, posts a single markdown comment that updates in place
+# (keyed by the `<!-- onlooker-coverage-comment -->` sentinel) so the PR
+# discussion isn't spammed with one comment per push.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mise
+        uses: jdx/mise-action@v2
+
+      - name: Install tools
+        run: mise install
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Run node coverage
+        run: node scripts/coverage/run-coverage.mjs --json > coverage-node.json
+
+      - name: Run bash function coverage
+        run: node scripts/coverage/bash-coverage.mjs --json > coverage-bash.json
+
+      - name: Render markdown comment
+        run: |
+          node scripts/coverage/format-comment.mjs \
+            --node coverage-node.json \
+            --bash coverage-bash.json \
+            --sha "$GITHUB_SHA" > coverage-comment.md
+          cat coverage-comment.md
+
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ github.run_id }}
+          path: |
+            coverage-node.json
+            coverage-bash.json
+            coverage-comment.md
+
+      - name: Upsert PR comment
+        if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          # Find any existing coverage comment by the sentinel, edit it if
+          # found, otherwise create a fresh one. Single comment per PR.
+          existing=$(gh pr view "$PR_NUMBER" --json comments \
+            --jq '.comments[] | select(.body | startswith("<!-- onlooker-coverage-comment -->")) | .url' \
+            | head -n1)
+          if [[ -n "$existing" ]]; then
+            comment_id="${existing##*#issuecomment-}"
+            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${comment_id}" \
+              -f body="$(cat coverage-comment.md)" >/dev/null
+            echo "Updated comment ${comment_id}"
+          else
+            gh pr comment "$PR_NUMBER" --body-file coverage-comment.md
+            echo "Posted new comment"
+          fi

package/.github/workflows/release.yml

@@ -12,24 +12,40 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
+      # Force release-please's intermediate PR-branch commits to be authored
+      # by github-actions[bot] instead of inheriting whatever identity the
+      # PAT owner happens to have configured on their local machine. The
+      # squash-merge of the release PR already attributes the merge to the
+      # PAT owner correctly, but the intermediate commits would otherwise
+      # leak the maintainer's hostname-shaped author email.
+      - name: Configure bot identity
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
       - uses: googleapis/release-please-action@v4
         id: release
         with:
           token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
-          
+
+      # Only publish to npm when the ecosystem (root) package was released.
+      # Archivist (and future sibling plugins) are distributed via the Claude
+      # 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.
       - uses: actions/checkout@v4
-        if: ${{ steps.release.outputs.release_created }}
-        
+        if: ${{ steps.release.outputs['.--release_created'] }}
+
       - uses: actions/setup-node@v4
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs['.--release_created'] }}
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
-          
+
       - run: npm ci
-        if: ${{ steps.release.outputs.release_created }}
-        
+        if: ${{ steps.release.outputs['.--release_created'] }}
+
       - run: npm publish
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs['.--release_created'] }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -6,6 +6,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test

package/.markdownlintignore

@@ -0,0 +1,3 @@
+node_modules/
+# release-please generated; regenerated on every release, not authored
+**/CHANGELOG.md

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -7,6 +7,43 @@
 
 # Changelog
 
+## [0.14.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.13.0...ecosystem-v0.14.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))
+
+## [0.13.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.12.0...ecosystem-v0.13.0) (2026-05-24)
+
+
+### Features
+
+* **tribunal:** add multi-agent code review plugin :sparkles: ([#30](https://github.com/onlooker-community/ecosystem/issues/30)) ([893f24a](https://github.com/onlooker-community/ecosystem/commit/893f24a8876fdd6ccb5c7dcf2636a7c902e88949))
+
+## [0.12.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.11.0...ecosystem-v0.12.0) (2026-05-23)
+
+
+### Features
+
+* **prompt-rules:** deterministic regex-triggered guidance injection :relieved: ([#28](https://github.com/onlooker-community/ecosystem/issues/28)) ([662c811](https://github.com/onlooker-community/ecosystem/commit/662c8119657cebc350900f859c43dbaca97d6703))
+
+## [0.11.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.10.0...ecosystem-v0.11.0) (2026-05-23)
+
+
+### Features
+
+* **archivist:** introduce structured session memory plugin :rocket: ([378fff3](https://github.com/onlooker-community/ecosystem/commit/378fff3c14b40644af45b1a2335992e7b0428160))
+* **coverage:** report node + bash coverage on every PR :sparkles: ([cb5d122](https://github.com/onlooker-community/ecosystem/commit/cb5d1221ad20e6257d66b507897dae14549a870f))
+* **lint:** add marketplace cross-reference linter :nail_care: ([0f48817](https://github.com/onlooker-community/ecosystem/commit/0f488170326659ef1d0b8bd7ae4d207c78a43694))
+* **lint:** add plugin manifest validator :nail_care: ([e12615f](https://github.com/onlooker-community/ecosystem/commit/e12615ff99d43caf59d5e215d882c0acb3352c01))
+
+
+### Bug Fixes
+
+* **hooks:** replace flock with portable mkdir mutex :bug: ([3dffa6f](https://github.com/onlooker-community/ecosystem/commit/3dffa6f5e43ef9f3c117f2406ddd03ce485df1cd))
+* **release:** sync marketplace.json out-of-band :relieved: ([0d2a0a3](https://github.com/onlooker-community/ecosystem/commit/0d2a0a38c0c4ee0e400b9a143a4be7904ea3f70a))
+
 ## [0.10.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.9.0...ecosystem-v0.10.0) (2026-05-22)
 
 

package/README.md

@@ -1,33 +1,77 @@
 # Onlooker Ecosystem
 
+[![Test](https://github.com/onlooker-community/ecosystem/actions/workflows/test.yml/badge.svg)](https://github.com/onlooker-community/ecosystem/actions/workflows/test.yml)
+
 Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev).
 
+The ecosystem is a **Claude Code plugin marketplace** built around a shared observability substrate. Every plugin writes to a common event log, derives stable project keys from your git remote, and stores artifacts under `~/.onlooker/` — so plugins compose without stepping on each other, and every event is queryable in one place.
+
+---
+
+## Plugins
+
+| Plugin | Description | Opt-in? |
+|--------|-------------|---------|
+| [`ecosystem`](./) | Observability substrate: session tracking, canonical events, prompt rules, tool history. Required by all other plugins. | No — always on |
+| [`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 |
+
+For how these fit together, see [docs/architecture.md](docs/architecture.md).
+
+---
+
+## Quick start
+
+```bash
+# Install the Onlooker CLI
+brew tap onlooker-community/tap
+brew install onlooker
+
+# Run the guided setup wizard
+onlooker setup
+```
+
 ---
 
 ## Development
 
-Install tools with [mise](https://mise.jdx.dev/) (`mise install`), then install dependencies (includes [`@onlooker-community/schema`](https://www.npmjs.com/package/@onlooker-community/schema) from npm):
+Install tools with [mise](https://mise.jdx.dev/) (`mise install`), then install dependencies:
 
 ```bash
 npm ci
-npm test              # bats + schema validation tests
+npm test                # bats + schema validation tests
 npm run test:shellcheck
-npm run test:ci       # shellcheck + bats + schema + lint
+npm run test:ci         # shellcheck + bats + schema + lint
 ```
 
-Hooks emit [canonical Onlooker events](https://github.com/onlooker-community/schema) via `scripts/lib/onlooker-event.mjs`. Bash helpers live in `scripts/lib/onlooker-schema.sh`.
+Hooks emit [canonical Onlooker events](https://github.com/onlooker-community/schema) via `scripts/lib/onlooker-event.mjs`. Bash helpers live in `scripts/lib/`.
 
-Tests live under `test/bats/` and `test/node/` and use an isolated temp home so nothing writes to your real `~/.onlooker`.
+Tests live under `test/bats/` and `test/node/` and use an isolated temp home so nothing writes to your real `~/.onlooker/`.
 
-## Quick Start
+---
 
-Get up and running in under 2 minutes:
+## Prompt rules
 
-```bash
-# Use homebrew to install Onlooker client
-brew tap onlooker-community/tap
-brew install onlooker
+The ecosystem plugin ships a `UserPromptSubmit` hook that injects declarative guidance when a user prompt matches a regex. Rules fire deterministically on literal prompt-text patterns, filling the niche that skills can't: guidance that must fire regardless of whether the model would have chosen a skill.
 
-# Use the wizard to be guided through setup
-onlooker setup
+Rules live in two files:
+
+- `~/.onlooker/prompt-rules.json` — global, applies across all projects
+- `<repo>/.claude/prompt-rules.json` — project-level, overrides global by `id`
+
+```json
+{
+  "rules": [
+    {
+      "id": "rule-no-verify-warning",
+      "pattern": "--no-verify",
+      "guidance": "Skipping hooks usually masks the real issue. Investigate the failure first.",
+      "fire_once_per_session": true,
+      "enabled": true
+    }
+  ]
+}
 ```
+
+`pattern` is POSIX ERE (`[[ =~ ]]` semantics). Run `/list-prompt-rules` to see active rules and per-session fire state.

package/config.json

@@ -1,4 +1,9 @@
 {
   "plugin_name": "onlooker",
-  "storage_path": "~/.onlooker"
+  "storage_path": "~/.onlooker",
+  "prompt_rules": {
+    "enabled": true,
+    "per_turn_max_chars": 1200,
+    "max_rules": 50
+  }
 }

package/docs/adr/001-claude-code-hooks-as-integration-surface.md

@@ -0,0 +1,43 @@
+# ADR-001: Claude Code Hooks as the Integration Surface
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Onlooker needs to observe what happens inside a Claude Code session — when sessions start and end, what tools are called, when context compacts, and when the model produces output. Several integration approaches were available:
+
+- **Claude Code hooks** — shell commands registered in `settings.json` that fire on lifecycle events (`SessionStart`, `Stop`, `PreCompact`, `PostToolUse`, `UserPromptSubmit`).
+- **MCP server** — a Model Context Protocol server that Claude Code connects to; the server receives tool calls and can inject context.
+- **Wrapper CLI** — a `claude` shim that intercepts invocations, records them, and delegates to the real binary.
+- **IDE extension** — a VS Code or JetBrains extension that observes editor events.
+
+## Decision
+
+The ecosystem uses **Claude Code hooks** as the primary integration surface.
+
+## Rationale
+
+**First-class support.** Hooks are a documented, stable feature of Claude Code. They receive structured JSON on stdin and can inject `additionalContext` via stdout. This is not a workaround — it's the intended extension mechanism.
+
+**No daemon required.** Hooks are short-lived shell processes. No persistent server, no port management, no process supervision. Each hook fires, does its work, and exits. This keeps the operational footprint near zero.
+
+**Composable and auditable.** Hook registrations live in `settings.json` alongside permissions and tool config. A developer can inspect exactly which hooks are registered, enable or disable them per-project, and trace any hook's behavior by reading its shell script.
+
+**Works across all Claude Code surfaces.** Hooks fire in the CLI, the desktop app, and IDE extensions. An MCP server or wrapper CLI would cover only the surfaces that honor those integrations.
+
+**Shell is universally available.** Hooks are shell commands. The Onlooker substrate (bash, jq, node) is the only runtime requirement. An MCP server would require a language runtime and a persistent process to be managed.
+
+## Why not MCP?
+
+MCP is the right surface for extending Claude's *tool use* — adding new capabilities the model can call. It is not a good fit for *observing* what the model does. MCP servers cannot easily intercept session lifecycle events (start, stop, compact), and the connection model assumes a persistent server. Hooks handle lifecycle events natively and are stateless by design.
+
+## Why not a wrapper CLI?
+
+A `claude` shim breaks when users install Claude Code via paths the shim does not intercept (desktop app, IDE extension). It also requires the shim to be on PATH before the real binary, which is fragile across environments. Hooks require no PATH manipulation.
+
+## Consequences
+
+- All ecosystem behavior is implemented in shell scripts sourced from `scripts/hooks/` and `scripts/lib/`. Shell has limitations (no associative arrays on bash 3.2, string-only data model), but the constraints are well-understood and the code is readable without a language-specific toolchain.
+- The hook event set is fixed by Claude Code. If an event that doesn't exist today is needed (e.g., a `PostCompact` or `ToolError` event), it cannot be added until Claude Code ships it.
+- Hooks run synchronously in some cases (`UserPromptSubmit`, `Stop`) and must be fast or the user experience degrades. Long-running evaluations (Tribunal, Echo) use `claude -p` subprocesses and must carry a recursion guard.

package/docs/adr/002-centralized-jsonl-event-log.md

@@ -0,0 +1,39 @@
+# ADR-002: Centralized JSONL Event Log with Schema Validation
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Every plugin produces structured signals — session timings, Tribunal verdicts, Echo drift scores, Archivist extraction events. These signals need to be stored somewhere. Options considered:
+
+- **Per-plugin flat files** — each plugin writes its own log in its own format.
+- **SQLite database** — a structured store under `~/.onlooker/`.
+- **Centralized JSONL log** — all plugins append to a single `~/.onlooker/logs/onlooker-events.jsonl` file, with a schema-validated envelope per event.
+- **Remote backend only** — events are sent directly to a cloud endpoint; nothing stored locally.
+
+## Decision
+
+All schema-defined events are written to a **centralized JSONL log** at `~/.onlooker/logs/onlooker-events.jsonl`, validated against [`@onlooker-community/schema`](https://github.com/onlooker-community/schema) before write. The log may also contain non-schema events from hooks that predate or have not yet been ported to the canonical pipeline (see Consequences).
+
+## Rationale
+
+**One place to query.** A single log means a dashboard, script, or downstream consumer can read everything without knowing which plugins are installed or where each one writes. Cross-plugin queries (e.g., "show Tribunal verdicts alongside the Echo drift scores for the same session") require no joins across separate stores.
+
+**JSONL is the simplest durable format.** One JSON object per line. Human-readable with `jq`. Appendable without locking (each `printf '%s\n'` is atomic on POSIX filesystems for lines under the page size). No schema migrations, no vacuum, no connection management.
+
+**Schema validation at write time prevents silent corruption.** Each event is validated before it is appended. If a plugin emits a malformed payload, the write fails loudly — the hook logs an error and the line is never added to the log. This means the log is always a valid, queryable dataset. Per-plugin flat files with ad-hoc formats would accumulate inconsistencies silently.
+
+**Versioned schema as a contract.** The schema is published as `@onlooker-community/schema` on npm and versioned independently. Plugins declare which schema version they target. When the schema adds new event types (e.g., the `echo.*` events added in v2.2.0), old plugins continue to work — they just don't emit the new types. Consumers can use the schema version field to handle evolution.
+
+**Local-first for privacy.** All data stays on the developer's machine by default. A future cloud-sync feature can read the JSONL and upload selectively; the log itself makes no network calls.
+
+## Why not SQLite?
+
+SQLite would give us structured queries, indexes, and transactions. The tradeoff is operational complexity: the file has a binary format (not inspectable with `cat`/`jq`), requires a SQLite binary, and has locking behavior that could deadlock if multiple hook processes fire concurrently. JSONL with append-only writes has no locking issue and is trivially inspectable.
+
+## Consequences
+
+- The log grows indefinitely. A future rotation/archival feature is needed for long-lived developer machines. Currently operators must prune manually.
+- The goal is that all event types are defined in `@onlooker-community/schema` before a plugin emits them. Adding a new event type requires a schema release — intentional friction that prevents undocumented shapes from accumulating. In practice, `prompt_rule.*` events are a current exception: they are emitted to the log by the prompt-rules hook but are not yet defined in the schema. This should be resolved in a future schema release.
+- Concurrent appends from multiple hooks (e.g., a `PostToolUse` hook and a `Stop` hook firing close together) are safe for lines under ~4 KB on POSIX, but multi-kilobyte payloads could interleave. In practice, event payloads are small and this has not been an issue.

package/docs/adr/003-ulid-over-uuid.md

@@ -0,0 +1,40 @@
+# ADR-003: ULID for All Identifiers
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Every artifact in the ecosystem — Archivist memories, Tribunal tasks and iterations, Echo suites and tests — needs a unique identifier. The identifier is used as a filename, a log correlation key, and a sort key. Options considered:
+
+- **UUID v4** — random, universally supported, 36 chars with hyphens.
+- **UUID v7** — time-ordered UUID, requires a library on older runtimes.
+- **ULID** — Universally Unique Lexicographically Sortable Identifier. 26 chars, Crockford Base32, time-ordered to millisecond precision.
+- **Timestamp + random suffix** — ad-hoc, human-readable but not globally unique.
+- **Sequential integer** — simple but requires a counter store and fails across processes.
+
+## Decision
+
+All ecosystem identifiers use **ULID**.
+
+## Rationale
+
+**Lexicographically sortable = chronologically sortable.** ULIDs sort correctly with `ls`, `sort`, and JSONL readers without parsing a timestamp field. Artifact directories and log entries naturally order by creation time. With UUID v4, sorting by filename requires a separate `created_at` index.
+
+**No hyphens, no special characters.** ULIDs use Crockford Base32 (characters `0-9A-Z` excluding `I`, `L`, `O`, `U`). They are safe in filenames, URLs, and environment variables without quoting or encoding. UUID hyphens require quoting in some shell contexts.
+
+**Compact.** 26 characters vs. 36 for UUID. Minor, but it matters in log lines and filenames that appear in terminal output.
+
+**Millisecond time prefix enables time-range queries.** The first 10 characters of a ULID encode the Unix timestamp in milliseconds. A script can filter the JSONL log to a time range by string-comparing ULID prefixes without parsing every `timestamp` field.
+
+**No runtime dependency.** Each plugin ships its own `echo-ulid.sh` / `archivist-ulid.sh` / `tribunal-ulid.sh` generator implemented in pure bash (with a `python3` fallback for millisecond timestamps on macOS, where `date +%s%3N` is broken). No UUID library needed.
+
+## Why not UUID v7?
+
+UUID v7 is time-ordered like ULID but uses the standard UUID format (32 hex + 4 hyphens). The tradeoffs vs. ULID are: more characters, hyphen special-casing in filenames, and no widely available pure-bash generator. ULID is the better fit for a shell-first ecosystem.
+
+## Consequences
+
+- Every plugin that generates IDs ships its own `*-ulid.sh` library. This is intentional duplication to avoid cross-plugin runtime dependencies, but it means ULID generation logic exists in three places. All three are tested identically via bats.
+- ULID has 80 bits of randomness in the lower 80 bits (after the 48-bit timestamp). The collision probability is negligible for the volumes this ecosystem handles, but not zero.
+- The time-ordered property is only guaranteed within a single millisecond. ULIDs generated in the same millisecond are random in the lower bits, so their relative order is not deterministic. This is acceptable — within a session, events are ordered by emission, not by ULID sort.

package/docs/adr/004-plugin-config-with-settings-overlay.md

@@ -0,0 +1,34 @@
+# ADR-004: Per-Plugin Config with settings.json Overlay
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Plugins need to be configurable. A developer working on a security-sensitive repo wants a tighter Tribunal gate policy; a developer on a fast-iteration project wants Echo to use a cheaper model. Several config models were available:
+
+- **Single global config** — one file under `~/.onlooker/` controls everything.
+- **Plugin-owned config only** — each plugin reads its own file; no user override path.
+- **Separate per-project config files** — e.g., `.onlooker/echo.json`, `.onlooker/tribunal.json`.
+- **Plugin defaults + settings.json overlay** — plugin ships `config.json` with defaults; users override via the standard Claude Code `settings.json` under a plugin-namespaced key.
+
+## Decision
+
+Each plugin ships `config.json` with defaults. Users override per-project in `.claude/settings.json` (or globally in `~/.claude/settings.json`) under the plugin's namespace key (e.g., `"echo"`, `"tribunal"`).
+
+## Rationale
+
+**`settings.json` is already the Claude Code config file.** Developers already open `.claude/settings.json` to configure permissions, hooks, and tools. Putting plugin config in the same file means one file to edit, one file to commit, one file to review in a PR. Introducing `.onlooker/echo.json` as a separate file creates fragmentation without benefit.
+
+**Two levels cover the common cases without complexity.** Global (`~/.claude/settings.json`) sets your personal defaults — the model you prefer, your default drift threshold. Project-level (`.claude/settings.json`) overrides for the specific repo. Most plugin config systems need exactly these two scopes; adding more (team, org, workspace) introduces merging ambiguity.
+
+**Plugin `config.json` is the source of truth for available knobs.** Every configurable key is documented in the plugin's `config.json` with its default value. Users browse the defaults to discover what's overridable. This is simpler than a separate schema document.
+
+**Config loading is a thin bash function.** Each plugin ships a `*-config.sh` library (`echo_config_get`, `tribunal_config_get`, etc.) that reads the settings overlay first, falls back to plugin defaults. The pattern is consistent across plugins and is tested via bats.
+
+## Consequences
+
+- Plugin config keys must not collide with existing Claude Code top-level keys (`permissions`, `hooks`, `mcpServers`, `env`, etc.). Plugin namespaces (`"echo"`, `"tribunal"`, `"archivist"`) are chosen to avoid conflicts.
+- Merge behavior is not yet uniform across plugins. Tribunal and Archivist use a recursive `deepmerge` (implemented in jq) so a user can override a single nested key without replacing the whole sub-object. Echo uses a simpler per-key lookup that falls back to plugin defaults. New plugins should use `deepmerge` for consistency.
+- `config.json` is committed to the repo and ships with the plugin. It is not user-editable in place — users always override via `settings.json`. This prevents accidental plugin updates from overwriting user config.
+- There is no validation that `settings.json` keys are recognized by the plugin. An unknown key silently does nothing. A future lint step could warn on unrecognized plugin config keys.