@blxzer/cursor-trellis 0.1.1 → 0.1.3

package/README.md

@@ -40,6 +40,8 @@ trellis init --cursor
 
 Optional: `trellis init --cursor --cursor2plus` for Cursor++ BYOK local bundle; see [docs/cursor.md](docs/cursor.md#cursor-optional-appendix).
 
+**Codebase retrieval (optional):** add `--capability codebase-retrieval` (or select it in the init prompt) to generate `.cursor/mcp.json` entries for **fast-context** and **codegraph**. Recommended for **Cursor++ BYOK** local concept search (`fast_context_search`); not required if you only need other capabilities (e.g. playwright).
+
 ## After init: what appears
 
 ```text

package/dist/migrations/manifests/0.1.1.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1.1",
+  "description": "v0.1.1 — Cursor-only platform reduction. Trellis templates, CLI init/update/uninstall, retrieval router, and docs converge on Cursor as the sole managed platform.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Cursor-only product trim.**\n\n- refactor(cli): platform registry, init, uninstall/update, and template dirs reduced to Cursor-only (S1–S11).\n- refactor(retrieval): drop `--platform` / non-Cursor dead branches from codebase retrieval planner (R12).\n- refactor(core): remove mem module export (R13).\n- docs/spec: workflow, AGENTS, README, and guides aligned to cursor-only surface.\n\nRun `trellis update` in each project to sync templates and scripts.",
+  "migrations": [],
+  "notes": "Backfilled manifest for npm 0.1.1 (published without local manifest). No automated migrations; template sync via `trellis update`."
+}

package/dist/migrations/manifests/0.1.2.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1.2",
+  "description": "v0.1.2 — Agent dispatch context assembly: `generate-dispatch-prompt` CLI (Layer 2) plus shared subagent_dispatch builder and slim preToolUse hook.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Subagent dispatch Layer 2 (Agent-facing).**\n\n- feat(cli): `task.py generate-dispatch-prompt <task-dir> <role>` assembles full Task prompts (marker, Selected task, prd/jsonl/spec embed).\n- refactor(scripts): `common/subagent_dispatch.py` single builder; hook is thin wrapper with marker dedup.\n- docs: workflow Phase 2.1/2.2 orchestrator contract; cursor-context-injection-guide + cursor-subagent-policy Layer 2 rows.\n\nFull/Parent implement/check on Cursor: main session should run dispatch CLI before `Task(trellis-*)`. Hook remains best-effort.",
+  "migrations": [],
+  "notes": "No user README changes. Run `trellis update` in each project to sync `.trellis/scripts` and hooks."
+}

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

@@ -13,7 +13,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** (or GO_TO_DEFINITION) verification on cited sources.
+3. Finish with **Read** verification on cited sources (definition jumps use **codegraph_node**, not LSP).
 
 Generate a fresh plan when needed:
 
@@ -35,14 +35,16 @@ python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --json
 | 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) |
+| 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`, `.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 |
+| 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
+## Semantic on Cursor (`platform-semantic`)
 
-Router id: `platform-semantic` (`platformNative: true`). Use Cursor **built-in semantic / codebase search**. Do **not** call `fast_context_search` on Cursor.
+- **cursorEnv native:** built-in codebase semantic search (`platformNative`). Do **not** use fast-context MCP for semantic Primary.
+- **cursorEnv byok:** **fast-context MCP** is **required** for concept retrieval; built-in `@codebase` is not available in the agent tool list.
+- Override detection: `TRELLIS_CURSOR_BYOK=0|1` or `~/.ccursor/routes.json` `byokMode`.
 
 ## Result-layer ranking (B / E / D)
 
@@ -50,7 +52,7 @@ When the plan block includes **结果层排序**, apply it **after** collecting
 
 ## 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).
+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).
 
 ## External facts
 

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

@@ -15,8 +15,9 @@ Cursor has **four** channels that can put text in front of the model. They are *
 | `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.
 
 ---
 

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                                                     |
@@ -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.

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

@@ -12,7 +12,7 @@ For **external / current / web facts**, **smart-search** (`run_smart_search.py`)
 | --- | --- | --- |
 | 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) | Cursor's platform-native semantic search |
+| Unknown keywords, semantic discovery | **@codebase** (Cursor Native) / **fast-context** (Cursor++ BYOK) | Native: built-in semantic; BYOK: `fast_context_search` MCP (see `cursorEnv` in plans) |
 | 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 |
@@ -22,7 +22,12 @@ For **external / current / web facts**, **smart-search** (`run_smart_search.py`)
 
 ## Semantic routing (Cursor)
 
-The retrieval planner routes semantic intents to **built-in `@codebase` and agent semantic search**. Do **not** use the third-party `fast-context` MCP on Cursor.
+The planner emits **`platform-semantic`** with backend chosen by **`cursorEnv`** (`native` | `byok` from `~/.ccursor/routes.json` or `TRELLIS_CURSOR_BYOK`):
+
+- **native:** built-in `@codebase` / agent semantic search — **do not** use fast-context as Primary.
+- **byok:** **fast-context MCP** (`fast_context_search`) — built-in semantic is not in the agent tool list.
+
+Definition / reference jumps: **codegraph** (not GO_TO_DEFINITION; Agent LSP unavailable).
 
 ## Token economy signals
 
@@ -99,9 +104,9 @@ Do **not** claim aggregate openclaw score gains from ranking alone without fresh
 
 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 on Cursor
+### Semantic routing on Cursor (plans)
 
-On Cursor, the router outputs `platform-semantic` routes (with `platformNative: true`). The agent should use `@codebase` or Cursor's built-in agent search — `fast_context_search` calls are tracked as **misuse** in eval telemetry.
+Envelopes include **`cursorEnv`**. `platform-semantic` uses **`platformNative: true`** on native and **`semanticBackend: fast-context-mcp`** on BYOK. Native: `@codebase` / built-in search; BYOK: `fast_context_search`.
 
 ### Semantic dual metrics (openclaw / eval)
 
@@ -110,7 +115,7 @@ On Cursor, the router outputs `platform-semantic` routes (with `platformNative:
 | `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 |
 
-On **Cursor**, `semantic_exec_rate` uses **platform-native** tool names only (`classify_tool_calls(..., platform=cursor)`); `fast_context_search` is tracked as **misuse**, not semantic exec. See `cursor-semantic-compliance.md`.
+On **Cursor**, `semantic_exec_rate` uses `classify_tool_calls(..., platform=cursor, cursor_env=...)`: **native** counts built-in semantic only; **byok** counts `fast_context_search` as semantic exec. `cursor_fast_context_misuse` applies only when **native** (or non-byok) uses fast-context while the plan has `platform-semantic`. See `cursor-semantic-compliance.md`.
 
 Plan-level presence does not imply execution-level use (see parent research `06-19` OQ-1 双轨).
 
@@ -126,7 +131,7 @@ Store **one JSON object per query** in JSONL (`schema_version: 2`). Split scores
 Report **summary rates must not be hand-copied** from batch router envelopes. Aggregate from JSONL:
 
 ```powershell
-python .trellis/scripts/aggregate_retrieval_telemetry.py runs/<run>/telemetry.jsonl --markdown
+python ./.trellis/scripts/aggregate_retrieval_telemetry.py runs/<run>/telemetry.jsonl --markdown
 ```
 
 Key exec fields (fill from session tool log): `tools_called`, `grep_count`, `read_count`, `codegraph_executed`, `semantic_executed`, `router_cli_invoked`, `plan_block_in_prompt`, `read_verification_done`. TypeScript contract: `packages/cli/src/utils/retrieval-execution-telemetry.ts` (`RETRIEVAL_TELEMETRY_FIELD_OWNERSHIP`).