@onlooker-community/ecosystem 0.16.0 → 0.18.0

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

@@ -0,0 +1,14 @@
+{
+  "name": "counsel",
+  "version": "0.2.0",
+  "description": "Weekly synthesis and recommendations from the full observability stack. Reads all plugin event logs, produces a structured improvement brief, and injects it at session start when the last brief is stale.",
+  "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/counsel/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.1.0...counsel-v0.2.0) (2026-06-02)
+
+
+### Features
+
+* **counsel:** weekly observability synthesis and coaching brief :robot: ([#51](https://github.com/onlooker-community/ecosystem/issues/51)) ([6364586](https://github.com/onlooker-community/ecosystem/commit/63645863cf3a1d7bbf0353aacb9b71e4f977dd56))

package/plugins/counsel/config.json

@@ -0,0 +1,20 @@
+{
+  "counsel": {
+    "enabled": true,
+    "synthesis_interval_days": 7,
+    "lookback_days": 30,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout": 90,
+      "max_tokens": 4096,
+      "temperature": 0.4
+    },
+    "capture": {
+      "min_events": 10,
+      "events_chars_max": 60000
+    },
+    "output": {
+      "brief_max_chars": 3000
+    }
+  }
+}

package/plugins/counsel/hooks/hooks.json

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

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Counsel SessionStart hook — weekly improvement brief injection.
+#
+# Fires at session start. If the last brief for this project is older than
+# synthesis_interval_days (default: 7), runs a Haiku synthesis pass over the
+# full event log and injects the resulting brief as additionalContext.
+#
+# Skip conditions (all silent):
+#   - counsel.enabled is false
+#   - no project key (non-git directory)
+#   - brief is still fresh
+#   - fewer than min_events events in the lookback window
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits hookSpecificOutput JSON on stdout (even when context is empty).
+#   - Errors are written to stderr only.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/counsel-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-config.sh"
+# shellcheck source=../lib/counsel-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-events.sh"
+# shellcheck source=../lib/counsel-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+# shellcheck source=../lib/counsel-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-ulid.sh"
+# shellcheck source=../lib/counsel-reader.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+# shellcheck source=../lib/counsel-synthesize.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-synthesize.sh"
+# shellcheck source=../lib/counsel-brief.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-brief.sh"
+
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '
+		{
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: $ctx
+			}
+		}
+	'
+}
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+REPO_ROOT=$(counsel_project_repo_root "$CWD")
+counsel_config_load "$REPO_ROOT"
+
+if ! counsel_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+PROJECT_KEY=$(counsel_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+_generate_rc=0
+OUTPUT_PATH=$(counsel_generate_brief "$SESSION_ID" "$CWD") || _generate_rc=$?
+
+if [[ $_generate_rc -ne 0 ]]; then
+	# rc=2 means stale check passed (brief is fresh) or too few events — silent skip.
+	[[ $_generate_rc -ne 2 ]] && printf 'counsel-session-start: brief generation failed for session %s\n' "$SESSION_ID" >&2
+	_emit ""
+	exit 0
+fi
+
+if [[ -z "$OUTPUT_PATH" || ! -f "$OUTPUT_PATH" ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Load the brief content and apply the configured char budget.
+BRIEF_MAX_CHARS=$(counsel_config_get '.counsel.output.brief_max_chars')
+[[ -z "$BRIEF_MAX_CHARS" || "$BRIEF_MAX_CHARS" == "null" ]] && BRIEF_MAX_CHARS="3000"
+
+BRIEF_CONTENT=$(head -c "$BRIEF_MAX_CHARS" "$OUTPUT_PATH" 2>/dev/null) || BRIEF_CONTENT=""
+
+if [[ -z "$BRIEF_CONTENT" ]]; then
+	_emit ""
+	exit 0
+fi
+
+CONTEXT="Counsel — weekly improvement brief (auto-generated from your onlooker event log):
+
+${BRIEF_CONTENT}
+
+(Counsel injected this brief for project key ${PROJECT_KEY}. Set counsel.enabled=false to disable.)"
+
+_emit "$CONTEXT"
+exit 0

package/plugins/counsel/scripts/lib/counsel-brief.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Brief orchestrator for Counsel.
+#
+# Checks whether a fresh brief is needed, runs the full synthesis pipeline,
+# writes a Markdown brief to ~/.onlooker/counsel/<project-key>/briefs/,
+# and emits counsel.brief.generated.
+#
+# Exposes:
+#   counsel_brief_is_stale <project_key> <interval_days>
+#     Returns 0 if a new brief should be generated, 1 if the existing one is fresh.
+#
+#   counsel_generate_brief <session_id> <cwd>
+#     Runs the full pipeline. Echoes the output path on success.
+#     Returns 2 if skipped (not stale or too few events).
+#     Returns 1 on hard failure.
+
+# shellcheck source=./counsel-reader.sh
+# shellcheck source=./counsel-synthesize.sh
+# shellcheck source=./counsel-events.sh
+# shellcheck source=./counsel-project-key.sh
+# (caller must source these before counsel-brief.sh)
+
+_counsel_latest_brief_path() {
+	local briefs_dir="${1:-}"
+	[[ -d "$briefs_dir" ]] || return 1
+	# Briefs are named YYYY-WW.md; newest sorts last lexicographically.
+	local latest
+	latest=$(ls -1 "$briefs_dir"/*.md 2>/dev/null | sort | tail -1)
+	[[ -n "$latest" ]] || return 1
+	printf '%s' "$latest"
+}
+
+_counsel_brief_mtime_epoch() {
+	local path="${1:-}"
+	[[ -f "$path" ]] || { printf '0'; return 0; }
+	if [[ "$(uname)" == "Darwin" ]]; then
+		stat -f '%m' "$path" 2>/dev/null || printf '0'
+	else
+		stat -c '%Y' "$path" 2>/dev/null || printf '0'
+	fi
+}
+
+counsel_brief_is_stale() {
+	local project_key="${1:-}"
+	local interval_days="${2:-7}"
+
+	local briefs_dir
+	briefs_dir=$(counsel_project_dir "$project_key")
+
+	local latest_path
+	latest_path=$(_counsel_latest_brief_path "$briefs_dir") || { return 0; }
+
+	local mtime now age_days
+	mtime=$(_counsel_brief_mtime_epoch "$latest_path")
+	now=$(date +%s 2>/dev/null) || now=0
+	age_days=$(( (now - mtime) / 86400 ))
+
+	[[ "$age_days" -ge "$interval_days" ]]
+}
+
+_counsel_format_brief() {
+	local brief_json="${1:-}"
+	local period_start="${2:-}"
+	local period_end="${3:-}"
+	local event_count="${4:-0}"
+
+	local summary patterns_json recs_json wins_json watch_json
+	summary=$(printf '%s' "$brief_json" | jq -r '.summary // ""' 2>/dev/null) || summary=""
+	patterns_json=$(printf '%s' "$brief_json" | jq -c '.patterns // []' 2>/dev/null) || patterns_json="[]"
+	recs_json=$(printf '%s' "$brief_json" | jq -c '.recommendations // []' 2>/dev/null) || recs_json="[]"
+	wins_json=$(printf '%s' "$brief_json" | jq -c '.wins // []' 2>/dev/null) || wins_json="[]"
+	watch_json=$(printf '%s' "$brief_json" | jq -c '.watch // []' 2>/dev/null) || watch_json="[]"
+
+	local timestamp
+	timestamp=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp="unknown"
+
+	{
+		printf '# Counsel Brief: %s — %s\n\n' "$period_start" "$period_end"
+		[[ -n "$summary" ]] && printf '> %s\n\n' "$summary"
+
+		printf '## Recommendations\n\n'
+		local rec_count
+		rec_count=$(printf '%s' "$recs_json" | jq 'length' 2>/dev/null) || rec_count=0
+		if [[ "$rec_count" -gt 0 ]]; then
+			local i
+			for ((i = 0; i < rec_count; i++)); do
+				local title rationale priority
+				title=$(printf '%s' "$recs_json" | jq -r ".[$i].title // \"\"" 2>/dev/null) || title=""
+				rationale=$(printf '%s' "$recs_json" | jq -r ".[$i].rationale // \"\"" 2>/dev/null) || rationale=""
+				priority=$(printf '%s' "$recs_json" | jq -r ".[$i].priority // \"medium\"" 2>/dev/null) || priority="medium"
+				[[ -z "$title" ]] && continue
+				printf '### [%s] %s\n\n' "$priority" "$title"
+				[[ -n "$rationale" ]] && printf '%s\n\n' "$rationale"
+			done
+		else
+			printf '*No recommendations this period.*\n\n'
+		fi
+
+		printf '## Patterns Observed\n\n'
+		local pat_count
+		pat_count=$(printf '%s' "$patterns_json" | jq 'length' 2>/dev/null) || pat_count=0
+		if [[ "$pat_count" -gt 0 ]]; then
+			printf '%s' "$patterns_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None identified.*\n\n'
+		fi
+
+		printf '## Wins\n\n'
+		local win_count
+		win_count=$(printf '%s' "$wins_json" | jq 'length' 2>/dev/null) || win_count=0
+		if [[ "$win_count" -gt 0 ]]; then
+			printf '%s' "$wins_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Watch\n\n'
+		local watch_count
+		watch_count=$(printf '%s' "$watch_json" | jq 'length' 2>/dev/null) || watch_count=0
+		if [[ "$watch_count" -gt 0 ]]; then
+			printf '%s' "$watch_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*Nothing flagged.*\n\n'
+		fi
+
+		printf '---\n'
+		printf '*Generated by counsel · %s · %d events analyzed*\n' "$timestamp" "$event_count"
+	}
+}
+
+counsel_generate_brief() {
+	local session_id="${1:-}"
+	local cwd="${2:-}"
+
+	[[ -z "$session_id" ]] && return 1
+
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+
+	# Resolve config values.
+	local interval_days lookback_days model timeout_s max_tokens temperature chars_max min_events
+	interval_days=$(counsel_config_get '.counsel.synthesis_interval_days')
+	[[ -z "$interval_days" || "$interval_days" == "null" ]] && interval_days="7"
+	lookback_days=$(counsel_config_get '.counsel.lookback_days')
+	[[ -z "$lookback_days" || "$lookback_days" == "null" ]] && lookback_days="30"
+	model=$(counsel_config_get '.counsel.evaluator.model')
+	[[ -z "$model" || "$model" == "null" ]] && model="claude-haiku-4-5-20251001"
+	timeout_s=$(counsel_config_get '.counsel.evaluator.timeout')
+	[[ -z "$timeout_s" || "$timeout_s" == "null" ]] && timeout_s="90"
+	max_tokens=$(counsel_config_get '.counsel.evaluator.max_tokens')
+	[[ -z "$max_tokens" || "$max_tokens" == "null" ]] && max_tokens="4096"
+	temperature=$(counsel_config_get '.counsel.evaluator.temperature')
+	[[ -z "$temperature" || "$temperature" == "null" ]] && temperature="0.4"
+	chars_max=$(counsel_config_get '.counsel.capture.events_chars_max')
+	[[ -z "$chars_max" || "$chars_max" == "null" ]] && chars_max="60000"
+	min_events=$(counsel_config_get '.counsel.capture.min_events')
+	[[ -z "$min_events" || "$min_events" == "null" ]] && min_events="10"
+
+	local project_key
+	project_key=$(counsel_project_key "$cwd")
+
+	# Stale check.
+	if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
+		return 2
+	fi
+
+	# Read events.
+	local events_text
+	events_text=$(counsel_read_events "$lookback_days" "$chars_max")
+
+	local event_count
+	event_count=$(counsel_count_events "$events_text")
+
+	if [[ "$event_count" -lt "$min_events" ]]; then
+		return 2
+	fi
+
+	# Run synthesis.
+	local brief_json
+	brief_json=$(counsel_synthesize "$events_text" "$model" "$timeout_s" "$max_tokens" "$temperature") || {
+		printf 'counsel_generate_brief: synthesis failed for session %s\n' "$session_id" >&2
+		return 1
+	}
+
+	# Compute period bounds.
+	local period_start period_end
+	period_end=$(date '+%Y-%m-%d' 2>/dev/null) || period_end="unknown"
+	if [[ "$(uname)" == "Darwin" ]]; then
+		period_start=$(date -v "-${lookback_days}d" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+	else
+		period_start=$(date -d "-${lookback_days} days" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+	fi
+
+	# Determine sources consulted.
+	local sources_json
+	sources_json=$(counsel_sources_from_events "$events_text")
+
+	# Write brief.
+	local briefs_dir output_path
+	if [[ -n "$project_key" ]]; then
+		briefs_dir=$(counsel_project_dir "$project_key")
+	else
+		briefs_dir="${onlooker_dir}/counsel/unknown/briefs"
+	fi
+
+	mkdir -p "$briefs_dir" 2>/dev/null || {
+		printf 'counsel_generate_brief: cannot create briefs dir %s\n' "$briefs_dir" >&2
+		return 1
+	}
+
+	local week_label
+	week_label=$(date '+%G-%V' 2>/dev/null) || week_label=$(date '+%Y-%U' 2>/dev/null) || week_label="unknown"
+	local filename="${week_label}.md"
+	output_path="${briefs_dir}/${filename}"
+
+	local doc
+	doc=$(_counsel_format_brief "$brief_json" "$period_start" "$period_end" "$event_count")
+
+	printf '%s\n' "$doc" > "$output_path" 2>/dev/null || {
+		printf 'counsel_generate_brief: failed to write %s\n' "$output_path" >&2
+		return 1
+	}
+
+	# Emit counsel.brief.generated.
+	local rec_count
+	rec_count=$(printf '%s' "$brief_json" | jq '.recommendations | length' 2>/dev/null) || rec_count=0
+
+	local payload
+	payload=$(jq -n \
+		--arg ps "$period_start" \
+		--arg pe "$period_end" \
+		--argjson rc "$rec_count" \
+		--argjson src "$sources_json" \
+		'{period_start: $ps, period_end: $pe, recommendation_count: $rc, sources_consulted: $src}') || payload=""
+
+	[[ -n "$payload" ]] && counsel_emit_event "counsel.brief.generated" "$payload" || true
+
+	printf '%s' "$output_path"
+}

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Config resolution for Counsel.
+#
+# Three-layer merge, latest wins:
+#   1. plugins/counsel/config.json   (plugin defaults)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   counsel_config_load <repo_root>    # populates _COUNSEL_CONFIG (JSON)
+#   counsel_config_get <jq-path>       # echoes string value (empty if unset)
+#   counsel_config_get_json <jq-path>  # echoes JSON value (null if unset)
+#   counsel_config_enabled             # 0 if counsel.enabled is true
+
+_COUNSEL_CONFIG="{}"
+
+counsel_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 '{ counsel: (.counsel // {}) }' "$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
+
+	_COUNSEL_CONFIG="$merged"
+}
+
+counsel_config_get() {
+	local path="$1"
+	printf '%s' "$_COUNSEL_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+counsel_config_get_json() {
+	local path="$1"
+	printf '%s' "$_COUNSEL_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+counsel_config_enabled() {
+	local v
+	v=$(counsel_config_get '.counsel.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/counsel/scripts/lib/counsel-events.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Canonical counsel.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema before being
+# appended to $ONLOOKER_EVENTS_LOG (defaults to $ONLOOKER_DIR/logs/onlooker-events.jsonl).
+#
+# Usage:
+#   counsel_emit_event "counsel.brief.generated" '{"period_start":"...","period_end":"...","recommendation_count":3}'
+
+_COUNSEL_PLUGIN_NAME="counsel"
+
+_counsel_event_js_path() {
+	if [[ -n "${_ONLOOKER_EVENT_JS:-}" && -f "$_ONLOOKER_EVENT_JS" ]]; then
+		printf '%s' "$_ONLOOKER_EVENT_JS"
+		return 0
+	fi
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local candidates=(
+		"${plugin_root}/scripts/lib/onlooker-event.mjs"
+		"${plugin_root}/../../scripts/lib/onlooker-event.mjs"
+	)
+	local c
+	for c in "${candidates[@]}"; do
+		[[ -f "$c" ]] && { printf '%s' "$c"; return 0; }
+	done
+	return 1
+}
+
+_counsel_session_id() {
+	if [[ -n "${_HOOK_SESSION_ID:-}" ]]; then
+		printf '%s' "$_HOOK_SESSION_ID"
+		return 0
+	fi
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+	printf 'unknown'
+}
+
+counsel_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_counsel_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_counsel_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_COUNSEL_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}' \
+		2>/dev/null) || return 1
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t counsel-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/counsel-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_COUNSEL_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'counsel_emit_event: schema validation failed for %s\n' "$event_type" >&2
+		[[ -s "$stderr_file" ]] && cat "$stderr_file" >&2
+		rm -f "$stderr_file"
+		return 1
+	}
+	rm -f "$stderr_file"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	mkdir -p "$(dirname "$log_path")" 2>/dev/null || return 1
+	printf '%s\n' "$event" >> "$log_path"
+}

package/plugins/counsel/scripts/lib/counsel-project-key.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Project key derivation for Counsel.
+#
+# Mirrors the tribunal/scribe project-key scheme so plugins partition storage
+# identically. A project key is a stable 12-char hex identifier derived from
+# the git remote URL (preferred) or repo root path (fallback).
+
+_counsel_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+counsel_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+counsel_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+counsel_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(counsel_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_counsel_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(counsel_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_counsel_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}
+
+counsel_project_dir() {
+	local project_key="${1:-}"
+	[[ -z "$project_key" ]] && return 1
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/counsel/${project_key}/briefs"
+}