@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-research/scripts/archive_milestone.py

@@ -24,13 +24,15 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Iterator, NamedTuple, Optional, Sequence
 
-try:
-    from isolation import (
+if __package__:
+    from .isolation import (
         IsolationError,
+        prune_host_scratch,
+        PROJECT_ENTRIES,
         checkpoint as isolation_checkpoint,
         verify_landed_task_files,
     )
-    from pipeline_git import (
+    from .pipeline_git import (
         bound_branch_name,
         default_branch_name,
         integrate_commit_body,
@@ -43,45 +45,75 @@ try:
         ship_commit_body,
         ship_subject,
     )
-    from review_panel import KNOWN_FAMILIES, ReviewPanelError, parse_sources
-    from pipeline_state import (
+    from .review_panel import KNOWN_FAMILIES, ReviewPanelError, parse_sources
+    from .pipeline_state import (
         PipelineState,
         PipelineStateError,
         load_state,
         transition_state,
     )
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts.isolation import (
-        IsolationError,
-        checkpoint as isolation_checkpoint,
-        verify_landed_task_files,
-    )
-    from scripts.pipeline_git import (
-        bound_branch_name,
-        default_branch_name,
-        integrate_commit_body,
-        integrate_subject,
-        is_bound_branch,
-        is_integrate_subject,
-        is_ship_subject,
-        milestone_id,
-        milestone_number,
-        ship_commit_body,
-        ship_subject,
-    )
-    from scripts.review_panel import KNOWN_FAMILIES, ReviewPanelError, parse_sources
-    from scripts.pipeline_state import (
-        PipelineState,
-        PipelineStateError,
-        load_state,
-        transition_state,
-    )
-    from scripts import _common
-
-if sys.platform == "win32":
-    import msvcrt
+    from . import _common
 else:
+    try:
+        from isolation import (
+            IsolationError,
+            prune_host_scratch,
+            PROJECT_ENTRIES,
+            checkpoint as isolation_checkpoint,
+            verify_landed_task_files,
+        )
+        from pipeline_git import (
+            bound_branch_name,
+            default_branch_name,
+            integrate_commit_body,
+            integrate_subject,
+            is_bound_branch,
+            is_integrate_subject,
+            is_ship_subject,
+            milestone_id,
+            milestone_number,
+            ship_commit_body,
+            ship_subject,
+        )
+        from review_panel import KNOWN_FAMILIES, ReviewPanelError, parse_sources
+        from pipeline_state import (
+            PipelineState,
+            PipelineStateError,
+            load_state,
+            transition_state,
+        )
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts.isolation import (
+            IsolationError,
+            prune_host_scratch,
+            PROJECT_ENTRIES,
+            checkpoint as isolation_checkpoint,
+            verify_landed_task_files,
+        )
+        from scripts.pipeline_git import (
+            bound_branch_name,
+            default_branch_name,
+            integrate_commit_body,
+            integrate_subject,
+            is_bound_branch,
+            is_integrate_subject,
+            is_ship_subject,
+            milestone_id,
+            milestone_number,
+            ship_commit_body,
+            ship_subject,
+        )
+        from scripts.review_panel import KNOWN_FAMILIES, ReviewPanelError, parse_sources
+        from scripts.pipeline_state import (
+            PipelineState,
+            PipelineStateError,
+            load_state,
+            transition_state,
+        )
+        from scripts import _common
+
+if sys.platform != "win32":
     import fcntl
 
 
@@ -350,31 +382,25 @@ else:  # standalone script or sibling import
 @contextmanager
 def discussion_lock(active_root: Path) -> Iterator[None]:
     if sys.platform == "win32":
-        lock_value = require_git_success(
-            run_git(
-                active_root.parent,
-                "rev-parse",
-                "--git-path",
-                "gsd-path-discussion.lock",
-            ),
-            "resolve discussion lock",
+        # Windows cannot flock a directory, so lock a file in the git dir,
+        # where it never shows up as an untracked project file.
+        resolved = run_git(
+            active_root.parent,
+            "rev-parse",
+            "--git-path",
+            "gsd-path-discussion.lock",
         )
-        lock_path = Path(lock_value)
+        if resolved.returncode != 0 or not resolved.stdout.strip():
+            # Outside git, which the POSIX directory lock allows: the same
+            # named kernel mutex pipeline_state holds for this directory.
+            with _common.directory_mutex(active_root):
+                yield
+            return
+        lock_path = Path(resolved.stdout.strip())
         if not lock_path.is_absolute():
             lock_path = active_root.parent / lock_path
-        lock_path.parent.mkdir(parents=True, exist_ok=True)
-        with lock_path.open("a+b") as handle:
-            handle.seek(0, os.SEEK_END)
-            if handle.tell() == 0:
-                handle.write(b"\0")
-                handle.flush()
-            handle.seek(0)
-            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
-            try:
-                yield
-            finally:
-                handle.seek(0)
-                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        with _common.exclusive_lock(lock_path):
+            yield
         return
 
     descriptor = os.open(active_root, os.O_RDONLY)
@@ -400,10 +426,10 @@ def frontmatter_value(content: str, key: str) -> Optional[str]:
     for line in lines[1:]:
         if line == "---":
             break
-        match = re.match(rf"^{re.escape(key)}:\s*([^#]*?)\s*(?:#.*)?$", line)
+        match = re.match(rf"^{re.escape(key)}:(.*)$", line)
         if match:
-            value = match.group(1).strip().strip('"').strip("'")
-            return value
+            value = _common.strip_yaml_comment(match.group(1))
+            return value.strip().strip('"').strip("'")
     return None
 
 
@@ -535,6 +561,8 @@ def archive_sequence_entries(project: Path) -> dict[int, Path]:
     archive_root = safe_archive_root(project)
     entries = {}
     for candidate in archive_root.iterdir():
+        if _common.is_ignored_junk(candidate):
+            continue
         match = ARCHIVE_PATTERN.fullmatch(candidate.name)
         if match is None or not candidate.is_dir():
             raise ArchiveError(f"archive root has a noncanonical entry: {candidate.name}")
@@ -558,14 +586,11 @@ def resolved_archive_target(
     expected_number = milestone_number(branch)
     configured = parsed_state.archive
     entries = archive_sequence_entries(project)
-    missing_prior = [
-        number for number in range(1, expected_number) if number not in entries
-    ]
     later = sorted(number for number in entries if number > expected_number)
-    if missing_prior or later:
+    if later:
         raise ArchiveError(
             f"archive sequence does not match bound branch {branch}: "
-            f"missing={missing_prior}, later={later}"
+            f"later={later}"
         )
 
     if configured is not None:
@@ -620,7 +645,7 @@ def pending_ruling_count(audit: Path) -> int:
 
 
 def is_existing_carry_forward(source: Path, archived: Path) -> bool:
-    entries = list(source.iterdir()) if source.is_dir() else []
+    entries = [path for path in source.iterdir() if not _common.is_ignored_junk(path)] if source.is_dir() else []
     archived_audit = archived / "DOCS-AUDIT.md"
     if not archived_audit.is_file() or pending_ruling_count(archived_audit) == 0:
         return False
@@ -681,7 +706,7 @@ def is_real_file(path: Path) -> bool:
 def canonical_task_files(tasks: Path) -> Sequence[Path]:
     if tasks.is_symlink() or not tasks.is_dir():
         return ()
-    candidates = sorted(tasks.iterdir())
+    candidates = sorted(path for path in tasks.iterdir() if not _common.is_ignored_junk(path))
     if any(
         not TASK_FILE_PATTERN.fullmatch(path.name) or not is_real_file(path)
         for path in candidates
@@ -1001,6 +1026,7 @@ def prepare(repo: Path, slug: str) -> dict:
     project = repo.resolve()
     active_root = require_project_layout(project)
     with discussion_lock(active_root):
+        prune_host_scratch(active_root)
         return prepare_locked(project, active_root, slug)
 
 
@@ -1036,9 +1062,10 @@ def prepare_locked(project: Path, active_root: Path, slug: str) -> dict:
         final = active_root / "review" / "FINAL.md"
         reviewed = re.search(r"(?m)^Reviewed HEAD:\s*(\S+)", final.read_text(encoding="utf-8")) if final.is_file() else None
         head = require_git_success(run_git(project, "rev-parse", "HEAD"), "resolve HEAD").strip()
-        if reviewed and reviewed.group(1) != head:
+        if reviewed and not _common.reviewed_head_covers(project, reviewed.group(1), head):
             raise ArchiveError(
                 f"FINAL.md Reviewed HEAD {reviewed.group(1)} does not match current HEAD {head}; "
+                f"{_common.RUNTIME_PIN_ALLOWANCE}; "
                 "re-run the final review on the current commit before archiving"
             )
         target = resolved_archive_target(project, slug, parsed_state)
@@ -1131,13 +1158,7 @@ def require_canonical_abandon_inputs(active_root: Path, archive: Path) -> None:
 def write_abandon_manifest(
     archive: Path, slug: str, ruling: str, abandoned_on: str
 ) -> None:
-    contents = []
-    for path in archive.rglob("*"):
-        if path.is_symlink():
-            raise ArchiveError(f"archive contents must not be symlinks: {path}")
-        if path.is_file() and path.name != "MANIFEST.md":
-            contents.append(path.relative_to(archive).as_posix())
-    contents.sort()
+    contents = archive_file_inventory(archive)
     listed_contents = "\n".join(f"- {path}" for path in contents)
     atomic_replace(
         archive / "MANIFEST.md",
@@ -1657,6 +1678,7 @@ def abandon_locked(
 
 
 run_git = _common.run_git
+reviewed_head_covers = _common.reviewed_head_covers
 run_command = _common.run_command
 
 
@@ -1693,10 +1715,13 @@ def require_clean_older_archives(project: Path, configured: str) -> None:
     current_prefix = f"{configured}/"
     dirty = set()
     ignored_current = set()
+    current_files = {f"{configured}/{name}" for name in archive_file_inventory(project / configured)}
     for record in status.split("\0"):
         has_status = len(record) > 3 and record[2] == " "
         code = record[:2] if has_status else ""
         path = record[3:] if has_status else record
+        if code == "!!" and _common.is_ignored_junk(project / path) and path not in current_files:
+            continue  # Ignored OS junk never ships and is not an artifact.
         if code == "!!" and (
             path == ".project/archive/"
             or path == configured
@@ -1745,7 +1770,7 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     archived_audit = archive / "research" / "DOCS-AUDIT.md"
     carried_forward = pending_ruling_count(archived_audit)
     # Persistent project metadata ships but never archives with a milestone.
-    allowed = {"STATE.md", "REPOSITORY.md", "archive", "LESSONS.md", "next"}
+    allowed = {"STATE.md", "REPOSITORY.md", "MEMBERS.md", "archive", "LESSONS.md", "next"}
     for name in ("config.json", "model-policy.json"):
         path = active_root / name
         if path.exists() or path.is_symlink():
@@ -1760,7 +1785,9 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     if carried_forward:
         allowed.add("research")
         active_audit = active_research / "DOCS-AUDIT.md"
-        entries = sorted(path.name for path in active_research.iterdir()) if active_research.is_dir() else []
+        entries = sorted(
+            path.name for path in active_research.iterdir() if not _common.is_ignored_junk(path)
+        ) if active_research.is_dir() else []
         if (
             active_research.is_symlink()
             or entries != ["DOCS-AUDIT.md"]
@@ -1772,7 +1799,12 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     elif active_research.exists() or active_research.is_symlink():
         raise ArchiveError("active research exists without a pending carry-forward queue")
 
-    unexpected = sorted(path.name for path in active_root.iterdir() if path.name not in allowed)
+    # Ignored, untracked non-pipeline entries (.DS_Store) never ship; pipeline entries block even when ignored.
+    visible = _common.git_visible_entries(active_root)
+    unexpected = sorted(
+        path.name for path in active_root.iterdir()
+        if path.name not in allowed and (path.name in PROJECT_ENTRIES or path.name in visible)
+    )
     if unexpected:
         raise ArchiveError(f"unexpected active .project paths remain: {', '.join(unexpected)}")
 
@@ -1848,6 +1880,12 @@ def prepared_transaction(
 
 
 def preflight(repo: Path) -> dict:
+    project = repo.resolve()
+    active_root = require_project_layout(project)
+    configured = strict_state(project)[0].archive
+    current = (archive_from_state(project, configured)
+               if configured and not archive_is_committed(project, configured) else None)
+    prune_host_scratch(active_root, current)
     project, _, state, configured, archive, _, reviewed_head = prepared_transaction(
         repo,
         ("ship", "shipped"),
@@ -1860,9 +1898,10 @@ def preflight(repo: Path) -> dict:
     require_stageable_carry_forward(project, archive)
     require_clean_older_archives(project, configured)
     head = require_git_success(run_git(project, "rev-parse", "HEAD"), "resolve preflight HEAD")
-    if reviewed_head != head:
+    if not reviewed_head_covers(project, reviewed_head, head):
         raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match current HEAD {head}"
+            f"FINAL.md Reviewed HEAD {reviewed_head} does not match current HEAD {head}; "
+            f"{_common.RUNTIME_PIN_ALLOWANCE}"
         )
     return {
         "archive": configured,
@@ -1937,6 +1976,28 @@ def validate_shipped_roadmap(text: str, state: PipelineState, archive: str) -> N
         raise ArchiveError("ROADMAP.md must record Status: shipped and the exact Archive")
 
 
+def member_ship_rows(project: Path, archive: Path, ship_commit: str) -> list:
+    """Ship body member lines, bound to the archived lock order and FINAL.md member heads."""
+    if __package__:
+        from . import check_handoffs
+        from .pipeline_git import ship_member_rows
+    else:
+        import check_handoffs
+        from pipeline_git import ship_member_rows
+    message = require_git_success(run_git(project, "show", "-s", "--format=%B", ship_commit), "inspect ship body")
+    rows = ship_member_rows(message)
+    lock = archive / "build" / "members.json"
+    locked = [entry["name"] for entry in json.loads(lock.read_text(encoding="utf-8"))["members"]] if lock.is_file() else []
+    try:
+        heads = check_handoffs.member_reviewed_heads((archive / "review" / "FINAL.md").read_text(encoding="utf-8"),
+                                                     "FINAL.md")
+    except check_handoffs.HandoffError as error:
+        raise ArchiveError(str(error)) from error
+    if [row["name"] for row in rows] != locked or {row["name"]: row["reviewed_head"] for row in rows} != heads:
+        raise ArchiveError("ship commit member lines must name each locked member at its FINAL.md reviewed HEAD")
+    return rows
+
+
 def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
@@ -2030,16 +2091,18 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
         )
     require_committed_carry_forward(project, configured, archive, ship_commit)
 
+    members = member_ship_rows(project, archive, ship_commit)
     ship_parent = require_git_success(run_git(project, "rev-parse", f"{ship_commit}^"), "resolve ship parent")
-    if reviewed_head != ship_parent:
+    if not reviewed_head_covers(project, reviewed_head, ship_parent):
         raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}"
+            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
+            f"{_common.RUNTIME_PIN_ALLOWANCE}"
         )
     require_canonical_commit_body(
         project,
         ship_commit,
         ship_subject(archive.name),
-        ship_commit_body(configured, reviewed_head),
+        ship_commit_body(configured, reviewed_head, members),
         "ship",
     )
 
@@ -2077,7 +2140,10 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
             + f"; run: git -C {project} revert <commits after {ship_commit[:12]} that touch .project>"
         )
 
-    return {"archive": configured, "commit": ship_commit}
+    result = {"archive": configured, "commit": ship_commit}
+    if members:
+        result["members"] = members
+    return result
 
 
 def parser() -> argparse.ArgumentParser:
@@ -2119,6 +2185,12 @@ def parser() -> argparse.ArgumentParser:
     )
     refresh_parser.add_argument("--repo", required=True, type=Path)
 
+    close_members_parser = subparsers.add_parser(
+        "close-members",
+        help="after preflight, integrate each locked member in lock order before the ship commit",
+    )
+    close_members_parser.add_argument("--repo", required=True, type=Path)
+
     integrate_parser = subparsers.add_parser(
         "integrate",
         help="resume and publish the shipped milestone integration",
@@ -2139,7 +2211,7 @@ def parser() -> argparse.ArgumentParser:
 def main(argv: Optional[Sequence[str]] = None) -> int:
     arguments = parser().parse_args(argv)
     try:
-        if arguments.command in {"validate-integrated", "refresh-origin", "integrate"}:
+        if arguments.command in {"validate-integrated", "refresh-origin", "integrate", "close-members"}:
             if __package__:
                 from . import integration
             else:
@@ -2156,6 +2228,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             result = integration.validate_integrated(arguments.repo, arguments.slug)
         elif arguments.command == "refresh-origin":
             result = integration.refresh_origin(arguments.repo)
+        elif arguments.command == "close-members":
+            result = integration.close_members(arguments.repo)
         elif arguments.command == "integrate":
             result = integration.integrate(arguments.repo, arguments.slug)
         else:

package/skills/gsd-path-research/scripts/build_recovery.py

@@ -1,5 +1,5 @@
 # gsd-path project runtime
-"""Guard a blocked build's return to Define or Plan using its committed base."""
+"""Guard return to Define or Plan using a committed recovery base."""
 
 from __future__ import annotations
 
@@ -17,7 +17,9 @@ EVENTS = {
     "define": "build intent corrections requested",
     "plan": "build plan repair requested",
 }
+PLAN_INTENT_EVENT = "plan intent corrections requested"
 MARKER = "build recovery: "
+RECOVERY_KEYS = frozenset({"base", "branch", "kind", "source"})
 
 
 def runtime():
@@ -36,9 +38,42 @@ def checkpoint_runtime():
     return state_checkpoint
 
 
+def _parse_recovery_record(value: object) -> dict:
+    if (
+        not isinstance(value, dict)
+        or not {"base", "branch", "kind"}.issubset(value)
+        or not set(value).issubset(RECOVERY_KEYS)
+        or not isinstance(value["base"], str)
+        or not re.fullmatch(r"[0-9a-f]{40}", value["base"])
+    ):
+        raise runtime().PipelineStateError("invalid build recovery record")
+    source = value.get("source", "build")
+    if source not in {"build", "plan"}:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    if source == "plan":
+        if value["kind"] != "define":
+            raise runtime().PipelineStateError("invalid build recovery record")
+    elif value["kind"] not in EVENTS:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    return {**value, "source": source}
+
+
+def _recovery_base_proves_milestone(before, current, source: str) -> bool:
+    if before.branch != current.branch or before.milestone != current.milestone:
+        return False
+    if source == "plan":
+        return (before.phase, before.status) in {("plan", "active"), ("plan", "blocked")}
+    return (before.phase, before.status) == ("build", "blocked")
+
+
 def context(repo: Path, text: str | None = None) -> dict | None:
     state = runtime()
-    current, loaded, _ = state.load_state(repo)
+    try:
+        current, loaded, _ = state.load_state(repo)
+    except state.PipelineStateError as error:
+        if "STATE.md must be a real file" not in str(error):
+            raise
+        return None
     text = loaded if text is None else text
     recovery = None
     for line in text.splitlines():
@@ -47,26 +82,24 @@ def context(repo: Path, text: str | None = None) -> dict | None:
         event = line.split(" — ", 2)[-1]
         if event.startswith(MARKER):
             try:
-                value = json.loads(event[len(MARKER):])
+                value = _parse_recovery_record(json.loads(event[len(MARKER):]))
             except ValueError as error:
                 raise state.PipelineStateError("invalid build recovery record") from error
-            if (not isinstance(value, dict) or set(value) != {"base", "branch", "kind"}
-                    or value["kind"] not in EVENTS
-                    or not isinstance(value["base"], str)
-                    or not re.fullmatch(r"[0-9a-f]{40}", value["base"])):
-                raise state.PipelineStateError("invalid build recovery record")
             recovery = {**value, "active": True} if value["branch"] == current.branch else None
-        elif event == "build started" and recovery:
-            recovery["active"] = False
+        elif recovery and recovery.get("active"):
+            source = recovery.get("source", "build")
+            if source == "build" and event == "build started":
+                recovery["active"] = False
+            elif source == "plan" and event == "plan approved":
+                recovery["active"] = False
     if recovery:
         if not state._is_ancestor(repo, recovery["base"], "HEAD"):
             raise state.PipelineStateError("build recovery base is not an ancestor of HEAD")
-        source = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
-        if source is None:
+        base_text = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
+        if base_text is None:
             raise state.PipelineStateError("build recovery base has no STATE.md")
-        before = state._state_from_text(source)
-        if ((before.phase, before.status) != ("build", "blocked")
-                or before.branch != current.branch or before.milestone != current.milestone):
+        before = state._state_from_text(base_text)
+        if not _recovery_base_proves_milestone(before, current, recovery.get("source", "build")):
             raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
     return recovery
 
@@ -90,6 +123,8 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
         raise state.PipelineStateError("build recovery requires real task artifacts")
     tasks = {}
     for path in sorted(directory.iterdir()):
+        if state._common.is_ignored_junk(path):
+            continue
         if not re.fullmatch(r"T[0-9]{3}-[a-z0-9][a-z0-9-]*\.md", path.name):
             raise state.PipelineStateError(f"invalid recovery task path: {path.name}")
         text = state._read_real_file(path, path.name)
@@ -106,18 +141,20 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
     return tasks
 
 
-def begin(repo: Path, before, after, event: str) -> dict:
+def _begin_common(repo: Path, before, event: str) -> str:
     state = runtime()
-    if (before.phase, before.status) != ("build", "blocked") or after.phase not in EVENTS:
-        raise state.PipelineStateError("build recovery requires build/blocked")
-    if event != EVENTS[after.phase]:
-        raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
     if before.archive is not None or before.branch != state._current_branch(repo):
         raise state.PipelineStateError("build recovery requires the active bound branch")
     if state._worktree_changes(repo):
         raise state.PipelineStateError("checkpoint the blocked build before recovery")
     if any(state.transaction_journals(repo).values()):
         raise state.PipelineStateError("finish pending transactions before build recovery")
+    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
+    return state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _settle_build_dispatch(repo: Path) -> None:
+    state = runtime()
     records = records_root(repo)
     for directory in {path.parent.parent for path in records.rglob("attempt-*/state.json")}:
         latest = max(directory.glob("attempt-*/state.json"), key=lambda path: int(path.parent.name.split("-")[1]))
@@ -126,19 +163,49 @@ def begin(repo: Path, before, after, event: str) -> dict:
                 or (record.get("worktree") and record.get("branch") and not record.get("cleanup_complete"))
                 or record.get("outcome") not in {"landed", "collected", "blocked", "resolved", "redispatched"}):
             raise state.PipelineStateError(f"settle dispatch records before recovery: {latest}")
-    tasks = settled_tasks(repo)
-    state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
-    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
-    base = state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _verify_done_tasks(repo: Path, tasks: dict[str, tuple[str, dict]], base: str) -> None:
+    state = runtime()
     done = [repo / ".project/tasks" / name for name, (_, fields) in tasks.items()
             if fields["status"] == "done"]
-    if done:
-        if __package__:
-            from scripts.isolation import verify_landed_task_files
-        else:
-            from isolation import verify_landed_task_files
-        verify_landed_task_files(repo, done, ".project/tasks", base)
-    return {"kind": after.phase, "base": base, "branch": before.branch}
+    if not done:
+        return
+    if __package__:
+        from scripts.isolation import verify_landed_task_files
+    else:
+        from isolation import verify_landed_task_files
+    verify_landed_task_files(repo, done, ".project/tasks", base)
+
+
+def begin(repo: Path, before, after, event: str) -> dict:
+    state = runtime()
+    if (before.phase, before.status) == ("build", "blocked") and after.phase in EVENTS:
+        if event != EVENTS[after.phase]:
+            raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
+        _settle_build_dispatch(repo)
+        tasks = settled_tasks(repo)
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": after.phase, "base": base, "branch": before.branch, "source": "build"}
+    if (
+        before.phase == "plan"
+        and before.status in {"active", "blocked"}
+        and (after.phase, after.status) == ("define", "active")
+    ):
+        if event != PLAN_INTENT_EVENT:
+            raise state.PipelineStateError(f"state transition requires event: {PLAN_INTENT_EVENT}")
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        tasks_dir = repo / ".project/tasks"
+        tasks = settled_tasks(repo) if tasks_dir.is_dir() and any(
+            path.is_file() and not state._common.is_ignored_junk(path)
+            for path in tasks_dir.iterdir()
+        ) else {}
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": "define", "base": base, "branch": before.branch, "source": "plan"}
+    raise state.PipelineStateError("build recovery requires build/blocked")
 
 
 def records_root(repo: Path) -> Path:
@@ -165,7 +232,8 @@ def validate_review_backup(repo: Path, recovery: dict, directory: Path) -> None:
         if path:
             expected[str(Path(path).relative_to(".project/review"))] = checkpoint_runtime()._git_text_at(repo, recovery["base"], path)
     actual = {str(path.relative_to(directory)): path.read_text(encoding="utf-8")
-              for path in directory.rglob("*") if path.is_file()} if directory.exists() else {}
+              for path in directory.rglob("*")
+              if path.is_file() and not state._common.is_ignored_junk(path)} if directory.exists() else {}
     if actual != expected:
         raise state.PipelineStateError("review backup differs from the recovery base")