@blxzer/cursor-trellis 0.1.0 → 0.1.2

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

@@ -0,0 +1,57 @@
+---
+description: "Trellis codebase retrieval on Cursor — follow router-derived plans; Rules are the primary injection channel (not sessionStart hooks)"
+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.
+
+## When a retrieval plan block is present
+
+If the user message or Trellis context contains a block starting with `## 代码库检索计划` or `## Codebase retrieval plan`:
+
+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** (or GO_TO_DEFINITION) verification on cited sources.
+
+Generate a fresh plan when needed:
+
+```powershell
+python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --instructions
+```
+
+JSON (includes `agentInstructions`):
+
+```powershell
+python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --json
+```
+
+## Default tool order (no plan block)
+
+| Need | Tool (Cursor) |
+| --- | --- |
+| Exact string / path | **Grep** (Instant Grep) |
+| Who calls / blast radius | **codegraph_callers** → 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 | Cursor **built-in codebase semantic search** (@codebase-class; **not** fast-context MCP) |
+| Policy / architecture / boundaries / storage rules | **Grep** on `AGENTS.md`, `**/AGENTS.md`, `.trellis/spec/**`, `README.md` (router `policy-docs-rg`) before implementation modules |
+| Definition jump | **GO_TO_DEFINITION** / find references **when the host exposes them**; otherwise **Read** + **Grep** on known candidates (LSP is optional, not a guaranteed Agent default) |
+| Wide cross-cutting explore | **DEEP_SEARCH** or Explore subagent, then verify with Grep/codegraph |
+
+## Semantic on Cursor
+
+Router id: `platform-semantic` (`platformNative: true`). Use Cursor **built-in semantic / codebase search**. Do **not** call `fast_context_search` on Cursor.
+
+## Result-layer ranking (B / E / D)
+
+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
+
+Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, and **impact** — not for pure literal search (Grep) or single-hop definition (LSP).
+
+## External facts
+
+Web/current events: **smart-search** first per `.trellis/spec/guides/retrieval-daily-guide.md`.

package/dist/templates/extract.d.ts

@@ -5,20 +5,6 @@ type TemplateCategory = "scripts" | "markdown" | "commands";
 export declare function getTrellisTemplatePath(): string;
 /** @deprecated Use getTrellisTemplatePath() instead. */
 export declare function getTrellisSourcePath(): string;
-/**
- * Get the path to the claude templates directory (hooks, agents, settings).
- */
-export declare function getClaudeTemplatePath(): string;
-/**
- * Get the path to the opencode templates directory (agents, plugins, lib).
- */
-export declare function getOpenCodeTemplatePath(): string;
-/**
- * Get the path to the Pi Agent templates directory (agents, extension, settings).
- */
-export declare function getPiTemplatePath(): string;
-/** @deprecated Use getPiTemplatePath() instead. */
-export declare function getPiSourcePath(): string;
 /**
  * Read a file from the trellis template directory.
  */

package/dist/templates/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/templates/extract.ts"],"names":[],"mappings":"AASA,KAAK,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5D;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAQ/C;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAQ9C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAQhD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAQ1C;AAED,mDAAmD;AACnD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/templates/extract.ts"],"names":[],"mappings":"AASA,KAAK,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5D;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAQ/C;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/templates/extract.js

@@ -19,40 +19,6 @@ export function getTrellisTemplatePath() {
 export function getTrellisSourcePath() {
     return getTrellisTemplatePath();
 }
-/**
- * Get the path to the claude templates directory (hooks, agents, settings).
- */
-export function getClaudeTemplatePath() {
-    const templatePath = path.join(__dirname, "claude");
-    if (fs.existsSync(templatePath)) {
-        return templatePath;
-    }
-    throw new Error("Could not find claude templates directory. Expected at templates/claude/");
-}
-/**
- * Get the path to the opencode templates directory (agents, plugins, lib).
- */
-export function getOpenCodeTemplatePath() {
-    const templatePath = path.join(__dirname, "opencode");
-    if (fs.existsSync(templatePath)) {
-        return templatePath;
-    }
-    throw new Error("Could not find opencode templates directory. Expected at templates/opencode/");
-}
-/**
- * Get the path to the Pi Agent templates directory (agents, extension, settings).
- */
-export function getPiTemplatePath() {
-    const templatePath = path.join(__dirname, "pi");
-    if (fs.existsSync(templatePath)) {
-        return templatePath;
-    }
-    throw new Error("Could not find pi templates directory. Expected at templates/pi/");
-}
-/** @deprecated Use getPiTemplatePath() instead. */
-export function getPiSourcePath() {
-    return getPiTemplatePath();
-}
 /**
  * Read a file from the trellis template directory.
  */

package/dist/templates/extract.js.map

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

package/dist/templates/markdown/agents.md

@@ -10,23 +10,19 @@ This project is managed by Trellis. The working knowledge you need lives under `
 - `.trellis/workspace/` — per-developer journals and session traces
 - `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)
 
-If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
+If a Trellis command is available on Cursor (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps.
 
 ## Command surface (what is user-invocable vs internal)
 
 Only a handful of Trellis entry points are meant for **manual `/` invocation**. Everything else is an **internal auto-triggered skill** — the agent loads it via the skill matcher or workflow routing, not by being called directly. Do **not** manually invoke internal skills through the slash palette.
 
-- **User-invocable (manual)**: `/trellis-continue`, `/trellis-finish-work` (and `/trellis-start` on agent-less platforms).
+- **User-invocable (manual)**: `/trellis-continue`, `/trellis-finish-work` (and `/trellis-start` when needed).
 - **Internal auto-triggered (do NOT call manually)**: `trellis-brainstorm`, `trellis-before-dev`, `trellis-check`, `trellis-break-loop`, `trellis-update-spec`, `trellis-micro-grill`, `trellis-meta`, `trellis-spec-bootstrap`, `trellis-skill-creator`, `smart-search-cli`. These activate on their own when the workflow/skill matcher decides they fit.
 
 ## Web research routing (smart-search first)
 
 For **any external / current / web fact**, use **smart-search** (`run_smart_search.py`) **first**. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`, or native web tools elsewhere) are **downgrade-only fallbacks**, used solely when smart-search is unavailable (`doctor` not ok, status `not_configured` / `failed`, or search timeout). Do not reach for built-in web search while smart-search is healthy. See `.trellis/spec/guides/retrieval-daily-guide.md` and the `smart-search-cli` skill.
 
-If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
-- `.agents/skills/` — reusable Trellis skills
-- `.codex/agents/` — optional custom subagents
-
 Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 
 <!-- TRELLIS:END -->

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

@@ -26,5 +26,6 @@ export declare const guidesCrossLayerThinkingGuideContent: string;
 export declare const guidesCodeReuseThinkingGuideContent: string;
 export declare const guidesDurableLearningDecisionGuideContent: string;
 export declare const guidesRetrievalDailyGuideContent: string;
+export declare const guidesCursorSemanticComplianceContent: string;
 export declare const guidesCursorSubagentPolicyContent: 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,iCAAiC,EAAE,MAE/C,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"}

package/dist/templates/markdown/index.js

@@ -51,5 +51,6 @@ export const guidesCrossLayerThinkingGuideContent = readLocalTemplate("spec/guid
 export const guidesCodeReuseThinkingGuideContent = readLocalTemplate("spec/guides/code-reuse-thinking-guide.md.txt");
 export const guidesDurableLearningDecisionGuideContent = readLocalTemplate("spec/guides/durable-learning-decision-guide.md.txt");
 export const guidesRetrievalDailyGuideContent = readLocalTemplate("spec/guides/retrieval-daily-guide.md.txt");
+export const guidesCursorSemanticComplianceContent = readLocalTemplate("spec/guides/cursor-semantic-compliance.md.txt");
 export const guidesCursorSubagentPolicyContent = readLocalTemplate("spec/guides/cursor-subagent-policy.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/prompts/run-semantic-slice-12.md.txt

@@ -0,0 +1,41 @@
+# REC-06 — 12 题 semantic 切片实验（Cursor）
+
+> 复制 `---BEGIN---` … `---END---` 到 **openclaw-retrieval-eval** 工作区新会话。  
+> 数据：`queries-semantic-slice.jsonl`（S01–S12）。
+
+---BEGIN---
+
+在 **`D:\openclaw-retrieval-eval`** 对 **`queries-semantic-slice.jsonl`** 共 **12 条**做 codebase 检索实验（非全 50 条）。
+
+### 目的
+
+测量 **semantic plan → semantic exec** 裂隙：计划含 `platform-semantic` 时，Agent 是否至少调用 **1 次 Cursor 内置代码库语义搜索**（**不要** fast-context MCP）。
+
+### 约束
+
+1. 代码根：`openclaw/`（pin `092075534e545ab4e0fe7824a3abe7e9784b3df7`）。
+2. 每条只用 JSONL 里 **`query` 原文**；盲测阶段不看 `expected_files`。
+3. 自然遵循 Trellis Rules + hook 注入的检索计划；若计划含 **语义合规** / **platform-semantic** 步骤，**必须执行**一次内置语义再定 Top-1。
+4. 每条记录：**完整 `tools_called` 列表**（Cursor 显示的工具名原样）、是否看到 `## 代码库检索计划`、是否执行内置语义。
+
+### 跑前
+
+```powershell
+python .trellis/scripts/batch_plan_envelope.py --queries queries-semantic-slice.jsonl --pretty
+```
+
+### 产出
+
+1. `runs/cursor-semantic-slice-<YYYYMMDD>.md`：12 条明细 + 工具表。
+2. `runs/cursor-semantic-slice-<YYYYMMDD>/telemetry.jsonl`：每行含 `query_id`、`platform":"cursor"`、`tools_called`、`plan_block_in_prompt`、`semantic_in_plan`（可先 `batch_plan_envelope` 填 plan 字段）。
+3. 汇总：
+
+```powershell
+python .trellis/scripts/aggregate_retrieval_telemetry.py runs/cursor-semantic-slice-<YYYYMMDD>/telemetry.jsonl --markdown
+```
+
+报告须含：`semantic_plan_rate`、`semantic_exec_rate`、`platform_semantic_exec_rate`、`cursor_fast_context_misuse_rate`。
+
+从 **S01** 开始，逐条执行。
+
+---END---

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

@@ -146,29 +146,29 @@ of that replay model.
 
 ## 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.
+**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., a hook event name), 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.
+**Symptom**: New value works partially — some methods return the default branch instead of the new value's specific behavior. No error is raised.
 
 **Example** (`cli_adapter.py`):
 ```python
-# BAD: "gemini" falls through to else, returns "claude"
+# BAD: "on_session_end" falls through to else, returns session-start defaults
 @property
-def cli_name(self) -> str:
-    if self.platform == "opencode":
-        return "opencode"
+def hook_kind(self) -> str:
+    if self.event == "on_session_start":
+        return "session-start"
     else:
-        return "claude"  # gemini silently gets "claude"!
+        return "session-start"  # on_session_end silently gets "session-start"!
 
-# GOOD: explicit branch for every platform
+# GOOD: explicit branch for every value
 @property
-def cli_name(self) -> str:
-    if self.platform == "opencode":
-        return "opencode"
-    elif self.platform == "gemini":
-        return "gemini"
+def hook_kind(self) -> str:
+    if self.event == "on_session_start":
+        return "session-start"
+    elif self.event == "on_session_end":
+        return "session-end"
     else:
-        return "claude"
+        return "session-start"
 ```
 
 **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.

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

@@ -123,18 +123,17 @@ After implementation:
 
 ---
 
-## Cross-Platform Template Consistency
+## Cross-Package Template Consistency
 
-In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
+In Trellis, command templates (e.g., `record-session.md`) exist in **multiple locations** with identical or near-identical content — the published template (`packages/cli/src/templates/cursor/commands/...`) and the dogfooded copy (`.cursor/commands/...`). This is a cross-layer boundary.
 
 ### Checklist: After Modifying Any Command Template
 
-- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
-- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
-- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
+- [ ] Find every copy that owns the same command: `find packages/cli/src/templates -name "<command>.*"` plus the dogfood mirror under `.cursor/commands/`
+- [ ] Update every copy (Markdown `.md` and any TOML sidecar)
 - [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
 
-**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
+**Real-world example**: Updated `record-session.md` in the dogfooded `.cursor/commands/` to use `--mode record`, but forgot to mirror it under `packages/cli/src/templates/cursor/commands/` — caught by cross-layer check.
 
 ---
 
@@ -177,20 +176,9 @@ release line.
 - [ ] Treat beta content appearing under root release paths as a source-path bug,
       not a rendering bug
 
-**Real-world example**: A beta-only task workflow change documented
-`prd.md` + `design.md` + `implement.md`, task-creation consent, and Codex
-mode banners under root `start/` and `advanced/` paths. The docs site then
-served 0.6 beta behavior under the Release selector. The fix was to restore root
-release docs, move the 0.6 content to `beta/` and `zh/beta/`, and add a grep
-audit for beta markers against the root release tree.
-
-**Real-world example**: Codex inline mode changed workflow platform markers from
-`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
-`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
-`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
-markers outside those blocks. Result: upgraded projects got new hook scripts
-but old workflow routing, so `get_context.py --mode phase --platform codex`
-could return empty Phase 2.1 detail.
+**Real-world example**: A beta-only task workflow change documented `prd.md` + `design.md` + `implement.md` and task-creation consent under root `start/` and `advanced/` paths. The docs site then served 0.6 beta behavior under the Release selector. The fix was to restore root release docs, move the 0.6 content to `beta/` and `zh/beta/`, and add a grep audit for beta markers against the root release tree.
+
+**Real-world example**: A workflow-phase marker refactor rewrote `[workflow-state:*]` blocks in `.trellis/workflow.md`. Fresh `init` was correct, but `trellis update` only merged the tagged `[workflow-state:*]` blocks and preserved stale free-text routing between them. Result: upgraded projects got new hook scripts but old workflow routing, so `get_context.py --mode phase` could return empty Phase 2.1 detail. (Historical note: the affected markers used to be platform-tagged when Trellis supported multiple AI platforms; the platform tags were removed when Trellis converged on Cursor-only.)
 
 ---
 

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

@@ -1,6 +1,8 @@
-# Cross-Platform Thinking Guide
+# Cross-Platform Thinking Guide (OS / path)
 
-> **Purpose**: Catch platform-specific assumptions before they become bugs.
+> **Purpose**: Catch OS and path assumptions before they become bugs.
+>
+> **Note (cursor-only fork):** This guide covers **operating-system and filesystem** portability (Windows vs macOS/Linux). AI platform adapter sync is Cursor-only; see `cross-layer-thinking-guide.md` for template consistency.
 
 ---
 
@@ -45,7 +47,7 @@ print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
 
 ```typescript
 // In template file (settings.json):
-{ "command": "{{PYTHON_CMD}} .claude/hooks/script.py" }
+{ "command": "{{PYTHON_CMD}} .cursor/hooks/script.py" }
 
 // In configurator:
 function getPythonCommand(): string {
@@ -85,7 +87,7 @@ function warnIfPythonTooOld(): void {
 }
 ```
 
-**Rule 5**: Don't assume the Python version the AI CLI uses matches your shell's `python3`. The user's terminal may resolve `python3` → homebrew 3.11, but AI CLI hosts (including enterprise-forked Claude Code / Cursor distributions) spawn hook subprocesses with a minimal PATH that resolves `python3` → `/usr/bin/python3` → macOS system 3.9. Distributed templates must either target the lowest plausible version or use `from __future__ import annotations` for PEP 604 syntax. See `cli/backend/script-conventions.md` → **CRITICAL: PEP 604 Annotations Require `from __future__ import annotations`** for the hard rule and audit check.
+**Rule 5**: Don't assume the Python version the AI CLI uses matches your shell's `python3`. The user's terminal may resolve `python3` → homebrew 3.11, but Cursor spawns hook subprocesses with a minimal PATH that resolves `python3` → `/usr/bin/python3` → macOS system 3.9. Distributed templates must either target the lowest plausible version or use `from __future__ import annotations` for PEP 604 syntax. See `cli/backend/script-conventions.md` → **CRITICAL: PEP 604 Annotations Require `from __future__ import annotations`** for the hard rule and audit check.
 
 **Rule 6**: When calling Python from Python, use `sys.executable`:
 
@@ -137,7 +139,7 @@ A path string has two distinct roles. **Treat them differently.**
 function collectTemplates(): Map<string, string> {
   const files = new Map<string, string>();
   for (const entry of walk(dir)) {
-    files.set(path.join(".opencode", entry), readFile(entry));  // \ on Windows
+    files.set(path.join(".cursor", entry), readFile(entry));  // \ on Windows
   }
   return files;
 }
@@ -148,7 +150,7 @@ import { toPosix } from "../utils/posix.js";
 function collectTemplates(): Map<string, string> {
   const files = new Map<string, string>();
   for (const entry of walk(dir)) {
-    files.set(toPosix(path.join(".opencode", entry)), readFile(entry));
+    files.set(toPosix(path.join(".cursor", entry)), readFile(entry));
   }
   return files;
 }
@@ -340,10 +342,10 @@ result = subprocess.run(
 When making platform-related changes, check **all these locations**:
 
 ### Commands / Skills Sync
-- [ ] New command/skill added to ALL platforms (claude, cursor, iflow, codex, and any new platform)
-- [ ] Each platform's test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
-- [ ] Platform-integration spec's required command table updated if adding a new required command
-- [ ] Command format matches platform convention (see `platform-integration.md` → Command Format by Platform)
+- [ ] New command/skill added to the Cursor templates (`src/templates/cursor/` and `src/templates/common/`)
+- [ ] Cursor test file updated with new entry in `EXPECTED_COMMAND_NAMES` / `EXPECTED_SKILL_NAMES`
+- [ ] Command format matches Cursor convention (see `platform-integration.md` → Command Format)
+- [ ] If the command exists in the dogfooded copy (`.cursor/`), sync it too
 
 ### Documentation & Help Text
 - [ ] Docstrings at top of Python files
@@ -388,7 +390,7 @@ Before committing cross-platform code:
 
 ### 7. External Tool API Contracts
 
-When integrating with external tools (Claude Code, Cursor, etc.), their API contracts are **implicit assumptions**.
+When integrating with external tools (Cursor, etc.), their API contracts are **implicit assumptions**.
 
 **Rule**: Verify API formats from official documentation, don't guess.
 
@@ -624,9 +626,8 @@ printf '{"name":"trellis-smoke","version":"0.0.0"}\n' > "$tmpdir/package.json"
 git -C "$tmpdir" init -q
 (
   cd "$tmpdir"
-  node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --claude --codex
-  test -f .claude/skills/<skill>/SKILL.md
-  test -f .agents/skills/<skill>/SKILL.md
+  node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --cursor
+  test -f .cursor/skills/<skill>/SKILL.md
   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

@@ -11,11 +11,13 @@ Cursor has **four** channels that can put text in front of the model. They are *
 | Channel | How it loads | Reliable on Cursor? | Trellis content here |
 |---|---|---|---|
 | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Prepended before **every** prompt, independent path | ✅ **Yes** | `trellis-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 |
 | `.trellis/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 |
 
-**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`. 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 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.
 
 ---
 
@@ -23,7 +25,7 @@ Cursor has **four** channels that can put text in front of the model. They are *
 
 - **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). Claude Code / OpenCode `sessionStart.additionalContext` is unaffected.
+- **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).
 
 ### How to diagnose "is sessionStart injection actually reaching the model?"

package/dist/templates/markdown/spec/guides/cursor-semantic-compliance.md.txt

@@ -0,0 +1,49 @@
+# Cursor semantic compliance (REC-06)
+
+## Plan vs exec
+
+| Layer | What counts |
+| --- | --- |
+| **Plan** | Router route `platform-semantic` (`platformNative: true`) or injected plan step「内置代码库语义搜索」 |
+| **Exec (Cursor)** | Tool log matches **platform semantic** patterns only — see `retrieval_tool_classification` |
+| **Not semantic exec on Cursor** | `fast_context_search`, pure Grep/Read/codegraph |
+
+## Classifying tool names from session logs
+
+Use the same patterns as telemetry:
+
+```powershell
+python -c "from common.retrieval_tool_classification import classify_tool_calls; print(classify_tool_calls(['Grep','codebase_search'], platform='cursor'))"
+```
+
+(Run from `.trellis/scripts` with `PYTHONPATH` set to that directory.)
+
+On **cursor**, `semantic_executed` = `platform_semantic_executed`. Track `fast_context_count` and `cursor_fast_context_misuse` separately.
+
+## Plan-only metrics (eval)
+
+```powershell
+python .trellis/scripts/batch_plan_envelope.py --queries queries-semantic-slice.jsonl --pretty
+```
+
+Do **not** use legacy `scripts/batch-plan-envelope.py` (looks for `semantic-fast-context` on all platforms).
+
+## 12-query slice experiment
+
+Prompt: `prompts/run-semantic-slice-12.md` in openclaw-retrieval-eval (or Trellis template copy).
+
+Record per query:
+
+- `plan_block_in_prompt` (visible `## 代码库检索计划` + 语义合规 block)
+- `tools_called` verbatim from Cursor
+- `platform_semantic_executed` / `fast_context_count` from classifier
+
+Aggregate:
+
+```powershell
+python .trellis/scripts/aggregate_retrieval_telemetry.py runs/<run>/telemetry.jsonl --markdown
+```
+
+## Agent instructions
+
+When `platform-semantic` is in the route list, `render_agent_instructions` appends **语义合规（Cursor）** requiring one built-in semantic search before Top-1 and logging the host tool name.

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

@@ -19,7 +19,8 @@ How did I reach trellis-research / trellis-implement / trellis-check?
 │
 ├─ 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).
+│    Context: CLI Layer 2 pre-embed (primary on Cursor); hook is best-effort
+│    (<!-- trellis-hook-injected --> marker; skips if already present).
 │
 └─ Used the trellis-check SKILL in main session (no subagent spawn)
    → Skill form. Main-session model. Only trellis-check has both
@@ -35,8 +36,8 @@ If unsure: Task dispatch is the path Trellis workflow routes through; Agent sess
 | 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                   |
+| Implementation (after `start-execution --approved`) | `ttrellis-implement`                                            | Agent                               | Code edits; no `git commit` in subagent; **CLI Layer 2** dispatch prompt on Cursor |
+| Post-implementation verification                    | `ttrellis-check`                                                | Agent                               | Fixes + `verify.md` / gate hints; **CLI Layer 2** on Cursor; main session records gates |
 | 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                                                     |
@@ -288,13 +289,13 @@ trellis_task_subagents:
 | `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.
+**Per-turn workflow-state on Cursor:** deferred — use `sessionStart` + `/trellis-continue` / `get_context.py --mode phase` instead of a per-turn hook injection (the relevant Cursor channel has a confirmed `additional_context` bug, see `cursor-context-injection-guide.md`).
 
 ---
 
 ## Parent/Child alignment
 
-- `generate-child-prompt --mode subagent` → Parent **Task** `trellis-implement` by default; inline mode remains the portable default for non-Cursor platforms.
+- `generate-child-prompt --mode subagent` → Parent **Task** `trellis-implement` by default; inline mode is the portable default when dispatching without spawning a subagent.
 - 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`.
 
@@ -309,6 +310,18 @@ trellis_task_subagents:
 
 ---
 
+## Maintainer: subagent missing task context (Cursor)
+
+If a dispatched subagent cannot answer from `prd.md` / jsonl (empty or generic replies):
+
+1. Confirm the main session used **CLI Layer 2** before `Task(...)` (workflow Phase 2.1 / 2.2).
+2. **Manual fallback (Method 3):** run `python ./.trellis/scripts/task.py generate-dispatch-prompt <task-dir> <role> [--scope "..."]`, paste stdout into `Task(subagent_type=..., prompt=...)`.
+3. Hook-only injection is best-effort on Cursor; do not treat `preToolUse` as the sole source.
+
+This command is **Agent-facing** — not listed in user README or slash command surface.
+
+---
+
 ## 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.