Update claude.md

Author: jdalton

CLAUDE.md

@@ -49,6 +49,23 @@ You are a **Principal Software Engineer** responsible for:
 - **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
 - **Coverage report**: `pnpm test:unit:coverage`
 
+### Cross-Platform Compatibility - CRITICAL: Windows and POSIX
+- **🚨 MANDATORY**: Tests and functionality MUST work on both POSIX (macOS/Linux) and Windows systems
+- **Path handling**: ALWAYS use `path.join()`, `path.resolve()`, `path.sep` for file paths
+  - ❌ WRONG: `'/usr/local/bin/npm'` (hard-coded POSIX path)
+  - ✅ CORRECT: `path.join(path.sep, 'usr', 'local', 'bin', 'npm')` (cross-platform)
+  - ❌ WRONG: `'/project/package-lock.json'` (hard-coded forward slashes)
+  - ✅ CORRECT: `path.join('project', 'package-lock.json')` (uses correct separator)
+- **Temp directories**: Use `os.tmpdir()` for temporary file paths in tests
+  - ❌ WRONG: `'/tmp/test-project'` (POSIX-specific)
+  - ✅ CORRECT: `path.join(os.tmpdir(), 'test-project')` (cross-platform)
+- **Path separators**: Never hard-code `/` or `\` in paths
+  - Use `path.sep` when you need the separator character
+  - Use `path.join()` to construct paths correctly
+- **File URLs**: Use `pathToFileURL()` and `fileURLToPath()` from `node:url` when working with file:// URLs
+- **Line endings**: Be aware of CRLF (Windows) vs LF (Unix) differences when processing text files
+- **Shell commands**: Consider platform differences in shell commands and utilities
+
 ### Git Commit Guidelines
 - **🚨 FORBIDDEN**: NEVER add Claude co-authorship or Claude signatures to commits
 - **🚨 FORBIDDEN**: Do NOT include "Generated with Claude Code" or similar AI attribution in commit messages