memorylink 1.0.0

package/docs/FEATURE_4_TAG_NORMALIZATION_PLAN.md

@@ -0,0 +1,211 @@
+# 🎯 FEATURE 4: TAG NORMALIZATION - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Automatically normalize tags (lowercase, hyphenate spaces) for consistent filtering and search.
+
+**Why:** Users type tags inconsistently ("TypeScript", "typescript", "Type Script") leading to broken filtering. Normalization ensures tags work reliably.
+
+**Priority:** 🟡 HIGH (Grok flagged as critical UX gap)  
+**Effort:** 1 day  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTICATION CRITERIA
+
+### Must Have:
+- ✅ Tags automatically normalized on input
+- ✅ Normalization: lowercase, hyphenate spaces
+- ✅ Examples: "TypeScript" → "typescript", "Type Script" → "type-script"
+- ✅ Works in all commands (memory, learn, change, snippet)
+- ✅ Normalized tags stored in JSONL
+- ✅ Search/filter uses normalized tags
+- ✅ Backward compatible (existing tags work)
+
+### Performance:
+- ✅ Normalization completes in < 1ms
+- ✅ No noticeable delay
+
+### Error Handling:
+- ✅ Empty tags → Skip
+- ✅ Special characters → Preserve or sanitize
+- ✅ Very long tags → Truncate or error
+
+---
+
+## 🏗️ DESIGN
+
+### Normalization Rules:
+```typescript
+function normalizeTag(tag: string): string {
+  return tag
+    .toLowerCase()           // "TypeScript" → "typescript"
+    .trim()                  // Remove whitespace
+    .replace(/\s+/g, '-')   // "Type Script" → "type-script"
+    .replace(/[^a-z0-9-]/g, '') // Remove special chars (optional)
+    .replace(/-+/g, '-')     // Multiple hyphens → single
+    .replace(/^-|-$/g, '');  // Remove leading/trailing hyphens
+}
+```
+
+### Examples:
+- "TypeScript" → "typescript"
+- "Type Script" → "type-script"
+- "React Hooks" → "react-hooks"
+- "API_KEY" → "api-key"
+- "  Python  " → "python"
+- "C++" → "c" (or "cpp" if we preserve)
+
+### Implementation Flow:
+```
+1. User provides tags: "TypeScript, React Hooks"
+2. Parse tags (split by comma)
+3. Normalize each tag
+4. Store normalized tags in JSONL
+5. Search/filter uses normalized tags
+```
+
+### Files to Modify:
+- `src/utils.ts` (MODIFY - add normalizeTag function)
+- `src/utils.ts` (MODIFY - update parseTags to normalize)
+- All commands that use tags (already use parseTags)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test `normalizeTag()` - lowercase conversion
+- [ ] Test `normalizeTag()` - space to hyphen
+- [ ] Test `normalizeTag()` - trim whitespace
+- [ ] Test `normalizeTag()` - special characters
+- [ ] Test `normalizeTag()` - multiple spaces
+- [ ] Test `normalizeTag()` - leading/trailing hyphens
+- [ ] Test `parseTags()` - normalization integration
+
+### Integration Tests:
+- [ ] Test memory command with mixed-case tags
+- [ ] Test learn command with spaced tags
+- [ ] Test snippet command with special chars
+- [ ] Test search with normalized tags
+- [ ] Test filter with normalized tags
+- [ ] Test backward compatibility
+
+### End-to-End Tests:
+- [ ] Test in real project
+- [ ] Test with actual user input
+- [ ] Test tag filtering works
+- [ ] Test tag search works
+
+### Hard Tests (Edge Cases):
+- [ ] Test with empty tags
+- [ ] Test with only spaces
+- [ ] Test with only special chars
+- [ ] Test with very long tags
+- [ ] Test with unicode characters
+- [ ] Test with mixed languages
+- [ ] Test with numbers in tags
+
+### Performance Tests:
+- [ ] Test normalization speed (< 1ms)
+- [ ] Test with many tags
+- [ ] Test with large tag strings
+
+### Cross-Platform Tests:
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows
+
+### Manual Tests:
+- [ ] Real user input
+- [ ] Real tag filtering
+- [ ] Real tag search
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Add normalizeTag function
+- Create `normalizeTag()` in `src/utils.ts`
+- Implement normalization rules
+- Add unit tests
+
+### Step 2: Update parseTags function
+- Modify `parseTags()` to normalize tags
+- Ensure backward compatibility
+- Test with existing tags
+
+### Step 3: Test all commands
+- Test memory command
+- Test learn command
+- Test change command
+- Test snippet command
+- Verify tags are normalized
+
+### Step 4: Test search/filter
+- Test tag search
+- Test tag filtering
+- Verify normalized tags work
+
+### Step 5: Verify backward compatibility
+- Test with existing tags
+- Test with mixed-case search
+- Ensure no breaking changes
+
+### Step 6: Write tests
+- Write unit tests
+- Write integration tests
+- Write E2E tests
+
+### Step 7: Test everything
+- Run all tests
+- Manual testing
+- Cross-platform testing
+
+### Step 8: Verify
+- All tests pass
+- Performance acceptable
+- Code quality passes
+- Documentation updated
+
+---
+
+## 🚨 ERROR HANDLING
+
+### Error Cases:
+1. **Empty tag after normalization**
+   - Skip the tag (not an error)
+   - Continue with other tags
+
+2. **All tags empty**
+   - Store as empty array
+   - Not an error
+
+3. **Invalid characters**
+   - Remove or sanitize
+   - Continue processing
+
+---
+
+## 📊 SUCCESS METRICS
+
+### Feature is Complete When:
+- ✅ All code written
+- ✅ All tests written
+- ✅ All tests pass (100%)
+- ✅ Performance < 1ms
+- ✅ Code quality passes
+- ✅ Works on all platforms
+- ✅ Backward compatible
+- ✅ Manual testing done
+- ✅ No bugs found
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+

package/docs/FEATURE_5_WINDOWS_PATH_HANDLING_PLAN.md

@@ -0,0 +1,199 @@
+# 🎯 FEATURE 5: WINDOWS/GIT PATH HANDLING - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Ensure cross-platform path handling works correctly on Windows, Linux, and macOS, especially for Git paths.
+
+**Why:** Windows uses backslashes, Git uses forward slashes. Path inconsistencies break file operations and Git integration.
+
+**Priority:** 🟡 HIGH (Grok flagged as critical cross-platform issue)  
+**Effort:** 1 day  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTANCE CRITERIA
+
+### Must Have:
+- ✅ All paths normalized to forward slashes (Git-compatible)
+- ✅ Works on Windows (backslash → forward slash)
+- ✅ Works on Linux/macOS (unchanged)
+- ✅ Git paths handled correctly
+- ✅ File operations work cross-platform
+- ✅ Path comparisons work correctly
+- ✅ Relative paths work correctly
+
+### Performance:
+- ✅ Path normalization completes in < 1ms
+- ✅ No noticeable delay
+
+### Error Handling:
+- ✅ Invalid paths → Clear error
+- ✅ Path traversal attempts → Blocked
+- ✅ Absolute paths → Handled correctly
+
+---
+
+## 🏗️ DESIGN
+
+### Path Normalization Rules:
+```typescript
+function normalizePath(path: string): string {
+  // Normalize to forward slashes (Git-compatible)
+  return path.replace(/\\/g, '/');
+}
+
+function normalizePathForPlatform(path: string, root: string): string {
+  // For storage: always use forward slashes (Git-compatible)
+  // For file operations: use platform-specific paths
+  const normalized = normalizePath(path);
+  
+  // If absolute path, make relative to root
+  if (path.isAbsolute(normalized)) {
+    return path.relative(root, normalized);
+  }
+  
+  return normalized;
+}
+```
+
+### Implementation Points:
+1. **Storage**: Always use forward slashes (Git-compatible)
+2. **File Operations**: Use platform-specific paths
+3. **Comparisons**: Normalize before comparing
+4. **Git Operations**: Use forward slashes
+
+### Files to Modify:
+- `src/utils.ts` (MODIFY - add normalizePath functions)
+- `src/commands/protect.ts` (MODIFY - normalize paths)
+- `src/commands/change.ts` (MODIFY - normalize paths)
+- `src/commands/snippet.ts` (MODIFY - normalize paths)
+- `src/commands/hooks.ts` (MODIFY - normalize paths in hooks)
+- `src/commands/auto-log.ts` (MODIFY - normalize paths)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test `normalizePath()` - Windows backslashes
+- [ ] Test `normalizePath()` - Mixed slashes
+- [ ] Test `normalizePath()` - Already normalized
+- [ ] Test `normalizePathForPlatform()` - Absolute paths
+- [ ] Test `normalizePathForPlatform()` - Relative paths
+- [ ] Test path comparisons
+
+### Integration Tests:
+- [ ] Test protect command with Windows paths
+- [ ] Test change command with Windows paths
+- [ ] Test snippet command with Windows paths
+- [ ] Test Git hooks with Windows paths
+- [ ] Test auto-log with Windows paths
+
+### End-to-End Tests:
+- [ ] Test on Windows (if available)
+- [ ] Test on Linux
+- [ ] Test on macOS
+- [ ] Test Git operations
+- [ ] Test file operations
+
+### Hard Tests (Edge Cases):
+- [ ] Test with mixed slashes
+- [ ] Test with UNC paths (Windows)
+- [ ] Test with very long paths
+- [ ] Test with special characters
+- [ ] Test with path traversal attempts
+- [ ] Test with absolute paths
+- [ ] Test with relative paths
+
+### Cross-Platform Tests:
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows (if available)
+- [ ] Test path handling on all platforms
+
+### Manual Tests:
+- [ ] Real file paths
+- [ ] Real Git paths
+- [ ] Real user workflow
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Add normalizePath functions
+- Create `normalizePath()` in `src/utils.ts`
+- Create `normalizePathForPlatform()` in `src/utils.ts`
+- Add unit tests
+
+### Step 2: Update protect.ts
+- Normalize paths before storing
+- Normalize paths in comparisons
+- Test Windows paths
+
+### Step 3: Update change.ts
+- Normalize file paths
+- Test Windows paths
+
+### Step 4: Update snippet.ts
+- Normalize file paths
+- Test Windows paths
+
+### Step 5: Update hooks.ts
+- Normalize paths in hook scripts
+- Test Windows paths
+
+### Step 6: Update auto-log.ts
+- Normalize paths from Git
+- Test Windows paths
+
+### Step 7: Test everything
+- Run all tests
+- Manual testing
+- Cross-platform testing
+
+### Step 8: Verify
+- All tests pass
+- Performance acceptable
+- Code quality passes
+- Documentation updated
+
+---
+
+## 🚨 ERROR HANDLING
+
+### Error Cases:
+1. **Invalid path**
+   - Validate path format
+   - Clear error message
+
+2. **Path traversal**
+   - Block ".." in paths
+   - Clear error message
+
+3. **Absolute path issues**
+   - Convert to relative
+   - Clear error message
+
+---
+
+## 📊 SUCCESS METRICS
+
+### Feature is Complete When:
+- ✅ All code written
+- ✅ All tests written
+- ✅ All tests pass (100%)
+- ✅ Performance < 1ms
+- ✅ Code quality passes
+- ✅ Works on all platforms
+- ✅ Manual testing done
+- ✅ No bugs found
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+

package/docs/FEATURE_6_CONFLICT_DETECTION_PLAN.md

@@ -0,0 +1,126 @@
+# 🎯 FEATURE 6: CONFLICT DETECTION IN DOCTOR - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Add conflict/duplication detection to `memorylink doctor` command.
+
+**Why:** Users create duplicate memories or conflicting entries. Doctor should warn about these issues.
+
+**Priority:** 🟡 HIGH (Perplexity flagged as critical UX gap)  
+**Effort:** 1 day  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTANCE CRITERIA
+
+### Must Have:
+- ✅ Detect duplicate memories (same details)
+- ✅ Detect conflicting memories (contradictory information)
+- ✅ Detect duplicate learnings (same problem/solution)
+- ✅ Show conflicts in doctor output
+- ✅ Clear warnings with IDs
+- ✅ Suggest actions (merge, deprecate, etc.)
+
+### Performance:
+- ✅ Conflict detection completes in < 1s
+- ✅ Works with large logs (1000+ entries)
+
+### Error Handling:
+- ✅ Invalid entries → Skip gracefully
+- ✅ Corrupted logs → Report but continue
+
+---
+
+## 🏗️ DESIGN
+
+### Conflict Types:
+1. **Exact Duplicates**: Same details, same timestamp range
+2. **Similar Duplicates**: Same details, different timestamps
+3. **Conflicting Rules**: Contradictory decisions/rules
+4. **Duplicate Learnings**: Same problem/solution
+
+### Detection Logic:
+```typescript
+function detectConflicts(memories: MemoryEntry[]): Conflict[] {
+  const conflicts: Conflict[] = [];
+  
+  // Group by normalized details
+  const groups = groupBy(memories, normalizeText);
+  
+  // Find duplicates
+  for (const [key, entries] of groups) {
+    if (entries.length > 1) {
+      conflicts.push({
+        type: 'duplicate',
+        entries: entries.map(e => e.id),
+        message: `Duplicate memory: "${entries[0].details.substring(0, 50)}..."`
+      });
+    }
+  }
+  
+  // Find conflicts (contradictory rules/decisions)
+  const rules = memories.filter(m => m.type === 'rule' || m.type === 'decision');
+  // Check for contradictions...
+  
+  return conflicts;
+}
+```
+
+### Files to Modify:
+- `src/commands/doctor.ts` (MODIFY - add conflict detection)
+- `src/types.ts` (MODIFY - add Conflict type)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test duplicate detection
+- [ ] Test conflict detection
+- [ ] Test with empty logs
+- [ ] Test with large logs
+
+### Integration Tests:
+- [ ] Test doctor command with conflicts
+- [ ] Test doctor command without conflicts
+- [ ] Test with real data
+
+### End-to-End Tests:
+- [ ] Test in real project
+- [ ] Test with actual duplicates
+- [ ] Test with actual conflicts
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Add Conflict type
+- Add to `src/types.ts`
+- Define conflict structure
+
+### Step 2: Implement conflict detection
+- Add functions to `src/commands/doctor.ts`
+- Detect duplicates
+- Detect conflicts
+
+### Step 3: Integrate into doctor
+- Add conflict check to doctor command
+- Display conflicts clearly
+
+### Step 4: Test
+- Write tests
+- Manual testing
+
+### Step 5: Verify
+- All tests pass
+- Performance acceptable
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+