@blxzer/cursor-trellis 0.3.5 → 0.4.0

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

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Tests for Plan A task-level depends_on resolution (declare + soft checks)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common.task_dependencies import (
+    KIND_CHILD,
+    KIND_MISSING,
+    KIND_POOL,
+    KIND_TASK,
+    NOT_SATISFIED,
+    SATISFIED,
+    UNRESOLVED,
+    dashboard_deps_line,
+    describe_dependencies,
+    find_dependency_cycles,
+    normalize_dep_list,
+    resolve_dep_ref,
+    satisfaction_status,
+)
+
+
+def _write_task(tasks_dir: Path, dir_name: str, status: str, depends_on=None) -> Path:
+    task_dir = tasks_dir / dir_name
+    task_dir.mkdir(parents=True, exist_ok=True)
+    data = {
+        "id": dir_name,
+        "name": dir_name,
+        "title": dir_name,
+        "status": status,
+    }
+    if depends_on is not None:
+        data["depends_on"] = depends_on
+    (task_dir / "task.json").write_text(json.dumps(data), encoding="utf-8")
+    return task_dir
+
+
+def _tasks_fixture(tmp_path: Path) -> Path:
+    tasks_dir = tmp_path / "repo" / ".cstl" / "tasks"
+    tasks_dir.mkdir(parents=True)
+    return tasks_dir
+
+
+def test_completed_task_is_satisfied(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-a", "completed")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-a"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-a"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert dep.kind == KIND_TASK
+    assert satisfaction_status(dep)[0] == SATISFIED
+    assert report.warnings() == []
+
+
+def test_archived_task_counts_as_completed(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    archive_dir = tasks_dir / "archive" / "2026-08"
+    archive_dir.mkdir(parents=True)
+    # Anomaly: archived task.json still says planning — location is the rule.
+    _write_task(archive_dir, "dep-archived", "planning")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-archived"])
+
+    dep = resolve_dep_ref("dep-archived", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_TASK
+    assert dep.is_archived
+    status, note = satisfaction_status(dep)
+    assert status == SATISFIED
+    assert note == "archived task counts as completed"
+
+
+def test_cancelled_task_satisfied_with_cancelled_warning(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-c", "cancelled")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-c"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-c"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert dep.is_cancelled
+    assert satisfaction_status(dep)[0] == SATISFIED
+    assert any("cancelled" in w for w in report.warnings())
+
+
+def test_in_progress_dependency_is_not_satisfied(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-b", "in_progress")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-b"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-b"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert satisfaction_status(dep)[0] == NOT_SATISFIED
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_dangling_reference_is_unresolved_warning(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["ghost-task"])
+
+    dep = resolve_dep_ref("ghost-task", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_MISSING
+    assert satisfaction_status(dep)[0] == UNRESOLVED
+    report = describe_dependencies(task_dir, {"depends_on": ["ghost-task"]}, tasks_dir=tasks_dir)
+    assert any("dangling" in w for w in report.warnings())
+
+
+def test_pool_prefix_is_unresolved_and_never_falls_through(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_POOL
+    assert satisfaction_status(dep)[0] == UNRESOLVED
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("unresolved" in w for w in report.warnings())
+
+
+def test_cycle_detected_across_tasks(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_a = _write_task(tasks_dir, "task-a", "planning", ["task-b"])
+    _write_task(tasks_dir, "task-b", "planning", ["task-a"])
+
+    report = describe_dependencies(task_a, {"depends_on": ["task-b"]}, tasks_dir=tasks_dir)
+    assert len(report.cycles) == 1
+    assert report.cycles[0][0] == report.cycles[0][-1]
+    assert any("cycle" in w for w in report.warnings())
+
+
+def test_self_reference_cycle_detected(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["task-x"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["task-x"]}, tasks_dir=tasks_dir)
+    assert report.cycles == [["task-x", "task-x"]]
+
+
+def test_find_dependency_cycles_pure(tmp_path: Path) -> None:
+    graph = {"a": ["b"], "b": ["c"], "c": ["a"], "d": []}
+    cycles = find_dependency_cycles(graph)
+    assert len(cycles) == 1
+    cycle = cycles[0]
+    assert cycle[0] == cycle[-1]
+    assert set(cycle) == {"a", "b", "c"}
+
+
+def test_scope_child_wins_over_global_task_with_same_name(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    # Global task named "shared" that IS completed — would be satisfied globally.
+    _write_task(tasks_dir, "shared", "completed")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["shared"])
+    scope = {"shared": "open"}
+
+    dep = resolve_dep_ref("shared", tasks_dir=tasks_dir, scope_children=scope)
+    assert dep.kind == KIND_CHILD
+    assert dep.source == "task-map"
+    assert satisfaction_status(dep)[0] == NOT_SATISFIED
+
+    report = describe_dependencies(
+        task_dir, {"depends_on": ["shared"]}, tasks_dir=tasks_dir, scope_children=scope
+    )
+    assert report.deps[0].kind == KIND_CHILD
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_child_integrated_is_satisfied_via_scope(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["child-a"])
+    scope = {"child-a": "integrated", "child-b": "cancelled"}
+
+    dep = resolve_dep_ref("child-a", tasks_dir=tasks_dir, scope_children=scope)
+    assert dep.kind == KIND_CHILD
+    assert satisfaction_status(dep)[0] == SATISFIED
+
+    report = describe_dependencies(
+        task_dir, {"depends_on": ["child-a", "child-b"]}, tasks_dir=tasks_dir, scope_children=scope
+    )
+    assert satisfaction_status(report.deps[0])[0] == SATISFIED
+    assert report.deps[1].is_cancelled
+    assert any("cancelled" in w for w in report.warnings())
+
+
+def test_empty_depends_on_has_no_warnings_or_dashboard_line(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning")
+    data = {"id": "task-x", "status": "planning"}
+
+    report = describe_dependencies(task_dir, data, tasks_dir=tasks_dir)
+    assert not report.has_deps()
+    assert report.warnings() == []
+    assert dashboard_deps_line(task_dir, data, tasks_dir=tasks_dir) is None
+
+
+def test_dashboard_deps_line_renders_badges(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-done", "completed")
+    _write_task(tasks_dir, "dep-wait", "in_progress")
+    _write_task(tasks_dir, "dep-gone", "cancelled")
+    task_dir = _write_task(
+        tasks_dir, "task-x", "planning", ["dep-done", "dep-wait", "dep-gone", "pool:P09"]
+    )
+    data = {
+        "id": "task-x",
+        "status": "planning",
+        "depends_on": ["dep-done", "dep-wait", "dep-gone", "pool:P09"],
+    }
+
+    line = dashboard_deps_line(task_dir, data, tasks_dir=tasks_dir)
+    assert line is not None
+    assert "dep-done ✅" in line
+    assert "dep-wait ⏳" in line
+    assert "dep-gone ✅已取消" in line
+    assert "pool:P09 ⚠️" in line
+
+
+def test_normalize_dep_list_dedupes_and_strips(tmp_path: Path) -> None:
+    assert normalize_dep_list(None) == []
+    assert normalize_dep_list(["a", " a ", "b", "a", "", 5]) == ["a", "b"]
+    assert normalize_dep_list("not-a-list") == []
+
+
+# =============================================================================
+# pool: real status (08-09-pool-links-and-cli)
+# =============================================================================
+
+def _pool_repo(tmp_path: Path, linked_tasks: list[str] | None) -> Path:
+    repo = tmp_path / "repo"
+    items_dir = repo / ".cstl" / "pool" / "items"
+    items_dir.mkdir(parents=True)
+    lines = ["id: P09", "title: t", "status: accepted", "type: mechanism"]
+    if linked_tasks:
+        lines.append("linked_tasks:")
+        lines += [f"  - {task}" for task in linked_tasks]
+    (items_dir / "P09.md").write_text(
+        "---\n" + "\n".join(lines) + "\n---\n\n## 意图\nx\n",
+        encoding="utf-8",
+    )
+    return repo
+
+
+def test_pool_missing_item_is_unresolved(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_POOL
+    status, note = satisfaction_status(dep)
+    assert status == UNRESOLVED
+    assert "not found" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("unresolved" in w for w in report.warnings())
+
+
+def test_pool_unlinked_is_unresolved(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=None)
+    tasks_dir = repo / ".cstl" / "tasks"
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_POOL
+    status, note = satisfaction_status(dep)
+    assert status == UNRESOLVED
+    assert "no linked tasks" in (note or "")
+
+
+def test_pool_linked_planning_task_is_not_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=["task-a"])
+    tasks_dir = repo / ".cstl" / "tasks"
+    _write_task(tasks_dir, "task-a", "planning")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.status == "not_satisfied"
+    status, note = satisfaction_status(dep)
+    assert status == NOT_SATISFIED
+    assert "not yet completed" in (note or "")
+    assert "task-a" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_pool_linked_completed_task_is_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=["task-a"])
+    tasks_dir = repo / ".cstl" / "tasks"
+    _write_task(tasks_dir, "task-a", "completed")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.status == "satisfied"
+    status, _ = satisfaction_status(dep)
+    assert status == SATISFIED
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert report.warnings() == []
+
+
+def test_pool_multilink_partial_then_complete(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=["task-a", "task-b"])
+    tasks_dir = repo / ".cstl" / "tasks"
+    _write_task(tasks_dir, "task-a", "completed")
+    _write_task(tasks_dir, "task-b", "in_progress")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    status, note = satisfaction_status(dep)
+    assert status == NOT_SATISFIED
+    assert "task-a, task-b" in (note or "")
+
+    _write_task(tasks_dir, "task-b", "completed")
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert satisfaction_status(dep)[0] == SATISFIED
+
+
+def test_pool_all_dangling_linked_tasks_is_unresolved(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=["ghost-a"])
+    tasks_dir = repo / ".cstl" / "tasks"
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.status == "unresolved"
+    status, note = satisfaction_status(dep)
+    assert status == UNRESOLVED
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("unresolved" in w for w in report.warnings())
+
+
+def test_pool_cancelled_linked_task_is_satisfied_with_cancelled_note(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, linked_tasks=["task-a"])
+    tasks_dir = repo / ".cstl" / "tasks"
+    _write_task(tasks_dir, "task-a", "cancelled")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.status == "cancelled"
+    assert dep.is_cancelled
+    status, note = satisfaction_status(dep)
+    assert status == SATISFIED
+    assert "cancelled" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("cancelled" in w for w in report.warnings())

package/dist/templates/trellis/scripts/cursor_retrieval_probe_prompt.md

@@ -251,36 +251,38 @@ verdict rules:
 
 ---
 
---- PROBE P-10: Definition / reference (codegraph — Agent LSP not exposed)
+--- PROBE P-10: Definition / reference (Prefer Grep+Read; codegraph when ambiguous)
 
 Cursor Agent does **not** expose GO_TO_DEFINITION in the tool table (Native/BYOK).
-Trellis routes definition/reference to **codegraph**. This probe measures the
-**product path**, not raw LSP.
+Trellis **Prefers** native **Grep → Read** for named-symbol definition; **codegraph**
+is the **Own** fallback when Grep is ambiguous or structural context is required.
 
-You are a retrieval capability probe. Use **codegraph_node** or **codegraph_search**
-as the **primary** path. Do NOT use Grep as the first step. Use **Read** only to
-confirm line numbers after codegraph returns a definition.
+You are a retrieval capability probe.
 
 Task: Locate the **definition** of `route_codebase_retrieval` (Python function).
 
+**Step 1 (Prefer):** Use **Grep** for `def route_codebase_retrieval` — do NOT use codegraph first.
+**Step 2:** Use **Read** to confirm the definition line and body start.
+**Step 3 (only if Grep ambiguous):** codegraph_explore / codegraph_search.
+
 Expected: definition in `.cstl/scripts/common/codebase_retrieval_router.py`
-(`def route_codebase_retrieval(`).
+(`def route_codebase_retrieval(` at line ~805).
 
 Reply in this exact format:
 
 ```
 P-10 RESULT
-tool_invoked: <exact tool name — codegraph_node, codegraph_search, or "none">
+tool_invoked: <primary tool — Grep, Read, codegraph_explore, or "none">
 definition_file: <path>
 definition_line: <line number or "unknown">
 verdict: pass|fail|environment_limitation
-notes: <if you tried GO_TO_DEFINITION and it was unavailable, say so; pass when codegraph + Read confirm def>
+notes: <GO_TO_DEFINITION availability; did Grep+Read succeed before any codegraph?>
 ```
 
 verdict rules:
-- **pass**: codegraph (or equivalent MCP) returned the correct `def route_codebase_retrieval` file.
-- **environment_limitation**: only when codegraph MCP/index is missing; not when LSP is missing.
-- **fail**: wrong file or no structural tool executed.
+- **pass**: Grep (+ Read) returned the correct `def route_codebase_retrieval` file; codegraph optional.
+- **environment_limitation**: only when Grep/Read are unavailable in the host (not when LSP is missing).
+- **fail**: wrong file, or codegraph used as first step without Grep attempt.
 
 ---
 

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

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+CLI Layer 2 — PRIMARY (guaranteed) context path for cstl-* Task dispatch.
+
+Usage:
+    python ./.cstl/scripts/generate_dispatch_prompt.py --agent research
+    python ./.cstl/scripts/generate_dispatch_prompt.py --agent implement --task .cstl/tasks/06-23-subagent-smoke
+    python ./.cstl/scripts/generate_dispatch_prompt.py --agent research --repo-root d:/MyHarness
+
+Outputs the complete dispatch prompt to stdout. The main session MUST capture
+this output and pass it as the `prompt` parameter to
+`Task(subagent_type=cstl-*, prompt=<generated>)`. This is the ONLY
+guaranteed context channel for custom Task subagents on Cursor.
+
+Hook injection (`preToolUse` / `additional_context`) is best-effort only
+(Cursor #158452; hook does not fire for Task tool in Cursor 3.8.22). Do not
+treat hook-only injection as a substitute for this CLI path.
+
+The generated prompt carries:
+  - Role identity ("You are the Trellis Research/Implement/Check Agent")
+  - Write scope constraints (Write ALLOWED / Write FORBIDDEN)
+  - Recursion guard
+  - Dynamic context (prd.md, design.md, implement.md, spec tree, jsonl files)
+
+Task path resolution:
+  - `--task <path>` is the **primary fallback** when no selected-task pointer exists
+    (e.g. `task.py select` failed due to missing session identity).
+  - When `--task` is omitted, auto-detect via selected pointer is **best-effort** only —
+    dispatch scripts do not hard-depend on a persisted selection.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate a complete Trellis subagent dispatch prompt."
+    )
+    parser.add_argument(
+        "--agent",
+        required=True,
+        choices=["research", "implement", "check"],
+        help="Subagent role to generate prompt for.",
+    )
+    parser.add_argument(
+        "--task",
+        default=None,
+        help="Task directory path (absolute or relative to repo root). "
+        "Primary fallback when no selected-task pointer exists. "
+        "If omitted, auto-detect via selected pointer is best-effort only.",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=None,
+        help="Repository root path. If omitted, auto-detect via .cstl or .git.",
+    )
+    parser.add_argument(
+        "--finish",
+        action="store_true",
+        help="Use finish context (check agent only, final pre-PR verification).",
+    )
+    parser.add_argument(
+        "--max-chars",
+        type=int,
+        default=None,
+        help="Truncate injected context at this character count. "
+        "When omitted, uses role default from injection-budget-guide.",
+    )
+    args = parser.parse_args()
+
+    # Resolve repo root
+    if args.repo_root:
+        repo_root = Path(args.repo_root).resolve()
+    else:
+        repo_root = _find_repo_root(Path.cwd())
+        if not repo_root:
+            print("ERROR: could not find repo root (no .cstl or .git upward)", file=sys.stderr)
+            return 1
+
+    from common.paths import DIR_WORKFLOW  # type: ignore[import-not-found]
+
+    # Make scripts importable — workspace root first (subagent_dispatch.py lives there),
+    # then repo_root's own scripts (may be a subproject with different common/)
+    workspace_root = _find_workspace_root(repo_root, DIR_WORKFLOW)
+    if workspace_root and workspace_root != repo_root:
+        ws_scripts = workspace_root / DIR_WORKFLOW / "scripts"
+        if str(ws_scripts) not in sys.path:
+            sys.path.insert(0, str(ws_scripts))
+
+    scripts_dir = repo_root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(1, str(scripts_dir))
+
+    from common.subagent_dispatch import build_dispatch_prompt  # type: ignore[import-not-found]
+    from common.injection_budget import DISPATCH_DEFAULT_MAX_CHARS  # type: ignore[import-not-found]
+
+    # Resolve task directory
+    if args.task:
+        task_dir = Path(args.task)
+        if not task_dir.is_absolute():
+            task_dir = repo_root / task_dir
+        task_dir = task_dir.resolve()
+    else:
+        task_dir = _resolve_selected_task(repo_root)
+        if not task_dir:
+            print(
+                "ERROR: no --task specified and no selected task found. "
+                "Run `python ./.cstl/scripts/task.py select <task>` first.",
+                file=sys.stderr,
+            )
+            return 1
+
+    if not task_dir.is_dir():
+        print(f"ERROR: task directory not found: {task_dir}", file=sys.stderr)
+        return 1
+
+    max_chars = args.max_chars
+    if max_chars is None:
+        max_chars = DISPATCH_DEFAULT_MAX_CHARS.get(args.agent)
+
+    prompt, warnings, errors = build_dispatch_prompt(
+        repo_root,
+        task_dir,
+        args.agent,
+        finish=args.finish,
+        max_chars=max_chars,
+        require_in_progress=False,
+    )
+
+    for w in warnings:
+        print(f"WARN: {w}", file=sys.stderr)
+    for e in errors:
+        print(f"ERROR: {e}", file=sys.stderr)
+
+    if not prompt:
+        print("ERROR: failed to generate prompt (see errors above)", file=sys.stderr)
+        return 1
+
+    # Output the prompt to stdout — the caller captures this
+    print(prompt)
+    return 0
+
+
+def _find_repo_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while current != current.parent:
+        if (current / ".cstl").is_dir() or (current / ".git").exists():
+            return current
+        current = current.parent
+    return None
+
+
+def _find_workspace_root(start: Path, dir_workflow: str) -> Path | None:
+    """Find the outermost directory with workflow dir (workspace root, not subproject)."""
+    found = None
+    current = start.resolve()
+    while current != current.parent:
+        if (current / dir_workflow).is_dir():
+            found = current
+        current = current.parent
+    return found
+
+
+def _resolve_selected_task(repo_root: Path) -> Path | None:
+    try:
+        from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+        result = resolve_selected_task(repo_root, {}, platform="cursor")
+        if result.task_path:
+            task_path = Path(result.task_path)
+            if not task_path.is_absolute():
+                task_path = repo_root / task_path
+            return task_path
+    except Exception:
+        pass
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Injection budget probe — measure alwaysApply, AGENTS, jsonl, and Layer 2 dispatch."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_SCRIPTS = Path(__file__).resolve().parent
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+from common.injection_budget import (  # noqa: E402
+    budget_violations,
+    collect_budget_report,
+    format_budget_report,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Measure Trellis injection budget surfaces.")
+    parser.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    parser.add_argument("--task", default=None, help="Task directory for jsonl/dispatch probes")
+    parser.add_argument(
+        "--dispatch-role",
+        choices=["implement", "check", "research"],
+        default="implement",
+        help="Role when measuring dispatch prompt (default: implement)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 on FAIL thresholds (rules >32KiB) or any WARN",
+    )
+    parser.add_argument("--json", action="store_true", help="Reserved for future machine output")
+    args = parser.parse_args()
+
+    if args.json:
+        print("ERROR: --json not implemented yet", file=sys.stderr)
+        return 2
+
+    repo_root = Path(args.repo_root).resolve()
+    task_dir = None
+    if args.task:
+        task_dir = Path(args.task)
+        if not task_dir.is_absolute():
+            task_dir = repo_root / task_dir
+        task_dir = task_dir.resolve()
+
+    report = collect_budget_report(
+        repo_root,
+        task_dir=task_dir,
+        dispatch_role=args.dispatch_role if task_dir else None,
+    )
+    print(format_budget_report(report))
+
+    violations = budget_violations(report, strict=args.strict)
+    if violations:
+        print("\n## Violations", file=sys.stderr)
+        for item in violations:
+            print(item, file=sys.stderr)
+        if args.strict or any(item.startswith("FAIL:") for item in violations):
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())