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

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

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

@@ -12,7 +12,7 @@ Usage:
     python3 task.py plan seal <dir>             # Seal the current material plan
     python3 task.py plan approve <dir> --revision N --basis "approval"
     python3 task.py start <dir>                 # Start an approved task, record current branch
-    python3 task.py replan <dir> "<reason>"     # Return an in-progress task to planning
+    python3 task.py replan <dir> --to <stage> "<reason>"  # Reopen the earliest affected planning stage
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py ownership <operation> ...   # Manage formal handoff task ownership
     python3 task.py finish                      # Clear active task
@@ -37,6 +37,7 @@ import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 
 from common.log import Colors, colored
 from common.paths import (
@@ -64,8 +65,10 @@ from common.io import (
 )
 from common.task_utils import is_within_tasks_dir, resolve_task_dir, run_task_hooks
 from common.task_planning import (
-    PlanningError, approve_plan, invalidate_plan, require_start_approval, seal_plan,
+    PlanningError, REPLAN_STAGES, STAGES, advance_stage, approve_plan, invalidate_plan, plan_digest,
+    planning_record, require_start_approval, seal_plan,
 )
+from common.task_migration import MigrationError, migrate as migrate_tasks, rollback as rollback_task_migration
 from common.tasks import iter_active_tasks, children_progress
 from common.workflow_selection import WORKFLOW_ID_RE, workflow_md_for_task
 
@@ -234,12 +237,38 @@ def cmd_select(args: argparse.Namespace) -> int:
 
 def cmd_plan(args: argparse.Namespace) -> int:
     repo_root = get_repo_root()
+    if args.plan_command == "migrate":
+        try:
+            if args.rollback:
+                receipt_path = args.rollback if args.rollback.is_absolute() else repo_root / args.rollback
+                result = rollback_task_migration(repo_root, receipt_path)
+            else:
+                if not args.manifest:
+                    raise MigrationError("plan migrate requires --manifest unless --rollback is used")
+                manifest_path = args.manifest if args.manifest.is_absolute() else repo_root / args.manifest
+                result = migrate_tasks(repo_root, manifest_path, apply=args.apply, receipt_value=args.receipt)
+        except (MigrationError, OwnershipError, OSError, ValueError) as exc:
+            print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+            return 1
+        print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+        return 0
+    stage: str | None = None
     try:
         target, data = _active_task_target(args.dir, repo_root)
+        if args.plan_command == "digest":
+            print(json.dumps({
+                "task_id": data.get("id") or target.name,
+                "revision": planning_record(data)["revision"],
+                "digest": plan_digest(data, target),
+            }, ensure_ascii=False, sort_keys=True))
+            return 0
         if data.get("status") != "planning":
-            raise PlanningError("plan seal/approve requires planning; use replan for a material change")
-        if args.plan_command == "seal":
-            revision = seal_plan(data, target)
+            raise PlanningError("planning transitions require status=planning; use replan for an in-progress task")
+        if args.plan_command == "advance":
+            stage = advance_stage(data, target, args.to)
+            revision = planning_record(data)["revision"]
+        elif args.plan_command == "seal":
+            revision = seal_plan(data, target, args.expected_digest)
         else:
             approve_plan(data, target, args.revision, args.basis)
             revision = args.revision
@@ -248,7 +277,10 @@ def cmd_plan(args: argparse.Namespace) -> int:
     except (PlanningError, OwnershipError, OSError, ValueError) as exc:
         print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
         return 1
-    print(colored(f"✓ Plan {args.plan_command}: revision {revision}", Colors.GREEN))
+    if args.plan_command == "advance":
+        print(colored(f"✓ Planning stage: {stage} (revision {revision})", Colors.GREEN))
+    else:
+        print(colored(f"✓ Plan {args.plan_command}: revision {revision}", Colors.GREEN))
     return 0
 
 
@@ -376,51 +408,37 @@ def cmd_start(args: argparse.Namespace) -> int:
 
 
 def cmd_replan(args: argparse.Namespace) -> int:
-    """Return an in-progress task to planning without losing its binding."""
+    """Return a task to its earliest affected planning stage."""
     repo_root = get_repo_root()
-    full_path = resolve_task_dir(args.dir, repo_root)
-    if full_path is None or not full_path.is_dir():
-        print(colored(f"Error: Task not found: {args.dir}", Colors.RED), file=sys.stderr)
-        return 1
-
     try:
-        assert_task_mutation_allowed(repo_root, full_path)
-    except (OwnershipError, OSError) as exc:
+        full_path, data = _active_task_target(args.dir, repo_root)
+    except (PlanningError, OwnershipError, OSError, ValueError) as exc:
         print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
-        return 2
+        return 1
 
     reason = " ".join(args.reason).strip()
     if not reason:
         print(colored("Error: replan reason must not be empty", Colors.RED), file=sys.stderr)
         return 1
 
-    task_json_path = full_path / FILE_TASK_JSON
-    data, read_reason = read_json_checked(task_json_path)
-    if data is None:
-        problem, hint = describe_json_read_failure(task_json_path, read_reason)
-        print(colored(f"Error: {problem}", Colors.RED), file=sys.stderr)
-        print(hint, file=sys.stderr)
-        return 1
-    if data.get("status") != "in_progress":
-        print(
-            colored(
-                f"Error: replan requires status=in_progress (found {data.get('status')!r})",
-                Colors.RED,
-            ),
-            file=sys.stderr,
-        )
-        return 1
-
     try:
-        invalidate_plan(data)
+        from_status = data["status"]
+        from_stage = planning_record(data).get("stage")
+        if from_status == "planning" and from_stage != "plan_closed":
+            raise PlanningError("replan requires planning/plan_closed or any in_progress task")
+        invalidate_plan(data, args.to)
     except PlanningError as exc:
         print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
         return 1
 
+    task_json_path = full_path / FILE_TASK_JSON
     event = {
         "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "task": full_path.relative_to(repo_root).as_posix(),
-        "from_status": "in_progress",
+        "from_status": from_status,
+        "from_stage": from_stage,
+        "to_stage": args.to,
+        "revision": planning_record(data)["revision"],
         "reason": reason,
         "branch": data.get("branch"),
     }
@@ -443,7 +461,7 @@ def cmd_replan(args: argparse.Namespace) -> int:
         print(colored("Error: replan event recorded but task status was not changed", Colors.RED), file=sys.stderr)
         return 1
 
-    print(colored(f"✓ Task returned to planning: {full_path.relative_to(repo_root)}", Colors.GREEN))
+    print(colored(f"✓ Task returned to planning/{args.to}: {full_path.relative_to(repo_root)}", Colors.GREEN))
     print("Reason:", reason)
     run_task_hooks("after_replan", task_json_path, repo_root)
     return 0
@@ -487,6 +505,15 @@ def cmd_finish(args: argparse.Namespace) -> int:
     return 0
 
 
+def _planning_stage(data: dict[str, Any]) -> str | None:
+    meta = data.get("meta")
+    planning = meta.get("planning") if isinstance(meta, dict) else None
+    stage = planning.get("stage") if isinstance(planning, dict) else None
+    if isinstance(stage, str) and stage:
+        return stage
+    return "intake" if data.get("status") == "planning" else None
+
+
 def cmd_current(args: argparse.Namespace) -> int:
     """Show active task."""
     repo_root = get_repo_root()
@@ -513,6 +540,7 @@ def cmd_current(args: argparse.Namespace) -> int:
                 "id": data.get("id") or data.get("name"),
                 "title": data.get("title"),
                 "status": data.get("status"),
+                "planning_stage": _planning_stage(data),
                 "parent": data.get("parent"),
                 "children": data.get("children", []),
                 "branch": data.get("branch"),
@@ -757,6 +785,7 @@ def cmd_list(args: argparse.Namespace) -> int:
                 "id": t.raw.get("id") or dir_name,
                 "title": t.title,
                 "status": t.status,
+                "planning_stage": _planning_stage(t.raw),
                 "display_status": _display_status(t, all_statuses),
                 "priority": t.priority,
                 "assignee": t.assignee or None,
@@ -800,6 +829,9 @@ def cmd_list(args: argparse.Namespace) -> int:
         # Children progress
         progress = children_progress(t.children, all_statuses)
         status_label = _display_status(t, all_statuses)
+        stage = _planning_stage(t.raw)
+        if stage:
+            status_label += f" · {stage}"
 
         # Package tag
         pkg_tag = f" @{t.package}" if t.package else ""
@@ -883,6 +915,8 @@ Usage:
   python3 task.py select <dir>                       Select context without starting
   python3 task.py plan seal <dir>                    Seal the current material plan
   python3 task.py plan approve <dir> --revision N --basis "approval"
+  python3 task.py plan migrate --manifest <file> [--apply --receipt <.trellis/file>]
+  python3 task.py plan migrate --rollback <.trellis/receipt.json>
   python3 task.py create <title> --description <desc> --package <pkg>   Create task for a specific package
   python3 task.py create <title> --description <desc> --parent <dir>    Create task as child of parent
   python3 task.py create <title> --description <desc> --no-start        Create without making it active in this session
@@ -891,7 +925,7 @@ Usage:
   python3 task.py validate <dir>                     Validate jsonl files
   python3 task.py list-context <dir>                 List jsonl entries
   python3 task.py start <dir>                        Set active task; records the checked-out branch when unset
-  python3 task.py replan <dir> "<reason>"            Return an in-progress task to planning
+  python3 task.py replan <dir> --to <stage> "<reason>" Return task to its earliest affected planning stage
   python3 task.py current [--source]                 Show active task
   python3 task.py finish                             Clear active task
   python3 task.py workflow <id>                      Select workflow variant for active task
@@ -1047,14 +1081,26 @@ def main() -> int:
     p_select = subparsers.add_parser("select", help="Select a task without changing its phase")
     p_select.add_argument("dir", help="Existing active task directory")
 
-    p_plan = subparsers.add_parser("plan", help="Seal a reviewed material plan or record its explicit approval")
+    p_plan = subparsers.add_parser("plan", help="Advance planning, inspect a plan digest, seal, migrate, or record approval")
     plan_sub = p_plan.add_subparsers(dest="plan_command", required=True)
+    p_advance = plan_sub.add_parser("advance", help="Advance to an allowed planning stage")
+    p_advance.add_argument("dir", help="Planning task directory")
+    p_advance.add_argument("--to", choices=sorted(STAGES - {"plan_closed"}), required=True, help="Target planning stage")
+    p_digest = plan_sub.add_parser("digest", help="Show the digest of the complete current plan")
+    p_digest.add_argument("dir", help="Planning task directory")
     p_seal = plan_sub.add_parser("seal", help="Seal the current material plan revision")
     p_seal.add_argument("dir", help="Planning task directory")
+    p_seal.add_argument("--expected-digest", required=True, help="Digest shown with the complete plan to the user")
     p_approve = plan_sub.add_parser("approve", help="Record actual user approval of the displayed plan")
     p_approve.add_argument("dir", help="Planning task directory")
     p_approve.add_argument("--revision", type=int, required=True)
     p_approve.add_argument("--basis", required=True, help="Short non-sensitive basis for real approval")
+    p_migrate = plan_sub.add_parser("migrate", help="Preview or apply a digest-guarded legacy task migration")
+    migration_mode = p_migrate.add_mutually_exclusive_group()
+    migration_mode.add_argument("--apply", action="store_true", help="Apply after validating every frozen source digest")
+    migration_mode.add_argument("--rollback", type=Path, help="Conditionally restore a prior migration receipt")
+    p_migrate.add_argument("--manifest", type=Path, help="Frozen JSON migration manifest (required except for rollback)")
+    p_migrate.add_argument("--receipt", help="New rollback receipt path under .trellis/; required with --apply")
 
     # start
     p_start = subparsers.add_parser("start", help="Set active task")
@@ -1066,9 +1112,10 @@ def main() -> int:
     )
 
     # replan
-    p_replan = subparsers.add_parser("replan", help="Return an in-progress task to planning")
+    p_replan = subparsers.add_parser("replan", help="Return an in-progress task to a selected planning stage")
     p_replan.add_argument("dir", help="Task directory")
     p_replan.add_argument("reason", nargs="+", help="Material reason for returning to planning")
+    p_replan.add_argument("--to", choices=sorted(REPLAN_STAGES), required=True, help="Earliest affected planning stage")
 
     # current
     p_current = subparsers.add_parser("current", help="Show active task")
@@ -1176,6 +1223,7 @@ def main() -> int:
     p_archive = subparsers.add_parser("archive", help="Archive task")
     p_archive.add_argument("name", help="Task directory or name")
     p_archive.add_argument("--no-commit", action="store_true", help="Skip auto git commit after archive")
+    p_archive.add_argument("--reason", help="Required when archiving a planning task")
     p_archive.add_argument(
         "--skip-branch-validation",
         action="store_true",