@blxzer/cursor-trellis 0.1.0

package/dist/templates/markdown/spec/guides/cursor-subagent-policy.md.txt

@@ -0,0 +1,382 @@
+# Cursor subagent dispatch policy
+
+> **Purpose:** Cursor-first guidance for when to spawn Trellis custom agents, which mode to use, and how model choice stays on the Cursor side.
+
+**Abstract policy:** `model_policy: cursor-configured` — Trellis workflow, agents, skills, and hooks **must not** hardcode vendor model IDs in **committed** defaults (`gpt-*`, `claude-*`, etc.).
+
+---
+
+## Quick reference: which entry point am I using?
+
+The same `trellis-*` name can be reached via three entry points with **different model routing**. Identify yours before touching model config:
+
+```
+How did I reach trellis-research / trellis-implement / trellis-check?
+│
+├─ Opened a Cursor chat and @mentioned or /slash-invoked it
+│  → Agent session. Top-bar model decides. Cursor Settings for trellis-* are
+│    largely ineffective under BYOK. Do NOT expect json5 + Method 2.5 here.
+│
+├─ Main session dispatched Task(subagent_type=trellis-*)
+│  → Task dispatch. ONLY path where BYOK json5 + Method 2.5 applies.
+│    Hook injects task context (<!-- trellis-hook-injected --> marker).
+│
+└─ Used the trellis-check SKILL in main session (no subagent spawn)
+   → Skill form. Main-session model. Only trellis-check has both
+     Agent + Skill forms; research/implement are NOT skills.
+```
+
+If unsure: Task dispatch is the path Trellis workflow routes through; Agent session and Skill are manual/edge entry points.
+
+---
+
+## Scene matrix
+
+| Scene                                               | Mechanism                                                      | Mode                                | Output / notes                                                                               |
+| --------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- |
+| Code, history, or external research                 | `ttrellis-research`                                             | Cursor **Agent** (writable)         | `{TASK}/research/*.md`; smart-search-cli first, Cursor web fallback per skill                |
+| Implementation (after `start-execution --approved`) | `ttrellis-implement`                                            | Agent                               | Code edits; no `git commit` in subagent                                                      |
+| Post-implementation verification                    | `ttrellis-check`                                                | Agent                               | Fixes + `verify.md` / gate hints; main session records gates when required                   |
+| Parent/Child child worker                           | `generate-child-prompt --mode subagent`                        | **Parent Task** `trellis-implement` (default) | Child delivers `verify.md` + `handoff.md`; rare per-child model → **new writable Agent** session when user names that child |
+| Architecture / deep review                          | `ttrellis-check` or documented inline deep review               | Agent or main session               | Model via dispatch strategy (Methods 1–2.5, 3–4 below)                                               |
+| PRD Grill (planning)                                | `trellis-micro-grill` contract **inside** `trellis-brainstorm` | **Not** a subagent                  | Single-question business follow-ups only                                                     |
+| Small unclear ask (no task)                         | `trellis-micro-grill` skill                                    | Main session                        | No task artifacts by default                                                                 |
+
+---
+
+## Model dispatch strategy (BYOK-aware)
+
+> **Full technical analysis:** .trellis/spec/guides/cursor-subagent-reverse-engineering-report.md
+
+### Environment detection
+
+| Environment           | Custom Task subagent model control                                                                 | Explore subagent model control                     |
+| --------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| **Native Cursor API** | Frontmatter `model:` works (server-side routing)                                                   | Native model picker                                |
+| **Cursor++ BYOK**     | ❌ Frontmatter / Cursor Settings per-agent: not wired for `trellis-*`; **✅ Method 2.5** if applied | ✅ Independent model via Cursor++ panel (v0.0.11+) |
+
+Under Cursor++ BYOK, **committed** agent frontmatter `model:` and **Cursor Settings** UI for `trellis-research` / `trellis-implement` / `trellis-check` do **not** populate `subagentModelOverrides` for those types (verified). Without **Method 2.5**, custom Task subagents **inherit** the parent session BYOK model. See `.trellis/spec/guides/cursor-subagent-reverse-engineering-report.md`.
+
+### Dispatch strategy matrix
+
+| Subagent type                       | Independent model? (BYOK)            | Method                                                                  | Fallback             |
+| ----------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | -------------------- |
+| **Explore** (built-in)              | ✅ Yes                               | Cursor++ panel (built-in override row)                                  | Inherit parent model |
+| **trellis-research** (custom Task)  | ✅ Yes if **Method 2.5** map applied | **Method 2.5** (machine-local); else Method 1 or **Method 3** (manual) | Inherit parent model |
+| **trellis-implement** (custom Task) | ✅ Yes if **Method 2.5** map applied | **Method 2.5**; else Method 1 or **Method 3**                           | Inherit parent model |
+| **trellis-check** (custom Task)     | ✅ Yes if **Method 2.5** map applied | **Method 2.5**; else Method 1 or **Method 3**                           | Inherit parent model |
+| **generalPurpose** / **shell** / **best-of-n-runner** | ✅ Yes if map includes keys | **Method 2.5 / 2.6** JSON map | Inherit parent model |
+
+### When to ask (and when not)
+
+**Ask** when a subagent dispatch is imminent AND the dispatch method depends on user choice.
+
+**Do not ask** for: planning-only turns, PRD Grill / micro-grill, inline edits in the main session, trellis-check **skill** without spawning the check agent, or any turn where no Trellis subagent will run this round.
+
+Task mode (Lite / Full / Parent) does **not** by itself trigger the question — only **impending subagent dispatch** does.
+
+### Method 1: Inherit (default, zero-friction)
+
+- Custom Task subagents inherit the parent session model.
+- No model question asked. No frontmatter edit.
+- **Use when:** The parent model is appropriate for the subagent's work, or the user has said "用当前模型派发" / "inherit" / "跟上次一样" in this turn.
+
+### Method 2: Explore subagent with custom model (read-only research)
+
+When research is purely **codebase exploration** (no external web search, no file writing outside exploration scope), dispatch an **Explore subagent** instead of trellis-research. The Explore type gets independent model selection via the Cursor++ panel.
+
+**Constraints:**
+
+- Explore subagent is **read-only** — it cannot Write or Edit files.
+- Cannot persist to {TASK}/research/\*.md directly — must return findings in chat, then main session persists.
+- Cannot use smart-search-cli or external tools — limited to Glob, Grep, Read, and terminal.
+
+**Use when:** Pure codebase search/understanding tasks where a different model adds value. Main session receives findings and writes the research files.
+
+### Method 2.5: Cursor++ BYOK proxy map (publishable bundle)
+
+**What it is:** A reversible patch to Cursor++ `extension.js` resolver `WPeLc8` that maps `subagentType` → BYOK catalog **slug** (`model-xxxxx`), evaluated **before** the inherit-parent branch. Verified 2026-06-18 (Cursor++ v0.0.11).
+
+**Trellis ships (every `trellis init` / `trellis update`, strategy C):** `.trellis/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, `config.local.json.example`. Native Cursor API users can ignore this directory.
+
+**Operator workflow (Cursor++ BYOK only):**
+
+1. Fill **`~/.ccursor/trellis-task-models.json`** (user-wide) with `subagent_type` → slug from **`~/.ccursor/providers.json`** `id` fields.
+2. Optionally override per repo: **`.trellis/local/subagent-models.json`** (project wins on same key).
+3. If paths are not auto-detected: copy `config.local.json.example` → `config.local.json`, or run `python patch_wpelc8.py --bootstrap`, or set `TRELLIS_CCURSOR_HOME` / `TRELLIS_CURSOR2PLUS_EXTENSION`.
+4. From `.trellis/local/cursor2plus/`: `python patch_wpelc8.py --print-map` → `python patch_wpelc8.py` → **Developer: Reload Window**.
+5. **Verify:** `taskToolCall dispatching` → `resolvedModelId` matches slug.
+
+**Revert:** `python patch_wpelc8.py --revert`; Reload Window. Re-run patch after Cursor / Cursor++ upgrades.
+
+**Cursor++ sidebar / Cursor Settings:** Do **not** wire `trellis-*` BYOK routing; use JSON + patch.
+
+### Method 2.6: Temporary Task types (advanced, BYOK)
+
+For rare per-dispatch models on the Task channel without changing global slots:
+
+1. Add `.cursor/agents/trellis-worker-<id>.md` (role prompt only; no committed `model:`).
+2. Add `"trellis-worker-<id>": "model-xxxxx"` to **project** `.trellis/local/subagent-models.json`.
+3. Re-run `patch_wpelc8.py`; dispatch `Task(subagent_type=trellis-worker-<id>)`.
+4. Remove agent file and JSON key when done.
+
+Parent/Child **default** does not use 2.6 — it uses `trellis-implement` from the user map. Per-child manual model → **new writable Agent** session (user-named exception).
+
+### Method 3: Manual dispatch (different model for Task subagent)
+
+When a custom Task subagent (`trellis-research`, `trellis-implement`, `trellis-check`) needs a **different model** than the parent under BYOK **and Method 2.5 is not available**:
+
+1. **Main session prepares the dispatch prompt** — full text with:
+   - First line: Selected task: <path> (e.g. .trellis/tasks/06-17-my-task)
+   - Task context from inject-subagent-context.py content (PRD, design, implement docs)
+   - Agent role instructions (from the corresponding .cursor/agents/trellis-<role>.md)
+   - Specific work assignment
+2. **Main session presents the prompt** to the user in a clearly marked block:
+   `── Manual Dispatch Prompt ──
+Target model: <recommended model>
+Agent role: trellis-<role>
+── Prompt Start ──
+<full prompt text>
+── Prompt End ──`
+3. **User actions:**
+   a. Open a new Cursor chat tab
+   b. Select the desired model in the model picker
+   c. Paste the prompt and send
+   d. Wait for completion
+   e. Copy relevant results back to the main session
+
+4. **Main session** receives results from user and integrates them (persists research, reviews implementation, etc.)
+
+**Use when:** The subagent work benefits significantly from a different model's strengths, and the manual overhead is justified.
+
+### Method 4: Ephemeral model overlay (native API only)
+
+Under **native Cursor API** (non-BYOK), frontmatter model: on agent files works for model routing. The original ephemeral overlay mechanism applies:
+
+1. Before dispatch: edit .cursor/agents/trellis-<role>.md frontmatter — add model: <id>.
+2. Dispatch the subagent.
+3. After dispatch: restore frontmatter — remove model: line.
+
+**Under BYOK: this method does NOT work.** Do not attempt ephemeral overlay in BYOK environments.
+
+### Decision flow
+
+```text
+Subagent dispatch needed
+├─ Cursor++ BYOK + trellis-* needs fixed per-role models?
+│  └─ Method 2.5 applied on this machine? → dispatch Task normally (map handles routing)
+├─ Parent model appropriate for trellis-*? → Method 1 (inherit)
+├─ Read-only codebase exploration only? → Method 2 (Explore + Cursor++ panel)
+├─ Native Cursor API (non-BYOK)? → Method 4 (ephemeral frontmatter overlay)
+└─ BYOK, no Method 2.5, different model required? → Method 3 (manual dispatch)
+```
+
+### Main-session contract
+
+When a dispatch is imminent:
+
+1. Assess which method applies based on the decision flow.
+2. If **Method 2.5** is active on this machine: dispatch `trellis-research` / `trellis-implement` / `trellis-check` via Task tool as usual — **do not** ask model each time; **do not** edit agent frontmatter.
+3. If Method 1 (inherit): dispatch directly, no model question.
+4. If Method 2 (Explore): set Explore model in Cursor++ panel if needed, dispatch `explore`.
+5. If Method 3 (manual): prepare the full dispatch prompt, present to user.
+6. If Method 4 (overlay, native API): ask model preference, apply overlay, dispatch, restore.
+
+### Rules
+
+- **Never** commit long-lived model: in shared Trellis templates or team repo defaults.
+- **Never** inject model IDs via hooks (inject-subagent-context.py stays task-only).
+- **Do not** attempt ephemeral model overlay under BYOK — it silently fails for routing (Method 4).
+- **Do not** rely on Cursor Settings per `trellis-*` agent for BYOK routing — use Method 2.5 map or Method 3.
+- Method 2.5 map lives **outside** committed Trellis templates (machine-local); never commit patched `extension.js` into the Trellis repo.
+- **Do not** assume Explore subagent can replace trellis-research for all scenarios — it is read-only and cannot persist files.
+- Workflow and skills **must not** hardcode vendor model IDs.
+
+### Child worker
+
+- **Default (BYOK + map):** Parent session dispatches **Task** `trellis-implement` with prompt from `generate-child-prompt --mode subagent`; model from user/project JSON map.
+- **Exception:** User or `child-prompts.md` names a child for **separate writable Agent** → new chat, manual model, paste prompt (Method 3).
+- **Native API:** ephemeral overlay on `trellis-implement` (Method 4) still valid.
+
+### Technical note
+
+Client layer still only builds override rows for built-in types such as `explore`. Cursor Settings entries for custom agent **names** do not reach the BYOK proxy override list for `trellis-*`. **Method 2.5** patches Cursor++ `WPeLc8` so `taskToolCall` sets `resolvedModelId` from a local `subagentType → slug` table before inherit-parent. **Method 3** bypasses Task routing (user picks model in a new chat).
+
+---
+
+
+## Trellis workflow: using per-agent models (BYOK + Method 2.5)
+
+Operational contract between the Trellis task ladder and Cursor++ BYOK.
+
+### Roles and who picks the model
+
+| Layer | Picks model for… | Mechanism |
+| ----- | ---------------- | --------- |
+| **You (operator)** | Main orchestration chat | Cursor model picker (parent BYOK route) |
+| **You (operator)** | `trellis-research` / `trellis-implement` / `trellis-check` (+ optional built-in Task types) | **Method 2.5 / 2.6** JSON maps + `.trellis/local/cursor2plus/patch_wpelc8.py` — **not** repo agent files |
+| **You (operator)** | `explore` | Cursor++ panel |
+| **Main Agent session** | When to spawn which agent | `workflow.md`, skills, scene matrix |
+| **Hooks** | Never | `inject-subagent-context.py` — task context only |
+
+### Normal Full / Lite task flow
+
+1. **Select task** — `task.py select`; dispatch prompts include `Selected task: .trellis/tasks/<id>` when hooks need it.
+2. **Main session model** — your choice for planning and orchestration.
+3. **Research** — Task `subagent_type=trellis-research` → mapped research slug (Method 2.5).
+4. **Implement** — after `start-execution --approved`, Task `trellis-implement` → mapped implement slug.
+5. **Check** — Task `trellis-check` → mapped check slug.
+6. **Gates / finish** — main session `record-gate`, `trellis-finish-work`.
+
+No model field in dispatch prompt under Method 2.5. Task `model: fast` does **not** override custom types under BYOK.
+
+### When to use which method
+
+| Setup | Research | Implement | Check |
+| ----- | -------- | --------- | ----- |
+| Method 2.5 configured | `trellis-research` Task | `trellis-implement` Task | `trellis-check` Task |
+| No map; one parent model | Task (inherit) | Task (inherit) | Task (inherit) |
+| No map; different models | Method 3 | Method 3 | Method 3 |
+| Repo read-only only | Method 2 Explore | — | — |
+
+### Parent/Child
+
+- **Default:** Parent dispatches **Task** `trellis-implement` (BYOK map applies to `subagentType`).
+- **Rare per-child model:** new writable Agent session when user names that child — not a separate Trellis subagent type by default.
+- Parent retains `review-child` / `integrate-child`; serial integration and worktree rules unchanged.
+
+### Maintainer checklist (BYOK)
+
+1. Resolve slugs in `~/.ccursor/providers.json` (or path in `config.local.json`).
+2. Edit user and/or project JSON maps; include `generalPurpose`, `shell`, `best-of-n-runner` if you use those Task types.
+3. Run `patch_wpelc8.py` from `.trellis/local/cursor2plus/` → Reload Window.
+4. Re-apply after Cursor / Cursor++ upgrades.
+
+### What stays in the Trellis repo
+
+- `.cursor/agents/trellis-*.md` — no committed `model:`; link to this policy.
+- Skills/workflow — **which** agent to spawn, not BYOK slugs.
+
+---
+
+## Model and reuse (baseline)
+
+- **Baseline:** `.cursor/agents/trellis-*.md` in repo have **no** `model:` → **inherit** parent Agent session model when no overlay is applied.
+- **`preToolUse` (Task/Subagent):** injects task context only (`inject-subagent-context.py`). Never inject model IDs.
+
+Optional team paste (comments only — not Cursor product settings):
+
+```yaml
+model_policy: cursor-configured
+dispatch_model: inherit_or_method25_or_manual
+child_worker:
+  mode: separate_writable_agent_session
+explore_subagent:
+  model: independent # Cursor++ panel
+trellis_task_subagents:
+  model: method_2_5_proxy_map # machine-local; not in git
+```
+
+---
+
+## Hooks (Cursor)
+
+| Event                      | Role                                                                    |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `sessionStart`             | Task dashboard, phase index, next-action                                |
+| `preToolUse` Task/Subagent | PRD/jsonl + `<!-- trellis-hook-injected -->`                            |
+| `beforeShellExecution`     | Short-lived ticket for `task.py select` / `selected` / `exit` in shells |
+| `stop`                     | Optional `retrieval-pack-latest.json` when task has `research/`         |
+
+**Per-turn workflow-state on Cursor:** deferred — use `sessionStart` + `/trellis-continue` / `get_context.py --mode phase` instead of Claude `UserPromptSubmit` injection.
+
+---
+
+## Parent/Child alignment
+
+- `generate-child-prompt --mode subagent` → Parent **Task** `trellis-implement` by default; inline mode remains the portable default for non-Cursor platforms.
+- Child workers call `task.py set-child-state <parent> <child> <open|working|blocked|review> --evidence <ref>` — **no** session identity required for this command.
+- Integration states (`accepted`, `integrating`, `integrated`, …) are **Parent-only** via `integrate-child` / `review-child`.
+
+---
+
+## Anti-patterns
+
+- Do not use generic `generalPurpose` / default agents for Trellis research, implement, or check.
+- Do not spawn `ttrellis-implement` from inside `ttrellis-implement` (recursion guard in agent defs).
+- Do not spawn a subagent for PRD Grill — use brainstorm Phase B + micro-grill contract.
+- Do not leave `model:` on agent files after dispatch (always restore).
+
+---
+
+## Hook fallback (no selected-task pointer)
+
+When `preToolUse` cannot resolve a selected task, the subagent should read **`Selected task:`** from the first line of its dispatch prompt, then load `implement.jsonl` / `check.jsonl`, `prd.md`, `design.md`, and `implement.md` manually. Trellis does **not** document or depend on Cursor `/multitask` for workflow orchestration.
+
+## Cursor++ (BYOK) compatibility
+
+[Cursor++](https://ccursor.cometix.dev) (ccursor by cometix) is a third-party Patch that intercepts Cursor API traffic via a local server (`127.0.0.1:39831`). It does **not** modify `.cursor/` files — it intercepts at the API/gRPC layer (`AgentService/RunSSE`, `AvailableModels`, etc.) and routes requests to BYOK providers.
+
+### Confirmed compatibility (v0.0.11+, Cursor 3.7.27)
+
+Verified by local testing on `D:\MyHarness` workspace:
+
+| Trellis component     | Status under Cursor++ | Evidence                                                                            |
+| --------------------- | --------------------- | ----------------------------------------------------------------------------------- |
+| `.cursor/agents/`     | Normal                | Agent files not intercepted; `model:` frontmatter read by Cursor at spawn           |
+| `.cursor/hooks/`      | Normal                | Agent log `requestContextKeys` contains `hooksConfig`                               |
+| `.cursor/skills/`     | Normal                | Agent log `requestContextKeys` contains `agentSkills`                               |
+| `.cursor/mcp.json`    | Normal                | 4+ MCP servers, 300+ tools load normally                                            |
+| SubAgent write access | **Fixed in v0.0.11**  | Prior versions defaulted SubAgent to readonly; `ttrellis-implement` now writes files |
+
+**Minimum version: v0.0.11.** Earlier versions break `ttrellis-implement` due to SubAgent readonly bug.
+
+### Model routing under BYOK (verified 2026-06-18)
+
+- **Explore subagent:** Independent model selection works via Cursor++ panel (v0.0.11+). Cursor++ intercepts and routes the selected BYOK model for Explore-type requests.
+- **Custom Task subagents:** Frontmatter `model:` and Cursor Settings per-agent names are **not** applied for `trellis-*` BYOK routing. Use **Method 2.5** or **Method 3**. **Explore** uses Cursor++ panel.
+- The `model:` ID **must match** a model configured in Cursor++ provider settings (`~/.ccursor/providers.json`). If it doesn't match, the request will fail with a provider error.
+- Cursor++ intercepts `AvailableModels`/`GetDefaultModel` - the model picker and model list are determined by BYOK provider config, not Cursor's official model catalog.
+- Under Cursor++, "inherit" means the parent session's BYOK-routed model, which may differ from what the Cursor UI label suggests.
+- **Full technical analysis:** `.trellis/spec/guides/cursor-subagent-reverse-engineering-report.md`
+
+### Safety boundary
+
+- Cursor++ patches Cursor internal modules at runtime. Strongest recovery: reinstall Cursor.
+- API keys are stored in **plaintext** in `~/.ccursor/providers.json` — restrict file permissions (`chmod 600` / Windows ACL).
+- Cursor++ stores rules in `~/.ccursor/knowledge-base.json`, independent of `.cursor/rules/` and Trellis rules.
+- Version updates lag behind Cursor releases — after a Cursor update, BYOK routing may break until Cursor++ catches up. Trellis hooks/agents/skills survive the window (they don't depend on API routing).
+- Do not mix Cursor++ BYOK sessions with Cursor official sessions — they cannot be continued across each other.
+- Cursor++ may violate Cursor ToS; use at own risk. Not recommended for enterprise/compliance environments.
+
+### Anti-patterns for Cursor++
+
+- Do not use Cursor++ older than v0.0.11 with Trellis (SubAgent readonly bug).
+- Do not assume Cursor official model IDs work under BYOK — use model IDs from your provider config.
+- Do not mix Cursor++ and Cursor official sessions for the same conversation.
+
+## Worktree template
+
+When Parent/Child children use `isolation: git-worktree`, configure `.cursor/worktrees.json` and `task.py prepare-child-worktree` so each child edits in an isolated Git checkout:
+
+```json
+{
+  "setup-worktree": ["<install-command>"],
+  "setup-worktree-unix": ["<install-command>"],
+  "setup-worktree-windows": ["<install-command>"]
+}
+```
+
+Replace `<install-command>` with the project's dependency install command (e.g. `pnpm install --frozen-lockfile`, `npm ci`, `pip install -e .`). Platform-specific keys (`setup-worktree-unix`, `setup-worktree-windows`) are optional; `setup-worktree` is the cross-platform fallback.
+
+For multi-package workspaces, list all install commands needed after a fresh checkout.
+
+## References
+
+- `.cursor/agents/ttrellis-research.md`, `ttrellis-implement.md`, `ttrellis-check.md`
+- `.cursor/agents/.trellis-model-overlay.local.md` — optional overlay audit stub (native API)
+- Reference `patch_wpelc8.py` in task `06-18-byok-manual-dispatch-automation/research/` — copy locally; not a runtime git dependency
+- `.trellis/workflow.md` — Task Ladder + Parent orchestration
+- [Cursor Subagents](https://cursor.com/docs/subagents) — `model: inherit | <id>`
+- [Cursor Multitask changelog](https://cursor.com/changelog/04-24-26) — `/multitask`, Worktrees, Multi-root Workspaces
+- `.cursor/worktrees.json` — Cursor native worktree setup configuration

package/dist/templates/markdown/spec/guides/durable-learning-decision-guide.md.txt

@@ -0,0 +1,76 @@
+# Durable Learning Decision Guide
+
+> **Purpose**: Decide whether a completed task should update `.trellis/spec/` or can archive with an explicit **no durable learning** line.
+
+This guide is a **thinking checklist**. It does not replace code-spec files under `.trellis/spec/<layer>/`.
+
+---
+
+## Valid outcomes (archive `verify.md`)
+
+Pick **one** grep-friendly line before `archive --check`:
+
+| Outcome | Example line in `verify.md` |
+| --- | --- |
+| No reusable insight | `Durable learning decision: no durable learning` (or any line containing `no durable learning`) |
+| Spec was updated | `Spec update evidence: .trellis/spec/Trellis/framework/index.md` |
+| Insight already documented | `Learning artifact: .trellis/tasks/<task>/handoff.md` |
+| Retrospective captured | `Learning artifact: .trellis/workspace/...` or `retrospective.md: <path>` |
+
+Optional planning note (not sufficient alone): `Spec update needed: <reason>` — still record **spec update evidence** after `/trellis:update-spec`.
+
+---
+
+## When to choose each outcome
+
+### `no durable learning`
+
+- Routine bugfix with no new contract or convention
+- One-off config or content change
+- Parent/child task where handoff adds no reusable workflow rule
+
+### Spec update (`Spec update evidence: ...`)
+
+- New or changed CLI/API signature or gate behavior
+- Repeated parent review **changes** on the same class of mistake
+- Workflow bug that should not recur (after `/trellis:break-loop` analysis)
+- Cross-layer contract clarification
+
+### Learning artifact
+
+- `handoff.md` or a retrospective already contains the full insight
+- Parent review notes in `verify.md` are enough for audit (link the path)
+
+---
+
+## Low-friction helpers
+
+```bash
+# Draft missing archive sections (append-only)
+python ./.trellis/scripts/task.py prepare-archive-evidence .trellis/tasks/<task>
+
+# Print spec-capture checklist (stdout only; does not edit specs)
+python ./.trellis/scripts/task.py prepare-learning-scaffold .trellis/tasks/<task> --trigger "parent review changes"
+
+# Parent review surfaces missing child learning lines
+python ./.trellis/scripts/task.py review-child <parent> <child> --check
+```
+
+---
+
+## Skills
+
+- **`/trellis:update-spec`** — edit code-spec after reviewer confirmation
+- **`/trellis:break-loop`** — deep bug analysis; often leads to spec updates
+- **`/trellis:finish-work`** — archive after learning line is present in `verify.md`
+
+---
+
+## Parent reviewer triggers
+
+When `review-child` reports **changes** or documents a workflow defect, the child should either:
+
+1. Update spec and add `Spec update evidence: ...`, or
+2. Document why the fix is one-off (`no durable learning`) with a short reason in `verify.md`.
+
+Do **not** auto-write specs from scaffolding output — scaffolding only suggests existing index paths from task `package` / `scope`.

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

@@ -0,0 +1,101 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Durable Learning Decision Guide](./durable-learning-decision-guide.md) | Choose no-learning vs spec update vs learning artifact before archive | Finishing a task, parent review, or after `/trellis:break-loop` |
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+| [Retrieval daily guide](./retrieval-daily-guide.md) | rg / codegraph / fast-context / smart-search / pack / router | Planning, research, finish verification |
+| [Cursor subagent policy](./cursor-subagent-policy.md) | Task tool scenes, Agent mode, `model_policy: cursor-configured`, Cursor++ | Parent/Child dispatch, research/implement/check, parallel execution |
+| [Cursor context injection guide](./cursor-context-injection-guide.md) | Which Cursor channels reach the model (sessionStart bug, .cursor/rules, AGENTS.md) | "Agent ignored instructions" on Cursor, adding always-visible rules |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] 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)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] 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)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

package/dist/templates/markdown/spec/guides/retrieval-daily-guide.md.txt

@@ -0,0 +1,92 @@
+# Retrieval daily guide (Cursor-first)
+
+> **Purpose:** Choose the right tool; do not confuse **search** with **retrieval-pack scoring**.
+
+## Web research rule (smart-search is mandatory first)
+
+For **external / current / web facts**, **smart-search** (`run_smart_search.py`) is the **mandatory first choice**. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`) are **downgrade-only**: use them solely when smart-search is unavailable (`doctor` not ok, `not_configured` / `failed`, or timeout). Never reach for built-in web search while smart-search is healthy. This rule overrides any general "use available tools" instinct — web retrieval strength is routed inside Trellis, not left to the platform default.
+
+## Quick matrix
+
+| Need | Tool | Notes |
+| --- | --- | --- |
+| Exact string / path / log line | **rg** (Grep) | Fast literal match in repo |
+| Symbol, callers, edit blast radius | **codegraph** MCP | Structure-first for caller/trap/extension intents |
+| Unknown keywords, semantic discovery | **@codebase** (Cursor) or **fast-context** (other platforms) | Cursor: platform-native semantics; others: fast-context MCP |
+| External / current facts | **smart-search-cli** | **Mandatory first** — built-in web tools are downgrade-only (see rule above) |
+| Trellis durable docs | **artifact-search** | `search_artifacts.py` |
+| Past sessions | **session-memory** | Historical; verify against tasks/spec |
+| Intent hint for code questions | **router** | `route_codebase_retrieval.py --platform <name>` — suggests only |
+| Score collected evidence | **retrieval-pack** | `get_context.py --mode retrieval-pack` — does **not** search |
+
+## Platform differences
+
+The router is platform-adaptive since v2. Different platforms have different built-in capabilities, and the router adjusts its route suggestions accordingly.
+
+| Capability | Cursor | Claude Code / Codex | Generic |
+| --- | --- | --- | --- |
+| Semantic search | Platform-native (`@codebase`) | **fast-context** MCP | **fast-context** MCP |
+| Exact search | Platform-native Grep | rg | rg |
+| Structural search | **codegraph** MCP | **codegraph** MCP | **codegraph** MCP |
+| LSP | Platform-native | N/A | N/A |
+
+**Key implication on Cursor**: Do NOT use `fast-context` for semantic search — Cursor's own `@codebase` and built-in search are higher quality (custom embedding model trained on agent sessions). The router outputs `platform-semantic` routes with `platformNative: true` instead of `semantic-fast-context` on cursor.
+
+## Token economy signals
+
+Each route in the router output includes a `tokenEconomy` label:
+
+| Label | Meaning | Typical tools |
+| --- | --- | --- |
+| `high` | Low token cost per correct answer (~80-200 tokens) | codegraph callers/search, platform-semantic |
+| `medium` | Moderate token cost (~200-700 tokens) | codegraph explore, smart rg, fast-context |
+| `low` | High token cost per answer (~3000+ tokens) | naive rg (unconstrained output) |
+
+When `projectFileCount > 2000`, the router promotes structural (codegraph) routes ahead of rg routes for better token efficiency on large codebases.
+
+## Commands
+
+```powershell
+python ./.trellis/scripts/search_artifacts.py --query "<topic>" --json
+python ./.trellis/scripts/search_memory.py --query "<topic>" --json
+python ./.trellis/scripts/run_smart_search.py "<question>" --intent deep-research --json
+python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --json --platform cursor
+python ./.trellis/scripts/get_context.py --mode retrieval-pack --json --input evidence.json
+```
+
+## smart-search fallback
+
+When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_configured` / `failed` (including **search timeout**), use **Cursor WebSearch/WebFetch**, then persist to `{TASK}/research/` with `source: cursor-web-fallback` in frontmatter. See `smart-search-cli` skill §4b.
+
+**CLI discovery (Cursor):** optional env/config override → PATH → `node_modules/.bin` / package script → optional harness wrappers (`Trellis/packages/cli/bin/smart-search.js`). No `.trellis/.runtime/` cache.
+
+## Router vs execution
+
+`route_codebase_retrieval.py` returns **intent + route suggestions** only. **codebase-evidence** is **candidate** until confirmed by Read/Git/tests.
+
+### Structural-first routing (v2)
+
+For structural intents (caller-chain, trap-package-disambiguation, extension-shared-symbol), the router now suggests **codegraph before rg**. This reflects codegraph's superior token economy for structural queries (~80-150 tokens/answer vs rg's ~3557 for naive grep). The agent should still use rg to fill gaps codegraph misses (dynamic dispatch, string-based callsites).
+
+### Semantic routing by platform
+
+On **Cursor**: the router outputs `platform-semantic` routes (with `platformNative: true`) instead of `semantic-fast-context`. The agent should use `@codebase` or Cursor's built-in agent search — these are higher quality than fast-context's Devstral model.
+
+On **other platforms**: the router outputs `semantic-fast-context` routes as before. When the envelope fallback mentions no corroborated candidates, invoke `fast_context_search` after exact rg fails.
+
+### Semantic dual metrics (openclaw / eval)
+
+| Metric | Meaning |
+| --- | --- |
+| `semantic_plan_rate` | Share of queries whose routing envelope lists a semantic route |
+| `semantic_exec_rate` | Share of queries with ≥1 semantic search tool call |
+
+Plan-level presence does not imply execution-level use (see parent research `06-19` OQ-1 双轨).
+
+## retrieval-pack
+
+Default `get_context.py --json` returns **retrievalGuide** only. Run `--mode retrieval-pack` after you have collected evidence JSON / smart-search manifests under `{TASK}/research/smart-search/`.
+
+## Adapters (optimization #9)
+
+Core: rg, task-artifacts, artifact-search, source-git-tests. Enhance: codegraph (structural-first), platform-semantic (Cursor) / fast-context (other), smart-search, session-memory. Placeholders: mcp/browser/network envelope only.