@blxzer/cursor-trellis 0.2.8 → 0.3.0

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -1,634 +1,634 @@
-# Cross-Platform Thinking Guide (OS / path)
-
-> **Purpose**: Catch OS and path assumptions before they become bugs.
->
-> **Note (cursor-only fork):** This guide covers **operating-system and filesystem** portability (Windows vs macOS/Linux). AI platform adapter sync is Cursor-only; see `cross-layer-thinking-guide.md` for template consistency.
-
----
-
-## Why This Matters
-
-**Most cross-platform bugs come from implicit assumptions**:
-
-- Assumed shebang works → breaks on Windows
-- Assumed `/` path separator → breaks on Windows
-- Assumed `\n` line endings → inconsistent behavior
-- Assumed command availability → `grep` vs `findstr`
-
----
-
-## Platform Differences Checklist
-
-### 1. Script Execution
-
-| Assumption | macOS/Linux | Windows |
-|------------|-------------|---------|
-| Shebang (`#!/usr/bin/env python3`) | ✅ Works | ❌ Ignored |
-| Direct execution (`./script.py`) | ✅ Works | ❌ Fails |
-| `python3` command | ✅ Always available | ⚠️ May need `python` |
-| `python` command | ⚠️ May be Python 2 | ✅ Usually Python 3 |
-
-**Rule 1**: For user-facing docs, help text, and error messages, either:
-
-- state the platform rule explicitly (`python` on Windows, `python3` elsewhere), or
-- render the command through the same platform-aware helper / placeholder the code uses.
-
-```python
-# BAD - Assumes shebang works
-print("Usage: ./script.py <args>")
-print("Run: script.py <args>")
-
-# GOOD - Platform-aware wording
-print("Usage: python on Windows, python3 elsewhere")
-print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
-```
-
-**Rule 2**: When generating config files at init time, use placeholder + platform detection:
-
-```typescript
-// In template file (settings.json):
-{ "command": "{{PYTHON_CMD}} .cursor/hooks/script.py" }
-
-// In configurator:
-function getPythonCommand(): string {
-  return process.platform === "win32" ? "python" : "python3";
-}
-
-function replacePlaceholders(content: string): string {
-  return content.replace(/\{\{PYTHON_CMD\}\}/g, getPythonCommand());
-}
-```
-
-**Rule 3**: When calling Python at runtime from JavaScript, detect platform dynamically:
-
-```javascript
-import { platform } from "os"
-
-const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
-execSync(`${PYTHON_CMD} "${scriptPath}"`, { ... })
-```
-
-**Rule 4**: If you need to verify Python is actually installed (not just choose
-the command), probe the same platform-selected alias you will later render or
-execute:
-
-```typescript
-function getPythonCommand(platform = process.platform): string {
-  return platform === "win32" ? "python" : "python3";
-}
-
-function warnIfPythonTooOld(): void {
-  const cmd = getPythonCommand();
-  try {
-    execSync(`${cmd} --version`, { stdio: "pipe" });
-  } catch {
-    // Missing Python is a separate error path; don't silently swap aliases.
-  }
-}
-```
-
-**Rule 5**: Don't assume the Python version the AI CLI uses matches your shell's `python3`. The user's terminal may resolve `python3` → homebrew 3.11, but Cursor spawns hook subprocesses with a minimal PATH that resolves `python3` → `/usr/bin/python3` → macOS system 3.9. Distributed templates must either target the lowest plausible version or use `from __future__ import annotations` for PEP 604 syntax. See `cli/backend/script-conventions.md` → **CRITICAL: PEP 604 Annotations Require `from __future__ import annotations`** for the hard rule and audit check.
-
-**Rule 6**: When calling Python from Python, use `sys.executable`:
-
-```python
-import sys
-import subprocess
-
-# BAD - Hardcoded command
-subprocess.run(["python3", "other_script.py"])
-
-# GOOD - Use current interpreter
-subprocess.run([sys.executable, "other_script.py"])
-```
-
-### 2. Path Handling
-
-| Assumption | macOS/Linux | Windows |
-|------------|-------------|---------|
-| `/` separator | ✅ Works | ⚠️ Sometimes works |
-| `\` separator | ❌ Escape char | ✅ Native |
-| `pathlib.Path` | ✅ Works | ✅ Works |
-
-**Rule (Python)**: Use `pathlib.Path` for all path operations.
-
-```python
-# BAD - String concatenation
-path = base + "/" + filename
-
-# GOOD - pathlib
-from pathlib import Path
-path = Path(base) / filename
-```
-
-#### Logical key vs filesystem path (TypeScript)
-
-A path string has two distinct roles. **Treat them differently.**
-
-| Role | OS-native (`\` on Windows) | Always POSIX (`/`) |
-|------|---------------------------|--------------------|
-| `fs.readFileSync(p)` / `path.join(cwd, x)` for fs call | ✅ Required | ❌ May fail on Windows |
-| `Map<relPath, content>` key, JSON field, hash dictionary key, anything persisted across OS | ❌ Cross-OS mismatch | ✅ Required |
-
-**Rule**: Anywhere a path string crosses OS or persists (Map keys consumed by another OS, JSON fields, hash dictionary keys), normalize to POSIX. Anywhere it goes straight to `fs.*`, leave OS-native.
-
-**Single source of truth**: `packages/cli/src/utils/posix.ts` exports `toPosix(p)`. Don't sprinkle `replaceAll('\\', '/')` at every `path.join` site — apply `toPosix` **once at the boundary**: collector exit (Map key entering hash dictionary) or write-time (`saveHashes` before `JSON.stringify`).
-
-```typescript
-// BAD - logical key carries OS-native separator
-function collectTemplates(): Map<string, string> {
-  const files = new Map<string, string>();
-  for (const entry of walk(dir)) {
-    files.set(path.join(".cursor", entry), readFile(entry));  // \ on Windows
-  }
-  return files;
-}
-
-// GOOD - normalize at the boundary
-import { toPosix } from "../utils/posix.js";
-
-function collectTemplates(): Map<string, string> {
-  const files = new Map<string, string>();
-  for (const entry of walk(dir)) {
-    files.set(toPosix(path.join(".cursor", entry)), readFile(entry));
-  }
-  return files;
-}
-
-// ALSO ACCEPTABLE - write-side defense (for storage helpers like saveHashes)
-function saveHashes(cwd: string, hashes: Record<string, string>): void {
-  const normalized = Object.fromEntries(
-    Object.entries(hashes).map(([k, v]) => [toPosix(k), v])
-  );
-  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(normalized, null, 2));
-}
-```
-
-**Common offender**: `path.relative(cwd, fullPath)` produces `\` on Windows. If you then use that string as a hash dictionary lookup key (`hashes[relPath]`), `toPosix` it first, or the lookup misses on Windows.
-
-### 3. Line Endings
-
-| Format | macOS/Linux | Windows | Git |
-|--------|-------------|---------|-----|
-| `\n` (LF) | ✅ Native | ⚠️ Some tools | ✅ Normalized |
-| `\r\n` (CRLF) | ⚠️ Extra char | ✅ Native | Converted |
-
-**Rule 1**: Use `.gitattributes` to enforce consistent line endings.
-
-```gitattributes
-* text=auto eol=lf
-*.sh text eol=lf
-*.py text eol=lf
-```
-
-**Rule 2**: When hashing or comparing **content** across platforms, normalize line endings before computing the hash. `.gitattributes` only governs git checkout — files written by users, scripts, or `core.autocrlf=true` may still arrive as CRLF, and `sha256(LF)` ≠ `sha256(CRLF)` for otherwise-identical content.
-
-```typescript
-// BAD - Windows users with autocrlf=true get a different hash
-export function computeHash(content: string): string {
-  return createHash("sha256").update(content, "utf-8").digest("hex");
-}
-
-// GOOD - normalize before hashing so logical content hashes identically
-export function computeHash(content: string): string {
-  const normalized = content.replace(/\r\n/g, "\n");
-  return createHash("sha256").update(normalized, "utf-8").digest("hex");
-}
-```
-
-Apply this rule wherever the hash crosses OS boundaries (template hash dictionary, content fingerprints stored in JSON, integrity checks against a remote registry).
-
-### 4. Environment Variables
-
-| Variable | macOS/Linux | Windows |
-|----------|-------------|---------|
-| `HOME` | ✅ Set | ❌ Use `USERPROFILE` |
-| `PATH` separator | `:` | `;` |
-| Case sensitivity | ✅ Case-sensitive | ❌ Case-insensitive |
-
-**Rule 1**: Use `pathlib.Path.home()` instead of environment variables.
-
-```python
-# BAD
-home = os.environ.get("HOME")
-
-# GOOD
-home = Path.home()
-```
-
-**Rule 2**: When injecting environment variables into shell commands, generate
-the prefix for the actual shell that will parse the command. Do not choose
-syntax from OS alone. AI tool "Bash" surfaces on Windows may execute through
-PowerShell, Git Bash, MSYS2, or another POSIX-like shell.
-
-```javascript
-// BAD - breaks when the host shell is PowerShell
-command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`;
-
-// GOOD - shell-dialect-aware command prefix
-const prefix = process.platform === "win32" && !isWindowsPosixShell(process.env)
-  ? `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
-  : `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `;
-command = `${prefix}${command}`;
-```
-
-On Windows, treat `MSYSTEM`, `MINGW_PREFIX`, `OSTYPE=msys|mingw|cygwin`,
-`SHELL=...bash`, or a platform-specific Git Bash setting as POSIX-shell
-signals. Keep PowerShell as the Windows default when there is no POSIX-shell
-signal.
-
-Also make duplicate-injection detection shell-aware. A guard that only matches
-`export VAR=` will miss PowerShell's `$env:VAR = ...` form and can wrap an
-already-correct command a second time.
-
-### 5. Command Availability
-
-| Command | macOS/Linux | Windows |
-|---------|-------------|---------|
-| `grep` | ✅ Built-in | ❌ Not available |
-| `find` | ✅ Built-in | ⚠️ Different syntax |
-| `cat` | ✅ Built-in | ❌ Use `type` |
-| `tail -f` | ✅ Built-in | ❌ Not available |
-
-**Rule**: Use Python standard library instead of shell commands when possible.
-
-```python
-# BAD - tail -f is not available on Windows
-subprocess.run(["tail", "-f", log_file])
-
-# GOOD - Cross-platform implementation
-def tail_follow(file_path: Path) -> None:
-    """Follow a file like 'tail -f', cross-platform compatible."""
-    with open(file_path, "r", encoding="utf-8", errors="replace") as f:
-        f.seek(0, 2)  # Go to end
-        while True:
-            line = f.readline()
-            if line:
-                print(line, end="", flush=True)
-            else:
-                time.sleep(0.1)
-```
-
-### Optional Advisory Checks in Agent Sandboxes
-
-AI CLI subprocesses may run with outbound network disabled even when the user's
-normal terminal has network access. Prefer local CLI probes over optional
-network probes when the local CLI already exposes the needed information.
-
-**Rule 1**: Do not let a failed optional advisory check consume a once-per-session
-marker. Write the marker only after the script resolves a usable value and can
-make the intended decision. Otherwise a transient sandbox/network failure hides
-the hint for the rest of the session.
-
-**Rule 2**: If a local command can provide the needed value, try it with a short
-timeout and captured output. For example, `trellis --version` already runs the
-CLI's version comparison logic and can support an actionable update prompt
-without duplicating npm registry parsing.
-
-**Rule 3**: Keep advisory checks silent on failure. The user-facing context output
-must not fail or become noisy because an advisory check could not complete.
-
-### 6. File Encoding
-
-| Default Encoding | macOS/Linux | Windows |
-|------------------|-------------|---------|
-| Terminal | UTF-8 | Often CP1252 or GBK |
-| File I/O | UTF-8 | System locale |
-| Git output | UTF-8 | May vary |
-
-**Rule**: Always explicitly specify `encoding="utf-8"` and use `errors="replace"`.
-
-> **Checklist**: When writing scripts that print non-ASCII, did you configure stdout encoding?
-> See `backend/script-conventions.md` for the specific pattern.
-
-```python
-# BAD - Relies on system default
-with open(file, "r") as f:
-    content = f.read()
-
-result = subprocess.run(cmd, capture_output=True, text=True)
-
-# GOOD - Explicit encoding with error handling
-with open(file, "r", encoding="utf-8", errors="replace") as f:
-    content = f.read()
-
-result = subprocess.run(
-    cmd,
-    capture_output=True,
-    text=True,
-    encoding="utf-8",
-    errors="replace"
-)
-```
-
-**Git commands**: Force UTF-8 output encoding:
-
-```python
-# Force git to output UTF-8
-git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
-result = subprocess.run(
-    git_args,
-    capture_output=True,
-    text=True,
-    encoding="utf-8",
-    errors="replace"
-)
-```
-
----
-
-## Change Propagation Checklist
-
-When making platform-related changes, check **all these locations**:
-
-### Commands / Skills Sync
-- [ ] New command/skill added to the Cursor templates (`src/templates/cursor/` and `src/templates/common/`)
-- [ ] Cursor test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
-- [ ] Command format matches Cursor convention (see `platform-integration.md` → Command Format)
-- [ ] If the command exists in the dogfooded copy (`.cursor/`), sync it too
-
-### Documentation & Help Text
-- [ ] Docstrings at top of Python files
-- [ ] `--help` output / argparse descriptions
-- [ ] Usage examples in README
-- [ ] Error messages that suggest commands
-- [ ] Markdown documentation (`.md` files)
-
-### Code Locations
-- [ ] `src/templates/` - Template files for new projects
-- [ ] `.trellis/scripts/` - Project's own scripts (if self-hosting)
-- [ ] `dist/` - Built output (rebuild after changes)
-
-### Search Pattern
-```bash
-# Find all places that might need updating
-grep -r "python [a-z]" --include="*.py" --include="*.md"
-grep -r "{{PYTHON_CMD}}\\|python3\\|python " --include="*.py" --include="*.md"
-```
-
----
-
-## Pre-Commit Checklist
-
-Before committing cross-platform code:
-
-- [ ] User-facing Python invocations are platform-aware (`python` on Windows, `python3` elsewhere) or use `{{PYTHON_CMD}}`
-- [ ] Python subprocesses from Python use `sys.executable`
-- [ ] All paths use `pathlib.Path`
-- [ ] No hardcoded path separators (`/` or `\`)
-- [ ] Path strings used as logical/persisted keys (Map keys, JSON fields, hash dictionary keys) are normalized via `toPosix()`; `fs.*` calls keep OS-native paths
-- [ ] Content hashes computed across OSes normalize line endings (`\r\n` → `\n`) before hashing
-- [ ] Cross-OS JSON with potential legacy pollution carries a `__version` sentinel and the loader discards unknown/legacy versions
-- [ ] No platform-specific commands without fallbacks (e.g., `tail -f`)
-- [ ] Optional advisory checks do not burn once-per-session markers on failure
-- [ ] All file I/O specifies `encoding="utf-8"` and `errors="replace"`
-- [ ] All subprocess calls specify `encoding="utf-8"` and `errors="replace"`
-- [ ] Git commands use `-c i18n.logOutputEncoding=UTF-8`
-- [ ] External tool API formats verified from documentation
-- [ ] Documentation matches code behavior
-- [ ] Ran search to find all affected locations
-
-### 7. External Tool API Contracts
-
-When integrating with external tools (Cursor, etc.), their API contracts are **implicit assumptions**.
-
-**Rule**: Verify API formats from official documentation, don't guess.
-
-```python
-# BAD - Guessed format
-output = {"continue": True, "message": "..."}
-
-# GOOD - Verified format from documentation
-output = {
-    "hookSpecificOutput": {
-        "hookEventName": "SessionStart",
-        "additionalContext": "..."
-    }
-}
-```
-
-> **Warning**: Different hook types may have different output formats.
-> Always check the specific documentation for each hook event.
-
----
-
-## Cross-Platform Persisted JSON: Schema Migration Sentinel
-
-When a JSON file may be read/written across OSes (committed to git, synced via cloud, copied between machines) **and an older format may already exist on user disks with cross-platform pollution** (Windows-style keys, CRLF-derived hashes, locale-encoded strings), add a `__version` sentinel and let the loader discard old formats so the writer regenerates clean data.
-
-**Why not migrate-in-place?** Path-key migration (`\\` → `/`) plus hash-input migration (CRLF → LF re-hash) plus encoding fixes are correlated — trying to translate the old payload risks producing wrong values. Discarding and regenerating is **safe**: the data is recomputable from disk, and `loadX` returning `{}` triggers the existing init/update path to rebuild canonical entries.
-
-```typescript
-const SCHEMA_VERSION = 2;
-type StoredV2 = { __version: number; hashes: Record<string, string> };
-
-export function loadHashes(cwd: string): Record<string, string> {
-  const file = getHashesPath(cwd);
-  if (!fs.existsSync(file)) return {};
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as unknown;
-
-    // Reject legacy flat format (no __version) and unknown versions.
-    // The next saveHashes / initializeHashes will write a fresh v2 file.
-    if (
-      !parsed ||
-      typeof parsed !== "object" ||
-      (parsed as StoredV2).__version !== SCHEMA_VERSION ||
-      typeof (parsed as StoredV2).hashes !== "object"
-    ) {
-      return {};
-    }
-    return (parsed as StoredV2).hashes;
-  } catch {
-    return {};
-  }
-}
-
-export function saveHashes(cwd: string, hashes: Record<string, string>): void {
-  const payload: StoredV2 = { __version: SCHEMA_VERSION, hashes };
-  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(payload, null, 2));
-}
-```
-
-**When to apply**:
-- Hash dictionaries / content fingerprints (e.g., `.template-hashes.json`)
-- Cache files where stale entries are recomputable from authoritative source
-- Any cross-OS persisted file where format change correlates with cross-platform fixes
-
-**When NOT to apply** — if losing the data hurts the user (task state, drafts, settings the user typed). Use real migration there. Sentinel + discard is only safe when data is recomputable.
-
-**Reference**: `packages/cli/src/utils/template-hash.ts` v2 envelope.
-
----
-
-## JSON/External Data Defensive Checks
-
-When parsing JSON or external data, TypeScript types are **compile-time only**. Runtime data may not match.
-
-**Rule**: Always add defensive checks for required fields before using them.
-
-```typescript
-// BAD - Trusts TypeScript type definition
-interface MigrationItem {
-  from: string;  // TypeScript says required
-  to?: string;
-}
-
-function process(item: MigrationItem) {
-  const path = item.from;  // Runtime: could be undefined!
-}
-
-// GOOD - Defensive check before use
-function process(item: MigrationItem) {
-  if (!item.from) return;  // Skip invalid data
-  const path = item.from;  // Now guaranteed
-}
-```
-
-**When to apply**:
-- Parsing JSON files (manifests, configs)
-- API responses
-- User input
-- Any data from external sources
-
-**Pattern**: Check existence → then use
-
-```typescript
-// Filter pattern - skip invalid items
-const validItems = items.filter(item => item.from && item.to);
-
-// Early return pattern - bail on invalid
-if (!data.requiredField) {
-  console.warn("Missing required field");
-  return defaultValue;
-}
-```
-
----
-
-## Common Mistakes
-
-### 1. "It works on my Mac"
-
-```python
-# Developer's Mac
-subprocess.run(["./script.py"])  # Works!
-
-# User's Windows
-subprocess.run(["./script.py"])  # FileNotFoundError
-```
-
-### 2. "The shebang should handle it"
-
-```python
-#!/usr/bin/env python3
-# This line is IGNORED on Windows
-```
-
-### 3. "I updated the template"
-
-```
-src/templates/script.py  ← Updated
-.trellis/scripts/script.py  ← Forgot to sync!
-```
-
-### 4. "Python 3 is always python3"
-
-```bash
-# Developer's Mac/Linux
-python3 script.py  # Works!
-
-# User's Windows (Python from python.org)
-python3 script.py  # 'python3' is not recognized
-python script.py   # Works!
-
-# Trellis docs/config should say the rule, not guess one alias everywhere
-{{PYTHON_CMD}} script.py
-```
-
-### 5. "UTF-8 is the default everywhere"
-
-```python
-# Developer's Mac (UTF-8 default)
-subprocess.run(cmd, capture_output=True, text=True)  # Works!
-
-# User's Windows (GBK/CP1252 default)
-subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
-```
-
-> **Note**: stdout encoding is also affected. See `backend/script-conventions.md` for the fix.
-
----
-
-## Recovery: When You Find a Platform Bug
-
-1. **Fix the immediate issue**
-2. **Search for similar patterns** (grep the codebase)
-3. **Update this guide** with the new pattern
-4. **Add to pre-commit checklist** if recurring
-
----
-
-**Core Principle**: If it's not explicit, it's an assumption. And assumptions break.
-
----
-
-## Release Checklist: Versioned Files
-
-When releasing a new version, ensure **all versioned files** are created/updated:
-
-- [ ] `src/migrations/manifests/{version}.json` - Migration manifest exists
-- [ ] Manifest has correct version, description, changelog
-- [ ] `pnpm build` copies manifests to `dist/`
-- [ ] Test upgrade path from older versions (not just adjacent)
-
-**Why this matters**: Missing manifests cause "path undefined" errors when users upgrade from older versions.
-
-```bash
-# Verify all expected manifests exist
-ls src/migrations/manifests/
-
-# Test upgrade path
-node -e "
-const { getMigrationsForVersion } = require('./dist/migrations/index.js');
-console.log('From 0.2.12:', getMigrationsForVersion('0.2.12', 'CURRENT').length);
-"
-```
-
-## Release Checklist: Bundled Assets
-
-When release notes or docs claim an asset is bundled, installed automatically, or
-included with Trellis, verify the whole distribution path:
-
-- [ ] Source file exists in the branch being tagged, not only in another branch,
-  docs submodule, or marketplace tree.
-- [ ] `pnpm build` copies the asset into `dist/templates/**`.
-- [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
-- [ ] The built binary installs the asset in a fresh temp repository.
-- [ ] `.trellis/.template-hashes.json` tracks the generated asset path.
-- [ ] `trellis update --dry-run` reports `Already up to date!` in that temp
-  repository.
-
-**Why this matters**: docs/changelog text can move independently from the code
-branch that owns distributable templates. A feature can be documented as bundled
-while the published npm tarball still lacks the files.
-
-```bash
-pnpm --filter @blxzer/cursor-trellis build
-
-cd packages/cli
-npm pack --dry-run --json | grep 'dist/templates/common/bundled-skills/<skill>/SKILL.md'
-cd ../..
-
-tmpdir=$(mktemp -d /tmp/trellis-built-bin-smoke-XXXXXX)
-printf '{"name":"trellis-smoke","version":"0.0.0"}\n' > "$tmpdir/package.json"
-git -C "$tmpdir" init -q
-(
-  cd "$tmpdir"
-  node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --cursor
-  test -f .cursor/skills/<skill>/SKILL.md
-  grep -q '<skill>' .trellis/.template-hashes.json
-  node /path/to/Trellis/packages/cli/bin/trellis.js update --dry-run
-)
-```
+# Cross-Platform Thinking Guide (OS / path)
+
+> **Purpose**: Catch OS and path assumptions before they become bugs.
+>
+> **Note (cursor-only fork):** This guide covers **operating-system and filesystem** portability (Windows vs macOS/Linux). AI platform adapter sync is Cursor-only; see `cross-layer-thinking-guide.md` for template consistency.
+
+---
+
+## Why This Matters
+
+**Most cross-platform bugs come from implicit assumptions**:
+
+- Assumed shebang works → breaks on Windows
+- Assumed `/` path separator → breaks on Windows
+- Assumed `\n` line endings → inconsistent behavior
+- Assumed command availability → `grep` vs `findstr`
+
+---
+
+## Platform Differences Checklist
+
+### 1. Script Execution
+
+| Assumption | macOS/Linux | Windows |
+|------------|-------------|---------|
+| Shebang (`#!/usr/bin/env python3`) | ✅ Works | ❌ Ignored |
+| Direct execution (`./script.py`) | ✅ Works | ❌ Fails |
+| `python3` command | ✅ Always available | ⚠️ May need `python` |
+| `python` command | ⚠️ May be Python 2 | ✅ Usually Python 3 |
+
+**Rule 1**: For user-facing docs, help text, and error messages, either:
+
+- state the platform rule explicitly (`python` on Windows, `python3` elsewhere), or
+- render the command through the same platform-aware helper / placeholder the code uses.
+
+```python
+# BAD - Assumes shebang works
+print("Usage: ./script.py <args>")
+print("Run: script.py <args>")
+
+# GOOD - Platform-aware wording
+print("Usage: python on Windows, python3 elsewhere")
+print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
+```
+
+**Rule 2**: When generating config files at init time, use placeholder + platform detection:
+
+```typescript
+// In template file (settings.json):
+{ "command": "{{PYTHON_CMD}} .cursor/hooks/script.py" }
+
+// In configurator:
+function getPythonCommand(): string {
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function replacePlaceholders(content: string): string {
+  return content.replace(/\{\{PYTHON_CMD\}\}/g, getPythonCommand());
+}
+```
+
+**Rule 3**: When calling Python at runtime from JavaScript, detect platform dynamically:
+
+```javascript
+import { platform } from "os"
+
+const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
+execSync(`${PYTHON_CMD} "${scriptPath}"`, { ... })
+```
+
+**Rule 4**: If you need to verify Python is actually installed (not just choose
+the command), probe the same platform-selected alias you will later render or
+execute:
+
+```typescript
+function getPythonCommand(platform = process.platform): string {
+  return platform === "win32" ? "python" : "python3";
+}
+
+function warnIfPythonTooOld(): void {
+  const cmd = getPythonCommand();
+  try {
+    execSync(`${cmd} --version`, { stdio: "pipe" });
+  } catch {
+    // Missing Python is a separate error path; don't silently swap aliases.
+  }
+}
+```
+
+**Rule 5**: Don't assume the Python version the AI CLI uses matches your shell's `python3`. The user's terminal may resolve `python3` → homebrew 3.11, but Cursor spawns hook subprocesses with a minimal PATH that resolves `python3` → `/usr/bin/python3` → macOS system 3.9. Distributed templates must either target the lowest plausible version or use `from __future__ import annotations` for PEP 604 syntax. See `cli/backend/script-conventions.md` → **CRITICAL: PEP 604 Annotations Require `from __future__ import annotations`** for the hard rule and audit check.
+
+**Rule 6**: When calling Python from Python, use `sys.executable`:
+
+```python
+import sys
+import subprocess
+
+# BAD - Hardcoded command
+subprocess.run(["python3", "other_script.py"])
+
+# GOOD - Use current interpreter
+subprocess.run([sys.executable, "other_script.py"])
+```
+
+### 2. Path Handling
+
+| Assumption | macOS/Linux | Windows |
+|------------|-------------|---------|
+| `/` separator | ✅ Works | ⚠️ Sometimes works |
+| `\` separator | ❌ Escape char | ✅ Native |
+| `pathlib.Path` | ✅ Works | ✅ Works |
+
+**Rule (Python)**: Use `pathlib.Path` for all path operations.
+
+```python
+# BAD - String concatenation
+path = base + "/" + filename
+
+# GOOD - pathlib
+from pathlib import Path
+path = Path(base) / filename
+```
+
+#### Logical key vs filesystem path (TypeScript)
+
+A path string has two distinct roles. **Treat them differently.**
+
+| Role | OS-native (`\` on Windows) | Always POSIX (`/`) |
+|------|---------------------------|--------------------|
+| `fs.readFileSync(p)` / `path.join(cwd, x)` for fs call | ✅ Required | ❌ May fail on Windows |
+| `Map<relPath, content>` key, JSON field, hash dictionary key, anything persisted across OS | ❌ Cross-OS mismatch | ✅ Required |
+
+**Rule**: Anywhere a path string crosses OS or persists (Map keys consumed by another OS, JSON fields, hash dictionary keys), normalize to POSIX. Anywhere it goes straight to `fs.*`, leave OS-native.
+
+**Single source of truth**: `packages/cli/src/utils/posix.ts` exports `toPosix(p)`. Don't sprinkle `replaceAll('\\', '/')` at every `path.join` site — apply `toPosix` **once at the boundary**: collector exit (Map key entering hash dictionary) or write-time (`saveHashes` before `JSON.stringify`).
+
+```typescript
+// BAD - logical key carries OS-native separator
+function collectTemplates(): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const entry of walk(dir)) {
+    files.set(path.join(".cursor", entry), readFile(entry));  // \ on Windows
+  }
+  return files;
+}
+
+// GOOD - normalize at the boundary
+import { toPosix } from "../utils/posix.js";
+
+function collectTemplates(): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const entry of walk(dir)) {
+    files.set(toPosix(path.join(".cursor", entry)), readFile(entry));
+  }
+  return files;
+}
+
+// ALSO ACCEPTABLE - write-side defense (for storage helpers like saveHashes)
+function saveHashes(cwd: string, hashes: Record<string, string>): void {
+  const normalized = Object.fromEntries(
+    Object.entries(hashes).map(([k, v]) => [toPosix(k), v])
+  );
+  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(normalized, null, 2));
+}
+```
+
+**Common offender**: `path.relative(cwd, fullPath)` produces `\` on Windows. If you then use that string as a hash dictionary lookup key (`hashes[relPath]`), `toPosix` it first, or the lookup misses on Windows.
+
+### 3. Line Endings
+
+| Format | macOS/Linux | Windows | Git |
+|--------|-------------|---------|-----|
+| `\n` (LF) | ✅ Native | ⚠️ Some tools | ✅ Normalized |
+| `\r\n` (CRLF) | ⚠️ Extra char | ✅ Native | Converted |
+
+**Rule 1**: Use `.gitattributes` to enforce consistent line endings.
+
+```gitattributes
+* text=auto eol=lf
+*.sh text eol=lf
+*.py text eol=lf
+```
+
+**Rule 2**: When hashing or comparing **content** across platforms, normalize line endings before computing the hash. `.gitattributes` only governs git checkout — files written by users, scripts, or `core.autocrlf=true` may still arrive as CRLF, and `sha256(LF)` ≠ `sha256(CRLF)` for otherwise-identical content.
+
+```typescript
+// BAD - Windows users with autocrlf=true get a different hash
+export function computeHash(content: string): string {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+
+// GOOD - normalize before hashing so logical content hashes identically
+export function computeHash(content: string): string {
+  const normalized = content.replace(/\r\n/g, "\n");
+  return createHash("sha256").update(normalized, "utf-8").digest("hex");
+}
+```
+
+Apply this rule wherever the hash crosses OS boundaries (template hash dictionary, content fingerprints stored in JSON, integrity checks against a remote registry).
+
+### 4. Environment Variables
+
+| Variable | macOS/Linux | Windows |
+|----------|-------------|---------|
+| `HOME` | ✅ Set | ❌ Use `USERPROFILE` |
+| `PATH` separator | `:` | `;` |
+| Case sensitivity | ✅ Case-sensitive | ❌ Case-insensitive |
+
+**Rule 1**: Use `pathlib.Path.home()` instead of environment variables.
+
+```python
+# BAD
+home = os.environ.get("HOME")
+
+# GOOD
+home = Path.home()
+```
+
+**Rule 2**: When injecting environment variables into shell commands, generate
+the prefix for the actual shell that will parse the command. Do not choose
+syntax from OS alone. AI tool "Bash" surfaces on Windows may execute through
+PowerShell, Git Bash, MSYS2, or another POSIX-like shell.
+
+```javascript
+// BAD - breaks when the host shell is PowerShell
+command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`;
+
+// GOOD - shell-dialect-aware command prefix
+const prefix = process.platform === "win32" && !isWindowsPosixShell(process.env)
+  ? `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
+  : `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `;
+command = `${prefix}${command}`;
+```
+
+On Windows, treat `MSYSTEM`, `MINGW_PREFIX`, `OSTYPE=msys|mingw|cygwin`,
+`SHELL=...bash`, or a platform-specific Git Bash setting as POSIX-shell
+signals. Keep PowerShell as the Windows default when there is no POSIX-shell
+signal.
+
+Also make duplicate-injection detection shell-aware. A guard that only matches
+`export VAR=` will miss PowerShell's `$env:VAR = ...` form and can wrap an
+already-correct command a second time.
+
+### 5. Command Availability
+
+| Command | macOS/Linux | Windows |
+|---------|-------------|---------|
+| `grep` | ✅ Built-in | ❌ Not available |
+| `find` | ✅ Built-in | ⚠️ Different syntax |
+| `cat` | ✅ Built-in | ❌ Use `type` |
+| `tail -f` | ✅ Built-in | ❌ Not available |
+
+**Rule**: Use Python standard library instead of shell commands when possible.
+
+```python
+# BAD - tail -f is not available on Windows
+subprocess.run(["tail", "-f", log_file])
+
+# GOOD - Cross-platform implementation
+def tail_follow(file_path: Path) -> None:
+    """Follow a file like 'tail -f', cross-platform compatible."""
+    with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+        f.seek(0, 2)  # Go to end
+        while True:
+            line = f.readline()
+            if line:
+                print(line, end="", flush=True)
+            else:
+                time.sleep(0.1)
+```
+
+### Optional Advisory Checks in Agent Sandboxes
+
+AI CLI subprocesses may run with outbound network disabled even when the user's
+normal terminal has network access. Prefer local CLI probes over optional
+network probes when the local CLI already exposes the needed information.
+
+**Rule 1**: Do not let a failed optional advisory check consume a once-per-session
+marker. Write the marker only after the script resolves a usable value and can
+make the intended decision. Otherwise a transient sandbox/network failure hides
+the hint for the rest of the session.
+
+**Rule 2**: If a local command can provide the needed value, try it with a short
+timeout and captured output. For example, `cstl --version` already runs the
+CLI's version comparison logic and can support an actionable update prompt
+without duplicating npm registry parsing.
+
+**Rule 3**: Keep advisory checks silent on failure. The user-facing context output
+must not fail or become noisy because an advisory check could not complete.
+
+### 6. File Encoding
+
+| Default Encoding | macOS/Linux | Windows |
+|------------------|-------------|---------|
+| Terminal | UTF-8 | Often CP1252 or GBK |
+| File I/O | UTF-8 | System locale |
+| Git output | UTF-8 | May vary |
+
+**Rule**: Always explicitly specify `encoding="utf-8"` and use `errors="replace"`.
+
+> **Checklist**: When writing scripts that print non-ASCII, did you configure stdout encoding?
+> See `backend/script-conventions.md` for the specific pattern.
+
+```python
+# BAD - Relies on system default
+with open(file, "r") as f:
+    content = f.read()
+
+result = subprocess.run(cmd, capture_output=True, text=True)
+
+# GOOD - Explicit encoding with error handling
+with open(file, "r", encoding="utf-8", errors="replace") as f:
+    content = f.read()
+
+result = subprocess.run(
+    cmd,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",
+    errors="replace"
+)
+```
+
+**Git commands**: Force UTF-8 output encoding:
+
+```python
+# Force git to output UTF-8
+git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
+result = subprocess.run(
+    git_args,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",
+    errors="replace"
+)
+```
+
+---
+
+## Change Propagation Checklist
+
+When making platform-related changes, check **all these locations**:
+
+### Commands / Skills Sync
+- [ ] New command/skill added to the Cursor templates (`src/templates/cursor/` and `src/templates/common/`)
+- [ ] Cursor test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
+- [ ] Command format matches Cursor convention (see `platform-integration.md` → Command Format)
+- [ ] If the command exists in the dogfooded copy (`.cursor/`), sync it too
+
+### Documentation & Help Text
+- [ ] Docstrings at top of Python files
+- [ ] `--help` output / argparse descriptions
+- [ ] Usage examples in README
+- [ ] Error messages that suggest commands
+- [ ] Markdown documentation (`.md` files)
+
+### Code Locations
+- [ ] `src/templates/` - Template files for new projects
+- [ ] `.trellis/scripts/` - Project's own scripts (if self-hosting)
+- [ ] `dist/` - Built output (rebuild after changes)
+
+### Search Pattern
+```bash
+# Find all places that might need updating
+grep -r "python [a-z]" --include="*.py" --include="*.md"
+grep -r "{{PYTHON_CMD}}\\|python3\\|python " --include="*.py" --include="*.md"
+```
+
+---
+
+## Pre-Commit Checklist
+
+Before committing cross-platform code:
+
+- [ ] User-facing Python invocations are platform-aware (`python` on Windows, `python3` elsewhere) or use `{{PYTHON_CMD}}`
+- [ ] Python subprocesses from Python use `sys.executable`
+- [ ] All paths use `pathlib.Path`
+- [ ] No hardcoded path separators (`/` or `\`)
+- [ ] Path strings used as logical/persisted keys (Map keys, JSON fields, hash dictionary keys) are normalized via `toPosix()`; `fs.*` calls keep OS-native paths
+- [ ] Content hashes computed across OSes normalize line endings (`\r\n` → `\n`) before hashing
+- [ ] Cross-OS JSON with potential legacy pollution carries a `__version` sentinel and the loader discards unknown/legacy versions
+- [ ] No platform-specific commands without fallbacks (e.g., `tail -f`)
+- [ ] Optional advisory checks do not burn once-per-session markers on failure
+- [ ] All file I/O specifies `encoding="utf-8"` and `errors="replace"`
+- [ ] All subprocess calls specify `encoding="utf-8"` and `errors="replace"`
+- [ ] Git commands use `-c i18n.logOutputEncoding=UTF-8`
+- [ ] External tool API formats verified from documentation
+- [ ] Documentation matches code behavior
+- [ ] Ran search to find all affected locations
+
+### 7. External Tool API Contracts
+
+When integrating with external tools (Cursor, etc.), their API contracts are **implicit assumptions**.
+
+**Rule**: Verify API formats from official documentation, don't guess.
+
+```python
+# BAD - Guessed format
+output = {"continue": True, "message": "..."}
+
+# GOOD - Verified format from documentation
+output = {
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": "..."
+    }
+}
+```
+
+> **Warning**: Different hook types may have different output formats.
+> Always check the specific documentation for each hook event.
+
+---
+
+## Cross-Platform Persisted JSON: Schema Migration Sentinel
+
+When a JSON file may be read/written across OSes (committed to git, synced via cloud, copied between machines) **and an older format may already exist on user disks with cross-platform pollution** (Windows-style keys, CRLF-derived hashes, locale-encoded strings), add a `__version` sentinel and let the loader discard old formats so the writer regenerates clean data.
+
+**Why not migrate-in-place?** Path-key migration (`\\` → `/`) plus hash-input migration (CRLF → LF re-hash) plus encoding fixes are correlated — trying to translate the old payload risks producing wrong values. Discarding and regenerating is **safe**: the data is recomputable from disk, and `loadX` returning `{}` triggers the existing init/update path to rebuild canonical entries.
+
+```typescript
+const SCHEMA_VERSION = 2;
+type StoredV2 = { __version: number; hashes: Record<string, string> };
+
+export function loadHashes(cwd: string): Record<string, string> {
+  const file = getHashesPath(cwd);
+  if (!fs.existsSync(file)) return {};
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as unknown;
+
+    // Reject legacy flat format (no __version) and unknown versions.
+    // The next saveHashes / initializeHashes will write a fresh v2 file.
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      (parsed as StoredV2).__version !== SCHEMA_VERSION ||
+      typeof (parsed as StoredV2).hashes !== "object"
+    ) {
+      return {};
+    }
+    return (parsed as StoredV2).hashes;
+  } catch {
+    return {};
+  }
+}
+
+export function saveHashes(cwd: string, hashes: Record<string, string>): void {
+  const payload: StoredV2 = { __version: SCHEMA_VERSION, hashes };
+  fs.writeFileSync(getHashesPath(cwd), JSON.stringify(payload, null, 2));
+}
+```
+
+**When to apply**:
+- Hash dictionaries / content fingerprints (e.g., `.template-hashes.json`)
+- Cache files where stale entries are recomputable from authoritative source
+- Any cross-OS persisted file where format change correlates with cross-platform fixes
+
+**When NOT to apply** — if losing the data hurts the user (task state, drafts, settings the user typed). Use real migration there. Sentinel + discard is only safe when data is recomputable.
+
+**Reference**: `packages/cli/src/utils/template-hash.ts` v2 envelope.
+
+---
+
+## JSON/External Data Defensive Checks
+
+When parsing JSON or external data, TypeScript types are **compile-time only**. Runtime data may not match.
+
+**Rule**: Always add defensive checks for required fields before using them.
+
+```typescript
+// BAD - Trusts TypeScript type definition
+interface MigrationItem {
+  from: string;  // TypeScript says required
+  to?: string;
+}
+
+function process(item: MigrationItem) {
+  const path = item.from;  // Runtime: could be undefined!
+}
+
+// GOOD - Defensive check before use
+function process(item: MigrationItem) {
+  if (!item.from) return;  // Skip invalid data
+  const path = item.from;  // Now guaranteed
+}
+```
+
+**When to apply**:
+- Parsing JSON files (manifests, configs)
+- API responses
+- User input
+- Any data from external sources
+
+**Pattern**: Check existence → then use
+
+```typescript
+// Filter pattern - skip invalid items
+const validItems = items.filter(item => item.from && item.to);
+
+// Early return pattern - bail on invalid
+if (!data.requiredField) {
+  console.warn("Missing required field");
+  return defaultValue;
+}
+```
+
+---
+
+## Common Mistakes
+
+### 1. "It works on my Mac"
+
+```python
+# Developer's Mac
+subprocess.run(["./script.py"])  # Works!
+
+# User's Windows
+subprocess.run(["./script.py"])  # FileNotFoundError
+```
+
+### 2. "The shebang should handle it"
+
+```python
+#!/usr/bin/env python3
+# This line is IGNORED on Windows
+```
+
+### 3. "I updated the template"
+
+```
+src/templates/script.py  ← Updated
+.trellis/scripts/script.py  ← Forgot to sync!
+```
+
+### 4. "Python 3 is always python3"
+
+```bash
+# Developer's Mac/Linux
+python3 script.py  # Works!
+
+# User's Windows (Python from python.org)
+python3 script.py  # 'python3' is not recognized
+python script.py   # Works!
+
+# Trellis docs/config should say the rule, not guess one alias everywhere
+{{PYTHON_CMD}} script.py
+```
+
+### 5. "UTF-8 is the default everywhere"
+
+```python
+# Developer's Mac (UTF-8 default)
+subprocess.run(cmd, capture_output=True, text=True)  # Works!
+
+# User's Windows (GBK/CP1252 default)
+subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
+```
+
+> **Note**: stdout encoding is also affected. See `backend/script-conventions.md` for the fix.
+
+---
+
+## Recovery: When You Find a Platform Bug
+
+1. **Fix the immediate issue**
+2. **Search for similar patterns** (grep the codebase)
+3. **Update this guide** with the new pattern
+4. **Add to pre-commit checklist** if recurring
+
+---
+
+**Core Principle**: If it's not explicit, it's an assumption. And assumptions break.
+
+---
+
+## Release Checklist: Versioned Files
+
+When releasing a new version, ensure **all versioned files** are created/updated:
+
+- [ ] `src/migrations/manifests/{version}.json` - Migration manifest exists
+- [ ] Manifest has correct version, description, changelog
+- [ ] `pnpm build` copies manifests to `dist/`
+- [ ] Test upgrade path from older versions (not just adjacent)
+
+**Why this matters**: Missing manifests cause "path undefined" errors when users upgrade from older versions.
+
+```bash
+# Verify all expected manifests exist
+ls src/migrations/manifests/
+
+# Test upgrade path
+node -e "
+const { getMigrationsForVersion } = require('./dist/migrations/index.js');
+console.log('From 0.2.12:', getMigrationsForVersion('0.2.12', 'CURRENT').length);
+"
+```
+
+## Release Checklist: Bundled Assets
+
+When release notes or docs claim an asset is bundled, installed automatically, or
+included with Trellis, verify the whole distribution path:
+
+- [ ] Source file exists in the branch being tagged, not only in another branch,
+  docs submodule, or marketplace tree.
+- [ ] `pnpm build` copies the asset into `dist/templates/**`.
+- [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
+- [ ] The built binary installs the asset in a fresh temp repository.
+- [ ] `.trellis/.template-hashes.json` tracks the generated asset path.
+- [ ] `cstl update --dry-run` reports `Already up to date!` in that temp
+  repository.
+
+**Why this matters**: docs/changelog text can move independently from the code
+branch that owns distributable templates. A feature can be documented as bundled
+while the published npm tarball still lacks the files.
+
+```bash
+pnpm --filter @blxzer/cursor-trellis build
+
+cd packages/cli
+npm pack --dry-run --json | grep 'dist/templates/common/bundled-skills/<skill>/SKILL.md'
+cd ../..
+
+tmpdir=$(mktemp -d /tmp/trellis-built-bin-smoke-XXXXXX)
+printf '{"name":"trellis-smoke","version":"0.0.0"}\n' > "$tmpdir/package.json"
+git -C "$tmpdir" init -q
+(
+  cd "$tmpdir"
+  node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --cursor
+  test -f .cursor/skills/<skill>/SKILL.md
+  grep -q '<skill>' .trellis/.template-hashes.json
+  node /path/to/Trellis/packages/cli/bin/trellis.js update --dry-run
+)
+```