@onlooker-community/ecosystem 0.33.1 → 0.34.0

package/docs/superpowers/specs/2026-08-09-lesson-transform-design.md

@@ -0,0 +1,261 @@
+# Lesson Transform — Design
+
+**Status:** Approved, not started.
+**Tracked by:** `ecosystem-4z8.1`, under epic `ecosystem-4z8`.
+**Parent design:** `docs/superpowers/specs/2026-08-08-promotion-pipeline-design.md` in the
+[onlooker](https://github.com/onlooker-community/onlooker) repo, Sections 2–4.
+That document governs the pipeline. This one covers stage five only, and where
+the two disagree, the disagreements are called out explicitly below.
+
+---
+
+## What this stage is
+
+Librarian's fifth stage. It reads one durable, classified, deduped archivist
+artifact and emits a **lesson candidate** — the subset of a Lesson that can be
+inferred from an artifact.
+
+It is not a Lesson. `lesson.schema.json` v2 requires thirteen fields; this stage
+owns four:
+
+| Field | Owner |
+|---|---|
+| `claim`, `rationale`, `evidence`, `applies_to` | **this stage** |
+| `visibility` | the human, at confirmation (`4z8.2`) |
+| `consensus` | the jury (`4z8.3`) |
+| `id`, `schema_version`, `source`, `status`, `superseded_by`, `author_key`, `promoted_at` | the pool write (`4z8.4`) |
+
+Keeping that split explicit is what stops a stage inventing a field it does not
+own. It also answers the open question the epic carried: the transform *cannot*
+validate against `lesson.schema.json`, because the object is deliberately
+incomplete at this point.
+
+## Decisions
+
+Four decisions were settled during design. The first and third depart from the
+parent spec; both departures are argued below rather than assumed.
+
+**1. No recoverable resolution means declined.** `evidence.resolution` is
+required with `minLength: 1`, and the archivist artifact shape has no resolution
+field — it must be inferred from prose. When it is not there, the artifact is
+declined. This preserves the contract's stance that "this breaks" without "and
+this fixed it" is a warning, not a lesson.
+
+**2. Validation is against vendored sub-schemas**, not the full lesson schema,
+and with no network access at runtime. See *Validation* below.
+
+**3. The transform emits `versioned` only.** It can never emit
+`version_independent`. If it cannot infer versions, the artifact is declined.
+
+The parent spec allows either branch and relies on the jury's `scope_accuracy`
+criterion to catch a lazy justification — "the schema stops the accident, the
+jury stops the lazy excuse." That defense has a hole: **private lessons run no
+jury at all.** A weakly-justified `version_independent` candidate marked private
+reaches the pool with nothing checking it, and a lesson with no version bound
+never expires.
+
+That is precisely the motivating failure. The stale vitest artifact was a
+private, local memory that misled its own author across sessions. Closing the
+branch at the transform makes the guarantee structural at every visibility tier
+instead of relying on a gate the private tier skips. `version_independent`
+becomes an explicit human choice at `4z8.2`, made by someone with the context to
+write a justification that is actually true.
+
+**4. A cheap pre-gate runs before the model.** Mirrors librarian's existing
+pre-LLM durability filter.
+
+## Architecture
+
+New file: `plugins/librarian/scripts/lib/librarian-lesson-transform.sh`, sourced
+by the existing `librarian-session-end.sh` chain and running after conflict/dup
+detection. No new hook. No new plugin — librarian already owns the watermark,
+and a second copy of that state would be free to drift.
+
+### Storage
+
+```
+~/.onlooker/librarian/<project-key>/lessons/
+  proposals/<ulid>.json    this stage
+  approved/<ulid>.json     4z8.4
+  declined.jsonl           4z8.4 (but see Boundary changes)
+```
+
+Lesson state lives in its own subtree rather than reusing librarian's existing
+`proposals/` directory. The two carry different consequences: a memory promotion
+writes to your machine, a lesson proposal is a step toward publishing beyond it.
+`4z8.2`'s open question is specifically the risk of users confusing the two, and
+separate trees mean a confirmation surface cannot merge them by accident.
+
+Each candidate carries its source `artifact_id` at the top level, which is
+load-bearing for idempotency.
+
+Use `$ONLOOKER_DIR`, never a hardcoded `~/.onlooker`, so the test suite's
+isolated temp home is respected.
+
+## The three steps
+
+### 1. Pre-gate (bash, free)
+
+`librarian_lesson_pregate <artifact_json>` scans `summary` and `detail` for a
+version-shaped token (`\d+\.\d+`, `v5`, `5.x`).
+
+Because `versioned` is the only branch this stage can emit, an artifact with no
+version token anywhere cannot produce a valid `scope.versions`. Rejecting it is
+a fact about the output shape, not a quality heuristic. The pre-gate rejects
+nothing else — "does this have a resolution" is semantic and stays with the
+model, because a keyword regex would silently drop good candidates.
+
+Pre-gate rejections are silent: no event, no ledger entry. `declined.jsonl`
+exists to make expensive drops auditable and to keep re-runs cheap. Re-running a
+regex is free, so recording it would dilute the signal `4z8.4` wants for rubric
+tuning.
+
+### 2. Model call
+
+Mirrors `librarian-classifier.sh`: `claude -p --max-turns 1`, model, temperature
+and max-tokens from config, a hard wall-clock timeout so SessionEnd cannot hang,
+fail-soft to empty string, markdown fences stripped before parsing. The timeout
+follows the classifier's ceiling of 20 seconds per call, and like the classifier
+it falls back through `timeout`, `gtimeout`, then no timeout when neither exists.
+
+The prompt supplies the artifact in a delimited block and requires one of two
+responses: a candidate object, or an explicit refusal carrying a reason
+(`no_resolution` or `no_versions`). A refusal is a real answer and must be
+distinguishable from a failed call.
+
+Config lives in the plugin's `config.json` under
+`librarian.lesson_transform.{model, timeout_seconds}`, read via
+`librarian_config_get` from the caller, with user overrides under the plugin
+namespace key per ADR-004. There is no `enabled` flag — that option was removed
+repo-wide in #108.
+
+Two keys only. `claude --help` exposes `--model` and no sampling flags, so
+`temperature` and `max_output_tokens` cannot reach the model through this CLI.
+`librarian-classifier.sh` currently reads both and passes them to a function
+that ignores them — dead config that reads as though it works. Sampling control
+would require moving off `claude -p` to the API, which is a separate decision.
+
+### 3. Validation
+
+Two layers, because **ajv is not available at runtime**. It resolves in dev and
+CI only; installed marketplace plugins ship no `node_modules` (ADR-005).
+
+- **Runtime:** dependency-free `jq`, which works everywhere.
+- **Source of truth:** sub-schemas vendored at
+  `plugins/librarian/schema/lesson-evidence.subschema.json` and
+  `lesson-applies-to.subschema.json`, extracted from the published
+  `lesson.schema.json`.
+- **Tests:** assert the `jq` validator and the vendored sub-schema agree over a
+  corpus. The parent spec sets this precedent directly — the two mechanisms were
+  "proven able to disagree," so they are asserted separately.
+- **CI:** a drift guard asserts the vendored copies carry recorded provenance
+  (source path and `schema_version: 2`) and have not been edited by hand.
+
+  Note that this is weaker than the guard used for *event* schemas, which
+  compares against `schema.onlooker.dev`. That endpoint currently serves no
+  lesson schema — `lesson.schema.json`, `/`, and `lesson/v2.json` all return
+  404 — so a fetch-and-compare guard is not available yet. When lesson schemas
+  are published, the guard should be upgraded to fetch-and-compare; until then
+  a cross-repo drift can only be caught by a human. Tracked separately.
+
+The version-range pattern is where this earns its keep. The schema accepts `<6`,
+`<=6`, `=6`, `>4`, `>=4`, and two-sided `>=4 <6`. It **rejects** npm-style
+`^5.4.21`, `~5`, `5.x`, and bare `5.4.21` — which are exactly what a model
+reaches for by default.
+
+It also rejects `>=0`, `>=0.0`, and `>=0.0.0` by construction. An unbounded
+lower bound is version-independence wearing a costume: it matches every session
+and never expires. That closes the same hole decision 3 closes, one layer down.
+
+Plus the cross-field rule JSON Schema cannot express: every key of
+`scope.versions` must name an entry in `applies_to.stack`.
+
+## Failure taxonomy
+
+Two categories look identical from the call site — both produce no candidate —
+and conflating them is the sharpest risk in this stage.
+
+| Condition | Outcome |
+|---|---|
+| pre-gate: no version token | silent skip, nothing written |
+| model returns unparseable JSON | declined, `transform_invalid` |
+| model refuses: no resolution | declined, `no_resolution` |
+| model refuses: cannot infer versions | declined, `no_versions` |
+| candidate fails sub-schema validation | declined, `schema_invalid` |
+| `versions` key not named in `stack` | declined, `schema_invalid` |
+| `claude` CLI absent | **untouched**, no ledger entry |
+| timeout, or empty response | **untouched**, no ledger entry |
+
+A verdict says "this artifact cannot become a lesson." An outage says "we could
+not tell." Recording an outage as a verdict buries a good artifact permanently,
+because the watermark has moved past it and declined entries are never re-read.
+
+## Idempotency
+
+**The watermark cannot provide it.** `last_scan.json` is `{scanned_at: <ISO>}` —
+a wall-clock timestamp stamped at scan time, not an artifact-id set. The parent
+spec's failure table states that the watermark, ledger and pool are "all keyed
+by `artifact_id`"; that is true of the ledger and pool but not the watermark.
+
+Before spending a model call, skip when the `artifact_id` already appears in
+`lessons/proposals/`, `lessons/declined.jsonl`, or `lessons/approved/`. That
+check is what actually delivers "the same artifact cannot be promoted twice" and
+"re-runs are cheap."
+
+Librarian's existing tombstones do not help here: they are keyed by body hash
+with a 180-day TTL, built for "the user rejected this memory, stop offering it."
+Lesson idempotency must be artifact-keyed and permanent.
+
+## Testing
+
+bats, using the repo's isolated-temp-home helpers.
+
+**The parent spec's acceptance test inverts.** It designates artifact
+`01KZ45MKAM734ZS7JK24D2DK0R` — the real vitest/vite mismatch — and expects it to
+transform to `kind: versioned` with `{vite: "<6", vitest: ">=4"}`. Under decision
+1 it cannot: the artifact records only that the mismatch is real, and its session
+ended with an open question titled "What is the correct fix for the vitest/vite
+version mismatch?" No resolution was ever found. Neither does its later
+refutation artifact (`01KZEAF9EY4C6TTR0V7YFN9VYJ`), which says the claim was
+disproven without stating what is true.
+
+So it becomes the **negative** test: declined, `no_resolution`. The artifact that
+motivated the whole design proves the resolution rule fires.
+
+The positive test uses a synthetic fixture, since no artifact on disk carries
+both a resolution and versions. Shape it like the vitest case so it still
+asserts `{vite: "<6", vitest: ">=4"}`.
+
+Also:
+
+- validator agreement over a range corpus — `^5.4.21`, `~5`, `5.x`, `5.4.21`,
+  `>=0`, `>=0.0.0` must all fail; `<6`, `>=4`, `>=4 <6`, `=6` must pass
+- infrastructure is not a verdict: with `claude` absent, nothing is written to
+  `declined.jsonl` or anywhere else. This is the test most likely to regress
+  silently
+- idempotency: an `artifact_id` already in `declined.jsonl` triggers no model call
+- cross-field: a `versions` key absent from `stack` is declined
+- pre-gate: an artifact with no version token produces no ledger entry
+
+## Events
+
+`librarian.lesson.proposed` and `librarian.lesson.declined`, emitted through
+`scripts/lib/onlooker-event.mjs`. Both must be registered in
+`@onlooker-community/schema` before they are emitted.
+
+## Boundary changes to sibling issues
+
+Building this stage first has two consequences for the issues around it:
+
+- **`4z8.4`** currently owns `declined.jsonl` and its append function. The
+  transform produces declines, so the storage primitive moves here and `4z8.4`
+  reuses it.
+- **`4z8.2`** gains the `version_independent` path from decision 3, including
+  where a human writes and edits the justification.
+
+## Out of scope
+
+Version inference from anything but artifact prose. Reading the project's
+current `package.json` or lockfile would report today's versions, not the
+versions in effect when the problem was observed — and the gap between those two
+is the entire staleness problem this pipeline exists to solve.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -25,10 +25,11 @@
     "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 plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh plugins/assayer/scripts/hooks/*.sh plugins/assayer/scripts/lib/*.sh plugins/cartographer/scripts/hooks/*.sh plugins/cartographer/scripts/lib/*.sh plugins/bursar/scripts/hooks/*.sh plugins/bursar/scripts/lib/*.sh plugins/lineage/scripts/hooks/*.sh plugins/lineage/scripts/lib/*.sh plugins/inspector/scripts/hooks/*.sh plugins/inspector/scripts/lib/*.sh",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
+    "lint:lesson-schema": "node scripts/lint/check-lesson-schema-drift.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",
     "coverage:bash": "node scripts/coverage/bash-coverage.mjs",
     "coverage": "npm run coverage:node && npm run coverage:bash",
-    "test:ci": "npm run test:shellcheck && npm run test:bats && npm run test:schema && npm run lint:check && npm run lint:manifests && npm run lint:references",
+    "test:ci": "npm run test:shellcheck && npm run test:bats && npm run test:schema && npm run lint:check && npm run lint:manifests && npm run lint:references && npm run lint:lesson-schema",
     "lint:check": "biome check . && markdownlint '**/*.md'",
     "lint": "biome lint --write && markdownlint --fix '**/*.md'",
     "format": "biome format --write && markdownlint --fix '**/*.md'",

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

@@ -1,6 +1,6 @@
 {
   "name": "librarian",
-  "version": "0.6.1",
+  "version": "0.7.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",

package/plugins/librarian/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.7.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.6.1...librarian-v0.7.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.6.1](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.6.0...librarian-v0.6.1) (2026-08-02)
 
 

package/plugins/librarian/config.json

@@ -16,6 +16,10 @@
       "max_output_tokens": 256,
       "min_classifier_confidence": 0.6
     },
+    "lesson_transform": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout_seconds": 20
+    },
     "durability_filter": {
       "marker_phrases": [
         "always",

package/plugins/librarian/schema/PROVENANCE.json

@@ -0,0 +1,7 @@
+{
+  "source_repo": "https://github.com/onlooker-community/onlooker",
+  "source_path": "packages/lesson-contract/schema/lesson.schema.json",
+  "schema_version": 2,
+  "extracted": ["properties.evidence", "properties.applies_to"],
+  "note": "Vendored because ajv is unavailable at runtime (ADR-005). Runtime enforcement is jq in librarian-lesson-validate.sh; these files are the source of truth those rules mirror. Upgrade to a fetch-and-compare guard once lesson schemas are published — schema.onlooker.dev serves none today."
+}

package/plugins/librarian/schema/lesson-applies-to.subschema.json

@@ -0,0 +1,74 @@
+{
+  "type": "object",
+  "properties": {
+    "stack": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "scope": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "versioned"
+            },
+            "versions": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1
+              },
+              "additionalProperties": {
+                "type": "string",
+                "pattern": "^((<|<=|=)\\d+(\\.\\d+)?(\\.\\d+)?|(>|>=)(\\d*[1-9]\\d*(\\.\\d+)?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*(\\.\\d+)?|0+\\.0+\\.\\d*[1-9]\\d*)|(>|>=)\\d+(\\.\\d+)?(\\.\\d+)? (<|<=)\\d+(\\.\\d+)?(\\.\\d+)?)$"
+              },
+              "description": "Comparator-prefixed version ranges keyed by stack entry, for example {\"vite\": \"<6\"}. A two-sided range reads lower bound then upper bound. Multiple entries combine with AND: every entry must match for the lesson to still apply.",
+              "minProperties": 1
+            }
+          },
+          "required": ["kind", "versions"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "version_independent"
+            },
+            "justification": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Why this lesson holds regardless of version. Judged, not assumed."
+            }
+          },
+          "required": ["kind", "justification"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "file_patterns": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "task_kinds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "required": ["stack", "scope", "file_patterns", "task_kinds"],
+  "additionalProperties": false,
+  "description": "Every key of scope.versions must name an entry in stack. That rule is enforced at ingest, not by this schema, because JSON Schema cannot express a constraint spanning two fields."
+}

package/plugins/librarian/schema/lesson-evidence.subschema.json

@@ -0,0 +1,36 @@
+{
+  "type": "object",
+  "properties": {
+    "artifact_ids": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
+      }
+    },
+    "session_ids": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "project_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{12}$"
+    },
+    "observed_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+    },
+    "resolution": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": ["artifact_ids", "session_ids", "project_key", "observed_at", "resolution"],
+  "additionalProperties": false
+}

package/plugins/librarian/scripts/hooks/librarian-session-end.sh

@@ -59,6 +59,12 @@ source "${PLUGIN_ROOT}/scripts/lib/librarian-durability.sh"
 source "${PLUGIN_ROOT}/scripts/lib/librarian-classifier.sh"
 # shellcheck source=../lib/librarian-conflict-detector.sh
 source "${PLUGIN_ROOT}/scripts/lib/librarian-conflict-detector.sh"
+# shellcheck source=../lib/librarian-lesson-validate.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-validate.sh"
+# shellcheck source=../lib/librarian-lesson-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-storage.sh"
+# shellcheck source=../lib/librarian-lesson-transform.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-lesson-transform.sh"
 
 librarian_now_ms() {
 	local now_ms
@@ -424,6 +430,26 @@ for ((i = 0; i < KEPT_COUNT; i++)); do
 		}')"
 done
 
+# ---------------------------------------------------------------------------
+# Stage 5 — lesson transform.
+#
+# Runs over the same durability survivors the classifier saw. Each artifact is
+# independent: a decline or an outage on one never stops the rest.
+# ---------------------------------------------------------------------------
+LESSON_PROPOSED=0
+LESSON_DECLINED=0
+
+for ((li = 0; li < KEPT_COUNT; li++)); do
+	LESSON_ARTIFACT=$(printf '%s' "$KEPT" | jq -c ".[$li]")
+	[[ -z "$LESSON_ARTIFACT" || "$LESSON_ARTIFACT" == "null" ]] && continue
+
+	LESSON_RESULT=$(librarian_lesson_transform_one "$PROJECT_KEY" "$LESSON_ARTIFACT")
+	case "$LESSON_RESULT" in
+		proposed:*) LESSON_PROPOSED=$((LESSON_PROPOSED + 1)) ;;
+		declined:*) LESSON_DECLINED=$((LESSON_DECLINED + 1)) ;;
+	esac
+done
+
 # ----------------------------------------------------------------------------
 # Watermark advance + scan.complete.
 # ----------------------------------------------------------------------------

package/plugins/librarian/scripts/lib/librarian-lesson-storage.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Storage for the lesson subtree.
+#
+#   <project_dir>/lessons/proposals/<ulid>.json   awaiting human confirmation
+#   <project_dir>/lessons/approved/<ulid>.json    jury passed (written by 4z8.4)
+#   <project_dir>/lessons/declined.jsonl          append-only, never re-judged
+#
+# Lessons live apart from librarian's memory `proposals/` on purpose: a memory
+# promotion writes to this machine, a lesson proposal is a step toward
+# publishing beyond it. Separate trees keep a confirmation surface from
+# merging the two by accident.
+#
+# Requires librarian-storage.sh (librarian_project_dir) and librarian-ulid.sh.
+
+librarian_lessons_dir() {
+	local key="$1"
+	printf '%s/lessons' "$(librarian_project_dir "$key")"
+}
+
+librarian_lesson_storage_init() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	local dir
+	dir=$(librarian_lessons_dir "$key")
+	mkdir -p "$dir/proposals" "$dir/approved" 2>/dev/null
+}
+
+# Write one candidate. Prints the ULID on success.
+# Usage: librarian_lesson_write_proposal <key> <candidate_json> <artifact_id>
+librarian_lesson_write_proposal() {
+	local key="$1"
+	local candidate="$2"
+	local artifact_id="$3"
+	[[ -z "$key" || -z "$candidate" || -z "$artifact_id" ]] && return 1
+
+	librarian_lesson_storage_init "$key" || return 1
+
+	local id now out
+	id=$(librarian_ulid) || return 1
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	out="$(librarian_lessons_dir "$key")/proposals/${id}.json"
+
+	jq -n \
+		--arg id "$id" \
+		--arg artifact_id "$artifact_id" \
+		--arg created "$now" \
+		--argjson candidate "$candidate" \
+		'{
+			id: $id,
+			artifact_id: $artifact_id,
+			created_at: $created,
+			status: "pending",
+			candidate: $candidate
+		}' > "$out" 2>/dev/null || return 1
+
+	printf '%s' "$id"
+}
+
+# Append one decline. Only ever called for real determinations — never for a
+# missing CLI, a timeout, or an empty response. Recording an outage here would
+# bury a good artifact permanently, because the watermark has already moved
+# past it and declined entries are never re-read.
+#
+# Usage: librarian_lesson_append_declined <key> <artifact_id> <reason> [detail]
+librarian_lesson_append_declined() {
+	local key="$1"
+	local artifact_id="$2"
+	local reason="$3"
+	local detail="${4:-}"
+	[[ -z "$key" || -z "$artifact_id" || -z "$reason" ]] && return 1
+
+	librarian_lesson_storage_init "$key" || return 1
+
+	local now line
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	line=$(jq -cn \
+		--arg artifact_id "$artifact_id" \
+		--arg reason "$reason" \
+		--arg detail "$detail" \
+		--arg at "$now" \
+		'{
+			artifact_id: $artifact_id,
+			reason: $reason,
+			detail: (if $detail == "" then null else $detail end),
+			declined_at: $at
+		}') || return 1
+
+	printf '%s\n' "$line" >> "$(librarian_lessons_dir "$key")/declined.jsonl"
+}
+
+# Returns 0 when this artifact has already been handled.
+#
+# The watermark cannot answer this: last_scan.json records only *when* we
+# scanned, not which artifacts were considered. Idempotency is artifact-keyed
+# and permanent, unlike tombstones (body-hash keyed, TTL'd).
+#
+# Usage: librarian_lesson_seen <key> <artifact_id>
+librarian_lesson_seen() {
+	local key="$1"
+	local artifact_id="$2"
+	[[ -z "$key" || -z "$artifact_id" ]] && return 1
+
+	local dir
+	dir=$(librarian_lessons_dir "$key")
+
+	# -R reads each line as a raw string and fromjson? yields nothing for a
+	# line that fails to parse, instead of aborting the whole jq invocation.
+	# Without this, one truncated trailing line (e.g. a process killed
+	# mid-append) makes jq exit 5 for the entire file, and every artifact
+	# declined before that line reads back as "not seen."
+	#
+	# `objects` after fromjson? is load-bearing, not decorative: fromjson?
+	# only guards the *parse*, not what comes after it in the pipe. A line
+	# that is valid JSON but not an object (a bare `123`, `true`, `"str"`, or
+	# `[1,2,3]`) parses cleanly, then `.artifact_id` indexing on that
+	# non-object errors out the whole jq invocation — the same
+	# every-prior-decline-reads-as-unseen failure the -R/fromjson? guard
+	# above exists to prevent, just reached through a different door.
+	# `objects` filters those values out before `.artifact_id` ever runs.
+	if [[ -f "$dir/declined.jsonl" ]] \
+		&& jq -Re --arg a "$artifact_id" 'fromjson? | objects | select(.artifact_id == $a)' \
+			"$dir/declined.jsonl" >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local f
+	for f in "$dir"/proposals/*.json "$dir"/approved/*.json; do
+		[[ -f "$f" ]] || continue
+		if jq -e --arg a "$artifact_id" '.artifact_id == $a' "$f" >/dev/null 2>&1; then
+			return 0
+		fi
+	done
+
+	return 1
+}