@mindfoldhq/trellis 0.5.10 → 0.5.11

package/dist/migrations/manifests/0.5.11.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.5.11",
+  "description": "Patch: drop 0.5.10 `git add -f` retry + new `session_auto_commit` config + session-start update hint.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(scripts): drop `git add -f` auto-retry from 0.5.10. When `.gitignore` excludes `.trellis/`, `add_session.py` and `task.py archive` print a warning and skip auto-commit instead of force-staging.\n\n**Enhancements:**\n- feat(scripts): new `session_auto_commit: true | false` in `.trellis/config.yaml` (default `true`). Set `false` to skip auto stage + commit — journal / archive files still write to disk. Closes #245.\n- feat(scripts): `get_context.py` shows `Trellis update available: <current> -> <latest>` once per session when local install lags. 1-second timeout, failures silent. Closes #254.",
+  "migrations": [],
+  "configSectionsAdded": [
+    {
+      "file": ".trellis/config.yaml",
+      "sentinel": "session_auto_commit:",
+      "sectionHeading": "Session Auto-Commit"
+    }
+  ],
+  "notes": "Patch on top of 0.5.10. Run `trellis update` — your `.trellis/config.yaml` gets a commented-out `session_auto_commit: true` block appended automatically. Uncomment and flip to `false` if your `.gitignore` excludes `.trellis/` and you want auto-commit off entirely."
+}

package/dist/migrations/manifests/0.6.0-beta.5.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.5",
+  "description": "Beta patch: cherry-picks v0.5.10 stable fixes (git-add-f prevention + Pi #246/#249) + version-update hint at session start (PR #254).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(scripts): `add_session.py` and `task.py archive` no longer print a generic `git add .trellis && git commit` fallback when the repo's `.gitignore` excludes `.trellis/`. They now stage only specific Trellis-owned paths and auto-retry with `git add -f -- <specific-paths>` only on `ignored by` stderr. The warning text explicitly states `Do NOT use \\`git add -f .trellis/\\``, naming `.trellis/.backup-*`, `.trellis/worktrees/`, `.trellis/.template-hashes.json`, `.trellis/.runtime/`, `.trellis/.cache/` as the subpaths users should ignore individually instead. Helper centralized in `templates/trellis/scripts/common/safe_commit.py`.\n- fix(pi): Pi extension now injects `<workflow-state>` breadcrumb on every `input` and `before_agent_start` event, plus a `<session-overview>` block sourced from `.trellis/scripts/get_context.py`. The `subagent` tool registration carries a `promptSnippet` with the `Active task: <path>` dispatch protocol. Closes #249.\n- fix(pi): Project-level `packages[\"npm:pi-subagents\"]` override added to `.pi/settings.json` so a globally-installed `npm:pi-subagents` cannot inject `extensions / skills / prompts / themes` into the current Trellis project. `scrubPiSettings` reverses the override on `trellis uninstall`. Closes #246.\n\n**Enhancements:**\n- feat(scripts): `get_context.py` default mode now performs a once-per-session `trellis --version` check and prepends `Trellis update available: <current> -> <latest>, run npm install -g @mindfoldhq/trellis@latest` before the context body when the local install lags. Best-effort with a 1-second timeout; failures silently skip. Marker stored under `.trellis/.runtime/` (auto-ignored). Closes #254.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.4. Run `trellis update`. Brings the four 0.5.10-line fixes / features into the 0.6 beta line."
+}

package/dist/templates/common/commands/start.md

@@ -11,6 +11,8 @@ Identity, git status, current task, active tasks, journal location.
 {{PYTHON_CMD}} ./.trellis/scripts/get_context.py
 ```
 
+If this output includes a line beginning `Trellis update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+
 ## Step 2: Workflow overview
 Phase Index + skill routing table + DO-NOT-skip rules.
 

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

@@ -85,6 +85,45 @@ After implementation:
 
 ---
 
+## Cross-Platform Template Consistency
+
+In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
+
+### Checklist: After Modifying Any Command Template
+
+- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
+- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
+- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
+- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
+
+**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
+
+---
+
+## Mode-Detection Probe Checklist
+
+When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
+
+### Before implementing:
+- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
+- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
+- [ ] Transient errors **abort or retry**, never silently switch modes
+- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
+- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
+
+### After implementing:
+- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
+- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
+- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
+- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
+- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
+
+**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
+
+**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
+
+---
+
 ## When to Create Flow Documentation
 
 Create detailed flow docs when:

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

@@ -26,37 +26,68 @@
 | `python3` command | ✅ Always available | ⚠️ May need `python` |
 | `python` command | ⚠️ May be Python 2 | ✅ Usually Python 3 |
 
-**Rule 1**: Always use explicit `python3` in documentation, help text, and error messages.
+**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 - Explicit interpreter
-print("Usage: python3 script.py <args>")
-print("Run: python3 ./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 calling Python from TypeScript/Node.js, detect the available command:
+**Rule 2**: When generating config files at init time, use placeholder + platform detection:
 
 ```typescript
+// In template file (settings.json):
+{ "command": "{{PYTHON_CMD}} .claude/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("python3 --version", { stdio: "pipe" });
-    return "python3";
+    execSync(`${cmd} --version`, { stdio: "pipe" });
   } catch {
-    try {
-      execSync("python --version", { stdio: "pipe" });
-      return "python";
-    } catch {
-      return "python3"; // Default, will fail with clear error
-    }
+    // Missing Python is a separate error path; don't silently swap aliases.
   }
 }
 ```
 
-**Rule 3**: When calling Python from Python, use `sys.executable`:
+**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 AI CLI hosts (including enterprise-forked Claude Code / Cursor distributions) spawn 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
@@ -69,30 +100,6 @@ subprocess.run(["python3", "other_script.py"])
 subprocess.run([sys.executable, "other_script.py"])
 ```
 
-**Rule 4**: Don't assume the Python version your AI CLI uses matches your shell's `python3`. Your terminal may resolve `python3` → 3.11 (via homebrew/pyenv), but AI CLI hosts often spawn hook subprocesses with a minimal PATH that resolves `python3` → the system Python (3.9 on macOS). Any `.py` file run as an AI-CLI hook must be written for the lowest plausible Python version.
-
-Concrete failure: PEP 604 union syntax (`str | None`) requires Python 3.10+. If your hook file uses it, start with `from __future__ import annotations` so annotations become lazy strings and work on Python 3.7+:
-
-```python
-#!/usr/bin/env python3
-"""My hook."""
-from __future__ import annotations     # REQUIRED for PEP 604 annotations
-
-def handler(x: str | None) -> dict | None:   # OK — lazy annotation
-    ...
-```
-
-```python
-# BAD — crashes on Python < 3.10:
-#   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
-def handler(x: str | None) -> dict | None:
-    ...
-```
-
-Note: `from __future__ import annotations` only covers **annotations**. Runtime expressions like `isinstance(x, int | str)` still require Python 3.10+. Avoid them in hook scripts.
-
-Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10+), `tomllib` (3.11+), `ExceptionGroup` / `except*` (3.11+) — all crash on older Python regardless of `__future__`.
-
 ### 2. Path Handling
 
 | Assumption | macOS/Linux | Windows |
@@ -101,7 +108,7 @@ Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10
 | `\` separator | ❌ Escape char | ✅ Native |
 | `pathlib.Path` | ✅ Works | ✅ Works |
 
-**Rule**: Use `pathlib.Path` for all path operations.
+**Rule (Python)**: Use `pathlib.Path` for all path operations.
 
 ```python
 # BAD - String concatenation
@@ -112,6 +119,51 @@ 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(".opencode", 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(".opencode", 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 |
@@ -119,7 +171,7 @@ path = Path(base) / filename
 | `\n` (LF) | ✅ Native | ⚠️ Some tools | ✅ Normalized |
 | `\r\n` (CRLF) | ⚠️ Extra char | ✅ Native | Converted |
 
-**Rule**: Use `.gitattributes` to enforce consistent line endings.
+**Rule 1**: Use `.gitattributes` to enforce consistent line endings.
 
 ```gitattributes
 * text=auto eol=lf
@@ -127,6 +179,23 @@ path = Path(base) / filename
 *.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 |
@@ -135,7 +204,7 @@ path = Path(base) / filename
 | `PATH` separator | `:` | `;` |
 | Case sensitivity | ✅ Case-sensitive | ❌ Case-insensitive |
 
-**Rule**: Use `pathlib.Path.home()` instead of environment variables.
+**Rule 1**: Use `pathlib.Path.home()` instead of environment variables.
 
 ```python
 # BAD
@@ -145,6 +214,25 @@ home = os.environ.get("HOME")
 home = Path.home()
 ```
 
+**Rule 2**: When injecting environment variables into shell commands, generate
+the prefix for the actual host shell. Do not assume `export` works everywhere.
+AI tool "Bash" surfaces on Windows may execute through PowerShell.
+
+```javascript
+// BAD - breaks when the host shell is PowerShell
+command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`;
+
+// GOOD - shell-aware command prefix
+const prefix = process.platform === "win32"
+  ? `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
+  : `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `;
+command = `${prefix}${command}`;
+```
+
+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 |
@@ -173,6 +261,25 @@ def tail_follow(file_path: Path) -> None:
                 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 |
@@ -183,6 +290,9 @@ def tail_follow(file_path: Path) -> None:
 
 **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:
@@ -223,6 +333,12 @@ result = subprocess.run(
 
 When making platform-related changes, check **all these locations**:
 
+### Commands / Skills Sync
+- [ ] New command/skill added to ALL platforms (claude, cursor, iflow, codex, and any new platform)
+- [ ] Each platform's test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
+- [ ] Platform-integration spec's required command table updated if adding a new required command
+- [ ] Command format matches platform convention (see `platform-integration.md` → Command Format by Platform)
+
 ### Documentation & Help Text
 - [ ] Docstrings at top of Python files
 - [ ] `--help` output / argparse descriptions
@@ -239,7 +355,7 @@ When making platform-related changes, check **all these locations**:
 ```bash
 # Find all places that might need updating
 grep -r "python [a-z]" --include="*.py" --include="*.md"
-grep -r "\./" --include="*.py" --include="*.md" | grep -v python3
+grep -r "{{PYTHON_CMD}}\\|python3\\|python " --include="*.py" --include="*.md"
 ```
 
 ---
@@ -248,10 +364,15 @@ grep -r "\./" --include="*.py" --include="*.md" | grep -v python3
 
 Before committing cross-platform code:
 
-- [ ] All Python invocations use `python3` explicitly (docs) or `sys.executable` (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`
@@ -283,6 +404,101 @@ output = {
 
 ---
 
+## 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"
@@ -318,6 +534,9 @@ 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"
@@ -328,6 +547,9 @@ 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.
 
 ---
 
@@ -341,3 +563,27 @@ subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
 ---
 
 **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);
+"
+```

package/dist/templates/trellis/config.yaml

@@ -14,6 +14,24 @@ session_commit_message: "chore: record journal"
 # Maximum lines per journal file before rotating to a new one
 max_journal_lines: 2000
 
+#-------------------------------------------------------------------------------
+# Session Auto-Commit
+#-------------------------------------------------------------------------------
+
+# Auto-commit behavior for session journal + task archive operations.
+# - true (default): scripts auto-stage and auto-commit journal / task changes
+#   after add_session.py / task.py archive runs.
+# - false: scripts do not touch git. Files (journal-*.md, task archive moves)
+#   are still written to disk; you decide whether to git add / commit.
+#
+# Use `false` if your project's .gitignore intentionally excludes `.trellis/`
+# and you want session data kept local-only, or if you prefer to review
+# staged changes manually before each commit.
+#
+# Accepts: true / false / yes / no / 1 / 0 / on / off (case-insensitive).
+#
+# session_auto_commit: true
+
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks
 #-------------------------------------------------------------------------------

package/dist/templates/trellis/scripts/add_session.py

@@ -44,6 +44,7 @@ from common.safe_commit import (
 from common.tasks import load_task
 from common.config import (
     get_packages,
+    get_session_auto_commit,
     get_session_commit_message,
     get_max_journal_lines,
     is_monorepo,
@@ -322,16 +323,27 @@ def _auto_commit_workspace(repo_root: Path) -> None:
 
     Path scope is restricted to specific products (journal files, index.md,
     active task dirs, the archive subtree). We never `git add` the whole
-    `.trellis/` tree, and if `.gitignore` blocks the specific paths we retry
-    with `git add -f <those-specific-paths>` — never `-f .trellis/`.
+    `.trellis/` tree, and if `.gitignore` blocks the specific paths we
+    warn + skip — never retry with ``-f``.
+
+    Honors ``session_auto_commit`` in ``.trellis/config.yaml``: when set to
+    ``false``, this function returns immediately without touching git
+    (journal/index files are still written to disk by the caller).
     """
+    if not get_session_auto_commit(repo_root):
+        print(
+            "[OK] session_auto_commit: false — skipping git stage/commit.",
+            file=sys.stderr,
+        )
+        return
+
     commit_msg = get_session_commit_message(repo_root)
     paths = safe_trellis_paths_to_add(repo_root)
     if not paths:
         print("[OK] No workspace changes to commit.", file=sys.stderr)
         return
 
-    success, used_force, err = safe_git_add(paths, repo_root)
+    success, _, err = safe_git_add(paths, repo_root)
     if not success:
         if err and "ignored by" in err.lower():
             print_gitignore_warning(paths)
@@ -342,12 +354,6 @@ def _auto_commit_workspace(repo_root: Path) -> None:
             )
         return
 
-    if used_force:
-        print(
-            "[OK] Staged Trellis-owned paths with -f (specific paths, not .trellis/).",
-            file=sys.stderr,
-        )
-
     # Check if there are staged changes for the paths we just staged.
     rc, _, _ = run_git(
         ["diff", "--cached", "--quiet", "--", *paths], cwd=repo_root

package/dist/templates/trellis/scripts/common/config.py

@@ -36,6 +36,29 @@ def _unquote(s: str) -> str:
     return s
 
 
+def _strip_inline_comment(value: str) -> str:
+    """Strip ` # …` inline comments while preserving `#` inside quoted strings.
+
+    YAML treats ` #` (space-hash) as a comment opener; bare `#` inside a token
+    is part of the value. Quoted strings are immune.
+
+    Mirrors :func:`common.trellis_config._strip_inline_comment` so both
+    parsers handle ``key: value  # comment`` identically.
+    """
+    in_quote: str | None = None
+    for idx, ch in enumerate(value):
+        if in_quote:
+            if ch == in_quote:
+                in_quote = None
+            continue
+        if ch in ('"', "'"):
+            in_quote = ch
+            continue
+        if ch == "#" and (idx == 0 or value[idx - 1].isspace()):
+            return value[:idx]
+    return value
+
+
 def parse_simple_yaml(content: str) -> dict:
     """Parse simple YAML with nested dict support (no dependencies).
 
@@ -93,7 +116,8 @@ def _parse_yaml_block(
         elif ":" in stripped:
             key, _, value = stripped.partition(":")
             key = key.strip()
-            value = _unquote(value.strip())
+            value = _strip_inline_comment(value).strip()
+            value = _unquote(value)
             current_list = None
 
             if value:
@@ -142,6 +166,7 @@ def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
 # Defaults
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
+DEFAULT_SESSION_AUTO_COMMIT = True
 
 CONFIG_FILE = "config.yaml"
 
@@ -187,6 +212,37 @@ def get_max_journal_lines(repo_root: Path | None = None) -> int:
         return DEFAULT_MAX_JOURNAL_LINES
 
 
+def get_session_auto_commit(repo_root: Path | None = None) -> bool:
+    """Whether scripts should auto-stage + auto-commit session/task changes.
+
+    Governs both ``add_session.py:_auto_commit_workspace`` and
+    ``task_store.py:_auto_commit_archive``.
+
+    Default: ``True`` (existing behavior — auto-stage + auto-commit).
+    Set ``session_auto_commit: false`` in ``.trellis/config.yaml`` to skip
+    auto-staging entirely; the journal/archive files are still written to
+    disk, but the user manages ``git add`` / ``git commit`` themselves.
+
+    Accepts native YAML booleans (``true`` / ``false``) and the string
+    aliases ``true / false / yes / no / 1 / 0 / on / off`` (case-insensitive).
+    Invalid values fall back to ``True`` with a stderr warning.
+    """
+    config = _load_config(repo_root)
+    raw = config.get("session_auto_commit", DEFAULT_SESSION_AUTO_COMMIT)
+    if isinstance(raw, bool):
+        return raw
+    s = str(raw).strip().lower()
+    if s in ("true", "yes", "1", "on"):
+        return True
+    if s in ("false", "no", "0", "off"):
+        return False
+    print(
+        f"[WARN] invalid session_auto_commit value: {raw!r}; using true (default)",
+        file=sys.stderr,
+    )
+    return DEFAULT_SESSION_AUTO_COMMIT
+
+
 def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
     """Get hook commands for a lifecycle event.
 

package/dist/templates/trellis/scripts/common/safe_commit.py

@@ -15,14 +15,19 @@ Design
 ------
 - Scripts only stage SPECIFIC product paths (journal files, index.md, the
   current task dir, the archive dir). Never the whole `.trellis/` tree.
-- If plain `git add <specific>` fails with "ignored by", retry with
-  `git add -f <specific>` — forcing only the paths the script knows it owns.
-  This is safe because the paths are narrow; it is NOT equivalent to
-  `git add -f .trellis/` (which would fan out to backups/worktrees/runtime).
-- If the -f retry also fails, print an explicit warning that includes a
-  negative example: ``Do NOT use `git add -f .trellis/` ...``
-
-The wider-grain forbidden command stays forbidden.
+- If plain `git add <specific>` fails with "ignored by", DO NOT retry with
+  ``-f``. The presence of `.trellis/` in `.gitignore` is treated as user
+  intent ("keep .trellis/ local-only"). The script warns and skips the
+  auto-commit; users who want auto-staging can either fix their `.gitignore`
+  or set ``session_auto_commit: false`` and manage git themselves.
+- The warning includes a negative example: ``Do NOT use `git add -f .trellis/` ...``
+  so any AI rereading the log doesn't reinvent the bug.
+
+History note: 0.5.10 introduced an automatic ``git add -f`` retry on the
+specific paths. That was reverted in 0.5.11 — auto-forcing into a tree the
+user had gitignored violates user intent even when the path list is narrow.
+The wider-grain forbidden command stays forbidden, and the narrow-grain auto
+``-f`` is gone too.
 """
 
 from __future__ import annotations
@@ -145,20 +150,18 @@ def _stderr_indicates_ignored(stderr: str) -> bool:
 def safe_git_add(
     paths: list[str], repo_root: Path
 ) -> tuple[bool, bool, str]:
-    """Run `git add` on specific paths, retrying with -f if .gitignore blocks.
+    """Run `git add` on specific paths; never retry with -f.
 
-    Returns (success, used_force, stderr). On success, callers should still
-    `git diff --cached` to detect whether anything was actually staged.
+    Returns ``(success, used_force, stderr)``. The ``used_force`` field is
+    kept for signature compatibility with the 0.5.10 implementation but is
+    always ``False`` — we never auto-force.
 
     Behavior:
       - No paths passed → success, no force, empty stderr.
-      - Plain `git add <paths>` succeeds → return.
-      - Plain fails with "ignored by" → retry with `git add -f <paths>`.
-      - Retry succeeds → return success with used_force=True.
-      - Retry fails → return failure; caller should print the gitignore
-        warning (see :func:`print_gitignore_warning`).
-      - Plain fails with a non-ignored error → return failure; do NOT retry
-        with -f (we only force when ignore is the cause).
+      - Plain ``git add -- <paths>`` succeeds → return success.
+      - Plain fails (any reason — ignored or otherwise) → return failure with
+        the stderr. Callers should inspect the stderr (see
+        :func:`print_gitignore_warning`) and skip the auto-commit.
     """
     if not paths:
         return True, False, ""
@@ -166,14 +169,7 @@ def safe_git_add(
     rc, _, err = run_git(["add", "--", *paths], cwd=repo_root)
     if rc == 0:
         return True, False, ""
-
-    if not _stderr_indicates_ignored(err):
-        return False, False, err
-
-    rc2, _, err2 = run_git(["add", "-f", "--", *paths], cwd=repo_root)
-    if rc2 == 0:
-        return True, True, err2 or err
-    return False, True, err2 or err
+    return False, False, err
 
 
 def print_gitignore_warning(paths: list[str]) -> None:
@@ -187,6 +183,15 @@ def print_gitignore_warning(paths: list[str]) -> None:
         "[WARN] git add failed because .trellis/ paths are ignored by your .gitignore.",
         file=sys.stderr,
     )
+    print(
+        "[WARN] Skipping auto-commit. The journal/task files were still written to disk;",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] git was not touched.",
+        file=sys.stderr,
+    )
+    print("[WARN]", file=sys.stderr)
     print(
         "[WARN] Trellis manages these specific paths and they should be tracked:",
         file=sys.stderr,
@@ -219,6 +224,27 @@ def print_gitignore_warning(paths: list[str]) -> None:
     for sub in TRELLIS_IGNORED_SUBPATHS:
         print(f"[WARN]   {sub}", file=sys.stderr)
     print("[WARN]", file=sys.stderr)
+    print(
+        "[WARN] Or, if you intentionally keep .trellis/ local-only, set in",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] .trellis/config.yaml:",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN]   session_auto_commit: false",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] so the scripts skip git entirely and you can review / commit",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] manually with `git status` / `git add` / `git commit`.",
+        file=sys.stderr,
+    )
+    print("[WARN]", file=sys.stderr)
     print(
         "[WARN] Do NOT use `git add -f .trellis/` — it pulls in backups, worktrees,",
         file=sys.stderr,

package/dist/templates/trellis/scripts/common/session_context.py

@@ -14,8 +14,12 @@ Provides:
 from __future__ import annotations
 
 import json
+import os
+import re
+import subprocess
 from pathlib import Path
 
+from .active_task import resolve_context_key
 from .config import get_git_packages
 from .git import run_git
 from .packages_context import get_packages_section
@@ -40,6 +44,14 @@ from .paths import (
 # Helpers
 # =============================================================================
 
+_PACKAGE_NAME = "@mindfoldhq/trellis"
+_UPDATE_CHECK_TIMEOUT_SECONDS = 1.0
+_VERSION_RE = re.compile(
+    r"^\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?\s*$"
+)
+_VERSION_TOKEN_RE = re.compile(r"\b\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?\b")
+
+
 def _collect_package_git_info(repo_root: Path) -> list[dict]:
     """Collect git status and recent commits for packages with independent git repos.
 
@@ -109,6 +121,158 @@ def _append_package_git_context(lines: list[str], package_git_info: list[dict])
         lines.append("")
 
 
+def _read_project_version(repo_root: Path) -> str | None:
+    try:
+        version = (repo_root / DIR_WORKFLOW / ".version").read_text(
+            encoding="utf-8"
+        ).strip()
+    except OSError:
+        return None
+    return version or None
+
+
+def _fetch_trellis_version_output() -> str | None:
+    try:
+        result = subprocess.run(
+            ["trellis", "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=_UPDATE_CHECK_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError, TimeoutError):
+        return None
+
+    if result.returncode != 0:
+        return None
+    output = f"{result.stdout}\n{result.stderr}".strip()
+    return output or None
+
+
+def _extract_available_update_version(output: str) -> str | None:
+    update_match = re.search(
+        r"Trellis update available:\s*"
+        r"(?P<current>\S+)\s*(?:→|->)\s*(?P<latest>\S+)",
+        output,
+    )
+    if update_match:
+        return update_match.group("latest").strip()
+    candidates = _VERSION_TOKEN_RE.findall(output)
+    return candidates[-1] if candidates else None
+
+
+def _resolve_available_update_version() -> str | None:
+    output = _fetch_trellis_version_output()
+    if not output:
+        return None
+    return _extract_available_update_version(output)
+
+
+def _parse_version(version: str) -> tuple[tuple[int, int, int], tuple[str, ...] | None] | None:
+    match = _VERSION_RE.match(version)
+    if not match:
+        return None
+    major, minor, patch, prerelease = match.groups()
+    numbers = (int(major), int(minor or "0"), int(patch or "0"))
+    prerelease_parts = tuple(prerelease.split(".")) if prerelease else None
+    return numbers, prerelease_parts
+
+
+def _compare_prerelease(
+    left: tuple[str, ...] | None,
+    right: tuple[str, ...] | None,
+) -> int:
+    if left is None and right is None:
+        return 0
+    if left is None:
+        return 1
+    if right is None:
+        return -1
+
+    for left_part, right_part in zip(left, right):
+        if left_part == right_part:
+            continue
+        left_numeric = left_part.isdigit()
+        right_numeric = right_part.isdigit()
+        if left_numeric and right_numeric:
+            left_int = int(left_part)
+            right_int = int(right_part)
+            return (left_int > right_int) - (left_int < right_int)
+        if left_numeric:
+            return -1
+        if right_numeric:
+            return 1
+        return (left_part > right_part) - (left_part < right_part)
+
+    return (len(left) > len(right)) - (len(left) < len(right))
+
+
+def _compare_versions(left: str, right: str) -> int | None:
+    parsed_left = _parse_version(left)
+    parsed_right = _parse_version(right)
+    if parsed_left is None or parsed_right is None:
+        return None
+
+    left_numbers, left_prerelease = parsed_left
+    right_numbers, right_prerelease = parsed_right
+    if left_numbers != right_numbers:
+        return (left_numbers > right_numbers) - (left_numbers < right_numbers)
+    return _compare_prerelease(left_prerelease, right_prerelease)
+
+
+def _update_marker_path(repo_root: Path) -> Path:
+    context_key = resolve_context_key()
+    if not context_key:
+        terminal_key = os.environ.get("TERM_SESSION_ID", "").strip()
+        context_key = terminal_key or f"ppid-{os.getppid()}"
+    safe_key = re.sub(r"[^A-Za-z0-9._-]+", "_", context_key).strip("._-")
+    if not safe_key:
+        safe_key = "session"
+    return (
+        repo_root
+        / DIR_WORKFLOW
+        / ".runtime"
+        / f"update-check-{safe_key[:160]}.marker"
+    )
+
+
+def _mark_update_check_attempted(repo_root: Path) -> bool:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return False
+    try:
+        marker_path.parent.mkdir(parents=True, exist_ok=True)
+        marker_path.write_text("checked\n", encoding="utf-8")
+    except OSError:
+        pass
+    return True
+
+
+def _get_update_hint(repo_root: Path) -> str | None:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return None
+
+    current_version = _read_project_version(repo_root)
+    if not current_version:
+        return None
+
+    latest_version = _resolve_available_update_version()
+    if not latest_version:
+        return None
+
+    _mark_update_check_attempted(repo_root)
+    comparison = _compare_versions(current_version, latest_version)
+    if comparison is None or comparison >= 0:
+        return None
+
+    return (
+        f"Trellis update available: {current_version} -> {latest_version}, "
+        f"run npm install -g {_PACKAGE_NAME}@latest"
+    )
+
+
 # =============================================================================
 # JSON Output
 # =============================================================================
@@ -571,4 +735,10 @@ def output_text(repo_root: Path | None = None) -> None:
     Args:
         repo_root: Repository root path. Defaults to auto-detected.
     """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    update_hint = _get_update_hint(repo_root)
+    if update_hint:
+        print(update_hint)
+        print("")
     print(get_context_text(repo_root))

package/dist/templates/trellis/scripts/common/task_store.py

@@ -24,6 +24,7 @@ from pathlib import Path
 
 from .config import (
     get_packages,
+    get_session_auto_commit,
     is_monorepo,
     resolve_package,
     validate_package,
@@ -391,16 +392,28 @@ def _auto_commit_archive(task_name: str, repo_root: Path) -> None:
     """Stage Trellis-owned task paths and commit after archive.
 
     Only stages specific subpaths (the archive subtree and active task dirs),
-    never the whole `.trellis/` tree. If `.gitignore` excludes `.trellis/`,
-    falls back to `git add -f <specific>` and emits a warning that explicitly
-    forbids `git add -f .trellis/` (which would fan out to caches/backups).
+    never the whole ``.trellis/`` tree. If ``.gitignore`` blocks the paths,
+    we warn + skip — we do NOT retry with ``git add -f``. The warning
+    explicitly forbids ``git add -f .trellis/`` (which would fan out to
+    caches/backups) and points users at ``session_auto_commit: false``.
+
+    Honors ``session_auto_commit`` in ``.trellis/config.yaml``: when set to
+    ``false``, this function returns immediately without touching git
+    (the archive directory move on disk is unaffected).
     """
+    if not get_session_auto_commit(repo_root):
+        print(
+            "[OK] session_auto_commit: false — skipping git stage/commit.",
+            file=sys.stderr,
+        )
+        return
+
     paths = safe_archive_paths_to_add(repo_root)
     if not paths:
         print("[OK] No task changes to commit.", file=sys.stderr)
         return
 
-    success, used_force, err = safe_git_add(paths, repo_root)
+    success, _, err = safe_git_add(paths, repo_root)
     if not success:
         if err and "ignored by" in err.lower():
             print_gitignore_warning(paths)
@@ -411,12 +424,6 @@ def _auto_commit_archive(task_name: str, repo_root: Path) -> None:
             )
         return
 
-    if used_force:
-        print(
-            "[OK] Staged Trellis-owned paths with -f (specific paths, not .trellis/).",
-            file=sys.stderr,
-        )
-
     rc, _, _ = run_git(
         ["diff", "--cached", "--quiet", "--", *paths], cwd=repo_root
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",