@onlooker-community/ecosystem 0.33.0 → 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.0",
+  "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/archivist/scripts/lib/archivist-config.sh

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
 # Config resolution for Archivist.
 #
-# Reads three layers, latest wins:
+# Uses the shared config loader from ecosystem. Reads five layers, latest wins:
 #   1. plugins/archivist/config.json (defaults shipped with the plugin)
 #   2. ~/.claude/settings.json
-#   3. <repo>/.claude/settings.json
+#   3. ~/.claude/settings.local.json (local overrides user)
+#   4. <repo>/.claude/settings.json
+#   5. <repo>/.claude/settings.local.json (local overrides project)
 #
 # Exposes:
 #   archivist_config_load <repo_root>    # populates _ARCHIVIST_CONFIG (JSON)
@@ -13,46 +15,20 @@
 # Settings overlay only touches the `archivist.*` subtree of settings.json so it
 # coexists with other plugins' configuration.
 
+# shellcheck source=../../../scripts/lib/config-loader.sh
+source "${PLUGIN_ROOT}/../../scripts/lib/config-loader.sh"
+
 _ARCHIVIST_CONFIG="{}"
 
 archivist_config_load() {
 	local repo_root="${1:-}"
-	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
-	local home_dir="${HOME:-}"
-
-	local merged="{}"
-	local file
-
-	file="${plugin_root}/config.json"
-	if [[ -f "$file" ]]; then
-		local defaults
-		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
-		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
-			|| merged="$defaults"
-	fi
-
-	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
-		[[ -n "$file" && -f "$file" ]] || continue
-		local overlay
-		overlay=$(jq '{ archivist: (.archivist // {}) }' "$file" 2>/dev/null) || continue
-		[[ -z "$overlay" ]] && continue
-		merged=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
-			def deepmerge($a; $b):
-				if ($a|type) == "object" and ($b|type) == "object" then
-					reduce (($a|keys) + ($b|keys) | unique)[] as $k
-						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
-				elif $b == null then $a
-				else $b end;
-			deepmerge($a; $b)
-		' 2>/dev/null) || true
-	done
-
-	_ARCHIVIST_CONFIG="$merged"
+	config_load_plugin "archivist" "$repo_root" "_ARCHIVIST_CONFIG"
+	return 0
 }
 
 # Read a value from the loaded config. Usage:
 #   archivist_config_get '.archivist.injection.max_items'
 archivist_config_get() {
 	local path="$1"
-	printf '%s' "$_ARCHIVIST_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+	config_get "_ARCHIVIST_CONFIG" "${path}"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "assayer",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Claim verification. At session end, parses the agent's final message for testable claims (\"I ran the tests, they pass\", \"the build is green\") and checks each against the actual command results in the session transcript, classifying it corroborated, contradicted, or unverifiable. Catches lying-without-malice. Advisory by default. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/assayer/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.1.2](https://github.com/onlooker-community/ecosystem/compare/assayer-v1.1.1...assayer-v1.1.2) (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))
+
 ## [1.1.1](https://github.com/onlooker-community/ecosystem/compare/assayer-v1.1.0...assayer-v1.1.1) (2026-08-01)
 
 

package/plugins/assayer/scripts/lib/assayer-config.sh

@@ -1,82 +1,59 @@
 #!/usr/bin/env bash
-# Config loading for Assayer.
-# Reads the repo's .claude/settings.json assayer.* keys, falling back to the
-# plugin's own config.json defaults.
-
-_ASSAYER_CONFIG_JSON=""
-_ASSAYER_PLUGIN_CONFIG_JSON=""
+# Config resolution for assayer.
+#
+# Uses the shared config loader from ecosystem. Reads five layers, latest wins:
+#   1. plugins/assayer/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. ~/.claude/settings.local.json (local overrides user)
+#   4. <repo>/.claude/settings.json
+#   5. <repo>/.claude/settings.local.json (local overrides project)
+#
+# Exposes:
+#   assayer_config_load <repo_root>    # populates _assayer_CONFIG (JSON)
+#   assayer_config_get <jq-path>       # echoes string value (empty if unset)
+#   assayer_config_get_json <jq-path>  # echoes JSON value (null if unset)
+
+# shellcheck source=../../../scripts/lib/config-loader.sh
+source "${PLUGIN_ROOT}/../../scripts/lib/config-loader.sh"
+
+_assayer_CONFIG="{}"
 
 assayer_config_load() {
 	local repo_root="${1:-}"
-
-	_ASSAYER_PLUGIN_CONFIG_JSON=""
-	local plugin_config="${CLAUDE_PLUGIN_ROOT:-}/config.json"
-	if [[ -f "$plugin_config" ]]; then
-		_ASSAYER_PLUGIN_CONFIG_JSON=$(cat "$plugin_config" 2>/dev/null) || _ASSAYER_PLUGIN_CONFIG_JSON=""
-	fi
-
-	_ASSAYER_CONFIG_JSON=""
-	if [[ -n "$repo_root" ]]; then
-		local settings_file="${repo_root}/.claude/settings.json"
-		if [[ -f "$settings_file" ]]; then
-			local settings
-			settings=$(cat "$settings_file" 2>/dev/null) || settings=""
-			local block
-			block=$(printf '%s' "$settings" | jq -c '.assayer // empty' 2>/dev/null) || block=""
-			[[ -n "$block" ]] && _ASSAYER_CONFIG_JSON="$block"
-		fi
-	fi
+	config_load_plugin "assayer" "$repo_root" "_assayer_CONFIG"
+	return 0
 }
 
-# Get a single scalar value. Checks settings.json first, then plugin config.json.
 assayer_config_get() {
-	local key="$1"
-
-	if [[ -n "$_ASSAYER_CONFIG_JSON" ]]; then
-		local val
-		val=$(printf '%s' "$_ASSAYER_CONFIG_JSON" | jq -r "${key} // empty" 2>/dev/null) || val=""
-		[[ -n "$val" && "$val" != "null" ]] && {
-			printf '%s' "$val"
-			return 0
-		}
-	fi
-
-	if [[ -n "$_ASSAYER_PLUGIN_CONFIG_JSON" ]]; then
-		local val
-		val=$(printf '%s' "$_ASSAYER_PLUGIN_CONFIG_JSON" | jq -r ".assayer${key} // empty" 2>/dev/null) || val=""
-		[[ -n "$val" && "$val" != "null" ]] && {
-			printf '%s' "$val"
-			return 0
-		}
-	fi
+	local path="$1"
+	config_get "_assayer_CONFIG" "${path}"
 }
 
-assayer_config_model() {
-	local val
-	val=$(assayer_config_get '.evaluation.model')
-	printf '%s' "${val:-claude-haiku-4-5-20251001}"
+assayer_config_get_json() {
+	local path="$1"
+	config_get_json "_assayer_CONFIG" "${path}"
 }
 
-assayer_config_timeout() {
-	local val
-	val=$(assayer_config_get '.evaluation.timeout_seconds')
-	printf '%s' "${val:-60}"
+assayer_config_model() {
+	local v
+	v=$(assayer_config_get '.assayer.evaluation.model')
+	printf '%s' "${v:-claude-haiku-4-5-20251001}"
 }
 
 assayer_config_max_claims() {
-	local val
-	val=$(assayer_config_get '.max_claims')
-	printf '%s' "${val:-12}"
+	local v
+	v=$(assayer_config_get '.assayer.max_claims')
+	printf '%s' "${v:-12}"
 }
 
 assayer_config_min_confidence() {
-	local val
-	val=$(assayer_config_get '.min_confidence')
-	printf '%s' "${val:-0.5}"
+	local v
+	v=$(assayer_config_get '.assayer.min_confidence')
+	printf '%s' "${v:-0.5}"
 }
 
-assayer_config_final_message_chars() {
-	local val
-	val=$(assayer_config_get '.final_message_chars')
-	printf '%s' "${val:-6000}"
+assayer_config_timeout() {
+	local v
+	v=$(assayer_config_get '.assayer.evaluation.timeout_seconds')
+	printf '%s' "${v:-60}"
 }

package/plugins/cartographer/scripts/lib/cartographer-config.sh

@@ -1,54 +1,36 @@
 #!/usr/bin/env bash
 # cartographer-config.sh — load and query Cartographer configuration.
 #
-# Merges three layers in precedence order (later wins):
+# Uses the shared config loader from ecosystem. Merges five layers in precedence order:
 #   1. plugins/cartographer/config.json  (plugin defaults)
 #   2. ~/.claude/settings.json           (.cartographer subtree)
-#   3. <repo>/.claude/settings.json      (.cartographer subtree)
+#   3. ~/.claude/settings.local.json     (.cartographer subtree, local overrides user)
+#   4. <repo>/.claude/settings.json      (.cartographer subtree)
+#   5. <repo>/.claude/settings.local.json (.cartographer subtree, local overrides project)
 #
 # Usage:
 #   cartographer_config_load <repo_root>
 #   cartographer_config_get_json ".cartographer.exclude_paths"
 
+# shellcheck source=../../../scripts/lib/config-loader.sh
+source "${PLUGIN_ROOT}/../../scripts/lib/config-loader.sh"
+
 _CARTOGRAPHER_CONFIG=""
-_CARTOGRAPHER_PLUGIN_CONFIG=""
 
 cartographer_config_load() {
 	local repo_root="${1:-}"
-	local plugin_dir
-	plugin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-	local plugin_config="$plugin_dir/config.json"
-
-	_CARTOGRAPHER_PLUGIN_CONFIG="{}"
-	if [[ -f "$plugin_config" ]]; then
-		_CARTOGRAPHER_PLUGIN_CONFIG=$(cat "$plugin_config")
-	fi
-
-	local home_settings="{}"
-	if [[ -f "$HOME/.claude/settings.json" ]]; then
-		home_settings=$(cat "$HOME/.claude/settings.json")
-	fi
-
-	local repo_settings="{}"
-	if [[ -n "$repo_root" && -f "$repo_root/.claude/settings.json" ]]; then
-		repo_settings=$(cat "$repo_root/.claude/settings.json")
-	fi
-
-	_CARTOGRAPHER_CONFIG=$(jq -n \
-		--argjson plugin "$_CARTOGRAPHER_PLUGIN_CONFIG" \
-		--argjson home "$home_settings" \
-		--argjson repo "$repo_settings" \
-		'$plugin * {"cartographer": (($plugin.cartographer // {}) * ($home.cartographer // {}) * ($repo.cartographer // {}))}')
+	config_load_plugin "cartographer" "$repo_root" "_CARTOGRAPHER_CONFIG"
+	return 0
 }
 
 cartographer_config_get() {
 	local path="${1:-}"
-	printf '%s' "$_CARTOGRAPHER_CONFIG" | jq -r "$path // empty" 2>/dev/null
+	config_get "_CARTOGRAPHER_CONFIG" "${path}"
 }
 
 cartographer_config_get_json() {
 	local path="${1:-}"
-	printf '%s' "$_CARTOGRAPHER_CONFIG" | jq -c "$path // empty" 2>/dev/null
+	config_get_json "_CARTOGRAPHER_CONFIG" "${path}"
 }
 
 cartographer_config_model_extraction() {

package/plugins/compass/scripts/lib/compass-config.sh

@@ -1,65 +1,35 @@
 #!/usr/bin/env bash
-# Config resolution for Compass.
+# Config resolution for compass.
 #
-# Reads three layers, latest wins:
+# Uses the shared config loader from ecosystem. Reads five layers, latest wins:
 #   1. plugins/compass/config.json (defaults shipped with the plugin)
 #   2. ~/.claude/settings.json
-#   3. <repo>/.claude/settings.json
+#   3. ~/.claude/settings.local.json (local overrides user)
+#   4. <repo>/.claude/settings.json
+#   5. <repo>/.claude/settings.local.json (local overrides project)
 #
 # Exposes:
-#   compass_config_load <repo_root>     # populates _COMPASS_CONFIG (JSON)
-#   compass_config_get <jq-path>        # echoes string value (empty if unset)
-#   compass_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   compass_config_load <repo_root>    # populates _compass_CONFIG (JSON)
+#   compass_config_get <jq-path>       # echoes string value (empty if unset)
+#   compass_config_get_json <jq-path>  # echoes JSON value (null if unset)
 
-_COMPASS_CONFIG="{}"
+# shellcheck source=../../../scripts/lib/config-loader.sh
+source "${PLUGIN_ROOT}/../../scripts/lib/config-loader.sh"
+
+_compass_CONFIG="{}"
 
 compass_config_load() {
 	local repo_root="${1:-}"
-	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
-	local home_dir="${HOME:-}"
-
-	local merged="{}"
-	local file
-
-	file="${plugin_root}/config.json"
-	if [[ -f "$file" ]]; then
-		local defaults
-		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
-		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
-			|| merged="$defaults"
-	fi
-
-	local repo_settings=""
-	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
-
-	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
-		[[ -n "$file" && -f "$file" ]] || continue
-		local overlay
-		overlay=$(jq '{ compass: (.compass // {}) }' "$file" 2>/dev/null) || continue
-		[[ -z "$overlay" ]] && continue
-		local attempt
-		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
-			def deepmerge($a; $b):
-				if ($a|type) == "object" and ($b|type) == "object" then
-					reduce (($a|keys) + ($b|keys) | unique)[] as $k
-						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
-				elif $b == null then $a
-				else $b end;
-			deepmerge($a; $b)
-		' 2>/dev/null) && [[ -n "$attempt" ]]; then
-			merged="$attempt"
-		fi
-	done
-
-	_COMPASS_CONFIG="$merged"
+	config_load_plugin "compass" "$repo_root" "_compass_CONFIG"
+	return 0
 }
 
 compass_config_get() {
 	local path="$1"
-	printf '%s' "$_COMPASS_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+	config_get "_compass_CONFIG" "${path}"
 }
 
 compass_config_get_json() {
 	local path="$1"
-	printf '%s' "$_COMPASS_CONFIG" | jq -c "${path}" 2>/dev/null
+	config_get_json "_compass_CONFIG" "${path}"
 }