@blxzer/cursor-trellis 0.3.5 → 0.3.6

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

@@ -20,6 +20,7 @@ from .paths import DIR_WORKFLOW, DIR_WORKSPACE, FILE_JOURNAL_PREFIX, get_develop
 
 
 SECTION_NAMES = {"summary", "main changes", "git commits", "testing", "status", "next steps"}
+JOURNAL_SNIPPET_MAX_TOKENS = 150
 FIELD_WEIGHTS = {
     "title": 8,
     "task": 8,
@@ -337,6 +338,31 @@ def normalize_space(value: str) -> str:
     return re.sub(r"\s+", " ", value).strip()
 
 
+def truncate_to_token_budget(text: str, max_tokens: int = JOURNAL_SNIPPET_MAX_TOKENS) -> str:
+    """Collapse whitespace and hard-cap by whitespace-split token count."""
+    normalized = normalize_space(text)
+    if not normalized:
+        return ""
+    tokens = normalized.split()
+    if len(tokens) <= max_tokens:
+        return normalized
+    return " ".join(tokens[:max_tokens])
+
+
+def get_latest_journal_summary(
+    journal_path: Path,
+    repo_root: Path,
+    developer: str,
+    max_tokens: int = JOURNAL_SNIPPET_MAX_TOKENS,
+) -> str:
+    """Return the latest session summary from one journal file (≤ max_tokens)."""
+    entries = parse_journal(journal_path, repo_root, developer)
+    if not entries:
+        return ""
+    summary = entries[-1].sections.get("summary", "")
+    return truncate_to_token_budget(summary, max_tokens)
+
+
 def to_repo_path(path: Path, repo_root: Path) -> str:
     try:
         return path.resolve().relative_to(repo_root.resolve()).as_posix()

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

@@ -12,6 +12,11 @@ import sys
 from pathlib import Path
 from typing import Literal
 
+from .injection_budget import (
+    JSONL_MAX_ENTRIES,
+    JSONL_MAX_FILE_CHARS,
+    JSONL_MAX_TOTAL_CHARS,
+)
 from .io import read_json
 from .paths import FILE_TASK_JSON
 
@@ -87,7 +92,8 @@ def read_jsonl_entries(
     jsonl_path: str,
     *,
     warn_prefix: str = "subagent-dispatch",
-) -> list[tuple[str, str]]:
+    apply_budget: bool = True,
+) -> tuple[list[tuple[str, str]], list[str]]:
     full_path = os.path.join(base_path, jsonl_path)
     if not os.path.exists(full_path):
         print(
@@ -95,10 +101,13 @@ def read_jsonl_entries(
             "sub-agent will receive only task artifacts",
             file=sys.stderr,
         )
-        return []
+        return [], []
 
     results: list[tuple[str, str]] = []
+    skipped: list[str] = []
     saw_real_entry = False
+    loaded_entries = 0
+    total_chars = 0
     try:
         with open(full_path, "r", encoding="utf-8") as f:
             for line in f:
@@ -112,12 +121,38 @@ def read_jsonl_entries(
                     if not file_path:
                         continue
                     saw_real_entry = True
+                    if apply_budget and loaded_entries >= JSONL_MAX_ENTRIES:
+                        skipped.append(f"{file_path}: entry cap ({JSONL_MAX_ENTRIES})")
+                        continue
+
+                    expanded: list[tuple[str, str]] = []
                     if entry_type == "directory":
-                        results.extend(read_directory_contents(base_path, file_path))
+                        expanded = read_directory_contents(base_path, file_path)
                     else:
                         content = read_file_content(base_path, file_path)
                         if content:
-                            results.append((file_path, content))
+                            expanded = [(file_path, content)]
+
+                    if not expanded:
+                        skipped.append(f"{file_path}: missing or empty")
+                        continue
+
+                    block_chars = sum(len(content) for _, content in expanded)
+                    if apply_budget and block_chars > JSONL_MAX_FILE_CHARS:
+                        skipped.append(
+                            f"{file_path}: file cap ({block_chars}>{JSONL_MAX_FILE_CHARS} chars)"
+                        )
+                        continue
+                    if apply_budget and total_chars + block_chars > JSONL_MAX_TOTAL_CHARS:
+                        skipped.append(
+                            f"{file_path}: total cap "
+                            f"({total_chars + block_chars}>{JSONL_MAX_TOTAL_CHARS})"
+                        )
+                        continue
+
+                    results.extend(expanded)
+                    total_chars += block_chars
+                    loaded_entries += 1
                 except json.JSONDecodeError:
                     continue
     except OSError:
@@ -129,13 +164,23 @@ def read_jsonl_entries(
             "(only seed / empty) — sub-agent will receive only task artifacts.",
             file=sys.stderr,
         )
-    return results
+    elif apply_budget and (results or skipped):
+        loaded_paths = ", ".join(path for path, _ in results) or "(none)"
+        print(
+            f"[{warn_prefix}] injection-budget: {jsonl_path} "
+            f"loaded {loaded_entries} entries ({total_chars} chars): {loaded_paths}",
+            file=sys.stderr,
+        )
+        for reason in skipped:
+            print(f"[{warn_prefix}] injection-budget: skipped {reason}", file=sys.stderr)
+    return results, skipped
 
 
 def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
     context_parts: list[str] = []
     agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
-    for file_path, content in read_jsonl_entries(repo_root, agent_jsonl):
+    entries, _ = read_jsonl_entries(repo_root, agent_jsonl)
+    for file_path, content in entries:
         context_parts.append(f"=== {file_path} ===\n{content}")
     return "\n\n".join(context_parts)
 
@@ -166,7 +211,8 @@ def get_implement_context(repo_root: str, task_dir: str) -> str:
 
 def get_check_context(repo_root: str, task_dir: str) -> str:
     context_parts: list[str] = []
-    for file_path, content in read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl"):
+    entries, _ = read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl")
+    for file_path, content in entries:
         context_parts.append(f"=== {file_path} ===\n{content}")
 
     prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
@@ -192,7 +238,25 @@ def get_finish_context(repo_root: str, task_dir: str) -> str:
 
 
 def get_research_context(repo_root: str, task_dir: str | None) -> str:
-    _ = task_dir
+    context_parts: list[str] = []
+
+    if task_dir:
+        entries, _ = read_jsonl_entries(repo_root, f"{task_dir}/research.jsonl")
+        for file_path, content in entries:
+            context_parts.append(f"=== {file_path} ===\n{content}")
+
+        prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+        if prd_content:
+            context_parts.append(
+                f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}"
+            )
+
+        design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+        if design_content:
+            context_parts.append(
+                f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+            )
+
     spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
     spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
 
@@ -219,7 +283,8 @@ To get structured package info, run: `python ./{DIR_WORKFLOW}/scripts/get_contex
 - Spec files: `{spec_path}/**/*.md`
 - Code search: Use Glob and Grep tools
 - External facts / docs: load `smart-search-cli` skill and use Bash (`smart-search` CLI), not Cursor WebSearch/WebFetch by default"""
-    return project_structure
+    context_parts.append(project_structure)
+    return "\n\n".join(context_parts)
 
 
 def build_implement_prompt(original_prompt: str, context: str) -> str:

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

@@ -24,6 +24,11 @@ from pathlib import Path
 from .log import Colors, colored
 from .paths import get_repo_root
 from .task_utils import resolve_task_dir
+from .injection_budget import (
+    JSONL_MAX_ENTRIES,
+    JSONL_MAX_TOTAL_CHARS,
+    measure_jsonl_manifest,
+)
 
 
 # =============================================================================
@@ -159,6 +164,19 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
 
     if errors == 0:
         print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
+        budget = measure_jsonl_manifest(repo_root, jsonl_file.parent, file_name)
+        if real_entries > JSONL_MAX_ENTRIES:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — {real_entries} entries (max {JSONL_MAX_ENTRIES})', Colors.YELLOW)}"
+            )
+        if budget.expanded_chars > JSONL_MAX_TOTAL_CHARS:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — expanded {budget.expanded_chars} chars (max {JSONL_MAX_TOTAL_CHARS})', Colors.YELLOW)}"
+            )
+        elif budget.skipped:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — {len(budget.skipped)} entries would be skipped at dispatch', Colors.YELLOW)}"
+            )
     else:
         print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
 

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

@@ -7,6 +7,7 @@ from pathlib import Path
 
 from .active_task import resolve_selected_task
 from .paths import DIR_TASKS, DIR_WORKFLOW, get_developer, get_repo_root, get_tasks_dir
+from .task_gates import verify_evidence_status
 from .task_map import get_child_state
 from .tasks import (
     children_progress,
@@ -23,6 +24,19 @@ def _task_path(dir_name: str) -> str:
     return f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
 
 
+def format_verify_summary(task_dir: Path, task_data: dict) -> str:
+    """Return a compact verify evidence label for dashboard task lines."""
+    verify_path = task_dir / "verify.md"
+    if not verify_path.is_file():
+        return "[verify: missing]"
+    status = verify_evidence_status(task_dir, task_data)
+    if all(status.values()):
+        return "[verify: ok]"
+    if any(status.values()):
+        return "[verify: partial]"
+    return "[verify: missing]"
+
+
 def _selected_line(
     repo_root: Path,
     platform_input: dict | None = None,
@@ -123,9 +137,10 @@ def _append_task(
         integration_state = get_child_state(parent_dir, name)
     status_display = format_child_task_display(task.status, integration_state)
     assignee = task.assignee or "-"
+    verify_summary = format_verify_summary(task.directory, task.raw or {})
     prefix = "  " * indent + "  - "
     lines.append(
-        f"{prefix}{_task_path(name)} ({status_display}){progress} [{assignee}]"
+        f"{prefix}{_task_path(name)} ({status_display}){progress} [{assignee}] {verify_summary}"
     )
     for child_name in task.children:
         if child_name in all_tasks:

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

@@ -127,6 +127,37 @@ def remove_child_from_task_map(
     write_task_map(parent_dir, data, body, f"Unlinked Child `{child_name}`.")
 
 
+def resolve_child_map_id(
+    parent_data: dict,
+    child_dir: Path,
+    child_data: dict | None = None,
+) -> str:
+    """Resolve task-map child id for a child directory (nested slash slugs)."""
+    structural = parent_data.get("children", [])
+    if not isinstance(structural, list):
+        structural = []
+
+    leaf = child_dir.name
+    if leaf in structural:
+        return leaf
+
+    if child_data:
+        for key in ("name", "id"):
+            value = child_data.get(key)
+            if isinstance(value, str) and value in structural:
+                return value
+
+    suffix_matches = [
+        cid
+        for cid in structural
+        if isinstance(cid, str) and (cid == leaf or cid.endswith(f"/{leaf}"))
+    ]
+    if len(suffix_matches) == 1:
+        return suffix_matches[0]
+
+    return leaf
+
+
 def set_child_state(
     parent_dir: Path,
     parent_data: dict,
@@ -183,7 +214,7 @@ def validate_parent_child_integration(
 ) -> list[str]:
     """Validate a Parent-controlled Child integration state transition."""
     errors: list[str] = []
-    child_name = child_dir.name
+    child_name = resolve_child_map_id(parent_data, child_dir, child_data)
     if state not in PARENT_CONTROLLED_STATES:
         errors.append(f"state is not Parent-controlled: {state}")
     if not _short_text(evidence):
@@ -295,10 +326,11 @@ def set_parent_child_integration_state(
     if errors:
         return False, errors
 
+    child_name = resolve_child_map_id(parent_data, child_dir, child_data)
     data = ensure_task_map(parent_dir, parent_data, list(parent_data.get("children", [])))
-    child = get_child_entry(data, child_dir.name)
+    child = get_child_entry(data, child_name)
     if child is None:
-        return False, [f"child missing from task-map.md: {child_dir.name}"]
+        return False, [f"child missing from task-map.md: {child_name}"]
 
     child["state"] = state
     child["evidence"] = evidence
@@ -316,12 +348,12 @@ def set_parent_child_integration_state(
         queue = []
         data["integration_queue"] = queue
     if state == "integrating":
-        if child_dir.name not in queue:
-            queue.append(child_dir.name)
-    elif child_dir.name in queue:
-        data["integration_queue"] = [item for item in queue if item != child_dir.name]
+        if child_name not in queue:
+            queue.append(child_name)
+    elif child_name in queue:
+        data["integration_queue"] = [item for item in queue if item != child_name]
 
-    event = f"Parent set Child `{child_dir.name}` integration state to `{state}`. Evidence: {evidence}."
+    event = f"Parent set Child `{child_name}` integration state to `{state}`. Evidence: {evidence}."
     if ref:
         event = f"{event} Ref: {ref}."
     if merge_ref:

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

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 """
 Task CRUD operations.
 
@@ -25,6 +25,11 @@ import sys
 from datetime import datetime
 from pathlib import Path
 
+from .artifact_locale import (
+    default_prd_content,
+    default_verify_content,
+    resolve_artifact_locale,
+)
 from .config import (
     get_packages,
     get_session_auto_commit,
@@ -67,6 +72,7 @@ from .task_map import (
     get_child_state,
     record_child_worktree,
     remove_child_from_task_map,
+    resolve_child_map_id,
     set_child_state,
     set_parent_child_integration_state,
     validate_parent_child_integration,
@@ -249,11 +255,10 @@ _SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
     ".pi",        # Pi Agent
 )
 
-_SEED_EXAMPLE = (
-    "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. "
-    "Put spec/research files only — no code paths. "
-    "Run `python .cstl/scripts/get_context.py --mode packages` to list available specs. "
-    "Delete this line once real entries are added."
+_STABLE_SPEC_SEED_PATHS: tuple[str, ...] = (
+    ".cstl/spec/guides/index.md",
+    ".cstl/spec/guides/verification-strength-guide.md",
+    ".cstl/spec/guides/injection-budget-guide.md",
 )
 
 
@@ -270,41 +275,70 @@ def _has_subagent_platform(repo_root: Path) -> bool:
     return False
 
 
-def _write_seed_jsonl(path: Path) -> None:
-    """Write a one-line seed JSONL file with a self-describing ``_example``.
-
-    The seed row has no ``file`` field, so downstream consumers (hooks +
-    preludes) that iterate entries via ``item.get("file")`` naturally skip
-    it. The row exists purely as an in-file prompt for the AI curator.
-    """
-    seed = {"_example": _SEED_EXAMPLE}
-    path.write_text(json.dumps(seed, ensure_ascii=False) + "\n", encoding="utf-8")
-
-
-def _default_prd_content(title: str, description: str | None = None) -> str:
-    """Return the default PRD skeleton created with every task."""
-    goal = (description or "").strip() or "TBD."
-    heading = title.strip() or "Untitled task"
-    return f"""# {heading}
-
-## Goal
-
-{goal}
-
-## Requirements
+def _resolve_seed_spec_paths(
+    repo_root: Path,
+    task_dir: Path,
+    task_data: dict,
+) -> list[str]:
+    """Return 2–3 existing spec file paths for jsonl create seeds."""
+    from .task_gates import suggest_spec_targets
+
+    candidates: list[str] = []
+    for path in suggest_spec_targets(repo_root, task_dir, task_data):
+        if path not in candidates:
+            candidates.append(path)
+    for rel in _STABLE_SPEC_SEED_PATHS:
+        if rel not in candidates:
+            candidates.append(rel)
+
+    existing = [rel for rel in candidates if (repo_root / rel).is_file()]
+    if len(existing) >= 2:
+        return existing[:3]
+
+    fallback = [
+        rel for rel in _STABLE_SPEC_SEED_PATHS if (repo_root / rel).is_file()
+    ]
+    return fallback[:3]
 
-- TBD
 
-## Acceptance Criteria
+def _write_seed_jsonl(
+    path: Path,
+    repo_root: Path,
+    task_dir: Path,
+    task_data: dict,
+) -> None:
+    """Write 2–3 JSONL rows with real spec ``file`` paths for sub-agent context."""
+    spec_paths = _resolve_seed_spec_paths(repo_root, task_dir, task_data)
+    if len(spec_paths) < 2:
+        raise ValueError(
+            "task create requires at least two existing spec guide paths for jsonl seed"
+        )
 
-- [ ] TBD
+    lines: list[str] = []
+    for spec_path in spec_paths:
+        lines.append(
+            json.dumps(
+                {
+                    "file": spec_path,
+                    "reason": "default spec seed — curate entries for this task",
+                },
+                ensure_ascii=False,
+            )
+        )
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
-## Notes
 
-- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
-- Lightweight tasks can remain PRD-only.
-- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start-execution --check`.
-"""
+def _default_prd_content(
+    title: str,
+    description: str | None = None,
+    *,
+    repo_root: Path | None = None,
+    task_dir: Path | None = None,
+) -> str:
+    """Return the default PRD skeleton created with every task."""
+    root = repo_root or get_repo_root()
+    locale = resolve_artifact_locale(task_dir, root)
+    return default_prd_content(title, description, locale, root)
 
 
 # =============================================================================
@@ -412,7 +446,14 @@ def cmd_create(args: argparse.Namespace) -> int:
     prd_path = task_dir / "prd.md"
     if not prd_path.exists():
         prd_path.write_text(
-            _default_prd_content(args.title, args.description),
+            _default_prd_content(args.title, args.description, repo_root=repo_root, task_dir=task_dir),
+            encoding="utf-8",
+        )
+
+    verify_path = task_dir / "verify.md"
+    if not verify_path.exists():
+        verify_path.write_text(
+            default_verify_content(repo_root=repo_root, task_dir=task_dir),
             encoding="utf-8",
         )
 
@@ -425,7 +466,7 @@ def cmd_create(args: argparse.Namespace) -> int:
         for jsonl_name in ("implement.jsonl", "check.jsonl"):
             jsonl_path = task_dir / jsonl_name
             if not jsonl_path.exists():
-                _write_seed_jsonl(jsonl_path)
+                _write_seed_jsonl(jsonl_path, repo_root, task_dir, task_data)
         seeded_jsonl = True
 
     # Handle --parent: establish bidirectional link
@@ -1136,10 +1177,11 @@ def cmd_set_child_state(args: argparse.Namespace) -> int:
         )
         return 1
 
+    child_map_id = resolve_child_map_id(parent_data, child_dir, child_data)
     ok, errors = set_child_state(
         parent_dir,
         parent_data,
-        child_dir.name,
+        child_map_id,
         state,
         args.evidence,
         getattr(args, "reason", None),
@@ -1265,6 +1307,29 @@ def cmd_integrate_child(args: argparse.Namespace) -> int:
     if merge_ref:
         print(f"Merge executed: git merge --no-ff --no-commit {merge_ref}")
     print(f"Parent map: {_repo_relative_path(parent_dir / 'task-map.md', repo_root)}")
+
+    if state == "integrated" and not getattr(args, "no_publish_pack", False):
+        from .parent_orchestration import build_publish_pack
+
+        summary, pack_errors = build_publish_pack(parent_dir)
+        if pack_errors or summary is None:
+            for item in pack_errors:
+                print(f"  - {item}", file=sys.stderr)
+            print(
+                colored(
+                    "Warning: integrate succeeded but publish-pack failed; "
+                    "PACK may be stale (see parent-status stalePack).",
+                    Colors.YELLOW,
+                ),
+                file=sys.stderr,
+            )
+            return 2
+        print(colored("✓ PACK refreshed after integrate", Colors.GREEN))
+        for line in summary.splitlines():
+            if line.startswith("- Generated:"):
+                print(line)
+                break
+
     return 0
 
 
@@ -1638,3 +1703,43 @@ def cmd_set_scope(args: argparse.Namespace) -> int:
 
     print(colored(f"✓ Scope set to: {scope}", Colors.GREEN))
     return 0
+
+
+# =============================================================================
+# Command: artifact-locale
+# =============================================================================
+
+def cmd_artifact_locale(args: argparse.Namespace) -> int:
+    """Get or set human-reviewed artifact locale (zh | en)."""
+    from .artifact_locale import (
+        resolve_artifact_locale,
+        set_task_artifact_locale,
+        set_workspace_artifact_locale,
+    )
+
+    repo_root = get_repo_root()
+    subcommand = getattr(args, "artifact_locale_command", None)
+
+    if subcommand == "get":
+        task_dir = resolve_task_dir(args.task, repo_root) if args.task else None
+        print(resolve_artifact_locale(task_dir, repo_root))
+        return 0
+
+    if subcommand == "set":
+        try:
+            if args.task:
+                task_dir = resolve_task_dir(args.task, repo_root)
+                set_task_artifact_locale(task_dir, args.locale, repo_root)
+                scope = f"task {task_dir.name}"
+            else:
+                set_workspace_artifact_locale(args.locale, repo_root)
+                scope = "workspace"
+        except (ValueError, FileNotFoundError) as exc:
+            print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+            return 1
+
+        print(colored(f"✓ artifact_locale set to {args.locale} ({scope})", Colors.GREEN))
+        return 0
+
+    print(colored("Error: use artifact-locale get|set", Colors.RED), file=sys.stderr)
+    return 1