docs: add feature backlog and track file moves in hooks

[carlos-alm]

Summary

• Create roadmap/ folder and add BACKLOG.md with 20 prioritized feature items derived from competitive analysis, including assessment columns for dependency impact, foundation alignment, problem-fit scoring, and breaking change tracking
• Move ROADMAP.md and llm-integration.md into roadmap/ to consolidate planning docs
• Add track-moves.sh PostToolUse hook that detects mv/git mv/cp in Bash commands and logs affected paths to session-edits.log, fixing false blocks from guard-git.sh when files are moved

Test plan

• Verify roadmap/BACKLOG.md renders correctly with all 20 items and scoring guide
• Verify roadmap/ROADMAP.md and roadmap/llm-integration.md are intact after move
• Test track-moves.sh by running mv in a session and confirming paths appear in .claude/session-edits.log
• Confirm guard-git.sh allows committing moved files after track-moves.sh logs them

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Completed ✅

Root Cause Analysis

Problem Being Solved: This PR addresses two distinct issues:

1. Documentation organization - Consolidating planning docs under roadmap/ and adding a comprehensive feature backlog derived from competitive analysis
2. Hook system gap - Fixing false positives in guard-git.sh when files are moved/copied but not tracked in the session edit log

Why This Approach: The file move tracking uses a PostToolUse hook on Bash commands to detect mv/git mv/cp operations and log all affected paths to the session edit log. This ensures guard-git.sh can validate commits that include moved files. The documentation reorganization follows a logical structure.

Risk Assessment: Low risk - this is primarily documentation organization with a defensive shell script addition.

Critical Concerns (if any)

None identified. All changes are additive and defensive in nature.

Code Quality Assessment

✅ Excellent Documentation Structure

• Comprehensive backlog: 20 well-researched features with clear assessment criteria
• Proper organization: roadmap/ folder consolidates all planning docs logically
• Scoring methodology: The 4-column assessment framework (Zero-dep, Foundation-aligned, Problem-fit, Breaking) provides systematic prioritization

✅ Robust Hook Implementation

• Correct command detection: Lines 27,48 - Regex properly matches mv, git mv, and cp with word boundaries
• Smart argument parsing: Lines 51-77 - Handles quoted arguments, filters flags, and respects shell quoting rules
• Safe path resolution: Lines 69-73 - Uses path.relative() to prevent directory traversal, only logs paths within project
• Defensive coding: Lines 20,78 - Multiple fallback points with || true to never break the tool chain
• Informational only: Line 93 - Always exits 0, never blocks execution (correct for PostToolUse hook)

✅ Configuration Integration

• Proper hook registration: Lines 67-75 in .claude/settings.json correctly add the new hook to PostToolUse for Bash commands
• Consistent timeout: 5s timeout matches other tracking hooks

✅ Security Considerations

• No shell injection: Uses execFileSync semantics via Node.js argument parsing
• Input validation: Extracts JSON safely, validates commands before processing
• Privilege principle: Logging only - no file system modifications

⚠️ Minor Technical Notes

1. Line 48: Regex could theoretically match git mvp or git mv-branch but this is extremely unlikely in practice
2. Lines 69-72: The relative path calculation assumes $PROJECT_DIR is always the git root, which should be true given the hook context

Final Assessment

Root Cause Analysis

Problem Being Solved: Addresses real issues - false positives in commit validation when files are moved, and lack of organized feature planning documentation.

Why This Approach: File move tracking is the correct architectural solution - detect at the Bash command level and integrate with existing session tracking. Documentation organization follows established patterns.

Risk Assessment: Minimal risk - purely additive changes that improve existing safety mechanisms.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Well-implemented solution to real problems. The hook script demonstrates strong understanding of shell command parsing and defensive programming. Documentation organization is excellent and will improve project maintainability. No breaking changes or risky patterns detected.

Minor suggestions for follow-up (not blocking):

1. Consider adding a test case for the regex patterns in future hook testing
2. The backlog assessment columns could be filled out in a future planning session

This PR successfully solves the stated problems with clean, defensive implementations.

---

[greptile-apps]

Greptile Summary

This PR adds infrastructure to track file moves in hooks and consolidates planning documentation. The track-moves.sh hook solves a critical gap in the session safety system: when files are moved via mv/git mv/cp, they weren't being logged to session-edits.log, causing guard-git.sh to incorrectly block commits. The hook parses Bash commands, extracts affected paths from move operations, and logs both source and destination paths.

• Created roadmap/ folder and moved ROADMAP.md and llm-integration.md into it for better organization
• Added BACKLOG.md with 20 prioritized feature items from competitive analysis, including assessment framework for dependency impact, foundation alignment, problem-fit scoring, and breaking change tracking
• Implemented track-moves.sh PostToolUse hook that detects mv/git mv/cp commands and logs paths to session-edits.log
• Registered the new hook in .claude/settings.json with 5s timeout

All changes are purely additive and non-breaking.

Confidence Score: 5/5

• This PR is safe to merge with no concerns
• All changes are documentation moves and a new safety hook that only logs data without blocking operations. The hook implementation is defensive with proper error handling, the shell script exits 0 in all cases, and the documentation files are simple renames with no content changes.
• No files require special attention

Important Files Changed

Filename	Overview
.claude/hooks/track-moves.sh	New PostToolUse hook that parses mv/git mv/cp commands and logs affected paths to session-edits.log for commit validation
.claude/settings.json	Added PostToolUse hook registration for track-moves.sh on Bash tool calls with 5s timeout
roadmap/BACKLOG.md	New feature backlog with 20 prioritized items derived from competitive analysis, includes scoring rubric for assessment
roadmap/ROADMAP.md	Moved from root to roadmap/ directory to consolidate planning documentation
roadmap/llm-integration.md	Moved from docs/ to roadmap/ directory for better planning doc organization

_{Last reviewed commit: cfe633b}

[greptile-apps]

_{5 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}