@onlooker-community/ecosystem 0.23.0 → 0.24.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.23.0",
+  "version": "0.24.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/.github/workflows/autofix.yml

@@ -0,0 +1,65 @@
+name: Auto-format
+
+# Applies `npm run lint` + `npm run format` automatically so formatting drift
+# never has to be fixed by hand. On pull requests it pushes a fixup commit back
+# to the PR branch (re-triggering checks via the PAT) — this is what keeps the
+# release-please PR green without manual intervention. On push to main it acts
+# as a safety net, committing fixes directly with `[skip ci]` to avoid looping.
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  autofix:
+    name: Auto-format and lint
+    runs-on: ubuntu-latest
+    # On fork PRs the PAT secret is not available and we cannot push to the
+    # contributor's branch, so skip the job rather than fail noisily. Same-repo
+    # PRs (including release-please's) and pushes to main always run.
+    if: >-
+      github.event_name == 'push' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use the release-please PAT (not the default GITHUB_TOKEN) so the
+          # pushed fixup commit re-triggers required checks on the PR. Commits
+          # made with GITHUB_TOKEN do not start new workflow runs.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          # Check out the actual branch head. For pull_request events the
+          # default checkout is a detached merge ref we cannot push from.
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Apply lint and format fixes
+        run: |
+          npm run lint
+          npm run format
+
+      - name: Commit and push fixes
+        run: |
+          if git diff --quiet; then
+            echo "No formatting changes needed."
+            exit 0
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add -A
+          if [ "${{ github.event_name }}" = 'push' ]; then
+            # On main, do not skip CI; the follow-up autofix run will no-op once the repo is clean.
+            git commit -m 'style: auto-format :art:'
+          else
+            git commit -m 'style: auto-format :art:'
+          fi
+          git push origin HEAD:${{ github.head_ref || github.ref_name }}

package/.release-please-manifest.json

@@ -1,15 +1,15 @@
 {
-  ".": "0.23.0",
+  ".": "0.24.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
   "plugins/cartographer": "0.2.0",
   "plugins/governor": "0.2.0",
   "plugins/compass": "0.2.0",
-  "plugins/scribe": "0.2.0",
+  "plugins/scribe": "0.2.1",
   "plugins/counsel": "0.2.0",
   "plugins/warden": "0.2.0",
-  "plugins/librarian": "0.1.0",
+  "plugins/librarian": "0.2.0",
   "plugins/curator": "0.1.0",
   "plugins/historian": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.24.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.23.1...ecosystem-v0.24.0) (2026-06-04)
+
+
+### Features
+
+* **librarian:** /librarian review skill closes promotion loop :tada: ([#68](https://github.com/onlooker-community/ecosystem/issues/68)) ([8f3e3db](https://github.com/onlooker-community/ecosystem/commit/8f3e3dbdf6f08dceb0cf61d46281936a4f9954de))
+
+## [0.23.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.23.0...ecosystem-v0.23.1) (2026-06-04)
+
+
+### Bug Fixes
+
+* **scribe:** mark hook scripts executable :relieved: ([#64](https://github.com/onlooker-community/ecosystem/issues/64)) ([05603e5](https://github.com/onlooker-community/ecosystem/commit/05603e56895c009c1435d1712592adbbc4c15e61))
+
 ## [0.23.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.22.0...ecosystem-v0.23.0) (2026-06-04)
 
 

package/package.json

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

package/plugins/compass/README.md

@@ -0,0 +1,173 @@
+# Compass
+
+Pre-write intent clarity gate.
+
+Compass fires on `PreToolUse` for write-class operations, evaluates whether the pending write has sufficient intent clarity to proceed, and blocks with a structured clarification prompt when confidence is low or the evaluators disagree. It is the only plugin that gates write-class tool calls before they execute — complementing governor (budget), tribunal (post-task quality), and warden (safety). To avoid the most common false positive — a terse user reply to a question the agent just asked — Compass evaluates the pending write against the **prior assistant turn** as context, not the current context alone. See [ADR-001](docs/adr/001-evaluate-prompts-in-context.md).
+
+Compass is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | Surface | What Compass does |
+|------|---------|-------------------|
+| `PreToolUse` | `Write`, `Edit`, `MultiEdit` | Runs the full evaluation pipeline and blocks the write when confidence is below threshold or the evaluators disagree. |
+| `PreToolUse` | `Bash` | Same pipeline, but first matches the command against write patterns (redirects, `rm`, `mv`, `cp`, `tee`, and similar). Exits 0 immediately when no write pattern matches. |
+| `PostToolUse` | `Write`, `Edit`, `MultiEdit` | Records the written file path, stem, and timestamp to the session cooldown table so same-file follow-up writes are not re-checked. |
+| `SessionStart` | `*` | Initializes session state: zero turn-check count, empty cooldown table, closed circuit breaker. Exits silently when Compass is disabled. |
+
+The evaluation pipeline runs in order:
+
+```
+Trigger Gate → Transcript Reader → Symbolic Skip Layer → Sanitizer → N=5 Evaluators → Gate
+```
+
+1. **Trigger gate** — applies, in order, the skip sentinel (`[compass:skip]`), skip globs, dir-plus-stem cooldown, the per-turn check budget, the context minimum, and the circuit breaker. The first match short-circuits and emits `compass.check.skipped`.
+2. **Transcript reader** — resolves the prior assistant turn from `transcript_path` in the hook JSON payload (the same field `tribunal-stop-gate.sh` reads). Always reads one turn back — already committed before `PreToolUse` fires, so there is no timing-skew risk. When `transcript_path` is absent or unreadable, the pipeline proceeds with an empty prior turn.
+3. **Symbolic skip layer** — short-circuits to a pass without an LLM call when the prior turn is an enumerated question and the current context is a clean option reference (a number, an ordinal phrase, or a short affirmation with no qualifier clause). Controlled by `skip_patterns.reply_to_question.enabled` (default `true`).
+4. **Sanitizer** — strips evaluator prompt tags, control characters, and null bytes from all evaluator-bound fields, then truncates them, before any content leaves the machine.
+5. **N=5 evaluators** — launches `evaluator.n` parallel Haiku calls with a structured prompt that places `<prior_assistant_turn>` and `<context_excerpt>` in 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?"*
+6. **Gate** — aggregates the sample scores into a mean and standard deviation and applies the blocking rule.
+
+### Blocking rule
+
+Compass blocks the write when **`confidence < confidence_threshold` OR `stddev > stddev_threshold`** (defaults `0.65` and `0.20`). The standard-deviation signal is independent of the mean — when the evaluators disagree, that disagreement is itself a reliable ambiguity signal. A blocked write surfaces the triggering file and tool, the mean score, the standard deviation, the most common concern, the evaluator rationale, and three resolution paths: type `compass: proceed` to override, provide more context for a single re-check, or type `compass: cancel` to abandon the write.
+
+### Error handling
+
+The default `error_policy` is `closed`: when fewer than `evaluator.min_valid_samples` return valid JSON, Compass blocks the write and explains that the check could not complete. Set `error_policy: "open"` to pass writes through on evaluator failure (appropriate for CI). A session-scoped circuit breaker opens after `circuit_breaker.consecutive_failures_to_open` consecutive failures and fails open for `circuit_breaker.open_duration_seconds`, regardless of `error_policy`.
+
+## Activation
+
+Compass is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "compass": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "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,
+    "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
+      }
+    },
+    "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"
+    },
+    "intervention": {
+      "recheck_limit": 1
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any evaluation to run. |
+| `evaluator.model` | `claude-haiku-4-5-20251001` | Model used for each evaluation sample. Haiku is fast and cheap; the convergence prompt does not require deep reasoning. |
+| `evaluator.n` | `5` | Number of parallel evaluation samples launched per check. |
+| `evaluator.temperature` | `0.3` | Sampling temperature. The noise floor at `n=5`, `temperature=0.3` is ~0.62–0.65 for unambiguous tasks, which informs the `confidence_threshold` default. |
+| `evaluator.max_output_tokens` | `128` | Token ceiling per sample. The evaluator returns a small JSON object, so this is intentionally tight. |
+| `evaluator.sample_timeout_seconds` | `8` | Per-sample watchdog. Samples not returned within this window are killed and excluded. |
+| `evaluator.min_valid_samples` | `3` | Minimum number of samples that must return valid JSON. Below this, the `error_policy` is applied. |
+| `confidence_threshold` | `0.65` | Mean score below which the write is blocked. Set at the top of the noise floor; raise after running calibration rather than lowering blindly. |
+| `stddev_threshold` | `0.2` | Sample standard deviation above which the write is blocked, independent of the mean. |
+| `cooldown.seconds` | `120` | A write whose path shares a parent directory and filename stem with a recent successful write is skipped within this window. |
+| `cooldown.identity_match` | `dir_plus_stem` | Cooldown identity strategy. Stem comparison strips only the final extension; the cooldown does not carry across a rename. |
+| `transcript.prior_turn_chars_max` | `800` | Maximum characters of the prior assistant turn fed into the evaluator. Set to `0` to omit the prior turn for near-zero egress. |
+| `transcript.transcript_max_age_seconds` | `300` | Maximum age of the transcript file Compass will read the prior turn from. |
+| `skip_patterns.reply_to_question.enabled` | `true` | Enables the symbolic skip layer. When disabled, every write that passes the trigger gate reaches the LLM evaluator. |
+| `max_checks_per_turn` | `3` | Per-turn evaluation budget. Writes beyond this skip with reason `turn_budget_exhausted`. |
+| `min_context_chars` | `80` | Minimum sanitized context length. Shorter context skips with reason `insufficient_context`. |
+| `context_chars_max` | `600` | Maximum characters of context sent to the evaluator. Set to `0` for near-zero egress. |
+| `include_file_contents` | `false` | When `false`, file contents are never sent to the evaluator — only tool name, file path, operation type, prior turn excerpt, and context excerpt. |
+| `skip_globs` | lock/sum/`node_modules`/`.git`/`dist`/`build` patterns | Paths matching any glob skip evaluation entirely. |
+| `error_policy` | `"closed"` | `closed` blocks on evaluator failure; `open` passes the write through and emits `compass.check.skipped` with reason `sampler_error`. |
+| `circuit_breaker.enabled` | `true` | Enables the session-scoped circuit breaker. |
+| `circuit_breaker.consecutive_failures_to_open` | `3` | Consecutive evaluator failures before the circuit opens. |
+| `circuit_breaker.open_duration_seconds` | `300` | How long the circuit stays open (failing open) before attempting to close. While open, writes skip with reason `circuit_open`. |
+| `intervention.recheck_limit` | `1` | Maximum re-checks per intervention after a user supplies clarification. |
+
+The plugin's `config.json` is the source of truth for available knobs.
+
+### Data egress
+
+Every evaluation sends content to the `evaluator.model` API endpoint. With `include_file_contents: false` (the default), Compass sends only the tool name, file path, operation type, bash command string (command only, not stdin), the prior assistant turn excerpt, and the context excerpt — never file contents. For near-zero egress, set `context_chars_max: 0` and `transcript.prior_turn_chars_max: 0`. Compass cannot auto-detect sensitive paths; for sensitive repositories, set `enabled: false`.
+
+## Storage layout
+
+Compass keeps per-session state — the turn-check count, cooldown table, and circuit-breaker state — under the shared substrate:
+
+```text
+~/.onlooker/compass/sessions/
+└── <session-id>.json   # turn_check_count, cooldown[], circuit_breaker{state, consecutive_failures, opened_at}
+```
+
+State is keyed by session ID and initialized at `SessionStart`. The runtime root is always resolved via `${ONLOOKER_DIR:-$HOME/.onlooker}` so the test suite's isolated temp home is respected.
+
+## Events emitted
+
+Compass emits the canonical `compass.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema). All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When | Key payload fields |
+|-------|------|--------------------|
+| `compass.check.passed` | Confidence ≥ threshold and stddev ≤ threshold. | `confidence`, `stddev`, `file_path`, `tool_name`, `had_prior_turn` |
+| `compass.check.failed` | Confidence < threshold or stddev > threshold. | `confidence`, `stddev`, `primary_concern`, `file_path` |
+| `compass.check.skipped` | A gate rule or the symbolic skip layer matched. | `reason`, `file_path` |
+
+`compass.check.skipped` reasons: `skip_sentinel`, `skip_glob`, `dir_plus_stem_cooldown`, `turn_budget_exhausted`, `insufficient_context`, `circuit_open`, `reply_to_question_pattern`, and `sampler_error`.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- `claude` CLI on `PATH` (the evaluator shells out to `claude -p` for each sample).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+
+## Architecture decisions
+
+Key decisions made during design are recorded in [`docs/adr/`](docs/adr/):
+
+- [ADR-001](docs/adr/001-evaluate-prompts-in-context.md) — Evaluate prompts in context (with the prior assistant turn), not in isolation, plus the symbolic skip pattern for question-answer turns
+
+The full design, including failure modes, the intervention UX, integration points, and open questions, lives in [`docs/design.md`](docs/design.md).

package/plugins/counsel/README.md

@@ -0,0 +1,98 @@
+# Counsel
+
+Weekly synthesis and coaching brief from the full observability stack.
+
+Counsel reads every plugin's events from your onlooker log, runs a single synthesis pass to surface recurring patterns, improvement opportunities, and wins, and writes a structured Markdown brief. At session start, when the last brief has gone stale, it regenerates one and injects it as invisible context — turning weeks of accumulated agent telemetry into a short, actionable read.
+
+Counsel is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | What Counsel does |
+|------|-------------------|
+| `SessionStart` | Resolves the project key, checks whether the latest brief is older than `synthesis_interval_days`. If stale (and enough events exist), reads the last `lookback_days` of events from the onlooker log, calls `claude -p` with a synthesis prompt, writes a `YYYY-WW.md` brief under `~/.onlooker/counsel/<project-key>/briefs/`, emits `counsel.brief.generated`, and injects the brief as `additionalContext`. |
+
+The synthesis pass produces a structured JSON object — `summary`, `patterns`, `recommendations` (each with `title`, `rationale`, and a `high`/`medium`/`low` `priority`), `wins`, and `watch` — which Counsel formats into the Markdown brief.
+
+Counsel partitions the event stream by source plugin, recognizing `tribunal`, `echo`, `sentinel`, `warden`, `oracle`, and `meridian` events (everything else maps to a generic `onlooker_events` source). The synthesis prompt focuses on recurring failure modes and blocked gates, prompt regression trends, budget and resource pressure, quality trends over time, and what the team is consistently doing well.
+
+The hook always exits 0 — it never blocks a session from starting. It skips silently when Counsel is disabled, the directory has no project key (non-git), the latest brief is still fresh, or fewer than `capture.min_events` events fall inside the lookback window.
+
+## Activation
+
+Counsel is **on by default**. Disable it per-project in `.claude/settings.json` (or globally in `~/.claude/settings.json`):
+
+```json
+{
+  "counsel": {
+    "enabled": false
+  }
+}
+```
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "counsel": {
+    "enabled": true,
+    "synthesis_interval_days": 7,
+    "lookback_days": 30,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout": 90,
+      "max_tokens": 4096,
+      "temperature": 0.4
+    },
+    "capture": {
+      "min_events": 10,
+      "events_chars_max": 60000
+    },
+    "output": {
+      "brief_max_chars": 3000
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `true` | Set to `false` to skip all synthesis and injection. |
+| `synthesis_interval_days` | `7` | Minimum age (in days) of the latest brief before a new one is generated. A brief younger than this is considered fresh and the hook skips. |
+| `lookback_days` | `30` | How far back in the event log to read when synthesizing a brief. |
+| `evaluator.model` | `claude-haiku-4-5-20251001` | Model used for the synthesis pass. Haiku is fast and cheap; upgrade for higher-stakes repos. |
+| `evaluator.timeout` | `90` | Per-call wall-clock timeout (seconds) passed to the `timeout` command around `claude -p`. |
+| `evaluator.max_tokens` | `4096` | Token ceiling for the synthesis response. |
+| `evaluator.temperature` | `0.4` | Sampling temperature for the synthesis pass. |
+| `capture.min_events` | `10` | Minimum number of events in the lookback window required to generate a brief. Below this, the hook skips silently. |
+| `capture.events_chars_max` | `60000` | Hard ceiling on the characters of summarized event text fed into the synthesis prompt. |
+| `output.brief_max_chars` | `3000` | Hard ceiling on the brief characters injected as session context. |
+
+## Storage layout
+
+```text
+~/.onlooker/counsel/<project-key>/
+└── briefs/
+    └── <YYYY-WW>.md          # one brief per ISO week; newest sorts last
+```
+
+Briefs are named by ISO year and week (`date '+%G-%V'`). The injected brief is always the lexicographically newest `.md` file in the directory; its file modification time is what the staleness check compares against `synthesis_interval_days`. When no project key can be derived, briefs fall back to `~/.onlooker/counsel/unknown/briefs/`.
+
+Project key: first 12 hex chars of SHA256 of `remote:<git-remote-origin-url>`, falling back to SHA256 of `root:<repo-root>` for repos without a remote. The repo root is resolved through the git common directory, so worktrees of the same repo share a key. This mirrors the tribunal and scribe keying scheme.
+
+## Events emitted
+
+Counsel emits its event surface through [`@onlooker-community/schema`](https://github.com/onlooker-community/schema). All events are validated against the schema before being appended to `~/.onlooker/logs/onlooker-events.jsonl`.
+
+| Event | When |
+|-------|------|
+| `counsel.brief.generated` | After a brief is written. Payload includes `period_start`, `period_end`, `recommendation_count`, and `sources_consulted` (the set of source plugins present in the analyzed event batch). |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- `claude` CLI on `PATH` (the hook shells out to `claude -p` for the synthesis pass).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.

package/plugins/governor/README.md

@@ -0,0 +1,127 @@
+# Governor
+
+Resource governance and budget enforcement for the Onlooker ecosystem.
+
+Governor tracks per-session token and cost spend, gates `Task` spawns before they exceed a configurable budget ceiling, and emits `governor.*` events for audit. Named for the steam-engine governor — the flyweight device that throttles a machine back before it runs away — it keeps a session's subagent fan-out inside a spend envelope instead of letting it accelerate unchecked.
+
+Governor is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+Governor keeps a per-session JSONL ledger and consults it on every `Task` spawn. Accounting is two-phase: the gate writes a *reservation* before a spawn runs so concurrent spawns each see the others' in-flight cost, and completion *cancels* that reservation and records observed spend.
+
+| Hook | Matcher | What Governor does |
+|------|---------|--------------------|
+| `SessionStart` | `*` | Creates `~/.onlooker/governance/ledgers/`, sweeps stale lock directories left by crashed prior sessions (emitting `governor.lock.stale_cleared` for each), and checks that the global policy file exists (warns to stderr if missing — never blocks). |
+| `PreToolUse` | `Task` | The gate. Estimates tokens for the spawn, reads consumed tokens from the ledger under an atomic check-and-reserve lock, decides allow or block, writes a reservation when allowing, and emits `governor.gate.checked`. |
+| `PostToolUse` | `Task` | Records the completed call: negates the reservation estimate, adds observed `actual_tokens` when the tool response carries usage counts, appends a record to the ledger, and emits `governor.call.recorded`. |
+| `Stop` | `*` | Reads cumulative totals from the ledger and emits `governor.session.complete` with token, cost, and call summaries plus an `under_budget` flag. |
+
+### The gate decision
+
+On each `Task` spawn, Governor estimates the spawn's token cost, adds it to the session's consumed tokens, and compares the projection against two thresholds:
+
+- **`ceiling_exceeded`** — projected tokens exceed `tokens_default × hard_stop_margin`. **Always blocks**, regardless of enforcement mode.
+- **`budget_exceeded`** — projected tokens exceed `tokens_default` but stay under the hard ceiling. Blocks only in `hard` enforcement; in `soft` enforcement the spawn is allowed and only the event is emitted.
+- **`lock_timeout`** — the gate lock could not be acquired within its timeout. Treated as a block in `hard` enforcement.
+
+To block, the hook writes `{"decision":"block","reason":"..."}` to stdout (the Claude Code `PreToolUse` block protocol) and still exits 0. All other paths allow the spawn. Every decision — allow or block — emits `governor.gate.checked` with the decision, reason, estimate, and remaining budget.
+
+### Token and cost estimation
+
+Governor does not know the model a spawn will use, so estimates are a planning-time upper bound. Tokens are estimated from the tool-input JSON using a **tier table** of characters-per-token ratios:
+
+| Content tier | Characters per token |
+|--------------|----------------------|
+| ASCII prose | 4.0 |
+| Code / JSON | 3.0 |
+| Mixed | 2.5 |
+| Non-Latin | 1.5 |
+
+The raw estimate is multiplied by `safety_margin` before the gate check. Cost is derived from tokens at a blended ~$9 per million (Sonnet-class $3/M input + $15/M output, assuming a 50/50 split). When a `PostToolUse` response carries `usage.input_tokens` / `usage.output_tokens`, the actual count is recorded alongside the estimate and the running total converges to real spend.
+
+## Activation
+
+Governor is **off by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "governor": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`. While disabled, every hook skips silently and no ledger is written.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "governor": {
+    "enabled": false,
+    "enforcement": "soft",
+    "global_policy_path": "~/.onlooker/governance/global-policy.yaml",
+    "session": {
+      "tokens_default": 100000,
+      "cost_usd_default": 1.0,
+      "reserve_pct": 10
+    },
+    "estimation": {
+      "safety_margin": 1.3,
+      "hard_stop_margin": 1.5,
+      "method": "tier_table"
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any tracking, gating, or event emission to run. |
+| `enforcement` | `"soft"` | `"soft"` tracks and emits events but never blocks on a budget overrun; `"hard"` blocks `Task` spawns once the budget is exceeded. A `ceiling_exceeded` overrun blocks in both modes. |
+| `global_policy_path` | `"~/.onlooker/governance/global-policy.yaml"` | Path checked at `SessionStart`. Missing file warns to stderr only — the session runs without a global ceiling. |
+| `session.tokens_default` | `100000` | Per-session token budget. Projecting past this triggers `budget_exceeded`. Overridable per session via the `ONLOOKER_SESSION_BUDGET_TOKENS` environment variable. |
+| `session.cost_usd_default` | `1.0` | Per-session cost budget in USD. Used by the `Stop` hook to set `under_budget`. |
+| `session.reserve_pct` | `10` | Percentage of the budget held in reserve. |
+| `estimation.safety_margin` | `1.3` | Multiplier applied to the raw token estimate before the gate check. |
+| `estimation.hard_stop_margin` | `1.5` | Multiplier on `tokens_default` that defines the hard ceiling (`ceiling_exceeded`), which blocks regardless of enforcement mode. |
+| `estimation.method` | `"tier_table"` | Estimation strategy. Only `tier_table` is implemented. |
+
+Config resolves in three layers, latest wins: plugin `config.json` → `~/.claude/settings.json` → `<repo>/.claude/settings.json`.
+
+## Storage layout
+
+```text
+~/.onlooker/governance/
+├── ledgers/
+│   ├── <session-id>.jsonl          # one ledger per session (id sanitized to [a-zA-Z0-9-_])
+│   ├── <session-id>.jsonl.lock     # gate / write lock
+│   └── <session-id>.jsonl.poisoned # marker written if a ledger write fails after retries
+└── global-policy.yaml              # advisory global ceiling (optional, checked at SessionStart)
+```
+
+Each ledger line is a JSON record. The gate appends `record_type: "reservation"` rows with a positive `estimated_tokens`; completion appends rows with a negated `estimated_tokens` (canceling the reservation) plus `actual_tokens` when usage is reported. Session totals sum `estimated_tokens + actual_tokens` across every row, so the running total resolves to in-flight estimates plus completed actuals.
+
+Governor honors `$ONLOOKER_DIR`; it never hardcodes `~/.onlooker`, so the test suite's isolated temp home is respected.
+
+## Events emitted
+
+Governor emits the canonical `governor.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema) v2.4.0+. All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When |
+|-------|------|
+| `governor.gate.checked` | On every `Task` spawn at the `PreToolUse` gate. Carries `decision`, `estimated_tokens`, `tokens_available`, `estimation_method`, `safety_margin`, and a `reason` when blocked. |
+| `governor.call.recorded` | After a `Task` completes (`PostToolUse`). Carries `estimated_tokens`, `cost_usd_estimated`, `duration_ms`, and — when usage is reported — `actual_tokens` and `estimation_error_pct`. |
+| `governor.session.complete` | At `Stop`. Carries `total_tokens`, `total_cost_usd`, `total_api_calls`, `budget_usd`, `under_budget`, and `ledger_poisoned`. |
+| `governor.lock.stale_cleared` | At `SessionStart`, once per stale lock directory swept (older than 60 seconds). |
+| `governor.ledger.write_failed` | When a ledger write fails after its retry budget; the ledger is poisoned and `unrecorded_tokens` is reported. |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `awk` for fractional token and cost arithmetic (standard on macOS and most Linux distributions).

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

@@ -1,6 +1,6 @@
 {
   "name": "librarian",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Consolidation layer between archivist's per-session artifacts and the user's durable typed memory store. Detects which session decisions, dead-ends, and open questions deserve to live across sessions, classifies them into the user/feedback/project/reference types, and queues them as proposals for explicit confirmation. Auto-promotion is opt-in. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",
@@ -9,6 +9,6 @@
   "homepage": "https://onlooker.dev",
   "repository": "https://github.com/onlooker-community/ecosystem",
   "license": "MIT",
-  "skills": [],
+  "skills": ["./skills/librarian"],
   "agents": []
 }

package/plugins/librarian/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.1.0...librarian-v0.2.0) (2026-06-04)
+
+
+### Features
+
+* **librarian:** /librarian review skill closes promotion loop :tada: ([#68](https://github.com/onlooker-community/ecosystem/issues/68)) ([8f3e3db](https://github.com/onlooker-community/ecosystem/commit/8f3e3dbdf6f08dceb0cf61d46281936a4f9954de))
+
 ## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.0.1...librarian-v0.1.0) (2026-06-04)