feat(reflect): add /retro — unconditional session reflection + once-per-session nudge

[HumanBean17]

What

Adds /retro — a detector-independent session-reflection command, a fail-open once-per-session Stop hook that nudges the agent to run it, and a committable backlog to accumulate proposals.

Why

The existing /reflect is detector-gated: it only fires when harnessgap's signals trip. Pre-calibration the detector's recall/precision is too weak to be the trigger for reflection — it misses most real friction. /retro decouples reflection from detection: the agent reflects on the session it just lived (the session is in context, so it's not reconstructing from memory), grounds in concrete evidence, and emits low-commitment one-liners a human can later triage into the harness. Recurrence across the backlog — not a single detector trip — becomes the signal to act on. The detector becomes optional seasoning, not the gate.

Files

• .claude/commands/retro.md — the /retro command. Grounds in evidence first (files reread, commands retried, wrong assumptions, detours), bans generic lessons, enforces the "it was not obvious that …; would have helped to know …" seed shape + a *(→ candidate change)* tag, appends to the backlog, and flags recurrence. Never edits harness config.
• .claude/harnessgap-retro-hook.cjs — fail-open, once-per-session Stop-hook wrapper. Loop-guarded via stop_hook_active + a marker keyed by session_id/transcript_path. Mirrors the fail-open discipline of harnessgap-stop-hook.js (src/init/claude.ts). .cjs because this repo is ESM ("type":"module") — .js+require crashes (see bug(init): Stop-hook wrapper crashes in ESM target repos ("type": "module") #47).
• test/retro-hook.test.ts — 7 contract tests: block-once, once-per-session via marker, independent sessions, loop-guard, malformed-stdin fail-open, transcript_path keying, no-key fail-open. All passing.
• docs/_reflections/log.md — accumulating friction backlog (template + the capture → recurrence → triage → retire loop).

How to activate (not committed — local/machine-specific)

.claude/settings.json is deliberately not in this PR (it carries a machine-specific absolute path during dogfooding). Register the hook with:

{
  "hooks": {
    "Stop": [
      { "matcher": "", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/harnessgap-retro-hook.cjs\"" } ] }
    ]
  }
}

Portable $CLAUDE_PROJECT_DIR-based registration + wiring into harnessgap init claude|qwen|gigacode (alongside /reflect, with two-Stop-hook coexistence) is tracked in #48.

Verification

• npx vitest run test/retro-hook.test.ts → 7/7 pass (and tsc builds clean).
• Live end-to-end: the hook fired at session end, surfaced the nudge, and the agent ran /retro and appended real proposals — confirming the block-reason path works in Claude Code, not just in unit tests.

Relationship to existing work

• /reflect (detector-gated, init-installed) is untouched. /retro is its complement: confirmed-friction (/reflect) vs unconditional (/retro).
• Open product question (in feat(init): ship /retro (unconditional reflection) + once-per-session nudge alongside /reflect #48): does /retro eventually supersede detector-gating for reflection?
• Related bug surfaced while building this: bug(init): Stop-hook wrapper crashes in ESM target repos ("type": "module") #47 (the init-emitted reflect wrapper has the same .js/ESM crash on ESM target repos).

🤖 Generated with Claude Code