@delorenj/pjangler 1.1.5 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delorenj/pjangler",
-  "version": "1.1.5",
+  "version": "1.2.2",
   "description": "Project subsystem bootstrapper CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
   "files": [
     "dist",
     "templates",
-    ".mise/scripts/versioning.sh"
+    ".mise/scripts/versioning.sh",
+    ".mise/scripts/link-agentfiles.sh"
   ],
   "engines": {
     "node": ">=20"
@@ -22,6 +23,7 @@
     "start": "node dist/index.js",
     "mcp": "node dist/mcp-server.js",
     "typecheck": "tsc --noEmit",
+    "test": "node tests/parity-migrate-regressions.mjs && node tests/mcp-catalog-regressions.mjs && node tests/mcp-server-regressions.mjs && node tests/project-registry-regressions.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -37,6 +39,7 @@
     "@clack/prompts": "^1.4.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.2",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/commonproject/.mise/scripts/create-plane-project.sh

@@ -59,6 +59,32 @@ PLANE_BASE_URL="${PLANE_BASE_URL:-https://plane.delo.sh}"
     echo "  Identifier: $PROJECT_IDENTIFIER"
 } >&2
 
+# ── Find-or-link by NAME first (repo name is the primary key) ────────────────
+# Plane does NOT enforce unique project names, so a bare POST would create a
+# DUPLICATE whenever a board of this name already exists (an earlier init, or
+# the hermes-agent flow). Search by name and reuse the match before creating.
+NAME_LIST=$(curl -s -X GET \
+    "${PLANE_BASE_URL}/api/v1/workspaces/${WORKSPACE}/projects/?per_page=200" \
+    -H "X-Api-Key: ${PLANE_API_KEY}" \
+    -H "Content-Type: application/json")
+EXISTING_BY_NAME=$(echo "$NAME_LIST" | PLANE_NAME="$PROJECT_NAME" python3 -c "
+import json, os, sys
+want = os.environ['PLANE_NAME'].strip().lower()
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+items = data.get('results', data) if isinstance(data, dict) else data
+for p in items or []:
+    if str(p.get('name', '')).strip().lower() == want:
+        print(p['id']); break
+" 2>/dev/null || true)
+if [[ -n "$EXISTING_BY_NAME" ]]; then
+    echo -e "${GREEN}✓ Linking existing Plane project by name '${PROJECT_NAME}' (id=${EXISTING_BY_NAME})${NC}" >&2
+    echo "$EXISTING_BY_NAME"
+    exit 0
+fi
+
 # Create project via Plane API
 RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
     "${PLANE_BASE_URL}/api/v1/workspaces/${WORKSPACE}/projects/" \

package/templates/commonproject/copier.yml

@@ -83,6 +83,8 @@ primary_language:
 
 _tasks:
   - "cp ~/.config/git/ignore .gitignore 2>/dev/null || echo '# Add ignores here' > .gitignore"
+  # Ensure secrets + per-dev agent-hook/skill overrides are ignored (appended after the base ignore).
+  - "printf '\\n# Secrets + per-dev agent-hook/skill overrides (see .agents/local.example.json)\\n.env\\n.env.*\\n!.env.op\\n.agents/local.json\\n.kimi-code/\\n.lastagent\\n**/.claude/settings.local.json\\n' >> .gitignore"
   - "ln -sf AGENTS.md CLAUDE.md"
   - "ln -sf AGENTS.md GEMINI.md"
   # Stamp the repo's absolute path into .project.json (the SOT) post-render.

package/templates/commonproject/template/.agents/hooks/README.md

@@ -0,0 +1,151 @@
+# Project-scoped agent hooks
+
+Agent hooks auto-installed for **every dev** in this repo, fanned out to each
+agent CLI (Claude Code, Codex, Hermes) from one source of truth — with a per-dev
+opt-out and shared Hindsight credentials.
+
+This is the [`/ssot-fanout`](https://github.com/delorenj/skillex) pattern, lean
+variant: **`hooks.master.json` is the only file you hand-edit**; every per-agent
+config is generated by `sync.py` and is idempotent (re-running with an unchanged
+master writes zero bytes).
+
+## TL;DR
+
+```bash
+mise run hooks-sync          # fan out the master -> claude + codex + hermes
+mise run hooks-check         # drift gate (read-only; used in CI)
+mise run hooks-uninstall     # remove codex + hermes injections
+mise run hindsight-setup     # one-time: pull the shared CAF Hindsight key into .env
+```
+
+You normally run nothing — `mise` does it on directory enter/leave (see
+[mise.toml](../../mise.toml) `[hooks]`).
+
+## What gets installed where
+
+| Agent | Target | Scope | When |
+|---|---|---|---|
+| **Claude Code** | committed `.claude/settings.json` (`hooks` key, `$CLAUDE_PROJECT_DIR`) | project, committed | nothing to do — every clone gets it |
+| **Codex** | per-user `~/.codex/hooks.json` (absolute-path entries) | per-user, injected | `mise enter` → inject, `mise leave` → remove |
+| **Kimi** | per-user `~/.kimi-code/config.toml` (sentinel `[[hooks]]` block) | per-user, injected | `mise enter` → inject, `mise leave` → remove |
+| **Hermes** | runtime `config.yaml` `hooks:` + `shell-hooks-allowlist.json`, via an **adapter** | per-deployment | `mise enter` merges (idempotent, backed up) |
+
+**Kimi** is fully Claude-compatible (identical event names; payload `{prompt}` /
+`{tool_name, tool_input}` on stdin; `shell:true` commands; edit tools `Write`/`Edit`),
+so it **reuses the same guard-wrapped scripts** as Claude/Codex — just injected as a
+sentinel-bounded `[[hooks]]` block in the per-user `config.toml` (timeout in seconds;
+`KIMI_CODE_HOME` respected; backed up to `config.toml.caf-bak`; byte-exact reversible).
+
+Each injection is **surgical & reversible** — `sync.py` only touches entries
+whose command points at this repo's `.agents/hooks/`, backs up before its first
+write (`*.caf-bak`), and an uninstall restores the original data.
+
+## The hooks
+
+| id | lifecycle → event | script | notes |
+|---|---|---|---|
+| `skill-check-reminder` | user prompt | `reminder-for-skill-check.sh` | project-skills + BMAD-recap nudge (path resolved relative to itself → portable) |
+| `hindsight-recall` | user prompt | `hindsight/hindsight-recall.sh` | recalls memory; no-ops gracefully without the `hindsight` CLI |
+| `hindsight-retain` | post-tool (`Write\|Edit\|MultiEdit`) | `hindsight/hindsight-retain.sh` | retains file edits |
+| `hindsight-session-end` | session end / stop | `hindsight/hindsight-session-end.sh` | session summary + journal |
+
+### Hermes uses an adapter, not the raw scripts
+
+Hermes runs hooks `shell=False` with the payload as JSON on stdin, has **no
+user-prompt event**, and uses different `tool_input` keys than Claude. So the
+Claude-shaped scripts would misparse. Instead Hermes calls
+[`hermes/hindsight-hook.sh <event>`](hermes/hindsight-hook.sh), which translates
+the Hermes payload and **pins the `CoachingAgentFramework` bank** (bank
+auto-resolution from the Hermes runtime cwd would resolve to the PM *submodule*).
+Wired: `post_tool_call` → retain, `on_session_end` → session marker. Recall is
+not wired (no event to attach to).
+
+## Per-dev opt-out — `.agents/local.json`
+
+Copy [`.agents/local.example.json`](../local.example.json) → `.agents/local.json`
+(gitignored) to disable things **just for you**:
+
+```jsonc
+{
+  "hooks": {
+    "disabled": ["hindsight-recall"],   // hook ids — skipped at runtime, ALL agents
+    "disabled_agents": ["codex"]        // claude|codex|hermes — codex/hermes injection skipped/removed
+  },
+  "skills": { "disabled": ["bmad-help"] } // skill dir names — not symlinked for you
+}
+```
+
+- **Disabled hooks** are enforced at **runtime** by
+  [`lib/hook-guard.sh`](lib/hook-guard.sh) — the committed Claude command is the
+  *guarded* form (`hook-guard.sh <id> <real-hook>`), which execs the hook unless
+  your `local.json` disables its id, in which case it exits 0 silently. This is
+  how you opt out of a hook whose config is committed and shared.
+- **Disabled agents** are enforced at **install** time (codex/hermes injection is
+  skipped, and removed if previously installed). `CAF_HOOKS_SKIP_CODEX=1` is an
+  env shortcut for `disabled_agents:["codex"]`.
+- **Disabled skills** are honored by the skill fan-out (below).
+
+## Skill fan-out — `.agents/skills` → each CLI
+
+`.agents/skills/` is the project's enabled skill set (committed inherited skills +
+`./skills/*` app skills symlinked in on enter). `link-project-skills-to-clis.sh`
+fans it out as per-skill symlinks to every agent CLI that doesn't read `.agents/`
+natively — a small `SKILL_TARGETS` table:
+
+| CLI | target dir | scope |
+|---|---|---|
+| Codex | `~/.codex/skills` | **global** — link ours in, never clobber foreign entries, removed on `leave` |
+| Kimi | `./.kimi-code/skills` | **local** — a project-scoped mirror we fully manage (stale real copies replaced with symlinks) |
+
+Add a CLI = one `dir|scope` line. Per-dev control via `.agents/local.json`
+`skills`:
+
+- `disabled: [...]` — never link these; pruned from managed mirrors.
+- `defer_to_global: true` — **only if you run a global `~/.agents/skills` system.**
+  Skips any project skill whose name also exists there, so your global copy wins
+  and you get **zero duplicates** (it even yields the slot in `~/.codex/skills`).
+  Teammates with no global layer leave it `false` (default) and **inherit the full
+  set**. Override the global dir with `AGENTS_GLOBAL_SKILLS_DIR`.
+
+Tasks: `mise run skills-relink` (re-fan), `mise run link-project-skills-to-clis`,
+`mise run unlink-project-skills-from-clis`.
+
+## Hindsight credentials — `mise run hindsight-setup`
+
+The hooks shell out to `hindsight`, which needs an API key for the self-hosted
+instance. Strategy: **one shared CAF-scoped key in 1Password**. `hindsight-setup`
+resolves it via `op` and writes `HINDSIGHT_API_URL` + `HINDSIGHT_API_KEY` into the
+gitignored `.env` (mise loads it, env vars outrank `~/.hindsight/config`). Point
+it at the right item if the default ref is wrong:
+
+```bash
+HINDSIGHT_OP_KEY_REF="op://DeLoSecrets/<item>/<field>" mise run hindsight-setup
+```
+
+Without a key the hooks **no-op gracefully** — recall/retain just do nothing.
+
+## Adding / changing a hook
+
+1. Edit `hooks.master.json`.
+2. `mise run hooks-sync`.
+3. Commit the master **and** the regenerated `.claude/settings.json` together
+   (codex/hermes targets are per-dev/per-deployment, not committed).
+4. CI runs `mise run hooks-check` — fails if the committed Claude settings drift.
+
+## Files
+
+```
+.agents/
+  local.example.json    # per-dev override template (copy -> local.json, gitignored)
+  hooks/
+    hooks.master.json   # SSOT — the only hand-edited config
+    sync.py             # fan-out engine (--install / --uninstall / --check)
+    reminder-for-skill-check.sh
+    hindsight/          # recall / retain / session-end + journal writer + lib/
+    hermes/             # hindsight-hook.sh — the Hermes payload adapter
+    lib/                # local-config.sh (override helpers) + hook-guard.sh (runtime guard)
+    README.md
+```
+
+`gitmark/` holds standalone git helpers — committed for convenience, **not** part
+of the agent-hook fan-out.

package/templates/commonproject/template/.agents/hooks/hermes/hindsight-hook.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Hermes -> Hindsight adapter.
+#
+# Hermes fires shell hooks with the payload piped as JSON on stdin:
+#   {"hook_event_name","tool_name","tool_input","session_id","cwd","extra"}
+# and runs the command shell=False (argv), so this is invoked as:
+#   hindsight-hook.sh <on_session_end|post_tool_call>
+#
+# Why an adapter (not the Claude hindsight scripts verbatim):
+#   - Hermes has NO user-prompt event, so recall has no attach point here.
+#   - Hermes tool_input keys differ from Claude's (.file_path/.new_string).
+#   - resolve_bank() from the Hermes runtime cwd would resolve to the PM
+#     SUBMODULE, not this repo — so we PIN the CoachingAgentFramework bank.
+#
+# Fire-and-forget; never blocks Hermes. No-ops gracefully without the CLI.
+set -uo pipefail
+
+EVENT="${1:-}"
+HERMES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # .agents/hooks/hermes
+REPO_ROOT="$(cd "${HERMES_DIR}/../../.." && pwd)"            # the project repo (NOT the PM submodule)
+
+# Per-dev opt-out: reuse the SAME hook ids as the other agents so one
+# local.json entry disables a hook everywhere.
+# shellcheck source=../lib/local-config.sh
+source "${HERMES_DIR}/../lib/local-config.sh"
+
+HS_BIN="${HOME}/.local/bin/hindsight"
+[[ -x "$HS_BIN" ]] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT="$(cat 2>/dev/null || echo '{}')"
+# Pin the project bank = repo basename (resolve_bank from the hermes runtime cwd
+# would resolve to the PM submodule). Generic across projects; HINDSIGHT_BANK overrides.
+BANK="${HINDSIGHT_BANK:-$(basename "$REPO_ROOT")}"
+
+retain_detached() {  # retain_detached <context> <text>
+  setsid nohup timeout 20 "$HS_BIN" memory retain "$BANK" "$2" --context "$1" \
+    < /dev/null > /dev/null 2>&1 &
+  disown 2>/dev/null || true
+}
+
+case "$EVENT" in
+  post_tool_call)
+    hook_disabled "hindsight-retain" && exit 0
+    tool=$(jq -r '.tool_name // "tool"' <<<"$INPUT" 2>/dev/null || echo tool)
+    path=$(jq -r '.tool_input.file_path // .tool_input.path // .tool_input.filename // .tool_input.file // empty' <<<"$INPUT" 2>/dev/null || echo "")
+    content=$(jq -r '.tool_input.new_string // .tool_input.content // .tool_input.text // empty' <<<"$INPUT" 2>/dev/null || echo "")
+    # Only retain file-ish edits; skip pure reads/terminal noise.
+    [[ -z "$path" && -z "$content" ]] && exit 0
+    snippet=$(printf '%s' "$content" | head -3 | tr '\n' ' ' | cut -c1-200)
+    retain_detached "code-edit" "Hermes ${tool} edited ${path:-<no-path>}: ${snippet}"
+    ;;
+  on_session_end)
+    hook_disabled "hindsight-session-end" && exit 0
+    sid=$(jq -r '.session_id // "unknown"' <<<"$INPUT" 2>/dev/null || echo unknown)
+    retain_detached "session-summary" "Hermes PM session ${sid} ended at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    ;;
+  *)
+    : # unknown / unmapped event -> no-op
+    ;;
+esac
+
+exit 0

package/templates/commonproject/template/.agents/hooks/hindsight/hindsight-journal-write.sh

@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+# Hindsight Journal writer — invoked at session-end (Stop hook).
+#
+# Reads ~/.agents/journal/sessions/<session_id>.jsonl, synthesizes
+# a plain-English journal entry covering the 6-section spec, and writes it to
+# ~/.agents/journal/YYYY-mm-dd-h-m-s.md.
+#
+# Sections:
+#   1. Search terms elicited & how they were selected
+#   2. Why hindsight was skipped (if it was)
+#   3. Bank resolved (incl. linked-bank fanout)
+#   4. Effectiveness of returned data (LLM-reflected)
+#   5. What could have been done differently (LLM-reflected)
+#   6. What was retained — both telemetry + LLM-reflected rationale
+#
+# Inputs:
+#   - stdin: Claude Code Stop hook JSON ({session_id, transcript_path, ...})
+#
+# Env knobs:
+#   HS_JOURNAL_DIR              Override journal root (default: ~/.agents/journal)
+#   HS_JOURNAL_REFLECT          0 to skip the LLM-reflection step (default: 1)
+#   HS_JOURNAL_REFLECT_BUDGET   low|mid|high (default: low)
+#   HS_JOURNAL_REFLECT_BANK     Bank to reflect into; default: bank of cwd
+#   HS_JOURNAL_REFLECT_DEBOUNCE_SECONDS  Min seconds between reflect calls per session (default: 240).
+#                                        Claude Code's Stop hook fires on every turn, not just session-close,
+#                                        so without this we'd burn an LLM call per response.
+#   HS_JOURNAL_KEEP_TELEMETRY   1 to keep per-session JSONL after write; default: 1
+#
+# Exit codes: always 0 (fire-and-forget; hook failures must not break Stop).
+
+set -uo pipefail
+
+HS_BIN="${HOME}/.local/bin/hindsight"
+HS_JOURNAL_DIR="${HS_JOURNAL_DIR:-${HOME}/.agents/journal}"
+HS_JOURNAL_SESSIONS_DIR="${HS_JOURNAL_DIR}/sessions"
+HS_JOURNAL_REFLECT="${HS_JOURNAL_REFLECT:-1}"
+HS_JOURNAL_REFLECT_BUDGET="${HS_JOURNAL_REFLECT_BUDGET:-low}"
+HS_JOURNAL_REFLECT_DEBOUNCE_SECONDS="${HS_JOURNAL_REFLECT_DEBOUNCE_SECONDS:-240}"
+HS_JOURNAL_KEEP_TELEMETRY="${HS_JOURNAL_KEEP_TELEMETRY:-1}"
+
+# Required tooling
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+[[ -z "$CWD" ]] && CWD=$(pwd)
+
+if [[ -z "$SESSION_ID" ]]; then
+  exit 0
+fi
+
+LOG_FILE="${HS_JOURNAL_SESSIONS_DIR}/${SESSION_ID}.jsonl"
+if [[ ! -f "$LOG_FILE" ]]; then
+  # No telemetry captured — nothing to journal.
+  exit 0
+fi
+
+# Resolve the primary bank (cwd-based, matching the recall hook's logic).
+BANK_LIB="$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-bank.sh"
+if [[ -f "$BANK_LIB" ]]; then
+  # shellcheck source=lib/hindsight-bank.sh
+  source "$BANK_LIB"
+  PRIMARY_BANK=$( (cd "$CWD" 2>/dev/null && resolve_bank) || echo "general")
+else
+  PRIMARY_BANK="general"
+fi
+REFLECT_BANK="${HS_JOURNAL_REFLECT_BANK:-$PRIMARY_BANK}"
+
+mkdir -p "$HS_JOURNAL_DIR" 2>/dev/null || exit 0
+
+# Filename: YYYY-mm-dd-h-m-s.md based on the SESSION START timestamp (earliest event
+# in the JSONL), so every Stop event during the session overwrites the same file
+# instead of spawning one journal per turn.
+SESSION_START_UTC=$(jq -rs '
+  [.[] | .ts // empty] | sort | .[0] // empty
+' "$LOG_FILE" 2>/dev/null)
+
+if [[ -n "$SESSION_START_UTC" ]]; then
+  # Convert UTC ISO-8601 to local time stamp like 2026-05-11-06-32-36
+  STAMP=$(date -d "$SESSION_START_UTC" +%Y-%m-%d-%H-%M-%S 2>/dev/null || date +%Y-%m-%d-%H-%M-%S)
+else
+  STAMP=$(date +%Y-%m-%d-%H-%M-%S)
+fi
+OUT_FILE="${HS_JOURNAL_DIR}/${STAMP}.md"
+REFLECT_CACHE="${HS_JOURNAL_SESSIONS_DIR}/${SESSION_ID}.reflect.txt"
+
+# --- Compute factual summary from the telemetry log ---
+
+# Each helper below either echoes a value, a JSON blob, or an empty string.
+
+recall_count=$(jq -cs '[.[] | select(.event=="recall")] | length' "$LOG_FILE" 2>/dev/null || echo 0)
+recall_skipped_count=$(jq -cs '[.[] | select(.event=="recall_skipped")] | length' "$LOG_FILE" 2>/dev/null || echo 0)
+retain_count=$(jq -cs '[.[] | select(.event=="retain")] | length' "$LOG_FILE" 2>/dev/null || echo 0)
+
+# Sum of result lines returned across all recall events (proxy for surfacing volume)
+total_recall_lines=$(jq -cs '[.[] | select(.event=="recall") | .total_lines] | add // 0' "$LOG_FILE" 2>/dev/null || echo 0)
+total_recall_chars=$(jq -cs '[.[] | select(.event=="recall") | .total_chars] | add // 0' "$LOG_FILE" 2>/dev/null || echo 0)
+empty_recall_count=$(jq -cs '[.[] | select(.event=="recall" and .returned_anything==false)] | length' "$LOG_FILE" 2>/dev/null || echo 0)
+
+# Sets of banks touched + skip reasons
+banks_primary=$(jq -rs '[.[] | select(.event=="recall") | .bank] | unique | join(", ")' "$LOG_FILE" 2>/dev/null || echo "")
+banks_linked=$(jq -rs '[.[] | select(.event=="recall") | .linked_banks // [] | .[]] | unique | join(", ")' "$LOG_FILE" 2>/dev/null || echo "")
+skip_reasons=$(jq -rs '[.[] | select(.event=="recall_skipped") | .reason] | unique | join(", ")' "$LOG_FILE" 2>/dev/null || echo "")
+
+# Build section-1 prompts list (the actual user prompts that elicited recalls)
+prompts_list=$(jq -rs '
+  [.[] | select(.event=="recall" or .event=="recall_skipped")]
+  | to_entries
+  | map("- **Turn \(.key+1)** (`\(.value.event)`, len=\(.value.prompt_len)): \(.value.prompt_first120 | gsub("\n";" ") | gsub("`";"′"))")
+  | join("\n")
+' "$LOG_FILE" 2>/dev/null || echo "")
+
+# Build section-3 bank breakdown
+bank_breakdown=$(jq -rs '
+  [.[] | select(.event=="recall")]
+  | group_by(.bank)
+  | map({
+      bank: .[0].bank,
+      calls: length,
+      lines: (map(.total_lines) | add),
+      linked: (map(.linked_banks // []) | add | unique)
+    })
+  | map("- `\(.bank)` — \(.calls) call(s), \(.lines) total lines back, linked: \(if (.linked|length)==0 then "(none)" else (.linked | join(", ")) end)")
+  | join("\n")
+' "$LOG_FILE" 2>/dev/null || echo "")
+
+# Build section-6a retained-fact list
+retained_list=$(jq -rs '
+  [.[] | select(.event=="retain")]
+  | to_entries
+  | map("- `\(.value.context)` → bank `\(.value.bank)` — `\(.value.file)` (\(.value.content_len) chars edited)\n  > \(.value.snippet | gsub("\n";" ") | .[0:160])")
+  | join("\n")
+' "$LOG_FILE" 2>/dev/null || echo "")
+
+# --- LLM reflection for subjective sections (4, 5, 6b) ---
+
+reflect_section=""
+reflect_error=""
+reflect_from_cache=0
+
+# Reuse cached reflect output if it's fresher than the debounce window.
+if [[ -f "$REFLECT_CACHE" ]]; then
+  cache_age=$(($(date +%s) - $(stat -c %Y "$REFLECT_CACHE" 2>/dev/null || echo 0)))
+  if [[ "$cache_age" -lt "$HS_JOURNAL_REFLECT_DEBOUNCE_SECONDS" ]]; then
+    reflect_section=$(cat "$REFLECT_CACHE" 2>/dev/null || echo "")
+    [[ -n "$reflect_section" ]] && reflect_from_cache=1
+  fi
+fi
+
+if [[ "$reflect_from_cache" -eq 0 ]] && [[ "$HS_JOURNAL_REFLECT" == "1" ]] && [[ -x "$HS_BIN" ]]; then
+  # Build a compact context payload describing the session.
+  ctx_payload=$(jq -cs --arg cwd "$CWD" --arg primary "$PRIMARY_BANK" '
+    {
+      cwd: $cwd,
+      primary_bank: $primary,
+      recall_events: [.[] | select(.event=="recall")],
+      recall_skipped: [.[] | select(.event=="recall_skipped")],
+      retain_events: [.[] | select(.event=="retain")]
+    }
+  ' "$LOG_FILE" 2>/dev/null || echo "{}")
+
+  reflect_query='Reflect on this Claude Code session, given the structured telemetry payload provided as context. Produce three short markdown subsections, each 2-4 sentences, plain English, no preamble:
+
+### 4. Effectiveness of returned data
+Given the recall results (total_lines, returned_anything flags) and what was retained vs. what was likely needed, assess whether the recalled context plausibly saved tokens / reduced wasted exploration. Be concrete: cite line counts and the specific banks consulted. If recall returned nothing useful, say so plainly.
+
+### 5. What could have been done differently in past sessions
+Speculate on prior-session habits — e.g. broader retains, better tagging, smaller recall budgets — that would have made *this* recall yield more relevant hits. Tie each suggestion to a concrete observation in the telemetry.
+
+### 6b. Why those exact words / why not references
+For each retain event in the telemetry, evaluate whether the retained text reads as a self-contained fact future Claude could act on, OR whether it leans on session-local references (file paths, snippets without rationale) that will go stale. If there are no retains, write a single sentence acknowledging that.
+
+Return ONLY the three subsections in the order shown. No top-level heading.'
+
+  reflect_raw=$("$HS_BIN" memory reflect "$REFLECT_BANK" "$reflect_query" \
+    --budget "$HS_JOURNAL_REFLECT_BUDGET" \
+    --context "$(printf '%s' "$ctx_payload" | head -c 8000)" \
+    --max-tokens 1500 \
+    --output json 2>/tmp/hs-journal-reflect.err) ||
+    reflect_error="reflect command failed (see /tmp/hs-journal-reflect.err)"
+
+  if [[ -n "$reflect_raw" ]]; then
+    reflect_section=$(printf '%s' "$reflect_raw" | jq -r '.text // empty' 2>/dev/null)
+    # Strip ANSI escapes defensively (hindsight pretty mode would emit them).
+    reflect_section=$(printf '%s' "$reflect_section" | sed -r 's/\x1b\[[0-9;]*[a-zA-Z]//g')
+
+    # Sanity-check: backend models sometimes emit tool-call stubs instead of an
+    # answer. If we see that pattern, drop the content and surface a clear note.
+    if [[ -z "$reflect_section" ]]; then
+      reflect_error="reflect returned empty text"
+      printf '%s' "$reflect_raw" >/tmp/hs-journal-reflect.out
+    elif printf '%s' "$reflect_section" | grep -qE '<(minimax|antml|tool):tool_call|<invoke name='; then
+      reflect_error="reflect backend returned a malformed tool-call stub instead of prose (raw saved to /tmp/hs-journal-reflect.out — likely a hindsight server prompt/template issue)"
+      printf '%s' "$reflect_section" >/tmp/hs-journal-reflect.out
+      reflect_section=""
+    elif [[ ${#reflect_section} -lt 80 ]]; then
+      reflect_error="reflect returned suspiciously short response (${#reflect_section} chars)"
+      printf '%s' "$reflect_section" >/tmp/hs-journal-reflect.out
+      reflect_section=""
+    fi
+  fi
+
+  # Cache a successful reflect so subsequent turns reuse it.
+  if [[ -n "$reflect_section" ]]; then
+    printf '%s' "$reflect_section" >"$REFLECT_CACHE" 2>/dev/null || true
+  fi
+fi
+
+# --- Compose the journal markdown ---
+
+# Heredoc the file out. Sections with no data emit a "(none)" placeholder.
+{
+  cat <<HEADER
+---
+session_id: ${SESSION_ID}
+written_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+cwd: ${CWD}
+primary_bank: ${PRIMARY_BANK}
+reflect_bank: ${REFLECT_BANK}
+reflect_mode: $([[ "$HS_JOURNAL_REFLECT" == "1" ]] && echo "auto" || echo "off")
+reflect_source: $([[ "$reflect_from_cache" -eq 1 ]] && echo "cache" || ([[ -n "$reflect_section" ]] && echo "fresh") || echo "none")
+recall_events: ${recall_count}
+recall_skipped: ${recall_skipped_count}
+retain_events: ${retain_count}
+total_recall_lines: ${total_recall_lines}
+total_recall_chars: ${total_recall_chars}
+---
+
+# Hindsight Journal — ${STAMP}
+
+## 1. Search terms elicited & how they were selected
+
+The current pipeline does **not** extract discrete keywords. The full user prompt is passed verbatim to \`hindsight memory recall <bank> "<prompt>"\`, where the server-side embedding model handles semantic matching against the bank's stored chunks. Below is each prompt that *did* trigger (or was *evaluated for*) a recall this session:
+
+HEADER
+
+  if [[ -n "$prompts_list" ]]; then
+    printf '%s\n\n' "$prompts_list"
+  else
+    printf '_(no prompts captured)_\n\n'
+  fi
+
+  cat <<SEC2
+## 2. Why hindsight was skipped (if it was)
+
+SEC2
+
+  if [[ "$recall_skipped_count" -gt 0 ]]; then
+    printf 'Skipped **%s** prompt(s) this session. Reasons observed: `%s`.\n\n' \
+      "$recall_skipped_count" "${skip_reasons:-unknown}"
+    printf '%s\n' 'Skip rules currently enforced by `hindsight-recall.sh`:'
+    printf '%s\n' '- Prompt under 24 characters (`prompt_under_min_length`)'
+    printf '%s\n' '- Empty prompt body (`empty_prompt`)'
+    printf '%s\n\n' '- `hindsight` CLI not on PATH (`hindsight_binary_missing`)'
+  else
+    printf 'Recall was attempted on every eligible prompt — no skips this session.\n\n'
+  fi
+
+  cat <<SEC3
+## 3. Bank resolved
+
+- **Primary bank** (cwd-resolved): \`${PRIMARY_BANK}\`
+- **Banks touched by recall**: ${banks_primary:-_(none)_}
+- **Linked banks reached via Dream fanout**: ${banks_linked:-_(none)_}
+
+Per-bank breakdown:
+
+SEC3
+
+  if [[ -n "$bank_breakdown" ]]; then
+    printf '%s\n\n' "$bank_breakdown"
+  else
+    printf '_(no recall events to break down)_\n\n'
+  fi
+
+  cat <<SEC6A
+## 6a. What was retained this session
+
+SEC6A
+
+  if [[ "$retain_count" -gt 0 ]]; then
+    printf '%s\n\n' "$retained_list"
+  else
+    printf '_(no retain events captured — either nothing was saved, or retains were issued via paths the hooks do not observe)_\n\n'
+  fi
+
+  # Subjective sections
+  cat <<SUBJ_HEADER
+## Reflective sections (LLM-synthesized)
+
+SUBJ_HEADER
+
+  if [[ -n "$reflect_section" ]]; then
+    printf '%s\n\n' "$reflect_section"
+  else
+    if [[ "$HS_JOURNAL_REFLECT" != "1" ]]; then
+      printf '_Reflection disabled (`HS_JOURNAL_REFLECT=0`). Run later with:_ `HS_JOURNAL_REFLECT=1 HS_JOURNAL_REFLECT_BANK=%s bash %s < <(echo %s)`\n\n' \
+        "$REFLECT_BANK" "$(realpath "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")" \
+        "$(printf '%s' "$INPUT" | jq -c .)"
+    elif [[ -n "$reflect_error" ]]; then
+      printf '_Reflection failed: %s_\n\n' "$reflect_error"
+    else
+      printf '_Reflection returned no content._\n\n'
+    fi
+  fi
+
+  cat <<FOOTER
+---
+
+### Raw telemetry
+
+\`\`\`
+$(cat "$LOG_FILE")
+\`\`\`
+
+_Telemetry log: \`${LOG_FILE}\`_
+FOOTER
+} >"$OUT_FILE" 2>/dev/null
+
+# Optionally prune the telemetry file (default: keep it).
+if [[ "$HS_JOURNAL_KEEP_TELEMETRY" != "1" ]]; then
+  rm -f "$LOG_FILE" 2>/dev/null || true
+fi
+
+exit 0