@blxzer/cursor-trellis 0.3.6 → 0.4.0

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

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 """
 Task quality gate helpers.
 
@@ -15,6 +15,11 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 
+from .task_dependencies import (
+    describe_dependencies,
+    read_depends_mode,
+    scope_children_for_task,
+)
 from .task_map import (
     get_child_state,
     load_task_map,
@@ -144,6 +149,7 @@ STABLE_TASK_KEYS = (
     "kind",
     "mode",
     "contract_epoch",
+    "depends_on",
 )
 
 
@@ -161,6 +167,7 @@ class GateGuardResult:
     is_full_task: bool = False
     closeout_profile: str = "lite"
     auto_gate_records: dict[str, dict] = field(default_factory=dict)
+    deps_blocking_summary: list[str] = field(default_factory=list)
 
 
 def utc_now() -> str:
@@ -610,8 +617,19 @@ def validate_start_execution(
     task_dir: Path,
     task_data: dict | None,
     approved: bool,
+    *,
+    ignore_deps: bool = False,
+    enforce_deps_block: bool = False,
 ) -> GateGuardResult:
-    """Validate start-execution readiness."""
+    """Validate start-execution readiness.
+
+    Dependency policy (Plan B, per adjudication 05 §3.1/§3.2):
+    - enforce_deps_block=True is passed ONLY by the mutating `--approved` path.
+      mode=block + unmet deps then fail unless ignore_deps=True.
+    - mode=off silences dependency warnings entirely.
+    - every other path (--check, warn mode) keeps Plan A semantics: deps are
+      warnings that never fail the guard.
+    """
     errors: list[str] = []
     if task_data is None:
         return GateGuardResult(ok=False, errors=["task.json"])
@@ -691,6 +709,29 @@ def validate_start_execution(
     if not approved:
         errors.append("--approved is required for mutation")
 
+    warnings: list[str] = []
+    deps_blocking_summary: list[str] = []
+    if task_data is not None:
+        scope = scope_children_for_task(task_dir, task_data)
+        report = describe_dependencies(
+            task_dir,
+            task_data,
+            scope_children=scope,
+        )
+        depends_mode = read_depends_mode(task_data)
+        if enforce_deps_block and depends_mode == "block":
+            deps_blocking_summary = report.blocking_errors()
+            if ignore_deps:
+                warnings.extend(report.warnings())
+            else:
+                errors.extend(deps_blocking_summary)
+        elif depends_mode != "off":
+            warnings.extend(report.warnings())
+            if depends_mode == "block" and not enforce_deps_block:
+                warnings.append(
+                    "dependency policy mode=block: --approved would fail unless --ignore-deps"
+                )
+
     baseline_record = None
     if not errors:
         baseline_record = make_baseline_record(
@@ -700,12 +741,14 @@ def validate_start_execution(
     return GateGuardResult(
         ok=not errors,
         errors=errors,
+        warnings=warnings,
         contract_fingerprint=contract_fingerprint,
         artifact_fingerprints=artifact_fingerprints,
         required_gates=required_gates,
         baseline_record=baseline_record,
         is_full_task=full_task,
         auto_gate_records=auto_gate_records,
+        deps_blocking_summary=deps_blocking_summary,
     )
 
 
@@ -737,9 +780,19 @@ def validate_start_execution_check(
     task_dir: Path,
     task_data: dict | None,
 ) -> GateGuardResult:
-    """Validate start-execution preflight without requiring approval."""
-    result = validate_start_execution(task_dir, task_data, approved=True)
-    return result
+    """Validate start-execution preflight without requiring approval.
+
+    NOTE (adjudication 05 §3.1 trap): the check path deliberately passes
+    enforce_deps_block=False — even when the task is in mode=block, --check
+    must never fail on dependencies; it only surfaces warnings. Only the
+    mutating --approved path may set enforce_deps_block=True.
+    """
+    return validate_start_execution(
+        task_dir,
+        task_data,
+        approved=True,
+        enforce_deps_block=False,
+    )
 
 
 def validate_transition_readiness(

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

@@ -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
@@ -1127,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
 # =============================================================================
@@ -1178,6 +1303,18 @@ 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,
@@ -1705,6 +1842,125 @@ def cmd_set_scope(args: argparse.Namespace) -> int:
     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
 # =============================================================================