@blxzer/cursor-trellis 0.1.2 → 0.2.1

package/dist/templates/trellis/scripts/common/codebase_retrieval_router.py

@@ -2,8 +2,8 @@
 """
 Deterministic codebase retrieval intent router (Python template).
 
-Mirrors packages/cli/src/utils/codebase-retrieval-router.ts for dogfood and
-get_context retrieval-pack flows. Does not invoke rg, MCP, or network tools.
+Shared contract with the Trellis CLI router; used by hooks, route_codebase_retrieval.py,
+and get_context retrieval-pack flows. Does not invoke rg, MCP, or network tools.
 """
 
 from __future__ import annotations
@@ -13,6 +13,12 @@ import re
 from pathlib import Path
 from typing import Any
 
+from .cursor_retrieval_env import (
+    ENV_BYOK,
+    detect_cursor_retrieval_env,
+    semantic_route_spec,
+)
+
 ROUTER_VERSION = 2
 
 PLATFORM_CURSOR = "cursor"
@@ -439,11 +445,32 @@ def _large_project(project_file_count: int | None) -> bool:
     return project_file_count > 2000
 
 
+def _platform_semantic_route(
+    *,
+    base_rationale: str,
+    cursor_env: str,
+) -> dict[str, object]:
+    spec = semantic_route_spec(cursor_env)
+    suffix = str(spec.get("rationale_suffix", ""))
+    commands = spec.get("commands")
+    cmd_list = list(commands) if isinstance(commands, list) else []
+    return {
+        "id": "platform-semantic",
+        "role": "semantic",
+        "sourceFamily": "platform-semantic",
+        "commands": cmd_list,
+        "rationale": base_rationale + suffix,
+        "platformNative": bool(spec.get("platformNative", False)),
+        "semanticBackend": spec.get("semanticBackend"),
+    }
+
+
 def _ordered_routes(
     intents: list[dict[str, object]],
     include_optional_adapters: bool,
     *,
     project_file_count: int | None = None,
+    cursor_env: str | None = None,
 ) -> list[dict[str, object]]:
     ids = {str(item["id"]) for item in intents}
     active = list(ids)
@@ -459,6 +486,7 @@ def _ordered_routes(
     conceptual_primary = conceptual and not preserve and not exact_primary_first
     large = _large_project(project_file_count)
     semantic_promoted = False
+    cenv = cursor_env or detect_cursor_retrieval_env()
 
     routes: list[dict[str, object]] = []
 
@@ -542,14 +570,7 @@ def _ordered_routes(
             if policy
             else "Conceptual query without exact signals; semantic recall before exact rg narrowing."
         )
-        append({
-            "id": "platform-semantic",
-            "role": "semantic",
-            "sourceFamily": "platform-semantic",
-            "commands": ["cursor @codebase or built-in semantic search"],
-            "rationale": semantic_rationale + " (Cursor built-in semantic search)",
-            "platformNative": True,
-        })
+        append(_platform_semantic_route(base_rationale=semantic_rationale, cursor_env=cenv))
         semantic_promoted = True
         append({
             "id": "exact-rg-primary",
@@ -638,24 +659,25 @@ def _ordered_routes(
             })
         append({
             "id": "lsp-navigation",
-            "role": "lsp",
-            "sourceFamily": "language-server",
-            "commands": ["definition", "references", "hover"],
+            "role": "ast",
+            "sourceFamily": "codegraph",
+            "commands": [
+                "codegraph_node <symbol> --includeCode",
+                "codegraph_search <symbol>",
+            ],
             "rationale": (
-                "Optional editor/LSP navigation when exposed; "
-                "not guaranteed in Agent tool telemetry — prefer Read/Grep/codegraph after candidates exist."
+                "Definition/reference via codegraph (Cursor Agent does not expose "
+                "GO_TO_DEFINITION); corroborate with Read on returned line ranges."
             ),
-            "platformNative": True,
+            "platformNative": False,
         })
         if not semantic_promoted:
-            append({
-                "id": "platform-semantic",
-                "role": "semantic",
-                "sourceFamily": "platform-semantic",
-                "commands": ["cursor @codebase or built-in semantic search"],
-                "rationale": "Semantic recall via Cursor built-in codebase search.",
-                "platformNative": True,
-            })
+            append(
+                _platform_semantic_route(
+                    base_rationale="Semantic recall for conceptual narrowing.",
+                    cursor_env=cenv,
+                )
+            )
 
     append({
         "id": "verification-source-git-tests",
@@ -678,6 +700,8 @@ def _fallback_hints(
     intents: list[dict[str, object]],
     include_optional_adapters: bool,
     routes: list[dict[str, object]],
+    *,
+    cursor_env: str | None = None,
 ) -> list[dict[str, object]]:
     hints: list[dict[str, object]] = [
         {
@@ -688,7 +712,22 @@ def _fallback_hints(
     if not include_optional_adapters:
         hints.append({
             "when": "codebase-retrieval not selected",
-            "action": "Skip optional AST/LSP/semantic routes; use exact search and verification.",
+            "action": "Skip optional AST/semantic routes; use exact search and verification.",
+            "replacesRole": "semantic",
+        })
+    cenv = cursor_env or detect_cursor_retrieval_env()
+    if cenv == ENV_BYOK:
+        hints.append({
+            "when": "built-in @codebase / SemanticSearch not in agent tool list",
+            "action": (
+                "Use fast_context_search (fast-context MCP) per platform-semantic route; "
+                "do not use WebSearch for codebase questions."
+            ),
+            "replacesRole": "semantic",
+        })
+        hints.append({
+            "when": "DEEP_SEARCH not available for wide cross-cutting explore",
+            "action": "Use Task subagent (explore), then Grep/codegraph/Read to verify.",
             "replacesRole": "semantic",
         })
     if any(str(item["id"]) == INTENT_POLICY for item in intents):
@@ -716,8 +755,8 @@ def _fallback_hints(
                 "(or only trap hits) before final Top-1"
             ),
             "action": (
-                "Use Cursor @codebase or built-in semantic search per platform-semantic route, "
-                "then narrow with rg on returned keywords and paths."
+                "Use fast_context_search (BYOK) or Cursor built-in semantic search (Native) "
+                "per platform-semantic route, then narrow with rg on returned keywords and paths."
             ),
             "replacesRole": "semantic",
         })
@@ -754,26 +793,33 @@ def route_codebase_retrieval(
     *,
     codebase_retrieval_selected: bool = True,
     project_file_count: int | None = None,
+    cursor_env: str | None = None,
 ) -> dict[str, object]:
     """Return the shared evidence envelope with router-owned fields populated."""
     normalized = _normalize_query(query)
     include_optional = codebase_retrieval_selected
+    cenv = cursor_env or detect_cursor_retrieval_env()
     if not normalized:
         intents = [
             _intent(INTENT_EXACT, "General codebase (exact baseline)", ["empty-query"], "low", True)
         ]
         empty_routes = _ordered_routes(
-            intents, include_optional,
+            intents,
+            include_optional,
             project_file_count=project_file_count,
+            cursor_env=cenv,
         )
         return {
             "version": ROUTER_VERSION,
             "query": normalized,
+            "cursorEnv": cenv,
             "intents": intents,
             "routes": empty_routes,
             "adapterState": [],
             "freshness": [],
-            "fallback": _fallback_hints(intents, include_optional, empty_routes),
+            "fallback": _fallback_hints(
+                intents, include_optional, empty_routes, cursor_env=cenv
+            ),
             "warnings": ["Empty query; only baseline exact route is emitted."],
             "verification": _base_verification(),
             "projectFileCount": project_file_count,
@@ -781,17 +827,20 @@ def route_codebase_retrieval(
 
     intents = _classify_intents(normalized)
     routes = _ordered_routes(
-        intents, include_optional,
+        intents,
+        include_optional,
         project_file_count=project_file_count,
+        cursor_env=cenv,
     )
     return {
         "version": ROUTER_VERSION,
         "query": normalized,
+        "cursorEnv": cenv,
         "intents": intents,
         "routes": routes,
         "adapterState": [],
         "freshness": [],
-        "fallback": _fallback_hints(intents, include_optional, routes),
+        "fallback": _fallback_hints(intents, include_optional, routes, cursor_env=cenv),
         "warnings": _warnings(intents),
         "verification": _verification_for_intents(intents),
         "projectFileCount": project_file_count,

package/dist/templates/trellis/scripts/common/config.py

@@ -289,7 +289,7 @@ def get_packages(repo_root: Path | None = None) -> dict[str, dict] | None:
         or None if not configured (single-repo mode).
 
     Example return:
-        {"cli": {"path": "packages/cli"}, "docs-site": {"path": "docs-site", "type": "submodule"}}
+        {"api": {"path": "packages/api"}, "web": {"path": "packages/web"}}
     """
     config = _load_config(repo_root)
     packages = config.get("packages")

package/dist/templates/trellis/scripts/common/cursor_retrieval_env.py

@@ -0,0 +1,92 @@
+"""Detect Cursor Native vs Cursor++ BYOK for retrieval routing."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+ENV_NATIVE = "native"
+ENV_BYOK = "byok"
+ENV_UNKNOWN = "unknown"
+
+CursorRetrievalEnv = str  # native | byok | unknown
+
+
+def ccursor_home() -> Path:
+    env = os.environ.get("TRELLIS_CCURSOR_HOME", "").strip()
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".ccursor"
+
+
+def detect_cursor_retrieval_env() -> CursorRetrievalEnv:
+    """Return native | byok | unknown.
+
+    Override: TRELLIS_CURSOR_BYOK=1|0
+    """
+    info = detect_cursor_retrieval_env_info()
+    env = info.get("env")
+    if env in (ENV_NATIVE, ENV_BYOK, ENV_UNKNOWN):
+        return str(env)
+    return ENV_UNKNOWN
+
+
+def detect_cursor_retrieval_env_info() -> dict[str, Any]:
+    """Full detection record (for probes and envelopes)."""
+    env_override = os.environ.get("TRELLIS_CURSOR_BYOK", "").strip()
+    if env_override == "1":
+        return {"env": ENV_BYOK, "source": "env-override", "byokMode": 1}
+    if env_override == "0":
+        return {"env": ENV_NATIVE, "source": "env-override", "byokMode": 0}
+
+    routes_path = ccursor_home() / "routes.json"
+    if not routes_path.is_file():
+        return {
+            "env": ENV_UNKNOWN,
+            "source": "routes-not-found",
+            "byokMode": None,
+            "routes_path": str(routes_path),
+        }
+    try:
+        routes = json.loads(routes_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "env": ENV_UNKNOWN,
+            "source": "routes-parse-error",
+            "byokMode": None,
+            "error": str(exc),
+            "routes_path": str(routes_path),
+        }
+    byok = routes.get("byokMode")
+    env = ENV_BYOK if byok == 1 else ENV_NATIVE if byok == 0 else ENV_UNKNOWN
+    redirect = routes.get("redirect", [])
+    return {
+        "env": env,
+        "source": "routes.json",
+        "byokMode": byok,
+        "routes_path": str(routes_path),
+        "redirect_endpoints": list(redirect) if isinstance(redirect, list) else [],
+    }
+
+
+def is_byok(env: CursorRetrievalEnv | None = None) -> bool:
+    return (env or detect_cursor_retrieval_env()) == ENV_BYOK
+
+
+def semantic_route_spec(cursor_env: CursorRetrievalEnv) -> dict[str, object]:
+    """platform-semantic route fields for conceptual / optional semantic slots."""
+    if cursor_env == ENV_BYOK:
+        return {
+            "commands": ["fast_context_search (fast-context MCP)"],
+            "rationale_suffix": " Cursor++ BYOK: built-in semantic unavailable; fast-context MCP primary.",
+            "platformNative": False,
+            "semanticBackend": "fast-context-mcp",
+        }
+    return {
+        "commands": ["cursor @codebase or built-in semantic search"],
+        "rationale_suffix": " Cursor built-in semantic search.",
+        "platformNative": True,
+        "semanticBackend": "cursor-builtin",
+    }

package/dist/templates/trellis/scripts/common/parent_orchestration.py

@@ -16,6 +16,7 @@ from .paths import get_repo_root
 from .task_gates import (
     build_spec_update_scaffold,
     durable_learning_decision_status,
+    task_closeout_profile,
 )
 from .task_map import (
     PARENT_TERMINAL_STATES,
@@ -31,7 +32,6 @@ _GLOBAL_CHILD_CONSTRAINTS = """General constraints:
 - Stay inside your child scope and declared touch areas.
 - Do not publish packages, push remotes, create tags, edit credentials, or change global/MCP configuration.
 - Preserve explicit user approval for destructive, remote, credential-bearing, publish, push, tag, and global configuration actions.
-- Keep template and dogfood copies synchronized when touching `.trellis/scripts` or Trellis CLI templates.
 - Write `verify.md` and `handoff.md` in your child task directory.
 - Handoff must include changed files, validation commands/results, residual risks, and parent integration notes.
 - If you find a needed contract change, stop and report it to the parent instead of silently redefining shared state/gate semantics.
@@ -530,18 +530,29 @@ def build_review_report(
                     ),
                 }
             )
-            actions["gates"].append(
-                {
-                    "task": "child",
-                    "transition": "child-review",
-                    "optional": True,
-                    "hint": (
-                        f"python ./.trellis/scripts/task.py record-gate {child_name} "
-                        f"--transition child-review --gate code-review --result PASS "
-                        f"--reviewer parent --evidence verify.md"
-                    ),
-                }
-            )
+            child_profile = task_closeout_profile(child_dir, child_data)
+            if child_profile == "full":
+                actions["gates"].append(
+                    {
+                        "task": "child",
+                        "transition": "child-review",
+                        "optional": False,
+                        "hint": (
+                            f"Required before accept: python ./.trellis/scripts/task.py record-gate {child_name} "
+                            f"--transition child-review --gate code-review --result PASS "
+                            f"--reviewer parent --evidence verify.md"
+                        ),
+                    }
+                )
+            elif child_profile == "lite":
+                actions["gates"].append(
+                    {
+                        "task": "child",
+                        "transition": "child-review",
+                        "optional": True,
+                        "hint": "Lite child: no child-review gate chain required.",
+                    }
+                )
         elif decision == "changes":
             target = "changes"
             errors.extend(
@@ -611,6 +622,7 @@ def build_review_report(
                 evidence,
                 ref,
                 reason,
+                current_state_override=sim_state,
             )
             errors.extend(step_errors)
             if step_errors:
@@ -626,9 +638,9 @@ def build_review_report(
                 {
                     "task": "parent",
                     "transition": "parent-integrated",
-                    "optional": True,
+                    "optional": False,
                     "hint": (
-                        f"python ./.trellis/scripts/task.py record-gate {parent_dir.name} "
+                        f"Required before parent archive: python ./.trellis/scripts/task.py record-gate {parent_dir.name} "
                         f"--transition parent-integrated --gate integration-review --result PASS "
                         f"--reviewer parent --evidence task-map.md"
                     ),

package/dist/templates/trellis/scripts/common/retrieval_adapter_metadata.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from datetime import datetime, timezone
 from typing import Any
 
+from common.cursor_retrieval_env import ENV_BYOK, detect_cursor_retrieval_env
 from common.retrieval_evidence import (
     SOURCE_ARTIFACT_SEARCH,
     SOURCE_CODEBASE_EVIDENCE,
@@ -71,7 +72,6 @@ REQUIRED_ADAPTERS = frozenset({ADAPTER_RG, ADAPTER_VERIFICATION})
 OPTIONAL_INTEGRATION_ADAPTERS = (
     ADAPTER_CODEGRAPH,
     ADAPTER_LSP,
-    ADAPTER_FAST_CONTEXT,
     ADAPTER_MCP,
     ADAPTER_BROWSER,
     ADAPTER_NETWORK,
@@ -236,15 +236,11 @@ def build_adapter_states(
             optional_integration_adapter_state(adapter=adapter, hints=hints)
         )
 
-    # Platform-semantic: Cursor built-in semantic search (replaces fast-context)
     states.append(
-        adapter_state_entry(
-            adapter=ADAPTER_PLATFORM_SEMANTIC,
-            state=STATE_AVAILABLE,
-            required=False,
-            invoked=False,
-            reason="Platform-native semantic search on Cursor (e.g. @codebase); supersedes fast-context",
-        )
+        platform_semantic_adapter_state(router=router, hints=hints)
+    )
+    states.append(
+        fast_context_adapter_state(router=router, hints=hints)
     )
 
     states.append(
@@ -441,6 +437,101 @@ def codebase_adapter_state(
     )
 
 
+def resolve_cursor_env_for_adapter_metadata(
+    router: dict[str, Any] | None,
+) -> str:
+    """native | byok | unknown for retrieval-pack adapter reasons."""
+    router = router or {}
+    env = string_value(router.get("cursorEnv"))
+    if env in ("native", "byok", "unknown"):
+        return env
+    return detect_cursor_retrieval_env()
+
+
+def platform_semantic_adapter_state(
+    *,
+    router: dict[str, Any] | None,
+    hints: dict[str, dict[str, Any]],
+) -> dict[str, object]:
+    hint = hints.get(ADAPTER_PLATFORM_SEMANTIC, {})
+    if hint:
+        return adapter_state_entry(
+            adapter=ADAPTER_PLATFORM_SEMANTIC,
+            state=resolve_hint_state(hints, ADAPTER_PLATFORM_SEMANTIC, default=STATE_SKIPPED),
+            required=False,
+            invoked=bool(hint.get("invoked")),
+            reason=string_value(hint.get("reason")) or "platform-semantic adapter hint",
+        )
+    env = resolve_cursor_env_for_adapter_metadata(router)
+    if env == ENV_BYOK:
+        reason = (
+            "Cursor++ BYOK: built-in codebase semantic often absent (Experiment D); "
+            "concept recall Primary is fast-context MCP per router cursorEnv"
+        )
+        state = STATE_UNAVAILABLE
+    elif env == "native":
+        reason = (
+            "Cursor Native: built-in codebase semantic (e.g. SemanticSearch / @codebase) "
+            "is Primary for concept recall"
+        )
+        state = STATE_AVAILABLE
+    else:
+        reason = (
+            "Cursor platform-semantic: Native uses built-in search; BYOK uses fast-context "
+            "when cursorEnv is byok (see cursor_retrieval_env)"
+        )
+        state = STATE_UNVERIFIED
+    return adapter_state_entry(
+        adapter=ADAPTER_PLATFORM_SEMANTIC,
+        state=state,
+        required=False,
+        invoked=False,
+        reason=reason,
+    )
+
+
+def fast_context_adapter_state(
+    *,
+    router: dict[str, Any] | None,
+    hints: dict[str, dict[str, Any]],
+) -> dict[str, object]:
+    hint = hints.get(ADAPTER_FAST_CONTEXT, {})
+    if hint:
+        return adapter_state_entry(
+            adapter=ADAPTER_FAST_CONTEXT,
+            state=resolve_hint_state(hints, ADAPTER_FAST_CONTEXT, default=STATE_SKIPPED),
+            required=False,
+            invoked=bool(hint.get("invoked")),
+            reason=string_value(hint.get("reason")) or "fast-context-mcp adapter hint",
+        )
+    env = resolve_cursor_env_for_adapter_metadata(router)
+    if env == ENV_BYOK:
+        reason = (
+            "Cursor++ BYOK: fast_context_search is compliant Primary for concept recall "
+            "(select codebase-retrieval at init for .cursor/mcp.json fast-context entry)"
+        )
+        state = STATE_AVAILABLE
+    elif env == "native":
+        reason = (
+            "Cursor Native: prefer built-in platform-semantic; fast-context is optional "
+            "and misuse when plan requires native semantic"
+        )
+        state = STATE_SKIPPED
+    else:
+        reason = (
+            "fast-context MCP: required for BYOK concept recall on Cursor when "
+            "codebase-retrieval capability is selected"
+        )
+        state = STATE_UNVERIFIED
+    return adapter_state_entry(
+        adapter=ADAPTER_FAST_CONTEXT,
+        state=state,
+        required=False,
+        invoked=False,
+        reason=reason,
+    )
+
+
 def optional_integration_adapter_state(
     *,
     adapter: str,