@opengsd/gsd-path 1.5.0 → 1.6.0

package/skills/gsd-path-build/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:

package/skills/gsd-path-build/scripts/build_state.py

@@ -94,6 +94,8 @@ class Task:
     verify_heavy: bool
     repo: str = ""
     review_findings: bool = False
+    verify: str = ""
+    supersedes: Tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -248,6 +250,8 @@ def _parse_task(path: Path, relative_path: str, task_file: Optional[str] = None)
         verify_heavy=_verify_heavy(text, label),
         repo=str(fields.get("repo") or ""),
         review_findings=REVIEW_FINDINGS_HEADING in _sections(text),
+        verify=_common.task_verify_command(text),
+        supersedes=_normalize_list(fields.get("supersedes", []), f"{label} supersedes", task_ids=True),
     )
 
 
@@ -420,7 +424,8 @@ def _recovery_reports(project: Project) -> Dict[str, Mapping[str, object]]:
     return reports
 
 
-def _validate_ready_metadata(project: Project) -> None:
+def _validate_ready_metadata(project: Project) -> Dict[str, Mapping[str, object]]:
+    """Validate every task against its recovery report; return the reports by task id."""
     by_id = {task.task_id: task for task in project.tasks}
     recovery = _recovery_reports(project)
     seen_worktrees: Dict[str, str] = {}
@@ -484,12 +489,155 @@ def _validate_ready_metadata(project: Project) -> None:
             if report.get("verdict") not in LANDED_VERDICTS:
                 reason = report.get("reason", "landing commit is not proven")
                 _invalid_state(task, str(reason))
+    return recovery
 
 
 def _overlap(left: Task, right: Task) -> List[str]:
     if left.repo != right.repo:
         return []
-    return sorted(set(left.files) & set(right.files))
+    return _common.overlapping_paths(left.files, right.files)
+
+
+def _superseded(tasks: Sequence[Task], task: Task) -> Dict[str, str]:
+    """Earlier task id -> the task that replaces its behavior: this task, or a `done` task."""
+
+    return {
+        earlier: other.task_id
+        for other in tasks
+        if other.status == "done" or other.task_id == task.task_id
+        for earlier in other.supersedes
+    }
+
+
+def _held(by_id: Mapping[str, Task], task: Task) -> List[Task]:
+    """The tasks whose protective role this task inherits: each task it supersedes, through a chain."""
+
+    held: Dict[str, Task] = {}
+    pending = list(task.supersedes)
+    while pending:
+        other = by_id.get(pending.pop())
+        if other is not None and other.task_id not in held:  # a cycle ends here
+            held[other.task_id] = other
+            pending.extend(other.supersedes)
+    return [by_id[name] for name in sorted(held)]
+
+
+def _live_verify(
+    by_id: Mapping[str, Task], superseded: Mapping[str, str], source: Task
+) -> Tuple[str, Optional[str], List[Tuple[str, str]]]:
+    """The Verify of a source that still runs, or the task that retired all of it, and the drops.
+
+    The Verify of a fix task is exactly the composition that fix-tasks generates from the
+    Verify of each task in its deps, so it carries a copy of each: only the copies that are
+    not retired stay in the command. Any other Verify is one command. Each drop is
+    (superseded task, superseding task); a copy whose command a live dependency still runs
+    is not a drop.
+    """
+
+    if source.task_id in superseded:
+        return "", superseded[source.task_id], [(source.task_id, superseded[source.task_id])]
+    deps = [by_id[dependency] for dependency in source.deps if dependency in by_id]
+    if not deps or source.verify != _common.fix_verify(dep.verify for dep in deps):
+        return source.verify, None, []
+    parts = [_live_verify(by_id, superseded, dep) for dep in deps]
+    live = [command for command, retired_by, _ in parts if not retired_by]
+    dropped = list(dict.fromkeys(drop for _, _, drops in parts for drop in drops
+                                 if by_id[drop[0]].verify not in live))
+    if not live:
+        return "", parts[0][1], dropped
+    return _common.fix_verify(live), None, dropped
+
+
+def _regression_sources(
+    tasks: Sequence[Task], task: Task
+) -> List[Tuple[Task, List[str], Optional[str], str, List[Tuple[str, str]]]]:
+    """Each `done` task whose Verify protects a file of this task:
+    (source, replaced, retired_by, command, dropped).
+
+    A source is a task of an earlier wave that shares a declared file with this task. A task
+    that supersedes others inherits their role: it is also a source, in any wave, for a task
+    that shares a file with a task it holds, and `replaced` names those tasks.
+    `retired_by` names the task that supersedes the source: this task, or a `done` task. A
+    retired Verify does not run, also not as a copy in the Verify of a fix task: `command`
+    is the Verify that runs and `dropped` names each retired copy (`_live_verify`). The source still counts for the one-at-a-time
+    rule, so the superseding task never runs beside a task that shares a file of the
+    superseded task.
+    """
+
+    by_id = {other.task_id: other for other in tasks}
+    superseded = _superseded(tasks, task)
+    sources = []
+    for other in tasks:
+        if other.status != "done" or other.task_id == task.task_id:
+            continue
+        replaced = [held.task_id for held in _held(by_id, other) if _overlap(task, held)]
+        if replaced or (other.wave < task.wave and _overlap(task, other)):
+            command, retired_by, dropped = _live_verify(by_id, superseded, other)
+            sources.append((other, replaced, retired_by, command, dropped))
+    return sources
+
+
+def _landing_tasks(repo: Path, task_id: str, project_dir: str) -> Tuple[List[Task], Task]:
+    tasks = [
+        _parse_task(path, path.relative_to(repo).as_posix())
+        for path in sorted((repo / project_dir / "tasks").glob("*.md"))
+    ]
+    task = next((item for item in tasks if item.task_id == task_id), None)
+    if task is None:
+        raise BuildStateError("unknown-task", f"task file is missing: {task_id}")
+    return tasks, task
+
+
+def retired_verifies(
+    repo: Path, task_id: str, project_dir: str = DEFAULT_PROJECT_DIR
+) -> List[Dict[str, str]]:
+    """Return the earlier-wave tasks whose Verify a landing of this task does not run again.
+
+    A task's plan-approved `supersedes` names them. The Verify is retired for that task, and
+    for every task that lands after that task is `done`: the Verify of the superseding task
+    then runs in its place (`regression_verifies`, key `supersedes`). A fix task whose
+    generated Verify holds only retired copies is here too. A fix task whose generated Verify
+    loses some of its copies has one entry for each, with the superseded task under `part`.
+    """
+
+    tasks, task = _landing_tasks(repo, task_id, project_dir)
+    retired: List[Dict[str, str]] = []
+    for other, _, retired_by, _, dropped in _regression_sources(tasks, task):
+        if retired_by:
+            if other.verify:
+                retired.append({"task": other.task_id, "superseded_by": retired_by})
+        else:
+            retired.extend({"task": other.task_id, "part": part, "superseded_by": by}
+                           for part, by in dropped)
+    return retired
+
+
+def regression_verifies(
+    repo: Path, task_id: str, own: str, project_dir: str = DEFAULT_PROJECT_DIR
+) -> List[Dict[str, object]]:
+    """Return the Verify commands of landed tasks that a landing of this task must also pass.
+
+    One entry per distinct command, with every source task that has it, and under
+    `supersedes` the tasks whose retired Verify it replaces for this landing. A command
+    that the task's own Verify already runs is left out: an identical command, or
+    a dependency's command when the own Verify is exactly the fix-task Verify of
+    the task's dependencies. Text that only contains a command proves nothing.
+    A retired Verify is not here, also not as a copy in the Verify of a fix task: see
+    `retired_verifies`.
+    """
+
+    tasks, task = _landing_tasks(repo, task_id, project_dir)
+    by_id = {item.task_id: item for item in tasks}
+    composed = [by_id[dependency].verify for dependency in task.deps if dependency in by_id]
+    covered = {own, *(composed if own == _common.fix_verify(composed) else ())}
+    sources: Dict[str, Dict[str, object]] = {}
+    for other, replaced, _, command, _ in _regression_sources(tasks, task):
+        if command and command not in covered:
+            entry = sources.setdefault(command, {"tasks": [], "command": command})
+            entry["tasks"].append(other.task_id)
+            if replaced:  # this Verify runs in the place of the Verify of each task it replaced
+                entry["supersedes"] = sorted({*entry.get("supersedes", ()), *replaced})
+    return list(sources.values())
 
 
 def _blocked_wave_reviews(project: Project) -> Dict[int, int]:
@@ -522,12 +670,31 @@ def _blocked_wave_reviews(project: Project) -> Dict[int, int]:
     }
 
 
+def _unreviewed_waves(project: Project, waves: Sequence[int]) -> List[int]:
+    """Return the given waves that still need a canonical review file of their own.
+
+    A repair wave is left out: the next review cycle of its source wave judges it.
+    """
+
+    review_dir = project.tasks_dir.parent / "review"
+    reviewed = {
+        wave for wave in waves
+        if all(task.review_findings for task in project.tasks if task.wave == wave)
+    }
+    if review_dir.is_dir() and not review_dir.is_symlink():
+        for path in review_dir.iterdir():
+            named = check_handoffs.WAVE_REVIEW_NAME.fullmatch(path.name)
+            if named is not None and path.is_file() and not path.is_symlink():
+                reviewed.add(int(named.group("wave")))
+    return [wave for wave in waves if wave not in reviewed]
+
+
 def ready(repo: str, project_dir: str = DEFAULT_PROJECT_DIR, *,
           allow_done: bool = False) -> Dict[str, object]:
     """Return task readiness, optionally accepting build/done for completion checks."""
 
     project = _load_project(repo, project_dir, ("active", "done") if allow_done else ("active",))
-    _validate_ready_metadata(project)
+    reports = _validate_ready_metadata(project)
     by_id = {task.task_id: task for task in project.tasks}
     unfinished_waves = sorted({task.wave for task in project.tasks if task.status != "done"})
     current_wave = unfinished_waves[0] if unfinished_waves else None
@@ -626,11 +793,31 @@ def ready(repo: str, project_dir: str = DEFAULT_PROJECT_DIR, *,
             {"wave": current_wave, "tasks": stalled},
         )
 
+    # Tasks that share a regression source land one at a time, each from the landing of the one
+    # before, so the source's Verify runs on their combined edits. A parallel round leaves the
+    # primary task file pending: a retained isolate shows that the task is already dispatched.
+    # A retired source still counts: its superseding task holds its role.
+    sources = {task.task_id: {other.task_id for other, _, _, _, _ in _regression_sources(project.tasks, task)}
+               for task in concurrent}
+    started = [task for task in selectable if reports[task.task_id].get("verdict") != "none"]
+    claimed = {source for task in active + started for source in sources[task.task_id]}
+    dispatchable = []
+    for task in selectable:
+        if task in started or not sources[task.task_id] & claimed:
+            dispatchable.append(task)
+            claimed |= sources[task.task_id]
+
     typed: Dict[str, object] = {}
     if repair_for_wave is not None:
         typed["repair_for_wave"] = repair_for_wave
     if blocked_review is not None:
         typed["blocked_review"] = blocked_review
+    # Informational: every wave below the lowest unfinished wave is all done.
+    unreviewed = _unreviewed_waves(project, sorted(
+        {task.wave for task in project.tasks if unfinished_waves and task.wave < unfinished_waves[0]}
+    ))
+    if unreviewed:
+        typed["unreviewed_waves"] = unreviewed
     return {
         "command": "ready",
         "branch": project.branch,
@@ -646,10 +833,13 @@ def ready(repo: str, project_dir: str = DEFAULT_PROJECT_DIR, *,
                 "deps": list(task.deps),
                 "files": list(task.files),
                 "task_file": task.task_file,
-                "verify_heavy": task.verify_heavy,
+                # The landing also runs each regression Verify, so a heavy one makes the task heavy.
+                "verify_heavy": task.verify_heavy
+                or any(other.verify_heavy and not retired_by
+                       for other, _, retired_by, _, _ in _regression_sources(project.tasks, task)),
                 **({"repo": task.repo} if task.repo else {}),
             }
-            for task in selectable
+            for task in dispatchable
         ],
     }
 

package/skills/gsd-path-build/scripts/check_handoffs.py

@@ -161,7 +161,8 @@ def _reject_placeholder(value: str, label: str) -> None:
     if placeholder is not None:
         raise HandoffError(
             f"{label} still contains the placeholder {placeholder.group(0)}; "
-            "replace it with the real value"
+            "replace it with the real value. A value cannot be only a placeholder; "
+            "literal text such as an HTML tag must be inside a sentence, in backticks"
         )
 
 
@@ -667,22 +668,30 @@ def _strip_comments(text: str) -> str:
     return COMMENT_PATTERN.sub("", text)
 
 
-def _numbered_items(section: str, *, continuations: bool = False) -> Dict[int, str]:
-    items: Dict[int, str] = {}
-    current = None
+def _numbered_entries(section: str, *, continuations: bool = False) -> List[Tuple[int, str]]:
+    """Each numbered item in document order; a repeated number stays a separate entry."""
+    entries: List[Tuple[int, str]] = []
+    open_item = False
     for line in _strip_comments(section).splitlines():
         match = NUMBERED_ITEM_PATTERN.fullmatch(line.strip())
         if not match:
-            if continuations and current is not None and line[:1].isspace() and line.strip():
-                items[current] += " " + line.strip()
+            if continuations and open_item and line[:1].isspace() and line.strip():
+                number, text = entries[-1]
+                entries[-1] = (number, text + " " + line.strip())
             elif line.strip():
-                current = None
+                open_item = False
             continue
-        number = int(match.group(1))
+        entries.append((int(match.group(1)), match.group(2).strip()))
+        open_item = True
+    return entries
+
+
+def _numbered_items(section: str, *, continuations: bool = False) -> Dict[int, str]:
+    items: Dict[int, str] = {}
+    for number, text in _numbered_entries(section, continuations=continuations):
         if number in items:
             raise HandoffError(f"repeated numbered item {number}")
-        items[number] = match.group(2).strip()
-        current = number
+        items[number] = text
     return items
 
 
@@ -693,7 +702,11 @@ def _success_criteria(intent: str) -> Dict[str, str]:
     expected = list(range(1, max(items) + 1))
     if sorted(items) != expected:
         raise HandoffError("INTENT.md success criteria must be contiguous from 1")
-    return {f"SC{number}": text for number, text in items.items()}
+    # Issue #392: a review can quote a criterion without the markers of its sub-bullet lines.
+    bare = _numbered_items(
+        _section(_common.without_sub_bullet_markers(intent), "Success criteria"), continuations=True
+    )
+    return {f"SC{number}": _common.Criterion(text, bare[number]) for number, text in items.items()}
 
 
 def _split_top_level_commas(value: str) -> List[str]:
@@ -1297,18 +1310,22 @@ def _normalize_ws(value: str) -> str:
 
 
 def task_review_observation(item: str, task_text: str) -> str:
-    """Separate an exact quoted acceptance criterion from its observed evidence."""
+    """Separate a quoted acceptance criterion from its observed evidence."""
     item = _normalize_ws(item)
     section = _common.section_body(task_text, "Acceptance criteria")
     if section is not None:
-        for criterion in _numbered_items(section, continuations=True).values():
-            quoted = _normalize_ws(criterion)
-            prefix = quoted + " — "
-            if item.startswith(prefix):
-                return item[len(prefix) :]
-            if item in {quoted, quoted + " —"}:
-                return ""
-    return item
+        # Issue #374: frozen landed bytes may repeat a criterion number. Only the
+        # criterion text matters here, so each repeated entry is still split
+        # from its evidence and the evidence gets the same checks.
+        criteria = [criterion for _number, criterion in _numbered_entries(section, continuations=True)]
+        quoted = _common.quoted_criterion(item, criteria)
+        if quoted is not None:
+            return item[quoted[1] + len(" — ") :]
+    # Issue #392: a quote can leave out the `- ` markers of the criterion's
+    # sub-bullet lines, so read the criteria again without them.
+    bare = _common.without_sub_bullet_markers(task_text)
+    return item if bare == task_text else task_review_observation(item, bare)
+
 
 
 def _verify_command(task_text: str) -> str:
@@ -1528,11 +1545,30 @@ def _validate_task_graph(
             if _task_wave(tasks[dependency], dependency) > wave:
                 raise HandoffError(f"{task_id} depends on later-wave {dependency}")
 
+    # `supersedes` retires the regression Verify of an earlier task: the same overlap rule selects both.
+    for task_id, text in tasks.items():
+        superseded = _strict_frontmatter(text, task_id).get("supersedes", [])
+        if (
+            not isinstance(superseded, list)
+            or any(not re.fullmatch(r"T\d{3}", item) for item in superseded)
+            or len(superseded) != len(set(superseded))
+        ):
+            raise HandoffError(f"{task_id} supersedes must be a list of different task ids, for example [T001]")
+        for earlier in superseded:
+            if earlier not in tasks:
+                raise HandoffError(f"{task_id} supersedes unknown task {earlier}")
+            if task_waves[earlier] >= task_waves[task_id]:
+                raise HandoffError(f"{task_id} supersedes {earlier}, which is not in an earlier wave")
+            if task_repos[earlier] != task_repos[task_id]:
+                raise HandoffError(f"{task_id} supersedes {earlier}, which is in another repo")
+            if not _common.overlapping_paths(task_files[earlier], task_files[task_id]):
+                raise HandoffError(f"{task_id} supersedes {earlier}, which shares no declared file with it")
+
     for index, left in enumerate(task_ids):
         for right in task_ids[index + 1 :]:
             if task_waves[left] != task_waves[right] or task_repos[left] != task_repos[right]:
                 continue
-            overlap = sorted(set(task_files[left]) & set(task_files[right]))
+            overlap = _common.overlapping_paths(task_files[left], task_files[right])
             if overlap:
                 if (
                     _task_scalar(tasks[left], left, "status") == "done"
@@ -1746,7 +1782,24 @@ def validate_roadmap(
 ) -> Dict[str, object]:
     """Validate roadmap structure and dependency ordering."""
 
-    _require_state(root, "roadmap", "active", project_dir)
+    # A milestone-boundary re-slice keeps its entering inspect or define state.
+    _require_state_one_of(
+        root,
+        {("roadmap", "active"), ("inspect", "active"), ("define", "active")},
+        project_dir,
+    )
+    if _require_pipeline(root, project_dir)["phase"] == "define":
+        if __package__:
+            from . import build_recovery
+        else:
+            import build_recovery
+        try:
+            # Define entered again after intent approval is not a boundary.
+            reopened = (build_recovery.context(root.resolve()) or {}).get("active")
+        except PipelineStateError as error:
+            raise HandoffError(str(error)) from error
+        if reopened:
+            raise HandoffError("roadmap re-slice is not legal after intent approval")
     relative = f"{project_dir}/ROADMAP.md"
     text = _read(root, relative)
     if re.search(r"(?m)^## Wave |^\|\s*Task\s*\||^Files:\s*", text):
@@ -2045,25 +2098,28 @@ def validate_wave_evidence(
     if enforce_plan_tasks:
         if reviewed_tasks != expected_tasks:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
     else:
         unknown = [task_id for task_id in reviewed_tasks if task_id not in expected_tasks]
         if unknown:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
         plan_order = [task_id for task_id in expected_tasks if task_id in reviewed_tasks]
         if reviewed_tasks != plan_order:
             raise HandoffError(
-                f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
+                f"{name} must review exactly {', '.join(expected_tasks)} in task id order"
             )
     task_verdicts = []
     for heading_index, heading in task_headings:
         task_id = heading.group("task")
         expected_title = _normalize_ws(_task_scalar(tasks[task_id], task_id, "title"))
         if _normalize_ws(heading.group("title")) != expected_title:
-            raise HandoffError(f"{name} title for {task_id} differs from task file")
+            raise HandoffError(
+                f"{name} title for {task_id} differs from task file; "
+                f"expected the exact `title:` value: {expected_title}"
+            )
         end = next(
             (
                 index
@@ -2080,7 +2136,10 @@ def validate_wave_evidence(
             if line.strip().startswith(f"- {marker} ")
         ]
         if not evidence:
-            raise HandoffError(f"{name} task {task_id} lacks {verdict} evidence")
+            raise HandoffError(
+                f"{name} task {task_id} lacks {verdict} evidence; "
+                f"add a line that starts with `- {marker} ` under its heading"
+            )
         for item in evidence:
             item = task_review_observation(item, tasks[task_id])
             _non_placeholder(item, f"{name} task {task_id} {verdict} evidence")
@@ -2132,7 +2191,7 @@ def validate_wave_evidence(
             sc_id in criteria
             and (
                 not separator
-                or _normalize_ws(heading_text) != _normalize_ws(criteria[sc_id])
+                or not _common.quotes_criterion(heading_text, criteria[sc_id])
             )
         ):
             raise HandoffError(f"{name} {sc_id} heading text differs from INTENT.md")
@@ -2150,7 +2209,10 @@ def validate_wave_evidence(
             if line.strip().startswith(f"- {marker} ")
         ]
         if not evidence:
-            raise HandoffError(f"{name} {sc_id} lacks {verdict} evidence")
+            raise HandoffError(
+                f"{name} {sc_id} lacks {verdict} evidence; "
+                f"add a line that starts with `- {marker} ` under its heading"
+            )
         for item in evidence:
             _non_placeholder(item, f"{name} {sc_id} {verdict} evidence")
         verdicts[sc_id] = verdict
@@ -2230,7 +2292,7 @@ def validate_final(
     verdicts: Dict[str, str] = {}
     for index, heading in enumerate(blocks):
         sc_id = heading.group("id")
-        if _normalize_ws(heading.group("title")) != _normalize_ws(criteria[sc_id]):
+        if not _common.quotes_criterion(heading.group("title"), criteria[sc_id]):
             raise HandoffError(f"FINAL.md {sc_id} heading text differs from INTENT.md")
         end = blocks[index + 1].start() if index + 1 < len(blocks) else len(text)
         block = text[heading.end() : end]