@blxzer/cursor-trellis 0.3.5 → 0.4.0

package/dist/templates/cursor/rules/cstl-cursor-modes.mdc

@@ -0,0 +1,32 @@
+---
+description: "Prefer Cursor native modes — task-driven; quiet cstl spine fallback"
+alwaysApply: true
+---
+
+# Prefer Cursor native modes (P1 — orchestrate, don't replace)
+
+cstl **prefers** Cursor native modes and maps them to Trellis Triage/phases. **Do not** replace Cursor UI or invent a parallel Plan/Ask/Debug product. Full table: `.cstl/spec/guides/cursor-native-modes-guide.md` · evidence: `{TASK}/research/modes-callability-matrix.md`.
+
+## Quick routing
+
+| Situation | Prefer | Trellis anchor |
+| --- | --- | --- |
+| Read-only explain / lookup | **Ask** when reachable; else No Task in Agent | `[Triage: No Task]` — no durable edits |
+| Scope / design before code | **Try `SwitchMode(plan)`**; if poor, write artifacts in Agent | Phase 1 → `prd.md` / `design.md` / `implement.md`; `--check` |
+| Approved build / verify | **Agent**; `SwitchMode(agent)` after Plan | Phase 2–3; `execution_mode` |
+| Runtime / repeat failure | **Debug** when reachable; else verify + break-loop | Evidence → `verify.md` |
+| Independent Parent children (post-approval) | **Multitask** / `Task` parallel when useful | Explicit `.cstl/tasks/<dir>` per worker; Parent integrates |
+
+## Quiet fallback
+
+When native cannot be task-driven well: continue on the **cstl spine** (Triage / Phase / artifacts / gates). Do **not** add user-facing “本版本不适配某 mode” copy. Do **not** center guidance on “please open the mode picker.”
+
+## Hard boundaries
+
+- Plan default save = **home dir** until Save to workspace → map into task files.
+- Multitask/subagents: **never** rely on `selected_task`; worktrees + Parent review.
+- Agent `SwitchMode`: **`plan` / `agent` only** (Ask/Debug not in the tool enum).
+
+## Rollback
+
+Delete this file + `cursor-native-modes-guide.md` (see guide Rollback).

package/dist/templates/cursor/rules/cstl-triage.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Trellis Request Triage — mandatory classification before any work (Cursor sessionStart additional_context is broken; this rule is the reliable injection channel)"
+description: "Trellis Request Triage — mandatory classification before any work (Cursor: alwaysApply rule is the per-turn reliable channel; sessionStart is session-level only)"
 alwaysApply: true
 ---
 
@@ -33,6 +33,4 @@ If the user declines a task for a simple request, skip Trellis for this session.
 
 ## Why this rule exists
 
-Cursor's `sessionStart` hook has a confirmed bug (#158452): `additional_context` is never injected into the agent's system context. The Triage rules in `.cstl/workflow.md` therefore never reach you via that channel. This `.cursor/rules` file is the reliable workaround — Cursor prepends rules to your context before every prompt, independent of the broken sessionStart path.
-
-Full decision-tree details, trigger-signal keywords, and the Task Ladder table: see `.cstl/workflow.md` → `### Request Triage`.
+Request Triage must be visible **on every turn**, not only at session start. `.cursor/rules` with `alwaysApply: true` is the reliable per-turn channel on Cursor. `sessionStart` `additional_context` delivers session-level orientation (dashboard, workflow summary) once per session — useful but insufficient for a per-turn hard gate. The full decision tree also lives in `.cstl/workflow.md` for on-demand loading via `get_context.py` / `cstl-continue`.

package/dist/templates/cursor/rules/retrieval-routing.mdc

@@ -5,7 +5,23 @@ alwaysApply: true
 
 # Codebase retrieval routing (Cursor)
 
-Before answering **code-location / architecture / caller-chain / config-schema** questions in this repo, use the retrieval layer deliberately. On Cursor, **`.cursor/rules` is the reliable policy channel**; **per-query `## 代码库检索计划` blocks** are injected by the **`beforeSubmitPrompt`** hook (`.cursor/hooks/inject-retrieval-plan.py`) when the user message looks like a codebase question. Do **not** depend on `sessionStart` hook `additional_context` (#158452) or end-of-turn retrieval-pack hooks for plans.
+Before answering **code-location / architecture / caller-chain / config-schema** questions in this repo, use the retrieval layer deliberately. On Cursor, **`.cursor/rules` is the reliable per-turn policy channel**; the **`beforeSubmitPrompt`** hook (`.cursor/hooks/inject-retrieval-plan.py`) runs **telemetry-only** — it does **not** inject `## 代码库检索计划` blocks. Generate a plan via `route_codebase_retrieval.py --instructions` when needed, or follow the default tool order below. Do **not** depend on end-of-turn retrieval-pack hooks for plans.
+
+## Prefer / Adapt / Own (code intelligence)
+
+**Three surfaces (do not conflate):** (1) **IDE Editor** — full extension LSP; (2) **Agents Window (Glass)** — staff-reported partial LSP vs Editor ([forum](https://forum.cursor.com/t/cursor-agents-window-lsp-not-working-with-typescript/156772)); (3) **Agent autonomous tools** — [official list](https://cursor.com/docs/agent/overview.md) is search/read/edit/shell/web — **no** `GO_TO_DEFINITION` / raw LSP tool. Trellis routes **Agent tool table** only. See `retrieval-daily-guide.md` § Prefer/Adapt/Own evidence (2026-08-05 smart-search + Native probe).
+
+| Need | **Prefer** (Cursor native, Agent-reachable) | **Adapt** (route by intent / `cursorEnv`) | **Own** (codegraph / MCP) |
+| --- | --- | --- | --- |
+| Exact literal / path | **Grep** | — | — |
+| Named-symbol definition (known identifier) | **Grep → Read** | Path hints from semantic when file unknown | codegraph when cross-package trap, overload ambiguity, or blast context needed |
+| Agent-session diagnostics | **ReadLints** (when in tool table) | — | — |
+| Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search (index embeddings; ≠ LSP) | **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. | — |
+| Caller chain / blast radius | Grep for imports/callbacks (gap-fill) | — | **codegraph_callers** / **codegraph_explore** |
+| Cross-package trap / extension symbol | Grep scoped by package or `extensions/` | — | **codegraph_search** / **codegraph_explore** |
+| Raw LSP / GO_TO_DEFINITION **as Agent tool** | **Not in Agent tool table** (official docs + Native probe 2026-08-05) | IDE Editor has LSP; Agents Window may lack parity — human UI, not Agent routing | codegraph when Grep+Read insufficient |
+
+**Rollback:** revert this rule + `retrieval-daily-guide.md` Prefer rows to the pre-P1 codegraph-first definition wording; keep codegraph MCP enabled.
 
 ## When a retrieval plan block is present
 
@@ -13,7 +29,7 @@ If the user message or Trellis context contains a block starting with `## 代码
 
 1. Execute steps **in order** before stating file paths or behavior claims.
 2. Treat each step as mandatory tooling (not suggestions).
-3. Finish with **Read** verification on cited sources (definition jumps use **codegraph_node**, not LSP).
+3. Finish with **Read** verification on cited sources (definition jumps: **Grep → Read** first; **codegraph** when the plan lists structural/trap routes or Grep is ambiguous).
 
 Generate a fresh plan when needed:
 
@@ -32,12 +48,13 @@ python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --json
 | Need | Tool (Cursor) |
 | --- | --- |
 | Exact string / path | **Grep** (Instant Grep) |
-| Who calls / blast radius | **codegraph_callers** → Grep for imports/callbacks |
+| Named-symbol definition | **Grep** → **Read** (Prefer native); **codegraph_explore** / **codegraph_search** when trap, overload, or blast context needed |
+| IDE diagnostics | **ReadLints** on touched or cited files |
+| Who calls / blast radius | **codegraph_callers** / **codegraph_explore** → Grep for imports/callbacks |
 | Same name across packages (trap) | **codegraph_search** / **codegraph_explore** → Grep |
 | Extension symbols | **codegraph_search** under `extensions/` |
 | Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search. **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. |
 | Policy / architecture / boundaries / storage rules | **Grep** on `AGENTS.md`, `**/AGENTS.md`, `.cstl/spec/**`, `README.md` (router `policy-docs-rg`) before implementation modules |
-| Definition jump | **codegraph_node** / **codegraph_search**, then **Read** (Agent does not expose GO_TO_DEFINITION / LSP) |
 | Wide cross-cutting explore | **Native:** DEEP_SEARCH or Explore subagent. **BYOK:** **Task explore** subagent, then Grep/codegraph/Read |
 
 ## Semantic on Cursor (`platform-semantic`)
@@ -50,10 +67,12 @@ python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --json
 
 When the plan block includes **结果层排序**, apply it **after** collecting path candidates and **before** stating Top-1 / Top-5: caller concrete sites over assembly files; trap demotion; env scripts/e2e/bench over generic `src/auth`/`paths`. Offline reorder: `rank_retrieval_candidates.py`.
 
-## codegraph-only value
+## codegraph-only value (Own layer)
+
+Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, **impact/blast radius**, and **definition/reference when native Grep+Read is ambiguous** — not for pure literal search (Grep), simple single-package definition jump (Grep+Read), BYOK concept Primary (use fast-context), Agent diagnostics (ReadLints), or **replacing IDE Editor LSP** (human surface).
 
-Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, **impact**, and **definition/reference** (replaces unavailable Agent LSP) — not for pure literal search (Grep) or BYOK concept Primary (use fast-context).
+**Re-probe gate:** Before elevating raw LSP to Prefer, verify Agent tool table + `retrieval-daily-guide.md` evidence notes; if external docs add LSP tools but Native probe fails, **keep fallback** and document the gap.
 
 ## External facts
 
-Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md` (see **External-knowledge gate** for search-or-not).
+Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md` (see **External-knowledge gate** for search-or-not).

package/dist/templates/markdown/index.d.ts

@@ -30,4 +30,13 @@ export declare const guidesCursorSemanticComplianceContent: string;
 export declare const guidesCursorSubagentPolicyContent: string;
 export declare const guidesExecutionStrategyContent: string;
 export declare const guidesCursorContextInjectionGuideContent: string;
+export declare const guidesCursorNativeModesGuideContent: string;
+export declare const guidesVerificationStrengthGuideContent: string;
+export declare const guidesInjectionBudgetGuideContent: string;
+export declare const guidesArtifactLocaleGuideContent: string;
+export declare const guidesDebugLoopGuideContent: string;
+export declare const guidesGoalReleaseRegressionRunbookContent: string;
+export declare const guidesPrototypeGuideContent: string;
+export declare const guidesTestDisciplineGuideContent: string;
+export declare const guidesCrossPlatformThinkingGuideContent: string;
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/markdown/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC;AACzE,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,sCAAsC,EAAE,MAEpD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,uCAAuC,EAAE,MACiB,CAAC"}

package/dist/templates/markdown/index.js

@@ -55,4 +55,13 @@ export const guidesCursorSemanticComplianceContent = readLocalTemplate("spec/gui
 export const guidesCursorSubagentPolicyContent = readLocalTemplate("spec/guides/cursor-subagent-policy.md.txt");
 export const guidesExecutionStrategyContent = readLocalTemplate("spec/guides/execution-strategy.md.txt");
 export const guidesCursorContextInjectionGuideContent = readLocalTemplate("spec/guides/cursor-context-injection-guide.md.txt");
+export const guidesCursorNativeModesGuideContent = readLocalTemplate("spec/guides/cursor-native-modes-guide.md.txt");
+export const guidesVerificationStrengthGuideContent = readLocalTemplate("spec/guides/verification-strength-guide.md.txt");
+export const guidesInjectionBudgetGuideContent = readLocalTemplate("spec/guides/injection-budget-guide.md.txt");
+export const guidesArtifactLocaleGuideContent = readLocalTemplate("spec/guides/artifact-locale-guide.md.txt");
+export const guidesDebugLoopGuideContent = readLocalTemplate("spec/guides/debug-loop-guide.md.txt");
+export const guidesGoalReleaseRegressionRunbookContent = readLocalTemplate("spec/guides/goal-release-regression-runbook.md.txt");
+export const guidesPrototypeGuideContent = readLocalTemplate("spec/guides/prototype-guide.md.txt");
+export const guidesTestDisciplineGuideContent = readLocalTemplate("spec/guides/test-discipline-guide.md.txt");
+export const guidesCrossPlatformThinkingGuideContent = readLocalTemplate("spec/guides/cross-platform-thinking-guide.md.txt");
 //# sourceMappingURL=index.js.map

package/dist/templates/markdown/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/markdown/spec/guides/artifact-locale-guide.md.txt

@@ -0,0 +1,93 @@
+# Human-Reviewed Artifact Locale Guide
+
+> **Purpose:** Let PRD / DESIGN / IMPLEMENT / VERIFY / HANDOFF follow the user's language (Chinese or English) without turning Trellis into a full i18n product.
+
+---
+
+## 1. Non-goals
+
+| In scope | Out of scope |
+| --- | --- |
+| Workspace / task `artifact_locale` | Full CLI `--help` / stderr i18n |
+| `task.py create` PRD seed language | Auto-translating archived tasks |
+| Session / planning hints for artifact language | Bilingual mirrors of `workflow.md` or `.cursor/rules` |
+| `prd.md` / `design.md` / `implement.md` / `verify.md` / `handoff.md` | `task.json` field names or gate enums |
+
+**Rollback:** `python ./.cstl/scripts/task.py artifact-locale set zh` or remove `artifact_locale` from `.cstl/config.yaml`. For a single task, delete `task.json` → `meta.artifact_locale`.
+
+---
+
+## 2. Configuration
+
+### Workspace default (`.cstl/config.yaml`)
+
+```yaml
+# Human-reviewed artifact locale (zh | en)
+artifact_locale: zh
+```
+
+Default when unset: **`zh`** (matches current dogfood and User Rules for Simplified Chinese replies).
+
+### CLI
+
+```powershell
+# Resolved locale (workspace default)
+python ./.cstl/scripts/task.py artifact-locale get
+
+# Resolved locale for one task (includes task override)
+python ./.cstl/scripts/task.py artifact-locale get --task .cstl/tasks/<dir>
+
+# Workspace default
+python ./.cstl/scripts/task.py artifact-locale set en
+python ./.cstl/scripts/task.py artifact-locale set zh
+
+# Per-task override
+python ./.cstl/scripts/task.py artifact-locale set zh --task .cstl/tasks/<dir>
+```
+
+Invalid values print a warning and fall back to the next layer (`task` → `workspace` → `zh`).
+
+---
+
+## 3. What respects locale
+
+| Artifact | Mechanism |
+| --- | --- |
+| `prd.md` on `task.py create` | Locale template under `.cstl/tasks/locale/{zh,en}/default-prd.md` |
+| `design.md` / `implement.md` | Agent planning (session context + `cstl-brainstorm`) |
+| `verify.md` / `handoff.md` | Agent execution / finish (same session hint) |
+| Optional `tasks/templates/*` copies | Agent follows guide; English paths stay canonical |
+
+**Does not change:** existing files in a task directory, CLI diagnostics, hooks, or machine gate names.
+
+---
+
+## 4. Dogfood checklist
+
+1. `artifact-locale set en` → `task.py create "Locale EN" --slug locale-dogfood-en` → `prd.md` uses `## Goal`, `## Requirements`.
+2. `artifact-locale set zh` → `task.py create "Locale ZH" --slug locale-dogfood-zh` → `prd.md` uses `## 目标`, `## 需求`.
+3. With workspace `en`, `artifact-locale set zh --task <dir>` → next create for that task only uses Chinese if `meta.artifact_locale` was set before create (override applies to resolved locale for that task).
+
+---
+
+## 5. Orthogonal `locale` settings
+
+| Setting | Purpose |
+| --- | --- |
+| **`artifact_locale`** (this guide) | Human-reviewed task artifacts |
+| Retrieval / semantic `locale` | Code search ranking and plan language |
+| smart-search `locale-scope` | External research evidence language |
+
+Do not merge these keys; they solve different problems.
+
+---
+
+## 6. Rollback
+
+1. `artifact-locale set zh` (workspace).
+2. Remove `meta.artifact_locale` from any task that should follow workspace only.
+3. Revert code/templates if needed — default `zh` keeps dogfood behavior without config.
+
+---
+
+**Core principle:** Product language follows the user for artifacts they review; infrastructure stays English unless explicitly scoped.

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

@@ -40,7 +40,7 @@ print("Run: script.py <args>")
 
 # GOOD - Platform-aware wording
 print("Usage: python on Windows, python3 elsewhere")
-print("Run: {{PYTHON_CMD}} ./.cstl/scripts/task.py <args>")
+print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
 ```
 
 **Rule 2**: When generating config files at init time, use placeholder + platform detection:
@@ -281,7 +281,7 @@ make the intended decision. Otherwise a transient sandbox/network failure hides
 the hint for the rest of the session.
 
 **Rule 2**: If a local command can provide the needed value, try it with a short
-timeout and captured output. For example, `cstl --version` already runs the
+timeout and captured output. For example, `trellis --version` already runs the
 CLI's version comparison logic and can support an actionable update prompt
 without duplicating npm registry parsing.
 
@@ -356,7 +356,7 @@ When making platform-related changes, check **all these locations**:
 
 ### Code Locations
 - [ ] `src/templates/` - Template files for new projects
-- [ ] `.cstl/scripts/` - Project's own scripts (if self-hosting)
+- [ ] `.trellis/scripts/` - Project's own scripts (if self-hosting)
 - [ ] `dist/` - Built output (rebuild after changes)
 
 ### Search Pattern
@@ -530,7 +530,7 @@ subprocess.run(["./script.py"])  # FileNotFoundError
 
 ```
 src/templates/script.py  ← Updated
-.cstl/scripts/script.py  ← Forgot to sync!
+.trellis/scripts/script.py  ← Forgot to sync!
 ```
 
 ### 4. "Python 3 is always python3"
@@ -606,8 +606,8 @@ included with Trellis, verify the whole distribution path:
 - [ ] `pnpm build` copies the asset into `dist/templates/**`.
 - [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
 - [ ] The built binary installs the asset in a fresh temp repository.
-- [ ] `.cstl/.template-hashes.json` tracks the generated asset path.
-- [ ] `cstl update --dry-run` reports `Already up to date!` in that temp
+- [ ] `.trellis/.template-hashes.json` tracks the generated asset path.
+- [ ] `trellis update --dry-run` reports `Already up to date!` in that temp
   repository.
 
 **Why this matters**: docs/changelog text can move independently from the code
@@ -628,7 +628,7 @@ git -C "$tmpdir" init -q
   cd "$tmpdir"
   node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --cursor
   test -f .cursor/skills/<skill>/SKILL.md
-  grep -q '<skill>' .cstl/.template-hashes.json
+  grep -q '<skill>' .trellis/.template-hashes.json
   node /path/to/Trellis/packages/cli/bin/trellis.js update --dry-run
 )
 ```

package/dist/templates/markdown/spec/guides/cursor-context-injection-guide.md.txt

@@ -4,29 +4,29 @@
 
 ---
 
-## The channel matrix (verified 2026-06-19)
+## The channel matrix (verified 2026-08-05, Cursor Native 3.8.x)
 
-Cursor has **four** channels that can put text in front of the model. They are **not** equally reliable:
+Cursor has **several** channels that can put text in front of the model. They are **not** equally reliable:
 
 | Channel | How it loads | Reliable on Cursor? | Trellis content here |
 |---|---|---|---|
-| `.cursor/rules/*.mdc` (`alwaysApply: true`) | Prepended before **every** prompt, independent path | ✅ **Yes** | `cstl-triage.mdc` (Request Triage hard gate) |
-| `beforeSubmitPrompt` hook → `additional_context` | Per user message; router emits `## 代码库检索计划` | ⚠️ **Verify on your Cursor build** (docs list field; forum reports vary) | `inject-retrieval-plan.py` + `retrieval-routing.mdc` enforcement |
-| `AGENTS.md` (repo root + nested) | Read automatically, treated as an always-on rule | ✅ **Yes** | smart-search-first rule, command surface, remote policy (the `<!-- TRELLIS:START -->` block) |
-| `sessionStart` hook → `additional_context` | Hook fires, JSON parsed... **but content never reaches the model's system context** | ❌ **No (confirmed bug)** | workflow.md Phase Index + Task Dashboard + first-reply notice |
+| `.cursor/rules/*.mdc` (`alwaysApply: true`) | Prepended before **every** prompt, independent path | ✅ **Yes** | `cstl-triage.mdc` (Request Triage hard gate), `retrieval-routing.mdc`, `cstl-cursor-modes.mdc` (Prefer native modes) |
+| `AGENTS.md` (repo root + nested) | Read automatically, treated as an always-on rule | ✅ **Yes** | smart-search-first rule, command surface (the `<!-- CSTL:START -->` block) |
+| `sessionStart` hook → `additional_context` | Once per session; delivered via `hooks_context` | ✅ **Yes** (fixed — verified 2026-08-05; was #158452) | Task Dashboard, workflow Phase Index summary, first-reply notice |
+| `beforeSubmitPrompt` hook → `additional_context` | Per user message; router would emit `## 代码库检索计划` | ❌ **No (telemetry-only since 2026-06-24)** | `inject-retrieval-plan.py` logs to `.cstl/.runtime/retrieval-plan-events.log`; **no injection** |
 | `.cstl/workflow.md` (read on demand) | Only if the agent explicitly runs `get_context.py` or reads the file | ⚠️ Depends on agent taking action | Full Request Triage section, Task Ladder, workflow-state breadcrumbs |
-| **`task.py generate-dispatch-prompt` → Task `prompt`** (CLI Layer 2) | Main session runs Trellis script before `Task(...)` | ✅ **Yes (primary for subagent task context on Cursor)** | Full embed: marker, `Selected task:`, prd/jsonl/spec bodies |
+| **`task.py generate-dispatch-prompt` → Task `prompt`** (CLI Layer 2) | Main session runs Trellis script before `Task(...)` | ✅ **Yes (primary for subagent task context on Cursor)** | Full embed: marker, `Selected task:`, prd/jsonl/spec bodies (budgeted — see [injection-budget-guide](./injection-budget-guide.md)) |
 
-**Key takeaway**: anything that must reach the model **every turn without the agent choosing to load it** must live in `.cursor/rules` or `AGENTS.md`. Subagent task context on Cursor uses **CLI Layer 2** before Task dispatch; `preToolUse` hook injection is best-effort only (see forum reports + 2026-06-22 spike). Anything in `workflow.md` that depends on `sessionStart` injection is **invisible to Cursor agents** until the bug is fixed.
+**Key takeaway**: anything that must reach the model **every turn** must live in `.cursor/rules` or `AGENTS.md`. `sessionStart` is reliable for **session-level** orientation (dashboard, workflow summary) but fires only once. Retrieval plans: use **Rules default tool order** or run `route_codebase_retrieval.py --instructions` on demand — do **not** rely on `beforeSubmitPrompt` injection. Subagent task context uses **CLI Layer 2** before Task dispatch.
 
 ---
 
-## The sessionStart bug (why this guide exists)
+## The sessionStart bug (#158452) — history and current status
 
-- **Bug**: Cursor forum #158452 — `sessionStart` hook `additional_context` is executed and JSON-parsed correctly, but the value is **never added to the agent's initial system context**.
-- **Status**: Confirmed by Cursor team (deanrie), internal bug filed, **no ETA** as of 2026-06-19.
-- **Scope**: Affects `sessionStart` and `postToolUse` `additional_context` on Cursor IDE. The `env` field of the same hook **does** work (separate storage path).
-- **Symptom**: hook runs (verifiable via side-channel log), valid JSON emitted, but the agent has zero awareness of the injected text (e.g. won't say a first-reply notice phrase).
+- **Bug**: Cursor forum #158452 — `sessionStart` hook `additional_context` was executed and JSON-parsed correctly, but the value was **not added to the agent's initial system context** (through ~2026-06).
+- **Status (2026-08-05)**: **Fixed** on Cursor Native 3.8.x — first-reply-notice probe passes; `hooks_context` contains full SessionStart payload. Re-verify after major Cursor upgrades.
+- **Historical scope**: Also affected `postToolUse` `additional_context` on some builds. The `env` field of the same hook uses a separate storage path.
+- **Routing implication**: Even with sessionStart working, **per-turn hard gates** (Triage, retrieval policy) stay in `.cursor/rules` — sessionStart fires only once per session.
 
 ### How to diagnose "is sessionStart injection actually reaching the model?"
 
@@ -38,23 +38,39 @@ Cursor has **four** channels that can put text in front of the model. They are *
 
 ## Trellis routing rules on Cursor
 
-Because of the bug, Trellis routes content by reliability on Cursor:
+Trellis routes content by reliability on Cursor:
 
 | Trellis content | Where it lives | Why |
 |---|---|---|
-| **Request Triage hard gate** (classify every turn, emit `[Triage: <Mode>]`) | `.cursor/rules/cstl-triage.mdc` (`alwaysApply: true`) | Must be visible every turn; sessionStart path is broken |
-| **smart-search-first web routing** | `AGENTS.md` (TRELLIS:START block) | AGENTS.md is a reliable always-on channel |
-| **Command surface** (what's user-invocable vs internal skill) | `AGENTS.md` (TRELLIS:START block) | Same |
-| **Workflow phases, Task Ladder, workflow-state breadcrumbs** | `.cstl/workflow.md` | Loaded on demand via `get_context.py` / `cstl-start` / `cstl-continue`; NOT auto-injected on Cursor |
+| **Request Triage hard gate** (classify every turn, emit `[Triage: <Mode>]`) | `.cursor/rules/cstl-triage.mdc` (`alwaysApply: true`) | Must be visible **every turn**; sessionStart is once-per-session |
+| **Codebase retrieval policy** | `.cursor/rules/retrieval-routing.mdc` + `route_codebase_retrieval.py` | `beforeSubmitPrompt` injection is telemetry-only; Rules + router CLI |
+| **Prefer Cursor native modes** (Plan/Ask/Debug/Agent/Multitask × Trellis) | `.cursor/rules/cstl-cursor-modes.mdc` + `cursor-native-modes-guide.md` | P1 orchestration; full table on demand in guide |
+| **smart-search-first web routing** | `AGENTS.md` (CSTL block) | AGENTS.md is a reliable always-on channel |
+| **Command surface** (what's user-invocable vs internal skill) | `AGENTS.md` (CSTL block) | Same |
+| **Session orientation** (dashboard, workflow summary, first-reply notice) | `sessionStart` hook → `additional_context` | Reliable on Cursor 3.8.x+; session-level only |
+| **Workflow phases, Task Ladder, workflow-state breadcrumbs** | `.cstl/workflow.md` + sessionStart summary | Full detail on demand via `get_context.py` / `cstl-continue` |
 
-**If a new "must-always-be-visible" rule is added to Trellis**: ship it as a `.cursor/rules/*.mdc` (Cursor) — do **not** rely on adding it to `workflow.md` and expecting sessionStart to deliver it.
+**If a new "must-always-be-visible" rule is added to Trellis**: ship it as a `.cursor/rules/*.mdc` (Cursor) — do **not** rely on `workflow.md` or sessionStart alone for per-turn enforcement. Run `injection_budget_probe.py` after adding rules (see [injection-budget-guide](./injection-budget-guide.md)).
+
+---
+
+## Injection budget (P0)
+
+Per-channel caps and jsonl/Layer 2 limits are defined in **[injection-budget-guide](./injection-budget-guide.md)**. Summary from channel matrix (2026-08-06):
+
+- **Per-turn:** C01 Rules + C02 AGENTS only (not C04).
+- **Session once:** C03 sessionStart dashboard/workflow.
+- **Subagent:** C06 Layer 2 with role `max_chars` + jsonl entry/file/total caps.
+- **Retrieval:** C16 Rules + router CLI on demand.
+
+Probe: `python ./.cstl/scripts/injection_budget_probe.py --repo-root .`
 
 ---
 
 ## When to update this guide
 
-- Cursor ships a fix for forum #158452 → mark the sessionStart row as "✅ Yes (fixed in version X)" and re-evaluate whether workflow.md content can move back to sessionStart-only.
-- A new Cursor injection channel appears (e.g. a working per-turn `beforeSubmitPrompt.additional_context`) → add a row to the matrix.
+- Cursor major upgrade → re-run sessionStart first-reply-notice probe and update the matrix date.
+- `beforeSubmitPrompt.additional_context` becomes reliable on a future build → re-enable injection in `inject-retrieval-plan.py` and update this guide.
 - Trellis adds a new `.cursor/rules/*.mdc` → add a row to the routing table.
 
 ---
@@ -62,6 +78,7 @@ Because of the bug, Trellis routes content by reliability on Cursor:
 ## Related
 
 - `cursor-subagent-policy.md` — Task tool scenes, model routing (this guide is about **context injection**, that one is about **subagent dispatch**).
+- `cursor-native-modes-guide.md` — Prefer Plan/Ask/Debug/Agent/Multitask; pairs with `cstl-cursor-modes.mdc`.
 - `.cstl/workflow.md` → `### Request Triage` — the full Triage decision tree (the rule in `.cursor/rules/cstl-triage.mdc` is the slim always-apply version pointing here).
 - Task `06-19-cursor-rules-triage` (archive) — the investigation that produced this guide.
 - Cursor forum thread: https://forum.cursor.com/t/sessionstart-hook-additional-context-is-never-injected-into-agents-initial-system-context/158452

package/dist/templates/markdown/spec/guides/cursor-native-modes-guide.md.txt

@@ -0,0 +1,125 @@
+# Cursor native modes — Prefer & orchestrate (don't replace)
+
+> **Purpose**: Task-drive Cursor **Plan / Ask / Debug / Agent / Multitask** into Trellis phases and artifacts. Prefer native when callable; **quietly** fall back to the cstl spine when not. Do **not** reimplement modes or publish an “unsupported mode” list.
+>
+> **Product anchor**: `.cstl/workspace/cursor-trellis-product-positioning.md` (P1).
+>
+> **Design lock**: Parent `research/task-driven-modes-design-lock-2026-08-06.md`.
+>
+> **Evidence**: `{TASK}/research/cursor-modes-external.md`, `{TASK}/research/modes-callability-matrix.md`.
+>
+> **Rollback**: [Rollback](#rollback).
+
+---
+
+## Principle
+
+| Layer | Duty |
+| --- | --- |
+| **Cursor native** | Plan / Ask / Debug / Agent / Multitask — **try task-driven use first** |
+| **cstl spine** | Triage / Phase / gates / artifacts / Parent integration — **quiet fallback** when native cannot be driven well |
+
+**Prefer native. Invent less.** Failures drop to existing cstl paths with little commentary — never a user-facing “本版本不适配某 mode” section.
+
+---
+
+## Prefer / Adapt table (mode × Trellis × artifacts)
+
+| Cursor mode | Prefer when | Task-driven Prefer | Quiet cstl fallback | Durable artifacts |
+| --- | --- | --- | --- | --- |
+| **Ask** | Explain / lookup; **no** durable change | Prefer Ask UI / side chat when the user is already there; Agent cannot `SwitchMode`→Ask | In-session **No Task** behavior (read-only, no `task.py create` without consent) | None |
+| **Plan** | Scope / design / tradeoffs before code | **Try `SwitchMode(plan)`**; after review, `SwitchMode(agent)` or Build; **Save to workspace** → map into task files | Keep writing `prd.md` / `design.md` / `implement.md` + `cstl-brainstorm` in Agent | Phase 1 files |
+| **Agent** | Approved build / verify | Default; `SwitchMode(agent)` when returning from Plan | — | Diff, `verify.md`, gates |
+| **Debug** | Repro / runtime / regressions | Prefer real Cursor Debug when the user/session can reach it | Evidence → `verify.md`; `cstl-break-loop` if looped | Notes / logs in `verify.md` |
+| **Multitask** | Independent Parent children post-approval | Prefer `/multitask` / Build in Parallel / Agent `Task` background workers **when useful** | Explicit `.cstl/tasks/<dir>` prompts + Parent `integrate-child` | Child `verify`/`handoff`; Parent `task-map` |
+
+### Phase quick map
+
+```
+Triage (No Task / Micro-Grill)  → Ask surface if present; else No Task in Agent
+Phase 1                         → SwitchMode(plan) when useful; else write artifacts in Agent
+Phase 2–3                       → Agent (+ workers when contracted)
+Stuck / repeat failure          → Debug when reachable; else verify.md + break-loop
+Parent parallel children        → Multitask / Task parallel when useful; Parent integrates
+```
+
+---
+
+## Mode-specific contracts
+
+### Ask ↔ No Task
+
+- Official Ask does not edit files. Agent tools cannot switch into Ask.
+- Classify **No Task** for pure Q&A; no task creation without consent.
+- Side chats (3.11) complement Ask during Agent runs — still not Trellis artifacts.
+
+### Plan ↔ Phase 1
+
+- Prefer **`SwitchMode(plan)`** for design-heavy Phase 1; care about switch-back quality.
+- Default plan save = **home directory** — **Save to workspace**, then map to `{TASK}/prd.md`, `design.md`, `implement.md`.
+- Does **not** skip `start-execution --check` / execution approval.
+- If Plan switch or save flow is poor: **quietly** author the same files in Agent.
+
+### Debug ↔ evidence
+
+- Prefer Cursor Debug instrumentation when reachable.
+- Always land proof in **`verify.md`**. Contract change → Return-to-Planning.
+
+### Multitask ↔ Parent/Child
+
+1. Trellis remains source of truth for status, gates, integration.
+2. Prefer native parallel surfaces to support independent Children when they help isolation/throughput.
+3. Every worker prompt includes **explicit `.cstl/tasks/<dir>`** — never rely on `selected_task`.
+4. Parent alone `integrate-child`; no collision guarantee without worktrees + review.
+
+---
+
+## Callability (Agent tool table)
+
+| Surface | Plan | Agent | Ask | Debug | Parallel Children |
+| --- | --- | --- | --- | --- | --- |
+| Agent `SwitchMode` | Yes → `plan` | Yes → `agent` | — | — | — |
+| Agent `Task` / Multitask | — | workers | — | — | Prefer when useful |
+| User / CLI modes | Plan UI / `/plan` | default | Ask UI / `/ask` | Debug UI | `/multitask`, Build in Parallel |
+
+Details: `research/modes-callability-matrix.md`.
+
+---
+
+## What cstl must not claim
+
+- Plans auto-save into `.cstl/tasks/`.
+- Multitask inherits `selected_task` or exposes a stable programmatic mode API.
+- Parallel agents cannot conflict without Trellis/worktree discipline.
+- `SwitchMode` can open Ask or Debug.
+- Shipping a parallel fake Plan/Ask/Debug product, or documenting gaps as “本版本不适配”.
+
+---
+
+## Dogfood / probes
+
+| Mode | Minimum probe | Pass when |
+| --- | --- | --- |
+| **Plan** | Schema or live `SwitchMode(plan)` note in verify | Prefer path documented; quiet Agent fallback if unused |
+| **Ask / Debug** | Callability matrix | Quiet spine behavior; no “不适配” section |
+| **Multitask** | Task parallel or doc contract | Explicit child paths; Parent integrates |
+| **Agent** | Session implements under contract | Artifacts on disk |
+
+---
+
+## Rollback
+
+Docs + rules only:
+
+1. Delete `.cursor/rules/cstl-cursor-modes.mdc` and `.cstl/spec/guides/cursor-native-modes-guide.md`.
+2. Drop related `guides/index.md` / `workflow.md` rows, or `cstl update` from pre-P1 templates.
+3. **cursor-trellis**: revert this Child’s tip or delete mirrored template paths.
+
+---
+
+## Related
+
+- `{TASK}/research/modes-callability-matrix.md`
+- `{TASK}/research/cursor-modes-external.md`
+- `.cursor/rules/cstl-cursor-modes.mdc`
+- `.cstl/spec/guides/cursor-subagent-policy.md`

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

@@ -96,19 +96,21 @@ When research is purely **codebase exploration** (no external web search, no fil
 
 ### 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).
+**What it is:** A reversible patch to Cursor++ `extension.js` **subagent model resolver** that maps `subagentType` → BYOK catalog **slug** (`model-xxxxx`), evaluated **before** the inherit-parent branch. Obfuscated symbol names change per build (historical `WPeLc8`; 2026-08+ profile `ZiKp4I`). Script uses multi-profile detection.
 
-**Trellis ships (every `cstl init` / `cstl update`, strategy C):** `.cstl/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, `config.local.json.example`. Native Cursor API users can ignore this directory.
+**Trellis ships (every `cstl init` / `cstl update`, strategy C):** `.cstl/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, **`UPGRADE-NOTE.md`** (upgrade re-apply), `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: **`.cstl/local/subagent-models.json`** (project wins on same key).
+1. Fill **`~/.ccursor/trellis-task-models.json5`** (user-wide) with `subagent_type` → displayName/apiModel from **`~/.ccursor/providers.json`**.
+2. Optionally override per repo: **`.cstl/local/subagent-models.json5`** (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 `.cstl/local/cursor2plus/`: `python patch_wpelc8.py --print-map` → `python patch_wpelc8.py` → **Developer: Reload Window**.
-5. **Verify:** `taskToolCall dispatching` → `resolvedModelId` matches slug.
+4. From `.cstl/local/cursor2plus/`: `python patch_wpelc8.py --check-compat` → `--print-map` → `--apply --approve` → **Developer: Reload Window**.
+5. **Verify:** A≠B probe (parent model ≠ map target) or `resolvedModelId` matches slug.
 
-**Revert:** `python patch_wpelc8.py --revert`; Reload Window. Re-run patch after Cursor / Cursor++ upgrades.
+**Revert:** `python patch_wpelc8.py --revert`; Reload Window.
+
+**After any Cursor / Cursor++ upgrade:** assume patch is stale — follow **`.cstl/local/cursor2plus/UPGRADE-NOTE.md`** (`--check-compat`, re-apply, or add a new resolver profile if symbols moved).
 
 **Cursor++ sidebar / Cursor Settings:** Do **not** wire `cstl-*` BYOK routing; use JSON + patch.
 
@@ -203,7 +205,7 @@ When a dispatch is imminent:
 
 ### 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 `cstl-*`. **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).
+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 `cstl-*`. **Method 2.5** patches Cursor++ subagent model resolver (profile-bound; see `UPGRADE-NOTE.md`) 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).
 
 ---