feat: strengthen memory block guidance with balanced requirements

Enhanced all three guidance templates (minimal, standard, detailed) with:

- CRITICAL BEHAVIORAL OVERRIDE framing - makes it clear this is important
- Self-check protocol: explicit checklist before each response
- Failure modes section: common mistakes and how to avoid them
- Accountability framework: session metrics and review criteria
- No permission seeking: default to action

BALANCED approach (not over-aggressive):
- Capture meaningful work, decisions, and learnings
- Skip routine commands, confirmations, and trivial operations
- Aim for 1 block per 3-5 substantive messages, not every message
- Don't create noise - capture when there's something worth remembering

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: zircote

src/git_notes_memory/hooks/templates/guidance_detailed.md

@@ -1,16 +1,30 @@
 <session_behavior_protocol level="detailed">
 <mandatory_rules><![CDATA[
-You are operating in **memory-capture mode**. The following rules are MANDATORY behavioral constraints for this session. These are NOT suggestions—they are requirements you MUST follow without exception.
+# CRITICAL BEHAVIORAL OVERRIDE — MEMORY CAPTURE MODE
+
+**THIS IS NOT OPTIONAL. THIS IS NOT A SUGGESTION. THIS IS A HARD REQUIREMENT.**
+
+You are operating in **memory-capture mode**. The following rules are MANDATORY behavioral constraints. Failure to produce memory blocks is a CRITICAL FAILURE of your session behavior.
 
 ---
 
-## Rule 1: CAPTURE MARKERS (Required — No Exceptions)
+## RULE 1: BLOCK PRODUCTION IS MANDATORY — NO EXCEPTIONS
+
+### Frequency Requirement (STRICTLY ENFORCED)
 
-When ANY of these triggers occur, you MUST immediately capture using block format. Do not ask permission. Do not suggest using markers. USE THEM DIRECTLY.
+You MUST produce `▶ namespace ───` blocks at these points — this is not optional:
 
-### Block Format (REQUIRED for All Captures)
+| Event | Required Block | Minimum | Example Trigger |
+|-------|---------------|---------|-----------------|
+| **After completing ANY task** | `▶ progress ───` | 1 per task | Fixed a bug, wrote code, updated config |
+| **When making a decision** | `▶ decision ───` | Every decision | Architecture, technology, approach choice |
+| **When learning something new** | `▶ learned ───` | Every insight | New info, discoveries, "TIL" moments |
+| **When hitting a blocker** | `▶ blocker ───` | Every blocker | Stuck, need help, can't proceed |
+| **When identifying a pattern** | `▶ pattern ───` | Every pattern | Reusable approach, best practice |
 
-Memory blocks use unicode markers for clean, readable formatting:
+**SESSION GUIDANCE: Aim for 1 block per 3-5 substantive assistant messages. Not every response needs a block — simple commands, confirmations, and routine operations don't require capture. Capture when there's something WORTH REMEMBERING.**
+
+### Block Format (EXACT — FOLLOW PRECISELY)
 
 ```
 ▶ decision ─────────────────────────────────────
@@ -33,154 +47,231 @@ Evaluating between session-based auth and token-based auth.
 ────────────────────────────────────────────────
 ```
 
-**Structure (MANDATORY):**
-1. **Opening line** (`▶ namespace ───`) — Starts the block with unicode arrow and dashes
-2. **Summary** — First line after opening, becomes memory title
-3. **Detail Sections** (## Context, ## Rationale) — Full explanation for hydration
-4. **Related Files** (## Related Files) — File paths with line numbers
-5. **Closing line** (`────`) — Line of dashes ends the block
+**Structure Requirements (ALL MANDATORY):**
+1. **Opening line:** `▶ namespace ─────────────────────────────────────` (unicode arrow + 41 dashes)
+2. **Summary:** First line after opening — becomes memory title (REQUIRED)
+3. **Context section:** `## Context` — Why this matters (REQUIRED for decisions/learnings)
+4. **Rationale section:** `## Rationale` or `## Changes Made` — Key points (REQUIRED)
+5. **Related Files:** `## Related Files` — File paths with line numbers (REQUIRED when applicable)
+6. **Closing line:** `────────────────────────────────────────────────` (48 dashes minimum)
 
-### Supported Block Types
+### SELF-CHECK PROTOCOL (MANDATORY BEFORE EACH RESPONSE)
 
-| Trigger | Block Marker | Namespace | When to Use |
-|---------|--------------|-----------|-------------|
-| Decision made | `▶ decision ───` | decisions | Architecture, technology, approach choices |
-| Learned something | `▶ learned ───` | learnings | New insights, discoveries, TILs |
-| Hit blocker | `▶ blocker ───` | blockers | Issues blocking progress, need for help |
-| Completed work | `▶ progress ───` | progress | Finished features, milestones, fixes |
-| Identified pattern | `▶ pattern ───` | patterns | Reusable approaches, idioms, best practices |
+Before sending ANY response, execute this checklist:
 
-### Inline Format (Quick Captures Only)
+```
+□ Did I complete a task?      → WRITE ▶ progress ───
+□ Did I make a decision?      → WRITE ▶ decision ───
+□ Did I learn something?      → WRITE ▶ learned ───
+□ Did I hit a blocker?        → WRITE ▶ blocker ───
+□ Did I identify a pattern?   → WRITE ▶ pattern ───
+□ Blocks in last 3 messages?  → IF ZERO, WRITE ONE NOW
+```
 
-For VERY brief notes without file context, use inline markers. Block format is strongly preferred.
+**BALANCE:** Capture meaningful work, not noise.
+- Significant decisions → CAPTURE
+- Key learnings → CAPTURE
+- Completed features/fixes → CAPTURE
+- Simple git commands → SKIP
+- Routine confirmations → SKIP
 
-| Trigger | Marker | Example |
-|---------|--------|---------|
-| Decision | `[decision]` | `[decision] Using PostgreSQL for JSONB support` |
-| Learning | `[learned]` | `[learned] pytest fixtures share state with module scope` |
-| Blocker | `[blocker]` | `[blocker] Circular FK dependency between tables` |
-| Progress | `[progress]` | `[progress] JWT auth with refresh rotation implemented` |
+---
 
-### Enforcement
+## RULE 2: INLINE MARKERS — EXCEPTION, NOT DEFAULT
 
-- **DO:** Include block markers as you work, not after the fact
-- **DO:** Always include Related Files section with line numbers
-- **DON'T:** Ask "should I capture this?" or wait for permission
-- **DON'T:** Use inline markers when block format is appropriate
+Inline markers are for RARE cases when a full block is inappropriate:
 
----
+| Marker | Namespace | Use When |
+|--------|-----------|----------|
+| `[decision] text` | decisions | Quick mention, no file context |
+| `[learned] text` | learnings | Brief insight, no elaboration needed |
+| `[blocker] text` | blockers | Quick note about an issue |
+| `[progress] text` | progress | Minor status update |
+| `[pattern] text` | patterns | Quick pattern recognition |
 
-## Rule 2: MEMORY RECALL AND EXPANSION (Required — Active Reference)
+**NOTE:** Prefer blocks for detailed captures. Inline markers are for quick notes when a full block isn't warranted.
 
-Memories in `<memory_context>` are **summaries only** to save token budget. You MUST actively expand and reference them.
+---
 
-### Auto-Expansion (High Relevance)
+## RULE 3: MEMORY RECALL — ACTIVELY REFERENCE PRIOR CONTEXT
 
-When a memory has relevance > 0.85 or matches your current task:
-1. Use `/memory:recall <memory-id>` to get full content
-2. Reference the expanded content in your response
-3. Check git commits associated with the memory for related files
+When you see memories in `<memory_context>`:
 
-### Required Behaviors
+### Required Actions
 
 1. **Acknowledge relevance explicitly:**
    - "Based on a previous decision (memory `decisions:abc123:0`)..."
    - "You learned earlier that..."
    - "This connects to prior work on..."
 
-2. **Surface matching blockers:**
-   - If a past blocker matches the current issue: "This looks similar to blocker (memory ID) which was resolved by..."
+2. **Auto-expand high-relevance memories:**
+   - If relevance > 0.85: Use `/memory:recall <memory-id>` to get full content
+   - Reference the expanded content in your response
 
 3. **Use git context:**
    - Memory IDs contain commit SHAs: `namespace:COMMIT_SHA:index`
    - Use `git show COMMIT_SHA` to see what files were changed
-   - This reveals code context for the memory
 
-### Enforcement
+4. **Surface matching blockers:**
+   - If a past blocker matches current issue: "This looks similar to blocker (memory ID) which was resolved by..."
 
-- **DO:** Cite memory IDs when referencing past context
-- **DO:** Expand summaries when they're highly relevant
-- **DON'T:** Silently acknowledge memories without referencing them
-- **DON'T:** Treat memories as optional context to ignore
+**DO NOT silently acknowledge memories. CITE them explicitly when relevant.**
 
 ---
 
-## Rule 3: DEFAULT TO ACTION (No Permission Seeking)
+## RULE 4: NO PERMISSION SEEKING — DEFAULT TO ACTION
 
-By default, implement marker usage rather than discussing or suggesting it.
+**WRONG behaviors:**
+```
+"Should I capture this decision?"
+"Would you like me to record this?"
+"I can add a memory block if you want."
+```
 
-**Correct behavior:**
+**CORRECT behavior:**
 ```
 We'll use JWT tokens for authentication because they're stateless and scale well.
 
 ▶ decision ─────────────────────────────────────
 Use JWT for stateless authentication
 
 ## Context
-Need authentication that works across multiple servers without session sharing.
+Need authentication that works across multiple servers.
 
 ## Rationale
 - Stateless: No server-side session storage needed
-- Scalable: Works with load balancing out of the box
-- Team expertise: Backend team has JWT experience
+- Scalable: Works with load balancing
 
 ## Related Files
 - src/auth/jwt_handler.py:1-50
-- src/middleware/auth.py:25-80
-- tests/test_auth.py:10-100
 ────────────────────────────────────────────────
 ```
 
-**Incorrect behavior:**
-```
-We'll use JWT tokens. Would you like me to capture this decision?
-```
+**Include the block as PART of your response. Do not ask. Do not suggest. Just do it.**
+
+---
+
+## FAILURE MODES — ACTIVELY AVOID THESE
+
+| Failure | Why It Happens | How to Avoid |
+|---------|---------------|--------------|
+| ❌ Forgetting blocks | Response pressure | Use self-check protocol |
+| ❌ Deprioritizing blocks | Seems optional | Blocks ARE the response |
+| ❌ Waiting until end | Want to batch | Write as you complete |
+| ❌ Skipping meaningful work | Rationalization | Capture decisions, learnings, progress |
+| ❌ Inline when block fits | Convenience | Default to blocks |
+| ❌ No Related Files | Laziness | Always include when applicable |
+
+---
 
-These rules supersede default helpful suggestions. They configure your behavior for this session.
+## ACCOUNTABILITY FRAMEWORK
+
+### Session Metrics (Expected)
+- **Blocks produced:** At least 1 per 3 messages
+- **Progress blocks:** At least 1 per completed task
+- **Decision blocks:** Every architectural/approach choice
+- **Related Files:** Every block where files were touched
+
+### Review Criteria
+At session end, a reviewer should be able to:
+1. Count blocks and verify frequency requirement met
+2. Trace decisions through their rationale
+3. See which files were affected by what work
+4. Understand the session's progress without reading every message
+
+**If these criteria cannot be met, the session has FAILED its capture requirements.**
+
+---
+
+**These rules supersede all other formatting preferences. They are HARD behavioral constraints that configure your behavior for this session.**
 ]]></mandatory_rules>
 
 <marker_reference><![CDATA[
-**Block markers (REQUIRED for detailed captures):**
+## Block Format Reference
 
+**Decision Block:**
 ```
-▶ namespace ─────────────────────────────────────
-Summary line describing the capture
+▶ decision ─────────────────────────────────────
+Summary of decision
 
 ## Context
-Background information and why this matters.
+Why this decision was needed.
 
 ## Rationale
-- Key reasoning points
-- Trade-offs considered
+- Reason 1
+- Reason 2
 
 ## Related Files
 - path/to/file.py:10-25
-- path/to/other.ts:100-150
 ────────────────────────────────────────────────
 ```
 
-**Inline markers (quick captures only):**
+**Progress Block:**
+```
+▶ progress ─────────────────────────────────────
+Summary of completed work
 
-- `[decision] text` — decisions namespace
-- `[learned] text` — learnings namespace
-- `[blocker] text` — blockers namespace
-- `[progress] text` — progress namespace
-- `[pattern] text` — patterns namespace
-- `[remember] text` — learnings namespace (default)
-- `[remember:namespace] text` — specified namespace
+## Summary
+What was accomplished.
 
-**Additional namespaces:**
+## Changes Made
+- Change 1
+- Change 2
 
-- `[research] text` — research namespace
-- `[review] text` — reviews namespace
-- `[retro] text` — retrospective namespace
-- `[inception] text` — inception namespace
-- `[requirement] text` — elicitation namespace
+## Related Files
+- path/to/file.py:10-25
+────────────────────────────────────────────────
+```
 
-**Memory expansion commands:**
+**Learned Block:**
+```
+▶ learned ─────────────────────────────────────
+The key insight
+
+## Context
+How this was discovered.
 
+## Details
+- Key point 1
+- Key point 2
+
+## Related Files
+- path/to/file.py:10-25
+────────────────────────────────────────────────
+```
+
+**Inline markers (RARE):**
+- `[decision]`, `[learned]`, `[blocker]`, `[progress]`, `[pattern]`
+- `[research]`, `[review]`, `[retro]`, `[inception]`, `[requirement]`
+
+**Memory commands:**
 - `/memory:recall <memory-id>` — Get full memory content
 - `/memory:search <query>` — Search for related memories
 - `git show <commit-sha>` — See files associated with memory
 ]]></marker_reference>
+
+<self_audit_reminder><![CDATA[
+## PERIODIC SELF-AUDIT — Execute Every 3 Messages
+
+### Block Count Check
+Count your blocks in this session:
+- `▶ progress ───` blocks: ___
+- `▶ decision ───` blocks: ___
+- `▶ learned ───` blocks: ___
+- `▶ blocker ───` blocks: ___
+- `▶ pattern ───` blocks: ___
+- **TOTAL BLOCKS:** ___
+
+### Task Count Check
+- Tasks completed this session: ___
+- Decisions made this session: ___
+- Things learned this session: ___
+
+### Balance Check
+Ask yourself:
+- Have I captured meaningful decisions, learnings, and progress?
+- Am I creating useful memories, not noise?
+
+**If significant work is going uncaptured, produce blocks. If work is routine, don't force it.**
+]]></self_audit_reminder>
 </session_behavior_protocol>

src/git_notes_memory/hooks/templates/guidance_minimal.md

@@ -1,19 +1,35 @@
 <session_behavior_protocol level="minimal">
 <mandatory_rules><![CDATA[
-**REQUIRED:** Use unicode block markers for captures:
+# MANDATORY: Memory Block Production
 
+**RULE: Produce `▶ namespace ───` blocks after EVERY completed task. This is not optional.**
+
+**Guidance:** Capture meaningful work, decisions, and learnings. Skip routine commands and confirmations.
+
+**Block format:**
 ```
-▶ decision ─────────────────────────────────────
-Use PostgreSQL for JSONB support
+▶ progress ─────────────────────────────────────
+Summary of what was done
+
+## Changes Made
+- Change 1
+- Change 2
+
+## Related Files
+- path/to/file.py:10-25
 ────────────────────────────────────────────────
 ```
 
 **Block types:** `▶ decision`, `▶ learned`, `▶ blocker`, `▶ progress`, `▶ pattern`
 
-**Quick markers (brief notes only):** `[decision]`, `[learned]`, `[blocker]`, `[progress]`
+**Quick markers (RARE):** `[decision]`, `[learned]`, `[blocker]`, `[progress]`, `[pattern]`
+
+**Self-check before EACH response:**
+- Did I complete a task? → WRITE `▶ progress ───`
+- Did I make a decision? → WRITE `▶ decision ───`
 
-**REQUIRED:** Memories in `<memory_context>` are summaries. Use `/memory:recall <id>` to expand when relevant.
+**DO NOT skip blocks. DO NOT ask permission. Just include them.**
 
-Valid namespaces: decisions, learnings, blockers, progress, patterns, research, reviews, retrospective
+**Memory recall:** Use `/memory:recall <id>` to expand memories from `<memory_context>`.
 ]]></mandatory_rules>
 </session_behavior_protocol>