@opengsd/gsd-path 1.5.0 → 1.6.1

package/RUNTIME.md

@@ -23,7 +23,7 @@ inputs, receipt handling, and entry conditions are owned by the
 | `gate-plan` | Git HEAD; optional lookahead project directory | Pending discussion, intent coverage, brief paths, and panel configuration checked in order. |
 | `approve-plan` | Owner approval and `--expected-head <reviewed full SHA>` | Plan gates followed by the existing journaled approval checkpoint. |
 | `lint-round` | Git HEAD; optional `--project-dir .project/next` | Task brief checks against HEAD, then plan handoff checks. |
-| `prepare-task` | `--expected-head <clean base> --task-id <id> --round-size <ready task count>` | Canonical task isolation; serial work also gets a verification sidecar before the primary becomes dirty. |
+| `prepare-task` | `--expected-head <clean base> --task-id <id> --round-size <ready task count>` | Canonical task isolation; serial work also gets a verification sidecar before the primary becomes dirty. A verification sidecar that an earlier `prepare-task` left for the task is retired first only when it is proven untouched: its branch did not move from its creation base on the bound branch, and it has no tracked change and no untracked or gitignored file. Any other sidecar stays, and the command stops with its path and what was found. |
 | `build-evidence` | `--expected-head <full SHA>` | Canonical landing proof written to `<project-dir>/build/evidence.json` (default: `.project/build/evidence.json`). |
 
 Plan approval recovery remains `pipeline_state.py resume-checkpoint`. Pre-Git
@@ -68,7 +68,7 @@ skeptic attempts under `skeptics/`.
 | `skeptics --repo <root> --wave <N> --cycle <C> --child-command '<cmd>' [--wait <s>] [--child-timeout <s>]` | Step 7 skeptic branch: one read-only skeptic per `skeptic_groups` locator in its own sidecar at the recorded review base, briefed with the criterion, every observation, and the cited tasks verbatim; validate with `review_findings.py`, collect, retire, then rerun the helper. `none` without skeptic groups; `escalate` for structural blockers or the cycle cap. The skeptic files stay uncommitted for the fix-task or ruling checkpoint. |
 | `fix-tasks --repo <root> --wave <N> --cycle <C>` | Step 7 batching: one fix task per `review_findings.py collect` batch with the failed criteria and observations verbatim, lint-checked; `escalate` for structural blockers, skeptic groups, cycle cap, or all-refuted. |
 | `complete --repo <root>` | Completion: clean primary at `build/active` (or a crash-left `build/done`), no unfinished wave, the archive-time review cycle check (`discussion_validate.review_cycle_counts`: contiguous cycles, passing last cycle, panel and skeptic artifacts present); `workflow_run.py build-evidence` at HEAD; `pipeline_state.py transition` to `ship/active` with event `build done; final review pending`; checkpoint `build: complete milestone`. |
-| `finish --repo <root> --task-id <id>` | Recover first; return a proven landing without repeating Verify, or verify, land, record, and retire one returned task. Without a dispatch record, or when the newest record is settled and its base differs from the task's current in-progress base (a native retry after a driver block), read the primary task's in-progress state; if it lacks a recorded base, use the parallel task isolate's state only if that worktree is authorized. A blocked record at the same base still refuses the retry. A deactivated isolate stays blocked. |
+| `finish --repo <root> --task-id <id>` | Recover first; return a proven landing without repeating Verify, or verify, land, record, and retire one returned task. Without a dispatch record, or when the newest record is settled and its base differs from the task's current in-progress base (a native retry after a driver block), read the primary task's in-progress state; if it lacks a recorded base, use the parallel task isolate's state only if that worktree is authorized. A blocked record at the same base still refuses the retry, except a host-dispatched record (no child command) while the task is still in progress at that base: `finish` may run again after a failed Verify. A deactivated isolate stays blocked. |
 | `answer --repo <root> --task-id <id> --answer '<text>'` | Append `Orchestrator answer:` to the isolate's task Log; the next `round` redispatches that isolate. |
 | `status --repo <root>` | Every task's newest dispatch record. |
 
@@ -95,6 +95,13 @@ For `round`, `review`, `panel`, and `skeptics`, when the child process is gone a
 unset, the driver rereads that attempt's state and exit receipt before
 collecting the result or blocking with
 `child wrapper exited without recording a result`.
+A landing is final when the removal of its isolate fails: the receipt reports
+the task as landed with a `cleanup_warning`, and the next `round` or `finish`
+checks the isolate again. When only a leftover of a landed task's isolate
+remains and it holds nothing that Git does not have, the driver stops with
+`task <id> is landed; remove its leftover isolate: <path>`, changes neither
+STATE nor HEAD, and never deletes the path itself. Every other isolate error
+keeps its recovery block.
 Review starts from a clean base. A same-cycle retry may dispatch a missing lens
 at that unchanged base while verified, already-collected review artifacts remain
 uncommitted. Altered artifacts or unrelated changes block recovery.
@@ -127,7 +134,15 @@ with `another dispatch_driver invocation holds the lock`; wait for the
 active call to return before retrying. Bookkeeping also blocks if an
 in-progress primary task has no open dispatch record.
 
-Verify output is saved in `verify.json`. A `verify-record` ledger entry is
+Verify output is saved in `verify.json`. `finish` also runs the Verify of each
+earlier-wave task that shares a file with the task, under the
+[wave loop](skills/gsd-path/references/build-native.md#wave-loop) rule; those
+runs are saved under `regressions` and a failure blocks the landing. A Verify
+that a `supersedes` field retires does not run; it is listed under `retired`. A fix
+task Verify that loses only the copy of a retired Verify has a `retired` entry with
+the key `part` (the superseded task) and the Log entry `orchestrator regression
+Verify of <fix task id>: part of <task id> retired: superseded by <task id>`. A task
+with a `Heavy: yes` regression Verify counts as heavy. A `verify-record` ledger entry is
 written only when the landing commit's parent equals the recorded task base;
 a later parallel landing can therefore have no ledger entry.
 
@@ -174,8 +189,11 @@ through its receipt only when the canonical file matches the saved hash.
 
 `fix-tasks` reconciles existing repair tasks and PLAN rows before linting and
 checkpointing. It creates missing batches in an appended repair wave and
-reports new tasks in `created`, reused tasks in `existing`, and batches already
-covered by other repair tasks in `carried`. Status `created` includes restored
+reports new tasks in `created`, reused tasks in `existing`, and batches that
+other repair tasks not yet `done` cover in the same repo in `carried`. A member
+batch and its task carry `repo`. A fix task for a finding that repeats after
+its fix landed also depends on that landed fix task, so
+`review_findings.py repair-evidence` can link the two. Status `created` includes restored
 PLAN rows or pending project bookkeeping; `exists` means nothing was written
 and no project changes needed a checkpoint. Status `none` means no batches
 need work; `escalate` leaves the named decisions with build step 7 and the user.

package/UPDATE.md

@@ -273,6 +273,41 @@ Unrecognized or foreign `.project/` state is never auto-migrated — the router
 
 ---
 
+## Uninstall skills
+
+```bash
+npx @opengsd/gsd-path@latest --uninstall --all --dry-run
+npx @opengsd/gsd-path@latest --uninstall --all
+```
+
+From a git clone, use `node scripts/install.mjs` with the same flags.
+
+- Select the hosts with host flags or `--all`. A selection is necessary.
+- Add `--local`, from the project directory, for project-local skills.
+- `--dry-run` lists each path and removes nothing. A real run lists each
+  removed path.
+- A host that has no GSD Path skills shows `nothing to remove`. This is not an
+  error. A second run removes nothing.
+
+**Removed:** skill directories that GSD Path owns, and Cursor's
+`agents/gsd-path.md`. A directory is owned when it has a GSD Path name
+(`gsd-path`, `gsd-path-*`, the legacy `ogsd` names, or the `path` alias) and
+contains a `VERSION` file or a `SKILL.md` that names `gsd-path`. The `path`
+alias must also pass the ownership rule in
+[What auto-updates](#what-auto-updates). A directory with a GSD Path name
+that is not owned shows as `kept` and stays in place.
+
+**Not removed:** other skills, host settings, `disabled-gsd-skills` backups,
+and all project files: `.project/`, `.gsd-path/`, the `AGENTS.md` block, and
+guard hooks. `--uninstall` with `--project`, `--update`, `--doctor`, or a hook
+or runtime flag stops with an error.
+
+Removal makes no backup. Changes that you made in a GSD Path skill directory
+are lost. Codex, Zed, and Muse use one skills root (with `--local`, also
+Antigravity): an uninstall for one of them removes the skills for all of them.
+
+---
+
 ## Troubleshooting
 
 | Symptom | Fix |

package/WORKFLOW.md

@@ -161,7 +161,8 @@ Owned state routes by STATE.md without rerunning the helper. Reserve `classify`
 for read-only inspection; do not re-derive a verdict from a directory listing.
 
 For a newly initialized existing Git repository, the state router returns
-`bind-initial` while `STATE.branch` is null. The router fetches `origin/main`,
+`bind-initial` while `STATE.branch` is null. The router fetches the recorded
+[default branch](#default-branch) (`origin/main` in this document),
 runs `pipeline_git.py bind-initial` with that exact SHA, and records the
 returned `gsd-path/M00N` binding through `pipeline_state.py transition` before
 entering inspect or define. Build consumes this binding and never creates or
@@ -512,7 +513,11 @@ untouched.
 One exception: a DOCS-AUDIT.md with pending `planned: no` rulings is copied
 atomically back into a recreated `research/` so the alignment queue survives;
 the archived original keeps full history. Active and archived research may
-coexist only for that byte-identical carry-forward.
+coexist only for that byte-identical carry-forward. When a lookahead track
+brings its own `research/`, `promote-next` removes the carry-forward in the
+promotion commit, but only if the lookahead DOCS-AUDIT.md keeps every
+carry-forward ruling (a pending row may gain a `T###`); otherwise promotion
+stops.
 
 Archives become read-only when committed. No phase may modify a committed
 archive; the next milestone's inspection may read it. A retry with a persisted
@@ -540,6 +545,49 @@ the subject and field body defined by its canonical phase contract; task-land
 fields live only in the
 [build contract](skills/gsd-path-build/SKILL.md).
 
+### Default branch
+
+Path ships onto the default branch of `origin`. The name is not fixed.
+`detect_project.py initialize` reads the local `refs/remotes/origin/HEAD` one
+time and records the name in `STATE.md` as `default_branch`; an unset
+`origin/HEAD` records `main`. Run `git remote set-head origin --auto` before
+the first Path run so that the record is the default branch of the forge. A
+`STATE.md` without the field means `main`, so older projects do not change.
+
+This document writes `main` and `origin/main` for the recorded default branch.
+In a project that records `master`, read them as `master` and `origin/master`:
+the integration merge subject ends with `into master`, and the user's merge
+request in `external-landing` mode targets `master`.
+
+The record does not change after initialization. Bind, integrate, validate,
+promotion, and the git guard read it. When the forge default no longer agrees
+with the record, integration stops with `remote default must be <recorded>`.
+A lookahead `next/STATE.md` must carry the same `default_branch` as the active
+state, or promotion stops. Names in the reserved `gsd-path/`,
+`gsd-path-integrate/`, and `gsd-path-task/` namespaces, and names with `#` or
+a quote character, cannot be recorded.
+
+In a multi-repo project, each repository has its own record. The coordinator
+records its default branch in `STATE.md`, as above. `members.py add` reads the
+local `refs/remotes/origin/HEAD` of the member one time and records the name
+in the member's section of `.project/MEMBERS.md`, as `Default branch: <name>`;
+an unset `origin/HEAD` records `main`. Run `git remote set-head origin --auto`
+in the member before you add it. A section without the field means `main`, so
+an older `MEMBERS.md` does not change. The members of one project can have
+different default branches, and the coordinator default can differ from them.
+The same name rules apply.
+
+Build start, the task brief check, undo, the member pre-push guard, and member
+close read the member record. The member bound branch starts at
+`origin/<recorded>`, the member merge subject ends with `into <recorded>`, and
+a member pull request targets `<recorded>`. When the remote default of the
+member no longer agrees with the record, `members.py validate` and member
+close stop with `remote default must be <recorded>`.
+
+Not supported: a new repository that Path creates uses `main`. This includes
+`members.py add --create`, which stops when the new repository has another
+default branch.
+
 ### Integration
 
 After the postcommit validator passes, ship performs integration — the only
@@ -548,14 +596,15 @@ receives merges or back-merges, and the default checkout is never entered;
 the local default branch ref may lag origin, which is harmless because
 binding resolves remote SHAs. `STATE.integration_default` stores the project
 choice and `STATE.integration` stores the current milestone choice. Both are
-`direct` or `pull-request`; they may change only before build, and the current
+`direct`, `pull-request`, or `external-landing`; they may change only before build, and the current
 milestone resets to the project default at the next handoff. Older v2 state
 without these fields means `direct`. `STATE.integration_source` is `default` or
 `milestone` so an explicit override remains distinct when its value happens to
 match the project default.
 
 Ship fetches origin, refreshes `origin/HEAD`, mirrors published milestone tags,
-and requires the remote default to be `main`. It then follows the locked mode:
+and requires the remote default to be the recorded
+[default branch](#default-branch). It then follows the locked mode:
 
 - `direct` creates a temporary named worktree (`gsd-path-integrate/M00N`) at
   the fetched remote-default SHA and merges the ship commit with `--no-ff`
@@ -567,10 +616,20 @@ and requires the remote default to be `main`. It then follows the locked mode:
 - `pull-request` requires `gh` authentication for GitHub.com and a GitHub.com
   origin. Path publishes the exact ship commit and creates or reuses the one
   eligible PR to `main` with a GSD Path credit footer. It returns
-  `awaiting-merge` until a human GitHub user merges it with a merge commit; Path
-  never enables auto-merge or merges the PR. After validation, Path creates the
-  annotated milestone tag. The [ship contract](skills/gsd-path-ship/SKILL.md)
+  `awaiting-merge` until a human GitHub user merges it with a merge commit or a
+  rebase merge; Path never enables auto-merge or merges the PR. After
+  validation, Path creates the annotated milestone tag. The [ship contract](skills/gsd-path-ship/SKILL.md)
   owns the candidate, provenance, topology, publication, and recovery rules.
+- `external-landing` is for an origin that is not GitHub.com, such as GitLab,
+  Gitea, or GitHub Enterprise Server, where a merge request is the only route
+  to `main`. It needs no forge CLI. Path publishes the bound branch at the
+  exact ship commit, does not push `main`, and returns `awaiting-merge` with
+  the required merge subject and body. You open the merge request in your
+  forge (for example with `glab`), let your pipeline run, and merge it with a
+  merge commit that has exactly that message. Do not squash, rebase, or
+  fast-forward. Your forge may delete the source branch after the merge. On
+  the next ship invocation, Path validates the two-parent merge on `main` and
+  creates the annotated milestone tag.
 
 Ship leaves the primary worktree and `STATE.branch` on the shipped local
 `gsd-path/M00N`; the router owns the later branch handoff. NNN always comes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Disk-backed AI agent pipeline. Docs: DOCS.md (start here), QUICK.md, FULL.md, UPDATE.md",
   "license": "MIT",
   "repository": {

package/scripts/_common.py

@@ -25,7 +25,8 @@ import signal
 import subprocess
 import time
 from pathlib import Path
-from typing import BinaryIO, Iterator, List, Optional, Sequence
+from typing import BinaryIO, Iterable, Iterator, List, Optional, Sequence, Tuple
+
 
 # Chosen by what imports, not os.name, so tests can emulate Windows on POSIX.
 try:
@@ -161,6 +162,33 @@ def project_ignore_error(repo: Path) -> Optional[str]:
             + ". Anchor the product rule (for example `/build/`) in a task that owns it.")
 
 
+_DEFAULT_BRANCH_RE = re.compile(
+    r"[^\s#\"'\\~^:?*\[\x00-\x1f\x7f-][^\s#\"'\\~^:?*\[\x00-\x1f\x7f]*"
+)
+_RESERVED_BRANCH_PREFIXES = ("gsd-path/", "gsd-path-integrate/", "gsd-path-task/")
+
+
+def valid_default_branch(name: str) -> bool:
+    """A git branch name that STATE frontmatter can hold and Path does not reserve."""
+    return (
+        bool(_DEFAULT_BRANCH_RE.fullmatch(name))
+        and name != "null"
+        and not name.startswith(_RESERVED_BRANCH_PREFIXES)
+        and not name.endswith(("/", ".", ".lock"))
+        and not any(part in name for part in ("..", "//", "/.", "@{"))
+    )
+
+
+def origin_default_branch(repo: Path) -> str:
+    """The origin default branch that initialization records; an unset origin/HEAD means main."""
+    result = run_git(repo, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    prefix = "refs/remotes/origin/"
+    remote_ref = result.stdout.strip()
+    if result.returncode != 0 or not remote_ref.startswith(prefix):
+        return "main"
+    return remote_ref.removeprefix(prefix)
+
+
 def section_body(text: str, heading: str) -> Optional[str]:
     """The text under `## <heading>` up to the next `## `, or None when absent."""
     match = re.search(
@@ -169,6 +197,79 @@ def section_body(text: str, heading: str) -> Optional[str]:
     return match.group("body") if match else None
 
 
+def overlapping_paths(left: Sequence[str], right: Sequence[str]) -> List[str]:
+    """Return the sorted paths that two task `files` lists both cover.
+
+    An entry covers itself and the paths below it. For a declared directory
+    and a path below it, the result names the lower path. The callers have no
+    task base, so this does not ask if an entry is a file: the task-brief
+    lint rejects a path below a file at the base.
+    """
+    return sorted(
+        {
+            max(one, other, key=len)
+            for one in left
+            for other in right
+            if one == other or one.startswith(other + "/") or other.startswith(one + "/")
+        }
+    )
+
+
+# The `- ` of an indented sub-bullet line. A line that would then read as a
+# numbered item (`- 2. text`) keeps its marker, so both readings of a source
+# have the same criteria.
+SUB_BULLET_MARKER = re.compile(r"(?m)^([ \t]+)-[ \t]+(?![ \t]*\d+\.\s)")
+
+
+def without_sub_bullet_markers(source: str) -> str:
+    """`source` with the `- ` marker of each indented sub-bullet line removed."""
+    return SUB_BULLET_MARKER.sub(r"\1", source)
+
+
+class Criterion(str):
+    """A criterion as its parser joins it, with the `- ` markers of its sub-bullet lines.
+
+    `bare` is the same criterion parsed from `without_sub_bullet_markers(source)`.
+    The joined text cannot tell a marker from a minus sign; the source lines can.
+    """
+
+    bare: str
+
+    def __new__(cls, text: str, bare: str) -> "Criterion":
+        criterion = super().__new__(cls, text)
+        criterion.bare = bare
+        return criterion
+
+
+def quotes_criterion(quote: str, criterion: str) -> bool:
+    """Whether a review quote is `criterion`, for every reader.
+
+    Only whitespace is collapsed. The quote must equal the criterion with all
+    the markers of its sub-bullet lines or with none of them; every other
+    character, a hyphen inside a line too, is compared.
+    """
+    forms = (criterion, getattr(criterion, "bare", criterion))
+    return " ".join(quote.split()) in {" ".join(form.split()) for form in forms}
+
+
+def quoted_criterion(item: str, criteria: Sequence[str]) -> Optional[Tuple[int, int]]:
+    """Index of the criterion quoted at the start of `item`, and where the quote ends.
+
+    A criterion can contain ` — ` itself, so each separator and the end of
+    `item` is a candidate, the longest quote first. A criterion as written
+    wins over any criterion read without its sub-bullet markers.
+    """
+    ends = [match.start() for match in re.finditer("(?= —(?: |$))|$", item)][::-1]
+    for bare in (False, True):
+        for end in ends:
+            quote = " ".join(item[:end].split())
+            for index, criterion in enumerate(criteria):
+                form = getattr(criterion, "bare", criterion) if bare else criterion
+                if quote == " ".join(form.split()):
+                    return index, end
+    return None
+
+
 def task_verify_command(task_text: str) -> str:
     """The Verify shell text, excluding the closing fence's separator newline."""
     body = section_body(task_text, "Verify")
@@ -176,6 +277,11 @@ def task_verify_command(task_text: str) -> str:
     return block.group("block").removesuffix("\n") if block else ""
 
 
+def fix_verify(commands: Iterable[str]) -> str:
+    """The Verify of a fix task: each distinct source Verify in its own subshell, under `set -e`."""
+    return "set -e\n" + "\n".join(f"(\n{command}\n)" for command in dict.fromkeys(commands))
+
+
 def latest_verify_entry(entries: list, command: str, commit: str,
                         repo: Optional[str] = None) -> Optional[dict]:
     """Rows are keyed by (command, repo, commit); a row without `repo` is a coordinator row."""
@@ -255,6 +361,49 @@ def run_git(
     return _run_exact(git_command(repo, *arguments), input=input)
 
 
+def _patch_ids(repo: Path, commits: Sequence[str]) -> list[Optional[str]]:
+    """`git patch-id --stable` per commit, in order; None for an empty commit."""
+    log = run_git(repo, "log", "--no-walk=unsorted", "-p", "--binary", "--no-color",
+                  "--no-ext-diff", *commits)
+    if log.returncode != 0:
+        raise ValueError("could not read commit patches")
+    ids = run_git(repo, "patch-id", "--stable", input=log.stdout)
+    if ids.returncode != 0:
+        raise ValueError("could not compute patch ids")
+    by_commit = {commit: patch for patch, commit in (line.split() for line in ids.stdout.splitlines())}
+    return [by_commit.get(commit) for commit in commits]
+
+
+def rebase_landing_problem(repo: Path, ship: str, landing: str) -> Optional[str]:
+    """Why landing is not a forge rebase merge of ship, or None when it is (#418).
+
+    A rebase merge replays ship's own commits onto the default branch. Proof:
+    the first-parent run that ends at landing has one non-merge commit per
+    non-merge commit of landing..ship, with equal patch ids in the same order;
+    when that run starts at ship's fork point, landing's tree equals ship's.
+    """
+    listed = run_git(repo, "rev-list", "--reverse", "--topo-order", "--no-merges", f"{landing}..{ship}")
+    if listed.returncode != 0:
+        return "could not list the ship commits"
+    originals = listed.stdout.split()
+    if not originals:
+        return "landing already contains the ship commit"
+    walked = run_git(repo, "rev-list", "--first-parent", "--parents", "-n", str(len(originals)), landing)
+    rows = [line.split() for line in walked.stdout.splitlines()][::-1]
+    if walked.returncode != 0 or len(rows) != len(originals) or any(len(row) != 2 for row in rows):
+        return "landing is not a linear run of rebased commits"
+    try:
+        if _patch_ids(repo, originals) != _patch_ids(repo, [row[0] for row in rows]):
+            return "rebased commits do not replay the ship commits in order"
+    except ValueError as error:
+        return str(error)
+    fork = run_git(repo, "merge-base", ship, landing).stdout.strip()
+    trees = run_git(repo, "rev-parse", f"{ship}^{{tree}}", f"{landing}^{{tree}}").stdout.split()
+    if rows[0][1] == fork and (len(trees) != 2 or trees[0] != trees[1]):
+        return "rebased tree differs from the ship tree"
+    return None
+
+
 def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
     """Git argv for repo, including WSL drvfs workarounds when needed."""
     return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)

package/scripts/build_recovery.py

@@ -22,6 +22,10 @@ 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():
     if __package__:
         from scripts import pipeline_state
@@ -58,8 +62,17 @@ def _parse_recovery_record(value: object) -> dict:
     return {**value, "source": source}
 
 
-def _recovery_base_proves_milestone(before, current, source: str) -> bool:
-    if before.branch != current.branch or before.milestone != current.milestone:
+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")}
@@ -99,7 +112,9 @@ def context(repo: Path, text: str | None = None) -> dict | None:
         if base_text is None:
             raise state.PipelineStateError("build recovery base has no STATE.md")
         before = state._state_from_text(base_text)
-        if not _recovery_base_proves_milestone(before, current, recovery.get("source", "build")):
+        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
 
@@ -289,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 unchanged_waves(repo: Path, recovery: dict) -> set[int]:
-    """Reuse evidence only when its intent, wave contract, and task bytes match."""
+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 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: