@opengsd/gsd-path 1.5.0 → 1.6.1

package/skills/gsd-path-docs-audit/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/skills/gsd-path-docs-audit/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-docs-audit/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]