@pennixrv/trellis 0.7.0-beta.5 → 0.7.0-beta.50

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

@@ -97,8 +97,8 @@ MARKER_PREFIX = "<!-- trellis-session:"
 # fingerprint mixed in the calendar date; see compute_record_fingerprint.
 MARKER_VERSION = 2
 LEGACY_MARKER_RE = re.compile(r"^<!-- trellis-session: fp=([0-9a-f]{16}) -->$")
-ENTRY_DATE_RE = re.compile(r"^\*\*Date\*\*: (\d{4}-\d{2}-\d{2})\s*$")
-SESSION_HEADING_RE = re.compile(r"^## Session (\d+):", re.MULTILINE)
+ENTRY_DATE_RE = re.compile(r"^\*\*(?:Date|日期（Date）)\*\*: (\d{4}-\d{2}-\d{2})\s*$")
+SESSION_HEADING_RE = re.compile(r"^## (?:Session|会话（Session）) (\d+)(?::|：)", re.MULTILINE)
 
 # Recording states, in the order the operation walks them.
 STATE_ABSENT = "absent"
@@ -170,7 +170,7 @@ def _max_session_in_index(content: str) -> int:
 
 
 def _max_session_in_journal(content: str) -> int:
-    """Highest `## Session N:` heading in a journal body (0 when none)."""
+    """Highest old or new session heading in a journal body (0 when none)."""
     numbers = [int(m.group(1)) for m in SESSION_HEADING_RE.finditer(content)]
     return max(numbers) if numbers else 0
 
@@ -195,7 +195,7 @@ def count_journal_files(dev_dir: Path, active_num: int) -> str:
     for f in files:
         filename = f.name
         lines = len(f.read_text(encoding="utf-8").splitlines())
-        status = "Active" if filename == active_file else "Archived"
+        status = "活动（Active）" if filename == active_file else "归档（Archived）"
         result_lines.append(f"| `{filename}` | ~{lines} | {status} |")
 
     return "\n".join(result_lines)
@@ -301,10 +301,10 @@ def create_new_journal_file(
     prev_num = num - 1
     new_file = dev_dir / f"{FILE_JOURNAL_PREFIX}{num}.md"
 
-    content = f"""# Journal - {developer} (Part {num})
+    content = f"""# 日志（Journal）- {developer}（第 {num} 部分）
 
-> Continuation from `{FILE_JOURNAL_PREFIX}{prev_num}.md` (archived at ~{max_lines} lines)
-> Started: {today}
+> 续接自 `{FILE_JOURNAL_PREFIX}{prev_num}.md`（约 {max_lines} 行时归档）
+> 开始日期（Started）: {today}
 
 ---
 
@@ -615,7 +615,7 @@ def _max_session_across_refs(repo_root: Path, refs: list[str], dev_rel: str) ->
             "-h",
             "-E",
             "-e",
-            r"^## Session [0-9]+:",
+            r"^## (Session [0-9]+:|会话（Session） [0-9]+：)",
             "-e",
             r"Total Sessions",
         ]
@@ -629,7 +629,7 @@ def _max_session_across_refs(repo_root: Path, refs: list[str], dev_rel: str) ->
 
     # `git grep` prefixes each hit with `<rev>:<path>:`, so the numbers are
     # matched anywhere in the line rather than anchored.
-    numbers = [int(m.group(1)) for m in re.finditer(r"## Session (\d+):", out)]
+    numbers = [int(m.group(1)) for m in re.finditer(r"## (?:Session|会话（Session）) (\d+)(?::|：)", out)]
     numbers += [
         int(m.group(1)) for m in re.finditer(r"Total Sessions[^\d]{0,8}(\d+)", out)
     ]
@@ -843,7 +843,7 @@ def classify_record(
     if session_num is None:
         return "", None, None, (
             f"{journal_file.name} carries this record's marker without a "
-            "'## Session N:' heading above it. The pending record is malformed; "
+            "session heading above it. The pending record is malformed; "
             "repair it by hand before retrying."
         )
 
@@ -884,9 +884,9 @@ def _render_bullet_section(header: str, items: list[str], bullet_prefix: str = "
 def _render_main_changes(changes: list[str], extra_content: str | None) -> str:
     """Render the Main Changes section from --change bullets or freeform content."""
     if changes:
-        return _render_bullet_section("Main Changes", changes)
+        return _render_bullet_section("主要变更（Main Changes）", changes)
     if extra_content:
-        return f"\n\n### Main Changes\n\n{extra_content}"
+        return f"\n\n### 主要变更（Main Changes）\n\n{extra_content}"
     return ""
 
 
@@ -906,39 +906,39 @@ def generate_session_content(
 ) -> str:
     """Generate session content."""
     if evidence:
-        commit_table = """| Hash | Message |
+        commit_table = """| 哈希（Hash） | 消息（Message） |
 |------|---------|"""
         for oid, subject in evidence:
             commit_table += f"\n| `{oid}` | {escape_markdown_cell(subject)} |"
     else:
-        commit_table = "(No commits - planning session)"
+        commit_table = "（无提交——规划会话）"
 
-    package_line = f"\n**Package**: {package}" if package else ""
-    branch_line = f"\n**Branch**: `{branch}`" if branch else ""
+    package_line = f"\n**包（Package）**: {package}" if package else ""
+    branch_line = f"\n**分支（Branch）**: `{branch}`" if branch else ""
 
     main_changes_section = _render_main_changes(changes or [], extra_content)
-    testing_section = _render_bullet_section("Testing", tests or [], bullet_prefix="- [OK] ")
-    next_steps_section = _render_bullet_section("Next Steps", next_steps or [])
+    testing_section = _render_bullet_section("测试（Testing）", tests or [], bullet_prefix="- [OK] ")
+    next_steps_section = _render_bullet_section("下一步（Next Steps）", next_steps or [])
 
     return f"""
 
-## Session {session_num}: {title}
+## 会话（Session） {session_num}：{title}
 {marker}
 
-**Date**: {today}
-**Task**: {title}{package_line}{branch_line}
+**日期（Date）**: {today}
+**任务（Task）**: {title}{package_line}{branch_line}
 
-### Summary
+### 摘要（Summary）
 
 {summary}{main_changes_section}
 
-### Git Commits
+### Git 提交（Git Commits）
 
 {commit_table}{testing_section}
 
-### Status
+### 状态（Status）
 
-[OK] **Completed**{next_steps_section}
+[OK] **已完成（Completed）**{next_steps_section}
 """
 
 
@@ -992,9 +992,9 @@ def update_index(
         if "@@@auto:current-status" in line:
             new_lines.append(line)
             in_current_status = True
-            new_lines.append(f"- **Active File**: `{active_file}`")
-            new_lines.append(f"- **Total Sessions**: {new_session}")
-            new_lines.append(f"- **Last Active**: {today}")
+            new_lines.append(f"- **活动文件（Active File）**: `{active_file}`")
+            new_lines.append(f"- **会话总数（Total Sessions）**: {new_session}")
+            new_lines.append(f"- **最近活动（Last Active）**: {today}")
             continue
 
         if "@@@/auto:current-status" in line:
@@ -1005,7 +1005,7 @@ def update_index(
         if "@@@auto:active-documents" in line:
             new_lines.append(line)
             in_active_documents = True
-            new_lines.append("| File | Lines | Status |")
+            new_lines.append("| 文件（File） | 行数（Lines） | 状态（Status） |")
             new_lines.append("|------|-------|--------|")
             new_lines.append(files_table)
             continue
@@ -1038,13 +1038,16 @@ def update_index(
                 r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*Base Branch\s*\|\s*$",
                 line,
             ):
-                new_lines.append("| # | Date | Title | Commits | Branch |")
+                new_lines.append("| # | 日期（Date） | 标题（Title） | 提交（Commits） | 分支（Branch） |")
                 continue
             if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*$", line):
-                new_lines.append("| # | Date | Title | Commits | Branch |")
+                new_lines.append("| # | 日期（Date） | 标题（Title） | 提交（Commits） | 分支（Branch） |")
+                continue
+            if re.match(r"^\|\s*#\s*\|\s*日期（Date）\s*\|\s*标题（Title）\s*\|\s*提交（Commits）\s*\|\s*分支（Branch）\s*\|\s*$", line):
+                new_lines.append("| # | 日期（Date） | 标题（Title） | 提交（Commits） | 分支（Branch） |")
                 continue
             if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*$", line):
-                new_lines.append("| # | Date | Title | Commits | Branch |")
+                new_lines.append("| # | 日期（Date） | 标题（Title） | 提交（Commits） | 分支（Branch） |")
                 continue
             if re.match(r"^\|[-| ]+\|\s*$", line) and not header_written:
                 new_lines.append("|---|------|-------|---------|--------|")

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

@@ -33,7 +33,7 @@ DIR_SHELL_TICKETS = "shell-tickets"
 # platform that works today.
 DIR_LEGACY_CURSOR_SHELL_TICKETS = "cursor-shell"
 SHELL_TICKET_TTL_SECONDS = 30
-TASK_SESSION_COMMANDS = {"start", "current", "finish"}
+TASK_SESSION_COMMANDS = {"start", "replan", "current", "finish"}
 
 _SESSION_KEYS = ("session_id", "sessionId", "sessionID")
 _CONVERSATION_KEYS = ("conversation_id", "conversationId", "conversationID")
@@ -425,7 +425,7 @@ def _pending_ticket_matches_args(ticket: dict[str, Any], repo_root: Path) -> boo
             continue
         if _string_value(subcommand.get("name")) != command_name:
             continue
-        if command_name != "start":
+        if command_name not in {"start", "replan"}:
             return True
         task_ref = args[1] if len(args) > 1 else None
         if _task_refs_match(_string_value(subcommand.get("task_ref")), task_ref, repo_root):
@@ -694,7 +694,7 @@ def resolve_active_task(
         active = _active_from_ref(task_ref, repo_root, "session", context_key)
         if active:
             return active
-        unbound = _resolve_unbound_task(repo_root)
+        unbound = _resolve_unbound_task(repo_root, context_key)
         if unbound is not None:
             return unbound
         return ActiveTask(None, "none", context_key)
@@ -736,8 +736,8 @@ def _resolve_single_session_fallback(repo_root: Path) -> ActiveTask | None:
     return _active_from_ref(task_ref, repo_root, "session-fallback", fallback_key)
 
 
-def _resolve_unbound_task(repo_root: Path) -> ActiveTask | None:
-    """Expose one developer-owned task when no session pointer exists."""
+def _resolve_unbound_task(repo_root: Path, context_key: str | None = None) -> ActiveTask | None:
+    """Expose read-only candidates without discarding a resolved identity."""
     sessions_dir = _runtime_sessions_dir(repo_root)
     if sessions_dir.is_dir():
         session_files = sorted(sessions_dir.glob("*.json"))
@@ -764,8 +764,8 @@ def _resolve_unbound_task(repo_root: Path) -> ActiveTask | None:
         for task in candidates
     ))
     if len(task_paths) == 1:
-        return ActiveTask(task_paths[0], "unbound", None)
-    return ActiveTask(None, "unbound_ambiguous", None, candidate_paths=task_paths)
+        return ActiveTask(task_paths[0], "unbound", context_key)
+    return ActiveTask(None, "unbound_ambiguous", context_key, candidate_paths=task_paths)
 
 
 def _utc_now() -> str:
@@ -834,7 +834,7 @@ def clear_active_task(
         return ActiveTask(None, "none")
 
     previous = resolve_active_task(repo_root, platform_input, platform)
-    if not previous.task_path or not previous.context_key:
+    if previous.source_type != "session" or not previous.task_path or not previous.context_key:
         return previous
 
     context_path = _context_path(repo_root, previous.context_key)

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

@@ -78,10 +78,10 @@ def init_developer(name: str, repo_root: Path | None = None) -> bool:
     journal_file = workspace_dir / f"{FILE_JOURNAL_PREFIX}1.md"
     if not journal_file.exists():
         today = datetime.now().strftime("%Y-%m-%d")
-        journal_content = f"""# Journal - {name} (Part 1)
+        journal_content = f"""# 日志（Journal）- {name}（第 1 部分）
 
-> AI development session journal
-> Started: {today}
+> AI 开发会话日志
+> 开始日期（Started）: {today}
 
 ---
 
@@ -95,46 +95,46 @@ def init_developer(name: str, repo_root: Path | None = None) -> bool:
     # Create index.md with markers for auto-update
     index_file = workspace_dir / "index.md"
     if not index_file.exists():
-        index_content = f"""# Workspace Index - {name}
+        index_content = f"""# 工作区索引（Workspace Index）- {name}
 
-> Journal tracking for AI development sessions.
+> AI 开发会话跟踪日志。
 
 ---
 
-## Current Status
+## 当前状态（Current Status）
 
 <!-- @@@auto:current-status -->
-- **Active File**: `journal-1.md`
-- **Total Sessions**: 0
-- **Last Active**: -
+- **活动文件（Active File）**: `journal-1.md`
+- **会话总数（Total Sessions）**: 0
+- **最近活动（Last Active）**: -
 <!-- @@@/auto:current-status -->
 
 ---
 
-## Active Documents
+## 活动文档（Active Documents）
 
 <!-- @@@auto:active-documents -->
-| File | Lines | Status |
+| 文件（File） | 行数（Lines） | 状态（Status） |
 |------|-------|--------|
-| `journal-1.md` | ~0 | Active |
+| `journal-1.md` | ~0 | 活动（Active） |
 <!-- @@@/auto:active-documents -->
 
 ---
 
-## Session History
+## 会话历史（Session History）
 
 <!-- @@@auto:session-history -->
-| # | Date | Title | Commits | Branch |
+| # | 日期（Date） | 标题（Title） | 提交（Commits） | 分支（Branch） |
 |---|------|-------|---------|--------|
 <!-- @@@/auto:session-history -->
 
 ---
 
-## Notes
+## 备注（Notes）
 
-- Sessions are appended to journal files
-- New journal file created when current exceeds 2000 lines
-- Use `add_session.py` to record sessions
+- 会话会追加到日志文件
+- 当前日志超过 2000 行时创建新的日志文件
+- 使用 `add_session.py` 记录会话
 """
         try:
             index_file.write_text(index_content, encoding="utf-8")

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

@@ -10,7 +10,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from .active_task import clear_active_task, clear_active_task_for_context, resolve_active_task, resolve_context_key, set_active_task
+from .active_task import ActiveTask, clear_active_task, clear_active_task_for_context, resolve_active_task, resolve_context_key, set_active_task
 from .continuation_record import (
     ContinuationError,
     SAFE_ID,
@@ -83,6 +83,9 @@ def _direct_context(root: Path, require_task: bool = False) -> tuple[str, Any]:
         raise OwnershipError("session_fallback_untrusted")
     if active.context_key != context_key:
         raise OwnershipError("direct_session_identity_unstable")
+    if active.source_type in {"unbound", "unbound_ambiguous"}:
+        # Candidate paths are recovery context, never an owned session pointer.
+        active = ActiveTask(None, "none", context_key)
     if require_task and not active.task_path:
         raise OwnershipError("no_direct_current_task")
     return context_key, active
@@ -273,14 +276,14 @@ def retire(root: Path, task_id: str, handoff_id: str, core_digest: str, expected
         elif record["archive_observation"] != archive_observation:
             raise OwnershipError("archive observation does not match retirement")
 
-        active = resolve_active_task(root, allow_single_session_fallback=False)
+        _, active = _direct_context(root)
         if active.context_key != actor:
             raise OwnershipError("direct_session_identity_unstable")
         if active.task_path == record["task"]["path"]:
             clear_active_task(root)
         elif active.task_path:
             raise OwnershipError("source task pointer changed during retirement")
-        active = resolve_active_task(root, allow_single_session_fallback=False)
+        _, active = _direct_context(root)
         if active.context_key != actor or active.task_path:
             raise OwnershipError("source task retirement could not be verified; recovery_required")
         record["previous_event_digest"] = record["integrity"]["record_digest"]
@@ -334,7 +337,7 @@ def claim(root: Path, task_id: str, task_path: str, handoff_id: str, core_digest
                 bound = set_active_task(record["task"]["path"], root)
                 if not bound:
                     raise OwnershipError("target task binding failed; recovery_required")
-                active = resolve_active_task(root, allow_single_session_fallback=False)
+                _, active = _direct_context(root)
             if active.context_key != actor or active.task_path != record["task"]["path"]:
                 raise OwnershipError("target task binding could not be verified; recovery_required")
             record["previous_event_digest"] = record["integrity"]["record_digest"]
@@ -361,7 +364,7 @@ def claim(root: Path, task_id: str, task_path: str, handoff_id: str, core_digest
         bound = set_active_task(task["path"], root)
         if not bound:
             raise OwnershipError("target task binding failed; recovery_required")
-        active = resolve_active_task(root, allow_single_session_fallback=False)
+        _, active = _direct_context(root)
         if active.context_key != actor or active.task_path != task["path"]:
             raise OwnershipError("target task binding could not be verified; recovery_required")
         record["previous_event_digest"] = record["integrity"]["record_digest"]
@@ -416,17 +419,19 @@ def status(root: Path | None, task_id: str, handoff_id: str, core_digest: str) -
 def assert_task_mutation_allowed(root: Path, task_path: Path) -> None:
     """Reject ordinary task pointer changes that would bypass ownership fencing."""
     actor = resolve_context_key()
-    if not actor:
-        return
     try:
         task_id = _safe_task_id(task_path.name)
     except ContinuationError:
         return
     relative = task_path.relative_to(root).as_posix()
     records_dir = root / ".trellis" / ".runtime" / "handoff-ownership" / task_id
-    if not records_dir.is_dir() or records_dir.is_symlink():
+    if records_dir.is_symlink():
+        raise OwnershipError("ownership record directory is unsafe")
+    if not records_dir.is_dir():
         return
     for record_path in sorted(records_dir.glob("*.json")):
+        if not actor:
+            raise OwnershipError("no_direct_session_identity: task has handoff ownership fencing")
         if record_path.is_symlink():
             raise OwnershipError("ownership record is unsafe")
         record = _decode(record_path)

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

@@ -145,12 +145,13 @@ def safe_archive_paths_to_add(
     repo_root: Path,
     task_name: str | None = None,
     modified_children: list[str] | None = None,
+    archive_dest: Path | None = None,
 ) -> list[str]:
     """Return paths to stage after `task.py archive`.
 
     Scoped to ONLY the paths the archive operation actually touched:
 
-      - the archive subtree (where the freshly-moved task lives)
+      - the exact archive task directory (where the freshly-moved task lives)
       - the source task directory (for source-side deletes; caller pairs
         this with `git rm --cached` since `git add` won't stage deletes
         for a path that no longer exists in the working tree)
@@ -174,14 +175,42 @@ def safe_archive_paths_to_add(
     archive_dir = tasks_dir / DIR_ARCHIVE
 
     if task_name is not None:
-        # Narrow scope — only paths that still exist on disk (so
-        # `git add` doesn't choke on the moved-away source). The caller
-        # handles the source-side deletes via `git rm --cached`
-        # explicitly.
-        if archive_dir.is_dir():
-            paths.append(
-                f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}"
-            )
+        # Narrow scope — only the exact destination that the archive operation
+        # moved. The destination is passed by task_store, which already owns
+        # the move result. Validate it again so a caller cannot widen the
+        # auto-commit to the archive root or a sibling month/task directory.
+        candidate: Path | None = None
+        if archive_dest is not None:
+            candidate = archive_dest
+            if not candidate.is_absolute():
+                candidate = repo_root / candidate
+        elif archive_dir.is_dir():
+            # Compatibility for callers that only have a task name. An
+            # ambiguous historical layout fails closed instead of staging the
+            # whole archive tree.
+            matches = [
+                month_dir / task_name
+                for month_dir in sorted(archive_dir.iterdir())
+                if month_dir.is_dir() and (month_dir / task_name).is_dir()
+            ]
+            if len(matches) == 1:
+                candidate = matches[0]
+
+        if candidate is not None and candidate.is_dir():
+            try:
+                candidate_resolved = candidate.resolve()
+                archive_resolved = archive_dir.resolve()
+                if (
+                    candidate_resolved.name == task_name
+                    and candidate_resolved.parent.parent == archive_resolved
+                ):
+                    relative = candidate_resolved.relative_to(repo_root.resolve())
+                    paths.append(relative.as_posix())
+            except (OSError, RuntimeError, ValueError):
+                # An invalid or ambiguous destination must not widen scope.
+                pass
+        if not paths:
+            return []
         for child_name in modified_children or []:
             paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child_name}")
         return paths

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

@@ -0,0 +1,137 @@
+"""Task-local material plan revisions; chat approval remains coordinator-owned."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+
+
+class PlanningError(ValueError):
+    """A planning contract needs correction before a task can start."""
+
+
+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")
+    choices = {
+        "execution_class": {"direct", "planned"},
+        "delivery_mode": {"change_bearing", "analysis_only"},
+    }
+    if key in choices and value not in choices[key]:
+        raise PlanningError(f"{key} must be one of: {', '.join(sorted(choices[key]))}")
+
+
+def classification(data: dict[str, Any]) -> tuple[str, str]:
+    meta = data.get("meta", {})
+    if not isinstance(meta, dict):
+        raise PlanningError("task meta must be an object")
+    execution = meta.get("execution_class")
+    delivery = meta.get("delivery_mode")
+    if execution not in ("direct", "planned") or delivery not in ("change_bearing", "analysis_only"):
+        raise PlanningError("classify this task with execution_class=direct|planned and delivery_mode=change_bearing|analysis_only before start")
+    return execution, delivery
+
+
+def planning_record(data: dict[str, Any]) -> dict[str, Any]:
+    meta = data.get("meta", {})
+    if not isinstance(meta, dict):
+        raise PlanningError("task meta must be an object")
+    record = meta.get("planning", {})
+    if not isinstance(record, dict):
+        raise PlanningError("meta.planning must be an object")
+    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}
+
+
+def invalidate_plan(data: dict[str, Any]) -> None:
+    record = planning_record(data)
+    data.setdefault("meta", {})["planning"] = {"revision": record["revision"] + 1}
+
+
+def _plan_documents(task_dir: Path, execution: str, delivery: str) -> list[str]:
+    names = ["prd.md"]
+    if execution == "planned":
+        names.append("design.md")
+        if delivery == "change_bearing":
+            names.append("implement.md")
+    for name in names:
+        document = task_dir / name
+        if document.is_symlink() or not document.is_file():
+            raise PlanningError(f"plan requires a regular task document: {name}")
+        if document.stat().st_size > 256 * 1024 or not document.read_text(encoding="utf-8").strip():
+            raise PlanningError(f"plan document must be bounded, non-empty UTF-8: {name}")
+    return names
+
+
+def seal_plan(data: dict[str, Any], task_dir: Path) -> int:
+    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.
+    revision = record["revision"] + (1 if record.get("seal") else 0)
+    data.setdefault("meta", {})["planning"] = {
+        "revision": revision,
+        "seal": {
+            "revision": revision,
+            "task_id": data.get("id") or task_dir.name,
+            "task_name": task_dir.name,
+            "documents": documents,
+            "document_digests": {name: sha256((task_dir / name).read_bytes()).hexdigest() for name in documents},
+            "execution_class": execution,
+            "delivery_mode": delivery,
+            "sealed_at": datetime.now(timezone.utc).isoformat(),
+        },
+    }
+    return revision
+
+
+def _require_seal(data: dict[str, Any], task_dir: Path) -> dict[str, Any]:
+    execution, delivery = classification(data)
+    record = planning_record(data)
+    seal = record.get("seal")
+    if not isinstance(seal, dict) or type(seal.get("revision")) is not int or seal.get("revision") != record["revision"]:
+        raise PlanningError("current material plan is not sealed; use task.py plan seal")
+    if seal.get("task_id") != (data.get("id") or task_dir.name) or seal.get("task_name") != task_dir.name:
+        raise PlanningError("sealed plan belongs to another task")
+    if seal.get("execution_class") != execution or seal.get("delivery_mode") != delivery:
+        raise PlanningError("plan classification changed; reseal the material plan")
+    if seal.get("documents") != _plan_documents(task_dir, execution, delivery):
+        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")
+    return record
+
+
+def approve_plan(data: dict[str, Any], task_dir: Path, revision: int, basis: str) -> None:
+    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:
+        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(),
+    })
+    data["meta"]["planning"] = record
+
+
+def require_start_approval(data: dict[str, Any], task_dir: Path) -> None:
+    if data.get("status") not in {"planning", "in_progress"}:
+        raise PlanningError("start requires an active planning or in_progress task")
+    # Existing running tasks retain their authorization; only crossing the
+    # planning boundary is gated. Selecting a task never crosses that boundary.
+    if data.get("status") == "in_progress":
+        return
+    execution, delivery = classification(data)
+    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)
+        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 later implementation approval; use task.py plan approve only after the user's approval")