@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/path/scripts/review_panel.py

@@ -15,6 +15,9 @@ import argparse
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Iterable, Optional, Sequence
 
@@ -214,6 +217,7 @@ def resolve_panel(
     advertised: Sequence[str],
     parent_family: Optional[str] = None,
     parent_slug: Optional[str] = None,
+    excluded_families: Sequence[str] = (),
 ) -> dict:
     inferred_parent = parent_family or (
         family_of_slug(parent_slug) if parent_slug else None
@@ -244,7 +248,12 @@ def resolve_panel(
             "named review_panel families are not advertised: " + ", ".join(missing)
         )
 
+    if config["mode"] == "named" and set(wanted) & set(excluded_families):
+        raise ReviewPanelError("named review_panel must use an independent family")
     for family in wanted:
+        if family in excluded_families:
+            skipped.append({"family": family, "reason": "excluded reviewer family"})
+            continue
         if family == inferred_parent:
             skipped.append({"family": family, "reason": "parent family"})
             continue
@@ -488,6 +497,7 @@ def parser() -> argparse.ArgumentParser:
     result.add_argument("--advertised", default="")
     result.add_argument("--parent-family")
     result.add_argument("--parent-slug")
+    result.add_argument("--exclude-family", action="append", choices=KNOWN_FAMILIES, default=[])
     result.add_argument("--kind", choices=("plan", "wave"))
     result.add_argument("--inputs", default="")
     result.add_argument("--output", type=Path)
@@ -541,6 +551,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             split_csv(arguments.advertised),
             arguments.parent_family,
             arguments.parent_slug,
+            arguments.exclude_family,
         )
         return emit(resolved)
     except ReviewPanelError as error:

package/skills/path/scripts/roadmap.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Interpret Roadmap text for selection, approval, promotion and milestone close."""
+from __future__ import annotations
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import re
+from typing import Optional
+
+
+class RoadmapError(RuntimeError):
+    pass
+
+
+class NoEligibleMilestone(RoadmapError):
+    pass
+
+
+ROADMAP_HEADING_RE = re.compile(r"^### (M\d{3,}) — (.+)$")
+STRICT_HEADING_RE = re.compile(r"^### (M\d{3,}) — ([a-z0-9][a-z0-9-]*)\s*$")
+MUTABLE_ROADMAP_FIELDS_RE = re.compile(r"^(Status|Archive|Integrated):")
+
+def normalized_slug(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug or "project"
+
+def roadmap_blocks(content: str) -> list[dict]:
+    lines = content.splitlines(keepends=True)
+    headings = []
+    for index, line in enumerate(lines):
+        match = ROADMAP_HEADING_RE.fullmatch(line.rstrip("\r\n"))
+        if match:
+            headings.append((index, match.group(1), match.group(2).strip()))
+    blocks = []
+    for position, (start, milestone_id, title) in enumerate(headings):
+        end = headings[position + 1][0] if position + 1 < len(headings) else len(lines)
+        fields = {}
+        for index in range(start + 1, end):
+            match = re.match(
+                r"^(Status|Archive|Integrated|Depends on):\s*([^#]*?)\s*(?:#.*)?$",
+                lines[index].rstrip("\r\n"),
+            )
+            if match:
+                if match.group(1) in fields:
+                    raise RoadmapError(
+                        f"roadmap milestone {milestone_id} has duplicate "
+                        f"{match.group(1)} field"
+                    )
+                fields[match.group(1)] = (index, match.group(2).strip())
+        blocks.append(
+            {
+                "id": milestone_id,
+                "title": title,
+                "start": start,
+                "end": end,
+                "fields": fields,
+            }
+        )
+    return blocks
+
+
+def milestone_block(content: str, milestone: str) -> dict:
+    normalized = normalized_slug(milestone)
+    matches = [
+        block
+        for block in roadmap_blocks(content)
+        if normalized_slug(block["title"]) == normalized
+    ]
+    if len(matches) != 1:
+        raise RoadmapError(f"ROADMAP.md must contain exactly one entry for {milestone}")
+    return matches[0]
+
+
+def dependency_ids(block: dict) -> list[str]:
+    dependencies = block["fields"].get("Depends on")
+    if dependencies is None:
+        raise RoadmapError(f"roadmap milestone {block['id']} lacks dependencies")
+    dependency_list = re.fullmatch(
+        r"\[\s*(M\d{3,}(?:\s*,\s*M\d{3,})*)?\s*\]",
+        dependencies[1],
+    )
+    if dependency_list is None:
+        raise RoadmapError(f"roadmap milestone {block['id']} has invalid dependencies")
+    return re.findall(r"M\d{3,}", dependency_list.group(1) or "")
+
+
+def next_eligible_pending(content: str, active_milestone: Optional[str] = None) -> dict:
+    blocks = roadmap_blocks(content)
+    blocks_by_id = {block["id"]: block for block in blocks}
+    if len(blocks_by_id) != len(blocks):
+        raise RoadmapError("ROADMAP.md milestone ids must be unique")
+    active_id = None
+    if active_milestone is not None:
+        active = milestone_block(content, active_milestone)
+        if active["fields"].get("Status", (-1, ""))[1] != "active":
+            raise RoadmapError(f"roadmap milestone {active_milestone} is not active")
+        active_id = active["id"]
+    for block in blocks:
+        if block["fields"].get("Status", (-1, ""))[1] != "pending":
+            continue
+        dependencies = dependency_ids(block)
+        if all(
+            dependency in blocks_by_id
+            and (
+                blocks_by_id[dependency]["fields"].get("Status", (-1, ""))[1]
+                == "shipped"
+                or dependency == active_id
+            )
+            for dependency in dependencies
+        ):
+            return block
+    raise NoEligibleMilestone("ROADMAP.md has no dependency-ready pending milestone")
+
+
+def selection_payload(selected: dict) -> dict:
+    milestone = normalized_slug(selected["title"])
+    return {
+        "status": "selected",
+        "id": selected["id"],
+        "milestone": milestone,
+        "branch": f"gsd-path/{selected['id']}",
+    }
+
+
+def select_lookahead(content: str, active_milestone: Optional[str] = None) -> dict:
+    try:
+        selected = next_eligible_pending(content, active_milestone)
+    except NoEligibleMilestone:
+        blocks = roadmap_blocks(content)
+        if blocks and all(
+            block["fields"].get("Status", (-1, ""))[1]
+            in {"shipped", "abandoned"}
+            for block in blocks
+        ):
+            return {"status": "complete"}
+        return {"status": "none"}
+    return selection_payload(selected)
+
+
+def roadmap_contract(content: str, milestone: str) -> tuple[str, ...]:
+    block = milestone_block(content, milestone)
+    lines = content.splitlines()
+    return tuple(
+        line.rstrip()
+        for line in lines[block["start"] : block["end"]]
+        if not MUTABLE_ROADMAP_FIELDS_RE.match(line)
+    )
+
+
+def compare_roadmap_entry(
+    before: str,
+    after: str,
+    milestone: str,
+    active_milestone: Optional[str] = None,
+) -> dict:
+    before_contract = roadmap_contract(before, milestone)
+    try:
+        after_contract = roadmap_contract(after, milestone)
+        selected = milestone_block(after, milestone)
+        eligible = next_eligible_pending(after, active_milestone)
+    except RoadmapError:
+        after_contract = ()
+        selected = None
+        eligible = None
+    status = (
+        "unchanged"
+        if before_contract == after_contract
+        and selected is not None
+        and eligible is not None
+        and selected["id"] == eligible["id"]
+        else "changed"
+    )
+    return {"status": status, "milestone": milestone}
+
+
+def strict_sections(text: str) -> dict[str, tuple[str, int, int]]:
+    lines = text.splitlines(keepends=True)
+    headings: list[tuple[str, str, int]] = []
+    for index, line in enumerate(lines):
+        match = STRICT_HEADING_RE.fullmatch(line.rstrip("\r\n"))
+        if match:
+            if int(match.group(1).removeprefix("M")) < 1:
+                raise RoadmapError(f"ROADMAP.md has invalid milestone id: {match.group(1)}")
+            headings.append((match.group(1), match.group(2), index))
+    sections: dict[str, tuple[str, int, int]] = {}
+    for position, (milestone_id, slug, start) in enumerate(headings):
+        end = headings[position + 1][2] if position + 1 < len(headings) else len(lines)
+        if slug in sections:
+            raise RoadmapError(f"ROADMAP.md repeats milestone slug: {slug}")
+        sections[slug] = (milestone_id, start, end)
+    return sections
+
+
+def replace_field(
+    lines: list[str],
+    start: int,
+    end: int,
+    field: str,
+    expected: set[str],
+    value: str,
+) -> None:
+    found: Optional[int] = None
+    for index in range(start, end):
+        raw = lines[index].rstrip("\r\n")
+        ending = lines[index][len(raw) :]
+        match = re.match(rf"^({re.escape(field)}:\s*)(\S+)(.*)$", raw)
+        if match is None:
+            continue
+        if found is not None:
+            raise RoadmapError(f"ROADMAP.md repeats {field} in one milestone")
+        if match.group(2) not in expected:
+            raise RoadmapError(
+                f"ROADMAP.md {field} is {match.group(2)}, expected {sorted(expected)}"
+            )
+        lines[index] = f"{match.group(1)}{value}{match.group(3)}{ending}"
+        found = index
+    if found is None:
+        raise RoadmapError(f"ROADMAP.md milestone is missing {field}")
+
+
+def milestone_status(lines: list[str], start: int, end: int) -> str:
+    values = []
+    for line in lines[start:end]:
+        match = re.fullmatch(r"Status:\s*(\S+)\s*", line.rstrip("\r\n"))
+        if match:
+            values.append(match.group(1))
+    if len(values) != 1:
+        raise RoadmapError("ROADMAP.md milestone must have one Status field")
+    return values[0]
+
+
+def activate_milestone(text: str, milestone: str) -> str:
+    sections = strict_sections(text)
+    if milestone not in sections:
+        raise RoadmapError(f"ROADMAP.md is missing selected milestone: {milestone}")
+    lines = text.splitlines(keepends=True)
+    active = [
+        slug
+        for slug, (_, start, end) in sections.items()
+        if milestone_status(lines, start, end) == "active"
+    ]
+    if active:
+        raise RoadmapError(
+            "ROADMAP.md already has an active milestone: " + ", ".join(active)
+        )
+    _, start, end = sections[milestone]
+    replace_field(lines, start, end, "Status", {"pending"}, "active")
+    return "".join(lines)
+
+
+def reslice(before: str, candidate: str, phase: str, selected: str) -> str:
+    old_blocks = roadmap_blocks(before)
+    before_lines = before.splitlines(keepends=True)
+    candidate_lines = candidate.splitlines(keepends=True)
+    for block in old_blocks:
+        status = block["fields"].get("Status", (-1, ""))[1]
+        if status not in {"active", "shipped", "abandoned"}:
+            continue
+        slug = normalized_slug(block["title"])
+        new = milestone_block(candidate, slug)
+        if status == "shipped":
+            changed = roadmap_contract(before, slug) != roadmap_contract(candidate, slug)
+        else:
+            changed = before_lines[block["start"]:block["end"]] != candidate_lines[new["start"]:new["end"]]
+        if changed:
+            raise RoadmapError(f"{status} roadmap entry changed: {slug}")
+    if phase in {"inspect", "define"}:
+        active = [b for b in roadmap_blocks(candidate) if b["fields"].get("Status", (-1, ""))[1] == "active"]
+        if len(active) != 1 or selection_payload(active[0])["milestone"] != selected:
+            raise RoadmapError("roadmap re-slice must retain the active entry")
+        return candidate
+    if not any(b["fields"].get("Status", (-1, ""))[1] == "abandoned" for b in old_blocks):
+        raise RoadmapError("post-abandon re-slice requires an abandoned milestone")
+    selection = select_lookahead(candidate)
+    if selection.get("milestone") != selected:
+        raise RoadmapError("roadmap re-slice must use the selected dependency-ready milestone")
+    return activate_milestone(candidate, selected)
+
+
+def has_questions(text: str, milestone: Optional[str] = None) -> bool:
+    """Report open questions for the active entry, or for ``milestone`` when given."""
+    lines = text.splitlines()
+    active_section: Optional[list[str]] = None
+    for index, line in enumerate(lines):
+        heading = STRICT_HEADING_RE.fullmatch(line)
+        if heading is None:
+            continue
+        if int(heading.group(1).removeprefix("M")) < 1:
+            raise RoadmapError(
+                f"ROADMAP.md has invalid milestone id: {heading.group(1)}"
+            )
+        end = next(
+            (
+                cursor
+                for cursor in range(index + 1, len(lines))
+                if STRICT_HEADING_RE.fullmatch(lines[cursor]) is not None
+            ),
+            len(lines),
+        )
+        section = lines[index:end]
+        if milestone is not None:
+            if heading.group(2) == milestone:
+                active_section = section
+            continue
+        if any(re.fullmatch(r"Status:\s*active(?:\s+#.*)?", item) for item in section):
+            if active_section is not None:
+                raise RoadmapError("ROADMAP.md has more than one active milestone")
+            active_section = section
+    if active_section is None:
+        if milestone is not None:
+            raise RoadmapError(f"ROADMAP.md is missing lookahead milestone: {milestone}")
+        raise RoadmapError("ROADMAP.md has no active milestone")
+    try:
+        start = active_section.index("Open questions") + 1
+    except ValueError as error:
+        raise RoadmapError("active roadmap milestone has no Open questions") from error
+    questions = [
+        line[2:].strip()
+        for line in active_section[start:]
+        if line.startswith("- ")
+    ]
+    return any(question.lower() != "none" for question in questions)

package/skills/path/scripts/state_checkpoint.py

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import hashlib
 import json
 import os
@@ -20,6 +25,43 @@ except ModuleNotFoundError as error:  # pragma: no cover - package imports used
     from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
 
 
+if __package__:
+    from . import roadmap
+else:
+    import roadmap
+
+if __package__:  # imported as scripts.state_checkpoint
+    from . import pipeline_state
+    from .pipeline_state import (
+        CHECKPOINT_JOURNAL_NAME,
+        CHECKPOINT_KINDS,
+        CHECKPOINT_SCHEMA,
+        PLAN_APPROVAL_SUBJECT,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        TASK_FILE_RE,
+        TASK_ID_RE,
+        ApprovedTaskContract,
+        PipelineState,
+        PipelineStateError,
+    )
+else:  # standalone script or sibling import
+    import pipeline_state
+    from pipeline_state import (
+        CHECKPOINT_JOURNAL_NAME,
+        CHECKPOINT_KINDS,
+        CHECKPOINT_SCHEMA,
+        PLAN_APPROVAL_SUBJECT,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        TASK_FILE_RE,
+        TASK_ID_RE,
+        ApprovedTaskContract,
+        PipelineState,
+        PipelineStateError,
+    )
+
+
 def _sha256(content: str) -> str:
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
@@ -65,41 +107,29 @@ def _checkpoint_artifact_digest(project: Path, mutable_paths: set[str]) -> str:
     return digest.hexdigest()
 
 
-def _roadmap_status(lines: list[str], start: int, end: int) -> str:
-    values = []
-    for line in lines[start:end]:
-        match = re.fullmatch(r"Status:\s*(\S+)\s*", line.rstrip("\r\n"))
-        if match:
-            values.append(match.group(1))
-    if len(values) != 1:
-        raise PipelineStateError("ROADMAP.md milestone must have one Status field")
-    return values[0]
-
-
 def _activate_roadmap_milestone(text: str, milestone: str) -> str:
-    sections = pipeline_state._roadmap_sections(text)
-    if milestone not in sections:
-        raise PipelineStateError(f"ROADMAP.md is missing selected milestone: {milestone}")
-    lines = text.splitlines(keepends=True)
-    active = [
-        slug
-        for slug, (_, start, end) in sections.items()
-        if _roadmap_status(lines, start, end) == "active"
-    ]
-    if active:
-        raise PipelineStateError(
-            "ROADMAP.md already has an active milestone: " + ", ".join(active)
-        )
-    _, start, end = sections[milestone]
-    pipeline_state._replace_roadmap_field(lines, start, end, "Status", {"pending"}, "active")
-    return "".join(lines)
-
+    try:
+        return roadmap.activate_milestone(text, milestone)
+    except roadmap.RoadmapError as error:
+        raise PipelineStateError(str(error)) from error
 
 def _approval_details(
     kind: str,
     state: PipelineState,
     selected_milestone: Optional[str],
 ) -> tuple[dict[str, Optional[str]], str, str, str]:
+    if kind == "roadmap-reslice":
+        if state.status != "active" or state.archive is not None:
+            raise PipelineStateError("roadmap re-slice requires active, unarchived state")
+        if state.phase in {"inspect", "define"} and selected_milestone == state.milestone and state.milestone:
+            changes = {}
+            event = "program roadmap re-slice approved"
+        elif state.phase == "roadmap" and state.milestone is None and selected_milestone and SLUG_RE.fullmatch(selected_milestone):
+            changes = {"phase": "inspect", "milestone": selected_milestone}
+            event = "roadmap approved after abandoned milestone"
+        else:
+            raise PipelineStateError("roadmap re-slice must preserve the active milestone or select after abandon")
+        return changes, event, "roadmap: program roadmap approved", "Why: approved roadmap checkpoint"
     if kind == "plan":
         if selected_milestone is not None:
             raise PipelineStateError("plan approval does not accept a selected milestone")
@@ -126,6 +156,12 @@ def _approval_details(
     raise PipelineStateError(f"unsupported approval kind: {kind}")
 
 
+def _reslice_roadmap(before: str, candidate: str, state: PipelineState, selected: str) -> str:
+    try:
+        return roadmap.reslice(before, candidate, state.phase, selected)
+    except roadmap.RoadmapError as error:
+        raise PipelineStateError(str(error)) from error
+
 def _checkpoint_request_fields(
     kind: str,
     project_dir: str,
@@ -175,6 +211,10 @@ def _approval_journal(repo: Path, journal: Mapping[str, object]) -> dict[str, ob
         "roadmap_before",
         "roadmap_after",
     }
+    if journal.get("kind") == "roadmap-reslice":
+        expected_keys.add("baseline_before")
+        if not isinstance(journal.get("baseline_before"), str):
+            raise PipelineStateError("checkpoint journal has an invalid re-slice baseline")
     if set(journal) != expected_keys:
         raise PipelineStateError("checkpoint journal has invalid fields")
     if journal.get("schema") != CHECKPOINT_SCHEMA or journal.get("repo") != str(repo):
@@ -253,12 +293,14 @@ def _approval_journal(repo: Path, journal: Mapping[str, object]) -> dict[str, ob
         or journal["state_after"] != rendered
     ):
         raise PipelineStateError("checkpoint journal approval contract is invalid")
-    if str(journal["kind"]) == "roadmap":
+    if journal["kind"] in {"roadmap", "roadmap-reslice"}:
         if project_dir != ".project":
             raise PipelineStateError("roadmap approval is legal only on the active track")
         if journal["roadmap_path"] != ".project/ROADMAP.md":
             raise PipelineStateError("checkpoint journal has an invalid ROADMAP path")
-        expected_roadmap = _activate_roadmap_milestone(
+        expected_roadmap = _reslice_roadmap(
+            str(journal["baseline_before"]), str(journal["roadmap_before"]), before, str(selected),
+        ) if journal["kind"] == "roadmap-reslice" else _activate_roadmap_milestone(
             str(journal["roadmap_before"]),
             str(selected),
         )
@@ -307,6 +349,12 @@ def _resume_checkpoint_locked(
     transaction = _approval_journal(repo, journal)
     state_path = _checkpoint_file(repo, str(transaction["state_path"]), "STATE.md")
     mutable = {state_path.relative_to(project).as_posix()}
+    baseline = project / "ROADMAP.before-reslice.md" if transaction["kind"] == "roadmap-reslice" else None
+    if baseline is not None:
+        mutable.add(baseline.name)
+        if baseline.exists() or baseline.is_symlink():
+            if pipeline_state._read_real_file(baseline, "re-slice baseline") != transaction["baseline_before"]:
+                raise PipelineStateError("re-slice baseline drifted during checkpoint recovery")
     roadmap_path: Optional[Path] = None
     if transaction["roadmap_path"] is not None:
         roadmap_path = _checkpoint_file(
@@ -354,6 +402,8 @@ def _resume_checkpoint_locked(
             raise PipelineStateError("completed checkpoint has the wrong ROADMAP.md")
 
     try:
+        if baseline is not None and baseline.exists():
+            baseline.unlink()
         committed = isolation_checkpoint(
             repo,
             expected_head,
@@ -362,6 +412,8 @@ def _resume_checkpoint_locked(
             [".project"],
         )
     except IsolationError as error:
+        if baseline is not None and pipeline_state._run_git(repo, "rev-parse", "HEAD").stdout.strip() == expected_head:
+            pipeline_state._atomic_write(baseline, str(transaction["baseline_before"]))
         raise PipelineStateError(f"approval checkpoint failed: {error}") from error
     if committed.get("commit") != pipeline_state._run_git(repo, "rev-parse", "HEAD").stdout.strip():
         raise PipelineStateError("approval checkpoint returned the wrong commit")
@@ -381,6 +433,8 @@ def _resume_checkpoint_locked(
 def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if kind != "plan":
         return
+    if project_dir == ".project":
+        pipeline_state._build_recovery().validate_plan(repo)
     head = pipeline_state._run_git(repo, "rev-parse", "--verify", "HEAD", check=False)
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
@@ -476,6 +530,8 @@ def checkpoint_approval(
         state, state_before, state_path = pipeline_state.load_state(resolved, project_dir)
         changes, event, subject, body = _approval_details(kind, state, selected_milestone)
         _validate_plan_briefs(resolved, kind, project_dir)
+        if kind == "plan" and project_dir == ".project":
+            pipeline_state._build_recovery().restore_unchanged_reviews(resolved)
         expected = {
             "phase": state.phase,
             "status": state.status,
@@ -497,13 +553,18 @@ def checkpoint_approval(
         roadmap_path: Optional[Path] = None
         roadmap_before: Optional[str] = None
         roadmap_after: Optional[str] = None
-        if kind == "roadmap":
+        baseline_before = None
+        if kind in {"roadmap", "roadmap-reslice"}:
             if project_dir != ".project":
                 raise PipelineStateError("roadmap approval is legal only on the active track")
             assert selected_milestone is not None
             roadmap_path = project / "ROADMAP.md"
             roadmap_before = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
-            roadmap_after = _activate_roadmap_milestone(
+            if kind == "roadmap-reslice":
+                baseline_before = pipeline_state._read_real_file(project / "ROADMAP.before-reslice.md", "re-slice baseline")
+            roadmap_after = _reslice_roadmap(
+                baseline_before, roadmap_before, state, selected_milestone,
+            ) if kind == "roadmap-reslice" else _activate_roadmap_milestone(
                 roadmap_before,
                 selected_milestone,
             )
@@ -512,6 +573,8 @@ def checkpoint_approval(
         mutable = {state_relative}
         if roadmap_path is not None:
             mutable.add(roadmap_path.relative_to(project).as_posix())
+        if baseline_before is not None:
+            mutable.add("ROADMAP.before-reslice.md")
         journal: dict[str, object] = {
             "schema": CHECKPOINT_SCHEMA,
             "repo": str(resolved),
@@ -528,6 +591,8 @@ def checkpoint_approval(
             "roadmap_before": roadmap_before,
             "roadmap_after": roadmap_after,
         }
+        if baseline_before is not None:
+            journal["baseline_before"] = baseline_before
         pipeline_state._write_json(journal_path, journal)
         return _resume_checkpoint_locked(resolved, project, journal_path, journal)
 
@@ -576,6 +641,10 @@ def defer_approval(
     with pipeline_state._state_lock(project):
         state, state_before, state_path = pipeline_state.load_state(resolved, project_dir)
         changes, event, _, _ = _approval_details(kind, state, selected_milestone)
+        if project_dir == ".project":
+            recovery = pipeline_state._build_recovery().context(resolved, state_before)
+            if recovery and recovery["active"]:
+                raise PipelineStateError("build recovery requires a plan checkpoint")
         _validate_plan_briefs(resolved, kind, project_dir)
         if patch:
             event = "patch plan approved"
@@ -595,17 +664,25 @@ def defer_approval(
             project_dir,
             approval_kind=kind,
         )
-        if kind == "roadmap":
+        baseline = None
+        if kind in {"roadmap", "roadmap-reslice"}:
             if project_dir != ".project":
                 raise PipelineStateError("roadmap approval is legal only on the active track")
             assert selected_milestone is not None
             roadmap_path = project / "ROADMAP.md"
-            roadmap_after = _activate_roadmap_milestone(
-                pipeline_state._read_real_file(roadmap_path, "ROADMAP.md"),
-                selected_milestone,
-            )
+            roadmap_before = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
+            if kind == "roadmap-reslice":
+                baseline = project / "ROADMAP.before-reslice.md"
+                roadmap_after = _reslice_roadmap(
+                    pipeline_state._read_real_file(baseline, "re-slice baseline"),
+                    roadmap_before, state, selected_milestone,
+                )
+            else:
+                roadmap_after = _activate_roadmap_milestone(roadmap_before, selected_milestone)
             pipeline_state._atomic_write(roadmap_path, roadmap_after)
         pipeline_state._atomic_write(state_path, state_after)
+        if baseline is not None:
+            baseline.unlink()
     return {
         "schema": CHECKPOINT_SCHEMA,
         "status": "approved",
@@ -1002,38 +1079,3 @@ def _classify_plan_drift(
         "contract_paths": sorted(contract_paths),
         "reason": "; ".join(reasons) if reasons else "approval contracts and declared paths are unchanged",
     }
-
-
-# pipeline_state imports this module, so the parent is resolved after the
-# definitions above. Parent functions are looked up on the module at call time
-# so patches applied to pipeline_state stay visible here.
-if __package__:  # imported as scripts.state_checkpoint
-    from . import pipeline_state
-    from .pipeline_state import (
-        CHECKPOINT_JOURNAL_NAME,
-        CHECKPOINT_KINDS,
-        CHECKPOINT_SCHEMA,
-        PLAN_APPROVAL_SUBJECT,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        TASK_FILE_RE,
-        TASK_ID_RE,
-        ApprovedTaskContract,
-        PipelineState,
-        PipelineStateError,
-    )
-else:  # standalone script or sibling import
-    import pipeline_state
-    from pipeline_state import (
-        CHECKPOINT_JOURNAL_NAME,
-        CHECKPOINT_KINDS,
-        CHECKPOINT_SCHEMA,
-        PLAN_APPROVAL_SUBJECT,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        TASK_FILE_RE,
-        TASK_ID_RE,
-        ApprovedTaskContract,
-        PipelineState,
-        PipelineStateError,
-    )