@mindfoldhq/trellis 0.6.0-beta.11 → 0.6.0-beta.13

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

@@ -71,6 +71,35 @@ 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
@@ -87,6 +116,10 @@ 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
 
 ---
 
@@ -195,3 +228,32 @@ Create detailed flow docs when:
 - 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.

package/dist/templates/markdown/spec/guides/index.md.txt

@@ -34,6 +34,8 @@ These guides help you **ask the right questions before coding**.
 - [ ] Data format changes between layers
 - [ ] Multiple consumers need the same data
 - [ ] You're not sure where to put some logic
+- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
+- [ ] UI / command code starts casting raw payload fields directly
 
 → Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
 
@@ -44,9 +46,25 @@ These guides help you **ask the right questions before coding**.
 - [ ] You're adding a new field to multiple places
 - [ ] **You're modifying any constant or config**
 - [ ] **You're creating a new utility/helper function** ← Search first!
+- [ ] Two files read the same untyped payload field with local casts
+- [ ] Multiple branches update the same derived state from `kind` / `action`
 
 → Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
 
+### When Verifying AI Cross-Review Results
+
+- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
+- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
+- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
+- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
+
+**Common AI reviewer false-positive patterns**:
+1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
+2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
+3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
+
+**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
+
 ---
 
 ## Pre-Modification Rule (CRITICAL)

package/dist/utils/task-json.d.ts

@@ -1,46 +1,13 @@
 /**
- * Canonical task.json shape — single source of truth shared by all TS writers.
+ * Canonical task.json shape — single source of truth shared by all TS
+ * writers. The canonical types and factory now live in the
+ * `@mindfoldhq/trellis-core` task API; this module re-exports them under
+ * the legacy `TaskJson` / `emptyTaskJson` names for CLI call sites.
  *
- * The runtime Python writer is `.trellis/scripts/common/task_store.py` in
- * `cmd_create` (lines ~147-172). This TS factory mirrors that 24-field shape
- * so bootstrap tasks (trellis init) and migration tasks (trellis update
- * --migrate) produce structurally identical task.json files.
- *
- * Field names, order, and null defaults match task_store.py exactly.
- */
-export interface TaskJson {
-    id: string;
-    name: string;
-    title: string;
-    description: string;
-    status: string;
-    dev_type: string | null;
-    scope: string | null;
-    package: string | null;
-    priority: string;
-    creator: string;
-    assignee: string;
-    createdAt: string;
-    completedAt: string | null;
-    branch: string | null;
-    base_branch: string | null;
-    worktree_path: string | null;
-    commit: string | null;
-    pr_url: string | null;
-    subtasks: string[];
-    children: string[];
-    parent: string | null;
-    relatedFiles: string[];
-    notes: string;
-    meta: Record<string, unknown>;
-}
-/**
- * Produce a fully-populated canonical-shape TaskJson.
- *
- * All 24 fields are emitted in canonical order. `overrides` shallow-merges on
- * top — callers should supply the per-task values (id, name, title, assignee,
- * createdAt, etc.) and leave null-default fields untouched unless they have a
- * real value.
+ * New code should prefer `TrellisTaskRecord` / `emptyTaskRecord` from
+ * `@mindfoldhq/trellis-core/task` directly.
  */
-export declare function emptyTaskJson(overrides?: Partial<TaskJson>): TaskJson;
+import { emptyTaskRecord, type TrellisTaskRecord } from "@mindfoldhq/trellis-core/task";
+export type TaskJson = TrellisTaskRecord;
+export declare const emptyTaskJson: typeof emptyTaskRecord;
 //# sourceMappingURL=task-json.d.ts.map

package/dist/utils/task-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-json.d.ts","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,QAAQ,CAAM,GAAG,QAAQ,CA6BzE"}
+{"version":3,"file":"task-json.d.ts","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAEzC,eAAO,MAAM,aAAa,wBAAkB,CAAC"}

package/dist/utils/task-json.js

@@ -1,49 +1,12 @@
 /**
- * Canonical task.json shape — single source of truth shared by all TS writers.
+ * Canonical task.json shape — single source of truth shared by all TS
+ * writers. The canonical types and factory now live in the
+ * `@mindfoldhq/trellis-core` task API; this module re-exports them under
+ * the legacy `TaskJson` / `emptyTaskJson` names for CLI call sites.
  *
- * The runtime Python writer is `.trellis/scripts/common/task_store.py` in
- * `cmd_create` (lines ~147-172). This TS factory mirrors that 24-field shape
- * so bootstrap tasks (trellis init) and migration tasks (trellis update
- * --migrate) produce structurally identical task.json files.
- *
- * Field names, order, and null defaults match task_store.py exactly.
- */
-/**
- * Produce a fully-populated canonical-shape TaskJson.
- *
- * All 24 fields are emitted in canonical order. `overrides` shallow-merges on
- * top — callers should supply the per-task values (id, name, title, assignee,
- * createdAt, etc.) and leave null-default fields untouched unless they have a
- * real value.
+ * New code should prefer `TrellisTaskRecord` / `emptyTaskRecord` from
+ * `@mindfoldhq/trellis-core/task` directly.
  */
-export function emptyTaskJson(overrides = {}) {
-    const today = new Date().toISOString().split("T")[0];
-    const base = {
-        id: "",
-        name: "",
-        title: "",
-        description: "",
-        status: "planning",
-        dev_type: null,
-        scope: null,
-        package: null,
-        priority: "P2",
-        creator: "",
-        assignee: "",
-        createdAt: today,
-        completedAt: null,
-        branch: null,
-        base_branch: null,
-        worktree_path: null,
-        commit: null,
-        pr_url: null,
-        subtasks: [],
-        children: [],
-        parent: null,
-        relatedFiles: [],
-        notes: "",
-        meta: {},
-    };
-    return { ...base, ...overrides };
-}
+import { emptyTaskRecord, } from "@mindfoldhq/trellis-core/task";
+export const emptyTaskJson = emptyTaskRecord;
 //# sourceMappingURL=task-json.js.map

package/dist/utils/task-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-json.js","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6BH;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,YAA+B,EAAE;IAC7D,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAa;QACrB,EAAE,EAAE,EAAE;QACN,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,EAAE;QACT,WAAW,EAAE,EAAE;QACf,MAAM,EAAE,UAAU;QAClB,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,KAAK;QAChB,WAAW,EAAE,IAAI;QACjB,MAAM,EAAE,IAAI;QACZ,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,IAAI;QACnB,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,IAAI;QACZ,YAAY,EAAE,EAAE;QAChB,KAAK,EAAE,EAAE;QACT,IAAI,EAAE,EAAE;KACT,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,EAAE,CAAC;AACnC,CAAC"}
+{"version":3,"file":"task-json.js","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,GAEhB,MAAM,+BAA+B,CAAC;AAIvC,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.6.0-beta.11",
+  "version": "0.6.0-beta.13",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,8 @@
     "giget": "^3.1.1",
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
-    "zod": "^4.4.2"
+    "zod": "^4.4.2",
+    "@mindfoldhq/trellis-core": "0.6.0-beta.13"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
@@ -77,12 +78,12 @@
     "typecheck": "tsc --noEmit",
     "lint:py": "basedpyright",
     "lint:all": "pnpm lint && pnpm lint:py",
-    "release": "node scripts/check-manifest-continuity.js && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version patch && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin main --tags",
-    "release:minor": "node scripts/check-manifest-continuity.js && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version minor && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin main --tags",
-    "release:major": "node scripts/check-manifest-continuity.js && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version major && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin main --tags",
-    "release:beta": "node scripts/check-manifest-continuity.js && node scripts/check-docs-changelog.js --type beta && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version prerelease --preid beta && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin HEAD --tags",
-    "release:rc": "node scripts/check-manifest-continuity.js && node scripts/check-docs-changelog.js --type rc && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version prerelease --preid rc && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin HEAD --tags",
-    "release:promote": "node scripts/check-manifest-continuity.js && node scripts/check-docs-changelog.js --type promote && pnpm test && git add -A -- ':!docs-site' && (git diff-index --quiet HEAD || git commit -m 'chore: pre-release updates') && pnpm version --no-git-tag-version \"$(node -p \"require('./package.json').version.replace(/-.*/, '')\")\" && V=$(node -p \"require('./package.json').version\") && git add package.json && git commit -m \"$V\" && git tag \"v$V\" && git push origin main --tags",
+    "release": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
+    "release:beta": "node scripts/release.js beta",
+    "release:rc": "node scripts/release.js rc",
+    "release:promote": "node scripts/release.js promote",
     "manifest": "node scripts/create-manifest.js"
   }
 }