continuous-improvement 3.8.0 → 3.9.2

package/bin/analyze.sh

@@ -1,161 +1,161 @@
-#!/usr/bin/env bash
-# analyze.sh — Read observations.jsonl, detect patterns, create instinct YAML files
-# Runs via /continuous-improvement command. Uses claude CLI with Haiku for cost-efficient analysis.
-
-set -euo pipefail
-
-INSTINCTS_DIR="${HOME}/.claude/instincts"
-
-# ---------------------------------------------------------------------------
-# Detect project
-# ---------------------------------------------------------------------------
-PROJECT_ROOT=""
-if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "${CLAUDE_PROJECT_DIR}" ]]; then
-  PROJECT_ROOT="${CLAUDE_PROJECT_DIR}"
-fi
-if [[ -z "$PROJECT_ROOT" ]]; then
-  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-fi
-if [[ -z "$PROJECT_ROOT" ]]; then
-  PROJECT_ROOT="global"
-fi
-
-# Use shasum on macOS, sha256sum on Linux
-if command -v sha256sum &>/dev/null; then
-  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
-elif command -v shasum &>/dev/null; then
-  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)"
-else
-  # Fallback: use project root basename if no hashing available
-  PROJECT_HASH="$(basename "$PROJECT_ROOT" | tr -cd 'a-zA-Z0-9' | cut -c1-12)"
-fi
-PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
-PROJECT_DIR="${INSTINCTS_DIR}/${PROJECT_HASH}"
-OBS_FILE="${PROJECT_DIR}/observations.jsonl"
-
-# ---------------------------------------------------------------------------
-# Check observations exist
-# ---------------------------------------------------------------------------
-if [[ ! -f "$OBS_FILE" ]] || [[ ! -s "$OBS_FILE" ]]; then
-  echo "No observations found at ${OBS_FILE}"
-  echo "Use Claude Code with hooks installed to generate observations."
-  exit 0
-fi
-
-OBS_COUNT=$(wc -l < "$OBS_FILE")
-echo "Found ${OBS_COUNT} observations in ${OBS_FILE}"
-
-if (( OBS_COUNT < 20 )); then
-  echo "Need at least 20 observations for meaningful analysis. Keep using Claude Code (${OBS_COUNT}/20)."
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# Read existing instincts to avoid duplicates
-# ---------------------------------------------------------------------------
-EXISTING_INSTINCTS=""
-for f in "${PROJECT_DIR}"/*.yaml "${INSTINCTS_DIR}/global"/*.yaml; do
-  [[ -f "$f" ]] && EXISTING_INSTINCTS="${EXISTING_INSTINCTS}$(cat "$f")"$'\n'
-done
-
-# ---------------------------------------------------------------------------
-# Take last 500 observations
-# ---------------------------------------------------------------------------
-RECENT_OBS=$(tail -500 "$OBS_FILE")
-
-# ---------------------------------------------------------------------------
-# Build analysis prompt
-# ---------------------------------------------------------------------------
-ANALYSIS_PROMPT="Analyze these Claude Code session observations and extract behavioral patterns as instinct YAML files.
-
-OBSERVATIONS (JSONL — each line is a tool call):
-${RECENT_OBS}
-
-EXISTING INSTINCTS (already learned — do NOT duplicate these):
-${EXISTING_INSTINCTS}
-
-YOUR TASK:
-1. Look for REPEATED PATTERNS — same tool sequence used 3+ times
-2. Look for ERROR-THEN-FIX sequences — tool fails, next tools fix it
-3. Look for TOOL PREFERENCES — one tool consistently chosen over alternatives
-4. Look for WORKFLOW PATTERNS — consistent ordering of operations
-5. Look for USER CORRECTIONS — user says no/stop/don't after an action
-
-OUTPUT FORMAT — output ONLY new instincts as YAML blocks, separated by ---:
-
-id: descriptive-kebab-case-id
-trigger: \"when [specific situation]\"
-confidence: 0.5
-domain: workflow|tooling|testing|patterns
-source: observation
-scope: project
-project_id: ${PROJECT_HASH}
-created: \"$(date -u +%Y-%m-%d)\"
-last_seen: \"$(date -u +%Y-%m-%d)\"
-observation_count: [number of times pattern was seen]
----
-[One sentence describing the specific actionable behavior]
-
-Rules:
-- Only create instincts for patterns seen 3+ times
-- Start confidence at 0.5 (suggest level)
-- Be specific and actionable (not vague advice)
-- Different from existing instincts listed above
-
-If no new patterns are found, output exactly: NO_NEW_PATTERNS
-
-Output ONLY the YAML blocks or NO_NEW_PATTERNS. No explanation, no preamble."
-
-# ---------------------------------------------------------------------------
-# Run analysis with Haiku
-# ---------------------------------------------------------------------------
-echo "Analyzing patterns with Haiku..."
-RESULT=$(echo "$ANALYSIS_PROMPT" | claude --model haiku --print -p - 2>/dev/null) || {
-  echo "Analysis failed — claude CLI error. Try running manually."
-  exit 1
-}
-
-if [[ "$RESULT" == "NO_NEW_PATTERNS" ]] || [[ -z "$RESULT" ]]; then
-  echo "No new patterns detected yet. Keep using Claude Code — patterns emerge over time."
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# Write instinct YAML files
-# ---------------------------------------------------------------------------
-mkdir -p "$PROJECT_DIR"
-
-NEW_COUNT=0
-INSTINCT_ID=""
-BLOCK=""
-
-while IFS= read -r line; do
-  if [[ "$line" == "---" ]] && [[ -n "$BLOCK" ]]; then
-    if [[ -n "$INSTINCT_ID" ]]; then
-      DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
-      printf '%s\n' "$BLOCK" > "$DEST"
-      echo "  + ${INSTINCT_ID} -> ${DEST}"
-      NEW_COUNT=$((NEW_COUNT + 1))
-    fi
-    INSTINCT_ID=""
-    BLOCK=""
-  else
-    BLOCK="${BLOCK}${line}"$'\n'
-    if [[ "$line" =~ ^id:\ (.+) ]]; then
-      INSTINCT_ID="${BASH_REMATCH[1]}"
-      INSTINCT_ID="${INSTINCT_ID//\"/}"
-      INSTINCT_ID="${INSTINCT_ID//\'/}"
-    fi
-  fi
-done <<< "$RESULT"
-
-# Handle last block
-if [[ -n "$INSTINCT_ID" ]] && [[ -n "$BLOCK" ]]; then
-  DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
-  printf '%s\n' "$BLOCK" > "$DEST"
-  echo "  + ${INSTINCT_ID} -> ${DEST}"
-  NEW_COUNT=$((NEW_COUNT + 1))
-fi
-
-echo ""
-echo "Created ${NEW_COUNT} new instinct(s) in ${PROJECT_DIR}/"
+#!/usr/bin/env bash
+# analyze.sh — Read observations.jsonl, detect patterns, create instinct YAML files
+# Runs via /continuous-improvement command. Uses claude CLI with Haiku for cost-efficient analysis.
+
+set -euo pipefail
+
+INSTINCTS_DIR="${HOME}/.claude/instincts"
+
+# ---------------------------------------------------------------------------
+# Detect project
+# ---------------------------------------------------------------------------
+PROJECT_ROOT=""
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "${CLAUDE_PROJECT_DIR}" ]]; then
+  PROJECT_ROOT="${CLAUDE_PROJECT_DIR}"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="global"
+fi
+
+# Use shasum on macOS, sha256sum on Linux
+if command -v sha256sum &>/dev/null; then
+  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
+elif command -v shasum &>/dev/null; then
+  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)"
+else
+  # Fallback: use project root basename if no hashing available
+  PROJECT_HASH="$(basename "$PROJECT_ROOT" | tr -cd 'a-zA-Z0-9' | cut -c1-12)"
+fi
+PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
+PROJECT_DIR="${INSTINCTS_DIR}/${PROJECT_HASH}"
+OBS_FILE="${PROJECT_DIR}/observations.jsonl"
+
+# ---------------------------------------------------------------------------
+# Check observations exist
+# ---------------------------------------------------------------------------
+if [[ ! -f "$OBS_FILE" ]] || [[ ! -s "$OBS_FILE" ]]; then
+  echo "No observations found at ${OBS_FILE}"
+  echo "Use Claude Code with hooks installed to generate observations."
+  exit 0
+fi
+
+OBS_COUNT=$(wc -l < "$OBS_FILE")
+echo "Found ${OBS_COUNT} observations in ${OBS_FILE}"
+
+if (( OBS_COUNT < 20 )); then
+  echo "Need at least 20 observations for meaningful analysis. Keep using Claude Code (${OBS_COUNT}/20)."
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Read existing instincts to avoid duplicates
+# ---------------------------------------------------------------------------
+EXISTING_INSTINCTS=""
+for f in "${PROJECT_DIR}"/*.yaml "${INSTINCTS_DIR}/global"/*.yaml; do
+  [[ -f "$f" ]] && EXISTING_INSTINCTS="${EXISTING_INSTINCTS}$(cat "$f")"$'\n'
+done
+
+# ---------------------------------------------------------------------------
+# Take last 500 observations
+# ---------------------------------------------------------------------------
+RECENT_OBS=$(tail -500 "$OBS_FILE")
+
+# ---------------------------------------------------------------------------
+# Build analysis prompt
+# ---------------------------------------------------------------------------
+ANALYSIS_PROMPT="Analyze these Claude Code session observations and extract behavioral patterns as instinct YAML files.
+
+OBSERVATIONS (JSONL — each line is a tool call):
+${RECENT_OBS}
+
+EXISTING INSTINCTS (already learned — do NOT duplicate these):
+${EXISTING_INSTINCTS}
+
+YOUR TASK:
+1. Look for REPEATED PATTERNS — same tool sequence used 3+ times
+2. Look for ERROR-THEN-FIX sequences — tool fails, next tools fix it
+3. Look for TOOL PREFERENCES — one tool consistently chosen over alternatives
+4. Look for WORKFLOW PATTERNS — consistent ordering of operations
+5. Look for USER CORRECTIONS — user says no/stop/don't after an action
+
+OUTPUT FORMAT — output ONLY new instincts as YAML blocks, separated by ---:
+
+id: descriptive-kebab-case-id
+trigger: \"when [specific situation]\"
+confidence: 0.5
+domain: workflow|tooling|testing|patterns
+source: observation
+scope: project
+project_id: ${PROJECT_HASH}
+created: \"$(date -u +%Y-%m-%d)\"
+last_seen: \"$(date -u +%Y-%m-%d)\"
+observation_count: [number of times pattern was seen]
+---
+[One sentence describing the specific actionable behavior]
+
+Rules:
+- Only create instincts for patterns seen 3+ times
+- Start confidence at 0.5 (suggest level)
+- Be specific and actionable (not vague advice)
+- Different from existing instincts listed above
+
+If no new patterns are found, output exactly: NO_NEW_PATTERNS
+
+Output ONLY the YAML blocks or NO_NEW_PATTERNS. No explanation, no preamble."
+
+# ---------------------------------------------------------------------------
+# Run analysis with Haiku
+# ---------------------------------------------------------------------------
+echo "Analyzing patterns with Haiku..."
+RESULT=$(echo "$ANALYSIS_PROMPT" | claude --model haiku --print -p - 2>/dev/null) || {
+  echo "Analysis failed — claude CLI error. Try running manually."
+  exit 1
+}
+
+if [[ "$RESULT" == "NO_NEW_PATTERNS" ]] || [[ -z "$RESULT" ]]; then
+  echo "No new patterns detected yet. Keep using Claude Code — patterns emerge over time."
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Write instinct YAML files
+# ---------------------------------------------------------------------------
+mkdir -p "$PROJECT_DIR"
+
+NEW_COUNT=0
+INSTINCT_ID=""
+BLOCK=""
+
+while IFS= read -r line; do
+  if [[ "$line" == "---" ]] && [[ -n "$BLOCK" ]]; then
+    if [[ -n "$INSTINCT_ID" ]]; then
+      DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
+      printf '%s\n' "$BLOCK" > "$DEST"
+      echo "  + ${INSTINCT_ID} -> ${DEST}"
+      NEW_COUNT=$((NEW_COUNT + 1))
+    fi
+    INSTINCT_ID=""
+    BLOCK=""
+  else
+    BLOCK="${BLOCK}${line}"$'\n'
+    if [[ "$line" =~ ^id:\ (.+) ]]; then
+      INSTINCT_ID="${BASH_REMATCH[1]}"
+      INSTINCT_ID="${INSTINCT_ID//\"/}"
+      INSTINCT_ID="${INSTINCT_ID//\'/}"
+    fi
+  fi
+done <<< "$RESULT"
+
+# Handle last block
+if [[ -n "$INSTINCT_ID" ]] && [[ -n "$BLOCK" ]]; then
+  DEST="${PROJECT_DIR}/${INSTINCT_ID}.yaml"
+  printf '%s\n' "$BLOCK" > "$DEST"
+  echo "  + ${INSTINCT_ID} -> ${DEST}"
+  NEW_COUNT=$((NEW_COUNT + 1))
+fi
+
+echo ""
+echo "Created ${NEW_COUNT} new instinct(s) in ${PROJECT_DIR}/"

package/bin/backfill.mjs

@@ -27,25 +27,25 @@ const args = process.argv.slice(2);
 const DRY_RUN = args.includes("--dry-run");
 const HELP = args.includes("--help") || args.includes("-h");
 if (HELP) {
-    console.log(`
-backfill — Tag legacy thin-schema observation rows.
-
-Usage:
-  npx continuous-improvement backfill            Tag rows in place
-  npx continuous-improvement backfill --dry-run  Report counts, write nothing
-
-What it does:
-  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
-  schema field ("thin" or "rich") to every row that lacks one. Thin rows
-  came from the legacy bash fallback (jq missing) and have no input_summary;
-  rich rows came from the Node observer and have full tool_input.command /
-  Edit.file_path / etc.
-
-Output:
-  - observations.jsonl rewritten in place (original kept as .bak)
-  - backfill-summary.json with per-project counts
-
-Idempotent. Always exits 0 — failures go to stderr only.
+    console.log(`
+backfill — Tag legacy thin-schema observation rows.
+
+Usage:
+  npx continuous-improvement backfill            Tag rows in place
+  npx continuous-improvement backfill --dry-run  Report counts, write nothing
+
+What it does:
+  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
+  schema field ("thin" or "rich") to every row that lacks one. Thin rows
+  came from the legacy bash fallback (jq missing) and have no input_summary;
+  rich rows came from the Node observer and have full tool_input.command /
+  Edit.file_path / etc.
+
+Output:
+  - observations.jsonl rewritten in place (original kept as .bak)
+  - backfill-summary.json with per-project counts
+
+Idempotent. Always exits 0 — failures go to stderr only.
 `);
     process.exit(0);
 }

package/bin/check-doc-runtime-claims.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Doc Runtime-Claims Check
+ *
+ * Codifies the audit-twice rule (memory: feedback_grep_hook_before_claim).
+ *
+ * Any user-facing line that claims a runtime hook / PreToolUse gate /
+ * physical block must be accompanied by a `hooks/<file>.mjs` reference
+ * inside a ±5-line window. Without that anchor, the doc is making a
+ * claim a future reader cannot verify against the actual filesystem.
+ *
+ * Origin: PR #105 shipped a smoke test that promised gateguard would
+ * physically block, when the hook did not yet exist. PR #108 built the
+ * hook. PR #115 reverted the inverse drift after the hook shipped but
+ * docs still said "roadmap." This lint locks the audit-twice rule into
+ * automation so the next runtime claim cannot land without its anchor.
+ *
+ * Scope: QUICKSTART.md, README.md, skills/*.md.
+ * Out of scope: bundle mirrors under plugins/, docs/, third-party/.
+ *
+ * Trigger phrases (case-insensitive substring match on the line):
+ *   - "PreToolUse hook"
+ *   - "physically block"   (catches "physically blocks", "physical block")
+ *   - "runtime gate"
+ *
+ * Deliberately narrow per the spec that authorized this lint. "runtime
+ * hook" was considered and dropped: too prone to false positives on
+ * disclaimers ("not a runtime hook", "no runtime hook is bundled").
+ * Future trigger additions need an explicit owner decision; do not bolt
+ * on phrases just because they sound related.
+ *
+ * Anchor: any reference matching `hooks/<name>.mjs` (case-insensitive)
+ * inside the ±5-line window (the trigger line itself plus 5 lines above
+ * and 5 lines below).
+ *
+ * Usage:
+ *   node bin/check-doc-runtime-claims.mjs              # Check the current repo
+ *   node bin/check-doc-runtime-claims.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every runtime-claim line has an in-window hooks/ anchor
+ *   1 — at least one claim line is unanchored
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const SCAN_FILES = ["QUICKSTART.md", "README.md"];
+const SCAN_SKILL_DIR = "skills";
+const ANCHOR_WINDOW = 5;
+const TRIGGER_PHRASES = [
+    "pretooluse hook",
+    "physically block",
+    "runtime gate",
+];
+const ANCHOR_PATTERN = /hooks\/[a-z0-9-]+\.mjs/i;
+function listSkillFiles(repoRoot) {
+    const skillsDir = join(repoRoot, SCAN_SKILL_DIR);
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((f) => /^[a-z][a-z0-9-]*\.md$/.test(f))
+        .map((f) => join(SCAN_SKILL_DIR, f))
+        .sort();
+}
+function scanFile(repoRoot, relPath) {
+    const fullPath = join(repoRoot, relPath);
+    let content;
+    try {
+        content = readFileSync(fullPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split(/\r?\n/);
+    const violations = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const lower = lines[i].toLowerCase();
+        const matchedPhrase = TRIGGER_PHRASES.find((p) => lower.includes(p));
+        if (!matchedPhrase)
+            continue;
+        const start = Math.max(0, i - ANCHOR_WINDOW);
+        const end = Math.min(lines.length - 1, i + ANCHOR_WINDOW);
+        const window = lines.slice(start, end + 1).join("\n");
+        if (ANCHOR_PATTERN.test(window))
+            continue;
+        violations.push({
+            file: relPath,
+            line: i + 1,
+            text: lines[i].trim(),
+        });
+    }
+    return violations;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const files = [...SCAN_FILES, ...listSkillFiles(repoRoot)];
+    const allViolations = [];
+    for (const file of files) {
+        allViolations.push(...scanFile(repoRoot, file));
+    }
+    if (allViolations.length === 0) {
+        console.log(`OK doc-runtime-claims: every runtime-claim line in ${files.length} scanned file(s) has a hooks/<name>.mjs anchor within ±${ANCHOR_WINDOW} lines.`);
+        exit(0);
+    }
+    console.error(`FAIL doc-runtime-claims: ${allViolations.length} unanchored runtime-claim line(s) found.`);
+    console.error(`Each line below contains a runtime-claim phrase but has no hooks/<name>.mjs reference within ±${ANCHOR_WINDOW} lines.`);
+    console.error("Add the hook file path inline so a reader can verify the claim against the filesystem.");
+    console.error("");
+    for (const v of allViolations) {
+        console.error(`  ${v.file}:${v.line}`);
+        console.error(`    ${v.text}`);
+    }
+    exit(1);
+}
+main();

package/bin/generate-plugin-manifests.mjs

@@ -80,6 +80,7 @@ async function writePluginBundleReadme() {
         "- `.claude-plugin/marketplace.json`",
         "- `skills/`",
         "- `commands/`",
+        "- `agents/` — `code-reviewer`, `security-auditor`, `test-engineer` personas (auto-discovered Claude Code subagents; pattern from addy/agent-skills)",
         "- `hooks/`",
         "- `bin/mcp-server.mjs`",
         "- `bin/observe.mjs`",
@@ -137,6 +138,7 @@ async function writePluginBundle() {
         writeJson(join(PLUGIN_BUNDLE_DIR, ".claude-plugin", "plugin.json"), getClaudePluginManifest()),
         writeJson(join(PLUGIN_BUNDLE_DIR, ".claude-plugin", "marketplace.json"), getClaudePluginMarketplaceManifest()),
         copyDirectory(join(REPO_ROOT, "commands"), join(PLUGIN_BUNDLE_DIR, "commands")),
+        copyDirectory(join(REPO_ROOT, "agents"), join(PLUGIN_BUNDLE_DIR, "agents")),
         copyDirectory(join(REPO_ROOT, "hooks"), join(PLUGIN_BUNDLE_DIR, "hooks")),
         copyDirectory(join(REPO_ROOT, "instinct-packs"), join(PLUGIN_BUNDLE_DIR, "instinct-packs")),
         copyDirectory(join(REPO_ROOT, "templates", "planning-with-files"), join(PLUGIN_BUNDLE_DIR, "templates", "planning-with-files")),

package/bin/hook-stats.mjs

@@ -46,27 +46,27 @@ import { platform } from "node:os";
 import { join } from "node:path";
 import { argv, cwd, exit, stderr, stdout } from "node:process";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
-const USAGE = `Usage: node bin/hook-stats.mjs [options]
-
-Reads JSONL telemetry from <HOME>/.claude/hook-telemetry/*.jsonl and
-prints per-hook aggregate counts over a recent time window.
-
-Options:
-  --hours=<n>            Time window in hours (default: 24)
-  --hash=<hash>          Only read this single <hash>.jsonl file
-                         (default: sha256 of the current working directory,
-                         normalized to forward slashes and lowercased on
-                         Windows, then first 12 hex chars)
-  --telemetry-dir=<path> Override telemetry dir
-                         (default: <HOME>/.claude/hook-telemetry)
-  --help                 Show this help and exit 0
-
-Output:
-  One line per hook: "<hook> last <hours>h: pass=<n> block=<n>
-  skip-short=<n> total=<n> avg-duration=<X>ms".
-  If there are no records in the window: "no records in last <hours>h".
-
-The reader is parse-tolerant: malformed JSONL lines are skipped silently.
+const USAGE = `Usage: node bin/hook-stats.mjs [options]
+
+Reads JSONL telemetry from <HOME>/.claude/hook-telemetry/*.jsonl and
+prints per-hook aggregate counts over a recent time window.
+
+Options:
+  --hours=<n>            Time window in hours (default: 24)
+  --hash=<hash>          Only read this single <hash>.jsonl file
+                         (default: sha256 of the current working directory,
+                         normalized to forward slashes and lowercased on
+                         Windows, then first 12 hex chars)
+  --telemetry-dir=<path> Override telemetry dir
+                         (default: <HOME>/.claude/hook-telemetry)
+  --help                 Show this help and exit 0
+
+Output:
+  One line per hook: "<hook> last <hours>h: pass=<n> block=<n>
+  skip-short=<n> total=<n> avg-duration=<X>ms".
+  If there are no records in the window: "no records in last <hours>h".
+
+The reader is parse-tolerant: malformed JSONL lines are skipped silently.
 `;
 function parseArgs(rawArgs) {
     const opts = {