@mindfoldhq/trellis 0.6.0-beta.2 → 0.6.0-beta.20

package/dist/templates/droid/settings.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -17,7 +17,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -27,7 +27,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }
@@ -50,7 +50,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/inject-workflow-state.py",
-            "timeout": 5
+            "timeout": 15
           }
         ]
       }

package/dist/templates/gemini/agents/trellis-check.md

@@ -19,14 +19,18 @@ You are already the `trellis-check` sub-agent that the main session dispatched.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -45,10 +49,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/gemini/agents/trellis-implement.md

@@ -21,13 +21,14 @@ Before implementing, read:
 - `.trellis/workflow.md` - Project workflow
 - `.trellis/spec/` - Development guidelines
 - Task `prd.md` - Requirements document
-- Task `info.md` - Technical design (if exists)
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 
 ## Core Responsibilities
 
 1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
-2. **Understand requirements** - Read prd.md and info.md
-3. **Implement features** - Write code following specs and design
+2. **Understand task artifacts** - Read prd.md, design.md if present, and implement.md if present
+3. **Implement features** - Write code following specs and task artifacts
 4. **Self-check** - Ensure code quality
 5. **Report results** - Report completion status
 
@@ -52,15 +53,15 @@ Read relevant specs based on task type:
 
 ### 2. Understand Requirements
 
-Read the task's prd.md and info.md:
+Read the task's prd.md, design.md if present, and implement.md if present:
 
 - What are the core requirements
 - Key points of technical design
-- Which files to modify/create
+- Implementation order, validation commands, and rollback points
 
 ### 3. Implement Features
 
-- Write code following specs and technical design
+- Write code following specs and task artifacts
 - Follow existing code patterns
 - Only do what's required, no over-engineering
 

package/dist/templates/gemini/settings.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .gemini/hooks/session-start.py",
-            "timeout": 10000
+            "timeout": 30000
           }
         ]
       }
@@ -19,7 +19,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .gemini/hooks/inject-workflow-state.py",
-            "timeout": 5000
+            "timeout": 15000
           }
         ]
       }

package/dist/templates/kiro/agents/trellis-check.json

@@ -1,7 +1,7 @@
 {
   "name": "trellis-check",
   "description": "Code quality check expert. Reviews code changes against specs and self-fixes issues.",
-  "prompt": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.\n\n- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md` and the spec files listed in `<task-path>/check.jsonl` yourself before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Check against specs** - Verify code follows guidelines\n3. **Self-fix** - Fix issues yourself, not just report them\n4. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs\n\nRead relevant specs in `.trellis/spec/` to check code:\n\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
+  "prompt": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.\n\n- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/check.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `design.md` - Technical design (if exists)\n- Task `implement.md` - Execution plan (if exists)\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present\n3. **Check against specs** - Verify code follows guidelines\n4. **Self-fix** - Fix issues yourself, not just report them\n5. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs and Task Artifacts\n\nRead the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:\n\n- Does it satisfy the task requirements\n- Does it follow the technical design and implementation plan when present\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
   "tools": [
     "read",
     "write",

package/dist/templates/kiro/agents/trellis-implement.json

@@ -1,7 +1,7 @@
 {
   "name": "trellis-implement",
   "description": "Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.",
-  "prompt": "# Implement Agent\n\nYou are the Implement Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.\n\n- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md`, `<task-path>/info.md` (if it exists), and the spec files listed in `<task-path>/implement.jsonl` yourself before doing the work.\n\n## Context\n\nBefore implementing, read:\n- `.trellis/workflow.md` - Project workflow\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `info.md` - Technical design (if exists)\n\n## Core Responsibilities\n\n1. **Understand specs** - Read relevant spec files in `.trellis/spec/`\n2. **Understand requirements** - Read prd.md and info.md\n3. **Implement features** - Write code following specs and design\n4. **Self-check** - Ensure code quality\n5. **Report results** - Report completion status\n\n## Forbidden Operations\n\n**Do NOT execute these git commands:**\n\n- `git commit`\n- `git push`\n- `git merge`\n\n---\n\n## Workflow\n\n### 1. Understand Specs\n\nRead relevant specs based on task type:\n\n- Spec layers: `.trellis/spec/<package>/<layer>/`\n- Shared guides: `.trellis/spec/guides/`\n\n### 2. Understand Requirements\n\nRead the task's prd.md and info.md:\n\n- What are the core requirements\n- Key points of technical design\n- Which files to modify/create\n\n### 3. Implement Features\n\n- Write code following specs and technical design\n- Follow existing code patterns\n- Only do what's required, no over-engineering\n\n### 4. Verify\n\nRun project's lint and typecheck commands to verify changes.\n\n---\n\n## Report Format\n\n```markdown\n## Implementation Complete\n\n### Files Modified\n\n- `src/components/Feature.tsx` - New component\n- `src/hooks/useFeature.ts` - New hook\n\n### Implementation Summary\n\n1. Created Feature component...\n2. Added useFeature hook...\n\n### Verification Results\n\n- Lint: Passed\n- TypeCheck: Passed\n```\n\n---\n\n## Code Standards\n\n- Follow existing code patterns\n- Don't add unnecessary abstractions\n- Only do what's required, no over-engineering\n- Keep code readable",
+  "prompt": "# Implement Agent\n\nYou are the Implement Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.\n\n- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/implement.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.\n\n## Context\n\nBefore implementing, read:\n- `.trellis/workflow.md` - Project workflow\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `design.md` - Technical design (if exists)\n- Task `implement.md` - Execution plan (if exists)\n\n## Core Responsibilities\n\n1. **Understand specs** - Read relevant spec files in `.trellis/spec/`\n2. **Understand task artifacts** - Read prd.md, design.md if present, and implement.md if present\n3. **Implement features** - Write code following specs and task artifacts\n4. **Self-check** - Ensure code quality\n5. **Report results** - Report completion status\n\n## Forbidden Operations\n\n**Do NOT execute these git commands:**\n\n- `git commit`\n- `git push`\n- `git merge`\n\n---\n\n## Workflow\n\n### 1. Understand Specs\n\nRead relevant specs based on task type:\n\n- Spec layers: `.trellis/spec/<package>/<layer>/`\n- Shared guides: `.trellis/spec/guides/`\n\n### 2. Understand Requirements\n\nRead the task's prd.md, design.md if present, and implement.md if present:\n\n- What are the core requirements\n- Key points of technical design\n- Implementation order, validation commands, and rollback points\n\n### 3. Implement Features\n\n- Write code following specs and task artifacts\n- Follow existing code patterns\n- Only do what's required, no over-engineering\n\n### 4. Verify\n\nRun project's lint and typecheck commands to verify changes.\n\n---\n\n## Report Format\n\n```markdown\n## Implementation Complete\n\n### Files Modified\n\n- `src/components/Feature.tsx` - New component\n- `src/hooks/useFeature.ts` - New hook\n\n### Implementation Summary\n\n1. Created Feature component...\n2. Added useFeature hook...\n\n### Verification Results\n\n- Lint: Passed\n- TypeCheck: Passed\n```\n\n---\n\n## Code Standards\n\n- Follow existing code patterns\n- Don't add unnecessary abstractions\n- Only do what's required, no over-engineering\n- Keep code readable",
   "tools": [
     "read",
     "write",

package/dist/templates/markdown/spec/guides/code-reuse-thinking-guide.md.txt

@@ -58,6 +58,29 @@ grep -r "keyword" .
 
 **Good**: Single source of truth, import everywhere
 
+### Pattern 4: Repeated Payload Field Extraction
+
+**Bad**: Multiple consumers cast the same JSON/event fields locally:
+
+```typescript
+const description = (ev as { description?: string }).description;
+const context = (ev as { context?: ContextEntry[] }).context;
+```
+
+This is duplicated contract logic even when the code is only two lines. Each
+consumer now has its own definition of what a valid payload means.
+
+**Good**: Put the decoder, type guard, or projection next to the data owner:
+
+```typescript
+if (isThreadEvent(ev)) {
+  renderThreadEvent(ev);
+}
+```
+
+**Rule**: If the same untyped payload field is read in 2+ places, create a
+shared type guard / normalizer / projection before adding a third reader.
+
 ---
 
 ## When to Abstract
@@ -82,6 +105,74 @@ When you've made similar changes to multiple files:
 2. **Search**: Run grep to find any missed
 3. **Consider**: Should this be abstracted?
 
+### Reducers Should Use Exhaustive Structure
+
+When state is derived from action-like values (`action`, `kind`, `status`,
+`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
+
+```typescript
+// BAD - action-specific state transitions are hard to audit
+if (action === "opened") { ... }
+else if (action === "comment") { ... }
+else if (action === "status") { ... }
+
+// GOOD - one reducer owns the transition table
+switch (event.action) {
+  case "opened":
+    ...
+    return;
+  case "comment":
+    ...
+    return;
+}
+```
+
+This matters when the event log is the source of truth. A reducer is the
+documented replay model; display code and commands should not duplicate pieces
+of that replay model.
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] No repeated untyped payload field extraction outside a shared decoder
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure
+- [ ] Reducer/action transitions live in one reducer or command dispatcher
+
+---
+
+## Gotcha: Python if/elif/else Exhaustive Check
+
+**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
+
+**Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
+
+**Example** (`cli_adapter.py`):
+```python
+# BAD: "gemini" falls through to else, returns "claude"
+@property
+def cli_name(self) -> str:
+    if self.platform == "opencode":
+        return "opencode"
+    else:
+        return "claude"  # gemini silently gets "claude"!
+
+# GOOD: explicit branch for every platform
+@property
+def cli_name(self) -> str:
+    if self.platform == "opencode":
+        return "opencode"
+    elif self.platform == "gemini":
+        return "gemini"
+    else:
+        return "claude"
+```
+
+**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
+
 ---
 
 ## Gotcha: Asymmetric Mechanisms Producing Same Output
@@ -90,16 +181,43 @@ When you've made similar changes to multiple files:
 
 **Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
 
-**Prevention checklist**:
-- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
-- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
-- [ ] Add a regression test that compares outputs from both mechanisms
+**Prevention**:
+- **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
+- **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
+- When migrating directory structures, search for ALL code paths that reference the old structure
+
+**Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
 
 ---
 
-## Checklist Before Commit
+## Template File Registration (Trellis-specific)
 
-- [ ] Searched for existing similar code
-- [ ] No copy-pasted logic that should be shared
-- [ ] Constants defined in one place
-- [ ] Similar patterns follow same structure
+When adding new files to `src/templates/trellis/scripts/`:
+
+**Single registration point**: `src/templates/trellis/index.ts`
+
+1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
+2. Add to `getAllScripts()` Map
+
+That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
+
+**Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
+
+**History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
+
+### Quick Checklist for New Scripts
+
+```bash
+# After adding a new .py file, verify it's in getAllScripts():
+grep -l "newFileName" src/templates/trellis/index.ts  # Should match
+```
+
+### Template Sync Convention
+
+`.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
+
+```bash
+rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
+```
+
+**Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.

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

@@ -9,6 +9,7 @@
 **Most bugs happen at layer boundaries**, not within layers.
 
 Common cross-layer bugs:
+
 - API returns format A, frontend expects format B
 - Database stores X, service transforms to Y, but loses data
 - Multiple layers implement the same logic differently
@@ -26,22 +27,24 @@ Source → Transform → Store → Retrieve → Transform → Display
 ```
 
 For each arrow, ask:
+
 - What format is the data in?
 - What could go wrong?
 - Who is responsible for validation?
 
 ### Step 2: Identify Boundaries
 
-| Boundary | Common Issues |
-|----------|---------------|
-| API ↔ Service | Type mismatches, missing fields |
-| Service ↔ Database | Format conversions, null handling |
-| Backend ↔ Frontend | Serialization, date formats |
-| Component ↔ Component | Props shape changes |
+| Boundary              | Common Issues                     |
+| --------------------- | --------------------------------- |
+| API ↔ Service         | Type mismatches, missing fields   |
+| Service ↔ Database    | Format conversions, null handling |
+| Backend ↔ Frontend    | Serialization, date formats       |
+| Component ↔ Component | Props shape changes               |
 
 ### Step 3: Define Contracts
 
 For each boundary:
+
 - What is the exact input format?
 - What is the exact output format?
 - What errors can occur?
@@ -68,27 +71,189 @@ For each boundary:
 
 **Good**: Each layer only knows its neighbors
 
+### Mistake 4: Every Consumer Parses The Same Payload
+
+**Bad**: A command reads JSONL events and casts fields inline:
+
+```typescript
+const thread = (ev as { thread?: string }).thread;
+const labels = (ev as { labels?: string[] }).labels;
+```
+
+This looks local, but it means every consumer owns a private version of the
+event contract. The next field change will update one command and miss another.
+
+**Good**: Decode once at the event boundary, then export typed projections:
+
+```typescript
+if (!isThreadEvent(ev)) return false;
+return ev.thread === filter.thread;
+```
+
+**Rule**: For append-only logs, JSON streams, RPC payloads, or config files,
+create one owner for:
+
+- event / payload type definitions
+- type guards and normalization from `unknown`
+- metadata projections used by UI commands
+- reducers that replay state from the source of truth
+
+Rendering code may format fields, but it must not redefine the payload contract.
+
 ---
 
 ## Checklist for Cross-Layer Features
 
 Before implementation:
+
 - [ ] Mapped the complete data flow
 - [ ] Identified all layer boundaries
 - [ ] Defined format at each boundary
 - [ ] Decided where validation happens
 
 After implementation:
+
 - [ ] Tested with edge cases (null, empty, invalid)
 - [ ] Verified error handling at each boundary
 - [ ] Checked data survives round-trip
+- [ ] Checked that consumers import shared decoders / projections instead of
+      casting payload fields locally
+- [ ] Checked that derived state points back to the source event identifier
+      (`seq`, `id`, `version`) instead of inventing a second cursor
+
+---
+
+## 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.
+
+---
+
+## Generated Runtime Template Upgrade Consistency
+
+Some generated files are both documentation and runtime input. In Trellis,
+`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
+SessionStart filters, and per-turn hooks. Template changes must be validated
+against both fresh init and upgrade paths.
+
+### Checklist: After Modifying A Runtime-Parsed Template
+
+- [ ] Identify every runtime parser that reads the template, not just the file
+      writer that installs it
+- [ ] Check whether relevant syntax lives outside obvious managed regions
+      such as tag blocks
+- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
+      the older `.trellis/.version`
+- [ ] Add an upgrade regression using an older pristine template fixture, then
+      assert the installed file reaches the current packaged shape
+- [ ] Update the backend spec that owns the runtime contract
+
+---
+
+## Versioned Documentation Boundary
+
+Versioned documentation is a cross-layer boundary: source paths, `docs.json`
+version routing, and the rendered version selector must all describe the same
+release line.
+
+### Checklist: Before Editing Versioned Docs
+
+- [ ] Identify the target release line: stable, beta, or RC
+- [ ] Verify the edited MDX path matches that line:
+  - stable: `docs-site/{start,advanced,...}` and `docs-site/zh/{start,advanced,...}`
+  - beta: `docs-site/beta/**` and `docs-site/zh/beta/**`
+  - RC: `docs-site/rc/**` and `docs-site/zh/rc/**`
+- [ ] Verify `docs.json` navigation points the version label to the same paths
+- [ ] Grep the opposite tree for release-line-specific terms before committing
+- [ ] Treat beta content appearing under root release paths as a source-path bug,
+      not a rendering bug
+
+**Real-world example**: A beta-only task workflow change documented
+`prd.md` + `design.md` + `implement.md`, task-creation consent, and Codex
+mode banners under root `start/` and `advanced/` paths. The docs site then
+served 0.6 beta behavior under the Release selector. The fix was to restore root
+release docs, move the 0.6 content to `beta/` and `zh/beta/`, and add a grep
+audit for beta markers against the root release tree.
+
+**Real-world example**: Codex inline mode changed workflow platform markers from
+`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
+`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
+`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
+markers outside those blocks. Result: upgraded projects got new hook scripts
+but old workflow routing, so `get_context.py --mode phase --platform codex`
+could return empty Phase 2.1 detail.
+
+---
+
+## 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:
+
 - Feature spans 3+ layers
 - Multiple teams are involved
 - Data format is complex
 - Feature has caused bugs before
+
+---
+
+## Event Log / Projection Boundary
+
+Append-only logs are cross-layer contracts. A single event travels through:
+
+```
+CLI input → event writer → events.jsonl → reader → filter → reducer → display
+```
+
+### Checklist: After Adding A New Event Kind Or Field
+
+- [ ] Add the event kind to the central event taxonomy
+- [ ] Add a typed event variant or type guard at the event layer
+- [ ] Add normalization helpers for array/object fields that come from
+      user input or JSON
+- [ ] Keep `seq` / `id` assignment in the event writer only
+- [ ] Make filters and reducers consume the typed event guard, not local casts
+- [ ] Make display code consume reducer output or typed events, not raw JSON
+- [ ] Add at least one regression that proves history replay and live filtering
+      use the same filter model
+
+**Real-world example**: Thread channels added `kind: "thread"`, `description`,
+`context`, labels, and `lastSeq`. The first implementation replayed thread
+state correctly, but several commands still re-parsed event payload fields with
+local casts. The fix was to make the core event layer own `ThreadChannelEvent`
+and `isThreadEvent`, make `reduceChannelMetadata` the only channel metadata
+projection, and make `reduceThreads` the only thread replay reducer.