@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/gsd-path-build/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,13 @@ 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"})
+
+
+# Only the value of a cap line is exempt; a comment or a line separator after it stays in the compared text.
+CAP_VALUE = re.compile(r"(?m)^(-[ \t]*(?:max_review_cycles|wave_budget):)[ \t\w.,$/:]*")
 
 
 def runtime():
@@ -36,9 +42,51 @@ 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, active: bool = True) -> bool:
+    if before.branch != current.branch:
+        return False
+    if before.milestone != current.milestone and (
+        # Issue #374: a legacy base records milestone null when define never
+        # named it. The owner names it at ship, after the build resumed, so
+        # only a closed build recovery accepts an unset base milestone; the
+        # bound branch already encodes M00N. A milestone named by the base
+        # must still equal the current one.
+        active or source != "build" or before.milestone is not None
+    ):
+        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 +95,26 @@ 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"), recovery["active"]
+        ):
             raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
     return recovery
 
@@ -108,18 +156,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]))
@@ -128,19 +178,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:
@@ -224,61 +304,78 @@ def validate_plan(repo: Path) -> None:
         intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
         if state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md") != intent:
             raise state.PipelineStateError("plan repair cannot change approved intent")
-    unchanged = unchanged_waves(repo, recovery)
-    for path in (repo / ".project/review").iterdir():
-        match = re.match(r"wave-([1-9]\d*)[.]", path.name)
-        if match and int(match[1]) not in unchanged:
-            raise state.PipelineStateError("changed wave must be reviewed after build resumes")
+    if stale_review_reasons(repo, recovery, _review_waves(repo / ".project/review")):
+        raise state.PipelineStateError("changed wave must be reviewed after build resumes")
+
 
+def _review_waves(directory: Path) -> set[int]:
+    return {int(match[1]) for path in directory.iterdir()
+            if (match := re.match(r"wave-([1-9]\d*)[.]", path.name))}
 
-def unchanged_waves(repo: Path, recovery: dict) -> set[int]:
-    """Reuse evidence only when its intent, wave contract, and task bytes match."""
+
+def stale_review_reasons(repo: Path, recovery: dict, waves: set[int]) -> dict[int, str]:
+    """Say why a wave's preserved review is stale; a wave not returned has matching intent, plan, and task bytes."""
     state = runtime()
     project = repo / ".project"
     old_intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
     if state._read_real_file(project / "intent/INTENT.md", "INTENT.md") != old_intent:
-        return set()
+        return dict.fromkeys(waves, "INTENT.md changed")
     old_plan = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/plan/PLAN.md") or ""
     new_plan = state._read_real_file(project / "plan/PLAN.md", "PLAN.md")
+    panel_lines = r"(?m)^-[ \t]*review_panel:.*$"
+    if re.findall(panel_lines, old_plan) != re.findall(panel_lines, new_plan):
+        return dict.fromkeys(waves, "PLAN.md `review_panel` setting changed")
 
     def sections(text):
         return {match[1]: match[2] for match in re.finditer(
             r"(?ms)^## ([^\n]+)\n(.*?)(?=^## |\Z)", text,
         )}
 
+    def governing(plan):
+        # Non-wave settings govern every wave, including coverage and surfaces. Caps only bound
+        # later work and Dependency notes are prose, so neither changes what a passed review judged.
+        return {title: CAP_VALUE.sub(r"\1", body) if title == "Config" else body
+                for title, body in plan.items()
+                if not title.startswith("Wave ") and title != "Dependency notes"}
+
     old_sections, new_sections = sections(old_plan), sections(new_plan)
-    # Non-wave settings govern every wave, including coverage and surfaces.
-    if ({k: v for k, v in old_sections.items() if not k.startswith("Wave ")}
-            != {k: v for k, v in new_sections.items() if not k.startswith("Wave ")}):
-        return set()
+    old_governing, new_governing = governing(old_sections), governing(new_sections)
+    for title in sorted(old_governing.keys() | new_governing.keys()):
+        if old_governing.get(title) != new_governing.get(title):
+            return dict.fromkeys(waves, f"PLAN.md section `{title}` changed")
     old_tasks = checkpoint_runtime()._task_contracts_at(repo, recovery["base"], ".project/tasks")
     current = settled_tasks(repo)
-    unchanged = set()
-    for title, body in new_sections.items():
-        match = re.match(r"Wave ([1-9]\d*)\b", title)
-        if not match or old_sections.get(title) != body:
+    reasons = {}
+    for wave in waves:
+        section = {title: body for title, body in new_sections.items() if re.match(rf"Wave {wave}\b", title)}
+        if not section or any(old_sections.get(title) != body for title, body in section.items()):
+            reasons[wave] = f"PLAN.md section `Wave {wave}` changed"
             continue
-        wave = match[1]
         before = {Path(path).name: text for path, text in old_tasks.values()
-                  if task_fields(text, path).get("wave") == wave}
-        after = {name: text for name, (text, fields) in current.items() if fields.get("wave") == wave}
-        if before and before == after:
-            unchanged.add(int(wave))
-    return unchanged
+                  if task_fields(text, path).get("wave") == str(wave)}
+        after = {name: text for name, (text, fields) in current.items() if fields.get("wave") == str(wave)}
+        if not before or before != after:
+            reasons[wave] = f"wave {wave} task contracts changed"
+    return reasons
 
 
-def restore_unchanged_reviews(repo: Path) -> None:
+def restore_unchanged_reviews(repo: Path) -> dict | None:
+    """Restore reusable wave reviews and report every preserved wave, so a dropped review is visible at approval."""
     recovery = context(repo)
     if not recovery or not recovery["active"]:
-        return
-    unchanged = unchanged_waves(repo, recovery)
-    for path in review_backup(repo, recovery).iterdir():
+        return None
+    backup = review_backup(repo, recovery)
+    waves = _review_waves(backup)
+    reasons = stale_review_reasons(repo, recovery, waves)
+    for path in backup.iterdir():
         match = re.match(r"wave-([1-9]\d*)[.]", path.name)
-        if match and int(match[1]) in unchanged:
+        if match and int(match[1]) not in reasons:
             destination = repo / ".project/review" / path.name
             content = path.read_text(encoding="utf-8")
             if not destination.exists() or runtime()._read_real_file(destination, destination.name) != content:
                 runtime()._atomic_write(destination, content)
+    return {"restored": sorted(waves - reasons.keys()),
+            "review_again": [{"wave": wave, "reason": reasons[wave]} for wave in sorted(reasons)]}
 
 
 def inventory_checkpoint(repo: Path, head: str) -> bool: