@blxzer/cursor-trellis 0.3.6 → 0.4.1

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/pool.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Review-pool CLI: validate / plan-check / link / unlink / show.
+
+Usage:
+    python pool.py validate [--root <repo>]
+    python pool.py plan-check [--root <repo>]
+    python pool.py link <item-id> <task-ref> [--root <repo>]
+    python pool.py unlink <item-id> <task-ref> [--root <repo>]
+    python pool.py show <item-id> [--root <repo>]
+
+Exit codes: any error-level finding (or a failed link/unlink/show) -> 1;
+warnings only -> 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from common.io import read_json
+from common.log import Colors, colored
+from common.paths import get_repo_root
+from common import pool_store
+
+
+def _print_issue(issue: pool_store.Issue) -> None:
+    color = Colors.RED if issue.is_error else Colors.YELLOW
+    level = "error" if issue.is_error else "warning"
+    location = f" ({issue.path})" if issue.path is not None else ""
+    print(colored(f"[{level}] {issue.code}: {issue.message}{location}", color))
+
+
+def _exit_for_issues(issues: list[pool_store.Issue]) -> int:
+    errors = [issue for issue in issues if issue.is_error]
+    warnings = [issue for issue in issues if not issue.is_error]
+    for issue in issues:
+        _print_issue(issue)
+    if not issues:
+        print(colored("OK", Colors.GREEN))
+    elif not errors:
+        print(colored(f"OK with {len(warnings)} warning(s)", Colors.GREEN))
+    else:
+        print(colored(f"{len(errors)} error(s), {len(warnings)} warning(s)", Colors.RED))
+    return 1 if errors else 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    issues = pool_store.validate_pool(args.root)
+    return _exit_for_issues(issues)
+
+
+def cmd_plan_check(args: argparse.Namespace) -> int:
+    issues = pool_store.check_plan(args.root)
+    return _exit_for_issues(issues)
+
+
+def cmd_link(args: argparse.Namespace) -> int:
+    result = pool_store.link_item_task(args.root, args.item_id, args.task_ref)
+    for issue in result.errors:
+        _print_issue(issue)
+    if not result.ok:
+        return 1
+    print(colored(f"linked {result.item_id} <-> {result.task_ref}", Colors.GREEN))
+    item = pool_store.load_item(args.root, result.item_id)
+    if item is not None:
+        print(f"  item.linked_tasks: {item.linked_tasks or '[]'}")
+    data = read_json(result.task_path / "task.json") if result.task_path else None
+    if data is not None:
+        print(f"  task.meta.pool_items: {pool_store.get_pool_items(data) or '[]'}")
+    return 0
+
+
+def cmd_unlink(args: argparse.Namespace) -> int:
+    result = pool_store.unlink_item_task(args.root, args.item_id, args.task_ref)
+    for issue in result.errors:
+        _print_issue(issue)
+    if not result.ok:
+        return 1
+    for issue in result.warnings:
+        _print_issue(issue)
+    print(colored(f"unlinked {result.item_id} <-> {result.task_ref}", Colors.GREEN))
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    item = pool_store.load_item(args.root, args.item_id)
+    if item is None:
+        print(
+            colored(
+                f"[error] item-not-found: pool item {args.item_id!r} not found",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+    tasks_dir = args.root / ".cstl" / "tasks"
+    print(f"id: {item.id or '<missing>'}")
+    print(f"title: {item.title or '<missing>'}")
+    print(f"status: {item.status or '<missing>'}")
+    print(f"type: {item.type or '<missing>'}")
+    print(f"path: {item.path}")
+    if not item.linked_tasks:
+        print("linked_tasks: []")
+    for ref in item.linked_tasks:
+        task_dir = pool_store.find_task_dir(ref, tasks_dir)
+        if task_dir is None:
+            print(f"linked_tasks: {ref} (missing)")
+            continue
+        data = read_json(task_dir / "task.json") or {}
+        status = data.get("status", "?")
+        archived = "archive/" in task_dir.as_posix()
+        suffix = " (archived)" if archived else ""
+        print(f"linked_tasks: {ref} -> {task_dir.name} ({status}){suffix}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pool.py",
+        description="Review-pool maintenance CLI: validate, plan-check, link, unlink, show.",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="Repository root. Defaults to nearest parent containing .cstl/.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_root(entry_parser: argparse.ArgumentParser) -> None:
+        # SUPPRESS so a missing subcommand --root never clobbers the global
+        # --root with None (argparse subparser defaults overwrite parent values).
+        entry_parser.add_argument(
+            "--root",
+            type=Path,
+            default=argparse.SUPPRESS,
+            help="Repository root (overrides the global --root).",
+        )
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate pool entries (sections, frontmatter, links, consistency).",
+    )
+    add_root(validate_parser)
+    plan_parser = subparsers.add_parser(
+        "plan-check",
+        help="Check plan.md references against known pool item ids.",
+    )
+    add_root(plan_parser)
+    link_parser = subparsers.add_parser(
+        "link",
+        help="Link a pool item to a task on both sides (idempotent).",
+    )
+    add_root(link_parser)
+    link_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    link_parser.add_argument("task_ref", help="Task dir name or resolvable ref")
+    unlink_parser = subparsers.add_parser(
+        "unlink",
+        help="Remove the item<->task link on both sides (best-effort).",
+    )
+    add_root(unlink_parser)
+    unlink_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    unlink_parser.add_argument("task_ref", help="Task dir name or resolvable ref")
+    show_parser = subparsers.add_parser(
+        "show",
+        help="Print one pool item with linked task statuses.",
+    )
+    add_root(show_parser)
+    show_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = getattr(args, "root", None)
+    args.root = root.resolve() if root is not None else get_repo_root()
+
+    handlers = {
+        "validate": cmd_validate,
+        "plan-check": cmd_plan_check,
+        "link": cmd_link,
+        "unlink": cmd_unlink,
+        "show": cmd_show,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -17,6 +17,8 @@ Usage:
     python task.py set-branch <dir> <branch>   # Set git branch
     python task.py set-base-branch <dir> <branch>  # Set PR target branch
     python task.py set-scope <dir> <scope>     # Set scope for PR title
+    python task.py set-deps <dir> <id...>      # Set task-level depends_on (soft checks)
+    python task.py set-depends-mode <dir> <warn|block|off>  # Dependency policy mode
     python task.py archive <task-dir> [--check] [--archive-integrated-children] # Check or archive completed task
     python task.py prepare-archive-evidence <task-dir> [--dry-run]  # Draft missing verify.md archive evidence
     python task.py prepare-learning-scaffold <task-dir> [--trigger <text>]  # Print spec-capture checklist (stdout only)
@@ -69,6 +71,7 @@ from common.task_gates import (
     write_gate_record,
 )
 from common.task_utils import resolve_task_dir, run_task_hooks
+from common.task_dependencies import read_depends_mode
 from common.tasks import (
     children_progress,
     format_child_task_display,
@@ -86,6 +89,9 @@ from common.task_store import (
     cmd_set_branch,
     cmd_set_base_branch,
     cmd_set_scope,
+    cmd_set_deps,
+    cmd_set_depends_mode,
+    append_depends_ignore_event,
     cmd_add_subtask,
     cmd_remove_subtask,
     cmd_prepare_child_worktree,
@@ -241,6 +247,15 @@ def _print_guard_errors(items: list[str], stream=None) -> None:
         print(f"  - {item}", file=stream)
 
 
+def _print_dependency_warnings(guard) -> None:
+    """Print dependency warnings (Plan A soft checks; never affect PASS/FAIL)."""
+    for warning in guard.warnings:
+        print(
+            colored(f"[dependencies] WARN: {warning}", Colors.YELLOW),
+            file=sys.stderr,
+        )
+
+
 def cmd_start_execution(args: argparse.Namespace) -> int:
     """Start approved task execution after a non-mutating readiness check."""
     repo_root = get_repo_root()
@@ -259,6 +274,7 @@ def cmd_start_execution(args: argparse.Namespace) -> int:
             for hint in start_execution_repair_hints(guard.errors, task_dir):
                 print(f"  Hint: {hint}")
             return 1
+        _print_dependency_warnings(guard)
         print(colored("Start-execution check: PASS", Colors.GREEN))
         print(f"Contract fingerprint: {guard.contract_fingerprint}")
         baseline_fingerprint = guard.artifact_fingerprints.get(BASELINE_GATE)
@@ -294,13 +310,29 @@ def cmd_start_execution(args: argparse.Namespace) -> int:
         print("Run with --check for non-mutating preflight or --approved after explicit user approval.", file=sys.stderr)
         return 1
 
-    guard = validate_start_execution(task_dir, task_data, approved=True)
+    ignore_deps = bool(getattr(args, "ignore_deps", False))
+    guard = validate_start_execution(
+        task_dir,
+        task_data,
+        approved=True,
+        ignore_deps=ignore_deps,
+        enforce_deps_block=True,
+    )
     if not guard.ok:
         print(colored("Error: cannot start execution; readiness check failed.", Colors.RED), file=sys.stderr)
         _print_guard_errors(guard.errors, stream=sys.stderr)
         return 1
 
+    _print_dependency_warnings(guard)
+
     assert task_data is not None
+    if ignore_deps and guard.deps_blocking_summary:
+        append_depends_ignore_event(
+            task_data,
+            command="start-execution",
+            mode=read_depends_mode(task_data),
+            blocking_summary=guard.deps_blocking_summary,
+        )
     if guard.baseline_record:
         write_gate_record(task_data, "start-execution", BASELINE_GATE, guard.baseline_record)
     for gate, record in guard.auto_gate_records.items():
@@ -537,6 +569,7 @@ Usage:
   python task.py set-branch <dir> <branch>          Set git branch
   python task.py set-base-branch <dir> <branch>     Set PR target branch
   python task.py set-scope <dir> <scope>            Set scope for PR title
+  python task.py set-deps <dir> [dep ...]           Set depends_on (no deps clears to [])
   python task.py archive <task-dir> [--check]       Check or archive completed task
   python task.py add-subtask <parent> <child>       Link child task to parent
   python task.py remove-subtask <parent> <child>    Unlink child from parent
@@ -672,6 +705,11 @@ def main() -> int:
                                    help="Run non-mutating execution readiness check")
     p_start_execution.add_argument("--approved", action="store_true",
                                    help="Record explicit approval and start execution")
+    p_start_execution.add_argument(
+        "--ignore-deps",
+        action="store_true",
+        help="Override blocking dependencies (depends_mode=block) and record an audit event",
+    )
 
     # record-gate
     p_record_gate = subparsers.add_parser("record-gate", help="Record reviewer quality gate")
@@ -708,6 +746,31 @@ def main() -> int:
     p_scope.add_argument("dir", help="Task directory")
     p_scope.add_argument("scope", help="Scope name")
 
+    # set-deps
+    p_deps = subparsers.add_parser(
+        "set-deps",
+        help="Set task-level depends_on (declare only; soft checks in Plan A)",
+    )
+    p_deps.add_argument("dir", help="Task directory or name")
+    p_deps.add_argument(
+        "dep",
+        nargs="*",
+        help="Dependency task ids (bare id or pool:Pxx). No deps clears to [].",
+    )
+
+    # set-depends-mode
+    p_depends_mode = subparsers.add_parser(
+        "set-depends-mode",
+        help="Set meta.depends_mode (warn | block | off) for dependency policy",
+    )
+    p_depends_mode.add_argument("dir", help="Task directory or name")
+    p_depends_mode.add_argument(
+        "mode",
+        choices=["warn", "block", "off"],
+        help="warn = Plan A soft checks (default); block = hard gates at "
+        "start-execution --approved and set-child-state working; off = silent",
+    )
+
     # artifact-locale
     p_artifact_locale = subparsers.add_parser(
         "artifact-locale",
@@ -939,6 +1002,8 @@ def main() -> int:
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,
         "set-scope": cmd_set_scope,
+        "set-deps": cmd_set_deps,
+        "set-depends-mode": cmd_set_depends_mode,
         "archive": cmd_archive,
         "prepare-archive-evidence": cmd_prepare_archive_evidence,
         "prepare-learning-scaffold": cmd_prepare_learning_scaffold,