@blxzer/pactile 0.5.0

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

@@ -0,0 +1,2478 @@
+#!/usr/bin/env python
+"""
+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_dependencies import (
+    describe_dependencies,
+    read_depends_mode,
+    scope_children_for_task,
+)
+from .task_map import (
+    get_child_state,
+    load_task_map,
+    validate_child_archive_state,
+    validate_parent_children_complete,
+)
+from .full_quality import full_quality_archive_errors, rigor_from_required_controls
+
+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[^\r\n]*)$"
+)
+ACCEPTANCE_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:final\s+|user\s+)?acceptance"
+    r"(?:\s+evidence)?\s*:\s*(\S[^\r\n]*)$"
+)
+ACCEPTED_BY_USER_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?accepted\s+by\s+user\s*:\s*(\S[^\r\n]*)$"
+)
+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(?:\s+decision)?|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[^\r\n]*)$"
+)
+INTEGRATION_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:final\s+)?integration"
+    r"(?:\s+evidence)?\s*:\s*(\S[^\r\n]*)$"
+)
+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]*)$"
+)
+CHECK_EVIDENCE_RE = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:check\s+evidence|pactile-check(?:\s+evidence)?)"
+    r"\s*:\s*(\S[^\r\n]*)$"
+)
+PLACEHOLDER_VALUES_RE = re.compile(
+    r"(?i)^(TBD|TODO|待定|待补充|N/?A|NA|NONE|-|\.\.\.)$"
+)
+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 = "pactile-cli"
+START_EXECUTION_AUTO_GATES = frozenset({"requirements-review", "architecture-review"})
+
+PROFILE_BASELINE_EIGHT = (
+    "intake-basic",
+    "define-basic",
+    "approval-personal",
+    "execute-agent",
+    "verify-basic",
+    "close-basic",
+    "context-progressive",
+    "observability-local",
+)
+REQUIRED_LIFECYCLE_SLOTS = (
+    "define-basic",
+    "approval-personal",
+    "execute-agent",
+    "verify-basic",
+    "close-basic",
+)
+
+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",
+    "depends_on",
+)
+
+
+@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
+    closeout_profile: str = "lite"
+    auto_gate_records: dict[str, dict] = field(default_factory=dict)
+    deps_blocking_summary: list[str] = field(default_factory=list)
+
+
+def utc_now() -> str:
+    """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 wave_c_stop_read_confirmed(start: Path | None = None) -> bool:
+    """Return True after ``pactile update`` wrote the Wave C confirm flag.
+
+    Unconfirmed projects keep leftover dual-read. Missing ``.pactile`` is
+    unconfirmed (unit fixtures without a repo root stay dual-read).
+    """
+    from .paths import DIR_WORKFLOW, get_repo_root
+
+    root = get_repo_root(start)
+    path = root / DIR_WORKFLOW / ".p36-wave-c.json"
+    if not path.is_file():
+        return False
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return isinstance(parsed, dict) and parsed.get("confirmed") is True
+
+
+def task_closeout_profile(task_dir: Path, task_data: dict | None = None) -> str:
+    """Return lite, full, or parent closeout profile.
+
+    New Tasks use persisted ``required_controls`` / Topology only. Missing
+    contract is explicit Lite. File existence and ``children[]`` are not
+    used to infer Rigor or Parent. Leftover kind/mode/classification are
+    dual-read only until Wave C is confirmed.
+    """
+    data = task_data or {}
+    topology = data.get("topology") if isinstance(data.get("topology"), dict) else {}
+    if topology.get("kind") == "parent-child":
+        return "parent"
+
+    persisted = rigor_from_required_controls(data)
+    if persisted in ("lite", "full"):
+        return persisted
+
+    if wave_c_stop_read_confirmed(task_dir):
+        return "lite"
+
+    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 "parent" in normalized:
+            return "parent"
+        if "full" in normalized:
+            return "full"
+        if "lite" in normalized:
+            return "lite"
+
+    return "lite"
+
+
+def is_full_task(task_dir: Path, task_data: dict | None = None) -> bool:
+    """Return True when a task should satisfy Full Task gates."""
+    return task_closeout_profile(task_dir, task_data) == "full"
+
+
+def resolve_strategy_contract_for_gates(
+    task_dir: Path,
+    task_data: dict | None,
+) -> tuple[dict, list[str]]:
+    """Return the Development Strategy Contract used for gate fingerprints."""
+    if task_data is None:
+        return {}, []
+    profile = task_closeout_profile(task_dir, task_data)
+    if profile == "full":
+        return read_strategy_contract(task_dir)
+    if profile == "parent" and (task_dir / "implement.md").is_file():
+        return read_strategy_contract(task_dir)
+    return {}, []
+
+
+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": "pactile-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.
+
+    This mutates memory only. Stage 2 persists `quality_gate_results` as a
+    Kernel Command projection (same command as `record-gate` / start / archive).
+    Do not treat this helper as an independent `task.json` writer.
+    """
+    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
+
+
+KERNEL_PROJECTION_EXTRA_KEYS = (
+    "quality_gate_results",
+    "execution_approval",
+    "required_controls",
+    "ac_evidence_ledger",
+    "independent_check",
+    "notes_projection",
+    "topology",
+    "dependency_graph",
+    "ondemand_modules",
+    "baseline_modules",
+    "depends_on",
+    "dependency_satisfied",
+    "decompose_proposal",
+    "profile_health",
+    "event_bridge",
+    "middleware_providers",
+    "capability_router",
+    "required_capabilities",
+)
+
+
+def collect_kernel_projection_extras(task_data: dict) -> dict:
+    """Non-canonical task.json fields owned by the same Kernel Command."""
+    extras: dict = {}
+    for key in KERNEL_PROJECTION_EXTRA_KEYS:
+        if key in task_data:
+            extras[key] = task_data[key]
+    return extras
+
+
+NOTES_PROJECTION_SCHEMA_VERSION = 1
+NOTES_PROJECTION_MAX_TOKEN_BUDGET = 150
+NOTES_PROJECTION_SOURCE_LEDGER = "ac_evidence_ledger"
+NOTES_PROJECTION_SOURCE_INDEPENDENT_CHECK = "independent_check"
+NOTES_PROJECTION_SOURCE_VERIFY = "verify.md"
+# Same high|medium|low labels as retrieval_evidence.TRUST_SCORE. Provenance
+# floor only — never a claim that the point text is factually correct.
+NOTES_PROJECTION_CONFIDENCE_HIGH = "high"
+NOTES_PROJECTION_CONFIDENCE_MEDIUM = "medium"
+NOTES_PROJECTION_CONFIDENCE_LOW = "low"
+
+
+def _ledger_evidence_points(task_data: dict) -> list[str]:
+    """Best-effort key points from ``ac_evidence_ledger.items[].evidence_ref``."""
+    ledger = task_data.get("ac_evidence_ledger")
+    if not isinstance(ledger, dict):
+        return []
+    items = ledger.get("items")
+    if not isinstance(items, list):
+        return []
+    points: list[str] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        evidence = item.get("evidence_ref")
+        if isinstance(evidence, str) and evidence.strip():
+            points.append(evidence.strip())
+    return points
+
+
+def _independent_check_note(task_data: dict) -> str:
+    check = task_data.get("independent_check")
+    if not isinstance(check, dict):
+        return ""
+    result = check.get("result")
+    mode = check.get("mode")
+    evidence = check.get("evidence")
+    parts = []
+    if isinstance(result, str) and result.strip():
+        parts.append(f"independent check {result}")
+    if isinstance(mode, str) and mode.strip():
+        parts.append(f"mode={mode}")
+    if isinstance(evidence, str) and evidence.strip():
+        parts.append(evidence.strip())
+    return "; ".join(parts)
+
+
+def _verify_md_note(task_dir: Path) -> str:
+    """Extract archive-evidence lines from verify.md for the notes summary."""
+    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 ""
+    sections: list[str] = []
+    for pattern in (VALIDATION_EVIDENCE_RE, ACCEPTANCE_EVIDENCE_RE):
+        for match in pattern.finditer(content):
+            if match.lastindex and match.lastindex >= 1:
+                value = match.group(1).strip()
+                if _is_substantive_evidence(value):
+                    sections.append(value)
+                    break
+    for match in DURABLE_LEARNING_EVIDENCE_RE.finditer(content):
+        if match.lastindex and match.lastindex >= 1:
+            value = match.group(1).strip()
+            if _is_substantive_evidence(value) and not NO_DURABLE_LEARNING_RE.search(value):
+                sections.append(value)
+                break
+    return "; ".join(sections)
+
+
+def _independent_check_passed(task_data: dict) -> bool:
+    check = task_data.get("independent_check")
+    if not isinstance(check, dict):
+        return False
+    result = check.get("result")
+    return isinstance(result, str) and result.strip().upper() == "PASS"
+
+
+def _has_user_approval_signal(task_data: dict) -> bool:
+    """True when start-execution approval or a user-approved gate skip is present.
+
+    Presence only; does not judge whether the approval is still fresh.
+    """
+    approval = task_data.get("execution_approval")
+    if isinstance(approval, dict) and approval:
+        return True
+    qgr = task_data.get("quality_gate_results")
+    if not isinstance(qgr, dict):
+        return False
+    transitions = qgr.get("transitions")
+    if not isinstance(transitions, dict):
+        return False
+    for transition_records in transitions.values():
+        if not isinstance(transition_records, dict):
+            continue
+        for record in transition_records.values():
+            if not isinstance(record, dict):
+                continue
+            if record.get("approved_by") == "user":
+                return True
+            approved_skip = record.get("approved_skip")
+            if isinstance(approved_skip, dict) and approved_skip.get("approved_by") == "user":
+                return True
+    return False
+
+
+def _notes_point_confidence(
+    source: str,
+    *,
+    independent_check_pass: bool,
+    has_user_approval: bool,
+) -> str:
+    """Provenance floor for one notes point. Missing signals stay ``low``.
+
+    Independent check PASS raises that note (and, with user approval, other
+    notes) to ``high``. A non-empty ledger ``evidence_ref`` floors at
+    ``medium`` and is not auto-raised to ``high`` without the PASS+approval
+    pair. User approval alone floors at ``medium``. Never fails the caller.
+    """
+    if source == NOTES_PROJECTION_SOURCE_INDEPENDENT_CHECK and independent_check_pass:
+        return NOTES_PROJECTION_CONFIDENCE_HIGH
+    if has_user_approval and independent_check_pass:
+        return NOTES_PROJECTION_CONFIDENCE_HIGH
+    if source == NOTES_PROJECTION_SOURCE_LEDGER:
+        return NOTES_PROJECTION_CONFIDENCE_MEDIUM
+    if has_user_approval:
+        return NOTES_PROJECTION_CONFIDENCE_MEDIUM
+    return NOTES_PROJECTION_CONFIDENCE_LOW
+
+
+def _notes_projection_point(
+    text: str,
+    source: str,
+    *,
+    independent_check_pass: bool,
+    has_user_approval: bool,
+) -> dict:
+    return {
+        "text": text,
+        "source": source,
+        "confidence": _notes_point_confidence(
+            source,
+            independent_check_pass=independent_check_pass,
+            has_user_approval=has_user_approval,
+        ),
+    }
+
+
+def _collect_notes_projection_points(task_dir: Path, task_data: dict) -> list[dict]:
+    independent_check_pass = _independent_check_passed(task_data)
+    has_user_approval = _has_user_approval_signal(task_data)
+    points: list[dict] = []
+    for text in _ledger_evidence_points(task_data):
+        points.append(
+            _notes_projection_point(
+                text,
+                NOTES_PROJECTION_SOURCE_LEDGER,
+                independent_check_pass=independent_check_pass,
+                has_user_approval=has_user_approval,
+            )
+        )
+    independent_note = _independent_check_note(task_data)
+    if independent_note:
+        points.append(
+            _notes_projection_point(
+                independent_note,
+                NOTES_PROJECTION_SOURCE_INDEPENDENT_CHECK,
+                independent_check_pass=independent_check_pass,
+                has_user_approval=has_user_approval,
+            )
+        )
+    verify_note = _verify_md_note(task_dir)
+    if verify_note:
+        points.append(
+            _notes_projection_point(
+                verify_note,
+                NOTES_PROJECTION_SOURCE_VERIFY,
+                independent_check_pass=independent_check_pass,
+                has_user_approval=has_user_approval,
+            )
+        )
+    return points
+
+
+def build_notes_projection(
+    task_dir: Path,
+    task_data: dict,
+    archived_rel: str = "",
+) -> dict:
+    """Build the ``notes_projection`` slot for kernel.json extras.
+
+    Summarizes re-usable key points from ``ac_evidence_ledger`` /
+    ``independent_check`` / ``verify.md`` (best-effort) and points at the
+    archived task artifacts. Each point carries ``source`` and a provenance
+    ``confidence`` (high|medium|low). Missing key points never blocks:
+    ``points`` is ``[]``, summary is left empty, and pointers still filled.
+    Low confidence never fails archive.
+    """
+    from .session_memory import JOURNAL_SNIPPET_MAX_TOKENS, truncate_to_token_budget
+
+    points = _collect_notes_projection_points(task_dir, task_data)
+
+    summary = truncate_to_token_budget(
+        "; ".join(point["text"] for point in points),
+        max_tokens=JOURNAL_SNIPPET_MAX_TOKENS,
+    )
+
+    pointers: list[str] = []
+    if archived_rel:
+        pointers.append(archived_rel)
+        if (task_dir / "verify.md").is_file():
+            pointers.append(f"{archived_rel}/verify.md")
+    elif task_dir.is_dir():
+        pointers.append(str(task_dir))
+
+    return {
+        "schema_version": NOTES_PROJECTION_SCHEMA_VERSION,
+        "summary": summary,
+        "pointers": pointers,
+        "source": "cmd_archive",
+        "points": points,
+    }
+
+
+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
+
+    if normalized_result in ("PASS", "SKIPPED"):
+        errors.extend(
+            validate_transition_readiness(
+                task_dir,
+                task_data,
+                transition,
+                gate=gate,
+                mode="record",
+            )
+        )
+        if errors:
+            return None, errors, warnings
+
+    contract, contract_errors = resolve_strategy_contract_for_gates(task_dir, task_data)
+    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,
+    *,
+    ignore_deps: bool = False,
+    enforce_deps_block: bool = False,
+) -> GateGuardResult:
+    """Validate start-execution readiness.
+
+    Dependency policy (Plan B, per adjudication 05 §3.1/§3.2):
+    - enforce_deps_block=True is passed ONLY by the mutating `--approved` path.
+      mode=block + unmet deps then fail unless ignore_deps=True.
+    - mode=off silences dependency warnings entirely.
+    - every other path (--check, warn mode) keeps Plan A semantics: deps are
+      warnings that never fail the guard.
+    """
+    errors: list[str] = []
+    if task_data is None:
+        return GateGuardResult(ok=False, errors=["task.json"])
+
+    errors.extend(_required_lifecycle_slot_errors(task_dir, task_data))
+
+    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")
+
+    warnings: list[str] = []
+    deps_blocking_summary: list[str] = []
+    if task_data is not None:
+        scope = scope_children_for_task(task_dir, task_data)
+        report = describe_dependencies(
+            task_dir,
+            task_data,
+            scope_children=scope,
+        )
+        depends_mode = read_depends_mode(task_data)
+        if enforce_deps_block and depends_mode == "block":
+            deps_blocking_summary = report.blocking_errors()
+            if ignore_deps:
+                warnings.extend(report.warnings())
+            else:
+                errors.extend(deps_blocking_summary)
+        elif depends_mode != "off":
+            warnings.extend(report.warnings())
+            if depends_mode == "block" and not enforce_deps_block:
+                warnings.append(
+                    "dependency policy mode=block: --approved would fail unless --ignore-deps"
+                )
+
+    baseline_record = None
+    if not errors:
+        baseline_record = make_baseline_record(
+            task_dir, task_data, "start-execution", contract
+        )
+
+    return GateGuardResult(
+        ok=not errors,
+        errors=errors,
+        warnings=warnings,
+        contract_fingerprint=contract_fingerprint,
+        artifact_fingerprints=artifact_fingerprints,
+        required_gates=required_gates,
+        baseline_record=baseline_record,
+        is_full_task=full_task,
+        auto_gate_records=auto_gate_records,
+        deps_blocking_summary=deps_blocking_summary,
+    )
+
+
+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.
+
+    NOTE (adjudication 05 §3.1 trap): the check path deliberately passes
+    enforce_deps_block=False — even when the task is in mode=block, --check
+    must never fail on dependencies; it only surfaces warnings. Only the
+    mutating --approved path may set enforce_deps_block=True.
+    """
+    return validate_start_execution(
+        task_dir,
+        task_data,
+        approved=True,
+        enforce_deps_block=False,
+    )
+
+
+def validate_transition_readiness(
+    task_dir: Path,
+    task_data: dict | None,
+    transition: str,
+    *,
+    gate: str | None = None,
+    mode: str = "record",
+) -> list[str]:
+    """Validate transition evidence and, in complete mode, required gate records."""
+    if task_data is None:
+        return ["task.json"]
+
+    errors: list[str] = []
+    if transition not in KNOWN_TRANSITIONS:
+        errors.append(f"unknown transition: {transition}")
+        return errors
+
+    profile = task_closeout_profile(task_dir, task_data)
+
+    if mode == "record":
+        if not gate:
+            errors.append("gate is required for record readiness checks")
+            return errors
+        required_signals = _evidence_requirements_for_gate(transition, gate)
+        errors.extend(_evidence_errors_for_signals(task_dir, task_data, required_signals))
+        return errors
+
+    if transition == "child-review":
+        if profile != "full":
+            return errors
+        contract, contract_errors = read_strategy_contract(task_dir)
+        errors.extend(contract_errors)
+        if contract_errors:
+            return errors
+        return errors + _complete_transition_gate_errors(
+            task_dir,
+            task_data,
+            transition,
+            contract,
+            required_gates_for_transition(transition, contract),
+        )
+
+    if transition == "full-task-complete":
+        if profile != "full":
+            return errors
+        contract, contract_errors = read_strategy_contract(task_dir)
+        errors.extend(contract_errors)
+        if contract_errors:
+            return errors
+        return errors + _complete_transition_gate_errors(
+            task_dir,
+            task_data,
+            transition,
+            contract,
+            required_gates_for_transition(transition, contract),
+        )
+
+    if transition == "parent-integrated":
+        if profile != "parent":
+            return errors
+        child_names = task_data.get("children")
+        if isinstance(child_names, list):
+            errors.extend(
+                validate_parent_children_complete(
+                    task_dir,
+                    [name for name in child_names if isinstance(name, str)],
+                )
+            )
+        errors.extend(
+            _evidence_errors_for_signals(task_dir, task_data, ["integration"])
+        )
+        contract, contract_errors = resolve_strategy_contract_for_gates(
+            task_dir,
+            task_data,
+        )
+        errors.extend(contract_errors)
+        if contract_errors:
+            return errors
+        return errors + _complete_transition_gate_errors(
+            task_dir,
+            task_data,
+            transition,
+            contract,
+            required_gates_for_transition(transition, contract),
+        )
+
+    return errors
+
+
+def _complete_transition_gate_errors(
+    task_dir: Path,
+    task_data: dict,
+    transition: str,
+    contract: dict,
+    required_gates: list[str],
+) -> list[str]:
+    errors: list[str] = []
+    contract_fingerprint = compute_contract_fingerprint(task_dir, task_data, contract)
+    for gate_name in required_gates:
+        artifact_fingerprint = compute_artifact_fingerprint(
+            task_dir, task_data, transition, gate_name
+        )
+        errors.extend(
+            _validate_gate_record_for_transition(
+                task_data=task_data,
+                transition=transition,
+                gate=gate_name,
+                contract_fingerprint=contract_fingerprint,
+                artifact_fingerprint=artifact_fingerprint,
+            )
+        )
+        errors.extend(
+            _evidence_errors_for_signals(
+                task_dir,
+                task_data,
+                _evidence_requirements_for_gate(transition, gate_name),
+            )
+        )
+    return errors
+
+
+def _evidence_requirements_for_gate(transition: str, gate: str) -> list[str]:
+    if gate == "code-review" and transition in ("full-task-complete", "child-review"):
+        return ["validation", "check_evidence", "reviewed_change_set"]
+    if gate == "integration-review" and transition == "parent-integrated":
+        return ["integration"]
+    if gate in ("architecture-review", "architecture-deep-review") and transition in (
+        "full-task-complete",
+        "child-review",
+    ):
+        return ["validation", "check_evidence"]
+    return []
+
+
+def _evidence_errors_for_signals(
+    task_dir: Path,
+    task_data: dict,
+    required_signals: list[str],
+) -> list[str]:
+    status = verify_evidence_status(task_dir, task_data)
+    label_map = {
+        "validation": "verify.md missing substantive validation evidence",
+        "check_evidence": "verify.md missing check evidence",
+        "acceptance": "verify.md missing final acceptance evidence",
+        "durable_learning": "verify.md missing durable-learning decision evidence",
+        "integration": "verify.md missing final integration evidence",
+        "reviewed_change_set": (
+            "verify.md or handoff.md missing reviewed change-set evidence"
+        ),
+    }
+    errors: list[str] = []
+    for signal in required_signals:
+        if not status.get(signal):
+            errors.append(label_map.get(signal, f"missing evidence signal: {signal}"))
+    return errors
+
+
+def verify_evidence_status(task_dir: Path, task_data: dict) -> dict[str, bool]:
+    """Return substantive evidence signals from verify.md and handoff.md."""
+    verify_path = task_dir / "verify.md"
+    content = ""
+    if verify_path.is_file():
+        try:
+            content = verify_path.read_text(encoding="utf-8")
+        except OSError:
+            content = ""
+
+    handoff_path = task_dir / "handoff.md"
+    handoff_content = ""
+    if handoff_path.is_file():
+        try:
+            handoff_content = handoff_path.read_text(encoding="utf-8")
+        except OSError:
+            handoff_content = ""
+
+    child_names = task_data.get("children")
+    has_children = isinstance(child_names, list) and bool(child_names)
+    return {
+        "validation": _has_substantive_validation_evidence(content),
+        "check_evidence": _has_substantive_check_evidence(content),
+        "acceptance": _has_substantive_acceptance_evidence(content),
+        "durable_learning": _has_durable_learning_evidence(content),
+        "integration": (
+            _has_substantive_integration_evidence(content) if has_children else True
+        ),
+        "reviewed_change_set": (
+            _has_substantive_reviewed_change_set(content)
+            or _has_substantive_reviewed_change_set(handoff_content)
+        ),
+    }
+
+
+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_lifecycle_slot_errors(task_dir, task_data))
+    errors.extend(_required_file_errors(task_dir, ["verify.md"]))
+    errors.extend(_verify_evidence_errors(task_dir, task_data))
+    errors.extend(full_quality_archive_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)],
+            )
+        )
+
+    profile = task_closeout_profile(task_dir, task_data)
+    contract: dict = {}
+    required_gates: list[str] = []
+    artifact_fingerprints: dict[str, str] = {}
+    baseline_record = None
+
+    if profile == "full":
+        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
+            )
+            errors.extend(
+                validate_transition_readiness(
+                    task_dir,
+                    task_data,
+                    "full-task-complete",
+                    mode="complete",
+                )
+            )
+    elif profile == "parent":
+        contract, contract_errors = resolve_strategy_contract_for_gates(
+            task_dir,
+            task_data,
+        )
+        errors.extend(contract_errors)
+        if not contract_errors:
+            errors.extend(
+                validate_transition_readiness(
+                    task_dir,
+                    task_data,
+                    "parent-integrated",
+                    mode="complete",
+                )
+            )
+        required_gates = required_gates_for_transition("parent-integrated", contract)
+
+    contract_fingerprint = compute_contract_fingerprint(task_dir, task_data, contract)
+
+    if profile == "full" and not errors:
+        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
+            )
+        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=profile == "full",
+        closeout_profile=profile,
+    )
+
+
+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:
+        verify_path.read_text(encoding="utf-8")
+    except OSError:
+        return ["verify.md could not be read for archive evidence"]
+
+    errors: list[str] = []
+    status = verify_evidence_status(task_dir, task_data)
+    if not status["validation"]:
+        errors.append("verify.md missing validation evidence")
+    if not status["acceptance"]:
+        errors.append("verify.md missing final acceptance evidence")
+    # Durable-learning is a learning decision, not task evidence. For Lite
+    # (one-off bugfix etc.) it is not a required slot: skip it so a Lite can
+    # close without forcing an explicit learning disposition (allow N/A).
+    # Full / Parent tasks still require a durable-learning decision.
+    if task_closeout_profile(task_dir, task_data) != "lite" and not status["durable_learning"]:
+        errors.append("verify.md missing durable-learning decision evidence")
+    if not status["integration"]:
+        errors.append("verify.md missing final integration evidence")
+
+    return errors
+
+
+def _is_substantive_evidence(value: str | None) -> bool:
+    if not value or not isinstance(value, str):
+        return False
+    stripped = value.strip()
+    if len(stripped) < 3:
+        return False
+    return not PLACEHOLDER_VALUES_RE.match(stripped)
+
+
+def _has_substantive_line_match(content: str, pattern: re.Pattern[str]) -> bool:
+    if not content:
+        return False
+    for match in pattern.finditer(content):
+        if match.lastindex and match.lastindex >= 1:
+            if _is_substantive_evidence(match.group(1)):
+                return True
+            continue
+        line = match.group(0)
+        if ":" in line:
+            value = line.split(":", 1)[1].strip()
+            if _is_substantive_evidence(value):
+                return True
+    return False
+
+
+def _has_substantive_validation_evidence(content: str) -> bool:
+    return _has_substantive_line_match(content, VALIDATION_EVIDENCE_RE)
+
+
+def _has_substantive_check_evidence(content: str) -> bool:
+    return _has_substantive_line_match(content, CHECK_EVIDENCE_RE)
+
+
+def _has_substantive_acceptance_evidence(content: str) -> bool:
+    return (
+        _has_substantive_line_match(content, ACCEPTANCE_EVIDENCE_RE)
+        or _has_substantive_line_match(content, ACCEPTED_BY_USER_RE)
+    )
+
+
+def _has_substantive_integration_evidence(content: str) -> bool:
+    return _has_substantive_line_match(content, INTEGRATION_EVIDENCE_RE)
+
+
+def _has_substantive_reviewed_change_set(content: str) -> bool:
+    if not content:
+        return False
+    for match in REVIEWED_CHANGE_SET_RE.finditer(content):
+        if _is_substantive_evidence(match.group(1)):
+            return True
+    return False
+
+
+def _has_validation_evidence(content: str) -> bool:
+    return _has_substantive_validation_evidence(content)
+
+
+def _has_final_acceptance_evidence(content: str) -> bool:
+    return _has_substantive_acceptance_evidence(content)
+
+
+def _has_durable_learning_evidence(content: str) -> bool:
+    return bool(
+        NO_DURABLE_LEARNING_RE.search(content)
+        or _has_substantive_line_match(content, DURABLE_LEARNING_EVIDENCE_RE)
+    )
+
+
+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 / ".pactile" / "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".pactile/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".pactile/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".pactile/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".pactile/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: .pactile/spec/<path>` after edits",
+            f"   - Already documented: `Learning artifact: {rel_task}/handoff.md`",
+            "",
+            "2. Use `/pactile:update-spec` or `/pactile: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 `.pactile/spec/<package-or-layer>/index.md` for the right code-spec file."
+        )
+        lines.append("")
+    lines.append(
+        "4. Re-run `python ./.pactile/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 ".pactile/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: .pactile/tasks/{task_dir.name}/handoff.md",
+        "# Spec update needed: (brief reason) — then run /pactile:update-spec and point Spec update evidence at the edited file",
+        "",
+    ]
+
+
+ARCHIVE_EVIDENCE_DRAFT_MARKER = "<!-- pactile: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."""
+    status = verify_evidence_status(task_dir, task_data)
+    return {
+        "validation": status["validation"],
+        "acceptance": status["acceptance"],
+        "durable_learning": status["durable_learning"],
+        "integration": status["integration"],
+    }
+
+
+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".pactile/tasks/{task_ref}"
+
+    for error in errors:
+        if error == "verify.md":
+            hints.append(
+                f"Create verify.md, then run: python ./.pactile/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 ./.pactile/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: .pactile/spec/<path>' after /pactile:update-spec; "
+                "'Learning artifact: <path>' when handoff/retrospective already captures the insight. "
+                f"Or run: python ./.pactile/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)
+            transition = _transition.strip()
+            if transition == "parent-integrated":
+                hints.append(
+                    f"Parent archive needs record-gate for parent-integrated/{gate}: "
+                    f"python ./.pactile/scripts/task.py record-gate {rel_task} "
+                    f"--transition parent-integrated --gate {gate} --result PASS "
+                    f"--reviewer parent --evidence task-map.md"
+                )
+            elif transition == "child-review":
+                hints.append(
+                    f"Full Child acceptance needs record-gate for child-review/{gate}: "
+                    f"python ./.pactile/scripts/task.py record-gate {rel_task} "
+                    f"--transition child-review --gate {gate} --result PASS "
+                    f"--reviewer parent --evidence verify.md"
+                )
+            else:
+                hints.append(
+                    f"Record reviewer gate after explicit review (never auto-PASS): "
+                    f"python ./.pactile/scripts/task.py record-gate {rel_task} "
+                    f"--transition {transition} --gate {gate} --result PASS "
+                    f"--reviewer <reviewer-id> --evidence verify.md"
+                )
+            continue
+        if error == "verify.md missing check evidence":
+            hints.append(
+                "Add a grep-friendly line such as "
+                "'Check evidence: <pactile-check summary or manual review notes>' to verify.md"
+            )
+            continue
+        if error == (
+            "verify.md or handoff.md missing reviewed change-set evidence"
+        ):
+            hints.append(
+                "Add 'Reviewed change-set: <git ref or diff summary>' to verify.md or handoff.md"
+            )
+            continue
+        if error == "verify.md missing substantive validation evidence":
+            hints.append(
+                "Replace placeholder validation lines with substantive command/outcome text in 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 ./.pactile/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".pactile/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 ./.pactile/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".pactile/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 Pactile 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 ./.pactile/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 pactile-brainstorm: fill Goal, Acceptance Criteria "
+                "(non-TBD checkboxes), then re-run start-execution --check."
+            )
+            continue
+        if error.startswith("missing required lifecycle slot:"):
+            hints.append(
+                "Restore the required Baseline slot in baseline_modules.active "
+                "(define-basic, approval-personal, execute-agent, verify-basic, "
+                "close-basic). Missing required slots cannot fake-green."
+            )
+            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 baseline_active_ids(task_dir: Path, task_data: dict | None) -> list[str]:
+    """Installed-and-active Baseline ids. Missing extras default to all eight."""
+    block = None
+    data = task_data if isinstance(task_data, dict) else {}
+    if isinstance(data.get("baseline_modules"), dict):
+        block = data["baseline_modules"]
+    else:
+        kernel_path = task_dir / "kernel.json"
+        kernel: dict = {}
+        if kernel_path.is_file():
+            try:
+                parsed = json.loads(kernel_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                parsed = {}
+            if isinstance(parsed, dict):
+                kernel = parsed
+        projection = (
+            kernel.get("projection") if isinstance(kernel.get("projection"), dict) else {}
+        )
+        extras = projection.get("extras") if isinstance(projection.get("extras"), dict) else {}
+        if isinstance(extras.get("baseline_modules"), dict):
+            block = extras["baseline_modules"]
+    if not isinstance(block, dict) or "active" not in block:
+        return list(PROFILE_BASELINE_EIGHT)
+    raw = block.get("active")
+    if not isinstance(raw, list):
+        return []
+    allowed = set(PROFILE_BASELINE_EIGHT)
+    out: list[str] = []
+    for item in raw:
+        if not isinstance(item, str):
+            continue
+        name = item.strip()
+        if name in allowed and name not in out:
+            out.append(name)
+    return out
+
+
+def _required_lifecycle_slot_errors(task_dir: Path, task_data: dict | None) -> list[str]:
+    active = set(baseline_active_ids(task_dir, task_data))
+    return [
+        f"missing required lifecycle slot: {slot}"
+        for slot in REQUIRED_LIFECYCLE_SLOTS
+        if slot not in active
+    ]
+
+
+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