@onlooker-community/ecosystem 0.19.0 → 0.21.0

package/plugins/curator/docs/design.md

@@ -0,0 +1,311 @@
+# Curator — Plugin Design
+
+**Plugin name:** `curator`
+**Tagline:** *Tends the memory garden.*
+**Status:** Design (pre-implementation)
+
+Curator is the maintenance layer for the user's typed memory store. It runs cheap heuristic checks at every `SessionStart` and an LLM-backed conflict sweep at most weekly, surfaces stale references, decayed dates, and contradicting entries, and proposes prunes for user review. It does not edit the memory store directly — the same posture librarian and cartographer adopt for durable substrates.
+
+It sits in the [memory architecture](../../../docs/memory-architecture.md) downstream of librarian: librarian writes (with user confirmation); curator audits. Curator is parallel to cartographer: same shape (audit, propose, surface), different substrate. Cartographer audits hand-maintained instruction files (CLAUDE.md, AGENTS.md, `.claude/rules/`); curator audits the typed auto-memory store at `~/.claude/projects/<encoded-project>/memory/`.
+
+---
+
+## Failure Modes Curator Addresses
+
+**A — Decayed date references.** A project memory says "merge freeze begins 2026-03-05 for mobile release cut." After March 5 passes, the memory is at best uninformative and at worst misleading (the model continues to flag work as freeze-sensitive). Curator detects past-tense date markers and proposes removal or refactor.
+
+**B — Stale path references.** A reference memory says "see `scripts/legacy_ingest.py` for the old pipeline shape." The file has since been deleted. The memory now points to nothing. Curator validates path references on a periodic sweep and flags broken ones.
+
+**C — Contradicting memories.** A user memory says "prefer functional patterns" and a feedback memory says "yes, the class-based approach was right for this hot path." Both are true in their original contexts. The model has to reconcile them at runtime, often badly. Curator's LLM-backed sweep finds high-similarity, opposing-sentiment pairs and surfaces the contradiction for human disambiguation.
+
+**D — Unused memories (weakest signal).** A memory has been in the store for 90 days and has never been surfaced as relevant in any session (signal: no `memory.recalled` event references it). It might be load-bearing as a backstop, or it might be dead weight. Curator flags but does not propose removal — the signal is too noisy for action.
+
+**E — Type drift.** A `project` memory ("we're rewriting auth for compliance") becomes a `feedback` memory ("this directory looks weird because of legal review") once the rewrite is done. The original type still fits but a better type now exists. Curator can detect type-drift candidates but the action (re-classification) is necessarily manual.
+
+---
+
+## Architecture
+
+```
+SessionStart hook fires
+        │
+        ▼
+┌──────────────────────┐
+│   Rate Gate          │  cheap checks: every session
+│                      │  LLM checks: once per llm_sweep_interval_days
+└─────────┬────────────┘
+          │
+          ▼
+┌──────────────────────┐
+│  Memory Reader       │  reads MEMORY.md + *.md files from memory store
+│                      │  parses frontmatter (name, description, type)
+└─────────┬────────────┘
+          │
+          ▼ (cheap sweep, every session)
+┌──────────────────────┐
+│  Date Checker        │  parse dates from bodies; flag past-tense markers
+└─────────┬────────────┘
+          │
+          ▼
+┌──────────────────────┐
+│  Reference Checker   │  validate path refs (file exists), symbol refs
+│                      │  (rg the symbol; warn on zero matches), URL refs
+│                      │  (HEAD with budget; skipped without consent)
+└─────────┬────────────┘
+          │
+          ▼
+┌──────────────────────┐
+│  Usage Tracker       │  read JSONL log; correlate memory IDs with
+│                      │  memory.recalled events from N days
+└─────────┬────────────┘
+          │
+          ▼ (LLM sweep, if interval elapsed)
+┌──────────────────────┐
+│  Similarity Matrix   │  Jaccard on token sets; pairs with sim > threshold
+│                      │  → LLM contradiction check
+└─────────┬────────────┘
+          │
+          ▼
+┌──────────────────────┐
+│  Findings Store      │  ~/.onlooker/curator/<key>/findings/<ulid>.json
+└─────────┬────────────┘
+          │ at SessionStart
+          ▼
+┌──────────────────────┐
+│ Surfacer             │  "Curator: 2 stale, 1 contradicting findings."
+│                      │  Review via /curator review.
+└──────────────────────┘
+```
+
+### Rate Gate
+
+Three categories of check, three cadences:
+
+- **Cheap checks (date, reference, usage):** run every `SessionStart`. Combined wall-clock budget: ≤500ms. Above that, curator emits `curator.scan.skipped` with `reason: "over_budget"` and defers.
+- **LLM contradiction sweep:** runs at most once per `llm_sweep_interval_days` (default: 7) per project. Watermark stored at `~/.onlooker/curator/<project-key>/last_llm_sweep.json`.
+- **Manual sweep:** `/curator scan` forces a full sweep including the LLM pass, ignoring rate gates.
+
+The rate gate exists because curator runs on every session start, and a quadratic LLM pass on a growing memory store is the worst kind of background cost: invisible, recurring, and proportional to user investment.
+
+### Memory Reader
+
+Parses the typed memory store:
+
+1. Reads `~/.claude/projects/<encoded-project>/memory/MEMORY.md` for the index entries.
+2. For each line of the form `- [Title](file.md) — hook`, resolves `file.md` against the memory dir.
+3. Reads each referenced file. Parses YAML frontmatter (`name`, `description`, `type`). The body after frontmatter is the memory content.
+4. If a file is referenced from `MEMORY.md` but does not exist, that itself is a `findings.broken_index` — surfaced immediately.
+5. If a file exists in the memory dir but is not referenced from `MEMORY.md`, that is `findings.orphaned_memory` — also surfaced.
+
+### Date Checker
+
+For each memory body, scans for date patterns and absolute references:
+
+- **ISO-8601 dates** (`2026-03-05`, `2026-03-05T10:00:00Z`).
+- **Quarter markers** (`Q1 2026`, `2026Q3`).
+- **Named deadlines** with absolute dates nearby (`freeze`, `deadline`, `release cut`, `migration`, `cutover`, `EOL`, `expires`).
+- **Relative-to-write markers** when the frontmatter has a discoverable write date (`promoted_at`, `created_at`): phrases like "next week", "by end of month", "this Friday" relative to that date.
+
+For each match, compares to today's date. If a date is more than `date_grace_period_days` (default: 14) in the past, emits `curator.finding.date_decayed` with the matched phrase and the gap in days.
+
+The check does not propose removal automatically — past dates often have lingering relevance ("freeze on 2026-03-05" might still document why a code shape is the way it is). The user decides whether to remove, refactor, or keep.
+
+### Reference Checker
+
+For each memory body, scans for two kinds of references:
+
+1. **Path references.** Patterns matching `path/to/file.ext` heuristics. For each candidate path, resolves against the repo root (from `git rev-parse --show-toplevel`). If the path does not exist, emits `curator.finding.path_broken` with the memory file and the broken path.
+2. **Symbol references.** Heuristic: backtick-wrapped identifiers (`` `myFunction` ``, `` `MyClass` ``) that look like code identifiers (CamelCase or snake_case with no spaces, length ≥ 3). For each, runs `rg --type-add 'all:*' --type all -F 'identifier'` in the repo root. If zero matches, emits `curator.finding.symbol_missing`.
+3. **URL references.** Optional, disabled by default. When `check_urls: true` and the URL host is not in `url_allowlist`, curator emits `curator.finding.url_unchecked` (a record that the memory contains an external URL it cannot validate without network). URLs in the allowlist (and only those) are HEAD-checked under a wall-clock budget.
+
+The reference checker treats matches as evidence of liveness, not correctness. A symbol that grep-matches might still be the wrong symbol; a path that resolves might point to renamed content. The checker is a smoke alarm, not a smoke detector.
+
+### Usage Tracker
+
+Reads `~/.onlooker/logs/onlooker-events.jsonl` (rate-limited; the tail is enough for usage windows) for events of type `memory.recalled` and `memory.referenced` over the last `usage_window_days` (default: 30). For each memory file, computes recall count.
+
+The Onlooker event log does not yet emit `memory.recalled` events. Adding that emitter belongs to the ecosystem substrate (so all plugins benefit), not to curator. Until it ships, the usage tracker emits `curator.finding.unused_undetectable` once per scan and skips the rest of the pass. This is recorded as a hard dependency in [Open Questions #1](#open-questions).
+
+When the emitter ships: memories with zero recalls in the window are flagged `curator.finding.unused_low_signal`. The finding is informational only — the design does not propose removal based on usage alone, because the recall signal is itself noisy (the model may not surface a memory it should have, and a recalled memory may have been irrelevant).
+
+### Similarity Matrix and Contradiction Check (LLM sweep)
+
+Run at most once per `llm_sweep_interval_days`:
+
+1. Compute pairwise Jaccard similarity over normalized token sets (lowercased, stopwords removed, top-K tokens per body).
+2. Filter to pairs where similarity ≥ `contradiction_similarity_threshold` (default: 0.4) and where the two memories have at least one opposing sentiment marker (one contains `always`/`prefer`/`do` and the other contains `never`/`avoid`/`don't`).
+3. For each surviving pair, call Haiku with both memory bodies and ask:
+
+```
+You are evaluating whether two memory entries contradict each other in practice.
+
+Two memories CONTRADICT when applying both leads to inconsistent action.
+Two memories COMPLEMENT when they apply in different contexts and a careful reader
+   can follow both.
+Two memories are REDUNDANT when one strictly subsumes the other.
+
+RULES:
+- Output only: {"verdict": "<contradict|complement|redundant|unrelated>",
+                "rationale": "<≤30 words>"}
+
+<memory_a>
+title: {{TITLE_A}}
+body: {{BODY_A}}
+</memory_a>
+
+<memory_b>
+title: {{TITLE_B}}
+body: {{BODY_B}}
+</memory_b>
+```
+
+Model: `claude-haiku-4-5-20251001`. Temperature 0.2. Max output tokens: 96.
+
+`contradict` verdicts become `curator.finding.contradiction`. `redundant` verdicts become `curator.finding.redundant_pair`. `complement` and `unrelated` are logged but not surfaced.
+
+### Findings Store and Surfacer
+
+Each finding is written to `~/.onlooker/curator/<project-key>/findings/<ulid>.json`:
+
+```json
+{
+  "id": "01J...",
+  "kind": "date_decayed | path_broken | symbol_missing | url_unchecked | unused_low_signal | contradiction | redundant_pair | broken_index | orphaned_memory",
+  "memory_files": ["feedback_no_trailing_summaries.md"],
+  "detail": { ... kind-specific ... },
+  "created_at": "2026-06-02T18:24:11Z",
+  "deduped_hash": "...",
+  "status": "open | acknowledged | resolved"
+}
+```
+
+The `deduped_hash` prevents the same finding from being re-emitted every session. Same shape as cartographer's `payload.finding_hash`.
+
+At `SessionStart`, curator counts open findings by kind and emits a one-line `additionalContext` pointer:
+
+> Curator: 1 contradiction, 2 path-broken, 1 date-decayed. Review with `/curator review`.
+
+The pointer caps the inject at one line; findings details live in the skill, not in context.
+
+---
+
+## Integration Points
+
+**Librarian.** Curator uses the `source: "librarian"` provenance to apply different staleness criteria to librarian-promoted memories vs. hand-written ones (open question — current default treats them identically).
+
+**Cartographer.** Same shape; different substrate. They can run independently. Curator's findings format intentionally mirrors cartographer's so a future unified findings dashboard can render both.
+
+**Ecosystem substrate.** Curator depends on a `memory.recalled` / `memory.referenced` event emitter that does not yet exist. Until it ships, the usage tracker is dormant.
+
+**Counsel.** Counsel reads curator's findings as part of the weekly observability brief; curator does not need to know about counsel.
+
+**Historian.** Independent. Curator audits the distilled memory store; historian operates on the transcript embeddings. A path that's stale in a memory is not made fresh by being in a transcript.
+
+---
+
+## Configuration (`config.json`)
+
+```json
+{
+  "plugin_name": "curator",
+  "storage_path": "${ONLOOKER_DIR:-$HOME/.onlooker}",
+  "curator": {
+    "enabled": false,
+    "memory_store_path": "${HOME}/.claude/projects/${CLAUDE_PROJECT_ENCODED}/memory",
+    "cheap_checks": {
+      "enabled": true,
+      "wall_clock_budget_ms": 500,
+      "skip_if_session_age_under_seconds": 5
+    },
+    "date_check": {
+      "enabled": true,
+      "date_grace_period_days": 14
+    },
+    "reference_check": {
+      "enabled": true,
+      "check_urls": false,
+      "url_allowlist": []
+    },
+    "usage_tracker": {
+      "enabled": true,
+      "usage_window_days": 30
+    },
+    "llm_sweep": {
+      "enabled": true,
+      "model": "claude-haiku-4-5-20251001",
+      "temperature": 0.2,
+      "max_output_tokens": 96,
+      "interval_days": 7,
+      "max_pair_evaluations_per_sweep": 50,
+      "contradiction_similarity_threshold": 0.40
+    },
+    "surfacer": {
+      "max_pointer_chars": 200,
+      "skip_when_zero": true
+    }
+  }
+}
+```
+
+`skip_if_session_age_under_seconds` exists because a session start followed quickly by another session start (compaction, restart) shouldn't re-run the cheap checks.
+
+---
+
+## Events
+
+| Event | Trigger | Key payload fields |
+|---|---|---|
+| `curator.scan.started` | Scan run begins | `mode: cheap\|llm\|manual`, `findings_open_before` |
+| `curator.scan.completed` | Scan run ends | `findings_new`, `findings_resolved`, `duration_ms` |
+| `curator.scan.skipped` | Skipped by rate gate | `reason: over_budget\|llm_interval_not_elapsed\|disabled` |
+| `curator.finding.date_decayed` | A dated phrase is past the grace period | `memory_file`, `matched_phrase`, `days_past` |
+| `curator.finding.path_broken` | Path reference does not resolve | `memory_file`, `broken_path` |
+| `curator.finding.symbol_missing` | Backticked identifier returns zero rg matches | `memory_file`, `symbol` |
+| `curator.finding.url_unchecked` | URL present, host not in allowlist | `memory_file`, `url_host` |
+| `curator.finding.unused_low_signal` | Zero recalls in window (when emitter exists) | `memory_file`, `window_days` |
+| `curator.finding.unused_undetectable` | Usage emitter not present | `note: "memory.recalled events not implemented"` |
+| `curator.finding.contradiction` | LLM verdict `contradict` | `memory_a`, `memory_b`, `rationale` |
+| `curator.finding.redundant_pair` | LLM verdict `redundant` | `memory_a`, `memory_b`, `rationale` |
+| `curator.finding.broken_index` | MEMORY.md references missing file | `referenced_file` |
+| `curator.finding.orphaned_memory` | Memory file not referenced from MEMORY.md | `memory_file` |
+| `curator.finding.acknowledged` | User acknowledged finding via skill (no action taken) | `finding_id` |
+| `curator.finding.resolved` | User resolved finding via skill (action taken) | `finding_id`, `action: prune\|edit\|reclassify\|defer` |
+
+---
+
+## Skills
+
+**`/curator review`** — interactive walkthrough of open findings. For each: shows the memory body excerpt, the finding kind and detail, and offers prune / edit / reclassify / acknowledge / defer.
+
+**`/curator scan`** — forces a full sweep including the LLM pass. Ignores rate gates.
+
+**`/curator calibrate`** — runs the LLM sweep against the current memory store and reports precision against a labeled set (which the user maintains in `~/.onlooker/curator/<project-key>/calibration_labels.json`). Useful for tuning `contradiction_similarity_threshold`.
+
+---
+
+## Open Questions
+
+1. **`memory.recalled` event dependency.** The usage tracker requires an event emitter in the ecosystem substrate that does not yet exist. The substrate change is small (`UserPromptExpansion` hook can emit an event each time a memory is reinjected) but it is a prerequisite. Until then, the usage signal is dormant — `curator.finding.unused_undetectable` is emitted once per scan to make the missing capability visible.
+
+2. **Librarian-promoted vs. hand-written staleness.** A librarian-promoted memory was distilled from a session; its staleness criteria might be "the source session is older than X." A hand-written memory has no equivalent decay marker. The current design treats them identically; the provenance field is captured but not yet used differently.
+
+3. **LLM sweep cost growth.** Pairwise contradiction checks are O(N²) on pair candidates. At 100 memories with similarity-filtering, the sweep is typically under 10 LLM calls; at 500 memories the worst case approaches the `max_pair_evaluations_per_sweep` cap. A smarter pre-filter (e.g., embedding-based clustering to limit pair candidates) becomes worthwhile around 200 memories.
+
+4. **Finding dedup vs. re-evaluation.** A `date_decayed` finding for `2026-03-05` is the same fact every session — `deduped_hash` prevents re-emission. But a `contradiction` finding between two memories may be re-evaluated if either memory's body changes; the dedup hash should include both bodies' hashes, not just memory IDs.
+
+5. **Auto-prune as a future opt-in.** Like librarian's `auto_promote`, curator could grow an `auto_prune` mode for high-confidence findings (e.g., `path_broken` with no possible interpretation). Deferred until the cheap-check precision is measured in practice.
+
+6. **Type-drift detection.** Mentioned as failure mode E but not addressed by the current checks. Would require an LLM call per memory: "given this body, what type fits best?" — too expensive for every session, plausible for the weekly sweep.
+
+7. **Interaction with `~/.claude/CLAUDE.md`.** Global instructions in `~/.claude/CLAUDE.md` shape behavior but live outside the typed memory store. Curator does not audit them — cartographer does. If the boundary moves (e.g., librarian gains the ability to propose `~/.claude/CLAUDE.md` edits), curator and cartographer will need a shared rule for which substrate owns which file.
+
+---
+
+## Non-Goals
+
+- Does not edit the memory store automatically — same posture as librarian and cartographer.
+- Does not write new memories — that is librarian's job.
+- Does not perform retrieval — the typed memory store reinjection mechanism is owned elsewhere.
+- Does not audit instruction files (CLAUDE.md, AGENTS.md, `.claude/rules/`) — that is cartographer's job.
+- Does not synthesize cross-session improvement briefs — that is counsel's job.
+- Does not block any tool call — curator's surfacer is informational only.

package/plugins/curator/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/curator-session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/curator/scripts/hooks/curator-session-start.sh

@@ -0,0 +1,343 @@
+#!/usr/bin/env bash
+# Curator SessionStart hook.
+#
+# Runs cheap-tier checks against the typed memory store and emits findings
+# under ~/.onlooker/curator/<project-key>/findings/. Surfaces a one-line
+# pointer to /curator review when open findings exist.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits valid hookSpecificOutput JSON even when nothing to inject.
+#   - No-ops when curator.enabled is not true.
+#   - No-ops when no git context, no memory store path, or no checks pass
+#     the rate gate.
+#
+# LLM contradiction sweep is deferred to a follow-up commit.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+fi
+
+# shellcheck source=../lib/curator-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-config.sh"
+# shellcheck source=../lib/curator-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-project-key.sh"
+# shellcheck source=../lib/curator-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-ulid.sh"
+# shellcheck source=../lib/curator-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-storage.sh"
+# shellcheck source=../lib/curator-emit.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-emit.sh"
+# shellcheck source=../lib/curator-memory-reader.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-memory-reader.sh"
+# shellcheck source=../lib/curator-checks.sh
+source "${PLUGIN_ROOT}/scripts/lib/curator-checks.sh"
+
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '{
+		hookSpecificOutput: {
+			hookEventName: "SessionStart",
+			additionalContext: $ctx
+		}
+	}'
+}
+
+INPUT=$(cat 2>/dev/null || true)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+REPO_ROOT=$(curator_project_repo_root "$CWD")
+curator_config_load "$REPO_ROOT"
+
+if ! curator_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+PROJECT_KEY=$(curator_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+curator_storage_init "$PROJECT_KEY" || { _emit ""; exit 0; }
+REMOTE_URL=$(curator_project_remote_url "$CWD")
+curator_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+# ----------------------------------------------------------------------------
+# Resolve the typed memory store path. Skip the audit if it can't be resolved.
+# ----------------------------------------------------------------------------
+
+MEM_PATH_TEMPLATE=$(curator_config_get '.curator.memory_store_path')
+if [[ -z "$MEM_PATH_TEMPLATE" || "$MEM_PATH_TEMPLATE" == "null" ]]; then
+	MEM_PATH_TEMPLATE='${HOME}/.claude/projects/${CLAUDE_PROJECT_ENCODED}/memory'
+fi
+MEM_DIR=$(curator_memory_resolve_path "$MEM_PATH_TEMPLATE")
+
+if [[ -z "$MEM_DIR" || ! -d "$MEM_DIR" ]]; then
+	# No memory store, nothing to audit. Still emit a scan event so the
+	# observability stream shows curator ran.
+	curator_emit "curator.scan.started" "$SESSION_ID" "$(jq -cn '{ mode: "cheap" }')"
+	curator_emit "curator.scan.complete" "$SESSION_ID" "$(jq -cn '{
+		mode: "cheap", outcome: "ok",
+		findings_new: 0, findings_resolved: 0, duration_ms: 0
+	}')"
+	_emit ""
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Cheap-tier rate gate.
+#
+# Three knobs:
+#   cheap_checks.enabled            global on/off for the cheap tier
+#   cheap_checks.wall_clock_budget_ms   abort phases past this elapsed
+#   surfacer.max_pointer_chars      truncate additionalContext at this
+# ----------------------------------------------------------------------------
+
+CHEAP_ENABLED=$(curator_config_get '.curator.cheap_checks.enabled')
+SCAN_START_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| SCAN_START_MS=$(($(date +%s) * 1000))
+SCAN_START_S=$((SCAN_START_MS / 1000))
+
+curator_emit "curator.scan.started" "$SESSION_ID" "$(jq -cn '{ mode: "cheap" }')"
+
+if [[ "$CHEAP_ENABLED" == "false" ]]; then
+	# Cheap tier explicitly off — emit scan.complete with skip_reason
+	# and skip straight to the surfacer (which reads previously-persisted
+	# findings, if any).
+	curator_emit "curator.scan.complete" "$SESSION_ID" "$(jq -cn \
+		--arg mode "cheap" --arg outcome "skipped" \
+		--arg skip_reason "disabled" \
+		--argjson findings_new 0 --argjson findings_resolved 0 \
+		--argjson duration_ms 0 \
+		'{ mode: $mode, outcome: $outcome, skip_reason: $skip_reason,
+		   findings_new: $findings_new, findings_resolved: $findings_resolved,
+		   duration_ms: $duration_ms }')"
+	FINDINGS_NEW=0
+	# Skip the per-check pipeline; fall through to the surfacer.
+	OUTCOME_FOR_SCAN_COMPLETE="skipped"
+else
+	OUTCOME_FOR_SCAN_COMPLETE="ok"
+fi
+
+BUDGET_MS=$(curator_config_get '.curator.cheap_checks.wall_clock_budget_ms')
+[[ -z "$BUDGET_MS" || "$BUDGET_MS" == "null" ]] && BUDGET_MS=500
+
+_curator_now_ms() {
+	python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null \
+		|| echo "$(( $(date +%s) * 1000 ))"
+}
+
+_curator_over_budget() {
+	local now elapsed
+	now=$(_curator_now_ms)
+	elapsed=$((now - SCAN_START_MS))
+	(( elapsed > BUDGET_MS ))
+}
+
+# When the cheap tier is enabled, run the four checks under the budget
+# gate. Each phase checks the budget BEFORE its work — partial phases
+# are allowed to finish since check work itself is cheap.
+DATE_FINDINGS='[]'
+PATH_FINDINGS='[]'
+BROKEN_INDEX='[]'
+ORPHANED='[]'
+BUDGET_TRIPPED="false"
+MEMORIES='[]'
+
+if [[ "$CHEAP_ENABLED" != "false" ]]; then
+	if _curator_over_budget; then
+		BUDGET_TRIPPED="true"
+	else
+		MEMORIES=$(curator_memory_load_all "$MEM_DIR")
+	fi
+
+	DATE_GRACE=$(curator_config_get '.curator.date_check.date_grace_period_days')
+	[[ -z "$DATE_GRACE" || "$DATE_GRACE" == "null" ]] && DATE_GRACE=14
+	DATE_CHECK_ENABLED=$(curator_config_get '.curator.date_check.enabled')
+
+	if [[ "$BUDGET_TRIPPED" != "true" && "$DATE_CHECK_ENABLED" != "false" ]]; then
+		if _curator_over_budget; then
+			BUDGET_TRIPPED="true"
+		else
+			DATE_FINDINGS=$(curator_check_dates "$MEMORIES" "$DATE_GRACE") || DATE_FINDINGS='[]'
+		fi
+	fi
+
+	REF_CHECK_ENABLED=$(curator_config_get '.curator.reference_check.enabled')
+	if [[ "$BUDGET_TRIPPED" != "true" && "$REF_CHECK_ENABLED" != "false" && -n "$REPO_ROOT" ]]; then
+		if _curator_over_budget; then
+			BUDGET_TRIPPED="true"
+		else
+			PATH_FINDINGS=$(curator_check_paths "$MEMORIES" "$REPO_ROOT") || PATH_FINDINGS='[]'
+		fi
+	fi
+
+	if [[ "$BUDGET_TRIPPED" != "true" ]]; then
+		if _curator_over_budget; then
+			BUDGET_TRIPPED="true"
+		else
+			BROKEN_INDEX=$(curator_check_broken_index "$MEMORIES")
+			ORPHANED=$(curator_check_orphaned "$MEMORIES")
+		fi
+	fi
+fi
+
+# ----------------------------------------------------------------------------
+# Persist findings (with dedup by deduped_hash) and emit per-finding events.
+# Skipped entirely when the cheap tier is disabled — the disabled path above
+# already emitted scan.complete and set FINDINGS_NEW=0.
+# ----------------------------------------------------------------------------
+
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+[[ "$CHEAP_ENABLED" == "false" ]] || FINDINGS_NEW=0
+
+_write_finding() {
+	local kind="$1"
+	local payload="$2"
+	local hash_input
+	hash_input="${kind}|$(printf '%s' "$payload" | jq -cS '.')"
+	local hash
+	hash=$(curator_finding_hash "$hash_input") || hash=""
+	[[ -z "$hash" ]] && return 0
+
+	# Dedup: skip if an open finding with the same hash already exists.
+	if curator_storage_has_finding_with_hash "$PROJECT_KEY" "$hash"; then
+		return 0
+	fi
+
+	local id record
+	id=$(curator_ulid)
+	record=$(jq -n \
+		--arg id "$id" \
+		--arg kind "$kind" \
+		--arg created_at "$NOW_TS" \
+		--arg deduped_hash "$hash" \
+		--argjson detail "$payload" \
+		'{
+			id: $id, kind: $kind, created_at: $created_at,
+			status: "open", deduped_hash: $deduped_hash, detail: $detail
+		}')
+	curator_storage_write_finding "$PROJECT_KEY" "$id" "$record" >/dev/null || return 0
+	FINDINGS_NEW=$((FINDINGS_NEW + 1))
+
+	# Per-kind event payload.
+	local event_type event_payload
+	event_type="curator.finding.${kind}"
+	event_payload=$(jq -cn --arg fid "$id" --argjson detail "$payload" \
+		'{ finding_id: $fid } + $detail')
+	curator_emit "$event_type" "$SESSION_ID" "$event_payload"
+}
+
+# Convert each finding-array entry into a stored + emitted finding.
+_emit_kind_findings() {
+	local kind="$1" findings_json="$2"
+	local n
+	n=$(printf '%s' "$findings_json" | jq 'length' 2>/dev/null) || n=0
+	local i payload
+	for ((i = 0; i < n; i++)); do
+		payload=$(printf '%s' "$findings_json" | jq -c ".[$i]")
+		[[ -z "$payload" || "$payload" == "null" ]] && continue
+		_write_finding "$kind" "$payload"
+	done
+}
+
+if [[ "$CHEAP_ENABLED" != "false" ]]; then
+	_emit_kind_findings "date_decayed" "$DATE_FINDINGS"
+	_emit_kind_findings "path_broken" "$PATH_FINDINGS"
+	_emit_kind_findings "broken_index" "$BROKEN_INDEX"
+	_emit_kind_findings "orphaned_memory" "$ORPHANED"
+fi
+
+# ----------------------------------------------------------------------------
+# Watermark + scan.complete. The disabled-tier branch above already emitted
+# scan.complete; this branch fires only when the cheap tier ran (success or
+# budget tripped).
+# ----------------------------------------------------------------------------
+
+if [[ "$CHEAP_ENABLED" != "false" ]]; then
+	curator_storage_write_watermark "$(curator_last_cheap_scan_path "$PROJECT_KEY")" || true
+
+	DURATION_MS=$(( $(_curator_now_ms) - SCAN_START_MS ))
+	if [[ "$BUDGET_TRIPPED" == "true" ]]; then
+		curator_emit "curator.scan.complete" "$SESSION_ID" "$(jq -cn \
+			--arg mode "cheap" --arg outcome "skipped" \
+			--arg skip_reason "over_budget" \
+			--argjson findings_new "$FINDINGS_NEW" \
+			--argjson findings_resolved 0 \
+			--argjson duration_ms "$DURATION_MS" \
+			'{ mode: $mode, outcome: $outcome, skip_reason: $skip_reason,
+			   findings_new: $findings_new,
+			   findings_resolved: $findings_resolved,
+			   duration_ms: $duration_ms }')"
+	else
+		curator_emit "curator.scan.complete" "$SESSION_ID" "$(jq -cn \
+			--arg mode "cheap" --arg outcome "ok" \
+			--argjson findings_new "$FINDINGS_NEW" \
+			--argjson findings_resolved 0 \
+			--argjson duration_ms "$DURATION_MS" \
+			'{ mode: $mode, outcome: $outcome,
+			   findings_new: $findings_new,
+			   findings_resolved: $findings_resolved,
+			   duration_ms: $duration_ms }')"
+	fi
+fi
+
+# ----------------------------------------------------------------------------
+# Surfacer.
+# ----------------------------------------------------------------------------
+
+SKIP_WHEN_ZERO=$(curator_config_get '.curator.surfacer.skip_when_zero')
+[[ -z "$SKIP_WHEN_ZERO" || "$SKIP_WHEN_ZERO" == "null" ]] && SKIP_WHEN_ZERO="true"
+
+OPEN_COUNT=$(curator_storage_count_open "$PROJECT_KEY")
+[[ -z "$OPEN_COUNT" || "$OPEN_COUNT" == "null" ]] && OPEN_COUNT=0
+
+if [[ "$OPEN_COUNT" -eq 0 && "$SKIP_WHEN_ZERO" == "true" ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Build a compact "2 path-broken, 1 date-decayed" descriptor for the
+# pointer message.
+COUNTS_BY_KIND=$(curator_storage_open_counts_by_kind "$PROJECT_KEY")
+SUMMARY=$(printf '%s' "$COUNTS_BY_KIND" | jq -r '
+	map( (.count|tostring) + " " + (.kind | gsub("_"; "-")) )
+	| join(", ")
+')
+
+CONTEXT=$(printf 'Curator: %s open finding%s (%s). Review with `/curator review`.' \
+	"$OPEN_COUNT" \
+	"$([ "$OPEN_COUNT" -eq 1 ] && echo "" || echo "s")" \
+	"$SUMMARY")
+
+# Cap the pointer length so a long per-kind summary never overflows the
+# user's SessionStart context.
+MAX_POINTER=$(curator_config_get '.curator.surfacer.max_pointer_chars')
+[[ -z "$MAX_POINTER" || "$MAX_POINTER" == "null" ]] && MAX_POINTER=200
+if [[ "${#CONTEXT}" -gt "$MAX_POINTER" ]]; then
+	# Reserve room for the truncation ellipsis without exceeding the cap.
+	TRUNC=$((MAX_POINTER - 1))
+	(( TRUNC < 1 )) && TRUNC=1
+	CONTEXT="${CONTEXT:0:TRUNC}…"
+fi
+
+_emit "$CONTEXT"
+exit 0