@onlooker-community/ecosystem 0.25.0 → 0.26.0

package/.claude-plugin/marketplace.json

@@ -5,26 +5,26 @@
     "email": "community@onlooker.dev"
   },
   "metadata": {
-    "description": "TODO Fill this out"
+    "description": "Composable observability, memory, and quality-gate plugins for Claude Code — all built on the Onlooker ecosystem event substrate."
   },
   "plugins": [
     {
       "name": "ecosystem",
       "source": "./",
-      "description": "Fill this out",
+      "description": "Observability substrate for Claude Code. Provides the shared $ONLOOKER_DIR storage root (default $HOME/.onlooker), canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
       "author": {
         "name": "Onlooker Community"
       },
       "homepage": "https://onlooker.dev",
       "repository": "https://github.com/onlooker-community/ecosystem",
       "license": "MIT",
-      "keywords": [],
-      "tags": []
+      "keywords": ["observability", "substrate", "events", "hooks", "telemetry"],
+      "tags": ["observability", "substrate"]
     },
     {
       "name": "archivist",
       "source": "./plugins/archivist",
-      "description": "Structured session memory across context truncation. Extracts decisions, dead ends, and open questions on PreCompact and reinjects the most important items at SessionStart. Requires the ecosystem plugin.",
+      "description": "Structured session memory across context truncation: extracts decisions, dead ends, and open questions on PreCompact and reinjects the most important items at SessionStart. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -34,10 +34,23 @@
       "keywords": ["memory", "compaction", "context", "session"],
       "tags": ["memory", "context-engineering"]
     },
+    {
+      "name": "cartographer",
+      "source": "./plugins/cartographer",
+      "description": "Proactive periodic auditor of the persistent instruction layer (CLAUDE.md, AGENTS.md, .claude/rules/). Discovers all instruction files in the repo, extracts semantic maps, and surfaces contradictions, shadowing, gaps, and drift before they cause expensive agent misbehavior. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["instructions", "audit", "claude-md", "agents-md", "drift", "consistency"],
+      "tags": ["instructions", "context-engineering"]
+    },
     {
       "name": "tribunal",
       "source": "./plugins/tribunal",
-      "description": "Multi-agent execution with LLM-as-a-Judge quality gates. An Actor performs work; a jury of typed Judges scores it against a project-overridable rubric; a Meta-Judge reviews the jury for bias; the gate decides accept, retry, or exhaust. Requires the ecosystem plugin.",
+      "description": "Multi-agent execution with LLM-as-a-Judge quality gates. An Actor performs work; a jury of typed Judges scores it against a project-overridable rubric; a Meta-Judge reviews the jury for bias; the gate decides accept, retry, or exhaust. Grounded in LLM-as-a-Judge (Zheng et al. 2023) and LLM-as-a-Meta-Judge (Wu et al. 2024). Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -76,7 +89,7 @@
     {
       "name": "compass",
       "source": "./plugins/compass",
-      "description": "Pre-write intent clarity gate. Intercepts write-class tool calls and samples N=5 parallel evaluators to score intent clarity before allowing writes to proceed. Blocks when confidence is low or evaluators disagree, surfacing a structured clarification prompt. Requires the ecosystem plugin.",
+      "description": "Pre-write intent clarity gate. Intercepts write-class tool calls and requires a confidence threshold before allowing them to proceed. Evaluates the pending write against the prior assistant turn as context to avoid false positives on question-answer turns. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -89,7 +102,7 @@
     {
       "name": "scribe",
       "source": "./plugins/scribe",
-      "description": "Intent documentation from agent activity. Captures why changes were made — problem context, decisions, tradeoffs, and constraints — and distills them into readable Markdown artifacts at session end. Git logs record what changed; scribe records why. Requires the ecosystem plugin.",
+      "description": "Intent documentation from agent activity. Captures why changes were made — problem context, decisions, tradeoffs — and distills them into readable artifacts at session end. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -102,7 +115,7 @@
     {
       "name": "counsel",
       "source": "./plugins/counsel",
-      "description": "Weekly synthesis and recommendations from your full observability stack. Reads all plugin event logs, identifies patterns, surfaces improvement opportunities, and injects a structured brief at session start when the last brief is stale. Turns disparate logs into a coaching signal. Requires the ecosystem plugin.",
+      "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. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -115,7 +128,7 @@
     {
       "name": "warden",
       "source": "./plugins/warden",
-      "description": "Untrusted-content gate. Scans content flowing in through WebFetch and Read for prompt-injection patterns, and when a threat is detected closes a session-scoped gate that blocks Write, Edit, and Bash until the user explicitly clears it. Grounded in Meta's Agents Rule of Two — warden removes the agent's external-actions property while untrusted content is in play. Requires the ecosystem plugin.",
+      "description": "Untrusted-content gate. Scans content flowing in through WebFetch and Read for prompt-injection patterns, and when a threat is detected closes a session-scoped gate that blocks Write, Edit, and Bash until the user explicitly clears it. Grounded in Meta's Agents Rule of Two: an agent should hold no more than two of {private data, external actions, untrusted content} at once — warden removes the external-actions property while untrusted content is in play. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -128,7 +141,7 @@
     {
       "name": "librarian",
       "source": "./plugins/librarian",
-      "description": "Consolidation layer between archivist's per-session artifacts and the user's durable typed memory store. Reads archivist artifacts at SessionEnd, applies a durability filter, classifies survivors via Haiku into the four memory types (user, feedback, project, reference), and queues proposals for explicit confirmation via /librarian review. Auto-promotion is opt-in. Requires the ecosystem plugin.",
+      "description": "Consolidation layer between archivist's per-session artifacts and the user's durable typed memory store. Detects which session decisions, dead-ends, and open questions deserve to live across sessions, classifies them into the user/feedback/project/reference types, and queues them as proposals for explicit confirmation. Auto-promotion is opt-in. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -141,7 +154,7 @@
     {
       "name": "curator",
       "source": "./plugins/curator",
-      "description": "Maintenance layer for the typed auto-memory store. At every SessionStart, runs four cheap heuristic checks against the memories at ~/.claude/projects/<encoded>/memory/ — date_decayed (ISO-8601 dates past the grace period), path_broken (path-shaped references that don't resolve under the repo root), broken_index (MEMORY.md pointing at missing files), and orphaned_memory (files in the dir not referenced from MEMORY.md). Surfaces findings via /curator review; never edits the memory store directly. Parallel to cartographer (which audits hand-maintained instruction files), curator audits the auto-memory substrate. Requires the ecosystem plugin.",
+      "description": "Maintenance layer for the user's typed auto-memory store. At every SessionStart, runs four cheap heuristic checks (date_decayed, path_broken, broken_index, orphaned_memory) against the memories at ~/.claude/projects/<encoded>/memory/ inside a wall-clock budget. Surfaces findings as a one-line pointer to /curator review; never edits the memory store directly. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -154,7 +167,7 @@
     {
       "name": "historian",
       "source": "./plugins/historian",
-      "description": "Episodic memory layer for past Claude Code sessions. At SessionEnd, reads the session transcript, drops tool calls and tool results, chunks the remaining user + assistant turns at turn boundaries with overlap, redacts secret-shaped substrings (AWS keys, GitHub PATs, Anthropic API keys, KEY=value env assignments), and appends one JSONL line per surviving chunk to ~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl. Future-tense retrieval (vector embeddings + UserPromptSubmit similarity surfacer) lands in a follow-up; this version ships the indexing pipeline only. Requires the ecosystem plugin.",
+      "description": "Episodic memory layer. At SessionEnd, chunks and sanitizes the session transcript and stores chunks under $ONLOOKER_DIR/historian/<project-key>/sessions/ (default $HOME/.onlooker). On UserPromptSubmit, embeds the prompt and performs similarity retrieval over stored chunks to surface relevant past context. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },
@@ -167,7 +180,7 @@
     {
       "name": "assayer",
       "source": "./plugins/assayer",
-      "description": "Claim verification. At session end, parses the agent's final message for testable success claims (\"I ran the tests, they pass\", \"the build is green\") and cross-checks each against the actual command results in the session transcript, classifying it corroborated, contradicted, or unverifiable. Catches lying-without-malice. Advisory by default. Requires the ecosystem plugin.",
+      "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. Requires the ecosystem plugin.",
       "author": {
         "name": "Onlooker Community"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ecosystem",
-  "version": "0.25.0",
-  "description": "Observability substrate for Claude Code. Provides the shared ~/.onlooker/ storage root, canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
+  "version": "0.26.0",
+  "description": "Observability substrate for Claude Code. Provides the shared $ONLOOKER_DIR storage root (default $HOME/.onlooker), canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
   "author": {
     "name": "Onlooker Community",
     "url": "https://onlooker.dev"

package/.release-please-manifest.json

@@ -1,13 +1,13 @@
 {
-  ".": "0.25.0",
+  ".": "0.26.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
-  "plugins/cartographer": "0.2.0",
-  "plugins/governor": "0.2.0",
+  "plugins/cartographer": "0.2.1",
+  "plugins/governor": "0.2.1",
   "plugins/compass": "0.2.0",
   "plugins/scribe": "0.2.1",
-  "plugins/counsel": "0.2.0",
+  "plugins/counsel": "0.3.0",
   "plugins/warden": "0.2.0",
   "plugins/librarian": "0.2.0",
   "plugins/curator": "0.1.0",

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.26.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.25.1...ecosystem-v0.26.0) (2026-06-11)
+
+
+### Features
+
+* **counsel:** add /counsel on-demand weekly-review command :rocket: ([#76](https://github.com/onlooker-community/ecosystem/issues/76)) ([8ce951c](https://github.com/onlooker-community/ecosystem/commit/8ce951cd5cb7b173f194f86c2960a31fb0d6889d))
+
+## [0.25.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.25.0...ecosystem-v0.25.1) (2026-06-10)
+
+
+### Bug Fixes
+
+* vendor portable-lock.sh into cartographer and governor ([#73](https://github.com/onlooker-community/ecosystem/issues/73)) ([ab2c354](https://github.com/onlooker-community/ecosystem/commit/ab2c354b131c26cc642ebb51e84a043dc43cbaa1))
+
 ## [0.25.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.24.0...ecosystem-v0.25.0) (2026-06-04)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -26,7 +26,7 @@
     "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 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",
+    "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",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",

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

@@ -1,6 +1,6 @@
 {
   "name": "cartographer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Proactive periodic auditor of the persistent instruction layer (CLAUDE.md, AGENTS.md, .claude/rules/). Discovers all instruction files in the repo, extracts semantic maps, and surfaces contradictions, shadowing, gaps, and drift before they cause expensive agent misbehavior. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/cartographer/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the Cartographer plugin are documented here.
 
+## [0.2.1](https://github.com/onlooker-community/ecosystem/compare/cartographer-v0.2.0...cartographer-v0.2.1) (2026-06-10)
+
+
+### Bug Fixes
+
+* vendor portable-lock.sh into cartographer and governor ([#73](https://github.com/onlooker-community/ecosystem/issues/73)) ([ab2c354](https://github.com/onlooker-community/ecosystem/commit/ab2c354b131c26cc642ebb51e84a043dc43cbaa1))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/cartographer-v0.1.0...cartographer-v0.2.0) (2026-05-25)
 
 

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

@@ -9,17 +9,27 @@
 #   cartographer_lock_acquire <lock_file>   # returns 0=acquired, 1=timeout
 #   cartographer_lock_release <lock_file>
 
-_CARTOGRAPHER_LOCK_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../scripts/lib" && pwd)/portable-lock.sh"
+# portable-lock.sh is vendored into this plugin's lib dir (a sibling of this
+# file) so cartographer stays self-contained when installed standalone from
+# the marketplace, where the ecosystem repo's top-level scripts/lib/ is absent.
+_CARTOGRAPHER_LOCK_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/portable-lock.sh"
 
-if [[ ! -f "$_CARTOGRAPHER_LOCK_LIB" ]]; then
-	printf '[cartographer-lock] ERROR: portable-lock.sh not found at %s\n' \
+if [[ -f "$_CARTOGRAPHER_LOCK_LIB" ]]; then
+	# shellcheck source=./portable-lock.sh
+	source "$_CARTOGRAPHER_LOCK_LIB"
+else
+	# The vendored lock should always be present, but if an unexpected
+	# packaging or path issue removes it we must degrade gracefully: the
+	# cartographer hooks are fail-soft and contractually exit 0, so a hard
+	# exit here would crash a session this plugin was only meant to observe.
+	# Define a primitive that always fails to acquire, so the hooks'
+	# `cartographer_lock_acquire ... || exit 0` skips the audit instead.
+	printf '[cartographer-lock] WARN: portable-lock.sh not found at %s; locking disabled, skipping audit\n' \
 		"$_CARTOGRAPHER_LOCK_LIB" >&2
-	exit 1
+	lock_acquire() { return 1; }
+	lock_release() { return 0; }
 fi
 
-# shellcheck source=../../../../scripts/lib/portable-lock.sh
-source "$_CARTOGRAPHER_LOCK_LIB"
-
 cartographer_lock_acquire() {
 	local lock_file="${1:?lock_file required}"
 	mkdir -p "$(dirname "$lock_file")" 2>/dev/null || true

package/plugins/cartographer/scripts/lib/portable-lock.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# portable-lock.sh — vendored copy of the ecosystem substrate's portable lock.
+#
+# Vendored into the cartographer plugin so the plugin is self-contained when
+# installed standalone from the marketplace: the cache layout
+# (~/.claude/plugins/cache/<owner>/cartographer/<version>/) does not include
+# the ecosystem repo's top-level scripts/lib/, so reaching up to it breaks.
+# This mirrors the per-plugin vendoring of cartographer-ulid.sh and friends.
+# Keep in sync with scripts/lib/portable-lock.sh at the repo root.
+#
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see concurrent writes to $ONLOOKER_DIR silently clobber each other.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "counsel",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -9,6 +9,6 @@
   "homepage": "https://onlooker.dev",
   "repository": "https://github.com/onlooker-community/ecosystem",
   "license": "MIT",
-  "skills": [],
+  "skills": ["./skills/counsel"],
   "agents": []
 }

package/plugins/counsel/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.2.0...counsel-v0.3.0) (2026-06-11)
+
+
+### Features
+
+* **counsel:** add /counsel on-demand weekly-review command :rocket: ([#76](https://github.com/onlooker-community/ecosystem/issues/76)) ([8ce951c](https://github.com/onlooker-community/ecosystem/commit/8ce951cd5cb7b173f194f86c2960a31fb0d6889d))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.1.0...counsel-v0.2.0) (2026-06-02)
 
 

package/plugins/counsel/README.md

@@ -18,6 +18,18 @@ Counsel partitions the event stream by source plugin, recognizing `tribunal`, `e
 
 The hook always exits 0 — it never blocks a session from starting. It skips silently when Counsel is disabled, the directory has no project key (non-git), the latest brief is still fresh, or fewer than `capture.min_events` events fall inside the lookback window.
 
+## On-demand brief — `/counsel`
+
+The SessionStart path only regenerates when the latest brief is stale. To run the weekly review immediately — regardless of freshness — invoke the `/counsel` skill. It forces a synthesis pass, writes the brief, emits `counsel.brief.generated`, and renders the result in the conversation instead of injecting it invisibly.
+
+| Invocation | What it does |
+|------------|--------------|
+| `/counsel` | Forces a fresh synthesis now (bypassing the staleness gate), writes `<YYYY-WW>.md`, and prints the brief. Re-running in the same ISO week overwrites that week's brief in place. |
+| `/counsel --show` | Renders the most recent brief already on disk. No LLM call, no events emitted. |
+| `/counsel --status` | Reports the latest brief's age, last-generated time, and whether it is stale. No LLM call. |
+
+The on-demand path bypasses only the staleness gate — output, events, storage layout, project keying, and the `capture.min_events` floor are identical to the SessionStart path. If too few events fall inside the lookback window, `/counsel` reports that rather than emitting a thin brief.
+
 ## Activation
 
 Counsel is **on by default**. Disable it per-project in `.claude/settings.json` (or globally in `~/.claude/settings.json`):

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

@@ -9,8 +9,10 @@
 #   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>
+#   counsel_generate_brief <session_id> <cwd> [force]
 #     Runs the full pipeline. Echoes the output path on success.
+#     When [force] is "1" or "force", the staleness gate is bypassed (used by
+#     the on-demand /counsel skill); the min_events gate always applies.
 #     Returns 2 if skipped (not stale or too few events).
 #     Returns 1 on hard failure.
 
@@ -101,7 +103,7 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
@@ -113,7 +115,7 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
@@ -125,14 +127,14 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
 			printf '*Nothing flagged.*\n\n'
 		fi
 
-		printf '---\n'
+		printf -- '---\n'
 		printf '*Generated by counsel · %s · %d events analyzed*\n' "$timestamp" "$event_count"
 	}
 }
@@ -140,6 +142,7 @@ _counsel_format_brief() {
 counsel_generate_brief() {
 	local session_id="${1:-}"
 	local cwd="${2:-}"
+	local force="${3:-0}"
 
 	[[ -z "$session_id" ]] && return 1
 
@@ -167,9 +170,11 @@ counsel_generate_brief() {
 	local project_key
 	project_key=$(counsel_project_key "$cwd")
 
-	# Stale check.
-	if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
-		return 2
+	# Stale check. On-demand invocations pass force to bypass it.
+	if [[ "$force" != "1" && "$force" != "force" ]]; then
+		if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
+			return 2
+		fi
 	fi
 
 	# Read events.
@@ -190,14 +195,28 @@ counsel_generate_brief() {
 		return 1
 	}
 
-	# Compute period bounds.
-	local period_start period_end
-	period_end=$(date '+%Y-%m-%d' 2>/dev/null) || period_end="unknown"
+	# Compute period bounds. The brief heading shows calendar dates; the emitted
+	# event requires RFC 3339 date-time strings (schema format: date-time), so
+	# compute the timestamps first and derive the date-only strings from them.
+	# Prefer UTC; fall back to local time (still RFC 3339, just a different zone)
+	# if -u is unavailable. If even that fails the date subsystem is broken and
+	# the bounds stay empty — the emit below skips rather than send garbage.
+	local period_start_ts period_end_ts
+	period_end_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+		|| period_end_ts=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+		|| period_end_ts=""
 	if [[ "$(uname)" == "Darwin" ]]; then
-		period_start=$(date -v "-${lookback_days}d" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+		period_start_ts=$(date -u -v "-${lookback_days}d" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=$(date -v "-${lookback_days}d" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=""
 	else
-		period_start=$(date -d "-${lookback_days} days" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+		period_start_ts=$(date -u -d "-${lookback_days} days" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=$(date -d "-${lookback_days} days" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=""
 	fi
+	local period_start period_end
+	period_end="${period_end_ts%%T*}"; [[ -z "$period_end" ]] && period_end="unknown"
+	period_start="${period_start_ts%%T*}"; [[ -z "$period_start" ]] && period_start="unknown"
 
 	# Determine sources consulted.
 	local sources_json
@@ -235,13 +254,19 @@ counsel_generate_brief() {
 
 	local payload
 	payload=$(jq -n \
-		--arg ps "$period_start" \
-		--arg pe "$period_end" \
+		--arg ps "$period_start_ts" \
+		--arg pe "$period_end_ts" \
 		--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
+	# Only emit when the period bounds are valid RFC 3339 date-times — emitting
+	# empty bounds would fail schema validation and silently drop the event.
+	if [[ -n "$payload" && -n "$period_start_ts" && -n "$period_end_ts" ]]; then
+		counsel_emit_event "counsel.brief.generated" "$payload" || true
+	else
+		printf 'counsel_generate_brief: skipped counsel.brief.generated (no valid period bounds)\n' >&2
+	fi
 
 	printf '%s' "$output_path"
 }

package/plugins/counsel/skills/counsel/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: counsel
+description: Run the weekly observability synthesis on demand and render the coaching brief in the conversation. Reads the onlooker event log, runs a single synthesis pass, writes the brief, and prints it — bypassing the SessionStart staleness gate. Use when the user explicitly invokes /counsel, or wants a fresh improvement brief right now instead of waiting for the next stale-brief regeneration. Supports --show (print the latest brief, no LLM call) and --status.
+---
+
+# Counsel Skill
+
+Counsel's SessionStart hook regenerates a weekly improvement brief only when the
+last one has gone stale (`synthesis_interval_days`, default 7) and injects it
+invisibly. This skill is the on-demand path: it forces a fresh synthesis right
+now and renders the brief into the conversation.
+
+## Setup
+
+Run this once at the start. It sources the plugin helpers, loads config, and
+resolves project context.
+
+```bash
+set -uo pipefail
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/counsel-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-ulid.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-reader.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-synthesize.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-brief.sh"
+
+REPO_ROOT=$(counsel_project_repo_root "$(pwd)")
+counsel_config_load "$REPO_ROOT"
+
+if ! counsel_config_enabled; then
+  echo "Counsel is disabled. Set counsel.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+
+PROJECT_KEY=$(counsel_project_key "$(pwd)")
+if [[ -z "$PROJECT_KEY" ]]; then
+  echo "No project key — Counsel needs a git repository (remote or root) to scope briefs. Skipping."
+  exit 0
+fi
+BRIEFS_DIR=$(counsel_project_dir "$PROJECT_KEY")
+```
+
+## Invocation Modes
+
+### `/counsel` — run the weekly review now (default)
+
+Forces a synthesis pass regardless of brief freshness, writes the brief to
+`${ONLOOKER_DIR:-~/.onlooker}/counsel/<project-key>/briefs/<YYYY-WW>.md`, emits
+`counsel.brief.generated`, and renders the result. Re-running in the same ISO
+week overwrites that week's brief in place. (`$ONLOOKER_DIR` overrides the
+storage root; the test suite and non-default installs rely on it.)
+
+```bash
+SESSION_ID="${CLAUDE_SESSION_ID:-$(counsel_ulid)}"
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+LOOKBACK=$(counsel_config_get '.counsel.lookback_days'); LOOKBACK="${LOOKBACK:-30}"
+echo "Running Counsel synthesis over the last ${LOOKBACK} days of events…"
+
+_rc=0
+OUTPUT_PATH=$(counsel_generate_brief "$SESSION_ID" "$(pwd)" force) || _rc=$?
+
+if [[ "$_rc" -eq 2 ]]; then
+  min_events=$(counsel_config_get '.counsel.capture.min_events'); min_events="${min_events:-10}"
+  echo "Not enough events to synthesize a brief (fewer than ${min_events} in the lookback window). Use the ecosystem long enough to accumulate telemetry, then try again."
+  exit 0
+elif [[ "$_rc" -ne 0 || -z "$OUTPUT_PATH" || ! -f "$OUTPUT_PATH" ]]; then
+  echo "Counsel synthesis failed. Check that the \`claude\` CLI is on PATH and the onlooker log is readable."
+  exit 1
+fi
+```
+
+Then render the brief verbatim to the conversation:
+
+```bash
+echo "## Counsel weekly review (\`$(basename "$OUTPUT_PATH" .md)\`)"
+echo ""
+cat "$OUTPUT_PATH"
+echo ""
+echo "_Brief saved to ${OUTPUT_PATH}._"
+```
+
+### `/counsel --show` — print the latest brief (no LLM call)
+
+Renders the most recent brief already on disk. No synthesis, no events emitted.
+
+```bash
+LATEST=$(ls -1 "$BRIEFS_DIR"/*.md 2>/dev/null | sort | tail -1)
+if [[ -z "$LATEST" || ! -f "$LATEST" ]]; then
+  echo "No brief on disk yet for this project. Run \`/counsel\` to generate one."
+  exit 0
+fi
+echo "## Counsel brief (\`$(basename "$LATEST" .md)\`)"
+echo ""
+cat "$LATEST"
+```
+
+### `/counsel --status` — brief freshness
+
+Reports the latest brief's age, last-generated time, and path. No LLM call.
+
+```bash
+INTERVAL=$(counsel_config_get '.counsel.synthesis_interval_days'); INTERVAL="${INTERVAL:-7}"
+LATEST=$(ls -1 "$BRIEFS_DIR"/*.md 2>/dev/null | sort | tail -1)
+
+echo "## Counsel status"
+echo "- Project key: ${PROJECT_KEY}"
+echo "- Briefs dir:  ${BRIEFS_DIR}"
+echo "- Stale after: ${INTERVAL} days"
+
+if [[ -z "$LATEST" || ! -f "$LATEST" ]]; then
+  echo "- Latest brief: none yet (run \`/counsel\`)"
+  exit 0
+fi
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  mtime=$(stat -f '%m' "$LATEST" 2>/dev/null || echo 0)
+  human=$(date -r "$mtime" 2>/dev/null || echo "$mtime")
+else
+  mtime=$(stat -c '%Y' "$LATEST" 2>/dev/null || echo 0)
+  human=$(date -d "@$mtime" 2>/dev/null || echo "$mtime")
+fi
+now=$(date +%s 2>/dev/null || echo "$mtime")
+age_days=$(( (now - mtime) / 86400 ))
+
+echo "- Latest brief: $(basename "$LATEST") (generated ${human}, ${age_days}d ago)"
+if [[ "$age_days" -ge "$INTERVAL" ]]; then
+  echo "- Status: stale — SessionStart will regenerate, or run \`/counsel\` now."
+else
+  echo "- Status: fresh — run \`/counsel\` to force a regeneration anyway."
+fi
+```
+
+## Notes
+
+- The synthesis pass shells out to `claude -p` with the configured
+  `evaluator.model` (default Haiku) — see the plugin README for all config keys.
+- The on-demand path honors the same `capture.min_events` floor as the hook: if
+  too few events fall inside the lookback window, it reports that instead of
+  emitting a thin brief.
+- Output, events, storage layout, and project keying are identical to the
+  SessionStart path — this skill only bypasses the staleness gate.

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

@@ -1,6 +1,6 @@
 {
   "name": "governor",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Resource governance and budget enforcement for the Onlooker ecosystem. Tracks per-session token and cost spend, gates Task spawns before they exceed a configurable budget ceiling, and emits governor.* events for audit. Named for the steam-engine governor — a device that regulates output. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/governor/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.1](https://github.com/onlooker-community/ecosystem/compare/governor-v0.2.0...governor-v0.2.1) (2026-06-10)
+
+
+### Bug Fixes
+
+* vendor portable-lock.sh into cartographer and governor ([#73](https://github.com/onlooker-community/ecosystem/issues/73)) ([ab2c354](https://github.com/onlooker-community/ecosystem/commit/ab2c354b131c26cc642ebb51e84a043dc43cbaa1))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/governor-v0.1.0...governor-v0.2.0) (2026-05-26)
 
 

package/plugins/governor/scripts/hooks/governor-post-tool-use.sh

@@ -24,12 +24,16 @@ 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"
-	# shellcheck disable=SC1091
-	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
 fi
 
 export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
 
+# portable-lock.sh is vendored into this plugin's lib dir so the ledger's
+# atomic appends keep working when governor is installed standalone, where the
+# ecosystem repo's top-level scripts/lib/ is absent from the plugin cache.
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+
 # shellcheck source=../lib/governor-config.sh
 source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
 # shellcheck source=../lib/governor-events.sh

package/plugins/governor/scripts/hooks/governor-pre-tool-use.sh

@@ -36,12 +36,16 @@ 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"
-	# shellcheck disable=SC1091
-	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
 fi
 
 export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
 
+# portable-lock.sh is vendored into this plugin's lib dir so the ledger's
+# atomic appends keep working when governor is installed standalone, where the
+# ecosystem repo's top-level scripts/lib/ is absent from the plugin cache.
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+
 # shellcheck source=../lib/governor-config.sh
 source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
 # shellcheck source=../lib/governor-events.sh

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

@@ -28,12 +28,16 @@ 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"
-	# shellcheck disable=SC1091
-	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
 fi
 
 export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
 
+# portable-lock.sh is vendored into this plugin's lib dir so the ledger's
+# atomic appends keep working when governor is installed standalone, where the
+# ecosystem repo's top-level scripts/lib/ is absent from the plugin cache.
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+
 # shellcheck source=../lib/governor-config.sh
 source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
 # shellcheck source=../lib/governor-events.sh

package/plugins/governor/scripts/hooks/governor-stop.sh

@@ -25,12 +25,16 @@ 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"
-	# shellcheck disable=SC1091
-	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
 fi
 
 export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
 
+# portable-lock.sh is vendored into this plugin's lib dir so the ledger's
+# atomic appends keep working when governor is installed standalone, where the
+# ecosystem repo's top-level scripts/lib/ is absent from the plugin cache.
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+
 # shellcheck source=../lib/governor-config.sh
 source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
 # shellcheck source=../lib/governor-events.sh

package/plugins/governor/scripts/lib/portable-lock.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# portable-lock.sh — vendored copy of the ecosystem substrate's portable lock.
+#
+# Vendored into the governor plugin so the ledger's atomic appends keep
+# working when governor is installed standalone from the marketplace: the
+# cache layout (~/.claude/plugins/cache/<owner>/governor/<version>/) does not
+# include the ecosystem repo's top-level scripts/lib/. Without a local copy,
+# lock_acquire would be undefined and governor_ledger_append would poison the
+# ledger after exhausting its retries. This mirrors the per-plugin vendoring
+# of governor-ulid.sh and friends.
+# Keep in sync with scripts/lib/portable-lock.sh at the repo root.
+#
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see concurrent writes to $ONLOOKER_DIR silently clobber each other.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}

package/scripts/lib/portable-lock.sh

@@ -4,7 +4,7 @@
 # Replaces flock(1), which ships with util-linux on Linux but is not present
 # in stock macOS. This matters because the Onlooker hooks run on user
 # machines, not just in CI: a macOS user without util-linux would otherwise
-# see every PostToolUse history append silently fail.
+# see concurrent writes to $ONLOOKER_DIR silently clobber each other.
 #
 # mkdir() is atomic on POSIX local filesystems, which is the only place
 # $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee

package/test/bats/cartographer-lock.bats

@@ -75,3 +75,22 @@ teardown() {
   [ "$status" -ne 0 ]
   wait
 }
+
+@test "missing vendored portable-lock.sh degrades to a no-op lock, never crashes" {
+  # Copy only the wrapper into an isolated dir WITHOUT its sibling
+  # portable-lock.sh to simulate a broken packaging/path. The cartographer
+  # hooks are fail-soft (exit 0), so sourcing must not abort and acquire must
+  # fail so the caller's `... || exit 0` skips the audit instead of crashing.
+  cp "${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-lock.sh" "${BATS_TEST_TMPDIR}/cartographer-lock.sh"
+  run bash -c "
+    source '${BATS_TEST_TMPDIR}/cartographer-lock.sh'
+    echo SOURCED_OK
+    cartographer_lock_acquire '${BATS_TEST_TMPDIR}/x.lock' && echo ACQUIRED || echo ACQUIRE_FAILED
+    cartographer_lock_release '${BATS_TEST_TMPDIR}/x.lock' && echo RELEASE_OK
+  "
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SOURCED_OK"* ]]
+  [[ "$output" == *"ACQUIRE_FAILED"* ]]
+  [[ "$output" == *"RELEASE_OK"* ]]
+  [[ "$output" == *"locking disabled"* ]]
+}

package/test/bats/counsel-brief.bats

@@ -0,0 +1,167 @@
+#!/usr/bin/env bats
+
+# Exercises counsel_generate_brief's staleness gate and the force bypass the
+# on-demand /counsel skill relies on. The claude CLI is stubbed so synthesis is
+# deterministic and offline.
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/counsel"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-config.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-events.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-ulid.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-synthesize.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-brief.sh"
+
+  # A git work tree so counsel_project_key resolves to a stable root key.
+  WORK="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$WORK"
+  git -C "$WORK" init -q
+  git -C "$WORK" config user.email test@example.com
+  git -C "$WORK" config user.name test
+
+  counsel_config_load "$WORK"
+
+  # Stub the claude CLI: ignore stdin/args, emit a valid synthesis object whose
+  # summary carries a marker we can assert on in the written brief.
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+cat <<'JSON'
+{"summary":"SYNTH_MARKER weekly review","patterns":["pattern one"],"recommendations":[{"title":"do x","rationale":"because y","priority":"high"}],"wins":["win one"],"watch":["watch one"]}
+JSON
+STUB
+  chmod +x "${STUB_BIN}/claude"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  # Event log with comfortably more than min_events records in-window.
+  export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+  mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  : > "$ONLOOKER_EVENTS_LOG"
+  local i
+  for ((i = 0; i < 12; i++)); do
+    printf '%s\n' \
+      "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s${i}\",\"payload\":{}}" \
+      >> "$ONLOOKER_EVENTS_LOG"
+  done
+
+  PROJECT_KEY=$(counsel_project_key "$WORK")
+  BRIEFS_DIR=$(counsel_project_dir "$PROJECT_KEY")
+  mkdir -p "$BRIEFS_DIR"
+}
+
+# ---------------------------------------------------------------------------
+# Staleness gate (default, non-force path used by the SessionStart hook)
+# ---------------------------------------------------------------------------
+
+# counsel_generate_brief prints the brief path on stdout and diagnostics on
+# stderr; capture stdout only so $out is exactly the path.
+gen() {
+  GEN_STATUS=0
+  GEN_OUT=$(counsel_generate_brief "$@" 2>/dev/null) || GEN_STATUS=$?
+}
+
+@test "generate_brief writes a brief when none exists yet" {
+  gen "sess-1" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "generate_brief skips (rc=2) when the latest brief is still fresh" {
+  # A freshly written brief makes counsel_brief_is_stale return false.
+  printf '# old brief\n' > "${BRIEFS_DIR}/2099-01.md"
+  gen "sess-2" "$WORK"
+  [ "$GEN_STATUS" -eq 2 ]
+}
+
+# Bullet lists and the rule in the rendered brief must not be mangled by
+# printf treating a leading dash as an option.
+@test "rendered brief contains intact bullets and horizontal rule" {
+  gen "sess-bullets" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  grep -q '^- pattern one$' "$GEN_OUT"
+  grep -q '^- win one$' "$GEN_OUT"
+  grep -q '^---$' "$GEN_OUT"
+}
+
+# ---------------------------------------------------------------------------
+# Force bypass (on-demand /counsel skill path)
+# ---------------------------------------------------------------------------
+
+@test "force bypasses the staleness gate and regenerates a fresh brief" {
+  printf '# stale-looking but fresh-on-disk brief\n' > "${BRIEFS_DIR}/2099-01.md"
+
+  gen "sess-3" "$WORK" force
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "force accepts the literal \"1\" as well" {
+  printf '# fresh\n' > "${BRIEFS_DIR}/2099-01.md"
+  gen "sess-4" "$WORK" 1
+  [ "$GEN_STATUS" -eq 0 ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "force still respects the min_events floor" {
+  # Only a couple of events — below the default min_events of 10.
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    "{\"event_type\":\"echo.regression.detected\",\"timestamp\":\"${ts}\",\"session_id\":\"s2\",\"payload\":{}}" \
+    > "$ONLOOKER_EVENTS_LOG"
+
+  gen "sess-5" "$WORK" force
+  [ "$GEN_STATUS" -eq 2 ]
+}
+
+# Regression: counsel.brief.generated must validate against the schema and land
+# in the event log. The period bounds are emitted as RFC 3339 date-time strings.
+@test "generated brief emits a schema-valid counsel.brief.generated event" {
+  gen "sess-evt" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  run grep -c '"event_type":"counsel.brief.generated"' "$ONLOOKER_EVENTS_LOG"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+  # period_start must be a full date-time, not a bare calendar date.
+  run grep -o '"period_start":"[^"]*"' "$ONLOOKER_EVENTS_LOG"
+  [[ "$output" == *"T"*"Z"* ]]
+}
+
+# If date cannot produce timestamps the bounds are empty; rather than emit an
+# event that fails schema validation, the emit is skipped and the brief is
+# still written.
+@test "emit is skipped (never invalid) when date cannot produce bounds" {
+  local datestub="${BATS_TEST_TMPDIR}/datebin"
+  mkdir -p "$datestub"
+  printf '#!/usr/bin/env bash\nexit 1\n' > "${datestub}/date"
+  chmod +x "${datestub}/date"
+  PATH="${datestub}:${PATH}"
+
+  gen "sess-nodate" "$WORK" force
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+  # No counsel.brief.generated event should have been appended.
+  run grep -c '"event_type":"counsel.brief.generated"' "$ONLOOKER_EVENTS_LOG"
+  [ "$output" -eq 0 ]
+}