@onlooker-community/ecosystem 0.33.0 → 0.34.0

package/.agents/skills/beads/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: beads
+description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.
+---
+
+# Beads
+
+Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
+
+## First Step
+
+Run:
+
+```bash
+bd prime
+```
+
+If that prints nothing, check whether the repository has an active Beads workspace:
+
+```bash
+bd where
+```
+
+## Preferred Route
+
+Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
+
+## Core CLI Workflow
+
+1. Find work:
+
+```bash
+bd ready
+bd list --status=open
+bd list --status=in_progress
+```
+
+2. Inspect before editing:
+
+```bash
+bd show <id>
+```
+
+3. Claim work atomically:
+
+```bash
+bd update <id> --claim
+```
+
+4. Create durable follow-up work when implementation reveals new tasks:
+
+```bash
+bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
+```
+
+5. Close completed work:
+
+```bash
+bd close <id> --reason="Completed"
+```
+
+## What Belongs In Beads
+
+Use Beads for:
+
+- shared project tasks
+- blockers and dependencies
+- discovered follow-up work
+- work that must survive thread reset, compaction, or handoff
+- status that another person or agent should be able to resume
+
+Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
+
+## Rules
+
+- Do not create markdown TODO files as the source of truth when Beads is available.
+- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
+- Prefer `--json` when parsing `bd` output programmatically.
+- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
+- Do not auto-close or mutate tasks unless the work is actually complete.

package/.agents/skills/beads/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Beads"
+  short_description: "Project task tracking with bd"
+  default_prompt: "Use $beads to inspect ready work and manage durable project tasks."

package/.claude/settings.json

@@ -1,5 +1,18 @@
 {
   "enabledPlugins": {
     "ecosystem@onlooker-community": true
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "bd prime --hook-json",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ]
   }
 }

package/.claude-plugin/plugin.json

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

package/.codex/config.toml

@@ -0,0 +1,2 @@
+[features]
+hooks = true

package/.codex/hooks.json

@@ -0,0 +1,51 @@
+{
+  "hooks": {
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "command": "bd codex-hook PostCompact",
+            "statusMessage": "Scheduling Beads context refresh",
+            "type": "command"
+          }
+        ],
+        "matcher": "manual|auto"
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "command": "bd codex-hook PreCompact",
+            "statusMessage": "Checking Beads context",
+            "type": "command"
+          }
+        ],
+        "matcher": "manual|auto"
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "bd codex-hook SessionStart",
+            "statusMessage": "Loading Beads context",
+            "type": "command"
+          }
+        ],
+        "matcher": "startup|resume|clear"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "command": "bd codex-hook UserPromptSubmit",
+            "statusMessage": "Refreshing Beads context",
+            "type": "command"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.markdownlint.json

@@ -13,5 +13,8 @@
   "MD060": false,
   "MD024": {
     "siblings_only": true
+  },
+  "MD010": {
+    "code_blocks": false
   }
 }

package/.release-please-manifest.json

@@ -1,19 +1,19 @@
 {
-  ".": "0.33.0",
+  ".": "0.34.0",
   "plugins/archivist": "0.3.1",
-  "plugins/tribunal": "1.1.1",
+  "plugins/tribunal": "1.1.2",
   "plugins/echo": "0.3.1",
   "plugins/cartographer": "0.3.1",
   "plugins/governor": "0.3.2",
   "plugins/compass": "0.4.1",
-  "plugins/scribe": "0.4.1",
+  "plugins/scribe": "0.4.2",
   "plugins/counsel": "0.5.1",
   "plugins/warden": "0.3.1",
-  "plugins/librarian": "0.6.1",
-  "plugins/curator": "0.2.1",
+  "plugins/librarian": "0.7.0",
+  "plugins/curator": "0.2.2",
   "plugins/historian": "0.3.2",
-  "plugins/assayer": "1.1.1",
+  "plugins/assayer": "1.1.2",
   "plugins/bursar": "0.3.0",
-  "plugins/lineage": "0.2.1",
-  "plugins/inspector": "0.3.1"
+  "plugins/lineage": "0.2.2",
+  "plugins/inspector": "0.3.2"
 }

package/AGENTS.md

@@ -0,0 +1,135 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
+
+> **Architecture in one line:** Issues live in a local Dolt database
+> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a
+> git-compatible protocol), stored under `refs/dolt/data` on your git
+> remote — separate from `refs/heads/*` where your code lives.
+> `.beads/issues.jsonl` is a passive export, not the wire protocol.
+>
+> See [SYNC_CONCEPTS.md](https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md)
+> for the one-screen overview and anti-patterns (don't treat JSONL as the
+> source of truth; don't `bd import` during normal operation; don't
+> reach for third-party Dolt hosting before trying the default).
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work atomically
+bd close <id>         # Complete work
+bd dolt push          # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:970c3bf2 -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See <https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md> for details and anti-patterns.
+
+## Agent Context Profiles
+
+The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
+
+- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
+- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
+- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
+
+## Session Completion
+
+This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
+
+1. **File issues for remaining work** - Create beads for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **Handle git/sync by active profile**:
+   ```bash
+   # Conservative/minimal/default: report status and proposed commands; wait for approval.
+   git status
+
+   # Team-maintainer opt-in only, unless current instructions forbid it:
+   git pull --rebase
+   bd dolt push
+   git push
+   git status
+   ```
+5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
+
+**Critical rules:**
+- Explicit user or orchestrator instructions override this Beads block.
+- Do not commit or push without clear authority from the active profile or the current user request.
+- If a required sync or push is blocked, stop and report the exact command and error.
+<!-- END BEADS INTEGRATION -->
+
+<!-- The Codex block below repeats the "Beads Issue Tracker" heading from the
+     integration block above. Both are generated and re-synced by different `bd`
+     subcommands, so neither heading can be renamed by hand without breaking
+     idempotent regeneration. These comments sit outside the BEGIN/END markers
+     so `bd` does not clobber them when it rewrites the block. -->
+<!-- markdownlint-disable MD024 -->
+<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
+## Beads Issue Tracker
+
+Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.
+
+### Quick Reference
+
+```bash
+bd ready                # Find available work
+bd show <id>            # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>           # Complete work
+bd prime                # Refresh Beads context
+```
+
+### Rules
+
+- Use `bd` for all task tracking; do not create markdown TODO lists.
+- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
+- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
+
+**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See <https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md> for details and anti-patterns.
+<!-- END BEADS CODEX SETUP -->
+<!-- markdownlint-enable MD024 -->

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.34.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.33.1...ecosystem-v0.34.0) (2026-08-09)
+
+
+### Features
+
+* **librarian:** transform artifacts into shareable lesson candidates :microscope: ([#132](https://github.com/onlooker-community/ecosystem/issues/132)) ([48adbc7](https://github.com/onlooker-community/ecosystem/commit/48adbc7ec572b96b47f1be5f92810088c98702c6))
+
+## [0.33.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.33.0...ecosystem-v0.33.1) (2026-08-02)
+
+
+### Bug Fixes
+
+* restore config convenience functions & refactor execution plugins to shared loader ([#128](https://github.com/onlooker-community/ecosystem/issues/128)) ([4b3660c](https://github.com/onlooker-community/ecosystem/commit/4b3660c5a8b234187ec1e71c37b63e6a3d305c98))
+
 ## [0.33.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.32.2...ecosystem-v0.33.0) (2026-08-02)
 
 

package/CLAUDE.md

@@ -94,7 +94,7 @@ Tests use an isolated temp home; nothing writes to your real `~/.onlooker/`.
 Workflow:
 1. Create a feature branch: `git switch -c <type>/<short-description>`
 2. Commit using `/commit`
-3. Push the branch and open a PR using `/git:gh-pr-create`
+3. Push the branch and open a PR using `/git-workflow:pr`
 4. Wait for CI to pass before merging
 
 ## Conventions
@@ -104,3 +104,58 @@ Workflow:
 - 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.
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6cd5cc61 -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See <https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md> for details and anti-patterns.
+
+## Agent Context Profiles
+
+The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
+
+- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
+- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
+- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
+
+## Session Completion
+
+This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
+
+1. **File issues for remaining work** - Create beads for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **Handle git/sync by active profile**:
+   ```bash
+   # Conservative/minimal/default: report status and proposed commands; wait for approval.
+   git status
+
+   # Team-maintainer opt-in only, unless current instructions forbid it:
+   git pull --rebase
+   git push
+   git status
+   ```
+5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
+
+**Critical rules:**
+- Explicit user or orchestrator instructions override this Beads block.
+- Do not commit or push without clear authority from the active profile or the current user request.
+- If a required sync or push is blocked, stop and report the exact command and error.
+<!-- END BEADS INTEGRATION -->

package/docs/lesson-promotion-pipeline.md

@@ -0,0 +1,210 @@
+# Lesson Promotion Pipeline
+
+**Status:** Not started. Design is settled; implementation lives in this repo.
+**Tracked by:** `onlooker-97e` in the onlooker beads tracker.
+**Authoritative design:** `docs/superpowers/specs/2026-08-08-promotion-pipeline-design.md`
+in the [onlooker](https://github.com/onlooker-community/onlooker) repo, Sections 2 and 3.
+Read that before making design decisions — this document is orientation, not the spec.
+
+---
+
+## What we are building
+
+A fourth destination for archivist artifacts: a **shared** pool of lessons that
+can cross machines and people, rather than the local, per-machine typed memory
+store librarian writes to today.
+
+This is easy to misread as "another memory type." It is not. Compare with
+[memory-architecture.md](memory-architecture.md):
+
+| | destination | scope | who sees it |
+|---|---|---|---|
+| librarian → typed memory store | `~/.claude/projects/<encoded>/memory/` | one machine | you |
+| **librarian → lesson pool** | `~/.onlooker/librarian/<project-key>/lessons/` | shared, eventually cross-person | you, your org, or the public |
+
+Everything upstream is unchanged. Artifacts are still captured by archivist,
+still filtered for durability, still classified, still deduped. The new work
+hangs off the end of that existing chain.
+
+## The shape
+
+```
+archivist artifacts                      EXISTS  session-scoped facts
+ └→ durability filter                    EXISTS  cheap, pre-LLM
+    └→ type classifier (Haiku)           EXISTS  user/feedback/project/reference
+       └→ conflict/dup detect (Jaccard)  EXISTS  keeps the queue high-signal
+          ══════════════════════════════════════
+          └→ lesson transform (Haiku)    NEW     claim, rationale, applies_to
+             └→ human picks + visibility NEW     propose-only, per librarian ADR-001
+                └→ tribunal gate         NEW     one-shot, visibility-scoped
+                   └→ approved pool      NEW     local; the sync service drains it later
+```
+
+Three new steps, in two existing plugins. **No new plugin.** Librarian already
+owns the artifact reader, the durability filter, the classifier, the dedup pass
+and the proposal queue — the transform is a fifth stage on a chain that exists,
+and its `last_scan.json` watermark already tracks which artifacts have been
+considered. A separate plugin would need a second copy of that state, free to
+drift.
+
+Tribunal contributes a rubric and reuses `tribunal-judge-security`, which it
+already ships disabled by default.
+
+## Why lessons rot, and what the contract does about it
+
+The design exists because of a real artifact in this repo's own storage: a
+vitest/vite version-mismatch decision that was true when captured and is false
+now. Shared and auto-injected, it would send someone else down a dead end.
+
+So staleness is **structural**, not procedural. A lesson carries version ranges,
+and a session outside those ranges simply never matches it. No review queue, no
+expiry job, nothing to forget to run. The contract enforces this by construction:
+`applies_to.scope` is a tagged union, and the branch that claims version
+independence must carry a written justification the tribunal scores. A transform
+that failed to infer versions has nothing to put there, so it cannot silently
+mint a lesson that never expires.
+
+## The contract
+
+Defined in `packages/lesson-contract` in the onlooker repo and **published as
+JSON Schema**:
+
+- `packages/lesson-contract/schema/lesson.schema.json`
+- `packages/lesson-contract/schema/counter-observation.schema.json`
+
+Currently `schema_version: 2`.
+
+**The producing side cannot import the definition.** Plugins here are
+bash-based and live in a different repo; the zod source is not available to
+them. Validate against the published JSON Schema, or simply conform to it. The
+sync endpoint in `apps/api` is the real enforcement boundary and validates
+regardless, so client-side validation is a convenience, not a trust boundary.
+
+Fields worth knowing before you start:
+
+| Field | Note |
+|---|---|
+| `claim` / `rationale` | what is asserted, and why it follows |
+| `evidence.resolution` | **required.** "this breaks" without "and this fixed it" is a warning, not a lesson |
+| `evidence.project_key` | the opaque hash, never the repo name |
+| `applies_to.scope` | `{kind: "versioned", versions}` or `{kind: "version_independent", justification}` |
+| `applies_to.stack` | every key of `scope.versions` must name an entry here — see cross-field rules below |
+| `author_key` | 32 lowercase hex, `HMAC(user_secret, scope)`, derived **per visibility scope** so org and public identities are unlinkable |
+| `visibility` | `private` / `org` / `public` |
+| `status` | `active` / `refuted` / `superseded` / `retracted`. There is deliberately no `expired` |
+
+**Cross-field rules the schema cannot express**, documented in the contract's
+`.describe()` text and enforced at ingest. Worth self-checking before emitting:
+
+- `consensus.agreed <= consensus.judges`
+- every key of `applies_to.scope.versions` names an entry in `applies_to.stack`
+
+## What is already decided
+
+Do not re-litigate these; they came out of a full design cycle and are recorded
+with reasoning in the spec.
+
+**The gate is one-shot.** `max_iterations: 1`. Below threshold, a candidate is
+dropped rather than repaired. Refutation should be cheaper to trigger than
+promotion — a wrong lesson actively misleads, a missing one merely fails to
+help. Fail toward removal. This also bounds token cost per promotion and stops
+the transform learning to satisfy judges rather than the evidence.
+
+**The human confirms before judging, not after.** The transform is Haiku and
+cheap; the jury is Opus and not. Splitting the filters this way means the human
+judges *intent* ("do I want to share anything about this?"), which only they can
+do and which costs nothing, and the jury judges *quality*, which only it can do
+and which costs real money. Opus tokens are then only ever spent on candidates
+someone already wants shared.
+
+**Gating is scoped by visibility.** Not every lesson passes a jury:
+
+| visibility | gate | why |
+|---|---|---|
+| `private` | none | you are the only consumer |
+| `org` | `lesson-promotion` rubric | the org boundary already implies trust |
+| `public` | rubric + disclosure lens | self-reported consensus is gameable by a modified client |
+
+**The rubric**, in tribunal's existing `config.json` shape:
+
+| criterion | weight | `min_pass` | asks |
+|---|---|---|---|
+| `grounding` | 0.45 | 0.7 | does the claim follow from `evidence` and `resolution`? |
+| `scope_accuracy` | 0.35 | 0.7 | does `applies_to` correctly bound the claim? |
+| `generality` | 0.20 | 0.6 | is this a lesson, or a session-scoped fact? |
+
+`score_threshold: 0.75`, `gate_policy: majority`, `aggregation_method:
+weighted_mean`, `judge_types: ["standard", "adversarial"]` — all tribunal
+defaults. The only override is `max_iterations: 1`.
+
+For `public`, add the disclosure lens using the already-shipped
+`tribunal-judge-security`:
+
+| criterion | weight | `min_pass` | asks |
+|---|---|---|---|
+| `disclosure` | 0.30 | **0.9** | leaks a secret or identity, or advocates a harmful practice? |
+
+The high floor is deliberate. Correctness rots and `applies_to` retires it;
+harm does not. A leaked credential never expires on its own, so disclosure gets
+a floor a strong weighted mean cannot average away.
+
+**State layout**, under librarian's existing project key:
+
+```
+~/.onlooker/librarian/<project-key>/
+  lessons/approved/<ulid>.json   jury passed; awaiting sync
+  lessons/declined.jsonl         artifact_id + verdict + reason
+```
+
+The declined ledger matters more than it looks. The watermark advances past a
+rejected artifact, so without a record a drop is either silently permanent or —
+on a rescan — re-pays Opus tokens to re-judge the same failures every session.
+Append-only, never re-judged automatically.
+
+**"Judged and failed" is not "could not judge."** Only real verdicts go in
+`declined.jsonl`. A tribunal API error, or a jury below quorum, leaves the
+candidate in proposals untouched. Conflating them lets one transient outage
+permanently bury good lessons behind a watermark that has already moved.
+
+## Conventions this repo imposes
+
+From [CLAUDE.md](../CLAUDE.md) — these differ from the onlooker repo:
+
+- **Hooks are bash.** No Python or Node entry points in hook scripts, though they
+  may shell out to `node` for event emission or heavy lifting.
+- **Event names** follow `<plugin>.<noun>.<verb>`. Likely additions here:
+  `librarian.lesson.proposed`, `librarian.lesson.approved`,
+  `librarian.lesson.declined`, `tribunal.lesson.judged`.
+- **ULIDs, not UUIDs**, and each plugin ships its own helper. Librarian will need
+  one for lesson ids if it does not have one — copy
+  `plugins/tribunal/scripts/lib/tribunal-ulid.sh` and rename the prefix.
+- **Config defaults** live in the plugin's `config.json`; user overrides go under
+  the plugin's namespace key in settings. See ADR-004.
+
+## Out of scope
+
+**Counter-observations and re-judgment.** They need consumers of shared
+lessons, which needs the sync service and retrieval. The contract already
+defines `ZCounterObservation`, and the counter-observation threshold is
+explicitly still an open number — do not invent one.
+
+**Publishing anywhere.** The pipeline stops at the local approved pool. Nothing
+crosses the network. The sync service drains that queue later, and does not
+exist yet.
+
+**The server-side re-judge for public lessons.** Local consensus for public
+lessons runs here; the pool records the intended visibility so the server knows
+what still needs independent judging.
+
+## Open questions
+
+- **Where the human confirmation surfaces.** Librarian already has a proposal
+  queue and a SessionStart surfacer for memory promotions. Reuse it, or keep
+  lesson proposals separate so the two kinds of confirmation are not confused?
+- **`author_key` derivation.** The contract pins the format — 32 hex,
+  `HMAC(user_secret, scope)` — but nothing derives it yet. Where does
+  `user_secret` live, and how is it created on first use?
+- **Whether the transform self-validates** against the published JSON Schema
+  before writing to the pool, or leaves all validation to ingest. Validating
+  locally catches a bad transform earlier; it also means fetching and caching
+  a schema from another repo.