@pennixrv/trellis 0.7.0-beta.52 → 0.7.0-beta.54

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

@@ -0,0 +1,231 @@
+"""Digest-guarded, reversible migration of legacy task planning metadata."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .io import write_text_atomic
+from .ownership_record import assert_task_mutation_allowed
+from .task_planning import REPLAN_STAGES
+
+
+class MigrationError(ValueError):
+    """A migration manifest, precondition, or receipt is unsafe or stale."""
+
+
+def _digest(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def _read_object(path: Path, label: str) -> tuple[dict[str, Any], bytes]:
+    try:
+        raw = path.read_bytes()
+        data = json.loads(raw)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise MigrationError(f"{label} is unreadable or invalid JSON: {path}") from exc
+    if not isinstance(data, dict):
+        raise MigrationError(f"{label} must contain a JSON object: {path}")
+    return data, raw
+
+
+def _task_path(repo_root: Path, value: Any) -> Path:
+    if not isinstance(value, str) or not value or "\\" in value:
+        raise MigrationError("manifest task path must be a project-relative POSIX path")
+    relative = Path(value)
+    if relative.is_absolute() or relative.parts[:2] != (".trellis", "tasks") or len(relative.parts) != 3:
+        raise MigrationError(f"migration only accepts direct active tasks: {value!r}")
+    tasks_dir = repo_root / ".trellis" / "tasks"
+    if (repo_root / ".trellis").is_symlink() or tasks_dir.is_symlink() or relative.parts[2] in {"", ".", "..", "archive"}:
+        raise MigrationError(f"unsafe task path: {value!r}")
+    target = repo_root / relative
+    if target.is_symlink() or not target.is_dir() or target.resolve().parent != tasks_dir.resolve():
+        raise MigrationError(f"task path is missing, linked, or outside active tasks: {value!r}")
+    return target
+
+
+def _load_manifest(repo_root: Path, manifest_path: Path) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    manifest, raw = _read_object(manifest_path, "migration manifest")
+    if manifest.get("schema_version") != 1 or not isinstance(manifest.get("tasks"), list) or not manifest["tasks"]:
+        raise MigrationError("migration manifest requires schema_version=1 and a non-empty tasks array")
+    rows: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for entry in manifest["tasks"]:
+        if not isinstance(entry, dict):
+            raise MigrationError("each migration task entry must be an object")
+        task_value = entry.get("path")
+        if not isinstance(task_value, str):
+            raise MigrationError("manifest task path must be a string")
+        task_dir = _task_path(repo_root, task_value)
+        if task_value in seen:
+            raise MigrationError(f"duplicate migration task path: {task_value}")
+        seen.add(task_value)
+        digests = entry.get("source_digests")
+        target = entry.get("target")
+        if not isinstance(digests, dict) or "task.json" not in digests or not isinstance(target, dict):
+            raise MigrationError(f"{task_value}: source_digests.task.json and target are required")
+        if any(not isinstance(name, str) or Path(name).name != name or not isinstance(value, str) or len(value) != 64 for name, value in digests.items()):
+            raise MigrationError(f"{task_value}: source digests must map filenames to SHA-256 hex digests")
+        if any(any(c not in "0123456789abcdef" for c in value) for value in digests.values()):
+            raise MigrationError(f"{task_value}: source digests must be lowercase SHA-256 hex")
+        execution = target.get("execution_class")
+        delivery = target.get("delivery_mode")
+        stage = target.get("stage")
+        if "stage" not in target:
+            raise MigrationError(f"{task_value}: target must explicitly set stage to a stage or null")
+        if execution not in ("planned", "direct") or delivery not in ("change_bearing", "analysis_only"):
+            raise MigrationError(f"{task_value}: target requires explicit execution_class and delivery_mode")
+        if stage is not None and (not isinstance(stage, str) or stage not in REPLAN_STAGES):
+            raise MigrationError(f"{task_value}: unsupported target stage: {stage!r}")
+        task_data, task_bytes = _read_object(task_dir / "task.json", f"{task_value}/task.json")
+        if task_data.get("status") == "planning" and stage != "intake":
+            raise MigrationError(f"{task_value}: existing planning task must migrate to intake")
+        if task_data.get("status") == "in_progress" and stage is not None:
+            raise MigrationError(f"{task_value}: migration must not infer a stage for an in_progress task")
+        if task_data.get("status") not in {"planning", "in_progress"}:
+            raise MigrationError(f"{task_value}: only planning or in_progress tasks may migrate")
+        for name, expected in digests.items():
+            path = task_dir / name
+            if path.is_symlink() or not path.is_file():
+                raise MigrationError(f"{task_value}/{name}: source file is missing or linked")
+            if _digest(path.read_bytes()) != expected:
+                raise MigrationError(f"{task_value}/{name}: source digest changed")
+        meta = task_data.get("meta", {})
+        if not isinstance(meta, dict):
+            raise MigrationError(f"{task_value}: task meta must be an object")
+        if "planning" in meta:
+            raise MigrationError(f"{task_value}: planning metadata already exists; refusing to overwrite it")
+        before_meta = {key: meta.get(key) for key in ("execution_class", "delivery_mode", "planning") if key in meta}
+        after_meta = {
+            **meta,
+            "execution_class": execution,
+            "delivery_mode": delivery,
+            "planning": {"revision": 1, **({"stage": stage} if stage else {})},
+        }
+        updated = {**task_data, "meta": after_meta}
+        rows.append({
+            "path": task_value,
+            "task_dir": task_dir,
+            "source_digests": digests,
+            "before_bytes": task_bytes,
+            "before_meta": before_meta,
+            "after_meta": {key: after_meta[key] for key in ("execution_class", "delivery_mode", "planning")},
+            "after_bytes": (json.dumps(updated, indent=2, ensure_ascii=False) + "\n").encode("utf-8"),
+        })
+    return {"manifest_digest": _digest(raw)}, rows
+
+
+def _check_sources(rows: list[dict[str, Any]]) -> None:
+    for row in rows:
+        for name, expected in row["source_digests"].items():
+            path = row["task_dir"] / name
+            if path.is_symlink() or not path.is_file() or _digest(path.read_bytes()) != expected:
+                raise MigrationError(f"{row['path']}/{name}: source digest changed")
+
+
+def _write(path: Path, raw: bytes) -> None:
+    if not write_text_atomic(path, raw.decode("utf-8")):
+        raise MigrationError(f"atomic write failed: {path}")
+
+
+def _receipt_path(repo_root: Path, value: str) -> Path:
+    path = Path(value)
+    if not path.is_absolute():
+        path = repo_root / path
+    trellis_dir = (repo_root / ".trellis").resolve()
+    if path.is_symlink() or not path.parent.exists() or not path.parent.resolve().is_relative_to(trellis_dir):
+        raise MigrationError("receipt path must be a new regular file under .trellis/")
+    if path.exists():
+        raise MigrationError(f"refusing to overwrite migration receipt: {path}")
+    return path
+
+
+def migrate(repo_root: Path, manifest_path: Path, *, apply: bool, receipt_value: str | None = None) -> dict[str, Any]:
+    if manifest_path.is_symlink() or not manifest_path.is_file():
+        raise MigrationError("manifest must be a regular file")
+    manifest, rows = _load_manifest(repo_root, manifest_path)
+    _check_sources(rows)
+    preview = [{"path": row["path"], "before": row["before_meta"], "after": row["after_meta"]} for row in rows]
+    if not apply:
+        return {"mode": "dry_run", "manifest_digest": manifest["manifest_digest"], "tasks": preview}
+    if not receipt_value:
+        raise MigrationError("--apply requires --receipt under .trellis/")
+    receipt_path = _receipt_path(repo_root, receipt_value)
+    receipt = {
+        "schema_version": 1,
+        "manifest_digest": manifest["manifest_digest"],
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "tasks": [],
+    }
+    for row in rows:
+        assert_task_mutation_allowed(repo_root, row["task_dir"])
+    written: list[dict[str, Any]] = []
+    try:
+        # Recheck every source before the first write to avoid partial migration on stale input.
+        _check_sources(rows)
+        for row in rows:
+            target = row["task_dir"] / "task.json"
+            _write(target, row["after_bytes"])
+            entry = {
+                "path": row["path"],
+                "before_task_json": row["before_bytes"].decode("utf-8"),
+                "after_digest": _digest(row["after_bytes"]),
+            }
+            receipt["tasks"].append(entry)
+            written.append(row)
+        receipt_raw = (json.dumps(receipt, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
+        _write(receipt_path, receipt_raw)
+    except Exception:
+        restore_errors: list[str] = []
+        for row in reversed(written):
+            try:
+                _write(row["task_dir"] / "task.json", row["before_bytes"])
+            except Exception as exc:  # report if a disk failure also blocks recovery
+                restore_errors.append(f"{row['path']}: {exc}")
+        if restore_errors:
+            raise MigrationError("migration failed and rollback was incomplete: " + "; ".join(restore_errors))
+        raise
+    return {"mode": "applied", "receipt": receipt_path.relative_to(repo_root).as_posix(), "tasks": preview}
+
+
+def rollback(repo_root: Path, receipt_path: Path) -> dict[str, Any]:
+    trellis_dir = (repo_root / ".trellis").resolve()
+    if (repo_root / ".trellis").is_symlink() or receipt_path.is_symlink() or not receipt_path.is_file() or not receipt_path.resolve().is_relative_to(trellis_dir):
+        raise MigrationError("receipt must be a regular file")
+    receipt, _raw = _read_object(receipt_path, "migration receipt")
+    rows = receipt.get("tasks")
+    if receipt.get("schema_version") != 1 or not isinstance(rows, list) or not rows:
+        raise MigrationError("migration receipt has an unsupported format")
+    prepared: list[tuple[Path, bytes, bytes]] = []
+    seen: set[str] = set()
+    for row in rows:
+        if not isinstance(row, dict) or not isinstance(row.get("path"), str) or row["path"] in seen:
+            raise MigrationError("migration receipt contains an invalid or duplicate task")
+        seen.add(row["path"])
+        task_dir = _task_path(repo_root, row["path"])
+        before = row.get("before_task_json")
+        after_digest = row.get("after_digest")
+        if not isinstance(before, str) or not isinstance(after_digest, str):
+            raise MigrationError(f"{row['path']}: receipt is missing rollback data")
+        current_path = task_dir / "task.json"
+        if current_path.is_symlink():
+            raise MigrationError(f"{row['path']}/task.json: symlinked task.json refused")
+        current = current_path.read_bytes()
+        if _digest(current) != after_digest:
+            raise MigrationError(f"{row['path']}/task.json: changed since migration; refusing rollback")
+        prepared.append((current_path, current, before.encode("utf-8")))
+    for path, _current, _before in prepared:
+        assert_task_mutation_allowed(repo_root, path.parent)
+    restored: list[tuple[Path, bytes]] = []
+    try:
+        for path, current, before in prepared:
+            _write(path, before)
+            restored.append((path, current))
+    except Exception:
+        for path, current in reversed(restored):
+            _write(path, current)
+        raise
+    return {"mode": "rolled_back", "tasks": [row["path"] for row in rows]}

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

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import json
+import re
 from datetime import datetime, timezone
 from hashlib import sha256
 from pathlib import Path
@@ -12,6 +14,23 @@ class PlanningError(ValueError):
     """A planning contract needs correction before a task can start."""
 
 
+STAGES = {
+    "intake",
+    "evidence",
+    "decision_convergence",
+    "solution_formation",
+    "solution_review",
+    "user_review",
+    "plan_closed",
+    "direct_ready",
+}
+REPLAN_STAGES = STAGES - {"plan_closed", "direct_ready"}
+DECISIONS_MARKER = "<!-- trellis-decisions:v1 -->"
+IMPLEMENTATION_PLAN_MARKER = "<!-- trellis-implementation-plan:v1 -->"
+_DECISION_FIELDS = ("id", "status", "question", "evidence", "answer_or_reason", "impact", "reopen_when")
+_STEP_FIELDS = ("id", "target", "depends_on", "action", "deliverables", "verification", "risks", "rollback")
+
+
 def validate_meta_value(key: str, value: str) -> None:
     if key == "planning" or key.startswith("planning."):
         raise PlanningError("meta.planning is reserved; use task.py plan seal/approve")
@@ -44,12 +63,186 @@ def planning_record(data: dict[str, Any]) -> dict[str, Any]:
     revision = record.get("revision", 1)
     if isinstance(revision, bool) or not isinstance(revision, int) or revision < 1:
         raise PlanningError("planning revision must be a positive integer")
-    return {**record, "revision": revision}
+    stage = record.get("stage", "intake" if data.get("status") == "planning" else None)
+    if stage is not None and (not isinstance(stage, str) or stage not in STAGES):
+        raise PlanningError(f"planning stage must be one of: {', '.join(sorted(STAGES))}")
+    return {**record, "revision": revision, **({"stage": stage} if stage else {})}
 
 
-def invalidate_plan(data: dict[str, Any]) -> None:
+def invalidate_plan(data: dict[str, Any], stage: str | None = None) -> None:
     record = planning_record(data)
-    data.setdefault("meta", {})["planning"] = {"revision": record["revision"] + 1}
+    next_record = {"revision": record["revision"] + 1}
+    if stage is not None:
+        if not isinstance(stage, str) or stage not in REPLAN_STAGES:
+            raise PlanningError(f"unknown planning stage: {stage}")
+        next_record["stage"] = stage
+    data.setdefault("meta", {})["planning"] = next_record
+
+
+def _marked_json(task_dir: Path, document: str, marker: str) -> dict[str, Any]:
+    path = task_dir / document
+    if path.is_symlink() or not path.is_file() or path.stat().st_size > 256 * 1024:
+        raise PlanningError(f"{document} must be a bounded regular file")
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError) as exc:
+        raise PlanningError(f"{document} must be valid UTF-8") from exc
+    markers = [index for index, line in enumerate(lines) if line.strip() == marker]
+    if len(markers) != 1:
+        raise PlanningError(f"{document} must contain exactly one {marker} block")
+    start = markers[0] + 1
+    if start >= len(lines) or lines[start].strip() != "```json":
+        raise PlanningError(f"{marker} must be immediately followed by a JSON fence")
+    end = next((index for index in range(start + 1, len(lines)) if lines[index].strip() == "```"), None)
+    if end is None:
+        raise PlanningError(f"{document} has an unterminated {marker} JSON fence")
+    try:
+        value = json.loads("\n".join(lines[start + 1:end]))
+    except json.JSONDecodeError as exc:
+        raise PlanningError(f"{document} {marker} block is invalid JSON: {exc.msg}") from exc
+    if not isinstance(value, dict) or value.get("schema_version") != 1:
+        raise PlanningError(f"{document} {marker} block requires schema_version=1")
+    return value
+
+
+def validate_decisions(task_dir: Path) -> list[dict[str, Any]]:
+    value = _marked_json(task_dir, "prd.md", DECISIONS_MARKER)
+    decisions = value.get("decisions")
+    if not isinstance(decisions, list):
+        raise PlanningError("trellis-decisions:v1 requires a decisions array")
+    ids: set[str] = set()
+    for item in decisions:
+        if not isinstance(item, dict) or any(key not in item for key in _DECISION_FIELDS):
+            raise PlanningError("each decision requires id, status, question, evidence, answer_or_reason, impact, and reopen_when")
+        if any(not isinstance(item[key], str) or not item[key].strip() for key in ("id", "question", "answer_or_reason", "impact", "reopen_when")):
+            raise PlanningError("decision text fields must be non-empty strings")
+        if item["id"] in ids:
+            raise PlanningError(f"duplicate decision id: {item['id']}")
+        ids.add(item["id"])
+        if not isinstance(item["status"], str) or item["status"] not in {"open", "decided", "deferred", "excluded"}:
+            raise PlanningError(f"invalid decision status for {item['id']}")
+        evidence = item["evidence"]
+        if not isinstance(evidence, list) or not evidence or any(not isinstance(entry, str) or not entry.strip() for entry in evidence):
+            raise PlanningError(f"decision evidence must contain non-empty references: {item['id']}")
+    return decisions
+
+
+def validate_implementation_plan(task_dir: Path) -> dict[str, Any]:
+    value = _marked_json(task_dir, "implement.md", IMPLEMENTATION_PLAN_MARKER)
+    steps = value.get("steps")
+    if not isinstance(steps, list) or not steps:
+        raise PlanningError("trellis-implementation-plan:v1 requires a non-empty steps array")
+    seen: set[str] = set()
+    for step in steps:
+        if not isinstance(step, dict) or any(key not in step for key in _STEP_FIELDS):
+            raise PlanningError("each implementation step requires id, target, depends_on, action, deliverables, verification, risks, and rollback")
+        identifier = step["id"]
+        if not isinstance(identifier, str) or not identifier.strip() or identifier in seen:
+            raise PlanningError(f"implementation step id is empty or duplicated: {identifier!r}")
+        target = step["target"]
+        if not isinstance(target, dict) or any(not isinstance(target.get(key), str) or not target[key].strip() for key in ("repository", "branch", "component_or_path")):
+            raise PlanningError(f"implementation step {identifier} requires repository, branch, and component_or_path")
+        for key in ("action", "deliverables", "verification", "risks", "rollback"):
+            if not isinstance(step[key], str) or not step[key].strip():
+                raise PlanningError(f"implementation step {identifier} requires non-empty {key}")
+        dependencies = step["depends_on"]
+        if not isinstance(dependencies, list) or any(not isinstance(dep, str) for dep in dependencies):
+            raise PlanningError(f"implementation step {identifier} depends_on must be an array of earlier step ids")
+        if len(dependencies) != len(set(dependencies)) or any(dep not in seen for dep in dependencies):
+            raise PlanningError(f"implementation step {identifier} has duplicate, unknown, or forward dependencies")
+        seen.add(identifier)
+    stop = value.get("stop_point")
+    if not isinstance(stop, dict) or any(not isinstance(stop.get(key), str) or not stop[key].strip() for key in ("condition", "observable_evidence", "remaining_work")):
+        raise PlanningError("implementation plan requires one stop_point with condition, observable_evidence, and remaining_work")
+    return value
+
+
+def validate_direct_plan(data: dict[str, Any], task_dir: Path) -> None:
+    if not isinstance(data.get("assignee"), str) or not data["assignee"].strip():
+        raise PlanningError("direct task requires one named owner in task.json")
+    prd = task_dir / "prd.md"
+    if prd.is_symlink() or not prd.is_file() or prd.stat().st_size > 256 * 1024:
+        raise PlanningError("direct task requires a bounded regular prd.md")
+    try:
+        content = prd.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise PlanningError("direct task prd.md must be readable UTF-8") from exc
+    headings = list(re.finditer(r"(?m)^#{1,6}\s+(.+?)\s*#*\s*$", content))
+    sections: dict[str, str] = {}
+    for index, heading in enumerate(headings):
+        title = re.sub(r"[\W_]+", "", heading.group(1).casefold())
+        end = headings[index + 1].start() if index + 1 < len(headings) else len(content)
+        sections[title] = content[heading.end():end].strip()
+    required = {
+        "one bounded change": {"scope", "boundedchange", "范围", "变更范围", "本次变更"},
+        "observable verification": {"verification", "验收", "验证", "验证方式"},
+        "rollback method": {"rollback", "rollbackplan", "回退", "回滚", "回退方案", "回滚方案"},
+    }
+    for label, alternatives in required.items():
+        if not any(sections.get(title) for title in alternatives):
+            raise PlanningError(f"direct task must provide a non-empty {label} section in prd.md")
+
+
+def plan_digest(data: dict[str, Any], task_dir: Path) -> str:
+    execution, delivery = classification(data)
+    documents = _plan_documents(task_dir, execution, delivery)
+    payload = {
+        "task_id": data.get("id") or task_dir.name,
+        "task_name": task_dir.name,
+        "execution_class": execution,
+        "delivery_mode": delivery,
+        "documents": {name: (task_dir / name).read_text(encoding="utf-8") for name in documents},
+    }
+    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return "sha256:" + sha256(encoded).hexdigest()
+
+
+def advance_stage(data: dict[str, Any], task_dir: Path, target: str) -> str:
+    if data.get("status") != "planning":
+        raise PlanningError("planning stages can only advance while status=planning")
+    if not isinstance(target, str) or target not in STAGES or target == "plan_closed":
+        raise PlanningError(f"invalid planning stage target: {target}")
+    execution, delivery = classification(data)
+    record = planning_record(data)
+    current = record.get("stage", "intake")
+    allowed = {
+        "intake": {"evidence"},
+        "evidence": {"decision_convergence", "solution_formation", "direct_ready"},
+        "decision_convergence": {"evidence", "solution_formation"},
+        "solution_formation": {"evidence", "decision_convergence", "solution_review"},
+        "solution_review": {"evidence", "decision_convergence", "solution_formation", "user_review"},
+        "user_review": {"evidence", "decision_convergence", "solution_formation"},
+        "plan_closed": set(),
+        "direct_ready": set(),
+    }
+    if current not in allowed or target not in allowed[current]:
+        raise PlanningError(f"invalid planning transition: {current} -> {target}")
+    decisions: list[dict[str, Any]] | None = None
+    if target in {"decision_convergence", "solution_formation", "solution_review", "user_review"} or current == "decision_convergence":
+        decisions = validate_decisions(task_dir)
+    open_decisions = [item["id"] for item in decisions or [] if item["status"] == "open"]
+    if target == "decision_convergence" and (execution != "planned" or delivery != "change_bearing" or not open_decisions):
+        raise PlanningError("decision_convergence requires planned change-bearing work with open decisions")
+    if target == "solution_formation" and (execution != "planned" or delivery != "change_bearing" or open_decisions):
+        raise PlanningError("solution_formation requires planned change-bearing work with no open decisions")
+    if target == "solution_review":
+        validate_implementation_plan(task_dir)
+        if open_decisions:
+            raise PlanningError("open decisions block solution review: " + ", ".join(open_decisions))
+    if target == "user_review":
+        validate_implementation_plan(task_dir)
+        if open_decisions:
+            raise PlanningError("open decisions block user review: " + ", ".join(open_decisions))
+    if target == "direct_ready":
+        if execution != "direct" or delivery != "change_bearing":
+            raise PlanningError("direct_ready requires direct change-bearing classification")
+        validate_direct_plan(data, task_dir)
+    if target in {"evidence", "decision_convergence", "solution_formation"} and current in {"solution_review", "user_review"}:
+        invalidate_plan(data, target)
+    else:
+        record["stage"] = target
+        data.setdefault("meta", {})["planning"] = record
+    return target
 
 
 def _plan_documents(task_dir: Path, execution: str, delivery: str) -> list[str]:
@@ -67,15 +260,24 @@ def _plan_documents(task_dir: Path, execution: str, delivery: str) -> list[str]:
     return names
 
 
-def seal_plan(data: dict[str, Any], task_dir: Path) -> int:
+def seal_plan(data: dict[str, Any], task_dir: Path, expected_digest: str) -> int:
+    record = planning_record(data)
+    if record.get("stage") != "user_review":
+        raise PlanningError("plan seal requires stage=user_review")
     execution, delivery = classification(data)
     documents = _plan_documents(task_dir, execution, delivery)
-    record = planning_record(data)
-    # Resealing an already sealed plan declares a material new version. A replan
-    # already advanced the revision; its first seal keeps that revision.
+    decisions = validate_decisions(task_dir)
+    if any(item["status"] == "open" for item in decisions):
+        raise PlanningError("open decisions prevent plan sealing")
+    validate_implementation_plan(task_dir)
+    actual_digest = plan_digest(data, task_dir)
+    if expected_digest != actual_digest:
+        raise PlanningError("displayed plan digest is stale; review the current complete plan again")
     revision = record["revision"] + (1 if record.get("seal") else 0)
     data.setdefault("meta", {})["planning"] = {
         "revision": revision,
+        "stage": "user_review",
+        "review_digest": actual_digest,
         "seal": {
             "revision": revision,
             "task_id": data.get("id") or task_dir.name,
@@ -84,13 +286,14 @@ def seal_plan(data: dict[str, Any], task_dir: Path) -> int:
             "document_digests": {name: sha256((task_dir / name).read_bytes()).hexdigest() for name in documents},
             "execution_class": execution,
             "delivery_mode": delivery,
+            "plan_digest": actual_digest,
             "sealed_at": datetime.now(timezone.utc).isoformat(),
         },
     }
     return revision
 
 
-def _require_seal(data: dict[str, Any], task_dir: Path) -> dict[str, Any]:
+def _require_seal(data: dict[str, Any], task_dir: Path, required_stage: str = "user_review") -> dict[str, Any]:
     execution, delivery = classification(data)
     record = planning_record(data)
     seal = record.get("seal")
@@ -104,6 +307,13 @@ def _require_seal(data: dict[str, Any], task_dir: Path) -> dict[str, Any]:
         raise PlanningError("sealed plan documents do not match this task")
     if seal.get("document_digests") != {name: sha256((task_dir / name).read_bytes()).hexdigest() for name in seal["documents"]}:
         raise PlanningError("sealed plan content changed or lacks content digests; reseal the material plan")
+    if seal.get("plan_digest") != plan_digest(data, task_dir) or record.get("review_digest") != seal.get("plan_digest"):
+        raise PlanningError("sealed plan digest is stale; review the current complete plan again")
+    if record.get("stage") != required_stage:
+        raise PlanningError(f"plan receipt requires stage={required_stage}")
+    if any(item["status"] == "open" for item in validate_decisions(task_dir)):
+        raise PlanningError("open decisions prevent plan approval")
+    validate_implementation_plan(task_dir)
     return record
 
 
@@ -111,12 +321,13 @@ def approve_plan(data: dict[str, Any], task_dir: Path, revision: int, basis: str
     record = _require_seal(data, task_dir)
     if revision != record["revision"]:
         raise PlanningError(f"approval revision must match current revision {record['revision']}")
-    if not basis.strip() or len(basis) > 1024 or "\x00" in basis:
+    if not isinstance(basis, str) or not basis.strip() or len(basis) > 1024 or "\x00" in basis:
         raise PlanningError("approval basis must be non-empty bounded text without credentials")
     record.update({
         "approved_revision": revision,
         "approval_basis": basis.strip(),
         "approved_at": datetime.now(timezone.utc).isoformat(),
+        "stage": "plan_closed",
     })
     data["meta"]["planning"] = record
 
@@ -132,6 +343,37 @@ def require_start_approval(data: dict[str, Any], task_dir: Path) -> None:
     if delivery == "analysis_only":
         raise PlanningError("analysis_only tasks remain in planning and cannot be started")
     if execution == "planned" and delivery == "change_bearing":
-        record = _require_seal(data, task_dir)
+        record = _require_seal(data, task_dir, "plan_closed")
         if type(record.get("approved_revision")) is not int or record.get("approved_revision") != record["revision"] or not record.get("approval_basis"):
             raise PlanningError("current sealed plan has no matching implementation approval; use task.py plan approve only after the user explicitly approves the displayed plan")
+    elif execution == "direct" and delivery == "change_bearing":
+        if planning_record(data).get("stage") != "direct_ready":
+            raise PlanningError("direct change-bearing tasks require stage=direct_ready before start")
+        validate_direct_plan(data, task_dir)
+
+
+def prepare_archive(data: dict[str, Any], task_dir: Path, reason: str | None) -> None:
+    if data.get("status") != "planning":
+        return
+    if not isinstance(reason, str) or not reason.strip() or len(reason) > 1024:
+        raise PlanningError("archiving a planning task requires --reason with the analysis result or abandonment reason")
+    record = planning_record(data)
+    meta = data.get("meta", {})
+    if not isinstance(meta, dict):
+        raise PlanningError("task meta must be an object")
+    if "execution_class" in meta or "delivery_mode" in meta:
+        _, delivery = classification(data)
+    else:
+        delivery = None
+    if delivery == "analysis_only":
+        if record.get("stage") != "evidence":
+            raise PlanningError("analysis-only archive requires stage=evidence and a completed evidence review")
+        research = task_dir / "research"
+        evidence_files = [path for path in research.glob("*.md") if path.is_file() and not path.is_symlink()] if research.is_dir() and not research.is_symlink() else []
+        if not evidence_files:
+            raise PlanningError("analysis-only archive requires at least one regular research/*.md evidence file")
+        kind = "analysis_complete"
+    else:
+        kind = "administrative_abandonment"
+    record["archive"] = {"kind": kind, "reason": reason.strip(), "recorded_at": datetime.now(timezone.utc).isoformat()}
+    data.setdefault("meta", {})["planning"] = record

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

@@ -68,6 +68,7 @@ from .task_utils import (
     resolve_task_dir,
     run_task_hooks,
 )
+from .task_planning import PlanningError, prepare_archive
 from .workflow_selection import DIR_WORKFLOWS, WORKFLOW_ID_RE
 
 
@@ -582,7 +583,7 @@ def cmd_create(args: argparse.Namespace) -> int:
         "parent": None,
         "relatedFiles": [],
         "notes": "",
-        "meta": meta,
+        "meta": {**meta, "planning": {"revision": 1, "stage": "intake"}},
     }
     # Optional per-task workflow selection: key present only when opted in,
     # so tasks without a selection keep today's task.json shape byte-for-byte.
@@ -1385,6 +1386,11 @@ def cmd_archive(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
         else:
+            try:
+                prepare_archive(data, task_dir, getattr(args, "reason", None))
+            except PlanningError as exc:
+                print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+                return 1
             # Before any mutation: branch metadata is unrecoverable once the
             # task leaves the active tree. Stale branches only warn.
             if not _validate_branch_metadata(
@@ -1985,9 +1991,12 @@ def cmd_set_meta(args: argparse.Namespace) -> int:
     meta = data.get("meta")
     if not isinstance(meta, dict):
         meta = {}
+    if key in {"execution_class", "delivery_mode"} and meta.get(key) != value and data.get("status") == "in_progress":
+        print(colored("Error: replan the in-progress task before changing its classification", Colors.RED), file=sys.stderr)
+        return 1
     if key in {"execution_class", "delivery_mode"} and meta.get(key) != value and "planning" in meta:
         try:
-            invalidate_plan(data)
+            invalidate_plan(data, "intake")
         except ValueError as exc:
             print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
             return 1