@onlooker-community/ecosystem 0.16.0 → 0.17.0

package/.claude-plugin/marketplace.json

@@ -72,6 +72,32 @@
       "license": "MIT",
       "keywords": ["governance", "budget", "cost", "tokens", "enforcement", "audit"],
       "tags": ["governance", "safety"]
+    },
+    {
+      "name": "compass",
+      "source": "./plugins/compass",
+      "description": "Pre-write intent clarity gate. Intercepts write-class tool calls and samples N=5 parallel evaluators to score intent clarity before allowing writes to proceed. Blocks when confidence is low or evaluators disagree, surfacing a structured clarification prompt. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["alignment", "intent", "safety", "pre-write", "evaluation", "clarification"],
+      "tags": ["safety", "alignment"]
+    },
+    {
+      "name": "scribe",
+      "source": "./plugins/scribe",
+      "description": "Intent documentation from agent activity. Captures why changes were made — problem context, decisions, tradeoffs, and constraints — and distills them into readable Markdown artifacts at session end. Git logs record what changed; scribe records why. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["documentation", "intent", "decisions", "tradeoffs", "why", "context"],
+      "tags": ["documentation", "memory"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.16.0",
+  "version": "0.17.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",

package/.release-please-manifest.json

@@ -1,8 +1,10 @@
 {
-  ".": "0.16.0",
+  ".": "0.17.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
   "plugins/cartographer": "0.2.0",
-  "plugins/governor": "0.1.0"
+  "plugins/governor": "0.2.0",
+  "plugins/compass": "0.2.0",
+  "plugins/scribe": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.17.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.16.0...ecosystem-v0.17.0) (2026-06-01)
+
+
+### Features
+
+* **compass:** pre-write intent clarity gate plugin :compass: ([#47](https://github.com/onlooker-community/ecosystem/issues/47)) ([144c2ef](https://github.com/onlooker-community/ecosystem/commit/144c2ef44d28bab3dcec14a9eace7ec76470d090))
+* **scribe:** intent documentation from agent activity :pencil2: ([#50](https://github.com/onlooker-community/ecosystem/issues/50)) ([f0a95d1](https://github.com/onlooker-community/ecosystem/commit/f0a95d1058e36d1bb5f0f645964d9e88e8f98b66))
+
 ## [0.16.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.15.2...ecosystem-v0.16.0) (2026-05-26)
 
 

package/CLAUDE.md

@@ -0,0 +1,88 @@
+# Onlooker Ecosystem — Agent Instructions
+
+## Repository layout
+
+```
+ecosystem/                    ← substrate plugin (always-on observability)
+  hooks/                      ← session, tool, and prompt hooks
+  scripts/lib/                ← shared bash helpers and the canonical event emitter
+  skills/                     ← user-invocable slash commands
+  config.json                 ← ecosystem defaults
+
+plugins/
+  archivist/                  ← session memory across context truncation
+  cartographer/               ← instruction-file auditor (CLAUDE.md, AGENTS.md, rules/)
+  compass/                    ← pre-write alignment gate (design phase)
+  echo/                       ← prompt-change regression detection
+  governor/                   ← resource governance and budget enforcement
+  tribunal/                   ← multi-agent quality gate (Actor → Jury → Meta-Judge → Gate)
+
+docs/
+  architecture.md             ← how plugins compose and share the event bus
+  adr/                        ← ecosystem-level architectural decisions
+
+scripts/lib/onlooker-event.mjs  ← canonical event builder; all plugins route through this
+~/.onlooker/                    ← shared runtime storage (logs, plugin artifacts)
+```
+
+## Plugin map
+
+| Plugin | Hook surface | When it fires |
+|--------|-------------|---------------|
+| ecosystem | SessionStart/End, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, UserPromptExpansion, PreCompact, PostCompact, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove | Always — substrate |
+| archivist | PreCompact, SessionStart | Extracts decisions/dead-ends on compaction; reinjects at next SessionStart |
+| cartographer | SessionStart, PostToolUse (Write, Edit, MultiEdit) | Audits instruction files on session start and after instruction-file writes |
+| compass | PreToolUse (Write, Edit, MultiEdit, Bash) | Before any write — alignment check |
+| echo | Stop | Regression-tests prompt changes after each agent stop |
+| governor | SessionStart, PreToolUse (Task), PostToolUse (Task), Stop | Budget gates on subagent spawns; tracks spend per session |
+| tribunal | Stop + skill invocation | Post-task quality gate; also invokable via `/tribunal` |
+
+Plugins communicate by emitting events to the JSONL log — they do not call each other directly. All plugins depend on the ecosystem substrate; no plugin depends on another plugin directly.
+
+## Compass plugin (design phase)
+
+Compass is the pre-write alignment gate. It has no implementation yet. Design lives in `plugins/compass/docs/design.md`.
+
+**What it does:** Fires on `PreToolUse` for write-class tools. Samples N=5 parallel Haiku evaluators to score intent clarity. Blocks when `confidence < 0.65 OR stddev > 0.20` and surfaces a clarification prompt.
+
+**Critical architectural decision (ADR-001):** The evaluator must see the **prior assistant turn** alongside the current context — not the current context alone. Evaluating a reply in isolation produces a systematic false-positive class: a user answering an agent's enumerated question ("the internal one") looks ambiguous without the question that prompted it.
+
+The pipeline is:
+
+```
+Trigger Gate → Transcript Reader → Symbolic Skip Layer → Sanitizer → N=5 Evaluators → Gate
+```
+
+- **Transcript reader** resolves `prior_assistant_turn` from `transcript_path` in the hook JSON payload (same field tribunal-stop-gate.sh reads). Reads one turn back from that file (already committed before `PreToolUse` fires — no timing-skew risk). If `transcript_path` is absent or unreadable, proceeds with an empty prior turn.
+- **Symbolic skip layer** short-circuits to `confident` when the prior turn is an enumerated question and the current context is an option reference, without an LLM call. Controlled by `skip_patterns.reply_to_question.enabled` (default `true`).
+- **Evaluator prompt** uses a structured pair: `<prior_assistant_turn>` and `<context_excerpt>` as separate XML-delimited slots. The convergence question is: *"Given the prior assistant turn as context, would two independent readers converge on the same interpretation of this write?"*
+
+See `plugins/compass/docs/adr/001-evaluate-prompts-in-context.md` for the full decision record.
+
+## Adding a new plugin
+
+1. Create `plugins/<name>/` with `.claude-plugin/plugin.json`, `config.json`, `hooks/hooks.json`.
+2. Use `scripts/lib/onlooker-event.mjs` for all event emission — never write directly to the JSONL log.
+3. Store runtime artifacts under `${ONLOOKER_DIR:-$HOME/.onlooker}/<name>/<project-key>/`. Always use `$ONLOOKER_DIR` — never hardcode `~/.onlooker` — so the test suite's isolated temp home is respected.
+4. Derive the project key via `tribunal_project_key` (or equivalent) — first 12 hex chars of SHA256(`remote:<origin-url>`), falling back to SHA256(`root:<repo-root>`) for repos without a remote. See `plugins/tribunal/scripts/lib/tribunal-project-key.sh`.
+5. Register event types in `@onlooker-community/schema` before emitting them (the emitter validates the envelope).
+6. Fail-soft when `~/.onlooker/` is absent — plugins must not block a session they were not invited to.
+
+## Development
+
+```bash
+mise install          # installs all tools declared in mise.toml
+npm ci
+npm test              # bats + schema validation
+npm run test:ci       # shellcheck + bats + schema + lint
+```
+
+Tests use an isolated temp home; nothing writes to your real `~/.onlooker/`.
+
+## Conventions
+
+- All hooks are bash scripts. No Python, no Node entry points in hook scripts (they may shell out to `node` for event emission or heavy lifting).
+- Hook scripts source shared helpers from `scripts/lib/` (or the plugin's own `scripts/lib/`).
+- Event types follow `<plugin>.<noun>.<verb>` — e.g. `compass.check.skipped`, `tribunal.gate.blocked`.
+- ULIDs everywhere for IDs (not UUIDs). Each plugin ships its own `*_ulid` helper (e.g. `archivist-ulid.sh`, `tribunal-ulid.sh`); there is no shared ecosystem helper. Copy `plugins/tribunal/scripts/lib/tribunal-ulid.sh` as a starting point and rename the function prefix.
+- Config defaults live in `config.json`. User overrides go in `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project) under the plugin's namespace key (e.g. `"compass"`, `"tribunal"`). See ADR-004.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -26,7 +26,7 @@
     "test": "npm run test:bats && npm run test:schema",
     "test:bats": "bats test/bats",
     "test:schema": "node --test test/node/*.test.mjs",
-    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh",
+    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",

package/plugins/compass/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "compass",
+  "version": "0.2.0",
+  "description": "Pre-write intent clarity gate. Intercepts write-class tool calls and requires a confidence threshold before allowing them to proceed. Evaluates the pending write against the prior assistant turn as context to avoid false positives on question-answer turns. 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/compass/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/compass-v0.1.0...compass-v0.2.0) (2026-06-01)
+
+
+### Features
+
+* **compass:** pre-write intent clarity gate plugin :compass: ([#47](https://github.com/onlooker-community/ecosystem/issues/47)) ([144c2ef](https://github.com/onlooker-community/ecosystem/commit/144c2ef44d28bab3dcec14a9eace7ec76470d090))

package/plugins/compass/config.json

@@ -0,0 +1,71 @@
+{
+  "plugin_name": "compass",
+  "storage_path": "~/.onlooker",
+  "compass": {
+    "enabled": false,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "n": 5,
+      "temperature": 0.3,
+      "max_output_tokens": 128,
+      "sample_timeout_seconds": 8,
+      "min_valid_samples": 3
+    },
+    "confidence_threshold": 0.65,
+    "stddev_threshold": 0.2,
+    "threshold_calibration_note": "Noise floor at N=5 temp=0.3 is ~0.62–0.65 for unambiguous tasks. Threshold at 0.65 catches borderline-unambiguous cases (acceptable cost: one clarifying prompt) and prevents ambiguous writes in the 0.60–0.64 range from proceeding silently. Run 'compass calibrate' to measure your project-specific baseline.",
+    "cooldown": {
+      "strategy": "path_and_identity",
+      "seconds": 120,
+      "identity_match": "dir_plus_stem"
+    },
+    "transcript": {
+      "prior_turn_chars_max": 800,
+      "transcript_max_age_seconds": 300
+    },
+    "skip_patterns": {
+      "reply_to_question": {
+        "enabled": true,
+        "question_pattern": "numbered_list_with_question_mark",
+        "reply_pattern": "option_reference_or_affirmation"
+      }
+    },
+    "max_checks_per_turn": 3,
+    "min_context_chars": 80,
+    "context_chars_max": 600,
+    "include_file_contents": false,
+    "skip_globs": ["**/*.lock", "**/*.sum", "**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**"],
+    "error_policy": "closed",
+    "circuit_breaker": {
+      "enabled": true,
+      "consecutive_failures_to_open": 3,
+      "open_duration_seconds": 300,
+      "open_behavior": "fail_open"
+    },
+    "sanitization": {
+      "strip_sequences": [
+        "<prior_assistant_turn>",
+        "</prior_assistant_turn>",
+        "<context_excerpt>",
+        "</context_excerpt>",
+        "<tool_input>",
+        "</tool_input>",
+        "<instructions>",
+        "</instructions>",
+        "<|",
+        "[INST]",
+        "[/INST]",
+        "<<SYS>>",
+        "<</SYS>>"
+      ],
+      "strip_null_bytes": true
+    },
+    "data_egress": {
+      "include_file_contents": false,
+      "note": "When false, only the tool name, file path, operation type, prior assistant turn excerpt, and context excerpt (<=600 chars) are sent. File contents are never sent. Set context_chars_max: 0 and prior_turn_chars_max: 0 for near-zero egress."
+    },
+    "intervention": {
+      "recheck_limit": 1
+    }
+  }
+}

package/plugins/compass/docs/adr/001-evaluate-prompts-in-context.md

@@ -0,0 +1,82 @@
+# ADR-001: Compass Evaluates Prompts-in-Context, Not Prompts-in-Isolation
+
+- Status: Accepted
+- Date: 2026-04-20
+- Deciders: Meagan
+- Tags: compass, oracle, calibration, convergence-sampling, hook-architecture
+
+## Context and Problem Statement
+
+Compass's `PreToolUse` hook evaluates each pending write operation using the tool call arguments and a short context excerpt from the conversation. When a user replies to a question the agent just asked — e.g., answering "Let's do 3, both" to an enumerated menu in the prior assistant turn — Compass flags the write that follows as uncertain and blocks progress.
+
+The write is not actually ambiguous. The ambiguity-resolving information lives in the prior assistant turn (the menu), which the hook payload does not see. Compass is correctly executing a subtly wrong specification: its convergence test asks whether two independent readers of the context *alone* would converge, and for context-dependent replies ("option 2", "both", "do the first one", "yes"), the answer in isolation is always no.
+
+This produces a class of false positives that undermines Compass's usefulness in the most common conversational pattern: the agent asks a clarifying question, the user answers it, work proceeds. Under the current design, every write that follows such an answer risks being flagged — not because the user was unclear, but because Compass is blind to what was asked.
+
+The failure mode is most visible in multi-turn flows where the agent itself has done the disambiguation work (listing options, asking targeted questions) and the user is simply selecting. Those are precisely the moments where calibration should be cheapest, not most expensive.
+
+## Decision Drivers
+
+- **False-positive cost is high**: every incorrect flag interrupts the user and forces them to restate context the conversation already established.
+- **Compass's stated value is catching misaligned-but-confident work**: the design should preserve suspicion of genuinely ambiguous writes while not penalizing legitimate context-dependent replies.
+- **Jeong & Son design principle**: declare what you can, reflect symbolically where possible, reserve the LLM for the residual. Answering a menu is a declarable case; it should not require LLM calibration at all.
+- **Hook architecture constraint**: Claude Code hooks receive event payloads, not full transcripts by default. Any fix must be compatible with the payload model.
+- **Tribunal design precedent**: when an evaluator reasons about the quality of its own output, giving it the right substrate to reason over is the load-bearing decision. Tribunal's Actor works because it has access to its full task description; Compass's evaluator needs the same structural access to the turn it is calibrating.
+
+## Considered Options
+
+1. **Make Compass less suspicious overall.** Raise the confidence threshold so borderline cases pass.
+2. **Evaluate prompts-in-context.** Pass the prior assistant turn into the evaluator payload so the convergence test operates on the pair `{prior_assistant_turn, current_context}`.
+3. **Symbolic skip pattern for question-answers.** Detect when the prior assistant turn ends in an enumerated question and the user prompt references an option; skip LLM calibration entirely for that case.
+4. **Integrate with Archivist.** Query Archivist's extracted turn-pair rather than reading the transcript directly.
+
+## Decision
+
+We adopt **Option 2 (evaluate prompts-in-context) as the architectural baseline, combined with Option 3 (symbolic skip pattern) as an optimization layer**.
+
+Option 2 establishes the correct unit of analysis: Compass's convergence test will evaluate whether two independent readers *with access to the prior assistant turn* would converge on the same interpretation of the pending write. This is the minimal change that resolves the specification bug without weakening Compass's core function.
+
+Option 3 layers on top: before invoking the LLM evaluator, Compass performs a cheap symbolic check. If the prior turn ends in an enumerated question (pattern: numbered list with `?` somewhere in the turn) and the current prompt references an option ("1", "option 2", "both", "do 3", "the first one", "yes", "no"), Compass short-circuits to `confident` without an LLM call. This is the Jeong & Son move: most answers to Claude's own questions are declarable; the LLM is reserved for the genuinely ambiguous residual.
+
+Option 1 is rejected because it weakens Compass uniformly, including for writes where suspicion is warranted. Option 4 is deferred; it is a clean longer-term integration but introduces a cross-plugin dependency that Compass does not currently have, and Option 2 is a prerequisite in any case.
+
+## Consequences
+
+### Positive
+
+- False positives on question-answer turns drop substantially (expected near-zero for the enumerated-menu case once Option 3 lands).
+- Compass's convergence test operates on the correct unit of analysis, aligning specification with intent.
+- The symbolic skip pattern reduces LLM invocation rate on a large class of turns, lowering latency and cost.
+- The architectural decision is inspectable and traceable: the substrate change (prior-turn context) is separate from the symbolic optimization (skip pattern), so each can be evaluated independently.
+
+### Negative
+
+- The hook payload grows: it must now include the prior assistant turn, which means reading from the transcript or session log. This adds I/O per evaluation and introduces timing-skew risk (the prior turn's event may not yet be flushed when the `PreToolUse` hook fires).
+- The symbolic skip pattern introduces a regex-based heuristic whose failure modes (false negatives on creatively-phrased answers, false positives on reply-shaped prompts that aren't actually answers) need monitoring.
+- Edge cases appear: what counts as "the prior assistant turn" when the user sends multiple messages in sequence, or when the prior turn was a tool result rather than a conversational reply? These need explicit handling.
+
+### Neutral
+
+- Archivist integration (Option 4) remains available as a future refactor. If Archivist becomes the canonical source of recent turn structure, Compass's transcript-reading logic can be replaced with an Archivist query without changing the architectural decision recorded here.
+
+## Implementation Notes
+
+- The hook script reads the most recent assistant turn from the session transcript. The transcript path is provided as `transcript_path` in the hook JSON payload (consistent with how `tribunal-stop-gate.sh` reads it: `jq -r '.transcript_path // ""'`). If `transcript_path` is absent or the file is unreadable, the hook proceeds with an empty `prior_assistant_turn`. The Onlooker event log is not a fallback — `session.prompt` events record user-prompt telemetry, not assistant-turn content.
+- Compass's evaluator prompt is updated to use a structured pair: `<prior_assistant_turn>` and `<context_excerpt>` as separate XML-delimited slots. The convergence question is phrased as: "Given the prior assistant turn as context, would two independent readers converge on the same interpretation of this write?"
+- The symbolic skip pattern is implemented in bash using `jq` and regex, consistent with the plugin's hook style.
+- Skip-pattern decisions are logged as `compass.check.skipped` with `reason: "reply_to_question_pattern"` so false-negative and false-positive rates can be measured.
+- A new `skip_patterns.reply_to_question.enabled` config key (default: `true`) toggles the symbolic layer.
+
+## Validation
+
+This decision is validated by running Compass against multi-turn conversations where the current implementation produces false interventions on question-answer turns. Expected outcomes:
+
+- Reply-to-question turns (answered with option references) short-circuit to `confident` under the skip pattern.
+- Reply-to-question turns with genuine ambiguity (e.g., "both, but only if it's easy") still reach the LLM evaluator, now with prior-turn context, and produce a meaningful calibration state.
+- Non-reply prompts (new requests, unrelated pivots) are unaffected by the skip pattern and continue through normal evaluation.
+
+## References
+
+- Jeong & Son (2026), *How Much LLM Does a Self-Revising Agent Actually Need?* (arXiv:2604.07236) — declarative substrate principle
+- Tribunal ADR-001 — evaluator substrate precedent: evaluators need structural access to what they evaluate
+- Compass design document (`plugins/compass/docs/design.md`)