@blxzer/cursor-trellis 0.1.0

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

@@ -0,0 +1,1735 @@
+#!/usr/bin/env python3
+"""
+Task quality gate helpers.
+
+Gate records are stored in task.json under:
+quality_gate_results.transitions[transition][gate]
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .task_map import (
+    get_child_state,
+    load_task_map,
+    validate_child_archive_state,
+    validate_parent_children_complete,
+)
+
+SCHEMA_VERSION = 1
+BASELINE_GATE = "baseline-check"
+
+KNOWN_TRANSITIONS = {
+    "start-execution",
+    "full-task-complete",
+    "child-review",
+    "parent-changes",
+    "parent-accepted",
+    "parent-integrating",
+    "parent-integrated",
+    "parent-cancelled",
+}
+
+REVIEW_GATES = {
+    "requirements-review",
+    "code-review",
+    "architecture-review",
+    "architecture-deep-review",
+    "integration-review",
+}
+
+KNOWN_GATES = {BASELINE_GATE, *REVIEW_GATES}
+RESULTS = {"PASS", "FAIL", "SKIPPED"}
+FAIL_ROOT_CAUSES = {
+    "implementation-defect": "Execution",
+    "contract-changing-defect": "Planning",
+    "validation-environment-blocker": "Verification / Review",
+}
+
+PROFILE_DEFAULT_GATES = {
+    "standard": ["requirements-review", "code-review"],
+    "strict": ["requirements-review", "code-review"],
+    "architecture": [
+        "requirements-review",
+        "architecture-review",
+        "code-review",
+    ],
+}
+
+ALLOWED_EXECUTION_MODES = {"inline", "worker", "child-task"}
+ALLOWED_ISOLATION = {"main-worktree", "git-worktree"}
+ALLOWED_VERIFICATION_PROFILES = {"standard", "strict", "architecture"}
+ALLOWED_RETRIEVAL_PROFILES = {
+    "exact-only",
+    "semantic",
+    "structure",
+    "architecture-memory",
+}
+ALLOWED_GATE_MODES = {"profile", "explicit"}
+
+MAX_SHORT_FIELD = 240
+MAX_REASON = 500
+REVIEWER_RE = re.compile(r"^[A-Za-z0-9_.:@/-]+$")
+VALIDATION_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?validation"
+    r"(?:\s+(?:commands?|results?|evidence))?\s*:\s*\S"
+)
+ACCEPTANCE_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:final\s+|user\s+)?acceptance"
+    r"(?:\s+evidence)?\s*:\s*\S"
+)
+ACCEPTED_BY_USER_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?accepted\s+by\s+user\s*:\s*\S"
+)
+NO_DURABLE_LEARNING_RE = re.compile(r"(?i)\bno\s+durable\s+learning\b")
+DURABLE_LEARNING_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:durable\s+learning|learning\s+decision|"
+    r"spec\s+updates?|spec\s+update\s+(?:needed|evidence)|updated\s+spec|"
+    r"retrospective(?:\.md)?|learning\s+artifact)\s*:\s*\S"
+)
+INTEGRATION_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:final\s+)?integration"
+    r"(?:\s+evidence)?\s*:\s*\S"
+)
+REVIEWED_CHANGE_SET_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:reviewed\s+)?"
+    r"(?:change[- ]set|changeset|diff|git\s+diff|ref|git\s+ref)"
+    r"(?:\s+(?:identity|evidence|summary|ref))?\s*:\s*(\S[^\r\n]*)$"
+)
+PRD_ACCEPTANCE_CRITERIA_HEADING_RE = re.compile(
+    r"(?im)^\s*#{1,6}\s*acceptance\s+criteria\s*$"
+)
+PRD_ACCEPTANCE_ITEM_RE = re.compile(
+    r"(?im)^\s*-\s*\[[ xX]\]\s+(.+)$"
+)
+PRD_PLACEHOLDER_RE = re.compile(r"(?i)^\s*(TBD|TODO|待定|待补充)(?:\s*[.:：])?\s*$")
+AUTO_PLANNING_REVIEWER = "trellis-cli"
+START_EXECUTION_AUTO_GATES = frozenset({"requirements-review", "architecture-review"})
+
+STABLE_TASK_KEYS = (
+    "id",
+    "name",
+    "title",
+    "description",
+    "status",
+    "dev_type",
+    "scope",
+    "package",
+    "priority",
+    "creator",
+    "assignee",
+    "parent",
+    "children",
+    "subtasks",
+    "relatedFiles",
+    "notes",
+    "meta",
+    "branch",
+    "base_branch",
+    "task_kind",
+    "task_type",
+    "kind",
+    "mode",
+    "contract_epoch",
+)
+
+
+@dataclass
+class GateGuardResult:
+    """Result from a protected-transition guard."""
+
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    contract_fingerprint: str = ""
+    artifact_fingerprints: dict[str, str] = field(default_factory=dict)
+    required_gates: list[str] = field(default_factory=list)
+    baseline_record: dict | None = None
+    is_full_task: bool = False
+    auto_gate_records: dict[str, dict] = field(default_factory=dict)
+
+
+def utc_now() -> str:
+    """Return a compact UTC timestamp for task.json records."""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace(
+        "+00:00", "Z"
+    )
+
+
+def normalize_result(result: str) -> str:
+    """Normalize a CLI result value."""
+    return result.strip().upper()
+
+
+def is_full_task(task_dir: Path, task_data: dict | None = None) -> bool:
+    """Return True when a task should satisfy Full Task gates."""
+    data = task_data or {}
+    meta = data.get("meta") if isinstance(data.get("meta"), dict) else {}
+    candidates = [
+        data.get("task_kind"),
+        data.get("task_type"),
+        data.get("kind"),
+        data.get("mode"),
+        meta.get("task_kind"),
+        meta.get("task_type"),
+        meta.get("classification"),
+        meta.get("mode"),
+    ]
+
+    for value in candidates:
+        if not isinstance(value, str):
+            continue
+        normalized = value.lower().replace("_", "-")
+        if "full" in normalized:
+            return True
+        if "lite" in normalized:
+            return False
+
+    return (task_dir / "design.md").is_file() and (task_dir / "implement.md").is_file()
+
+
+def read_strategy_contract(task_dir: Path) -> tuple[dict, list[str]]:
+    """Parse the lightweight Development Strategy Contract from implement.md."""
+    implement_path = task_dir / "implement.md"
+    if not implement_path.is_file():
+        return {}, ["implement.md"]
+
+    try:
+        lines = implement_path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}, ["implement.md could not be read"]
+
+    contract: dict = {}
+    section: str | None = None
+    list_key: str | None = None
+    started = False
+
+    top_level_keys = {
+        "execution_mode",
+        "isolation",
+        "verification_profile",
+        "retrieval_profile",
+        "optional_capabilities",
+        "quality_gates",
+    }
+
+    for raw_line in lines:
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("#") or stripped.startswith("```"):
+            continue
+
+        top_match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$", stripped)
+        if top_match:
+            key = top_match.group(1)
+            value = top_match.group(2).strip()
+            if key in top_level_keys:
+                started = True
+                section = key if key == "quality_gates" else None
+                list_key = key if key == "optional_capabilities" and not value else None
+                if key == "quality_gates":
+                    contract.setdefault("quality_gates", {})
+                elif key == "optional_capabilities":
+                    if value:
+                        contract[key] = _parse_inline_list(value)
+                    else:
+                        contract[key] = []
+                else:
+                    contract[key] = value
+                continue
+
+        if not started:
+            continue
+
+        nested_match = re.match(r"^\s+([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$", line)
+        if nested_match and section == "quality_gates":
+            key = nested_match.group(1)
+            value = nested_match.group(2).strip()
+            gates = contract.setdefault("quality_gates", {})
+            if value:
+                gates[key] = _parse_inline_list(value)
+                list_key = None
+            else:
+                gates[key] = []
+                list_key = f"quality_gates.{key}"
+            continue
+
+        item_match = re.match(r"^\s*-\s+(.+)$", line)
+        if item_match:
+            item = item_match.group(1).strip()
+            if list_key == "optional_capabilities":
+                contract.setdefault("optional_capabilities", []).append(item)
+            elif list_key and list_key.startswith("quality_gates."):
+                gate_key = list_key.split(".", 1)[1]
+                gates = contract.setdefault("quality_gates", {})
+                gates.setdefault(gate_key, []).append(item)
+
+    errors = validate_strategy_contract(contract)
+    return contract, errors
+
+
+def validate_strategy_contract(contract: dict) -> list[str]:
+    """Validate the parsed Development Strategy Contract."""
+    errors: list[str] = []
+    required = [
+        "execution_mode",
+        "isolation",
+        "verification_profile",
+        "retrieval_profile",
+        "optional_capabilities",
+        "quality_gates",
+    ]
+    for key in required:
+        if key not in contract:
+            errors.append(f"Development Strategy Contract missing {key}")
+
+    execution_mode = contract.get("execution_mode")
+    if execution_mode and execution_mode not in ALLOWED_EXECUTION_MODES:
+        errors.append(f"invalid execution_mode: {execution_mode}")
+
+    isolation = contract.get("isolation")
+    if isolation and isolation not in ALLOWED_ISOLATION:
+        errors.append(f"invalid isolation: {isolation}")
+
+    verification_profile = contract.get("verification_profile")
+    if verification_profile and verification_profile not in ALLOWED_VERIFICATION_PROFILES:
+        errors.append(f"invalid verification_profile: {verification_profile}")
+
+    retrieval_profile = contract.get("retrieval_profile")
+    if retrieval_profile and retrieval_profile not in ALLOWED_RETRIEVAL_PROFILES:
+        errors.append(f"invalid retrieval_profile: {retrieval_profile}")
+
+    optional_capabilities = contract.get("optional_capabilities")
+    if "optional_capabilities" in contract and not isinstance(optional_capabilities, list):
+        errors.append("optional_capabilities must be a list")
+
+    gates = contract.get("quality_gates")
+    if isinstance(gates, dict):
+        errors.extend(_validate_quality_gates(gates, verification_profile))
+    elif "quality_gates" in contract:
+        errors.append("quality_gates must be a mapping")
+
+    return errors
+
+
+def enabled_gates_for_contract(contract: dict) -> list[str]:
+    """Return enabled non-baseline gates from a parsed contract."""
+    gates = contract.get("quality_gates")
+    if not isinstance(gates, dict):
+        return []
+
+    mode = gates.get("mode", "profile")
+    if mode == "explicit":
+        enabled = gates.get("enabled", [])
+        return [g for g in enabled if isinstance(g, str)]
+
+    profile = gates.get("profile") or contract.get("verification_profile") or "standard"
+    return list(PROFILE_DEFAULT_GATES.get(profile, PROFILE_DEFAULT_GATES["standard"]))
+
+
+def required_gates_for_transition(transition: str, contract: dict) -> list[str]:
+    """Return non-baseline gates required before a transition."""
+    enabled = set(enabled_gates_for_contract(contract))
+
+    if transition == "start-execution":
+        required = ["requirements-review"]
+        if "architecture-review" in enabled:
+            required.append("architecture-review")
+        return required
+
+    if transition in ("full-task-complete", "child-review"):
+        required = ["code-review"]
+        if "architecture-review" in enabled:
+            required.append("architecture-review")
+        if "architecture-deep-review" in enabled:
+            required.append("architecture-deep-review")
+        return required
+
+    if transition == "parent-integrated":
+        return ["integration-review"]
+
+    return []
+
+
+def compute_contract_fingerprint(
+    task_dir: Path,
+    task_data: dict,
+    contract: dict | None = None,
+) -> str:
+    """Compute a task-level fingerprint excluding generated result fields."""
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "task_dir": task_dir.name,
+        "stable_task": _stable_task_data(task_data),
+        "strategy_contract": contract or {},
+    }
+    return _hash_payload(payload)
+
+
+def compute_artifact_fingerprint(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+    gate: str,
+) -> str:
+    """Compute a transition/gate-scoped artifact fingerprint."""
+    files = _artifact_files_for(transition, gate)
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "transition": transition,
+        "gate": gate,
+        "task_dir": task_dir.name,
+        "stable_task": _stable_task_data(task_data),
+        "parent_contract": _parent_contract_metadata(
+            task_dir,
+            task_data,
+            transition,
+        ),
+        "reviewed_change_set": _reviewed_change_set_metadata(
+            task_dir,
+            transition,
+        ),
+        "files": _read_artifact_files(task_dir, files),
+    }
+    return _hash_payload(payload)
+
+
+def make_baseline_record(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+    contract: dict | None = None,
+    evidence: str = "task.json",
+) -> dict:
+    """Build a CLI-owned baseline-check PASS record."""
+    contract_fingerprint = compute_contract_fingerprint(task_dir, task_data, contract)
+    artifact_fingerprint = compute_artifact_fingerprint(
+        task_dir, task_data, transition, BASELINE_GATE
+    )
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "transition": transition,
+        "gate": BASELINE_GATE,
+        "result": "PASS",
+        "reviewer": "trellis-cli",
+        "evidence": evidence,
+        "checked_at": utc_now(),
+        "contract_fingerprint": contract_fingerprint,
+        "artifact_fingerprint": artifact_fingerprint,
+        "issue_fingerprint": None,
+        "consecutive_failures": 0,
+        "approved_skip": None,
+    }
+
+
+def write_gate_record(task_data: dict, transition: str, gate: str, record: dict) -> None:
+    """Write a gate record into task_data in-place."""
+    qgr = task_data.get("quality_gate_results")
+    if not isinstance(qgr, dict):
+        qgr = {}
+        task_data["quality_gate_results"] = qgr
+
+    qgr["schema_version"] = SCHEMA_VERSION
+    qgr["contract_fingerprint"] = record.get("contract_fingerprint")
+    qgr["artifact_fingerprint"] = record.get("artifact_fingerprint")
+    transitions = qgr.get("transitions")
+    if not isinstance(transitions, dict):
+        transitions = {}
+        qgr["transitions"] = transitions
+
+    transition_records = transitions.get(transition)
+    if not isinstance(transition_records, dict):
+        transition_records = {}
+        transitions[transition] = transition_records
+    transition_records[gate] = record
+
+
+def build_reviewer_gate_record(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+    gate: str,
+    result: str,
+    reviewer: str,
+    evidence: str,
+    issue_fingerprint: str | None = None,
+    issue_summary: str | None = None,
+    root_cause: str | None = None,
+    skip_approved_by: str | None = None,
+    skip_reason: str | None = None,
+    contract_fingerprint: str | None = None,
+    artifact_fingerprint: str | None = None,
+) -> tuple[dict | None, list[str], list[str]]:
+    """Validate and build a non-baseline reviewer gate record."""
+    normalized_result = normalize_result(result)
+    errors = validate_reviewer_gate_input(
+        transition=transition,
+        gate=gate,
+        result=normalized_result,
+        reviewer=reviewer,
+        evidence=evidence,
+        issue_fingerprint=issue_fingerprint,
+        issue_summary=issue_summary,
+        root_cause=root_cause,
+        skip_approved_by=skip_approved_by,
+        skip_reason=skip_reason,
+    )
+    warnings: list[str] = []
+    if errors:
+        return None, errors, warnings
+
+    contract, contract_errors = read_strategy_contract(task_dir) if is_full_task(task_dir, task_data) else ({}, [])
+    if contract_errors:
+        errors.extend(contract_errors)
+        return None, errors, warnings
+
+    current_contract_fingerprint = compute_contract_fingerprint(
+        task_dir, task_data, contract
+    )
+    current_artifact_fingerprint = compute_artifact_fingerprint(
+        task_dir, task_data, transition, gate
+    )
+    if contract_fingerprint and contract_fingerprint != current_contract_fingerprint:
+        errors.append("provided contract fingerprint does not match current task artifacts")
+    if artifact_fingerprint and artifact_fingerprint != current_artifact_fingerprint:
+        errors.append("provided artifact fingerprint does not match current task artifacts")
+    if errors:
+        return None, errors, warnings
+
+    previous = _get_gate_record(task_data, transition, gate)
+    consecutive_failures = 0
+    required_user_choice = None
+    if normalized_result == "FAIL":
+        consecutive_failures = _next_consecutive_failures(previous, issue_fingerprint)
+        if consecutive_failures > 3:
+            required_user_choice = {
+                "required": True,
+                "reason": "same gate and issue fingerprint failed more than three times",
+                "options": [
+                    "re-plan",
+                    "continue-fixing",
+                    "user-approved-skip-if-allowed",
+                ],
+            }
+            warnings.append(
+                "same gate and issue fingerprint has failed more than three times; ask the user to choose re-plan, continue fixing, or user-approved skip if allowed"
+            )
+
+    approved_skip = None
+    if normalized_result == "SKIPPED":
+        approved_skip = {
+            "approved_by": skip_approved_by,
+            "reason": skip_reason,
+            "approved_at": utc_now(),
+        }
+
+    record = {
+        "schema_version": SCHEMA_VERSION,
+        "transition": transition,
+        "gate": gate,
+        "result": normalized_result,
+        "reviewer": reviewer,
+        "evidence": evidence,
+        "checked_at": utc_now(),
+        "contract_fingerprint": current_contract_fingerprint,
+        "artifact_fingerprint": current_artifact_fingerprint,
+        "issue_fingerprint": issue_fingerprint if normalized_result == "FAIL" else None,
+        "root_cause": root_cause if normalized_result == "FAIL" else None,
+        "route": _route_for_fail_root_cause(root_cause) if normalized_result == "FAIL" else None,
+        "consecutive_failures": consecutive_failures,
+        "required_user_choice": required_user_choice,
+        "approved_skip": approved_skip,
+    }
+    if issue_summary and normalized_result == "FAIL":
+        record["issue_summary"] = issue_summary
+    return record, [], warnings
+
+
+def validate_start_execution(
+    task_dir: Path,
+    task_data: dict | None,
+    approved: bool,
+) -> GateGuardResult:
+    """Validate start-execution readiness."""
+    errors: list[str] = []
+    if task_data is None:
+        return GateGuardResult(ok=False, errors=["task.json"])
+
+    status = task_data.get("status")
+    if status not in ("planning", "in_progress"):
+        errors.append(f"task status must be planning or in_progress, got {status!r}")
+
+    errors.extend(_required_file_errors(task_dir, ["prd.md"]))
+
+    has_design = (task_dir / "design.md").is_file()
+    has_implement = (task_dir / "implement.md").is_file()
+    if has_design != has_implement:
+        errors.append("design.md and implement.md must be present together for Full Tasks")
+
+    full_task = is_full_task(task_dir, task_data)
+    contract: dict = {}
+    required_gates: list[str] = []
+    if full_task:
+        contract, contract_errors = read_strategy_contract(task_dir)
+        errors.extend(contract_errors)
+        if not contract_errors:
+            required_gates = required_gates_for_transition("start-execution", contract)
+
+    contract_fingerprint = compute_contract_fingerprint(task_dir, task_data, contract)
+    artifact_fingerprints = {
+        BASELINE_GATE: compute_artifact_fingerprint(
+            task_dir, task_data, "start-execution", BASELINE_GATE
+        )
+    }
+
+    auto_gate_records: dict[str, dict] = {}
+    for gate in required_gates:
+        artifact_fingerprints[gate] = compute_artifact_fingerprint(
+            task_dir, task_data, "start-execution", gate
+        )
+        gate_errors = _validate_gate_record_for_transition(
+            task_data=task_data,
+            transition="start-execution",
+            gate=gate,
+            contract_fingerprint=contract_fingerprint,
+            artifact_fingerprint=artifact_fingerprints[gate],
+        )
+        if gate_errors and gate in START_EXECUTION_AUTO_GATES and _only_missing_gate_record(
+            gate_errors
+        ):
+            readiness_errors = _start_execution_planning_gate_readiness_errors(
+                task_dir,
+                gate,
+                full_task=full_task,
+                contract=contract,
+            )
+            if readiness_errors:
+                errors.extend(readiness_errors)
+            else:
+                auto_gate_records[gate] = make_planning_review_gate_record(
+                    task_dir=task_dir,
+                    task_data=task_data,
+                    transition="start-execution",
+                    gate=gate,
+                    contract=contract,
+                    contract_fingerprint=contract_fingerprint,
+                    artifact_fingerprint=artifact_fingerprints[gate],
+                )
+        else:
+            errors.extend(gate_errors)
+
+    if approved:
+        errors.extend(
+            _validate_existing_execution_approval(
+                task_data=task_data,
+                contract_fingerprint=contract_fingerprint,
+                artifact_fingerprint=artifact_fingerprints[BASELINE_GATE],
+            )
+        )
+
+    if not approved:
+        errors.append("--approved is required for mutation")
+
+    baseline_record = None
+    if not errors:
+        baseline_record = make_baseline_record(
+            task_dir, task_data, "start-execution", contract
+        )
+
+    return GateGuardResult(
+        ok=not errors,
+        errors=errors,
+        contract_fingerprint=contract_fingerprint,
+        artifact_fingerprints=artifact_fingerprints,
+        required_gates=required_gates,
+        baseline_record=baseline_record,
+        is_full_task=full_task,
+        auto_gate_records=auto_gate_records,
+    )
+
+
+def _validate_existing_execution_approval(
+    task_data: dict,
+    contract_fingerprint: str,
+    artifact_fingerprint: str,
+) -> list[str]:
+    """Reject stale approval state before re-approving an in-progress task."""
+    approval = task_data.get("execution_approval")
+    if not isinstance(approval, dict):
+        return []
+
+    errors: list[str] = []
+    if approval.get("transition") != "start-execution":
+        errors.append("stale execution approval: transition mismatch")
+    if approval.get("contract_fingerprint") != contract_fingerprint:
+        errors.append("stale execution approval: contract fingerprint changed")
+    if approval.get("artifact_fingerprint") != artifact_fingerprint:
+        errors.append("stale execution approval: artifact fingerprint changed")
+    if errors:
+        errors.append(
+            "return to Planning, refresh gates, run start-execution --check, and ask for explicit approval again"
+        )
+    return errors
+
+
+def validate_start_execution_check(
+    task_dir: Path,
+    task_data: dict | None,
+) -> GateGuardResult:
+    """Validate start-execution preflight without requiring approval."""
+    result = validate_start_execution(task_dir, task_data, approved=True)
+    return result
+
+
+def validate_archive(
+    task_dir: Path,
+    task_data: dict | None,
+) -> GateGuardResult:
+    """Validate archive readiness without mutating task files."""
+    errors: list[str] = []
+    if task_data is None:
+        return GateGuardResult(ok=False, errors=["task.json"])
+
+    errors.extend(_required_file_errors(task_dir, ["verify.md"]))
+    errors.extend(_verify_evidence_errors(task_dir, task_data))
+
+    parent_name = task_data.get("parent")
+    if isinstance(parent_name, str) and parent_name:
+        parent_dir = task_dir.parent / parent_name
+        if not parent_dir.is_dir():
+            errors.append(f"parent task not found: {parent_name}")
+        else:
+            errors.extend(validate_child_archive_state(parent_dir, task_dir.name))
+            if get_child_state(parent_dir, task_dir.name) == "integrated":
+                errors.extend(_required_file_errors(task_dir, ["handoff.md"]))
+
+    child_names = task_data.get("children")
+    if isinstance(child_names, list) and child_names:
+        errors.extend(
+            validate_parent_children_complete(
+                task_dir,
+                [name for name in child_names if isinstance(name, str)],
+            )
+        )
+
+    full_task = is_full_task(task_dir, task_data)
+    contract: dict = {}
+    required_gates: list[str] = []
+    artifact_fingerprints: dict[str, str] = {}
+    baseline_record = None
+
+    if full_task:
+        contract, contract_errors = read_strategy_contract(task_dir)
+        errors.extend(contract_errors)
+        if not contract_errors:
+            required_gates = required_gates_for_transition(
+                "full-task-complete", contract
+            )
+
+    contract_fingerprint = compute_contract_fingerprint(task_dir, task_data, contract)
+
+    if full_task:
+        artifact_fingerprints[BASELINE_GATE] = compute_artifact_fingerprint(
+            task_dir, task_data, "full-task-complete", BASELINE_GATE
+        )
+        for gate in required_gates:
+            artifact_fingerprints[gate] = compute_artifact_fingerprint(
+                task_dir, task_data, "full-task-complete", gate
+            )
+            errors.extend(
+                _validate_gate_record_for_transition(
+                    task_data=task_data,
+                    transition="full-task-complete",
+                    gate=gate,
+                    contract_fingerprint=contract_fingerprint,
+                    artifact_fingerprint=artifact_fingerprints[gate],
+                )
+            )
+        if not errors:
+            baseline_record = make_baseline_record(
+                task_dir, task_data, "full-task-complete", contract
+            )
+
+    return GateGuardResult(
+        ok=not errors,
+        errors=errors,
+        contract_fingerprint=contract_fingerprint,
+        artifact_fingerprints=artifact_fingerprints,
+        required_gates=required_gates,
+        baseline_record=baseline_record,
+        is_full_task=full_task,
+    )
+
+
+def _verify_evidence_errors(task_dir: Path, task_data: dict) -> list[str]:
+    """Validate human-readable archive evidence in verify.md."""
+    verify_path = task_dir / "verify.md"
+    if not verify_path.is_file():
+        return []
+
+    try:
+        content = verify_path.read_text(encoding="utf-8")
+    except OSError:
+        return ["verify.md could not be read for archive evidence"]
+
+    errors: list[str] = []
+    if not _has_validation_evidence(content):
+        errors.append("verify.md missing validation evidence")
+    if not _has_final_acceptance_evidence(content):
+        errors.append("verify.md missing final acceptance evidence")
+    if not _has_durable_learning_evidence(content):
+        errors.append("verify.md missing durable-learning decision evidence")
+
+    child_names = task_data.get("children")
+    if isinstance(child_names, list) and child_names:
+        if not INTEGRATION_EVIDENCE_RE.search(content):
+            errors.append("verify.md missing final integration evidence")
+
+    return errors
+
+
+def _has_validation_evidence(content: str) -> bool:
+    return bool(VALIDATION_EVIDENCE_RE.search(content))
+
+
+def _has_final_acceptance_evidence(content: str) -> bool:
+    return bool(
+        ACCEPTANCE_EVIDENCE_RE.search(content)
+        or ACCEPTED_BY_USER_RE.search(content)
+    )
+
+
+def _has_durable_learning_evidence(content: str) -> bool:
+    return bool(
+        NO_DURABLE_LEARNING_RE.search(content)
+        or DURABLE_LEARNING_EVIDENCE_RE.search(content)
+    )
+
+
+def durable_learning_decision_status(content: str) -> dict[str, bool]:
+    """Return which durable-learning outcomes are signaled in verify.md text."""
+    return {
+        "no_durable_learning": bool(NO_DURABLE_LEARNING_RE.search(content)),
+        "spec_update": bool(
+            re.search(
+                r"(?im)^\s*(?:[-*]\s*)?(?:spec\s+updates?|spec\s+update\s+"
+                r"(?:needed|evidence)|updated\s+spec)\s*:\s*\S",
+                content,
+            )
+        ),
+        "learning_artifact": bool(
+            re.search(
+                r"(?im)^\s*(?:[-*]\s*)?(?:learning\s+artifact|retrospective(?:\.md)?)\s*:\s*\S",
+                content,
+            )
+            or re.search(
+                r"(?im)^\s*(?:[-*]\s*)?(?:durable\s+learning|learning\s+decision)\s*:\s*\S",
+                content,
+            )
+        ),
+        "any": _has_durable_learning_evidence(content),
+    }
+
+
+def suggest_spec_targets(repo_root: Path, task_dir: Path, task_data: dict) -> list[str]:
+    """Suggest existing spec paths from task scope; does not invent new rules."""
+    suggestions: list[str] = []
+    spec_root = repo_root / ".trellis" / "spec"
+    if not spec_root.is_dir():
+        return suggestions
+
+    package = task_data.get("package")
+    if isinstance(package, str) and package.strip():
+        pkg_index = spec_root / package.strip() / "index.md"
+        if pkg_index.is_file():
+            suggestions.append(f".trellis/spec/{package.strip()}/index.md")
+
+    scope = task_data.get("scope")
+    if isinstance(scope, str) and scope.strip():
+        scope_parts = [p for p in scope.strip().replace("\\", "/").split("/") if p]
+        scope_path = spec_root.joinpath(*scope_parts) if scope_parts else spec_root
+        if scope_path.is_dir():
+            index = scope_path / "index.md"
+            if index.is_file():
+                suggestions.append(
+                    f".trellis/spec/{scope_path.relative_to(spec_root).as_posix()}/index.md"
+                )
+
+    guide_paths = (
+        "guides/durable-learning-decision-guide.md",
+        "guides/index.md",
+    )
+    for rel in guide_paths:
+        path = spec_root / rel
+        if path.is_file():
+            suggestions.append(f".trellis/spec/{rel}")
+
+    return _dedupe_preserve_order(suggestions)[:6]
+
+
+def build_spec_update_scaffold(
+    repo_root: Path,
+    task_dir: Path,
+    task_data: dict,
+    *,
+    trigger: str | None = None,
+) -> str:
+    """Markdown checklist for spec capture; user/reviewer must confirm before editing specs."""
+    targets = suggest_spec_targets(repo_root, task_dir, task_data)
+    rel_task = f".trellis/tasks/{task_dir.name}"
+    lines = [
+        "## Spec update scaffold (reviewer-confirmed)",
+        "",
+        "_Suggestions only — do not treat this block as project policy until a human confirms._",
+        "",
+    ]
+    if trigger:
+        lines.extend([f"Trigger: {trigger.strip()}", ""])
+    lines.extend(
+        [
+            "1. Decide outcome in verify.md:",
+            "   - Routine: `Durable learning decision: no durable learning`",
+            "   - Reusable insight: `Spec update evidence: .trellis/spec/<path>` after edits",
+            f"   - Already documented: `Learning artifact: {rel_task}/handoff.md`",
+            "",
+            "2. Use `/trellis:update-spec` or `/trellis:break-loop` for depth; never auto-write specs.",
+            "",
+        ]
+    )
+    if targets:
+        lines.append("3. Existing spec indexes to consider (from task scope):")
+        for target in targets:
+            lines.append(f"   - `{target}`")
+        lines.append("")
+    else:
+        lines.append(
+            "3. Browse `.trellis/spec/<package-or-layer>/index.md` for the right code-spec file."
+        )
+        lines.append("")
+    lines.append(
+        "4. Re-run `python ./.trellis/scripts/task.py archive <task> --check` after verify.md is final."
+    )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _learning_decision_draft_lines(task_dir: Path, task_data: dict) -> list[str]:
+    """Default durable-learning block for prepare-archive-evidence."""
+    repo_root = task_dir.parent.parent.parent
+    targets = suggest_spec_targets(repo_root, task_dir, task_data)
+    target_hint = targets[0] if targets else ".trellis/spec/<layer>/index.md"
+    return [
+        "Durable learning decision: no durable learning for this task scope.",
+        "",
+        "# Replace the line above with ONE of these before archive:",
+        f"# Spec update evidence: {target_hint}",
+        f"# Learning artifact: .trellis/tasks/{task_dir.name}/handoff.md",
+        "# Spec update needed: (brief reason) — then run /trellis:update-spec and point Spec update evidence at the edited file",
+        "",
+    ]
+
+
+ARCHIVE_EVIDENCE_DRAFT_MARKER = "<!-- trellis:archive-evidence-draft -->"
+
+
+def _verify_evidence_status(task_dir: Path, task_data: dict) -> dict[str, bool]:
+    """Return which archive evidence sections are present in verify.md."""
+    verify_path = task_dir / "verify.md"
+    if not verify_path.is_file():
+        return {
+            "validation": False,
+            "acceptance": False,
+            "durable_learning": False,
+            "integration": False,
+        }
+    try:
+        content = verify_path.read_text(encoding="utf-8")
+    except OSError:
+        return {
+            "validation": False,
+            "acceptance": False,
+            "durable_learning": False,
+            "integration": False,
+        }
+
+    child_names = task_data.get("children")
+    has_children = isinstance(child_names, list) and bool(child_names)
+    return {
+        "validation": _has_validation_evidence(content),
+        "acceptance": _has_final_acceptance_evidence(content),
+        "durable_learning": _has_durable_learning_evidence(content),
+        "integration": (
+            bool(INTEGRATION_EVIDENCE_RE.search(content)) if has_children else True
+        ),
+    }
+
+
+def archive_repair_hints(
+    errors: list[str],
+    task_dir: Path,
+    task_data: dict,
+    guard: GateGuardResult,
+) -> list[str]:
+    """Map archive validation errors to actionable next-step hints."""
+    hints: list[str] = []
+    task_ref = task_dir.name
+    rel_task = f".trellis/tasks/{task_ref}"
+
+    for error in errors:
+        if error == "verify.md":
+            hints.append(
+                f"Create verify.md, then run: python ./.trellis/scripts/task.py "
+                f"prepare-archive-evidence {rel_task}"
+            )
+            continue
+        if error == "verify.md missing validation evidence":
+            hints.append(
+                "Add a grep-friendly line such as "
+                "'Validation commands: <command> — <outcome>' to verify.md, "
+                f"or run: python ./.trellis/scripts/task.py prepare-archive-evidence {rel_task}"
+            )
+            continue
+        if error == "verify.md missing final acceptance evidence":
+            hints.append(
+                "Add 'Final acceptance evidence: <criteria met>' or "
+                "'Accepted by user: <who/when>' to verify.md, "
+                f"or run prepare-archive-evidence {rel_task}"
+            )
+            continue
+        if error == "verify.md missing durable-learning decision evidence":
+            hints.append(
+                "Durable learning decision (pick one grep-friendly line in verify.md): "
+                "'Durable learning decision: no durable learning' for routine work; "
+                "'Spec update evidence: .trellis/spec/<path>' after /trellis:update-spec; "
+                "'Learning artifact: <path>' when handoff/retrospective already captures the insight. "
+                f"Or run: python ./.trellis/scripts/task.py prepare-archive-evidence {rel_task}"
+            )
+            continue
+        if error == "verify.md missing final integration evidence":
+            hints.append(
+                "Parent tasks need 'Final integration evidence: <child handoffs / task-map>'. "
+                f"Run prepare-archive-evidence {rel_task} to draft a section from task-map.md"
+            )
+            continue
+        if error.startswith("missing gate record:"):
+            _rest = error.split(":", 1)[1].strip()
+            _transition, gate = _rest.split("/", 1)
+            hints.append(
+                f"Record reviewer gate after explicit review (never auto-PASS): "
+                f"python ./.trellis/scripts/task.py record-gate {rel_task} "
+                f"--transition full-task-complete --gate {gate} --result PASS "
+                f"--reviewer <reviewer-id> --evidence verify.md"
+            )
+            continue
+        if error.startswith("gate failed:"):
+            hints.append(
+                "Resolve the FAIL gate (fix, re-review, or user-approved SKIPPED) "
+                "before archive."
+            )
+            continue
+        if error.startswith("stale "):
+            hints.append(
+                "Artifacts changed since the gate was recorded. Re-run review and "
+                "record-gate for full-task-complete, then archive --check again."
+            )
+            continue
+        if "child" in error and "integrated or cancelled" in error:
+            hints.append(
+                "Advance each child in parent task-map to integrated or cancelled "
+                "via integrate-child before parent archive."
+            )
+            continue
+        if error == "handoff.md" or error.startswith("handoff.md"):
+            hints.append(
+                "Integrated children require handoff.md on the child task before archive."
+            )
+            continue
+
+    if not hints and not guard.ok:
+        hints.append(
+            f"Run: python ./.trellis/scripts/task.py prepare-archive-evidence {rel_task} "
+            "then archive --check again."
+        )
+
+    if guard.is_full_task and guard.required_gates:
+        missing_reviewer = any(
+            e.startswith("missing gate record: full-task-complete/")
+            for e in errors
+        )
+        if missing_reviewer and not any("record-gate" in h for h in hints):
+            for gate in guard.required_gates:
+                hints.append(
+                    f"Full Task archive needs record-gate for full-task-complete/{gate} "
+                    "(reviewer action required)."
+                )
+
+    return _dedupe_preserve_order(hints)
+
+
+def _dedupe_preserve_order(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        if item in seen:
+            continue
+        seen.add(item)
+        out.append(item)
+    return out
+
+
+def build_archive_evidence_draft(
+    task_dir: Path,
+    task_data: dict,
+    guard: GateGuardResult | None = None,
+) -> str:
+    """Build markdown sections that satisfy archive evidence regex checks."""
+    if guard is None:
+        guard = validate_archive(task_dir, task_data)
+
+    status = _verify_evidence_status(task_dir, task_data)
+    child_names = task_data.get("children")
+    has_children = isinstance(child_names, list) and bool(child_names)
+    lines = [
+        "",
+        "## Archive evidence (draft)",
+        "",
+        ARCHIVE_EVIDENCE_DRAFT_MARKER,
+        "",
+        "_Auto-drafted by prepare-archive-evidence. Edit placeholders before archive._",
+        "",
+    ]
+
+    if not status["validation"]:
+        lines.extend(
+            [
+                "Validation commands: (fill in commands and outcomes, e.g. pnpm test — pass)",
+                "",
+            ]
+        )
+    if not status["acceptance"]:
+        lines.extend(
+            [
+                "Final acceptance evidence: (describe acceptance criteria met for this task)",
+                "",
+            ]
+        )
+    if not status["durable_learning"]:
+        lines.extend(_learning_decision_draft_lines(task_dir, task_data))
+    if has_children and not status["integration"]:
+        summary = _integration_draft_summary(task_dir, child_names)
+        lines.extend(
+            [
+                f"Final integration evidence: {summary}",
+                "",
+            ]
+        )
+
+    if guard.is_full_task and guard.required_gates:
+        rel_task = f".trellis/tasks/{task_dir.name}"
+        lines.extend(
+            [
+                "## Completion gate preparation (not recorded)",
+                "",
+                "Reviewer gates are **not** recorded by this helper. After review, run:",
+                "",
+            ]
+        )
+        for gate in guard.required_gates:
+            lines.append(
+                f"- `python ./.trellis/scripts/task.py record-gate {rel_task} "
+                f"--transition full-task-complete --gate {gate} --result PASS "
+                f"--reviewer <reviewer-id> --evidence verify.md`"
+            )
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _integration_draft_summary(task_dir: Path, child_names: list) -> str:
+    """Summarize child integration states for a parent integration evidence line."""
+    names = [n for n in child_names if isinstance(n, str)]
+    if not names:
+        return "parent children integrated per task-map.md"
+
+    data, _body = load_task_map(task_dir)
+    states: list[str] = []
+    if isinstance(data, dict):
+        children = data.get("children")
+        if isinstance(children, list):
+            by_id = {
+                entry.get("id"): entry.get("state")
+                for entry in children
+                if isinstance(entry, dict) and entry.get("id")
+            }
+            for name in names:
+                state = by_id.get(name, "unknown")
+                states.append(f"{name}={state}")
+
+    if states:
+        return "children " + ", ".join(states) + " per task-map.md"
+    return "all structural children terminal in task-map.md before parent archive"
+
+
+def prepare_archive_evidence(
+    task_dir: Path,
+    task_data: dict | None,
+    *,
+    dry_run: bool = False,
+) -> tuple[bool, list[str]]:
+    """
+    Append missing archive evidence sections to verify.md without rewriting user text.
+
+    Returns (changed, messages).
+    """
+    messages: list[str] = []
+    if task_data is None:
+        return False, ["task.json missing or invalid"]
+
+    verify_path = task_dir / "verify.md"
+    guard = validate_archive(task_dir, task_data)
+
+    if verify_path.is_file():
+        try:
+            existing = verify_path.read_text(encoding="utf-8")
+        except OSError:
+            return False, ["verify.md could not be read"]
+        if ARCHIVE_EVIDENCE_DRAFT_MARKER in existing:
+            messages.append(
+                "verify.md already contains an archive evidence draft block; "
+                "edit it in place instead of re-running prepare."
+            )
+            still_missing = _verify_evidence_errors(task_dir, task_data)
+            if not still_missing:
+                return False, messages
+            messages.append(
+                "Some evidence is still missing after the draft block; "
+                "fill placeholders or add lines outside the draft section."
+            )
+            return False, messages
+        content = existing
+    else:
+        content = "# Verification Evidence\n"
+
+    draft = build_archive_evidence_draft(task_dir, task_data, guard)
+    status = _verify_evidence_status(task_dir, task_data)
+    child_names = task_data.get("children")
+    has_children = isinstance(child_names, list) and bool(child_names)
+    needs_draft = (
+        not status["validation"]
+        or not status["acceptance"]
+        or not status["durable_learning"]
+        or (has_children and not status["integration"])
+        or (guard.is_full_task and guard.required_gates)
+    )
+    if not needs_draft:
+        messages.append("No missing archive evidence sections to draft.")
+        return False, messages
+
+    new_content = content.rstrip() + "\n" + draft
+    if dry_run:
+        messages.append("Dry run: would append archive evidence draft to verify.md")
+        return True, messages
+
+    try:
+        verify_path.write_text(new_content, encoding="utf-8")
+    except OSError as exc:
+        return False, [f"failed to write verify.md: {exc}"]
+
+    messages.append("Appended archive evidence draft to verify.md")
+    remaining = _verify_evidence_errors(task_dir, task_data)
+    gate_errors = [
+        e
+        for e in validate_archive(task_dir, task_data).errors
+        if e.startswith("missing gate record:")
+        or e.startswith("gate failed:")
+        or e.startswith("stale ")
+    ]
+    if remaining:
+        messages.append(
+            "Still missing after draft (edit placeholders): " + "; ".join(remaining)
+        )
+    if gate_errors:
+        messages.append(
+            "Completion gates still require explicit record-gate: "
+            + "; ".join(gate_errors)
+        )
+    return True, messages
+
+
+def validate_reviewer_gate_input(
+    transition: str,
+    gate: str,
+    result: str,
+    reviewer: str,
+    evidence: str,
+    issue_fingerprint: str | None = None,
+    issue_summary: str | None = None,
+    root_cause: str | None = None,
+    skip_approved_by: str | None = None,
+    skip_reason: str | None = None,
+) -> list[str]:
+    """Validate CLI inputs for record-gate."""
+    errors: list[str] = []
+
+    if transition not in KNOWN_TRANSITIONS:
+        errors.append(f"unknown transition: {transition}")
+    if gate == BASELINE_GATE:
+        errors.append("baseline-check is CLI-owned and cannot be recorded manually")
+    elif gate not in REVIEW_GATES:
+        errors.append(f"unknown gate: {gate}")
+    if result not in RESULTS:
+        errors.append(f"invalid result: {result}")
+    if not _is_short_token(reviewer) or not REVIEWER_RE.match(reviewer):
+        errors.append("reviewer must be a short identifier")
+    if not _is_short_text(evidence):
+        errors.append("evidence must be a short reference, not a review body")
+
+    if result == "PASS":
+        if issue_fingerprint:
+            errors.append("--issue-fingerprint is only valid for FAIL")
+        if root_cause:
+            errors.append("--root-cause is only valid for FAIL")
+        if skip_approved_by or skip_reason:
+            errors.append("skip metadata is only valid for SKIPPED")
+    elif result == "FAIL":
+        if not _is_short_token(issue_fingerprint):
+            errors.append("FAIL requires --issue-fingerprint")
+        if root_cause not in FAIL_ROOT_CAUSES:
+            errors.append(
+                "FAIL requires --root-cause implementation-defect|contract-changing-defect|validation-environment-blocker"
+            )
+        if issue_summary and not _is_short_text(issue_summary, MAX_REASON):
+            errors.append("--issue-summary must be short and single-line")
+        if skip_approved_by or skip_reason:
+            errors.append("skip metadata is only valid for SKIPPED")
+    elif result == "SKIPPED":
+        if issue_fingerprint or issue_summary or root_cause:
+            errors.append("issue metadata is only valid for FAIL")
+        if skip_approved_by != "user":
+            errors.append("SKIPPED requires --skip-approved-by user")
+        if not _is_short_text(skip_reason, MAX_REASON):
+            errors.append("SKIPPED requires --skip-reason")
+
+    return errors
+
+
+def _route_for_fail_root_cause(root_cause: str | None) -> str | None:
+    if root_cause is None:
+        return None
+    return FAIL_ROOT_CAUSES.get(root_cause)
+
+
+def _validate_quality_gates(
+    gates: dict,
+    verification_profile: str | None,
+) -> list[str]:
+    errors: list[str] = []
+    mode = gates.get("mode")
+    if mode not in ALLOWED_GATE_MODES:
+        errors.append("quality_gates.mode must be profile or explicit")
+
+    profile = gates.get("profile")
+    if profile and profile not in ALLOWED_VERIFICATION_PROFILES:
+        errors.append(f"invalid quality_gates.profile: {profile}")
+
+    enabled = gates.get("enabled", [])
+    disabled = gates.get("disabled", [])
+    if enabled is None:
+        enabled = []
+    if disabled is None:
+        disabled = []
+
+    if mode == "explicit":
+        if not isinstance(enabled, list):
+            errors.append("quality_gates.enabled must be a list in explicit mode")
+        if not isinstance(disabled, list):
+            errors.append("quality_gates.disabled must be a list in explicit mode")
+
+    all_configured = []
+    if isinstance(enabled, list):
+        all_configured.extend(enabled)
+    if isinstance(disabled, list):
+        all_configured.extend(disabled)
+
+    for gate in all_configured:
+        if gate not in KNOWN_GATES:
+            errors.append(f"unknown quality gate: {gate}")
+
+    if BASELINE_GATE in disabled:
+        errors.append("baseline-check cannot be disabled")
+
+    active = set(enabled) if mode == "explicit" else set(
+        PROFILE_DEFAULT_GATES.get(
+            profile or verification_profile or "standard",
+            PROFILE_DEFAULT_GATES["standard"],
+        )
+    )
+    if "architecture-deep-review" in active and "architecture-review" not in active:
+        errors.append("architecture-deep-review requires architecture-review")
+
+    return errors
+
+
+def _parse_inline_list(value: str) -> list[str] | str:
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [
+            item.strip().strip("'\"")
+            for item in inner.split(",")
+            if item.strip()
+        ]
+    return value
+
+
+def _hash_payload(payload: dict) -> str:
+    body = json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def _stable_task_data(task_data: dict) -> dict:
+    stable: dict = {}
+    for key in STABLE_TASK_KEYS:
+        if key in task_data:
+            stable[key] = task_data.get(key)
+    return stable
+
+
+def _parent_contract_metadata(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+) -> dict | None:
+    if transition == "child-review":
+        parent_name = task_data.get("parent")
+        if not isinstance(parent_name, str) or not parent_name:
+            return None
+        parent_dir = task_dir.parent / parent_name
+        data, _ = load_task_map(parent_dir)
+        return _task_map_contract_metadata("child", parent_dir, data)
+
+    if transition.startswith("parent-"):
+        data, _ = load_task_map(task_dir)
+        return _task_map_contract_metadata("parent", task_dir, data)
+
+    return None
+
+
+def _task_map_contract_metadata(
+    role: str,
+    parent_dir: Path,
+    task_map_data: dict | None,
+) -> dict:
+    return {
+        "role": role,
+        "parent": parent_dir.name,
+        "task_map_found": task_map_data is not None,
+        "contract_epoch": (
+            task_map_data.get("contract_epoch")
+            if isinstance(task_map_data, dict)
+            else None
+        ),
+    }
+
+
+def _reviewed_change_set_metadata(
+    task_dir: Path,
+    transition: str,
+) -> dict | None:
+    evidence_files = _change_set_evidence_files_for(transition)
+    if not evidence_files:
+        return None
+
+    files = []
+    for name in evidence_files:
+        path = task_dir / name
+        try:
+            content = path.read_text(encoding="utf-8") if path.is_file() else ""
+        except OSError:
+            content = ""
+        files.append(
+            {
+                "path": name,
+                "present": path.is_file(),
+                "entries": _extract_reviewed_change_set_entries(content),
+            }
+        )
+    return {"files": files}
+
+
+def _change_set_evidence_files_for(transition: str) -> list[str]:
+    if transition == "full-task-complete":
+        return ["verify.md"]
+    if transition == "child-review":
+        return ["verify.md", "handoff.md"]
+    if transition.startswith("parent-"):
+        return ["task-map.md", "verify.md"]
+    return []
+
+
+def _extract_reviewed_change_set_entries(content: str) -> list[str]:
+    return [
+        match.group(1).strip()
+        for match in REVIEWED_CHANGE_SET_RE.finditer(content)
+    ]
+
+
+def _only_missing_gate_record(errors: list[str]) -> bool:
+    return bool(errors) and all(
+        error.startswith("missing gate record:") for error in errors
+    )
+
+
+def make_planning_review_gate_record(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+    gate: str,
+    contract: dict,
+    contract_fingerprint: str,
+    artifact_fingerprint: str,
+) -> dict:
+    """Build a CLI-owned PASS record when planning artifacts satisfy the gate."""
+    _ = task_dir, task_data, contract
+    evidence_by_gate = {
+        "requirements-review": "prd.md",
+        "architecture-review": "design.md+implement.md",
+    }
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "transition": transition,
+        "gate": gate,
+        "result": "PASS",
+        "reviewer": AUTO_PLANNING_REVIEWER,
+        "evidence": evidence_by_gate.get(gate, "planning-artifacts"),
+        "checked_at": utc_now(),
+        "contract_fingerprint": contract_fingerprint,
+        "artifact_fingerprint": artifact_fingerprint,
+        "issue_fingerprint": None,
+        "root_cause": None,
+        "route": None,
+        "consecutive_failures": 0,
+        "required_user_choice": None,
+        "approved_skip": None,
+        "auto_recorded": True,
+        "auto_record_reason": "planning-artifacts",
+    }
+
+
+def _start_execution_planning_gate_readiness_errors(
+    task_dir: Path,
+    gate: str,
+    *,
+    full_task: bool,
+    contract: dict,
+) -> list[str]:
+    if gate == "requirements-review":
+        return _prd_requirements_review_errors(task_dir)
+    if gate == "architecture-review":
+        errors = _required_file_errors(task_dir, ["design.md", "implement.md"])
+        if not full_task:
+            errors.append(
+                "architecture-review requires design.md and implement.md (Full Task)"
+            )
+        errors.extend(validate_strategy_contract(contract))
+        return errors
+    return [f"planning gate readiness check unsupported: {gate}"]
+
+
+def _prd_requirements_review_errors(task_dir: Path) -> list[str]:
+    path = task_dir / "prd.md"
+    if not path.is_file():
+        return ["prd.md missing for requirements-review"]
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return ["prd.md could not be read for requirements-review"]
+    if not content.strip():
+        return ["prd.md is empty (requirements-review)"]
+    if not PRD_ACCEPTANCE_CRITERIA_HEADING_RE.search(content):
+        return [
+            "prd.md missing Acceptance Criteria heading (complete PRD Grill before start-execution)"
+        ]
+    criteria: list[str] = []
+    for match in PRD_ACCEPTANCE_ITEM_RE.finditer(content):
+        text = match.group(1).strip()
+        if text and not PRD_PLACEHOLDER_RE.match(text):
+            criteria.append(text)
+    if not criteria:
+        return [
+            "prd.md needs at least one non-placeholder Acceptance Criteria item (replace TBD checkboxes)"
+        ]
+    return []
+
+
+def start_execution_repair_hints(
+    errors: list[str],
+    task_dir: Path,
+) -> list[str]:
+    """Map start-execution validation errors to actionable planning hints."""
+    hints: list[str] = []
+    rel_task = f".trellis/tasks/{task_dir.name}"
+    for error in errors:
+        if error.startswith("missing gate record:"):
+            _rest = error.split(":", 1)[1].strip()
+            _transition, gate = _rest.split("/", 1)
+            if gate in START_EXECUTION_AUTO_GATES:
+                hints.append(
+                    "Complete planning artifacts so Trellis can auto-record this gate on "
+                    f"`start-execution --approved` (requirements: prd.md Acceptance Criteria; "
+                    "architecture: design.md + valid implement.md contract)."
+                )
+            else:
+                hints.append(
+                    f"python ./.trellis/scripts/task.py record-gate {rel_task} "
+                    f"--transition start-execution --gate {gate} --result PASS "
+                    f"--reviewer <reviewer-id> --evidence verify.md"
+                )
+            continue
+        if "Acceptance Criteria" in error or "TBD" in error:
+            hints.append(
+                "Finish PRD Grill in trellis-brainstorm: fill Goal, Acceptance Criteria "
+                "(non-TBD checkboxes), then re-run start-execution --check."
+            )
+            continue
+        if "Development Strategy Contract" in error or error.startswith("invalid "):
+            hints.append(
+                "Fix the Development Strategy Contract block in implement.md "
+                "(execution_mode, isolation, verification_profile, quality_gates)."
+            )
+            continue
+        if error == "design.md and implement.md must be present together for Full Tasks":
+            hints.append(
+                "Add both design.md and implement.md for Full Tasks, or stay PRD-only for Lite."
+            )
+    return _dedupe_preserve_order(hints)
+
+
+def _artifact_files_for(transition: str, gate: str) -> list[str]:
+    if transition == "start-execution":
+        return ["prd.md", "design.md", "implement.md"]
+    if transition == "full-task-complete":
+        return ["prd.md", "design.md", "implement.md", "verify.md"]
+    if transition == "child-review":
+        return ["prd.md", "design.md", "implement.md", "verify.md", "handoff.md"]
+    if transition in ("parent-accepted", "parent-integrated"):
+        return ["task-map.md", "verify.md"]
+    _ = gate
+    return ["prd.md", "verify.md"]
+
+
+def _read_artifact_files(task_dir: Path, names: list[str]) -> list[dict]:
+    files = []
+    for name in names:
+        path = task_dir / name
+        try:
+            content = path.read_text(encoding="utf-8") if path.is_file() else None
+        except OSError:
+            content = None
+        files.append({"path": name, "content": content})
+    return files
+
+
+def _required_file_errors(task_dir: Path, names: list[str]) -> list[str]:
+    errors = []
+    for name in names:
+        path = task_dir / name
+        if not path.is_file():
+            errors.append(name)
+            continue
+        try:
+            if not path.read_text(encoding="utf-8").strip():
+                errors.append(f"{name} is empty")
+        except OSError:
+            errors.append(f"{name} could not be read")
+    return errors
+
+
+def _get_gate_record(task_data: dict, transition: str, gate: str) -> dict | None:
+    qgr = task_data.get("quality_gate_results")
+    if not isinstance(qgr, dict):
+        return None
+    transitions = qgr.get("transitions")
+    if not isinstance(transitions, dict):
+        return None
+    transition_records = transitions.get(transition)
+    if not isinstance(transition_records, dict):
+        return None
+    record = transition_records.get(gate)
+    return record if isinstance(record, dict) else None
+
+
+def _validate_gate_record_for_transition(
+    task_data: dict,
+    transition: str,
+    gate: str,
+    contract_fingerprint: str,
+    artifact_fingerprint: str,
+) -> list[str]:
+    errors: list[str] = []
+    record = _get_gate_record(task_data, transition, gate)
+    if record is None:
+        errors.append(f"missing gate record: {transition}/{gate}")
+        return errors
+
+    result = record.get("result")
+    if result == "FAIL":
+        errors.append(f"gate failed: {transition}/{gate}")
+        return errors
+    if result not in ("PASS", "SKIPPED"):
+        errors.append(f"gate record has invalid result: {transition}/{gate}")
+        return errors
+    if record.get("contract_fingerprint") != contract_fingerprint:
+        errors.append(f"stale contract fingerprint: {transition}/{gate}")
+    if record.get("artifact_fingerprint") != artifact_fingerprint:
+        errors.append(f"stale artifact fingerprint: {transition}/{gate}")
+    if result == "SKIPPED":
+        approved_skip = record.get("approved_skip")
+        if not isinstance(approved_skip, dict):
+            errors.append(f"SKIPPED gate lacks approval metadata: {transition}/{gate}")
+        elif approved_skip.get("approved_by") != "user" or not approved_skip.get("reason"):
+            errors.append(f"invalid SKIPPED approval metadata: {transition}/{gate}")
+    return errors
+
+
+def _next_consecutive_failures(
+    previous: dict | None,
+    issue_fingerprint: str | None,
+) -> int:
+    if not previous or previous.get("result") != "FAIL":
+        return 1
+    if previous.get("issue_fingerprint") != issue_fingerprint:
+        return 1
+    previous_count = previous.get("consecutive_failures")
+    return int(previous_count) + 1 if isinstance(previous_count, int) else 2
+
+
+def _is_short_token(value: str | None, max_len: int = MAX_SHORT_FIELD) -> bool:
+    if not value or not isinstance(value, str):
+        return False
+    if len(value) > max_len:
+        return False
+    if any(ch.isspace() for ch in value):
+        return False
+    return True
+
+
+def _is_short_text(value: str | None, max_len: int = MAX_SHORT_FIELD) -> bool:
+    if not value or not isinstance(value, str):
+        return False
+    if len(value) > max_len:
+        return False
+    if "\n" in value or "\r" in value:
+        return False
+    return True