@onlooker-community/ecosystem 0.10.0 → 0.14.0

package/docs/architecture.md

@@ -0,0 +1,117 @@
+# Ecosystem Architecture
+
+This document describes how the Onlooker ecosystem fits together: the shared substrate, the plugin layer, the event bus, and the configuration system.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Claude Code session                                            │
+│                                                                 │
+│  ┌─────────────┐  ┌───────────┐  ┌──────────┐  ┌──────────┐  │
+│  │  ecosystem  │  │ archivist │  │ tribunal │  │   echo   │  │
+│  │  (substrate)│  │  plugin   │  │  plugin  │  │  plugin  │  │
+│  └──────┬──────┘  └─────┬─────┘  └────┬─────┘  └────┬─────┘  │
+│         │               │             │              │         │
+│         └───────────────┴─────────────┴──────────────┘         │
+│                               │                                 │
+│                    ┌──────────▼──────────┐                     │
+│                    │  onlooker-event.mjs  │  schema-validated   │
+│                    │  (canonical emitter) │  event envelope     │
+│                    └──────────┬──────────┘                     │
+│                               │                                 │
+│                    ┌──────────▼──────────┐                     │
+│                    │  ~/.onlooker/logs/  │                     │
+│                    │  onlooker-events    │  append-only JSONL   │
+│                    │  .jsonl             │                     │
+│                    └─────────────────────┘                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## The substrate layer: `ecosystem`
+
+The `ecosystem` plugin (repo root) is not optional — it provides the infrastructure every other plugin builds on:
+
+| Component | What it does |
+|-----------|-------------|
+| `~/.onlooker/` directory | Shared storage root, created by the Onlooker installer. All plugins store artifacts here under their own sub-path. |
+| `scripts/lib/onlooker-event.mjs` | Canonical event builder. Accepts a JSON payload on stdin, validates it against `@onlooker-community/schema`, and prints the validated envelope to stdout. Callers capture the output and append it to the JSONL log. |
+| `scripts/lib/onlooker-schema.sh` | Bash convenience wrapper around `onlooker-event.mjs`. Provides `onlooker_event_from_hook` (builds an envelope via `node`) and `onlooker_append_event` (appends a pre-built envelope to the log). Node is still required. |
+| `scripts/lib/validate-path.sh` | Sets canonical `$ONLOOKER_*` environment variables (log path, tracker dirs, etc.) so every hook uses consistent paths. |
+| Session trackers | `SessionStart`, `SessionEnd`, `PreCompact`, `PostCompact`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, and `WorktreeRemove` hooks that emit `session.*`, `tool.*`, `turn.*` events for the observability layer. |
+| Prompt rules | `UserPromptSubmit` hook that injects declarative guidance on regex match. |
+
+## The plugin layer
+
+Plugins are independent packages under `plugins/<name>/`. Each has its own:
+- `config.json` — defaults for all knobs.
+- `hooks.json` — declares which Claude Code hook events to subscribe to.
+- `.claude-plugin/plugin.json` — marketplace manifest (name, version, description, agents, skills).
+- `CHANGELOG.md` + release-please track — versioned independently of the ecosystem.
+
+Plugins communicate by **emitting events**, not by calling each other directly. An Echo evaluation and a Tribunal jury run both write to the same JSONL log; a dashboard or downstream consumer can query across both.
+
+### Plugin dependency model
+
+All plugins depend on `ecosystem`. No plugin depends on another plugin at runtime. This means:
+- Tribunal does not require Archivist to be installed.
+- Echo does not require Tribunal to be installed (despite evaluating similar things — see [Echo ADR-002](../plugins/echo/docs/adr/002-direct-evaluation-vs-tribunal-pipeline.md)).
+- You can install any subset of plugins and the others still work.
+
+## The event bus
+
+Every observable event flows through `onlooker-event.mjs` before being written to disk. The emitter:
+
+1. Wraps the plugin-supplied payload in a canonical envelope:
+   ```json
+   {
+     "id": "01J...",
+     "plugin": "echo",
+     "session_id": "...",
+     "event_type": "echo.suite.complete",
+     "timestamp": "2026-05-24T...",
+     "schema_version": "2.2.0",
+     "payload": { ... }
+   }
+   ```
+2. Validates the envelope and payload against [`@onlooker-community/schema`](https://github.com/onlooker-community/schema). If validation fails, the node process exits non-zero and prints to stderr; most hooks treat empty output as a skip rather than a hard error, so some validation failures may be silent unless the caller explicitly checks exit status.
+3. Prints the validated envelope to stdout. The calling bash function (`onlooker_append_event`) captures this and appends it as a single JSON line to `~/.onlooker/logs/onlooker-events.jsonl`.
+
+The schema is versioned independently and published to npm. Plugin shell scripts invoke `onlooker-event.mjs` at runtime so schema validation always reflects the installed version.
+
+> **Note:** Not all events in the JSONL log are schema-validated. `prompt_rule.*` events are currently emitted outside the canonical schema pipeline (the event types are not yet defined in `@onlooker-community/schema`). Schema-first emission is the goal for all future event types.
+
+## Project keying
+
+Every plugin that stores per-project artifacts uses the same key derivation:
+
+```
+key = first 12 hex chars of SHA256(git remote get-url origin)
+```
+
+If no remote exists (local-only repo), the key falls back to `SHA256(realpath of git toplevel)`.
+
+This means:
+- Two clones of the same repo share the same key and therefore the same baselines, memories, and Tribunal history.
+- Git worktrees of the same repo also share the key.
+- Moving the repo directory does not change the key (remote URL is stable).
+
+## Configuration system
+
+Each plugin reads config in two steps:
+
+1. **Plugin defaults** — `plugins/<name>/config.json`. Ships with the plugin; defines all available knobs and their defaults.
+2. **Settings overlay** — `.claude/settings.json` (repo-level) or `~/.claude/settings.json` (global). The plugin-specific key (e.g., `echo`, `tribunal`) is merged onto the defaults.
+
+Tribunal and Archivist use a recursive `deepmerge` so nested keys can be overridden individually without replacing an entire sub-object. Echo uses a simpler per-key lookup against the flat settings block. Repo-level settings take precedence over global; both override plugin defaults. This lets you:
+- Enable a plugin for a specific project without touching your global config.
+- Override the evaluation model for a high-stakes repo without affecting others.
+
+## Architecture decisions
+
+Ecosystem-level decisions are recorded in [`docs/adr/`](adr/):
+
+- [ADR-001](adr/001-claude-code-hooks-as-integration-surface.md) — Claude Code hooks as the integration surface
+- [ADR-002](adr/002-centralized-jsonl-event-log.md) — Centralized JSONL event log with schema validation
+- [ADR-003](adr/003-ulid-over-uuid.md) — ULID for all identifiers
+- [ADR-004](adr/004-plugin-config-with-settings-overlay.md) — Per-plugin config with settings.json overlay

package/hooks/hooks.json

@@ -50,6 +50,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-duration-tracker.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/prompt-rule-injector.sh"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.10.0",
+  "version": "0.14.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -19,19 +19,25 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^1.4.1"
+    "@onlooker-community/schema": "^2.2.0"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
     "test": "npm run test:bats && npm run test:schema",
     "test:bats": "bats test/bats",
     "test:schema": "node --test test/node/*.test.mjs",
-    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh",
-    "test:ci": "npm run test:shellcheck && npm run test:bats && npm run test:schema && npm run lint:check",
-    "lint:check": "biome check . && markdownlint '**/*.md' --ignore node_modules --ignore CHANGELOG.md",
-    "lint": "biome lint --write",
-    "format": "biome format --write",
+    "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",
+    "lint:references": "node scripts/lint/check-references.mjs",
+    "lint:manifests": "node scripts/lint/check-manifests.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",
+    "lint:check": "biome check . && markdownlint '**/*.md'",
+    "lint": "biome lint --write && markdownlint --fix '**/*.md'",
+    "format": "biome format --write && markdownlint --fix '**/*.md'",
     "format:check": "biome format",
+    "format:md": "markdownlint --fix '**/*.md'",
     "biome:ci": "biome ci"
   },
   "engines": {

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

@@ -0,0 +1,14 @@
+{
+  "name": "archivist",
+  "version": "0.1.0",
+  "description": "Structured session memory across context truncation: extracts decisions, dead ends, and open questions on PreCompact and reinjects the most important items at SessionStart. Builds on the Onlooker ecosystem plugin.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": [],
+  "agents": []
+}

package/plugins/archivist/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/archivist-v0.0.1...archivist-v0.1.0) (2026-05-23)
+
+
+### Features
+
+* **archivist:** introduce structured session memory plugin :rocket: ([378fff3](https://github.com/onlooker-community/ecosystem/commit/378fff3c14b40644af45b1a2335992e7b0428160))

package/plugins/archivist/README.md

@@ -0,0 +1,105 @@
+# Archivist
+
+Structured session memory across context truncation.
+
+When Claude Code compacts a long conversation, Archivist extracts the decisions made, dead ends hit, and open questions raised — then reinjects the most relevant items at the start of the next session. Context windows are finite; important context shouldn't be.
+
+Archivist is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | What Archivist does |
+|------|---------------------|
+| `PreCompact` | Reads the transcript tail, calls `claude -p` with a structured-extraction prompt, validates referenced file paths against the current repo, and writes ULID-keyed JSON artifacts under `~/.onlooker/archivist/<project-key>/`. |
+| `SessionStart` | Loads artifacts for the current project key, ranks them (pinned first, then recency), and emits them as invisible `additionalContext` within a token budget. |
+
+## Activation
+
+Archivist is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "archivist": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "archivist": {
+    "enabled": false,
+    "extraction": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 1500,
+      "transcript_tail_chars": 60000
+    },
+    "injection": {
+      "max_items": 8,
+      "max_chars": 2400,
+      "include_open_questions": true,
+      "include_dead_ends": true
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any extraction or injection to run. |
+| `extraction.model` | `claude-haiku-4-5-20251001` | Model used for transcript extraction. Haiku is fast and cheap; the extraction prompt is structured and does not require deep reasoning. |
+| `extraction.max_output_tokens` | `1500` | Token ceiling for the extraction response. |
+| `extraction.transcript_tail_chars` | `60000` | How many characters of the transcript tail to feed into extraction. Larger values capture more context at higher cost. |
+| `injection.max_items` | `8` | Maximum number of artifacts to inject at `SessionStart`. |
+| `injection.max_chars` | `2400` | Hard ceiling on total injected context characters. |
+| `injection.include_open_questions` | `true` | Whether to inject open question artifacts. |
+| `injection.include_dead_ends` | `true` | Whether to inject dead end artifacts. |
+
+## Storage layout
+
+```text
+~/.onlooker/archivist/<project-key>/
+├── manifest.json                    # project_key, remote_url, repo_root, last_compact_at
+├── decisions/<ulid>.json
+├── dead_ends/<ulid>.json
+├── open_questions/<ulid>.json
+└── pinned.json                      # ULIDs that always inject first, regardless of recency
+```
+
+Each artifact:
+
+```json
+{
+  "id": "01J...",
+  "kind": "decision",
+  "project_key": "abc123def456",
+  "source": "local",
+  "created_at": "2026-05-22T10:00:00Z",
+  "updated_at": "2026-05-22T10:00:00Z",
+  "summary": "One-line headline.",
+  "detail": "Optional longer text.",
+  "files": ["relative/path/from/repo/root.ts"],
+  "session_id": "..."
+}
+```
+
+The `source` field is `"local"` today. Future cloud sync may set it to `"cloud"` or `"team:<id>"`.
+
+## Cross-repo isolation
+
+Two layers ensure artifacts from one repo never surface in another:
+
+1. **Project keying** — the storage path is derived from the repo's git remote URL (SHA256, first 12 chars). Two different repos produce different keys.
+2. **Path validation** — every `files[]` entry extracted from the transcript is resolved against `git rev-parse --show-toplevel`. Entries referencing paths outside the repo or that don't exist are stripped before persisting.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for `~/.onlooker/` substrate).
+- `claude` CLI on `PATH` for extraction.
+- `jq` for JSON manipulation.

package/plugins/archivist/config.json

@@ -0,0 +1,18 @@
+{
+  "plugin_name": "archivist",
+  "storage_path": "~/.onlooker",
+  "archivist": {
+    "enabled": false,
+    "extraction": {
+      "model": "claude-haiku-4-5-20251001",
+      "max_output_tokens": 1500,
+      "transcript_tail_chars": 60000
+    },
+    "injection": {
+      "max_items": 8,
+      "max_chars": 2400,
+      "include_open_questions": true,
+      "include_dead_ends": true
+    }
+  }
+}

package/plugins/archivist/hooks/hooks.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/archivist-extract.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/archivist-extract.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/archivist-inject.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/archivist/scripts/hooks/archivist-extract.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# Archivist PreCompact extraction hook.
+#
+# Triggered by PreCompact (manual + auto). Reads the transcript tail, asks
+# `claude -p` for a structured JSON extraction of decisions, dead ends, and
+# open questions, validates referenced paths against the current repo, and
+# writes ULID-keyed artifacts under ~/.onlooker/archivist/<project-key>/.
+#
+# Hook contract:
+#   - Always exits 0 and approves compaction. Never blocks.
+#   - Skips work if archivist.enabled is not true.
+#   - Skips work if there is no git context (no project key).
+#   - Errors from `claude -p` are swallowed; the worst case is "no new memory
+#     for this compact", never "compaction failed".
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# Ecosystem substrate (validate-path.sh) lives in the sibling ecosystem plugin.
+# Prefer the env var the harness sets; fall back to walking up to the repo
+# root in dev checkouts.
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	# In the marketplace repo, plugins/archivist/scripts/hooks is 4 dirs
+	# below the ecosystem root.
+	_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/archivist-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-project-key.sh"
+# shellcheck source=../lib/archivist-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-ulid.sh"
+# shellcheck source=../lib/archivist-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-storage.sh"
+# shellcheck source=../lib/archivist-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/archivist-config.sh"
+
+# Always approve compaction at exit, no matter what happened above.
+_approve() {
+	jq -cn --arg reason "${1:-Compaction approved}" \
+		'{decision: "approve", reason: $reason}'
+}
+
+INPUT=$(cat)
+trap '_approve "Archivist extraction errored out, compaction approved anyway"' ERR
+
+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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+TRIGGER=$(printf '%s' "$INPUT" | jq -r '.trigger // "auto"' 2>/dev/null) || TRIGGER="auto"
+CUSTOM_INSTRUCTIONS=$(printf '%s' "$INPUT" | jq -r '.custom_instructions // ""' 2>/dev/null) || CUSTOM_INSTRUCTIONS=""
+
+REPO_ROOT=$(archivist_project_repo_root "$CWD")
+PROJECT_KEY=$(archivist_project_key "$CWD")
+
+# Config requires repo_root to scan settings.json overlay; load anyway with
+# best-effort empty fallback.
+archivist_config_load "$REPO_ROOT"
+
+if ! archivist_config_enabled; then
+	_approve "Archivist disabled (skip extraction)"
+	exit 0
+fi
+
+if [[ -z "$PROJECT_KEY" || -z "$REPO_ROOT" ]]; then
+	_approve "Archivist: no git context, nothing to extract"
+	exit 0
+fi
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_approve "Archivist: no transcript available"
+	exit 0
+fi
+
+if ! command -v claude >/dev/null 2>&1; then
+	_approve "Archivist: claude CLI not on PATH, skipping extraction"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Build the extraction prompt from the transcript tail.
+# ----------------------------------------------------------------------------
+
+TRANSCRIPT_TAIL_CHARS=$(archivist_config_get '.archivist.extraction.transcript_tail_chars')
+[[ -z "$TRANSCRIPT_TAIL_CHARS" || "$TRANSCRIPT_TAIL_CHARS" == "null" ]] && TRANSCRIPT_TAIL_CHARS=60000
+
+MAX_OUTPUT_TOKENS=$(archivist_config_get '.archivist.extraction.max_output_tokens')
+[[ -z "$MAX_OUTPUT_TOKENS" || "$MAX_OUTPUT_TOKENS" == "null" ]] && MAX_OUTPUT_TOKENS=1500
+
+EXTRACTION_MODEL=$(archivist_config_get '.archivist.extraction.model')
+[[ -z "$EXTRACTION_MODEL" || "$EXTRACTION_MODEL" == "null" ]] && EXTRACTION_MODEL=""
+
+# Take the last N chars of the transcript file. Using a portable approach
+# (tail -c works on macOS and Linux).
+TRANSCRIPT_TAIL=$(tail -c "$TRANSCRIPT_TAIL_CHARS" "$TRANSCRIPT_PATH" 2>/dev/null) || TRANSCRIPT_TAIL=""
+
+if [[ -z "$TRANSCRIPT_TAIL" ]]; then
+	_approve "Archivist: empty transcript tail"
+	exit 0
+fi
+
+PROMPT_FILE=$(mktemp -t archivist-prompt.XXXXXX 2>/dev/null) || PROMPT_FILE="/tmp/archivist-prompt.$$"
+trap 'rm -f "$PROMPT_FILE"; _approve "Archivist extraction errored out, compaction approved anyway"' ERR
+trap 'rm -f "$PROMPT_FILE"' EXIT
+
+{
+	printf '%s\n' 'You are extracting structured session memory from a Claude Code transcript that is about to be compacted (context truncated). Return JSON only — no prose, no markdown fences.'
+	printf '\n'
+	printf '%s\n' 'Output schema (JSON, exactly these keys):'
+	printf '%s\n' '{'
+	printf '%s\n' '  "decisions": [ { "summary": "...", "detail": "...", "files": ["relative/path.ts"] } ],'
+	printf '%s\n' '  "dead_ends": [ { "summary": "...", "detail": "what was tried and why it did not work", "files": [] } ],'
+	printf '%s\n' '  "open_questions": [ { "summary": "...", "detail": "...", "files": [] } ]'
+	printf '%s\n' '}'
+	printf '\n'
+	printf '%s\n' 'Rules:'
+	printf '%s\n' '- Only include items that would meaningfully help a future session continue this work. Skip routine status updates.'
+	printf '%s\n' '- "summary" is a single declarative sentence under 120 chars.'
+	printf '%s\n' '- "detail" is optional and should add why/how context, not restate the summary.'
+	printf '%s\n' '- "files" should list repository-relative paths that the item references. Omit absolute paths and paths outside this repo.'
+	printf '%s\n' '- Prefer reusable rules ("decisions") over event recaps. Decisions outlive specific bugs.'
+	printf '%s\n' '- Return at most 6 decisions, 6 dead_ends, 6 open_questions. If none qualify in a category, return an empty array.'
+	printf '%s\n' '- Output a single JSON object on one line, parseable by JSON.parse.'
+	if [[ -n "$CUSTOM_INSTRUCTIONS" ]]; then
+		printf '\n'
+		printf 'Additional user-provided focus: %s\n' "$CUSTOM_INSTRUCTIONS"
+	fi
+	printf '\n'
+	printf 'Repository root: %s\n' "$REPO_ROOT"
+	printf '\n'
+	printf '%s\n' '---BEGIN TRANSCRIPT TAIL---'
+	printf '%s\n' "$TRANSCRIPT_TAIL"
+	printf '%s\n' '---END TRANSCRIPT TAIL---'
+} > "$PROMPT_FILE"
+
+# ----------------------------------------------------------------------------
+# Invoke `claude -p`. We rely on its default JSON-only output mode when asked
+# for JSON in the prompt; we don't pass --output-format because we want the
+# raw text we asked for.
+# ----------------------------------------------------------------------------
+
+CLAUDE_ARGS=(-p --max-turns 1)
+[[ -n "$EXTRACTION_MODEL" ]] && CLAUDE_ARGS+=(--model "$EXTRACTION_MODEL")
+
+# 90-second hard ceiling on extraction so a hung LLM call never blocks the
+# user's compaction more than that.
+EXTRACTION_TIMEOUT=90
+
+RESPONSE=""
+if command -v timeout >/dev/null 2>&1; then
+	RESPONSE=$(timeout "$EXTRACTION_TIMEOUT" claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+elif command -v gtimeout >/dev/null 2>&1; then
+	RESPONSE=$(gtimeout "$EXTRACTION_TIMEOUT" claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+else
+	RESPONSE=$(claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+fi
+
+if [[ -z "$RESPONSE" ]]; then
+	_approve "Archivist: extraction returned no output"
+	exit 0
+fi
+
+# Strip any accidental markdown fences before parsing.
+CLEAN_RESPONSE=$(printf '%s' "$RESPONSE" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+
+if ! printf '%s' "$CLEAN_RESPONSE" | jq -e '.decisions and .dead_ends and .open_questions' >/dev/null 2>&1; then
+	_approve "Archivist: extraction output was not valid JSON"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Persist artifacts.
+# ----------------------------------------------------------------------------
+
+REMOTE_URL=$(archivist_project_remote_url "$CWD")
+archivist_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+WRITE_COUNT=0
+
+for KIND_PAIR in "decisions:decision" "dead_ends:dead_end" "open_questions:open_question"; do
+	KIND_DIR="${KIND_PAIR%%:*}"
+	KIND_LABEL="${KIND_PAIR##*:}"
+
+	ENTRY_COUNT=$(printf '%s' "$CLEAN_RESPONSE" | jq ".${KIND_DIR} | length" 2>/dev/null) || ENTRY_COUNT=0
+	for ((i = 0; i < ENTRY_COUNT; i++)); do
+		ENTRY=$(printf '%s' "$CLEAN_RESPONSE" | jq ".${KIND_DIR}[$i]" 2>/dev/null) || continue
+		[[ -z "$ENTRY" || "$ENTRY" == "null" ]] && continue
+
+		SUMMARY=$(printf '%s' "$ENTRY" | jq -r '.summary // ""')
+		[[ -z "$SUMMARY" ]] && continue
+
+		DETAIL=$(printf '%s' "$ENTRY" | jq -r '.detail // ""')
+		PATHS_JSON=$(printf '%s' "$ENTRY" | jq '.files // []')
+		CLEAN_PATHS=$(archivist_validate_paths_array "$REPO_ROOT" "$PATHS_JSON")
+
+		ID=$(archivist_ulid)
+		ARTIFACT=$(jq -n \
+			--arg id "$ID" \
+			--arg kind "$KIND_LABEL" \
+			--arg project_key "$PROJECT_KEY" \
+			--arg now "$NOW_TS" \
+			--arg session_id "$SESSION_ID" \
+			--arg trigger "$TRIGGER" \
+			--arg summary "$SUMMARY" \
+			--arg detail "$DETAIL" \
+			--argjson files "$CLEAN_PATHS" \
+			'{
+				id: $id,
+				kind: $kind,
+				project_key: $project_key,
+				source: "local",
+				created_at: $now,
+				updated_at: $now,
+				summary: $summary,
+				detail: (if $detail == "" then null else $detail end),
+				files: $files,
+				session_id: (if $session_id == "" then null else $session_id end),
+				trigger: $trigger
+			}')
+
+		archivist_storage_write_artifact "$PROJECT_KEY" "$KIND_DIR" "$ID" "$ARTIFACT" >/dev/null \
+			&& WRITE_COUNT=$((WRITE_COUNT + 1))
+	done
+done
+
+_approve "Archivist: wrote ${WRITE_COUNT} artifacts (trigger=${TRIGGER})"
+exit 0