@pennixrv/trellis 0.7.1 → 0.7.2-beta.2

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import contextlib
+import copy
 from datetime import datetime, timezone
 import hashlib
 import json
@@ -61,11 +62,14 @@ def _task_dir(value: str) -> Path:
     return task_dir
 
 
-def _load(task_dir: Path) -> tuple[dict, dict]:
+def _load(task_dir: Path, *, initialize_meta: bool = False) -> tuple[dict, dict]:
     task_file = task_dir / FILE_TASK_JSON
     data, reason = read_json_checked(task_file)
     if data is None:
         raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", f"cannot read {task_file}: {reason}")
+    # Explicit initialization may adopt legacy records; malformed metadata still fails.
+    if initialize_meta and "meta" not in data:
+        data["meta"] = {}
     meta = data.get("meta")
     if not isinstance(meta, dict):
         raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "task.meta must be an object")
@@ -106,6 +110,28 @@ def _state(meta: dict) -> dict:
         raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "route dependency admission has an invalid shape")
     if state.get("current_phase_id") is not None and state["current_phase_id"] not in state["phase_ids"]:
         raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "current phase is not in the task route")
+    skip_records = state.get("skip_records")
+    if not isinstance(skip_records, dict):
+        raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "task phase skip records have an invalid shape")
+    for phase_id, skip in skip_records.items():
+        if (
+            phase_id not in PHASE_ID_SET
+            or not isinstance(skip, dict)
+            or not isinstance(skip.get("reason"), str)
+            or not skip["reason"].strip()
+            or not isinstance(skip.get("evidence_refs"), list)
+            or not skip["evidence_refs"]
+            or any(not isinstance(value, str) or not value.strip() for value in skip["evidence_refs"])
+            or skip.get("task_route_revision") != state["task_route_revision"]
+            or not ROUTE_REVISION.fullmatch(str(skip.get("input_revision", "")))
+            or not isinstance(skip.get("artifact_revision"), str)
+            or not re.fullmatch(r"[a-f0-9]{64}", skip["artifact_revision"])
+            or (
+                phase_id in state["phases"]
+                and skip["artifact_revision"] != state["phases"][phase_id].get("artifact_revision")
+            )
+        ):
+            raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", f"task phase skip record is invalid: {phase_id}")
     for phase_id in state["phase_ids"]:
         record = state["phases"].get(phase_id)
         if not isinstance(record, dict) or record.get("status") not in {"not_started", "active", "waiting_user", "blocked", "accepted", "skipped"}:
@@ -130,6 +156,10 @@ def implementation_start_ready(data: dict, task_dir: Path) -> bool:
     phase_ids = state.get("phase_ids")
     if not isinstance(phase_ids, list) or PHASE_IDS[3] not in phase_ids:
         return False
+    phases = state.get("phases")
+    implementation = phases.get(PHASE_IDS[3]) if isinstance(phases, dict) else None
+    if not isinstance(implementation, dict) or implementation.get("status") != "active":
+        return False
     if state.get("task_kind") not in {"implementation", "combined"}:
         return False
     authorization = state.get("implementation_authorization")
@@ -145,6 +175,7 @@ def implementation_start_ready(data: dict, task_dir: Path) -> bool:
     ):
         return False
     _require_current_requirements_confirmation(task_dir, state)
+    _require_current_accepted_artifacts(task_dir, state)
     if PHASE_IDS[2] not in phase_ids:
         skip_records = state.get("skip_records")
         skipped_design = skip_records.get(PHASE_IDS[2]) if isinstance(skip_records, dict) else None
@@ -176,7 +207,8 @@ def _save(task_file: Path, data: dict) -> None:
 
 @contextlib.contextmanager
 def _task_lock(task_dir: Path):
-    lock_file = task_dir / ".task-phase.lock"
+    lock_file = get_repo_root() / ".trellis/.runtime/task-phase" / f"{task_dir.name}.lock"
+    lock_file.parent.mkdir(parents=True, exist_ok=True)
     with lock_file.open("a+b") as handle:
         if os.name == "nt":
             import msvcrt
@@ -223,28 +255,39 @@ def _phase(state: dict, phase_id: str | None = None) -> tuple[str, dict]:
     return current, record
 
 
-def _require_current_requirements_confirmation(task_dir: Path, state: dict) -> None:
-    if PHASE_IDS[0] not in state["phase_ids"]:
-        return
+def _is_withdrawal_route(state: dict) -> bool:
     requirements = state["phases"].get(PHASE_IDS[0], {})
     withdrawal = state.get("return_record")
     skip_records = state.get("skip_records")
     skipped_requirements = skip_records.get(PHASE_IDS[0]) if isinstance(skip_records, dict) else None
-    if (
+    return (
         state["phase_ids"] == [PHASE_IDS[0], PHASE_IDS[4]]
-        and state.get("current_phase_id") == PHASE_IDS[4]
+        and state.get("current_phase_id") in {PHASE_IDS[4], None}
         and isinstance(requirements, dict)
-        and requirements.get("status") == "skipped"
-        and isinstance(skipped_requirements, dict)
-        and skipped_requirements.get("task_route_revision") == state.get("task_route_revision")
+        and (
+            requirements.get("status") == "accepted"
+            or (
+                requirements.get("status") == "skipped"
+                and isinstance(skipped_requirements, dict)
+                and skipped_requirements.get("task_route_revision") == state.get("task_route_revision")
+            )
+        )
         and isinstance(withdrawal, dict)
         and isinstance(withdrawal.get("from"), str)
         and withdrawal["from"] in PHASE_ID_SET
         and withdrawal.get("to") == PHASE_IDS[4]
+        and withdrawal.get("return_kind") == "withdrawal"
         and withdrawal.get("task_route_revision") == state.get("task_route_revision")
         and isinstance(withdrawal.get("evidence_refs"), list)
         and bool(withdrawal["evidence_refs"])
-    ):
+    )
+
+
+def _require_current_requirements_confirmation(task_dir: Path, state: dict) -> None:
+    if PHASE_IDS[0] not in state["phase_ids"]:
+        return
+    requirements = state["phases"].get(PHASE_IDS[0], {})
+    if requirements.get("status") == "skipped" and _is_withdrawal_route(state):
         return
     acceptance = requirements.get("acceptance") if isinstance(requirements, dict) else None
     if (
@@ -280,6 +323,7 @@ def _invalidate_from(state: dict, first_phase: str, keep_first: bool = False) ->
     for phase_id in state["phase_ids"]:
         if PHASE_IDS.index(phase_id) < first_index:
             continue
+        state["skip_records"].pop(phase_id, None)
         record = state["phases"][phase_id]
         if keep_first and phase_id == first_phase:
             record["status"] = "active"
@@ -327,6 +371,24 @@ def _artifact_digest(task_dir: Path, refs: list[str]) -> str:
     return digest.hexdigest()
 
 
+def _require_current_accepted_artifacts(task_dir: Path, state: dict) -> None:
+    for phase_id in state["phase_ids"]:
+        record = state["phases"][phase_id]
+        if record.get("status") != "accepted":
+            continue
+        refs = record.get("artifact_refs")
+        if not isinstance(refs, list) or any(not isinstance(ref, str) for ref in refs):
+            raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", f"accepted artifact references are invalid: {phase_id}")
+        if _artifact_digest(task_dir, refs) != record.get("artifact_revision"):
+            raise TaskWorkflowError("TASK_PHASE_STALE_ARTIFACT", f"accepted artifacts changed for {phase_id}; return to the affected phase and review the current candidate again")
+    authorization = state.get("implementation_authorization")
+    if authorization is not None:
+        if not isinstance(authorization, dict) or not isinstance(authorization.get("contract_ref"), str):
+            raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "implementation authorization has no contract reference")
+        if _artifact_digest(task_dir, [authorization["contract_ref"]]) != authorization.get("contract_revision"):
+            raise TaskWorkflowError("TASK_PHASE_STALE_ARTIFACT", "implementation contract changed after authorization; review and authorize its current content before continuing")
+
+
 def _validate_route(value: str | None) -> list[str]:
     raw = _required_text(value, "--phase-ids")
     phases = raw.split(",")
@@ -350,6 +412,8 @@ def _validate_classification(task_kind: str | None, complexity: str | None, proj
         raise TaskWorkflowError("TASK_PHASE_INVALID_INPUT", "--project-context must be new or existing")
     if task_kind == "analysis" and PHASE_IDS[3] in phases:
         raise TaskWorkflowError("TASK_PHASE_INVALID_ROUTE", "analysis tasks cannot include the Task Implementation and Test Verification Phase")
+    if task_kind in {"implementation", "combined"} and PHASE_IDS[3] not in phases:
+        raise TaskWorkflowError("TASK_PHASE_INVALID_ROUTE", "implementation and combined tasks must include the Task Implementation and Test Verification Phase")
 
 
 def _increment(value: str, allow_zero: bool = False) -> str:
@@ -402,7 +466,13 @@ def _init(args: argparse.Namespace, task_dir: Path, data: dict, meta: dict) -> i
         "implementation_authorization": None,
         "closeout_disposition": None,
         "skip_records": {
-            phase: {"reason": route_reason, "evidence_refs": route_evidence, "task_route_revision": "1"}
+            phase: {
+                "reason": route_reason,
+                "evidence_refs": route_evidence,
+                "task_route_revision": "1",
+                "input_revision": input_revision,
+                "artifact_revision": _phase_record(input_revision)["artifact_revision"],
+            }
             for phase in omitted
         },
         "return_record": None,
@@ -417,6 +487,31 @@ def _show(state: dict) -> int:
     return 0
 
 
+def _require_acceptance_coverage(task_dir: Path, contract_ref: str) -> None:
+    _artifact_digest(task_dir, [contract_ref])
+    lines = (task_dir / contract_ref).read_text(encoding="utf-8").splitlines()
+    heading = next((index for index, line in enumerate(lines) if line.strip() == "## 验收覆盖"), None)
+    headers = ["接受条件", "工作包", "Owner", "验证入口", "交付证据", "停止条件"]
+    if heading is not None:
+        section = []
+        for line in lines[heading + 1:]:
+            if line.startswith("#"):
+                break
+            if line.strip():
+                section.append(line.strip())
+        rows = [line.strip("|").split("|") for line in section if line.startswith("|") and line.endswith("|")]
+        rows = [[cell.strip() for cell in row] for row in rows]
+        if (
+            len(rows) >= 3
+            and rows[0] == headers
+            and len(rows[1]) == len(headers)
+            and all(re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1])
+            and all(len(row) == len(headers) and all(row) for row in rows[2:])
+        ):
+            return
+    raise TaskWorkflowError("TASK_PHASE_COVERAGE_REQUIRED", "implementation contract requires ## 验收覆盖 with nonempty rows: " + " | ".join(headers))
+
+
 def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -> int:
     action = args.phase_action
     child_dispositions: dict[str, str] = {}
@@ -427,14 +522,21 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
         raise TaskWorkflowError("TASK_PHASE_TASK_TERMINAL", f"task is already {data['status']}")
 
     _expected_route(state, args.expected_route_revision)
-    if action == "route" and state.get("current_phase_id") is None:
-        raise TaskWorkflowError("TASK_PHASE_INCOMPLETE", "completed phases cannot be rerouted")
-    current, record = _phase(state)
+    reviewed_delivery = (
+        state.get("current_phase_id") is None
+        and action in {"return", "route"}
+        and state["phases"].get(PHASE_IDS[4], {}).get("status") == "accepted"
+    )
+    if reviewed_delivery:
+        current, record = PHASE_IDS[4], state["phases"][PHASE_IDS[4]]
+    else:
+        current, record = _phase(state)
+    accepted_design_return = action == "return" and current == PHASE_IDS[2] and record.get("status") == "accepted"
     returning_to_requirements = action == "return" and args.target_phase == PHASE_IDS[0]
     rerouting_to_requirements = action == "route" and args.target_phase == PHASE_IDS[0]
     if current != PHASE_IDS[0] and not returning_to_requirements and not rerouting_to_requirements:
         _require_current_requirements_confirmation(task_dir, state)
-    if action not in {"show", "resume", "route", "authorize", "admission"} and record.get("status") != "active":
+    if action not in {"show", "resume", "route", "authorize", "admission"} and record.get("status") != "active" and not reviewed_delivery and not accepted_design_return:
         raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "only the active phase can be changed")
 
     if action == "artifact":
@@ -478,9 +580,16 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
         if current == PHASE_IDS[0]:
             raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "The Goal Exploration and Requirements Confirmation Phase must reach minimum alignment and acceptance and cannot be skipped")
         record.update({"status": "skipped", "reason": reason, "evidence_refs": evidence})
-        state["skip_records"][current] = {"reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
+        state["skip_records"][current] = {
+            "reason": reason,
+            "evidence_refs": evidence,
+            "task_route_revision": state["task_route_revision"],
+            "input_revision": state["input_revision"],
+            "artifact_revision": record["artifact_revision"],
+        }
         _advance(state, current)
     elif action == "accept":
+        _require_current_accepted_artifacts(task_dir, state)
         artifact_revision = _required_text(args.artifact_revision, "--artifact-revision")
         current_revision = _artifact_digest(task_dir, record["artifact_refs"])
         if artifact_revision != record["artifact_revision"] or current_revision != record["artifact_revision"]:
@@ -495,6 +604,8 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "Solution Design and Convergence Phase must remain active for pending_user_decision or deferred; accept implementation_contract, analysis_conclusion, or no_go")
         if result_ref not in record["artifact_refs"]:
             raise TaskWorkflowError("TASK_PHASE_RESULT_NOT_BOUND", "--result-ref must be included in the current phase artifact refs")
+        if current == PHASE_IDS[2] and outcome == "implementation_contract":
+            _require_acceptance_coverage(task_dir, result_ref)
         if current == PHASE_IDS[3]:
             authorization = state.get("implementation_authorization")
             if not isinstance(authorization, dict) or authorization.get("task_route_revision") != state["task_route_revision"]:
@@ -505,8 +616,7 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             if outcome != args.closeout_disposition:
                 raise TaskWorkflowError("TASK_PHASE_INVALID_INPUT", "Delivery Review and On-Site Closeout Phase outcome must match --closeout-disposition")
             if args.closeout_disposition == "cancelled":
-                withdrawal = state.get("return_record")
-                if not isinstance(withdrawal, dict) or withdrawal.get("to") != PHASE_IDS[4] or not withdrawal.get("evidence_refs"):
+                if not _is_withdrawal_route(state):
                     raise TaskWorkflowError("TASK_PHASE_USER_CONFIRMATION_REQUIRED", "cancellation closeout requires a user-confirmed route to Delivery Review and On-Site Closeout Phase")
             child_dispositions = _validate_child_dispositions(
                 task_dir, data, args.closeout_disposition, args.child_disposition
@@ -532,14 +642,38 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             _advance(state, current)
     elif action == "return":
         target = _required_text(args.target_phase, "--target-phase")
-        if target not in state["phase_ids"] or state["phase_ids"].index(target) >= state["phase_ids"].index(current):
+        return_kind = args.return_kind
+        execution_rework = return_kind == "execution_rework"
+        if target not in state["phase_ids"] or (
+            state["phase_ids"].index(target) >= state["phase_ids"].index(current)
+            and not ((reviewed_delivery or accepted_design_return or execution_rework) and target == current)
+        ):
             raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "return target must be an earlier phase in the current route")
         reason = _required_text(args.reason, "--reason")
         evidence = _refs(args.evidence_ref, "--evidence-ref", required=True)
+        authorization = state.get("implementation_authorization")
+        admission = state.get("route_dependency_admission")
+        if execution_rework:
+            if current not in PHASE_IDS[3:] or target not in PHASE_IDS[3:] or PHASE_IDS[3] not in state["phase_ids"]:
+                raise TaskWorkflowError("TASK_PHASE_INVALID_TRANSITION", "execution_rework is limited to implementation and delivery phases")
+            candidate = copy.deepcopy(data)
+            candidate_state = candidate["meta"]["task_workflow"]
+            _invalidate_from(candidate_state, target, keep_first=True)
+            candidate_state["implementation_authorization"] = authorization
+            _require_current_accepted_artifacts(task_dir, candidate_state)
+            candidate_state["current_phase_id"] = PHASE_IDS[3]
+            candidate_state["phases"][PHASE_IDS[3]]["status"] = "active"
+            if not implementation_start_ready(candidate, task_dir):
+                raise TaskWorkflowError("TASK_PHASE_IMPLEMENTATION_NOT_AUTHORIZED", "execution_rework requires the unchanged authorized implementation contract")
+            if admission is not None and (admission.get("admission_state") != "ready" or admission.get("task_route_revision") != state["task_route_revision"]):
+                raise TaskWorkflowError("TASK_PHASE_ADMISSION_REQUIRED", "execution_rework requires current ready dependency admission")
         state["input_revision"] = _increment(state["input_revision"])
         _invalidate_from(state, target, keep_first=True)
+        if execution_rework:
+            state["implementation_authorization"] = authorization
+            state["route_dependency_admission"] = admission
         state["phases"][target]["input_revision"] = state["input_revision"]
-        state["return_record"] = {"from": current, "to": target, "reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
+        state["return_record"] = {"from": current, "to": target, "return_kind": return_kind, "authorization_retained": execution_rework, "reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
     elif action == "route":
         phases = _validate_route(args.phase_ids)
         task_kind = args.task_kind if args.task_kind is not None else state["task_kind"]
@@ -563,8 +697,9 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
             target == PHASE_IDS[4]
             and phases == [PHASE_IDS[0], PHASE_IDS[4]]
             and bool(evidence)
+            and args.return_kind == "withdrawal"
         )
-        if not changed and not classification_changed and target == current:
+        if not changed and not classification_changed and target == current and not reviewed_delivery:
             raise TaskWorkflowError("TASK_PHASE_INVALID_ROUTE", "the updated route and target are unchanged")
         earliest_change = min((PHASE_IDS.index(phase) for phase in changed), default=PHASE_IDS.index(target))
         if target not in PHASE_ID_SET or (PHASE_IDS.index(target) > earliest_change and not withdrawal_route):
@@ -604,9 +739,25 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
         for phase_id, phase_record in state["phases"].items():
             if phase_id not in old_phases:
                 phase_record["input_revision"] = state["input_revision"]
-        state["skip_records"] = {}
+        state["skip_records"] = {
+            phase_id: {
+                **skip,
+                "task_route_revision": state["task_route_revision"],
+                "input_revision": state["input_revision"],
+                "artifact_revision": state["phases"][phase_id]["artifact_revision"],
+            }
+            for phase_id, skip in state["skip_records"].items()
+            if phase_id in phases and state["phases"][phase_id].get("status") == "skipped"
+        }
         for phase_id in omitted:
-            state["skip_records"][phase_id] = {"reason": reason, "evidence_refs": evidence, "task_route_revision": state["task_route_revision"]}
+            phase_record = state["phases"].get(phase_id, old_phases.get(phase_id, _phase_record(state["input_revision"])))
+            state["skip_records"][phase_id] = {
+                "reason": reason,
+                "evidence_refs": evidence,
+                "task_route_revision": state["task_route_revision"],
+                "input_revision": state["input_revision"],
+                "artifact_revision": phase_record["artifact_revision"],
+            }
         if withdrawal_route and state["phases"][PHASE_IDS[0]].get("status") != "accepted":
             state["phases"][PHASE_IDS[0]].update({
                 "status": "skipped",
@@ -620,6 +771,8 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
                 "reason": reason,
                 "evidence_refs": evidence,
                 "task_route_revision": state["task_route_revision"],
+                "input_revision": state["input_revision"],
+                "artifact_revision": state["phases"][PHASE_IDS[0]]["artifact_revision"],
             }
         state["implementation_authorization"] = None
         state["closeout_disposition"] = None
@@ -627,6 +780,7 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
         state["return_record"] = {
             "from": current,
             "to": target,
+            **({"return_kind": "withdrawal"} if withdrawal_route else {}),
             "reason": reason,
             "evidence_refs": evidence,
             "task_route_revision": state["task_route_revision"],
@@ -647,7 +801,8 @@ def _update(args: argparse.Namespace, task_dir: Path, data: dict, state: dict) -
                 raise TaskWorkflowError("TASK_PHASE_STALE_ARTIFACT", "Solution Design and Convergence Phase implementation contract changed after acceptance; refresh and accept the current artifact before authorization")
         elif contract_ref not in state.get("skip_records", {}).get(PHASE_IDS[2], {}).get("evidence_refs", []):
             raise TaskWorkflowError("TASK_PHASE_CONTRACT_NOT_ACCEPTED", "when Solution Design and Convergence Phase is omitted, the implementation contract must be among its route evidence")
-        state["implementation_authorization"] = {"contract_ref": contract_ref, "approval_ref": approval_ref, "task_route_revision": state["task_route_revision"]}
+        _require_acceptance_coverage(task_dir, contract_ref)
+        state["implementation_authorization"] = {"contract_ref": contract_ref, "contract_revision": _artifact_digest(task_dir, [contract_ref]), "approval_ref": approval_ref, "task_route_revision": state["task_route_revision"]}
         if current == PHASE_IDS[2]:
             _advance(state, current)
     else:
@@ -662,7 +817,7 @@ def cmd_phase(args: argparse.Namespace) -> int:
     try:
         task_dir = _task_dir(args.task_dir)
         with _task_lock(task_dir):
-            data, meta = _load(task_dir)
+            data, meta = _load(task_dir, initialize_meta=args.phase_action == "init")
             if args.phase_action == "init":
                 return _init(args, task_dir, data, meta)
             return _update(args, task_dir, data, _state(meta))
@@ -707,6 +862,56 @@ def _paseo_list(args: list[str], cwd: Path, code: str) -> list[dict]:
     return value
 
 
+def _delegation_binding(repo_root: Path, child_dir: Path, child_data: dict, result_path: str) -> dict:
+    if not isinstance(result_path, str) or Path(result_path).is_absolute() or ".." in Path(result_path).parts or not result_path.startswith(".trellis/delegated-results/"):
+        raise TaskWorkflowError("TASK_DELEGATE_CONTRACT_INVALID", "result path must stay under .trellis/delegated-results/")
+    try:
+        contract_path = (child_dir / "prd.md").resolve(strict=True)
+        contract_path.relative_to(child_dir.resolve())
+        role_path = (repo_root / ".trellis/agents/delegated-worktree-primary-agent.md").resolve(strict=True)
+        role_path.relative_to((repo_root / ".trellis/agents").resolve())
+        if not contract_path.is_file() or not role_path.is_file() or contract_path.stat().st_size + role_path.stat().st_size > 1048576:
+            raise ValueError("delegated contract and role must be regular files within the size budget")
+        contract = contract_path.read_bytes()
+        role = role_path.read_bytes()
+    except (OSError, ValueError) as error:
+        raise TaskWorkflowError("TASK_DELEGATE_CONTRACT_INVALID", str(error)) from error
+    if not contract.strip() or not role.strip():
+        raise TaskWorkflowError("TASK_DELEGATE_CONTRACT_INVALID", "child PRD and delegated role must be nonempty")
+    return {
+        "contract_sha256": hashlib.sha256(contract).hexdigest(),
+        "role_sha256": hashlib.sha256(role).hexdigest(),
+        "branch": _required_text(child_data.get("branch"), "child branch"),
+        "base_commit": _git_output(["rev-parse", "--verify", "--end-of-options", f"{_required_text(child_data.get('base_branch'), 'child base_branch')}^{{commit}}"], repo_root),
+        "result_path": result_path,
+    }
+
+
+def cmd_delegate_bind(args: argparse.Namespace) -> int:
+    try:
+        repo_root = get_repo_root().resolve()
+        child_dir = _task_dir(args.child_task)
+        child, _ = _load(child_dir)
+        if not isinstance(child.get("parent"), str) or not child["parent"].strip():
+            raise TaskWorkflowError("TASK_DELEGATE_PARENT_LINK_INVALID", "child task has no parent link")
+        parent_dir = _task_dir(child["parent"])
+        parent, meta = _load(parent_dir)
+        if child_dir.name not in parent.get("children", []) or not implementation_start_ready(parent, parent_dir):
+            raise TaskWorkflowError("TASK_DELEGATE_IMPLEMENTATION_NOT_AUTHORIZED", "bind only a linked child within current parent implementation authorization")
+        state = _state(meta)
+        authorization = state["implementation_authorization"]
+        result_path = args.result_path or f".trellis/delegated-results/{child_dir.name}.md"
+        binding = _delegation_binding(repo_root, child_dir, child, result_path)
+        binding.update({"authorization_ref": authorization["approval_ref"], "parent_contract_revision": authorization["contract_revision"], "task_route_revision": state["task_route_revision"]})
+        meta.setdefault("delegation_authorizations", {})[child_dir.name] = binding
+        _save(parent_dir / FILE_TASK_JSON, parent)
+        print(json.dumps(binding, ensure_ascii=False))
+        return 0
+    except TaskWorkflowError as error:
+        print(f"{error.code}: {error}", file=sys.stderr)
+        return 1
+
+
 def cmd_delegate_start(args: argparse.Namespace) -> int:
     try:
         repo_root = get_repo_root().resolve()
@@ -722,6 +927,11 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
             child_data, child_meta = _load(child_dir)
             if child_data.get("parent") != parent_dir.name or child_dir.name not in parent_data.get("children", []):
                 raise TaskWorkflowError("TASK_DELEGATE_PARENT_LINK_INVALID", "parent and child task links do not match")
+            from .task_continuity import assert_task_mutation_allowed
+
+            assert_task_mutation_allowed(repo_root, parent_dir, parent_data)
+            if child_data.get("status") not in {"planning", "in_progress"}:
+                raise TaskWorkflowError("TASK_DELEGATE_CHILD_TERMINAL", "only a planning or in-progress child task can be delegated")
             if parent_data.get("status") != "in_progress" or not implementation_start_ready(parent_data, parent_dir):
                 raise TaskWorkflowError("TASK_DELEGATE_IMPLEMENTATION_NOT_AUTHORIZED", "parent task is not at an authorized Task Implementation and Test Verification Phase entry")
 
@@ -775,6 +985,7 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
                 raise TaskWorkflowError("TASK_DELEGATE_PASEO_UNAVAILABLE", f"could not run Paseo: {error}") from error
             if version.returncode != 0:
                 raise TaskWorkflowError("TASK_DELEGATE_PASEO_UNAVAILABLE", (version.stderr or version.stdout).strip() or "Paseo CLI preflight failed")
+            _paseo_list(["agent", "ls", "--all", "--global", "--background", "--json"], repo_root, "TASK_DELEGATE_PASEO_UNAVAILABLE")
             role_path = repo_root / ".trellis" / "agents" / "delegated-worktree-primary-agent.md"
             try:
                 role = role_path.read_text(encoding="utf-8")
@@ -785,6 +996,16 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
             if not isinstance(authorization, dict) or not isinstance(authorization.get("approval_ref"), str):
                 raise TaskWorkflowError("TASK_DELEGATE_AUTHORIZATION_INVALID", "current implementation authorization is invalid")
             contract_digest = hashlib.sha256(contract_bytes).hexdigest()
+            bindings = parent_meta.get("delegation_authorizations", {})
+            binding = bindings.get(child_dir.name) if isinstance(bindings, dict) else None
+            if not isinstance(binding, dict):
+                raise TaskWorkflowError("TASK_DELEGATE_CONTRACT_NOT_BOUND", "freeze this child through delegate-bind before dispatch")
+            actual = _delegation_binding(repo_root, child_dir, child_data, binding.get("result_path", ""))
+            if any(binding.get(key) != value for key, value in actual.items()) or actual["contract_sha256"] != contract_digest or actual["role_sha256"] != hashlib.sha256(role.encode("utf-8")).hexdigest() or binding.get("authorization_ref") != authorization["approval_ref"] or binding.get("parent_contract_revision") != authorization["contract_revision"] or binding.get("task_route_revision") != state["task_route_revision"]:
+                raise TaskWorkflowError("TASK_DELEGATE_STALE_CONTRACT", "child PRD, role, Git base, output path, or parent authorization changed; review and bind the child again")
+            prompt_bytes = len((role + contract).encode("utf-8"))
+            if prompt_bytes > (24000 if os.name == "nt" else 96000):
+                raise TaskWorkflowError("TASK_DELEGATE_PROMPT_TOO_LARGE", "delegated prompt exceeds the native Paseo argv budget; narrow the contract before creating resources")
             previous = child_meta.get("delegated_worktree_execution_record")
             reuse_workspace = False
             workspace_id = None
@@ -808,7 +1029,7 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
                 previous_worktree = Path(previous_worktree_path).expanduser().resolve()
                 agents = _paseo_list([
                     "agent", "ls", "--all", "--global", "--background", "--json",
-                    "--label", f"trellis.task_id={child_dir.name}",
+                    "--label", f"trellis.task_id={previous.get('label_task_id', child_dir.name)}",
                 ], repo_root, "TASK_DELEGATE_RECONCILIATION_REQUIRED")
                 for agent in agents:
                     agent_id = agent.get("id")
@@ -859,9 +1080,14 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
                 "workspace_id": workspace_id,
                 "worktree_path": str(worktree) if worktree else None,
                 "agent_id": None,
+                "label_task_id": child_dir.name,
+                "role_sha256": actual["role_sha256"],
+                "result_path": actual["result_path"],
                 "status": "starting",
                 "started_at": datetime.now(timezone.utc).isoformat(),
             }
+            if previous is not None:
+                child_meta.setdefault("delegated_worktree_execution_history", []).append(previous)
             child_meta["delegated_worktree_execution_record"] = record
             _save(child_dir / FILE_TASK_JSON, child_data)
 
@@ -902,6 +1128,7 @@ def cmd_delegate_start(args: argparse.Namespace) -> int:
                     "the parent authorization and Git baseline are execution metadata. Do not accept task phases or change task lifecycle state.\n\n"
                     f"Parent task: {parent_dir.name}\nParent route revision: {state['task_route_revision']}\n"
                     f"Authorized contract: prd.md\nBranch: {branch}\nBase commit: {base_commit}\n\n"
+                    f"Assigned result artifact: {actual['result_path']}\n"
                     f"{role}\n\n## Child task prd.md\n{contract}"
                 )
                 agent = _paseo_json([
@@ -939,6 +1166,7 @@ def cmd_cancel_task(args: argparse.Namespace) -> int:
             readiness_error = task_closeout_readiness(data, "cancelled")
             if readiness_error:
                 raise TaskWorkflowError("TASK_PHASE_CLOSEOUT_REQUIRED", readiness_error)
+            _require_current_accepted_artifacts(task_dir, _state(meta))
             _validate_child_dispositions(task_dir, data, "cancelled", None, from_acceptance=True)
             _assert_delegated_resources_closed(task_dir, data)
             meta["task_cancellation"] = {
@@ -947,7 +1175,8 @@ def cmd_cancel_task(args: argparse.Namespace) -> int:
             }
             data["status"] = "cancelled"
             data["completedAt"] = None
-            _save(task_dir / FILE_TASK_JSON, data)
+            from .task_move import relocate_task
+            task_dir = relocate_task(get_repo_root(), task_dir, data)
             from .active_task import clear_task_from_sessions
             from .task_continuity import clear_task_runtime_records
 
@@ -961,6 +1190,56 @@ def cmd_cancel_task(args: argparse.Namespace) -> int:
         return 1
 
 
+def cmd_reopen_task(args: argparse.Namespace) -> int:
+    try:
+        task_dir = _task_dir(args.task_dir)
+        with _task_lock(task_dir):
+            data, meta = _load(task_dir)
+            previous_status = data.get("status")
+            if previous_status not in {"completed", "cancelled"}:
+                raise TaskWorkflowError("TASK_PHASE_REOPEN_INVALID_STATUS", "only completed or cancelled tasks can be reopened")
+            reason = _required_text(args.reason, "--reason")
+            evidence = _refs(args.evidence_ref, "--evidence-ref", required=True)
+            _assert_delegated_resources_closed(task_dir, data)
+            recoveries = meta.setdefault("task_lifecycle_recoveries", [])
+            if not isinstance(recoveries, list) or any(not isinstance(record, dict) for record in recoveries):
+                raise TaskWorkflowError("TASK_PHASE_TASK_INVALID", "task lifecycle recovery history is malformed")
+            recovery = {
+                "from_status": previous_status,
+                "to_status": "planning",
+                "reason": reason,
+                "evidence_refs": evidence,
+                "reopened_at": datetime.now(timezone.utc).isoformat(),
+                "terminal_completed_at": data.get("completedAt"),
+                "terminal_cancellation": copy.deepcopy(meta.get("task_cancellation")),
+            }
+            state = meta.get("task_workflow")
+            if state is not None:
+                state = _state(meta)
+                state["implementation_authorization"] = None
+                state["route_dependency_admission"] = None
+                state["closeout_disposition"] = None
+            recoveries.append(recovery)
+            data["status"] = "planning"
+            data["completedAt"] = None
+            from .task_move import relocate_task
+            from .active_task import clear_task_from_sessions
+            from .task_continuity import clear_task_runtime_records
+
+            repo_root = get_repo_root()
+            # Relocation rewrites runtime paths; terminal runtime must be discarded first.
+            for runtime_dir in (task_dir, repo_root / ".trellis/tasks/planning" / task_dir.name):
+                clear_task_from_sessions(str(runtime_dir), repo_root)
+                if not clear_task_runtime_records(repo_root, runtime_dir.relative_to(repo_root).as_posix()):
+                    raise TaskWorkflowError("TASK_PHASE_RUNTIME_CLEANUP_FAILED", "could not discard terminal task runtime; task remains terminal")
+            task_dir = relocate_task(repo_root, task_dir, data)
+            print(json.dumps({"status": "planning", "task_lifecycle_recovery": recovery, "runtime_records_cleared": True}, ensure_ascii=False))
+            return 0
+    except TaskWorkflowError as error:
+        print(f"{error.code}: {error}", file=sys.stderr)
+        return 1
+
+
 def task_closeout_readiness(data: dict, disposition: str) -> str | None:
     if "meta" in data and not isinstance(data["meta"], dict):
         return "task metadata is malformed"
@@ -982,8 +1261,7 @@ def task_closeout_readiness(data: dict, disposition: str) -> str | None:
     if state.get("closeout_disposition") != disposition:
         return f"Delivery Review and On-Site Closeout Phase disposition is {state.get('closeout_disposition')}; expected {disposition}"
     if disposition == "cancelled":
-        withdrawal = state.get("return_record")
-        if not isinstance(withdrawal, dict) or withdrawal.get("to") != PHASE_IDS[4] or not withdrawal.get("evidence_refs"):
+        if not _is_withdrawal_route(state):
             return "cancellation requires a user-confirmed route to Delivery Review and On-Site Closeout Phase"
     return None
 
@@ -1033,27 +1311,96 @@ def _validate_child_dispositions(
     return choices
 
 
+def cmd_delegate_reconcile(args: argparse.Namespace) -> int:
+    try:
+        root = get_repo_root().resolve()
+        task_dir = _task_dir(args.child_task)
+        data, meta = _load(task_dir)
+        record = meta.get("delegated_worktree_execution_record")
+        if not isinstance(record, dict):
+            raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "no valid delegated execution mapping")
+        if record.get("status") == "retired" and isinstance(record.get("closure_evidence"), dict):
+            print(json.dumps(record, ensure_ascii=False))
+            return 0
+        label = record.get("label_task_id", task_dir.name)
+        agents = _paseo_list(["agent", "ls", "--all", "--global", "--background", "--json", "--label", f"trellis.task_id={label}"], root, "TASK_DELEGATE_RECONCILIATION_REQUIRED")
+        if any(agent.get("status") != "closed" for agent in agents):
+            raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", "a delegated Paseo agent is still active or unknown")
+        agent_id = record.get("agent_id")
+        if agent_id and not any(agent.get("id") == agent_id for agent in agents):
+            raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "recorded agent is not available; preserve its mapping until native closure evidence is available")
+        worktree_path = record.get("worktree_path")
+        workspace_id = record.get("workspace_id")
+        workspaces = _paseo_list(["workspace", "ls", "--background", "--json"], root, "TASK_DELEGATE_RECONCILIATION_REQUIRED")
+        workspace = next((row for row in workspaces if row.get("workspaceId") == workspace_id), None) if workspace_id else None
+        if workspace and (not isinstance(worktree_path, str) or Path(workspace.get("cwd", "")).resolve() != Path(worktree_path).resolve()):
+            raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "workspace mapping does not match")
+        head = None
+        if isinstance(worktree_path, str) and Path(worktree_path).is_dir():
+            worktree = Path(worktree_path).resolve()
+            common = Path(_git_output(["rev-parse", "--git-common-dir"], worktree))
+            common = (common if common.is_absolute() else worktree / common).resolve()
+            expected_common = Path(_git_output(["rev-parse", "--git-common-dir"], root))
+            expected_common = (expected_common if expected_common.is_absolute() else root / expected_common).resolve()
+            if common != expected_common or _git_output(["branch", "--show-current"], worktree) != record.get("branch"):
+                raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "worktree does not belong to the recorded repository and branch")
+            dirty = _git_output(["status", "--porcelain", "--untracked-files=all"], worktree)
+            allowed = "?? " + record.get("result_path", "")
+            if any(line != allowed for line in dirty.splitlines()):
+                raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "worktree contains unintegrated changes; preserve and integrate them before retiring")
+            head = _git_output(["rev-parse", "HEAD"], worktree)
+            if run_git(["merge-base", "--is-ancestor", head, "HEAD"], cwd=root)[0] != 0:
+                raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "worktree commits are not integrated into the coordinator checkout")
+        elif workspace:
+            raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "workspace still exists but its worktree cannot be inspected")
+        elif not agent_id:
+            branch = record.get("branch")
+            if not isinstance(branch, str) or run_git(["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=root)[0] != 1:
+                raise TaskWorkflowError("TASK_DELEGATE_RECONCILIATION_REQUIRED", "incomplete mapping still has an unresolved branch")
+        evidence = {"agent_ids": [agent.get("id") for agent in agents], "workspace_id": workspace_id, "head": head, "checked_at": datetime.now(timezone.utc).isoformat()}
+        if not args.execute:
+            print(json.dumps({"status": "ready", "evidence": evidence}, ensure_ascii=False))
+            return 0
+        reason = _required_text(args.reason, "--reason")
+        approval_ref = _required_text(args.approval_ref, "--approval-ref")
+        record.update({"status": "retired", "closure_evidence": {**evidence, "reason": reason, "approval_ref": approval_ref}})
+        _save(task_dir / FILE_TASK_JSON, data)
+        print(json.dumps(record, ensure_ascii=False))
+        return 0
+    except TaskWorkflowError as error:
+        print(f"{error.code}: {error}", file=sys.stderr)
+        return 1
+
+
 def _assert_delegated_resources_closed(task_dir: Path, data: dict) -> None:
-    repo_root = get_repo_root()
     children = data.get("children", [])
     if not isinstance(children, list):
         raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", "linked child task list is malformed")
     for task_id in [task_dir.name, *children]:
         _, child_meta = _load(_task_dir(task_id))
-        record = child_meta.get("delegated_worktree_execution_record")
-        if record is None:
-            continue
-        agent_id = record.get("agent_id") if isinstance(record, dict) else None
-        if not isinstance(agent_id, str) or not agent_id.strip():
-            raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", f"delegated execution status is unknown for {task_id}; preserve the current state")
-        agents = _paseo_list(
-            ["agent", "ls", "--all", "--global", "--background", "--json", "--label", f"trellis.task_id={task_id}"],
-            repo_root,
-            "TASK_PHASE_RESOURCE_ACTIVE",
-        )
-        agent = next((item for item in agents if item.get("id") == agent_id), None)
-        if agent is None or agent.get("status") != "closed":
-            raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", f"delegated Paseo agent for {task_id} is not confirmed closed; preserve the current state")
+        _assert_delegated_record_closed(task_id, child_meta.get("delegated_worktree_execution_record"))
+
+
+def _assert_delegated_record_closed(task_id: str, record) -> None:
+    if record is None:
+        return
+    if isinstance(record, dict) and record.get("status") == "retired" and isinstance(record.get("closure_evidence"), dict):
+        return
+    agent_id = record.get("agent_id") if isinstance(record, dict) else None
+    if not isinstance(agent_id, str) or not agent_id.strip():
+        raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", f"delegated execution status is unknown for {task_id}; preserve the current state")
+    agents = _paseo_list(
+        ["agent", "ls", "--all", "--global", "--background", "--json", "--label", f"trellis.task_id={record.get('label_task_id', task_id)}"],
+        get_repo_root(),
+        "TASK_PHASE_RESOURCE_ACTIVE",
+    )
+    agent = next((item for item in agents if item.get("id") == agent_id), None)
+    if agent is None or agent.get("status") != "closed":
+        raise TaskWorkflowError("TASK_PHASE_RESOURCE_ACTIVE", f"delegated Paseo agent for {task_id} is not confirmed closed; preserve the current state")
+    worktree_path = record.get("worktree_path")
+    if isinstance(worktree_path, str) and Path(worktree_path).is_dir():
+        if _git_output(["status", "--porcelain", "--untracked-files=all", "--", ".trellis/tasks", ".trellis/.runtime"], Path(worktree_path)):
+            raise TaskWorkflowError("TASK_DELEGATE_TASK_FACTS_CHANGED", "delegated worktree changed protected task facts; preserve evidence and exclude those changes before integration")
 
 
 def cmd_complete_task(args: argparse.Namespace) -> int:
@@ -1068,9 +1415,7 @@ def cmd_complete_task(args: argparse.Namespace) -> int:
             disposition = state.get("closeout_disposition")
             if disposition not in {"delivery_ready", "no_go"}:
                 raise TaskWorkflowError("TASK_PHASE_CLOSEOUT_REQUIRED", "Delivery Review and On-Site Closeout Phase must accept delivery_ready or no_go before complete")
-            closeout = state["phases"][PHASE_IDS[4]]
-            if _artifact_digest(task_dir, closeout.get("artifact_refs", [])) != closeout.get("artifact_revision"):
-                raise TaskWorkflowError("TASK_PHASE_STALE_ARTIFACT", "Delivery Review and On-Site Closeout Phase artifacts changed after acceptance; review the current delivery candidate again")
+            _require_current_accepted_artifacts(task_dir, state)
             readiness_error = task_closeout_readiness(data, disposition)
             if readiness_error:
                 raise TaskWorkflowError("TASK_PHASE_CLOSEOUT_REQUIRED", readiness_error)
@@ -1081,7 +1426,8 @@ def cmd_complete_task(args: argparse.Namespace) -> int:
                 raise TaskWorkflowError("TASK_PHASE_IMPLEMENTATION_NOT_STARTED", "implementation tasks must enter in_progress before complete")
             data["status"] = "completed"
             data["completedAt"] = datetime.now().strftime("%Y-%m-%d")
-            _save(task_dir / FILE_TASK_JSON, data)
+            from .task_move import relocate_task
+            task_dir = relocate_task(get_repo_root(), task_dir, data)
             from .active_task import clear_task_from_sessions
             from .task_continuity import clear_task_runtime_records