@blxzer/cursor-trellis 0.1.0

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

@@ -0,0 +1,851 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Task Management Script.
+
+Usage:
+    python task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>]
+    python task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
+    python task.py validate <dir>              # Validate jsonl files
+    python task.py list-context <dir>          # List jsonl entries
+    python task.py dashboard                   # Show Task Dashboard
+    python task.py select <dir>                # Select task for this live session
+    python task.py selected [--source]         # Show selected task
+    python task.py start-execution <dir> --approved  # Start approved execution
+    python task.py record-gate <dir> --transition <key> --gate <gate> --result PASS|FAIL|SKIPPED --reviewer <id> --evidence <ref> [--root-cause <cause>]
+    python task.py exit                        # Clear selected task
+    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 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)
+    python task.py list                        # List active tasks
+    python task.py list-archive [month]        # List archived tasks
+    python task.py add-subtask <parent-dir> <child-dir>     # Link child to parent
+    python task.py remove-subtask <parent-dir> <child-dir>  # Unlink child from parent
+    python task.py prepare-child-worktree <parent-dir> <child-dir> --branch <branch>
+    python task.py set-child-state <parent-dir> <child-dir> <state> --evidence <ref>
+    python task.py integrate-child <parent-dir> <child-dir> <state> --evidence <ref>
+    python task.py generate-child-prompt <parent-dir> <child-dir> [--mode inline|subagent]
+    python task.py parent-status <parent-dir>
+    python task.py review-child <parent-dir> <child-dir> [--check] [--decision accept|changes|cancel|integrate-through]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from common.log import Colors, colored
+from common.paths import (
+    DIR_WORKFLOW,
+    DIR_TASKS,
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+)
+from common.active_task import (
+    clear_selected_task,
+    resolve_context_key,
+    resolve_selected_task,
+    set_selected_task,
+)
+from common.io import read_json, write_json
+from common.task_dashboard import render_task_dashboard
+from common.cli_environment import optional_capability_note
+from common.task_gates import (
+    BASELINE_GATE,
+    build_reviewer_gate_record,
+    read_strategy_contract,
+    start_execution_repair_hints,
+    validate_start_execution,
+    validate_start_execution_check,
+    write_gate_record,
+)
+from common.task_utils import resolve_task_dir, run_task_hooks
+from common.tasks import (
+    children_progress,
+    format_child_task_display,
+    iter_active_tasks,
+    load_parent_child_integration_states,
+)
+from common.task_map import get_child_state
+
+# Import command handlers from split modules (also re-exports for plan.py compatibility)
+from common.task_store import (
+    cmd_create,
+    cmd_archive,
+    cmd_prepare_archive_evidence,
+    cmd_prepare_learning_scaffold,
+    cmd_set_branch,
+    cmd_set_base_branch,
+    cmd_set_scope,
+    cmd_add_subtask,
+    cmd_remove_subtask,
+    cmd_prepare_child_worktree,
+    cmd_set_child_state,
+    cmd_integrate_child,
+    cmd_generate_child_prompt,
+    cmd_parent_status,
+    cmd_review_child,
+)
+from common.task_context import (
+    cmd_add_context,
+    cmd_validate,
+    cmd_list_context,
+)
+
+
+# =============================================================================
+# Command: dashboard / select / selected / start-execution / record-gate / exit
+# =============================================================================
+
+def _repo_relative(path, repo_root) -> str:
+    try:
+        return path.relative_to(repo_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _resolve_existing_task(task_input: str, repo_root):
+    full_path = resolve_task_dir(task_input, repo_root)
+    if not full_path.is_dir():
+        print(colored(f"Error: Task not found: {task_input}", Colors.RED), file=sys.stderr)
+        print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.trellis/tasks/01-31-my-task')", file=sys.stderr)
+        return None
+    return full_path
+
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    """Show Task Dashboard without mutating selection or status."""
+    _ = args
+    print(render_task_dashboard(get_repo_root()))
+    return 0
+
+
+def cmd_select(args: argparse.Namespace) -> int:
+    """Select a task for this live session without changing task.status."""
+    repo_root = get_repo_root()
+    task_input = args.dir
+    full_path = _resolve_existing_task(task_input, repo_root)
+    if full_path is None:
+        return 1
+
+    if not resolve_context_key():
+        print(
+            colored("Error: session identity not available; selected_task was not persisted.", Colors.RED),
+            file=sys.stderr,
+        )
+        print(
+            "Hint: run inside an AI session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py select.",
+            file=sys.stderr,
+        )
+        return 1
+
+    selected = set_selected_task(_repo_relative(full_path, repo_root), repo_root)
+    if not selected:
+        print(colored("Error: failed to select task", Colors.RED), file=sys.stderr)
+        return 1
+
+    print(colored(f"✓ Selected task: {selected.task_path}", Colors.GREEN))
+    print(f"Source: {selected.source}")
+    print("Task status unchanged.")
+    return 0
+
+
+def _print_no_selected_task_guidance() -> None:
+    """Explain why no task is selected and what to run next."""
+    print(colored("No task selected for this live session.", Colors.YELLOW), file=sys.stderr)
+    print("Next actions:", file=sys.stderr)
+    print(
+        "  - Route work: python ./.trellis/scripts/task.py dashboard",
+        file=sys.stderr,
+    )
+    print(
+        "  - Select a task: python ./.trellis/scripts/task.py select <task-dir>",
+        file=sys.stderr,
+    )
+    print(
+        "  - List active tasks: python ./.trellis/scripts/task.py list",
+        file=sys.stderr,
+    )
+    print(
+        "  - Persist selection in shells: set TRELLIS_CONTEXT_ID (or use your platform session hook)",
+        file=sys.stderr,
+    )
+
+
+def cmd_selected(args: argparse.Namespace) -> int:
+    """Show selected task."""
+    repo_root = get_repo_root()
+    selected = resolve_selected_task(repo_root)
+
+    if args.source:
+        print(f"Selected task: {selected.task_path or '(none)'}")
+        print(f"Source: {selected.source}")
+        if selected.stale:
+            print("State: stale")
+        if not selected.task_path:
+            _print_no_selected_task_guidance()
+        return 0 if selected.task_path else 1
+
+    if selected.task_path:
+        print(selected.task_path)
+        return 0
+
+    _print_no_selected_task_guidance()
+    return 1
+
+
+def cmd_exit(args: argparse.Namespace) -> int:
+    """Clear selected task for this live session without changing task.status."""
+    _ = args
+    repo_root = get_repo_root()
+    selected = clear_selected_task(repo_root)
+    if not selected.task_path:
+        print(colored("No selected task set", Colors.YELLOW))
+        return 0
+
+    print(colored(f"✓ Cleared selected task (was: {selected.task_path})", Colors.GREEN))
+    print(f"Source: {selected.source}")
+    print("Task status unchanged.")
+    return 0
+
+
+def _print_guard_errors(items: list[str], stream=None) -> None:
+    if stream is None:
+        stream = sys.stdout
+    for item in items:
+        print(f"  - {item}", file=stream)
+
+
+def cmd_start_execution(args: argparse.Namespace) -> int:
+    """Start approved task execution after a non-mutating readiness check."""
+    repo_root = get_repo_root()
+    task_dir = _resolve_existing_task(args.dir, repo_root)
+    if task_dir is None:
+        return 1
+
+    task_json_path = task_dir / FILE_TASK_JSON
+    task_data = read_json(task_json_path) if task_json_path.is_file() else None
+
+    if args.check:
+        guard = validate_start_execution_check(task_dir, task_data)
+        if not guard.ok:
+            print(colored("Start-execution check: FAIL", Colors.RED))
+            _print_guard_errors(guard.errors)
+            for hint in start_execution_repair_hints(guard.errors, task_dir):
+                print(f"  Hint: {hint}")
+            return 1
+        print(colored("Start-execution check: PASS", Colors.GREEN))
+        print(f"Contract fingerprint: {guard.contract_fingerprint}")
+        baseline_fingerprint = guard.artifact_fingerprints.get(BASELINE_GATE)
+        if baseline_fingerprint:
+            print(f"Artifact fingerprint: {baseline_fingerprint}")
+        if guard.required_gates:
+            print(f"Required reviewer gates: {', '.join(guard.required_gates)}")
+        if task_dir is not None:
+            contract, _ = read_strategy_contract(task_dir)
+            cap_note = optional_capability_note(contract.get("optional_capabilities"))
+            if cap_note:
+                print(colored(f"Note: {cap_note}", Colors.YELLOW))
+        print("Artifact gates are ready. Ask the user for explicit execution approval before running `task.py start-execution <task> --approved`.")
+        return 0
+
+    if not args.approved:
+        print(colored("Error: no action selected for start-execution.", Colors.RED), file=sys.stderr)
+        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)
+    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
+
+    assert task_data is not None
+    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():
+        write_gate_record(task_data, "start-execution", gate, record)
+    task_data["execution_approval"] = {
+        "schema_version": 1,
+        "transition": "start-execution",
+        "approved_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "approved_by": "user",
+        "approval_source": "task.py start-execution --approved",
+        "contract_fingerprint": guard.contract_fingerprint,
+        "artifact_fingerprint": guard.artifact_fingerprints.get(BASELINE_GATE),
+    }
+    if task_data.get("status") == "planning":
+        task_data["status"] = "in_progress"
+    if not write_json(task_json_path, task_data):
+        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    print(colored(f"✓ Execution approved for: {_repo_relative(task_dir, repo_root)}", Colors.GREEN))
+    print(f"Status: {task_data.get('status')}")
+    run_task_hooks("after_start", task_json_path, repo_root)
+    return 0
+
+
+def cmd_record_gate(args: argparse.Namespace) -> int:
+    """Record a non-baseline reviewer gate result."""
+    repo_root = get_repo_root()
+    task_dir = _resolve_existing_task(args.dir, repo_root)
+    if task_dir is None:
+        return 1
+
+    task_json_path = task_dir / FILE_TASK_JSON
+    task_data = read_json(task_json_path) if task_json_path.is_file() else None
+    if task_data is None:
+        print(colored("Error: task.json not found or invalid", Colors.RED), file=sys.stderr)
+        return 1
+
+    record, errors, warnings = build_reviewer_gate_record(
+        task_dir=task_dir,
+        task_data=task_data,
+        transition=args.transition,
+        gate=args.gate,
+        result=args.result,
+        reviewer=args.reviewer,
+        evidence=args.evidence,
+        issue_fingerprint=args.issue_fingerprint,
+        issue_summary=args.issue_summary,
+        root_cause=args.root_cause,
+        skip_approved_by=args.skip_approved_by,
+        skip_reason=args.skip_reason,
+        contract_fingerprint=args.contract_fingerprint,
+        artifact_fingerprint=args.artifact_fingerprint,
+    )
+    if errors:
+        print(colored("Error: cannot record quality gate.", Colors.RED), file=sys.stderr)
+        _print_guard_errors(errors, stream=sys.stderr)
+        return 1
+
+    assert record is not None
+    write_gate_record(task_data, args.transition, args.gate, record)
+    if not write_json(task_json_path, task_data):
+        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    print(colored(f"✓ Recorded gate: {args.transition}/{args.gate} = {record['result']}", Colors.GREEN))
+    print(f"Evidence: {record['evidence']}")
+    print(f"Contract fingerprint: {record['contract_fingerprint']}")
+    print(f"Artifact fingerprint: {record['artifact_fingerprint']}")
+    if record.get("route"):
+        print(f"Route: {record['route']}")
+    for warning in warnings:
+        print(colored(f"Warning: {warning}", Colors.YELLOW), file=sys.stderr)
+    return 0
+
+
+# =============================================================================
+# Command: list
+# =============================================================================
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List active tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    selected_task = resolve_selected_task(repo_root).task_path
+    developer = get_developer(repo_root)
+    filter_mine = args.mine
+    filter_status = args.status
+
+    if filter_mine:
+        if not developer:
+            print(colored("Error: No developer set. Run init_developer.py first", Colors.RED), file=sys.stderr)
+            return 1
+        print(colored(f"My tasks (assignee: {developer}):", Colors.BLUE))
+    else:
+        print(colored("All active tasks:", Colors.BLUE))
+    print()
+
+    # Single pass: collect all tasks via shared iterator
+    all_tasks = {t.dir_name: t for t in iter_active_tasks(tasks_dir)}
+    all_statuses = {name: t.status for name, t in all_tasks.items()}
+
+    # Display tasks hierarchically
+    count = 0
+
+    def _print_task(
+        dir_name: str,
+        indent: int = 0,
+        parent_dir: Path | None = None,
+    ) -> None:
+        nonlocal count
+        t = all_tasks[dir_name]
+
+        # Apply --mine filter
+        if filter_mine and (t.assignee or "-") != developer:
+            return
+
+        # Apply --status filter
+        if filter_status and t.status != filter_status:
+            return
+
+        relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
+        marker = ""
+        if relative_path == selected_task:
+            marker = f" {colored('<- selected', Colors.GREEN)}"
+
+        integration_states = None
+        if t.children:
+            integration_states = load_parent_child_integration_states(
+                t.directory, t.children
+            )
+        progress = children_progress(
+            t.children, all_statuses, integration_states
+        )
+
+        integration_state = None
+        if parent_dir is not None:
+            integration_state = get_child_state(parent_dir, dir_name)
+        status_display = format_child_task_display(t.status, integration_state)
+
+        # Package tag
+        pkg_tag = f" @{t.package}" if t.package else ""
+
+        prefix = "  " * indent + "  - "
+
+        if filter_mine:
+            print(
+                f"{prefix}{dir_name}/ ({status_display}){pkg_tag}{progress}{marker}"
+            )
+        else:
+            print(
+                f"{prefix}{dir_name}/ ({status_display}){pkg_tag}{progress} "
+                f"[{colored(t.assignee or '-', Colors.CYAN)}]{marker}"
+            )
+        count += 1
+
+        # Print children indented
+        for child_name in t.children:
+            if child_name in all_tasks:
+                _print_task(child_name, indent + 1, parent_dir=t.directory)
+
+    # Display only top-level tasks (those without a parent)
+    for dir_name in sorted(all_tasks.keys()):
+        if not all_tasks[dir_name].parent:
+            _print_task(dir_name)
+
+    if count == 0:
+        if filter_mine:
+            print("  (no tasks assigned to you)")
+        else:
+            print("  (no active tasks)")
+
+    print()
+    print(f"Total: {count} task(s)")
+    return 0
+
+
+# =============================================================================
+# Command: list-archive
+# =============================================================================
+
+def cmd_list_archive(args: argparse.Namespace) -> int:
+    """List archived tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    archive_dir = tasks_dir / "archive"
+    month = args.month
+
+    print(colored("Archived tasks:", Colors.BLUE))
+    print()
+
+    if month:
+        month_dir = archive_dir / month
+        if month_dir.is_dir():
+            print(f"[{month}]")
+            for d in sorted(month_dir.iterdir()):
+                if d.is_dir():
+                    print(f"  - {d.name}/")
+        else:
+            print(f"  No archives for {month}")
+    else:
+        if archive_dir.is_dir():
+            for month_dir in sorted(archive_dir.iterdir()):
+                if month_dir.is_dir():
+                    month_name = month_dir.name
+                    count = sum(1 for d in month_dir.iterdir() if d.is_dir())
+                    print(f"[{month_name}] - {count} task(s)")
+
+    return 0
+
+
+# =============================================================================
+# Help
+# =============================================================================
+
+def show_usage() -> None:
+    """Show usage help."""
+    print("""Task Management Script
+
+Usage:
+  python task.py create <title>                     Create new task directory
+  python task.py create <title> --package <pkg>     Create task for a specific package
+  python task.py create <title> --parent <dir>      Create task as child of parent
+  python task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
+  python task.py validate <dir>                     Validate jsonl files
+  python task.py list-context <dir>                 List jsonl entries
+  python task.py dashboard                          Show Task Dashboard
+  python task.py select <dir>                       Select task for this live session
+  python task.py selected [--source]                Show selected task
+  python task.py start-execution <dir> --check      Check execution readiness
+  python task.py start-execution <dir> --approved   Start approved execution
+  python task.py record-gate <dir> --transition <key> --gate <gate> --result PASS|FAIL|SKIPPED --reviewer <id> --evidence <ref> [--root-cause <cause>]
+  python task.py exit                               Clear selected task
+  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 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
+  python task.py prepare-child-worktree <parent> <child> --branch <branch>
+  python task.py set-child-state <parent> <child> <state> --evidence <ref>
+  python task.py integrate-child <parent> <child> <state> --evidence <ref>
+  python task.py list [--mine] [--status <status>]  List tasks
+  python task.py list-archive [YYYY-MM]             List archived tasks
+
+Monorepo options:
+  --package <pkg>      Package name (validated against config.yaml packages)
+
+List options:
+  --mine, -m           Show only tasks assigned to current developer
+  --status, -s <s>     Filter by status (planning, in_progress, review, completed)
+
+Examples:
+  python task.py create "Add login feature" --slug add-login
+  python task.py create "Add login feature" --slug add-login --package cli
+  python task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
+  python task.py add-context <dir> implement .trellis/spec/cli/backend/auth.md "Auth guidelines"
+  python task.py set-branch <dir> task/add-login
+  python task.py dashboard
+  python task.py select .trellis/tasks/01-21-add-login
+  python task.py selected --source
+  python task.py start-execution .trellis/tasks/01-21-add-login --check
+  python task.py start-execution .trellis/tasks/01-21-add-login --approved
+  python task.py record-gate .trellis/tasks/01-21-add-login --transition full-task-complete --gate code-review --result FAIL --reviewer codex --evidence verify.md --issue-fingerprint auth-branch-1 --root-cause implementation-defect
+  python task.py exit
+  python task.py archive add-login --check
+  python task.py archive add-login
+  python task.py add-subtask parent-task child-task  # Link existing tasks
+  python task.py remove-subtask parent-task child-task
+  python task.py prepare-child-worktree parent-task child-task --branch child-task
+  python task.py set-child-state parent-task child-task review --evidence verify.md
+  python task.py integrate-child parent-task child-task accepted --evidence handoff.md --ref child-branch
+  python task.py integrate-child parent-task child-task integrated --evidence task-map.md --ref child-branch --execute-merge
+  python task.py generate-child-prompt parent-task child-task --mode inline
+  python task.py parent-status parent-task
+  python task.py review-child parent-task child-task --check
+  python task.py review-child parent-task child-task --decision accept --ref child-branch
+  python task.py list                               # List all active tasks
+  python task.py list --mine                        # List my tasks only
+  python task.py list --mine --status in_progress   # List my in-progress tasks
+""")
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> int:
+    """CLI entry point."""
+    # Deprecation guard: `init-context` was removed in v0.5.0-beta.12.
+    # Detect early so argparse doesn't mask the real reason with a generic
+    # "invalid choice" error.
+    if len(sys.argv) >= 2 and sys.argv[1] == "init-context":
+        print(
+            colored(
+                "Error: `task.py init-context` was removed in v0.5.0-beta.12.",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        print(
+            "implement.jsonl / check.jsonl are now seeded on `task.py create` for",
+            file=sys.stderr,
+        )
+        print(
+            "sub-agent-capable platforms and curated by the AI during planning when needed.",
+            file=sys.stderr,
+        )
+        print("See .trellis/workflow.md planning artifact guidance or run:", file=sys.stderr)
+        print(
+            "  python ./.trellis/scripts/get_context.py --mode phase --step 1",
+            file=sys.stderr,
+        )
+        print(
+            "Use `task.py add-context <dir> implement|check <path> <reason>` to append entries.",
+            file=sys.stderr,
+        )
+        return 2
+
+    parser = argparse.ArgumentParser(
+        description="Task Management Script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # create
+    p_create = subparsers.add_parser("create", help="Create new task")
+    p_create.add_argument("title", help="Task title")
+    p_create.add_argument("--slug", "-s", help="Task slug")
+    p_create.add_argument("--assignee", "-a", help="Assignee developer")
+    p_create.add_argument("--priority", "-p", default="P2", help="Priority (P0-P3)")
+    p_create.add_argument("--description", "-d", help="Task description")
+    p_create.add_argument("--parent", help="Parent task directory (establishes subtask link)")
+    p_create.add_argument("--package", help="Package name for monorepo projects")
+
+    # add-context
+    p_add = subparsers.add_parser("add-context", help="Add context entry")
+    p_add.add_argument("dir", help="Task directory")
+    p_add.add_argument("file", help="JSONL file (implement|check)")
+    p_add.add_argument("path", help="File path to add")
+    p_add.add_argument("reason", nargs="?", help="Reason for adding")
+
+    # validate
+    p_validate = subparsers.add_parser("validate", help="Validate context files")
+    p_validate.add_argument("dir", help="Task directory")
+
+    # list-context
+    p_listctx = subparsers.add_parser("list-context", help="List context entries")
+    p_listctx.add_argument("dir", help="Task directory")
+
+    # dashboard
+    subparsers.add_parser("dashboard", help="Show Task Dashboard")
+
+    # select
+    p_select = subparsers.add_parser("select", help="Select task for this live session")
+    p_select.add_argument("dir", help="Task directory")
+
+    # selected
+    p_selected = subparsers.add_parser("selected", help="Show selected task")
+    p_selected.add_argument("--source", action="store_true",
+                            help="Show selected task source")
+
+    # start-execution
+    p_start_execution = subparsers.add_parser("start-execution", help="Start approved task execution")
+    p_start_execution.add_argument("dir", help="Task directory")
+    p_start_execution.add_argument("--check", action="store_true",
+                                   help="Run non-mutating execution readiness check")
+    p_start_execution.add_argument("--approved", action="store_true",
+                                   help="Record explicit approval and start execution")
+
+    # record-gate
+    p_record_gate = subparsers.add_parser("record-gate", help="Record reviewer quality gate")
+    p_record_gate.add_argument("dir", help="Task directory")
+    p_record_gate.add_argument("--transition", required=True, help="Transition key")
+    p_record_gate.add_argument("--gate", required=True, help="Gate name")
+    p_record_gate.add_argument("--result", required=True, help="PASS, FAIL, or SKIPPED")
+    p_record_gate.add_argument("--reviewer", required=True, help="Reviewer identifier")
+    p_record_gate.add_argument("--evidence", required=True, help="Short evidence reference")
+    p_record_gate.add_argument("--issue-fingerprint", help="Required for FAIL")
+    p_record_gate.add_argument("--issue-summary", help="Optional short issue summary for FAIL")
+    p_record_gate.add_argument("--root-cause",
+                               help="Required for FAIL: implementation-defect, contract-changing-defect, or validation-environment-blocker")
+    p_record_gate.add_argument("--skip-approved-by", help="Must be 'user' for SKIPPED")
+    p_record_gate.add_argument("--skip-reason", help="Required reason for SKIPPED")
+    p_record_gate.add_argument("--contract-fingerprint", help="Optional current contract fingerprint assertion")
+    p_record_gate.add_argument("--artifact-fingerprint", help="Optional current artifact fingerprint assertion")
+
+    # exit
+    subparsers.add_parser("exit", help="Clear selected task")
+
+    # set-branch
+    p_branch = subparsers.add_parser("set-branch", help="Set git branch")
+    p_branch.add_argument("dir", help="Task directory")
+    p_branch.add_argument("branch", help="Branch name")
+
+    # set-base-branch
+    p_base = subparsers.add_parser("set-base-branch", help="Set PR target branch")
+    p_base.add_argument("dir", help="Task directory")
+    p_base.add_argument("base_branch", help="Base branch name (PR target)")
+
+    # set-scope
+    p_scope = subparsers.add_parser("set-scope", help="Set scope")
+    p_scope.add_argument("dir", help="Task directory")
+    p_scope.add_argument("scope", help="Scope name")
+
+    # archive
+    p_archive = subparsers.add_parser("archive", help="Archive task")
+    p_archive.add_argument("name", help="Task directory or name")
+    p_archive.add_argument("--check", action="store_true", help="Run non-mutating archive readiness check")
+    p_archive.add_argument("--no-commit", action="store_true", help="Skip auto git commit after archive")
+    p_archive.add_argument(
+        "--archive-integrated-children",
+        action="store_true",
+        help="When archiving a parent, also archive integrated children that pass archive --check",
+    )
+
+    # prepare-archive-evidence
+    p_prepare_archive = subparsers.add_parser(
+        "prepare-archive-evidence",
+        help="Append missing archive evidence sections to verify.md",
+    )
+    p_prepare_archive.add_argument("name", help="Task directory or name")
+    p_prepare_archive.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be appended without writing verify.md",
+    )
+
+    # prepare-learning-scaffold
+    p_learning_scaffold = subparsers.add_parser(
+        "prepare-learning-scaffold",
+        help="Print durable-learning / spec-update checklist (does not edit specs)",
+    )
+    p_learning_scaffold.add_argument("name", help="Task directory or name")
+    p_learning_scaffold.add_argument(
+        "--trigger",
+        help="Optional reason (e.g. parent review changes, repeated workflow bug)",
+    )
+
+    # list
+    p_list = subparsers.add_parser("list", help="List tasks")
+    p_list.add_argument("--mine", "-m", action="store_true", help="My tasks only")
+    p_list.add_argument("--status", "-s", help="Filter by status")
+
+    # add-subtask
+    p_addsub = subparsers.add_parser("add-subtask", help="Link child task to parent")
+    p_addsub.add_argument("parent_dir", help="Parent task directory")
+    p_addsub.add_argument("child_dir", help="Child task directory")
+
+    # remove-subtask
+    p_rmsub = subparsers.add_parser("remove-subtask", help="Unlink child task from parent")
+    p_rmsub.add_argument("parent_dir", help="Parent task directory")
+    p_rmsub.add_argument("child_dir", help="Child task directory")
+
+    # prepare-child-worktree
+    p_prepare_worktree = subparsers.add_parser("prepare-child-worktree", help="Create/register a Child git worktree")
+    p_prepare_worktree.add_argument("parent_dir", help="Parent task directory")
+    p_prepare_worktree.add_argument("child_dir", help="Child task directory")
+    p_prepare_worktree.add_argument("--branch", required=True, help="Child git branch to create or checkout")
+    p_prepare_worktree.add_argument("--base", help="Base ref for a new Child branch")
+    p_prepare_worktree.add_argument("--path", help="Worktree path under .trellis/worktrees/")
+    p_prepare_worktree.add_argument("--check", action="store_true", help="Run non-mutating worktree readiness check")
+
+    # set-child-state
+    p_child_state = subparsers.add_parser("set-child-state", help="Set Child Worker state in Parent task-map.md")
+    p_child_state.add_argument("parent_dir", help="Parent task directory")
+    p_child_state.add_argument("child_dir", help="Child task directory")
+    p_child_state.add_argument("state", help="Child state")
+    p_child_state.add_argument("--evidence", required=True, help="Short evidence reference")
+    p_child_state.add_argument("--reason", help="Optional short reason")
+
+    # integrate-child
+    p_integrate_child = subparsers.add_parser("integrate-child", help="Set Parent-controlled Child integration state")
+    p_integrate_child.add_argument("parent_dir", help="Parent task directory")
+    p_integrate_child.add_argument("child_dir", help="Child task directory")
+    p_integrate_child.add_argument("state", help="Parent-controlled Child state")
+    p_integrate_child.add_argument("--evidence", required=True, help="Short evidence reference")
+    p_integrate_child.add_argument("--ref", help="Child git ref or reviewed diff reference")
+    p_integrate_child.add_argument("--reason", help="Optional short reason")
+    p_integrate_child.add_argument("--execute-merge", action="store_true", help="Execute git merge --no-ff --no-commit for an integrated Child")
+    p_integrate_child.add_argument("--check", action="store_true", help="Run non-mutating integration readiness check")
+
+    # generate-child-prompt
+    p_gen_prompt = subparsers.add_parser(
+        "generate-child-prompt",
+        help="Generate child implementation prompt for parent orchestration",
+    )
+    p_gen_prompt.add_argument("parent_dir", help="Parent task directory")
+    p_gen_prompt.add_argument("child_dir", help="Child task directory")
+    p_gen_prompt.add_argument(
+        "--mode",
+        choices=["inline", "subagent"],
+        default="inline",
+        help="Delivery mode hint (inline manual handoff vs optional subagent)",
+    )
+    p_gen_prompt.add_argument(
+        "--include-artifacts",
+        action="store_true",
+        help="Embed child artifact bodies in the generated prompt",
+    )
+    p_gen_prompt.add_argument("--output", "-o", help="Write prompt to file instead of stdout")
+
+    # parent-status
+    p_parent_status = subparsers.add_parser("parent-status", help="Show parent task-map orchestration status")
+    p_parent_status.add_argument("parent_dir", help="Parent task directory")
+
+    # review-child
+    p_review_child = subparsers.add_parser(
+        "review-child",
+        help="Review child handoff and optionally advance integration states",
+    )
+    p_review_child.add_argument("parent_dir", help="Parent task directory")
+    p_review_child.add_argument("child_dir", help="Child task directory")
+    p_review_child.add_argument("--check", action="store_true", help="Non-mutating review readiness check")
+    p_review_child.add_argument(
+        "--decision",
+        choices=["accept", "changes", "cancel", "integrate-through"],
+        help="Parent review decision (runs integrate-child steps when valid)",
+    )
+    p_review_child.add_argument("--ref", help="Child git ref for accept / integrate-through")
+    p_review_child.add_argument("--reason", help="Required for changes or cancel decisions")
+    p_review_child.add_argument("--notes", help="Short parent review notes included in the report")
+    p_review_child.add_argument(
+        "--write-artifact",
+        action="store_true",
+        help="Also write review-<child>.md under the parent task directory",
+    )
+    p_review_child.add_argument(
+        "--no-append-parent-verify",
+        action="store_true",
+        help="Do not append review notes to parent verify.md",
+    )
+
+    # list-archive
+    p_listarch = subparsers.add_parser("list-archive", help="List archived tasks")
+    p_listarch.add_argument("month", nargs="?", help="Month (YYYY-MM)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        show_usage()
+        return 1
+
+    commands = {
+        "create": cmd_create,
+        "add-context": cmd_add_context,
+        "validate": cmd_validate,
+        "list-context": cmd_list_context,
+        "dashboard": cmd_dashboard,
+        "select": cmd_select,
+        "selected": cmd_selected,
+        "start-execution": cmd_start_execution,
+        "record-gate": cmd_record_gate,
+        "exit": cmd_exit,
+        "set-branch": cmd_set_branch,
+        "set-base-branch": cmd_set_base_branch,
+        "set-scope": cmd_set_scope,
+        "archive": cmd_archive,
+        "prepare-archive-evidence": cmd_prepare_archive_evidence,
+        "prepare-learning-scaffold": cmd_prepare_learning_scaffold,
+        "add-subtask": cmd_add_subtask,
+        "remove-subtask": cmd_remove_subtask,
+        "prepare-child-worktree": cmd_prepare_child_worktree,
+        "set-child-state": cmd_set_child_state,
+        "integrate-child": cmd_integrate_child,
+        "generate-child-prompt": cmd_generate_child_prompt,
+        "parent-status": cmd_parent_status,
+        "review-child": cmd_review_child,
+        "list": cmd_list,
+        "list-archive": cmd_list_archive,
+    }
+
+    if args.command in commands:
+        return commands[args.command](args)
+    else:
+        show_usage()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())