@blxzer/cursor-trellis 0.1.0 → 0.1.2

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

@@ -12,25 +12,17 @@ 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) or **fast-context** (other platforms) | Cursor: platform-native semantics; others: fast-context MCP |
+| Unknown keywords, semantic discovery | **@codebase** (Cursor) | Cursor's platform-native semantic search |
 | External / current facts | **smart-search-cli** | **Mandatory first** — built-in web tools are downgrade-only (see rule above) |
 | Trellis durable docs | **artifact-search** | `search_artifacts.py` |
 | Past sessions | **session-memory** | Historical; verify against tasks/spec |
-| Intent hint for code questions | **router** | `route_codebase_retrieval.py --platform <name>` — suggests only |
+| Intent hint for code questions | **router** | `route_codebase_retrieval.py` — plan JSON + `agentInstructions`; `--instructions` for steps only |
+| Agent follows plan on Cursor | **`beforeSubmitPrompt` → `inject-retrieval-plan.py`** + **`.cursor/rules/retrieval-routing.mdc`** | Per-turn plan block from router `--instructions`; Rules enforce execution; not `sessionStart` (#158452) |
 | Score collected evidence | **retrieval-pack** | `get_context.py --mode retrieval-pack` — does **not** search |
 
-## Platform differences
+## Semantic routing (Cursor)
 
-The router is platform-adaptive since v2. Different platforms have different built-in capabilities, and the router adjusts its route suggestions accordingly.
-
-| Capability | Cursor | Claude Code / Codex | Generic |
-| --- | --- | --- | --- |
-| Semantic search | Platform-native (`@codebase`) | **fast-context** MCP | **fast-context** MCP |
-| Exact search | Platform-native Grep | rg | rg |
-| Structural search | **codegraph** MCP | **codegraph** MCP | **codegraph** MCP |
-| LSP | Platform-native | N/A | N/A |
-
-**Key implication on Cursor**: Do NOT use `fast-context` for semantic search — Cursor's own `@codebase` and built-in search are higher quality (custom embedding model trained on agent sessions). The router outputs `platform-semantic` routes with `platformNative: true` instead of `semantic-fast-context` on cursor.
+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.
 
 ## Token economy signals
 
@@ -44,16 +36,37 @@ Each route in the router output includes a `tokenEconomy` label:
 
 When `projectFileCount > 2000`, the router promotes structural (codegraph) routes ahead of rg routes for better token efficiency on large codebases.
 
+**Dogfood default (REC-10):** `route_codebase_retrieval.py` and `get_context.py --mode retrieval-pack` default `--project-file-count` to **`auto`** — they count files under the Trellis repo root (`git ls-files` when `.git` exists, else a bounded walk). Override with an integer (e.g. `5000`) for eval fixtures or non-git trees. **Harness note:** `D:\MyHarness` is not a git repo; dogfood from `Trellis/` or pass `--project-file-count` explicitly when routing from the workspace root.
+
 ## Commands
 
 ```powershell
 python ./.trellis/scripts/search_artifacts.py --query "<topic>" --json
 python ./.trellis/scripts/search_memory.py --query "<topic>" --json
 python ./.trellis/scripts/run_smart_search.py "<question>" --intent deep-research --json
-python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --json --platform cursor
+python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --json
+python ./.trellis/scripts/route_codebase_retrieval.py "<question>" --instructions
 python ./.trellis/scripts/get_context.py --mode retrieval-pack --json --input evidence.json
+python ./.trellis/scripts/codegraph_session_smoke.py --json
 ```
 
+## Codegraph session readiness (eval / dogfood)
+
+Before a **cold benchmark** or structural-heavy run:
+
+1. **MCP**: In Cursor project MCP settings, enable the **codegraph** server for the workspace (or eval checkout).
+2. **Index on disk**: Run `python ./.trellis/scripts/codegraph_session_smoke.py` (exit 0 = at least one `.codegraph/` under workspace root or a top-level subproject). Use `--root <eval-checkout>` when the agent root is not the harness.
+3. **Live MCP smoke** (manual): one `codegraph_search` with a known symbol in that repo; stale-index banner → re-read affected files.
+
+Paste into the **run report header** (markdown):
+
+| Field | Example |
+| --- | --- |
+| `codegraph_mcp` | `configured` / `off` / `unknown` |
+| `codegraph_index_path` | from smoke JSON `codegraph_index_paths[0]` |
+| `codegraph_smoke_at` | ISO8601 UTC |
+| `codegraph_smoke_ok` | `true` / `false` |
+
 ## smart-search fallback
 
 When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_configured` / `failed` (including **search timeout**), use **Cursor WebSearch/WebFetch**, then persist to `{TASK}/research/` with `source: cursor-web-fallback` in frontmatter. See `smart-search-cli` skill §4b.
@@ -62,17 +75,33 @@ When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_con
 
 ## Router vs execution
 
-`route_codebase_retrieval.py` returns **intent + route suggestions** only. **codebase-evidence** is **candidate** until confirmed by Read/Git/tests.
+`route_codebase_retrieval.py` returns **intent + route suggestions** and **`agentInstructions`** (numbered steps with Cursor-native tool names). **codebase-evidence** is **candidate** until confirmed by Read/Git/tests.
+
+On **Cursor**, per-query plans come from **`beforeSubmitPrompt` → `inject-retrieval-plan.py`**; durable execution policy lives in **`.cursor/rules/retrieval-routing.mdc`** (`alwaysApply`). Do **not** rely on `sessionStart` hook injection (#158452) or end-of-turn **retrieval-pack** for plans — retrieval-pack **scores** collected evidence; it does not search.
+
+### Result-layer ranking (B / E / D — REC-05)
+
+After Grep/codegraph/semantic produce **path candidates**, reorder before choosing Top-1 / Top-5:
+
+| Intent | Rule |
+| --- | --- |
+| `caller-chain` | Expanded pool first; boost concrete call sites; demote facade/barrel/runtime/registry **assembly-only** files. |
+| `trap-package-disambiguation` | Demote snapshot/registry/`src/agents/` trap paths unless Read confirms the asked layer. |
+| `env-config-literal` | Prefer `scripts/`, `e2e/`, `bench/`, `test/` over generic `src/auth` / `src/paths`. |
+
+- **Agent plans**: `render_agent_instructions` / `inject-retrieval-plan.py` append a **结果层排序** block when these intents appear.
+- **Eval / offline**: `python ./.trellis/scripts/rank_retrieval_candidates.py --candidates fixtures.json --intents caller-chain --top-k 5 --pretty`
+- **Library**: TS `packages/cli/src/utils/retrieval-result-ranking.ts` (Vitest fixtures B03/B05/D03); Python mirror `common/retrieval_result_ranking.py`.
+
+Do **not** claim aggregate openclaw score gains from ranking alone without fresh telemetry (`candidate_pool_recall` vs final Top-K).
 
 ### Structural-first routing (v2)
 
 For structural intents (caller-chain, trap-package-disambiguation, extension-shared-symbol), the router now suggests **codegraph before rg**. This reflects codegraph's superior token economy for structural queries (~80-150 tokens/answer vs rg's ~3557 for naive grep). The agent should still use rg to fill gaps codegraph misses (dynamic dispatch, string-based callsites).
 
-### Semantic routing by platform
+### Semantic routing on Cursor
 
-On **Cursor**: the router outputs `platform-semantic` routes (with `platformNative: true`) instead of `semantic-fast-context`. The agent should use `@codebase` or Cursor's built-in agent search — these are higher quality than fast-context's Devstral model.
-
-On **other platforms**: the router outputs `semantic-fast-context` routes as before. When the envelope fallback mentions no corroborated candidates, invoke `fast_context_search` after exact rg fails.
+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.
 
 ### Semantic dual metrics (openclaw / eval)
 
@@ -81,12 +110,31 @@ On **other platforms**: the router outputs `semantic-fast-context` routes as bef
 | `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`.
+
 Plan-level presence does not imply execution-level use (see parent research `06-19` OQ-1 双轨).
 
+### Execution telemetry (schema v2, eval / openclaw)
+
+Store **one JSON object per query** in JSONL (`schema_version: 2`). Split scores:
+
+| Field | Owner | Meaning |
+| --- | --- | --- |
+| `answer_score` | Human rubric | Top-1 / Recall@5 / answer quality (0–6 per query in main-50) |
+| `compliance_score` | Derived | Plan vs exec layer compliance (0–1); structural/codegraph, semantic, read verify |
+
+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
+```
+
+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`).
+
 ## retrieval-pack
 
 Default `get_context.py --json` returns **retrievalGuide** only. Run `--mode retrieval-pack` after you have collected evidence JSON / smart-search manifests under `{TASK}/research/smart-search/`.
 
 ## Adapters (optimization #9)
 
-Core: rg, task-artifacts, artifact-search, source-git-tests. Enhance: codegraph (structural-first), platform-semantic (Cursor) / fast-context (other), smart-search, session-memory. Placeholders: mcp/browser/network envelope only.
+Core: rg, task-artifacts, artifact-search, source-git-tests. Enhance: codegraph (structural-first), platform-semantic (Cursor `@codebase`), smart-search, session-memory. Placeholders: mcp/browser/network envelope only.

package/dist/templates/shared-hooks/index.d.ts

@@ -11,7 +11,7 @@ export interface HookScript {
     /** Script content — no placeholders, ready to write directly */
     content: string;
 }
-export type SharedHookName = "session-start.py" | "inject-shell-session-context.py" | "inject-workflow-state.py" | "inject-subagent-context.py" | "research-end-retrieval-pack.py";
+export type SharedHookName = "session-start.py" | "inject-shell-session-context.py" | "inject-retrieval-plan.py" | "inject-workflow-state.py" | "inject-subagent-context.py" | "research-end-retrieval-pack.py";
 export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qoder" | "copilot" | "codebuddy" | "droid" | "kiro";
 /**
  * Which shared hooks each platform actually invokes. Single source of truth

package/dist/templates/shared-hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,iCAAiC,GACjC,0BAA0B,GAC1B,4BAA4B,GAC5B,gCAAgC,CAAC;AAErC,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CA+B1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CAGd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,iCAAiC,GACjC,0BAA0B,GAC1B,0BAA0B,GAC1B,4BAA4B,GAC5B,gCAAgC,CAAC;AAErC,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CAgC1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CAGd"}

package/dist/templates/shared-hooks/index.js

@@ -45,6 +45,7 @@ export const SHARED_HOOKS_BY_PLATFORM = {
     cursor: [
         "session-start.py",
         "inject-shell-session-context.py",
+        "inject-retrieval-plan.py",
         "inject-subagent-context.py",
         "research-end-retrieval-pack.py",
     ],

package/dist/templates/shared-hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AA2BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,KAAK,EAAE,CAAC,0BAA0B,CAAC;IACnC,MAAM,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACxD,KAAK,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACvD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,IAAI,EAAE,CAAC,4BAA4B,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,OAAO,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AA4BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,KAAK,EAAE,CAAC,0BAA0B,CAAC;IACnC,MAAM,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACxD,KAAK,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACvD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,IAAI,EAAE,CAAC,4BAA4B,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,OAAO,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/templates/shared-hooks/inject-retrieval-plan.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Cursor beforeSubmitPrompt: inject router-derived ## 代码库检索计划 per user turn.
+
+Runs route_codebase_retrieval + render_agent_instructions for the submitted
+prompt. Complements retrieval-routing.mdc (Rules) with an explicit plan block
+so REC-03 telemetry can set plan_block_in_prompt=true.
+
+Silent exit 0 (no stdout) when:
+  - TRELLIS_HOOKS=0 / not a Trellis repo
+  - prompt is meta-only (continue, slash commands, etc.)
+  - gate says retrieval plan is not needed
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.platform.startswith("win"):
+    import io as _io
+
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(
+                    sys,
+                    _stream_name,
+                    _io.TextIOWrapper(
+                        _stream.detach(), encoding="utf-8", errors="replace"
+                    ),
+                )
+            except Exception:
+                pass
+
+DIR_WORKFLOW = ".trellis"
+PLAN_MARKER_ZH = "## 代码库检索计划"
+PLAN_MARKER_EN = "## Codebase retrieval plan"
+
+
+def _find_trellis_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while True:
+        if (current / DIR_WORKFLOW / "scripts").is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def _detect_platform(input_data: dict[str, Any]) -> str | None:
+    if isinstance(input_data.get("cursor_version"), str):
+        return "cursor"
+    if os.environ.get("CURSOR_PROJECT_DIR"):
+        return "cursor"
+    script_parts = set(Path(sys.argv[0]).parts)
+    if ".cursor" in script_parts:
+        return "cursor"
+    return None
+
+
+def _load_capabilities(root: Path) -> dict[str, object] | None:
+    path = root / DIR_WORKFLOW / "capabilities.json"
+    if not path.is_file():
+        return None
+    try:
+        with path.open(encoding="utf-8") as handle:
+            parsed = json.load(handle)
+        return parsed if isinstance(parsed, dict) else None
+    except Exception:
+        return None
+
+
+def _emit_plan_block(plan_text: str) -> None:
+    payload = {
+        "additional_context": plan_text,
+        "hookSpecificOutput": {
+            "hookEventName": "beforeSubmitPrompt",
+            "additionalContext": plan_text,
+        },
+    }
+    print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+
+def main() -> int:
+    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get(
+        "TRELLIS_DISABLE_HOOKS"
+    ) == "1":
+        return 0
+
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        data = {}
+
+    if not isinstance(data, dict):
+        data = {}
+
+    cwd_str = data.get("cwd") or os.getcwd()
+    root = _find_trellis_root(Path(str(cwd_str)))
+    if root is None:
+        return 0
+
+    scripts_dir = root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common.codebase_retrieval_router import (  # type: ignore[import-not-found]
+            codebase_retrieval_selected_from_capabilities,
+            route_codebase_retrieval,
+        )
+        from common.project_file_stats import (  # type: ignore[import-not-found]
+            resolve_project_file_count_arg,
+        )
+        from common.retrieval_agent_instructions import (  # type: ignore[import-not-found]
+            render_agent_instructions,
+        )
+        from common.retrieval_plan_gate import (  # type: ignore[import-not-found]
+            extract_user_prompt,
+            should_inject_retrieval_plan,
+        )
+    except Exception:
+        return 0
+
+    query = extract_user_prompt(data)
+    if not should_inject_retrieval_plan(query):
+        return 0
+
+    try:
+        project_file_count = resolve_project_file_count_arg("auto", repo_root=root)
+    except ValueError:
+        project_file_count = None
+
+    caps = _load_capabilities(root)
+    selected = codebase_retrieval_selected_from_capabilities(caps)
+    plan = route_codebase_retrieval(
+        query,
+        codebase_retrieval_selected=selected,
+        project_file_count=project_file_count,
+    )
+    instructions = render_agent_instructions(
+        plan,
+        locale="zh",
+    )
+    if PLAN_MARKER_ZH not in instructions and PLAN_MARKER_EN not in instructions:
+        return 0
+
+    _emit_plan_block(instructions)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())