@blxzer/cursor-trellis 0.1.0 → 0.1.1

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

@@ -0,0 +1,157 @@
+"""Classify agent tool names for retrieval execution telemetry (Cursor-first)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+CODEGRAPH_PATTERNS = (
+    re.compile(r"^codegraph_", re.I),
+    re.compile(r"^project-0-.*-codegraph-", re.I),
+    re.compile(r"codegraph_search", re.I),
+    re.compile(r"codegraph_explore", re.I),
+    re.compile(r"codegraph_callers", re.I),
+    re.compile(r"codegraph_node", re.I),
+)
+
+PLATFORM_SEMANTIC_PATTERNS = (
+    re.compile(r"@codebase", re.I),
+    re.compile(r"semantic.?search", re.I),
+    re.compile(r"DEEP_SEARCH", re.I),
+    re.compile(r"codebase.?search", re.I),
+    re.compile(r"SemanticSearch", re.I),
+    re.compile(r"Instant Search", re.I),
+    re.compile(r"Cursor.*semantic", re.I),
+    re.compile(r"built-?in.*codebase", re.I),
+)
+
+FAST_CONTEXT_PATTERNS = (
+    re.compile(r"fast_context_search", re.I),
+    re.compile(r"fast-context", re.I),
+    re.compile(r"fast_context", re.I),
+)
+
+GREP_PATTERNS = (
+    re.compile(r"^grep$", re.I),
+    re.compile(r"^Grep$", re.I),
+    re.compile(r"^rg$", re.I),
+    re.compile(r"ripgrep", re.I),
+    re.compile(r"Instant Grep", re.I),
+)
+
+READ_PATTERNS = (
+    re.compile(r"^read$", re.I),
+    re.compile(r"^Read$", re.I),
+    re.compile(r"ReadFile", re.I),
+    re.compile(r"Get-Content", re.I),
+)
+
+ROUTER_CLI_PATTERNS = (
+    re.compile(r"route_codebase_retrieval", re.I),
+    re.compile(r"retrieval-routing", re.I),
+)
+
+STRUCTURAL_ROUTE_IDS = frozenset(
+    {
+        "caller-chain-ast",
+        "trap-demote-codegraph",
+        "extension-codegraph",
+        "ast-codegraph",
+    }
+)
+
+
+def _matches(name: str, patterns: tuple[re.Pattern[str], ...]) -> bool:
+    return any(p.search(name) for p in patterns)
+
+
+def is_platform_semantic_tool_name(name: str) -> bool:
+    return _matches(name.strip(), PLATFORM_SEMANTIC_PATTERNS)
+
+
+def is_fast_context_tool_name(name: str) -> bool:
+    return _matches(name.strip(), FAST_CONTEXT_PATTERNS)
+
+
+@dataclass(frozen=True)
+class ClassifiedToolCalls:
+    tools_called: list[str]
+    grep_count: int
+    read_count: int
+    codegraph_attempted: bool
+    codegraph_executed: bool
+    semantic_attempted: bool
+    semantic_executed: bool
+    router_cli_invoked: bool
+    platform_semantic_executed: bool = False
+    fast_context_count: int = 0
+    cursor_fast_context_misuse: bool = False
+
+
+def classify_tool_calls(raw: list[str], *, platform: str = "cursor") -> ClassifiedToolCalls:
+    tools_called = list(raw)
+    grep_count = 0
+    read_count = 0
+    codegraph_executed = False
+    router_cli_invoked = False
+    platform_semantic_executed = False
+    fast_context_count = 0
+    plat = (platform or "cursor").lower()
+
+    for name in raw:
+        trimmed = name.strip()
+        if not trimmed:
+            continue
+        if _matches(trimmed, GREP_PATTERNS):
+            grep_count += 1
+        if _matches(trimmed, READ_PATTERNS):
+            read_count += 1
+        if _matches(trimmed, CODEGRAPH_PATTERNS):
+            codegraph_executed = True
+        if _matches(trimmed, ROUTER_CLI_PATTERNS):
+            router_cli_invoked = True
+        if is_fast_context_tool_name(trimmed):
+            fast_context_count += 1
+        if is_platform_semantic_tool_name(trimmed):
+            platform_semantic_executed = True
+
+    if plat == "cursor":
+        semantic_executed = platform_semantic_executed
+    else:
+        semantic_executed = platform_semantic_executed or fast_context_count > 0
+
+    semantic_attempted = semantic_executed or fast_context_count > 0
+    misuse = plat == "cursor" and fast_context_count > 0
+
+    return ClassifiedToolCalls(
+        tools_called=tools_called,
+        grep_count=grep_count,
+        read_count=read_count,
+        codegraph_attempted=codegraph_executed,
+        codegraph_executed=codegraph_executed,
+        semantic_attempted=semantic_attempted,
+        semantic_executed=semantic_executed,
+        router_cli_invoked=router_cli_invoked,
+        platform_semantic_executed=platform_semantic_executed,
+        fast_context_count=fast_context_count,
+        cursor_fast_context_misuse=misuse,
+    )
+
+
+def structural_routes_in_plan(route_ids: list[str]) -> bool:
+    return any(
+        "codegraph" in rid or rid in STRUCTURAL_ROUTE_IDS for rid in route_ids
+    )
+
+
+def semantic_routes_in_plan(route_ids: list[str]) -> bool:
+    return any(rid in ("platform-semantic", "semantic-fast-context") for rid in route_ids)
+
+
+def platform_semantic_route_order(routes: list[dict]) -> int | None:
+    for route in routes:
+        if isinstance(route, dict) and route.get("id") == "platform-semantic":
+            order = route.get("order")
+            if isinstance(order, int):
+                return order
+    return None

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

@@ -0,0 +1,52 @@
+"""REC-11: post-plan hints when platform-semantic is first-class in the router envelope."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def platform_semantic_order_from_envelope(envelope: dict[str, Any]) -> int | None:
+    routes = envelope.get("routes")
+    if not isinstance(routes, list):
+        return None
+    for route in routes:
+        if not isinstance(route, dict):
+            continue
+        if route.get("id") == "platform-semantic":
+            order = route.get("order")
+            if isinstance(order, int):
+                return order
+    return None
+
+
+def semantic_compliance_gate_hint(
+    envelope: dict[str, Any],
+    *,
+    locale: str = "zh",
+) -> str:
+    """
+    When platform-semantic is order 1 (or 2 on policy-first routes), append a
+    hard compliance strip for eval / hook-injected plans (REC-06 + REC-11).
+    """
+    order = platform_semantic_order_from_envelope(envelope)
+    if order is None or order > 2:
+        return ""
+    routes = envelope.get("routes") or []
+    if not isinstance(routes, list):
+        return ""
+    if not any(isinstance(r, dict) and r.get("id") == "platform-semantic" for r in routes):
+        return ""
+
+    if locale != "zh":
+        return (
+            "**Plan gate (REC-11):** `platform-semantic` is step "
+            f"#{order}. Before Top-1 you MUST run one Cursor built-in codebase "
+            "semantic search and log the exact tool name. Do not use fast-context MCP. "
+            "If semantic returns paths, corroborate with Read on candidate ranges."
+        )
+    return (
+        "**计划门控（REC-11）：** 本问 `platform-semantic` 为第 "
+        f"{order} 步。定 Top-1 前 **必须** 执行 1 次 Cursor **内置代码库语义搜索**，"
+        "并在记录中写下宿主工具名；**禁止** fast-context MCP。"
+        "语义命中路径后须 **Read** 验证候选片段（verified 层）。"
+    )

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

@@ -132,7 +132,7 @@ def get_step(step_id: str) -> str:
 
 
 def _platform_matches(platform: str, block_names: list[str]) -> bool:
-    """Case-insensitive fuzzy match: accept 'cursor', 'Cursor', 'claude-code', 'Claude Code'."""
+    """Case-insensitive fuzzy match: accept 'cursor' or 'Cursor'."""
     needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
     for name in block_names:
         hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
@@ -142,29 +142,8 @@ def _platform_matches(platform: str, block_names: list[str]) -> bool:
 
 
 def resolve_effective_platform(platform: str, config: dict) -> str:
-    """Map ``codex`` to a dispatch-mode-namespaced virtual platform name.
-
-    When ``--platform codex`` is passed, return ``"codex-inline"`` (default)
-    or ``"codex-sub-agent"`` based on ``.trellis/config.yaml`` ``codex.dispatch_mode``.
-    ``filter_platform`` then surfaces blocks whose marker lists include the
-    namespaced name (e.g. ``[codex-sub-agent, ...]`` or ``[codex-inline, Kilo,
-    Antigravity, Windsurf]``).
-
-    Default is ``inline`` because Codex sub-agents run with ``fork_turns="none"``
-    isolation and can't inherit the parent session's task context — inline
-    keeps the main agent in charge so context isn't lost. Invalid / missing
-    values also fall back to inline.
-
-    Other platforms are returned unchanged.
-    """
-    if platform == "codex":
-        mode = "inline"
-        codex_cfg = config.get("codex") if isinstance(config, dict) else None
-        if isinstance(codex_cfg, dict):
-            cfg_mode = codex_cfg.get("dispatch_mode")
-            if cfg_mode in ("inline", "sub-agent"):
-                mode = cfg_mode
-        return f"codex-{mode}"
+    """Return the platform name unchanged (Cursor-only fork)."""
+    _ = config
     return platform
 
 

package/dist/templates/trellis/scripts/rank_retrieval_candidates.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""CLI: rank codebase path candidates for B/E/D intents (eval / dogfood)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from common.retrieval_result_ranking import rank_retrieval_result_candidates
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Rank retrieval path candidates (caller / trap / env intents).",
+    )
+    parser.add_argument(
+        "--candidates",
+        help="Path to JSON array of candidate objects, or '-' for stdin.",
+    )
+    parser.add_argument(
+        "--intents",
+        required=True,
+        help="Comma-separated intent ids (e.g. caller-chain,env-config-literal).",
+    )
+    parser.add_argument("--top-k", type=int, default=5)
+    parser.add_argument("--expanded-pool-size", type=int, default=None)
+    parser.add_argument(
+        "--caller-pool-expansion",
+        action="store_true",
+        help="Enable caller pool expansion (caller-chain intent).",
+    )
+    parser.add_argument("--min-concrete-callers", type=int, default=3)
+    parser.add_argument("--json", action="store_true", help="Emit JSON (default).")
+    parser.add_argument("--pretty", action="store_true")
+    return parser.parse_args(argv)
+
+
+def load_candidates(source: str | None) -> list[dict]:
+    if source is None or source == "-":
+        raw = sys.stdin.read()
+    else:
+        raw = Path(source).read_text(encoding="utf-8")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list):
+        raise ValueError("candidates must be a JSON array")
+    return [item for item in parsed if isinstance(item, dict)]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        candidates = load_candidates(args.candidates)
+    except (OSError, json.JSONDecodeError, ValueError) as error:
+        print(f"rank_retrieval_candidates: {error}", file=sys.stderr)
+        return 2
+
+    intents = [part.strip() for part in args.intents.split(",") if part.strip()]
+    expansion = None
+    if args.caller_pool_expansion:
+        expansion = {
+            "enabled": True,
+            "minConcreteCallers": args.min_concrete_callers,
+        }
+
+    result = rank_retrieval_result_candidates(
+        candidates,
+        intents=intents,
+        top_k=args.top_k,
+        expanded_pool_size=args.expanded_pool_size,
+        caller_pool_expansion=expansion,
+    )
+    indent = 2 if args.pretty else None
+    print(json.dumps(result, indent=indent, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/trellis/scripts/route_codebase_retrieval.py

@@ -7,12 +7,16 @@ from __future__ import annotations
 
 import argparse
 import json
+import sys
 from pathlib import Path
 
 from common.codebase_retrieval_router import (
     codebase_retrieval_selected_from_capabilities,
     route_codebase_retrieval,
 )
+from common.paths import get_repo_root
+from common.project_file_stats import resolve_project_file_count_arg
+from common.retrieval_agent_instructions import render_agent_instructions
 
 
 def load_capabilities(path: Path | None) -> dict[str, object] | None:
@@ -38,16 +42,24 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         help="Treat codebase-retrieval as unselected (omit optional adapter routes).",
     )
     parser.add_argument(
-        "--platform",
-        default="generic",
-        choices=["cursor", "claude-code", "codex", "generic"],
-        help="Host platform for platform-adaptive routing (default: generic).",
+        "--project-file-count",
+        default="auto",
+        metavar="N|auto",
+        help=(
+            "File count for large-repo routing (>2000 promotes codegraph). "
+            "Default auto: git ls-files or walk from repo root. Example: 5000."
+        ),
     )
     parser.add_argument(
-        "--project-file-count",
-        type=int,
-        default=None,
-        help="Total file count in project for token economy signals (e.g. 5000).",
+        "--locale",
+        default="zh",
+        choices=["zh", "en"],
+        help="Language for agent instructions (default: zh).",
+    )
+    parser.add_argument(
+        "--instructions",
+        action="store_true",
+        help="Print agent-executable instructions only (no JSON).",
     )
     parser.add_argument("--json", action="store_true", help="Emit JSON to stdout (default).")
     parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON.")
@@ -56,6 +68,14 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
 
 def main(argv: list[str] | None = None) -> int:
     args = parse_args(argv)
+    try:
+        project_file_count = resolve_project_file_count_arg(
+            args.project_file_count,
+            repo_root=get_repo_root(),
+        )
+    except ValueError as error:
+        print(f"route_codebase_retrieval: {error}", file=sys.stderr)
+        return 2
     caps = load_capabilities(Path(args.capabilities) if args.capabilities else None)
     selected = (
         False
@@ -65,11 +85,18 @@ def main(argv: list[str] | None = None) -> int:
     plan = route_codebase_retrieval(
         args.query,
         codebase_retrieval_selected=selected,
-        platform=args.platform,
-        project_file_count=args.project_file_count,
+        project_file_count=project_file_count,
+    )
+    instructions = render_agent_instructions(
+        plan,
+        locale=args.locale,
     )
+    if args.instructions:
+        sys.stdout.write(instructions)
+        return 0
+    payload: dict[str, object] = {**plan, "agentInstructions": instructions}
     indent = 2 if args.pretty else None
-    print(json.dumps(plan, indent=indent, ensure_ascii=False))
+    print(json.dumps(payload, indent=indent, ensure_ascii=False))
     return 0
 
 

package/dist/templates/trellis/scripts/score_evidence.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""REC-11: derive evidence_score (0-2) from telemetry + optional rubric row."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+from common.retrieval_tool_classification import classify_tool_calls  # noqa: E402
+
+
+def evidence_score_from_record(record: dict[str, Any]) -> int:
+    """
+    Trellis verified layer proxy for eval (R-CR-014):
+    0 = no Read on candidates
+    1 = Read used but no corroborated_files / weak verify
+    2 = read_verification_done and (corroborated_files or read_count >= 1 with top1)
+    """
+    if not record.get("read_verification_done") and int(record.get("read_count") or 0) <= 0:
+        return 0
+    corroborated = record.get("corroborated_files") or []
+    if isinstance(corroborated, list) and len(corroborated) > 0:
+        return 2
+    if record.get("read_verification_done") or int(record.get("read_count") or 0) > 0:
+        top1 = str(record.get("top1") or record.get("top_1") or "").strip()
+        if top1:
+            return 2
+        return 1
+    return 0
+
+
+def enrich_record(raw: dict[str, Any]) -> dict[str, Any]:
+    platform = str(raw.get("platform", "cursor"))
+    tools = raw.get("tools_called") or []
+    if not isinstance(tools, list):
+        tools = []
+    classified = classify_tool_calls([str(t) for t in tools], platform=platform)
+    out = dict(raw)
+    out["platform_semantic_executed"] = bool(
+        raw.get("platform_semantic_executed", classified.platform_semantic_executed)
+    )
+    out["semantic_executed"] = bool(raw.get("semantic_executed", classified.semantic_executed))
+    out["read_count"] = int(raw.get("read_count", classified.read_count))
+    if "read_verification_done" not in out:
+        out["read_verification_done"] = classified.read_count > 0
+    out["evidence_score"] = evidence_score_from_record(out)
+    ans = raw.get("answer_score")
+    if isinstance(ans, (int, float)):
+        out["combined_score"] = float(ans) + float(out["evidence_score"])
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("jsonl", type=Path, help="Per-query telemetry JSONL")
+    parser.add_argument("--pretty", action="store_true")
+    parser.add_argument("--markdown", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not args.jsonl.is_file():
+        print(f"error: not found: {args.jsonl}", file=sys.stderr)
+        return 1
+
+    rows: list[dict[str, Any]] = []
+    for line in args.jsonl.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        raw = json.loads(stripped)
+        if isinstance(raw, dict):
+            rows.append(enrich_record(raw))
+
+    evidence_total = sum(int(r.get("evidence_score", 0)) for r in rows)
+    combined: list[float] = []
+    for r in rows:
+        c = r.get("combined_score")
+        if isinstance(c, (int, float)):
+            combined.append(float(c))
+
+    summary = {
+        "n": len(rows),
+        "evidence_score_total": evidence_total,
+        "evidence_score_max": len(rows) * 2,
+        "avg_evidence_score": 0.0 if not rows else evidence_total / len(rows),
+        "avg_combined_score": 0.0 if not combined else sum(combined) / len(combined),
+    }
+
+    if args.markdown:
+        print("## Evidence scores (REC-11)\n")
+        print("| query_id | evidence_score | read_verify | semantic_exec |")
+        print("| --- | ---: | --- | --- |")
+        for r in rows:
+            print(
+                f"| {r.get('query_id','')} | {r.get('evidence_score',0)} | "
+                f"{r.get('read_verification_done')} | {r.get('semantic_executed')} |"
+            )
+        print(f"\nTotal evidence: **{evidence_total}** / {summary['evidence_score_max']}")
+    else:
+        payload = {"summary": summary, "records": rows}
+        print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())