# Windows 11 Cross-Platform Compatibility

## Summary

This document describes the Windows 11 compatibility fixes implemented for the Cleave skill installation system.

## Issues Addressed

### Critical Issues Fixed

1. **Path Separator Bug (CRITICAL)** ✅
   - **Issue**: Hardcoded Unix path separator (`+ "/"`) caused "Path escapes home directory" error on Windows
   - **Fix**: Replaced with `Path.is_relative_to()` for cross-platform path comparison
   - **Location**: `install.py:131`

2. **Stale Directory Copies (CRITICAL)** ✅
   - **Issue**: Windows fallback creates directory copy instead of symlink, which never updates on package upgrade
   - **Fix**: Added `.version` file tracking and automatic update detection
   - **Location**: `install.py:59-61, 246-279`

3. **Partial Copy Cleanup (CRITICAL)** ✅
   - **Issue**: If `shutil.copytree()` fails mid-operation, partial files remain orphaned
   - **Fix**: Added cleanup in exception handler
   - **Location**: `install.py:64-68`

4. **Windows Long Path Validation (HIGH)** ✅
   - **Issue**: Paths >260 characters fail on Windows without long path support enabled
   - **Fix**: Added pre-validation with helpful error message
   - **Location**: `install.py:92-117, 143-151`

### Additional Improvements

5. **Symlink Privilege Fallback** ✅
   - Windows requires Developer Mode or admin privileges for symlinks
   - Automatically falls back to directory copy with user notification
   - **Location**: `install.py:27-72`

6. **MCP Dependency Check** ✅
   - Added programmatic check for Sequential Thinking MCP server requirement
   - Provides installation instructions if missing
   - **Location**: `skill/__init__.py:18-42`

## Implementation Details

### Version Tracking

Directory copies now include a `.version` file:

```
~/.claude/skills/cleave/
├── SKILL.md
├── .version      # <- New: tracks installed version
└── __init__.py
```

On subsequent `cleave install-skill` runs:
1. Checks if existing directory copy has `.version` file
2. Compares installed version with current package version
3. Auto-updates if stale (removes old, installs new)

### Path Validation

Before installation, validates:
- Path length < 260 characters (Windows MAX_PATH)
- Path is within home directory (security check)
- Extended-length prefix detection (`\\?\`)

### Fallback Strategy

```
┌─────────────────────────┐
│ Attempt symlink_to()    │
└────────┬────────────────┘
         │
         ├─ Success → Done (Unix/Windows Developer Mode)
         │
         └─ OSError
            │
            └─ Windows?
               ├─ Yes → shutil.copytree() + .version
               │        ├─ Success → Done (fallback)
               │        └─ Fail → Cleanup + Error
               │
               └─ No → Error (unexpected symlink failure)
```

## Test Coverage

Added 12 new tests in `tests/test_windows_compat.py`:

### Cross-Platform Path Handling (2 tests)
- ✅ Path validation works with Windows backslashes
- ✅ Path escape detection prevents directory traversal

### Symlink Fallback (4 tests)
- ✅ Falls back to copy on Windows permission error
- ✅ Uses actual symlink on Unix
- ✅ InstallResult indicates copy method used
- ✅ Recognizes existing directory copy installations

### Long Path Validation (3 tests)
- ✅ Detects paths >260 chars on Windows
- ✅ Allows short paths on Windows
- ✅ Skips validation on Unix (no limit)

### Version Tracking (2 tests)
- ✅ Creates .version file for directory copies
- ✅ Detects and updates stale copies

### MCP Dependency (1 test)
- ✅ Returns installation instructions for Sequential Thinking MCP

**Total Test Count**: 28 (16 original + 12 new)
**All tests passing**: ✅

## Known Limitations

### 1. Copy vs Symlink Performance
- **Impact**: Directory copies consume more disk space and don't reflect live package updates
- **Mitigation**: Version tracking auto-updates on upgrade
- **Alternative**: Users can enable Windows Developer Mode for true symlinks

### 2. UNC Path Support
- **Status**: Not explicitly tested or validated
- **Impact**: Network paths (`\\server\share\home`) may fail
- **Recommendation**: Use local disk paths for Claude Code configuration

### 3. Race Conditions (TOCTOU)
- **Status**: Small window between `unlink()` and `symlink_to()`
- **Impact**: Low risk on single-user systems
- **Recommendation**: Future enhancement to use atomic operations

### 4. Antivirus False Positives
- **Status**: No detection or recovery mechanism
- **Impact**: Some AV software may block symlink or copy operations
- **Recommendation**: Document AV exclusion requirements if users report issues

## Deployment Status

**Verdict**: ✅ **APPROVED** for Windows 11 deployment

- All critical issues resolved
- Comprehensive test coverage
- Graceful fallback for symlink privilege limitations
- Auto-update mechanism for directory copies

## Migration Path

### For Existing Windows Users with Manual Installs

If you previously created `~/.claude/skills/cleave` manually:

1. **If it's a symlink**: No action needed
2. **If it's a directory**: Run `cleave install-skill` to add version tracking

### For Package Upgrades

After running `pip install --upgrade styrene-cleave`:

1. Run `cleave install-skill`
2. System will detect stale version and auto-update
3. No manual intervention required

## Future Enhancements

### Medium Priority
- [ ] Junction point support (Windows directory-only links without privileges)
- [ ] Atomic update operations (eliminate TOCTOU window)
- [ ] Better Windows error messages (detect Developer Mode status)

### Low Priority
- [ ] UNC path validation and support
- [ ] Antivirus interference detection
- [ ] Progress indication for large copies

## References

- **Adversarial Review Report**: See adversarial agent output
- **GitHub Issue**: (Windows 11 compatibility)
- **Python Docs**: `Path.is_relative_to()` (Python 3.9+)
- **Windows Docs**: Symlink creation requires `SeCreateSymbolicLinkPrivilege`
