@blxzer/cursor-trellis 0.3.5 → 0.4.0

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

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 """
 Task CRUD operations.
 
@@ -9,6 +9,8 @@ Provides:
     cmd_set_branch     - Set git branch for task
     cmd_set_base_branch - Set PR target branch
     cmd_set_scope      - Set scope for PR title
+    cmd_set_deps       - Set task-level depends_on (declare + soft checks)
+    cmd_set_depends_mode - Set meta.depends_mode (warn | block | off)
     cmd_add_subtask    - Link child task to parent
     cmd_remove_subtask - Unlink child task from parent
     cmd_prepare_child_worktree - Create/register Child git worktree
@@ -25,6 +27,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 +74,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 +257,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 +277,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 +448,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 +468,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
@@ -1086,6 +1129,129 @@ def cmd_prepare_child_worktree(args: argparse.Namespace) -> int:
     return 0
 
 
+# =============================================================================
+# Plan B: depends_mode block helpers
+# =============================================================================
+
+def append_depends_ignore_event(
+    task_data: dict,
+    *,
+    command: str,
+    mode: str,
+    blocking_summary: list[str],
+    evidence: str | None = None,
+    reason: str | None = None,
+) -> None:
+    """Append a depends-ignore audit event to meta.depends_ignore_events.
+
+    Mutates task_data in memory; the caller persists it in the SAME
+    write_json as the mutation it accompanies (execution approval / child
+    state), so the event can never dangle as a separate stale write. The
+    list is capped at MAX_IGNORE_EVENTS (FIFO drops the oldest entry).
+    """
+    from .task_dependencies import MAX_IGNORE_EVENTS
+    from .task_map import utc_now
+
+    meta = task_data.get("meta")
+    if not isinstance(meta, dict):
+        meta = {}
+        task_data["meta"] = meta
+    events = meta.get("depends_ignore_events")
+    if not isinstance(events, list):
+        events = []
+    event: dict = {
+        "at": utc_now(),
+        "command": command,
+        "by": "user",
+        "mode": mode,
+        "blocking_summary": list(blocking_summary),
+    }
+    if evidence:
+        event["evidence"] = evidence
+    if reason:
+        event["reason"] = reason
+    events.append(event)
+    del events[:-MAX_IGNORE_EVENTS]
+    meta["depends_ignore_events"] = events
+
+
+def _guard_child_working_deps(
+    args: argparse.Namespace,
+    parent_dir: Path,
+    parent_data: dict,
+    child_dir: Path,
+    child_data: dict,
+    child_map_id: str,
+) -> int:
+    """Enforce depends_mode=block before a Child transitions to `working`.
+
+    Reads the CHILD's meta.depends_mode (the Parent mode never proxies for
+    the Child). The dependency union covers the Child task.json depends_on
+    plus the Parent task-map children[].depends_on entry; either source
+    blocking rejects the transition unless --ignore-deps is passed, which
+    appends an audit event to the Child task.json and a line to the Parent
+    task-map Event Log. Returns 0 to allow, nonzero to reject.
+    """
+    from .task_dependencies import describe_child_dependencies, read_depends_mode
+    from .task_map import get_child_entry, load_task_map, write_task_map
+
+    mode = read_depends_mode(child_data)
+    if mode != "block":
+        return 0
+
+    repo_root = get_repo_root()
+    map_data, _ = load_task_map(parent_dir)
+    entry = get_child_entry(map_data, child_map_id)
+    report = describe_child_dependencies(
+        child_dir, child_data, entry, repo_root=repo_root
+    )
+    blocking = report.blocking_errors()
+    if not blocking:
+        return 0
+
+    if not getattr(args, "ignore_deps", False):
+        print(
+            colored(
+                "Error: cannot set Child state to 'working': blocking dependencies "
+                "(depends_mode=block).",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        for item in blocking:
+            print(f"  - {item}", file=sys.stderr)
+        print(
+            "Run with --ignore-deps to override (audited via meta.depends_ignore_events).",
+            file=sys.stderr,
+        )
+        return 1
+
+    append_depends_ignore_event(
+        child_data,
+        command="set-child-state",
+        mode=mode,
+        blocking_summary=blocking,
+        evidence=args.evidence,
+        reason=getattr(args, "reason", None),
+    )
+    child_json_path = child_dir / FILE_TASK_JSON
+    if not write_json(child_json_path, child_data):
+        print(
+            colored("Error: failed to write task.json (ignore event)", Colors.RED),
+            file=sys.stderr,
+        )
+        return 1
+
+    map_data_evt, map_body = load_task_map(parent_dir)
+    if map_data_evt is not None:
+        event = (
+            f"Ignored dependencies (mode=block) for child `{child_dir.name}` "
+            f"while setting state `working`: {'; '.join(blocking)}"
+        )
+        write_task_map(parent_dir, map_data_evt, map_body, event)
+    return 0
+
+
 # =============================================================================
 # Command: set-child-state
 # =============================================================================
@@ -1136,10 +1302,23 @@ def cmd_set_child_state(args: argparse.Namespace) -> int:
         )
         return 1
 
+    child_map_id = resolve_child_map_id(parent_data, child_dir, child_data)
+    if state == "working":
+        guard_rc = _guard_child_working_deps(
+            args,
+            parent_dir,
+            parent_data,
+            child_dir,
+            child_data,
+            child_map_id,
+        )
+        if guard_rc != 0:
+            return guard_rc
+
     ok, errors = set_child_state(
         parent_dir,
         parent_data,
-        child_dir.name,
+        child_map_id,
         state,
         args.evidence,
         getattr(args, "reason", None),
@@ -1265,6 +1444,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 +1840,162 @@ def cmd_set_scope(args: argparse.Namespace) -> int:
 
     print(colored(f"✓ Scope set to: {scope}", Colors.GREEN))
     return 0
+
+
+# =============================================================================
+# Command: set-deps
+# =============================================================================
+
+def cmd_set_deps(args: argparse.Namespace) -> int:
+    """Set task-level depends_on (Plan A: declare + soft checks, no blocking).
+
+    Bare task ids and `pool:Pxx` refs are supported. Dangling references are
+    warned but still written (Plan A is discovery-first; `warn` never errors).
+    """
+    from .task_dependencies import KIND_MISSING, normalize_dep_list, resolve_dep_ref
+
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(
+            colored(f"Error: task.json not found at {target_dir}", Colors.RED),
+            file=sys.stderr,
+        )
+        return 1
+
+    data = read_json(task_json)
+    if not data:
+        return 1
+
+    normalized = normalize_dep_list(args.dep)
+    data["depends_on"] = normalized
+
+    dangling = [
+        ref
+        for ref in normalized
+        if resolve_dep_ref(ref, repo_root=repo_root).kind == KIND_MISSING
+    ]
+
+    if not write_json(task_json, data):
+        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    if normalized:
+        print(
+            colored(
+                f"✓ depends_on set: {', '.join(normalized)}",
+                Colors.GREEN,
+            )
+        )
+    else:
+        print(colored("✓ depends_on cleared to []", Colors.GREEN))
+    for ref in dangling:
+        print(
+            colored(
+                f"[dependencies] WARN: dangling dependency: {ref} "
+                "(no matching task or child; declaration kept)",
+                Colors.YELLOW,
+            ),
+            file=sys.stderr,
+        )
+    return 0
+
+
+# =============================================================================
+# Command: set-depends-mode
+# =============================================================================
+
+def cmd_set_depends_mode(args: argparse.Namespace) -> int:
+    """Set meta.depends_mode (warn | block | off) for a task.
+
+    warn is the default (= Plan A soft checks); block opts the task into
+    hard dependency gates at start-execution --approved and
+    set-child-state working; off silences dependency output entirely.
+    """
+    from .task_dependencies import DEPENDS_MODES, read_depends_mode
+
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(
+            colored(f"Error: task.json not found at {target_dir}", Colors.RED),
+            file=sys.stderr,
+        )
+        return 1
+
+    data = read_json(task_json)
+    if not data:
+        return 1
+
+    previous = read_depends_mode(data)
+    if args.mode not in DEPENDS_MODES:
+        print(
+            colored(
+                f"Error: depends_mode must be one of {', '.join(DEPENDS_MODES)}",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+    meta = data.get("meta")
+    if not isinstance(meta, dict):
+        meta = {}
+        data["meta"] = meta
+    meta["depends_mode"] = args.mode
+
+    if not write_json(task_json, data):
+        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    print(
+        colored(
+            f"✓ depends_mode: {previous} -> {args.mode}",
+            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