refactor(templates): convert guidance templates from XML to Markdown

- Replace XML templates with Markdown format for better readability
- Update guidance_builder.py to load .md files instead of .xml
- Update tests to check string content instead of XML parsing
- Make plugin path discovery version-agnostic in validate command

Author: zircote

commands/validate.md

@@ -179,7 +179,10 @@ print()
 print("## 4. Hook Entry Points")
 print("-" * 40)
 
-plugin_root = Path.home() / '.claude/plugins/cache/git-notes-memory/memory-capture/0.1.0'
+# Discover plugin root dynamically (version-agnostic)
+plugin_cache = Path.home() / '.claude/plugins/cache/git-notes-memory/memory-capture'
+plugin_versions = sorted(plugin_cache.glob('*/'), key=lambda p: p.name, reverse=True) if plugin_cache.exists() else []
+plugin_root = plugin_versions[0] if plugin_versions else plugin_cache / '0.3.0'
 hooks_dir = plugin_root / "hooks"
 hooks = [
     ("sessionstart.py", "SessionStart", "Context injection at session start"),

src/git_notes_memory/hooks/guidance_builder.py

@@ -1,9 +1,9 @@
 """Response guidance builder for SessionStart hook.
 
-This module provides the GuidanceBuilder class which loads XML templates
+This module provides the GuidanceBuilder class which loads Markdown templates
 teaching Claude how to structure responses for reliable memory signal detection.
 
-The guidance templates are stored as external XML files in the templates/
+The guidance templates are stored as external Markdown files in the templates/
 directory for easy editing without code changes.
 
 The guidance includes:
@@ -29,7 +29,7 @@
 
 logger = logging.getLogger(__name__)
 
-# Directory containing XML templates
+# Directory containing Markdown templates
 TEMPLATES_DIR = Path(__file__).parent / "templates"
 
 
@@ -47,9 +47,9 @@ class GuidanceLevel(Enum):
 
 
 class GuidanceBuilder:
-    """Builds XML response guidance for session injection.
+    """Builds response guidance for session injection.
 
-    This class loads XML templates from the templates/ directory that teach
+    This class loads Markdown templates from the templates/ directory that teach
     Claude how to structure responses for reliable memory signal detection.
     The guidance helps improve signal detection accuracy from ~70% to ~85%+.
 
@@ -61,8 +61,8 @@ class GuidanceBuilder:
     Example::
 
         builder = GuidanceBuilder()
-        xml = builder.build_guidance("standard")
-        # Returns XML string for additionalContext prepending
+        guidance = builder.build_guidance("standard")
+        # Returns guidance string for additionalContext prepending
     """
 
     def __init__(self, templates_dir: Path | None = None) -> None:
@@ -76,7 +76,7 @@ def __init__(self, templates_dir: Path | None = None) -> None:
         self._cache: dict[str, str] = {}
 
     def build_guidance(self, detail_level: str = "standard") -> str:
-        """Build response guidance XML by loading from template file.
+        """Build response guidance by loading from template file.
 
         Args:
             detail_level: One of "minimal", "standard", or "detailed".
@@ -85,7 +85,7 @@ def build_guidance(self, detail_level: str = "standard") -> str:
                 - detailed: Full templates with examples (~1200 tokens)
 
         Returns:
-            XML string for inclusion in additionalContext.
+            Guidance string for inclusion in additionalContext.
 
         Raises:
             ValueError: If detail_level is not recognized.
@@ -94,7 +94,7 @@ def build_guidance(self, detail_level: str = "standard") -> str:
         Example::
 
             builder = GuidanceBuilder()
-            xml = builder.build_guidance("standard")
+            guidance = builder.build_guidance("standard")
             # Use in SessionStart additionalContext
         """
         try:
@@ -122,7 +122,7 @@ def _load_template(self, level: str) -> str:
         if level in self._cache:
             return self._cache[level]
 
-        template_path = self._templates_dir / f"guidance_{level}.xml"
+        template_path = self._templates_dir / f"guidance_{level}.md"
 
         if not template_path.exists():
             msg = f"Template file not found: {template_path}"

…ry/hooks/templates/guidance_detailed.xml …ory/hooks/templates/guidance_detailed.mdsrc/git_notes_memory/hooks/templates/guidance_detailed.xml renamed to src/git_notes_memory/hooks/templates/guidance_detailed.md src/git_notes_memory/hooks/templates/guidance_detailed.xml renamed to src/git_notes_memory/hooks/templates/guidance_detailed.md

@@ -1,5 +1,5 @@
 <session_behavior_protocol level="detailed">
-<mandatory_rules><![CDATA[
+<mandatory_rules>
 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.
 
 ---
@@ -8,12 +8,12 @@ You are operating in **memory-capture mode**. The following rules are MANDATORY
 
 When ANY of these triggers occur, you MUST immediately include the appropriate marker inline in your response. Do not ask permission. Do not suggest using markers. USE THEM DIRECTLY.
 
-| Trigger | REQUIRED Action | Example |
-|---------|-----------------|---------|
-| Making ANY decision (architectural, design, library choice, approach) | `[decision] What + Why` | `[decision] Using PostgreSQL for persistence: better JSON support, team expertise, ACID compliance needed` |
-| Learning something new, discovering a pattern, TIL moment, surprise | `[learned] Insight + Application` | `[learned] pytest module-scoped fixtures share state across tests—use function scope for mutable fixtures` |
-| Hitting a blocker, encountering an issue, stuck on a problem | `[blocker] Issue + Needed` | `[blocker] Schema migration blocked by circular FK dependencies between users and organizations tables` |
-| Completing significant work, finishing a milestone | `[progress] Accomplishment` | `[progress] Implemented JWT authentication with refresh token rotation` |
+| Trigger                                                               | REQUIRED Action                   | Example                                                                                                    |
+| --------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Making ANY decision (architectural, design, library choice, approach) | `[decision] What + Why`           | `[decision] Using PostgreSQL for persistence: better JSON support, team expertise, ACID compliance needed` |
+| Learning something new, discovering a pattern, TIL moment, surprise   | `[learned] Insight + Application` | `[learned] pytest module-scoped fixtures share state across tests—use function scope for mutable fixtures` |
+| Hitting a blocker, encountering an issue, stuck on a problem          | `[blocker] Issue + Needed`        | `[blocker] Schema migration blocked by circular FK dependencies between users and organizations tables`    |
+| Completing significant work, finishing a milestone                    | `[progress] Accomplishment`       | `[progress] Implemented JWT authentication with refresh token rotation`                                    |
 
 ### Enforcement
 
@@ -31,11 +31,13 @@ When `<memory_context>` contains retrieved memories, you MUST actively reference
 ### Required Behaviors
 
 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, say: "This looks similar to a previous blocker (memory ID) which was resolved by..."
 
 3. **Weave naturally:**
@@ -55,21 +57,24 @@ When `<memory_context>` contains retrieved memories, you MUST actively reference
 By default, implement marker usage rather than discussing or suggesting it.
 
 **Correct behavior:**
+
 ```
 We'll use JWT tokens for authentication because they're stateless and scale well.
 [decision] Using JWT for auth: stateless, scales to multiple servers, team has experience
 ```
 
 **Incorrect behavior:**
+
 ```
 We'll use JWT tokens. Would you like me to capture this decision?
 ```
 
 These rules supersede default helpful suggestions. They configure your behavior for this session.
-]]></mandatory_rules>
+</mandatory_rules>
 
-<marker_reference><![CDATA[
+<marker_reference>
 **Valid markers:**
+
 - `[decision] text` — decisions namespace
 - `[learned] text` — learnings namespace
 - `[blocker] text` — blockers namespace
@@ -80,11 +85,13 @@ These rules supersede default helpful suggestions. They configure your behavior
 **Valid namespaces:** decisions, learnings, blockers, progress, patterns, research, reviews, retrospective
 
 **Structured format (optional for detailed captures):**
+
 ```
 **Decision**: [One-line summary]
 **Context**: [Why this decision was needed]
 **Choice**: [What was chosen]
 **Rationale**: [Why this choice over alternatives]
 ```
-]]></marker_reference>
+
+</marker_reference>
 </session_behavior_protocol>

…ory/hooks/templates/guidance_minimal.xml …mory/hooks/templates/guidance_minimal.mdsrc/git_notes_memory/hooks/templates/guidance_minimal.xml renamed to src/git_notes_memory/hooks/templates/guidance_minimal.md src/git_notes_memory/hooks/templates/guidance_minimal.xml renamed to src/git_notes_memory/hooks/templates/guidance_minimal.md

@@ -1,5 +1,7 @@
+# Guidance: Minimal Instructions
+
 <session_behavior_protocol level="minimal">
-<mandatory_rules><![CDATA[
+<mandatory_rules>
 **REQUIRED:** Use these markers inline when triggers occur. Do not ask—act.
 
 - Decision made: `[decision] rationale`
@@ -10,5 +12,5 @@
 **REQUIRED:** Reference memories from `<memory_context>` when relevant. Say "Based on previous..."
 
 Valid namespaces: decisions, learnings, blockers, progress, patterns, research
-]]></mandatory_rules>
+</mandatory_rules>
 </session_behavior_protocol>

…ry/hooks/templates/guidance_standard.xml …ory/hooks/templates/guidance_standard.mdsrc/git_notes_memory/hooks/templates/guidance_standard.xml renamed to src/git_notes_memory/hooks/templates/guidance_standard.md src/git_notes_memory/hooks/templates/guidance_standard.xml renamed to src/git_notes_memory/hooks/templates/guidance_standard.md

@@ -1,17 +1,19 @@
+# Guidance: Standard Instructions
+
 <session_behavior_protocol level="standard">
-<mandatory_rules><![CDATA[
+<mandatory_rules>
 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.
 
 ## Rule 1: CAPTURE MARKERS (Required)
 
 When you make a decision, learn something, hit a blocker, or complete work, you MUST use the appropriate marker inline in your response. Do not ask permission—use them directly.
 
-| Trigger | REQUIRED Action |
-|---------|-----------------|
-| Making any architectural/design decision | Write: `[decision] What you decided and why` |
-| Learning something, discovering a pattern, TIL moment | Write: `[learned] The insight and why it matters` |
-| Hitting a blocker or encountering an issue | Write: `[blocker] What blocks progress and what's needed` |
-| Completing significant work | Write: `[progress] What was accomplished` |
+| Trigger                                               | REQUIRED Action                                           |
+| ----------------------------------------------------- | --------------------------------------------------------- |
+| Making any architectural/design decision              | Write: `[decision] What you decided and why`              |
+| Learning something, discovering a pattern, TIL moment | Write: `[learned] The insight and why it matters`         |
+| Hitting a blocker or encountering an issue            | Write: `[blocker] What blocks progress and what's needed` |
+| Completing significant work                           | Write: `[progress] What was accomplished`                 |
 
 **Do not suggest using markers. USE THEM DIRECTLY when the trigger occurs.**
 
@@ -28,15 +30,16 @@ When `<memory_context>` contains retrieved memories, you MUST actively reference
 ## Rule 3: DEFAULT TO ACTION
 
 By default, implement marker usage rather than discussing it. When a trigger condition is met:
+
 - DO: Include the marker inline in your response
 - DON'T: Ask "should I capture this?" or "would you like me to remember this?"
 
 These rules supersede default helpful suggestions. They configure your behavior for this session.
-]]></mandatory_rules>
+</mandatory_rules>
 
-<marker_reference><![CDATA[
+<marker_reference>
 **Valid markers:** `[decision]`, `[learned]`, `[blocker]`, `[progress]`, `[remember]`, `[remember:namespace]`
 
 **Valid namespaces:** decisions, learnings, blockers, progress, patterns, research, reviews, retrospective
-]]></marker_reference>
+</marker_reference>
 </session_behavior_protocol>

tests/test_guidance_builder.py

@@ -2,15 +2,13 @@
 
 Tests the response guidance builder including:
 - GuidanceBuilder class
-- XML generation for different detail levels
+- Markdown template generation for different detail levels
 - GuidanceLevel enum
 - Configuration integration
 """
 
 from __future__ import annotations
 
-import xml.etree.ElementTree as ET
-
 import pytest
 
 from git_notes_memory.hooks.config_loader import (
@@ -62,12 +60,12 @@ def test_all_levels_defined(self) -> None:
 
 
 # =============================================================================
-# XML Template Content Tests
+# Template Content Tests
 # =============================================================================
 
 
-class TestXMLTemplateContent:
-    """Test that XML templates contain expected content."""
+class TestTemplateContent:
+    """Test that templates contain expected content."""
 
     def test_detailed_has_behavioral_examples(
         self, guidance_builder: GuidanceBuilder
@@ -164,42 +162,36 @@ def test_contains_inline_marker_syntax(
             assert "[blocker]" in xml
 
 
-class TestGuidanceBuilderXMLStructure:
-    """Test XML structure validity of generated guidance."""
+class TestGuidanceBuilderStructure:
+    """Test structure of generated guidance templates."""
 
-    def test_minimal_is_valid_xml(self, guidance_builder: GuidanceBuilder) -> None:
-        """Test that minimal output is valid XML."""
-        xml = guidance_builder.build_guidance("minimal")
-        # Should parse without error (S314 safe: parsing our own generated XML)
-        root = ET.fromstring(xml)  # noqa: S314
-        assert root.tag == "session_behavior_protocol"
-        assert root.attrib.get("level") == "minimal"
+    def test_minimal_has_protocol_tag(self, guidance_builder: GuidanceBuilder) -> None:
+        """Test that minimal output has session_behavior_protocol structure."""
+        content = guidance_builder.build_guidance("minimal")
+        assert '<session_behavior_protocol level="minimal">' in content
+        assert "</session_behavior_protocol>" in content
 
-    def test_standard_is_valid_xml(self, guidance_builder: GuidanceBuilder) -> None:
-        """Test that standard output is valid XML."""
-        xml = guidance_builder.build_guidance("standard")
-        root = ET.fromstring(xml)  # noqa: S314
-        assert root.tag == "session_behavior_protocol"
-        assert root.attrib.get("level") == "standard"
+    def test_standard_has_protocol_tag(self, guidance_builder: GuidanceBuilder) -> None:
+        """Test that standard output has session_behavior_protocol structure."""
+        content = guidance_builder.build_guidance("standard")
+        assert '<session_behavior_protocol level="standard">' in content
+        assert "</session_behavior_protocol>" in content
 
-    def test_detailed_is_valid_xml(self, guidance_builder: GuidanceBuilder) -> None:
-        """Test that detailed output is valid XML."""
-        xml = guidance_builder.build_guidance("detailed")
-        root = ET.fromstring(xml)  # noqa: S314
-        assert root.tag == "session_behavior_protocol"
-        assert root.attrib.get("level") == "detailed"
+    def test_detailed_has_protocol_tag(self, guidance_builder: GuidanceBuilder) -> None:
+        """Test that detailed output has session_behavior_protocol structure."""
+        content = guidance_builder.build_guidance("detailed")
+        assert '<session_behavior_protocol level="detailed">' in content
+        assert "</session_behavior_protocol>" in content
 
     def test_detailed_has_mandatory_rules(
         self, guidance_builder: GuidanceBuilder
     ) -> None:
-        """Test that detailed guidance has mandatory_rules element."""
-        xml = guidance_builder.build_guidance("detailed")
-        root = ET.fromstring(xml)  # noqa: S314
-        rules = root.find("mandatory_rules")
-        assert rules is not None
-        # Rules should contain the markdown content
-        assert rules.text is not None
-        assert "MUST" in rules.text
+        """Test that detailed guidance has mandatory_rules section."""
+        content = guidance_builder.build_guidance("detailed")
+        assert "<mandatory_rules>" in content
+        assert "</mandatory_rules>" in content
+        # Rules should contain MUST requirements
+        assert "MUST" in content
 
 
 class TestGuidanceBuilderTokenEstimation:
@@ -328,15 +320,15 @@ def test_whitespace_level_raises(self, guidance_builder: GuidanceBuilder) -> Non
         with pytest.raises(ValueError):
             guidance_builder.build_guidance("  ")
 
-    def test_special_chars_in_templates_escaped(
+    def test_special_chars_in_templates_preserved(
         self, guidance_builder: GuidanceBuilder
     ) -> None:
-        """Test that templates with special chars are still valid XML via CDATA."""
-        xml = guidance_builder.build_guidance("detailed")
-        # Templates contain markdown with special chars wrapped in CDATA
-        # Let's verify the XML is still valid (S314 safe: parsing our own generated XML)
-        root = ET.fromstring(xml)  # noqa: S314
-        assert root is not None
+        """Test that templates preserve markdown formatting chars."""
+        content = guidance_builder.build_guidance("detailed")
+        # Templates contain markdown formatting that should be preserved
+        assert "**" in content  # Bold markers
+        assert "`" in content  # Code markers
+        assert content  # Non-empty content
 
     def test_multiple_builds_are_independent(
         self, guidance_builder: GuidanceBuilder