docs: bump version to v2.26.1 for session catchup fix

Tests hook output, path sanitization, UTF-8 encoding, and separator
handling without requiring interactive /clear. Run with:
  bash tests/test_clear_recovery.sh

.codebuddy/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.codebuddy/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

.codex/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.codex/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

.continue/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

.cursor/hooks/user-prompt-submit.ps1

@@ -1,8 +1,16 @@
 # planning-with-files: User prompt submit hook for Cursor (PowerShell)
-# Reminds the agent about active planning files on every user message.
-# Critical for session recovery after context reset.
+# Injects plan context on every user message.
+# Critical for session recovery after /clear — dumps actual content, not just advice.
 
 if (Test-Path "task_plan.md") {
-    Write-Output "[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding."
+    Write-Output "[planning-with-files] ACTIVE PLAN — current state:"
+    Get-Content "task_plan.md" -TotalCount 50 -Encoding UTF8
+    Write-Output ""
+    Write-Output "--- recent progress ---"
+    if (Test-Path "progress.md") {
+        Get-Content "progress.md" -Tail 20 -Encoding UTF8
+    }
+    Write-Output ""
+    Write-Output "[planning-with-files] Read findings.md for research context. Continue from the current phase."
 }
 exit 0

.cursor/hooks/user-prompt-submit.sh

@@ -1,9 +1,15 @@
 #!/bin/bash
 # planning-with-files: User prompt submit hook for Cursor
-# Reminds the agent about active planning files on every user message.
-# Critical for session recovery after context reset.
+# Injects plan context on every user message.
+# Critical for session recovery after /clear — dumps actual content, not just advice.
 
 if [ -f task_plan.md ]; then
-    echo "[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding."
+    echo "[planning-with-files] ACTIVE PLAN — current state:"
+    head -50 task_plan.md
+    echo ""
+    echo "--- recent progress ---"
+    tail -20 progress.md 2>/dev/null
+    echo ""
+    echo "[planning-with-files] Read findings.md for research context. Continue from the current phase."
 fi
 exit 0

.cursor/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.factory/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.factory/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

.gemini/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

.mastracode/hooks.json

@@ -2,9 +2,9 @@
   "UserPromptSubmit": [
     {
       "type": "command",
-      "command": "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi",
+      "command": "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi",
       "timeout": 5000,
-      "description": "Remind agent about active plan on every user message for session recovery"
+      "description": "Inject plan context on every user message for session recovery after /clear"
     }
   ],
   "PreToolUse": [

.mastracode/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.opencode/skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:

.pi/skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

README.md

@@ -42,10 +42,11 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
 <details>
 <summary><strong>📦 Releases & Session Recovery</strong></summary>
 
-### Current Version: v2.26.0
+### Current Version: v2.26.1
 
 | Version | Highlights |
 |---------|------------|
+| **v2.26.1** | Fix: session catchup after `/clear` — path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
 | **v2.26.0** | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |
 | **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |
 | **v2.18.1** | Copilot garbled characters complete fix |
@@ -149,7 +150,7 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
 [![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)
 [![Mastra Code](https://img.shields.io/badge/Mastra%20Code-Skills-00BCD4)](https://code.mastra.ai)
 [![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)
-[![Version](https://img.shields.io/badge/version-2.26.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![Version](https://img.shields.io/badge/version-2.26.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
 [![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
 
 ## Quick Install

skills/planning-with-files/SKILL.md

@@ -7,7 +7,7 @@ hooks:
   UserPromptSubmit:
     - hooks:
         - type: command
-          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] Active plan detected. If you have not read task_plan.md, progress.md, and findings.md in this conversation, read them now before proceeding.'; fi"
+          command: "if [ -f task_plan.md ]; then echo '[planning-with-files] ACTIVE PLAN — current state:'; head -50 task_plan.md; echo ''; echo '--- recent progress ---'; tail -20 progress.md 2>/dev/null; echo ''; echo '[planning-with-files] Read findings.md for research context. Continue from the current phase.'; fi"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       hooks:
@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.23.0"
+  version: "2.26.1"
 ---
 
 # Planning with Files

skills/planning-with-files/scripts/session-catchup.py

@@ -17,12 +17,42 @@ from typing import List, Dict, Optional, Tuple
 PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
 
 
+def normalize_path(project_path: str) -> str:
+    """Normalize project path to match Claude Code's internal representation.
+
+    Claude Code stores session directories using the Windows-native path
+    (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
+    Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
+    string. This function converts Git Bash paths to Windows paths first.
+    """
+    p = project_path
+
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+
+    # Resolve to absolute path to handle relative paths and symlinks
+    try:
+        resolved = str(Path(p).resolve())
+        # On Windows, resolve() returns C:\Users\... which is what we want
+        if os.name == 'nt' or '\\' in resolved:
+            p = resolved
+    except (OSError, ValueError):
+        pass
+
+    return p
+
+
 def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
     """Resolve session storage path for the current runtime variant."""
-    sanitized = project_path.replace('/', '-')
-    if not sanitized.startswith('-'):
-        sanitized = '-' + sanitized
+    normalized = normalize_path(project_path)
+
+    # Claude Code's sanitization: replace path separators and : with -
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
     sanitized = sanitized.replace('_', '-')
+    # Strip leading dash if present (Unix absolute paths start with /)
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
 
     claude_path = Path.home() / '.claude' / 'projects' / sanitized
 
@@ -50,7 +80,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
 def parse_session_messages(session_file: Path) -> List[Dict]:
     """Parse all messages from a session file, preserving order."""
     messages = []
-    with open(session_file, 'r') as f:
+    with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
         for line_num, line in enumerate(f):
             try:
                 data = json.loads(line)

tests/test_clear_recovery.sh

@@ -0,0 +1,230 @@
+#!/bin/bash
+# test_clear_recovery.sh — Automated test for session recovery after /clear
+#
+# Tests that the UserPromptSubmit hook injects actual plan content
+# (not just advisory text) when task_plan.md exists.
+#
+# This simulates what happens after /clear:
+#   1. Context is empty
+#   2. User sends a message
+#   3. UserPromptSubmit hook fires
+#   4. Hook output is injected into context
+#
+# PASS = hook output contains actual plan content
+# FAIL = hook output is just advisory text or empty
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TESTDIR=$(mktemp -d)
+PASS=0
+FAIL=0
+
+cleanup() {
+    rm -rf "$TESTDIR"
+    echo ""
+    if [ "$FAIL" -eq 0 ]; then
+        echo "========================================="
+        echo "  ALL $PASS TESTS PASSED"
+        echo "========================================="
+    else
+        echo "========================================="
+        echo "  $FAIL FAILED, $PASS PASSED"
+        echo "========================================="
+        exit 1
+    fi
+}
+trap cleanup EXIT
+
+echo "=== Session Recovery Hook Test ==="
+echo "Test dir: $TESTDIR"
+echo ""
+
+# --- Setup: Create realistic planning files ---
+cat > "$TESTDIR/task_plan.md" << 'PLAN'
+# Task Plan
+
+## Goal
+Build a REST API with authentication, database, and tests
+
+## Current Phase
+Phase 2: Database Integration - in_progress
+
+## Phases
+
+### Phase 1: Project Setup
+**Status:** complete
+- [x] Initialize Node.js project
+- [x] Install dependencies
+
+### Phase 2: Database Integration
+**Status:** in_progress
+- [x] Set up PostgreSQL connection
+- [ ] Create user schema
+- [ ] Add migration scripts
+
+### Phase 3: Authentication
+**Status:** pending
+- [ ] JWT token generation
+- [ ] Login/register endpoints
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+| pg connection refused | 1 | Started docker container |
+PLAN
+
+cat > "$TESTDIR/progress.md" << 'PROGRESS'
+# Progress Log
+
+## Session: 2026-03-20
+**Phase:** Phase 2: Database Integration
+
+### Actions Taken
+1. Created database connection module
+2. Tested connection to PostgreSQL
+3. Fixed docker networking issue
+4. Started work on user schema
+
+### Files Modified
+- `src/db/connection.ts` — Database pool setup
+- `docker-compose.yml` — Added PostgreSQL service
+PROGRESS
+
+cat > "$TESTDIR/findings.md" << 'FINDINGS'
+# Findings
+
+## Technical Decisions
+| Decision | Chosen | Why |
+|----------|--------|-----|
+| ORM | Drizzle | Type-safe, lightweight |
+| Auth | JWT | Stateless, simple |
+FINDINGS
+
+# --- Test 1: Hook injects plan content (not just advisory) ---
+echo "Test 1: UserPromptSubmit hook injects plan content"
+cd "$TESTDIR"
+OUTPUT=$(bash -c 'if [ -f task_plan.md ]; then echo "[planning-with-files] ACTIVE PLAN — current state:"; head -50 task_plan.md; echo ""; echo "--- recent progress ---"; tail -20 progress.md 2>/dev/null; echo ""; echo "[planning-with-files] Read findings.md for research context. Continue from the current phase."; fi' 2>/dev/null)
+
+if echo "$OUTPUT" | grep -q "Build a REST API"; then
+    echo "  PASS: Hook output contains the goal"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook output missing the goal"
+    FAIL=$((FAIL + 1))
+fi
+
+if echo "$OUTPUT" | grep -q "Phase 2.*in_progress"; then
+    echo "  PASS: Hook output contains current phase status"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook output missing current phase"
+    FAIL=$((FAIL + 1))
+fi
+
+if echo "$OUTPUT" | grep -q "Database Integration"; then
+    echo "  PASS: Hook output contains phase name"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook output missing phase name"
+    FAIL=$((FAIL + 1))
+fi
+
+if echo "$OUTPUT" | grep -q "Created database connection module"; then
+    echo "  PASS: Hook output contains recent progress"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook output missing recent progress"
+    FAIL=$((FAIL + 1))
+fi
+
+if echo "$OUTPUT" | grep -q "ACTIVE PLAN"; then
+    echo "  PASS: Hook output has clear ACTIVE PLAN header"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook output missing ACTIVE PLAN header"
+    FAIL=$((FAIL + 1))
+fi
+
+echo ""
+
+# --- Test 2: Hook is silent when no plan exists ---
+echo "Test 2: Hook is silent when no task_plan.md"
+cd /tmp
+OUTPUT2=$(bash -c 'if [ -f task_plan.md ]; then echo "[planning-with-files] ACTIVE PLAN — current state:"; head -50 task_plan.md; fi' 2>/dev/null)
+
+if [ -z "$OUTPUT2" ]; then
+    echo "  PASS: No output when no plan file"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: Hook produced output without plan file"
+    FAIL=$((FAIL + 1))
+fi
+
+echo ""
+
+# --- Test 3: Session catchup path fix (Windows Git Bash paths) ---
+echo "Test 3: Session catchup path sanitization"
+SCRIPT="${REPO_ROOT}/skills/planning-with-files/scripts/session-catchup.py"
+PYTHON=$(command -v python3 || command -v python)
+
+if [ -f "$SCRIPT" ]; then
+    # Test that normalize_path handles Git Bash /c/ conversion
+    if grep -q "p\[1\].upper() + ':'" "$SCRIPT"; then
+        echo "  PASS: normalize_path converts /c/ to C: (drive letter conversion present)"
+        PASS=$((PASS + 1))
+    else
+        echo "  FAIL: normalize_path missing Git Bash drive letter conversion"
+        FAIL=$((FAIL + 1))
+    fi
+
+    # Test UTF-8 encoding parameter
+    if grep -q "encoding='utf-8'" "$SCRIPT"; then
+        echo "  PASS: session file opened with UTF-8 encoding"
+        PASS=$((PASS + 1))
+    else
+        echo "  FAIL: session file not opened with UTF-8 encoding"
+        FAIL=$((FAIL + 1))
+    fi
+
+    # Test that both \ and / are replaced in sanitization
+    if grep -q "replace('\\\\\\\\', '-')" "$SCRIPT" && grep -q "replace('/', '-')" "$SCRIPT"; then
+        echo "  PASS: sanitization handles both \\ and / separators"
+        PASS=$((PASS + 1))
+    else
+        echo "  FAIL: sanitization missing separator handling"
+        FAIL=$((FAIL + 1))
+    fi
+else
+    echo "  SKIP: session-catchup.py not found at $SCRIPT"
+fi
+
+echo ""
+
+# --- Test 4: PreToolUse hook still injects plan header ---
+echo "Test 4: PreToolUse hook injects plan header"
+cd "$TESTDIR"
+OUTPUT3=$(bash -c 'cat task_plan.md 2>/dev/null | head -30 || true' 2>/dev/null)
+
+if echo "$OUTPUT3" | grep -q "Task Plan"; then
+    echo "  PASS: PreToolUse outputs plan header"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: PreToolUse did not output plan"
+    FAIL=$((FAIL + 1))
+fi
+
+echo ""
+
+# --- Test 5: PostToolUse reminder mentions progress.md ---
+echo "Test 5: PostToolUse mentions progress.md"
+OUTPUT4=$(bash -c 'if [ -f task_plan.md ]; then echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."; fi' 2>/dev/null)
+
+if echo "$OUTPUT4" | grep -q "progress.md"; then
+    echo "  PASS: PostToolUse mentions progress.md"
+    PASS=$((PASS + 1))
+else
+    echo "  FAIL: PostToolUse does not mention progress.md"
+    FAIL=$((FAIL + 1))
+fi

tests/test_path_fix.py

@@ -0,0 +1,59 @@
+"""Test the path sanitization fix for session-catchup.py"""
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'skills', 'planning-with-files', 'scripts'))
+
+# Re-implement the fix here for testing (avoids import issues)
+def normalize_path(project_path):
+    p = project_path
+    # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
+    if len(p) >= 3 and p[0] == '/' and p[2] == '/':
+        p = p[1].upper() + ':' + p[2:]
+    try:
+        resolved = str(Path(p).resolve())
+        if os.name == 'nt' or os.sep == '\\':
+            p = resolved
+    except (OSError, ValueError):
+        pass
+    return p
+
+
+def sanitize(project_path):
+    normalized = normalize_path(project_path)
+    sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
+    sanitized = sanitized.replace('_', '-')
+    if sanitized.startswith('-'):
+        sanitized = sanitized[1:]
+    return sanitized
+
+
+expected = "C--Users-oasrvadmin-Documents-planning-with-files-repo"
+
+tests = {
+    "Git Bash": "/c/Users/oasrvadmin/Documents/planning-with-files-repo",
+    "Forward slash": "C:/Users/oasrvadmin/Documents/planning-with-files-repo",
+}
+
+all_pass = True
+for label, path in tests.items():
+    result = sanitize(path)
+    claude_dir = Path.home() / '.claude' / 'projects' / result
+    match = result == expected
+    exists = claude_dir.exists()
+    print(f"[{label}]")
+    print(f"  Input:    {path}")
+    print(f"  Result:   {result}")
+    print(f"  Expected: {expected}")
+    print(f"  Match:    {match}")
+    print(f"  Dir exists: {exists}")
+    print()
+    if not match:
+        all_pass = False
+
+if all_pass:
+    print("ALL TESTS PASSED")
+else:
+    print("SOME TESTS FAILED")
+    sys.exit(1)