@opengsd/gsd-path 1.4.0 → 1.6.0

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

@@ -33,7 +33,11 @@ DISPATCH_PATTERN = re.compile(
     r"^- `(?P<dimension>[^`]+)` — (?P<status>dispatched|skipped) "
     r"→ (?P<output>[^—]+) — (?P<reason>.+)$"
 )
-QUESTION_PATTERN = re.compile(r"^- `\[RESEARCH\] (?P<question>[^`]+)` → `(?P<dimension>[^`]+)`$")
+QUESTION_PATTERN = re.compile(
+    r"^- (?P<fence>`+)(?!`)(?P<body>.+?)(?<!`)(?P=fence)(?!`) → "
+    r"(?P<dimensions>`[^`,\s]+`(?:,\s*`[^`,\s]+`)*)$"
+)
+QUESTION_PREFIX = "[RESEARCH] "
 FINDING_PATTERN = re.compile(r"^### (?P<id>P\d{3}) — (?P<title>.+)$")
 CRITERION_LOCATOR_PATTERN = re.compile(r"^SC[1-9]\d*$")
 COMMENT_PATTERN = re.compile(r"<!--.*?-->", re.DOTALL)
@@ -56,6 +60,21 @@ WAVE_REVIEW_NAME = re.compile(
     r"wave-(?P<wave>[1-9]\d*)\.cycle(?P<cycle>[1-9]\d*)"
     r"(?:\.(?P<lens>contract|adversarial))?\.md$"
 )
+VALID_REVIEW_DEPTHS = frozenset({"full", "deep", "verify-only"})
+
+
+def _max_wave_cycle(root: Path, project_dir: str, wave: int) -> int:
+    review_dir = root / PurePosixPath(project_dir) / "review"
+    if not review_dir.is_dir():
+        return 0
+    maximum = 0
+    for path in review_dir.iterdir():
+        named = WAVE_REVIEW_NAME.fullmatch(path.name)
+        if named and int(named.group("wave")) == wave:
+            maximum = max(maximum, int(named.group("cycle")))
+    return maximum
+
+
 WAVE_SC_HEADING = re.compile(r"^### (SC[1-9]\d*) — (.+)$")
 WAVE_TASK_HEADING = re.compile(
     r"^## (?P<task>T\d{3}) — (?P<title>.+): (?P<verdict>pass|fail)$"
@@ -73,6 +92,23 @@ SURFACE_HEADING = re.compile(
     r"(?m)^### (?P<surface>\S.*?) — (?P<task>T\d{3})\s*$"
 )
 SURFACE_CONTRACT_HEADING = re.compile(r"(?m)^## Surface contract\s*$")
+# Spec-reach probes (see references/spec-probes.md). The closed edge taxonomy
+# names the classic black-box categories; `none` records a criterion with no
+# data-shape edge and must be dismissed with a reason.
+EDGE_CATEGORIES = (
+    "boundary",
+    "adjacency",
+    "empty",
+    "encoding",
+    "ordering",
+    "precision",
+    "idempotency",
+    "concurrency",
+)
+EDGE_ID_PATTERN = re.compile(r"^E[1-9]\d*$")
+PROHIBITION_ID_PATTERN = re.compile(r"^N[1-9]\d*$")
+CRITERION_DISPOSITION_PATTERN = re.compile(r"^criterion\s+(SC[1-9]\d*)$")
+TABLE_SEPARATOR_PATTERN = re.compile(r"^:?-+:?$")
 GAP_NAME_PATTERN = re.compile(r"^final-gap-(?P<number>[1-9]\d*)\.md$")
 GAP_HEADING_PATTERN = re.compile(
     r"^# Gap Review — (?P<number>[1-9]\d*): (?P<risk>\S.*)$"
@@ -125,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"
         )
 
 
@@ -181,7 +218,7 @@ def _read(root: Path, relative: str) -> str:
     path = root / relative
     if not path.is_file() or path.is_symlink():
         raise HandoffError(f"missing real hand-off file: {relative}")
-    return path.read_text(encoding="utf-8")
+    return _common.read_user_text(path)
 
 
 def _require_pipeline(root: Path, project_dir: str) -> Dict[str, str]:
@@ -361,7 +398,7 @@ def _research_questions(intent: str) -> List[str]:
     ]
 
 
-def _research_assignments(section: str) -> List[Tuple[str, str]]:
+def _research_assignments(section: str) -> List[Tuple[str, List[str]]]:
     assignments = []
     lines = [line.strip() for line in section.splitlines() if line.strip()]
     if lines == ["- none"]:
@@ -372,7 +409,25 @@ def _research_assignments(section: str) -> List[Tuple[str, str]]:
         match = QUESTION_PATTERN.fullmatch(line)
         if match is None:
             raise HandoffError("RESEARCH.md has a malformed question assignment")
-        assignments.append((match.group("question").strip(), match.group("dimension")))
+        body = match.group("body")
+        fence_length = len(match.group("fence"))
+        if any(len(run) == fence_length for run in re.findall(r"`+", body)):
+            raise HandoffError("RESEARCH.md has a malformed question assignment")
+        if (
+            body.startswith(" ")
+            and body.endswith(" ")
+            and body.strip(" ")
+        ):
+            body = body[1:-1]
+        if not body.startswith(QUESTION_PREFIX):
+            raise HandoffError("RESEARCH.md has a malformed question assignment")
+        question = body[len(QUESTION_PREFIX) :]
+        if not question:
+            raise HandoffError("RESEARCH.md has a malformed question assignment")
+        dimensions = re.findall(r"`([^`]+)`", match.group("dimensions"))
+        if len(dimensions) != len(set(dimensions)):
+            raise HandoffError("RESEARCH.md repeats a target in a question assignment")
+        assignments.append((question, dimensions))
     return assignments
 
 
@@ -446,19 +501,23 @@ def validate_research_artifacts(
 
     assignments = _research_assignments(_section(handoff, "Question assignments"))
     questions = _research_questions(intent)
-    assigned_questions = [question for question, _dimension in assignments]
-    if sorted(assigned_questions) != sorted(questions):
-        raise HandoffError("RESEARCH.md question assignments do not match the intent source")
+    assigned_questions = [question for question, _dimensions in assignments]
     if len(assigned_questions) != len(set(assigned_questions)):
         raise HandoffError("RESEARCH.md repeats a question assignment")
+    if sorted(assigned_questions) != sorted(questions):
+        raise HandoffError("RESEARCH.md question assignments do not match the intent source")
     dispatched_set = set(dispatched)
-    if any(dimension not in dispatched_set for _question, dimension in assignments):
+    if any(
+        dimension not in dispatched_set
+        for _question, assigned_dimensions in assignments
+        for dimension in assigned_dimensions
+    ):
         raise HandoffError("every assigned question must target a dispatched dimension")
     for dimension in dispatched:
         dimension_questions = [
             question
-            for question, assigned_dimension in assignments
-            if assigned_dimension == dimension
+            for question, assigned_dimensions in assignments
+            if dimension in assigned_dimensions
         ]
         if not dimension_questions:
             raise HandoffError(f"dispatched {dimension} has no assigned research question")
@@ -496,7 +555,7 @@ def _field(block: str, field: str) -> str:
 
 
 def _raw_source_field(block: str, field: str, source: str) -> str:
-    matches = re.findall(rf"(?m)^- \*\*{re.escape(field)}\*\*:\s*(.*)$", block)
+    matches = _common.find_review_bullet_field_values(block.splitlines(), field)
     if not matches:
         raise HandoffError(f"{source} is missing {field}")
     if len(matches) != 1:
@@ -521,10 +580,16 @@ def _heading_block(text: str, heading: re.Match[str]) -> str:
 def _source_repair_fields(source: str, text: str, locator: str) -> Tuple[str, str]:
     if source.endswith("FINAL.md"):
         if not CRITERION_LOCATOR_PATTERN.fullmatch(locator):
-            raise HandoffError(f"{source} locator must name an SC criterion")
+            raise HandoffError(
+                f"{source} locator must be an SC<n> id; copy the id from a "
+                "criterion heading"
+            )
         heading = re.search(rf"(?m)^### {re.escape(locator)} — .+$", text)
         if not heading:
-            raise HandoffError(f"{source} does not contain locator {locator}")
+            raise HandoffError(
+                f"{source} has no criterion heading for locator {locator}; "
+                "copy an SC<n> id from a heading"
+            )
         block = _heading_block(text, heading)
         verdict = _source_field(block, "Verdict", source)
         if verdict not in {"not-met", "unverifiable"}:
@@ -532,8 +597,13 @@ def _source_repair_fields(source: str, text: str, locator: str) -> Tuple[str, st
         evidence = _source_field(block, "Finding", source)
         fix_direction = _source_field(block, "Fix direction", source)
     else:
-        if not locator.startswith("Risk: ") or locator not in text.splitlines():
-            raise HandoffError(f"{source} does not contain locator {locator}")
+        risk_lines = [line for line in text.splitlines() if line.startswith("Risk: ")]
+        if not locator.startswith("Risk: ") or locator not in risk_lines:
+            candidates = ", ".join(repr(line) for line in risk_lines) or "none found"
+            raise HandoffError(
+                f"{source} locator must equal a full 'Risk: ...' line from the "
+                f"gap review; copy one of {candidates}"
+            )
         block = _section(text, "Finding")
         evidence = _source_field(block, "Found", source)
         fix_direction = _source_field(block, "Fix direction", source)
@@ -598,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
 
 
@@ -624,7 +702,47 @@ 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]:
+    """Split on commas outside parentheses, brackets, and simple quoted strings."""
+
+    parts: List[str] = []
+    start = 0
+    depth_paren = 0
+    depth_bracket = 0
+    quote: Optional[str] = None
+    index = 0
+    while index < len(value):
+        character = value[index]
+        if quote is not None:
+            if character == quote:
+                quote = None
+            index += 1
+            continue
+        if character in {"'", '"'}:
+            quote = character
+            index += 1
+            continue
+        if character == "(":
+            depth_paren += 1
+        elif character == ")":
+            depth_paren = max(0, depth_paren - 1)
+        elif character == "[":
+            depth_bracket += 1
+        elif character == "]":
+            depth_bracket = max(0, depth_bracket - 1)
+        elif character == "," and depth_paren == 0 and depth_bracket == 0:
+            parts.append(value[start:index])
+            start = index + 1
+        index += 1
+    parts.append(value[start:])
+    return parts
 
 
 def _surfaces(text: str, label: str) -> List[str]:
@@ -643,7 +761,7 @@ def _surfaces(text: str, label: str) -> List[str]:
     _non_placeholder(value, f"{label} Surfaces")
     named: List[str] = []
     seen = set()
-    for item in value.split(","):
+    for item in _split_top_level_commas(value):
         if not item.strip():
             continue
         surface = _unquoted(item)
@@ -790,6 +908,338 @@ def _coverage_rows(plan: str) -> List[Tuple[str, str, str]]:
     return rows
 
 
+def _probe_table(
+    body: str, label: str, header: str, id_pattern: "re.Pattern[str]", width: int
+) -> List[List[str]]:
+    """Rows of one fixed-width probe table; the last cell keeps any `|` it holds."""
+
+    rows: List[List[str]] = []
+    for line in _strip_comments(body).splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            # A row that lost its leading pipe would otherwise vanish silently.
+            if "|" in stripped and id_pattern.fullmatch(_unquoted(stripped.split("|", 1)[0])):
+                raise HandoffError(f"{label} row must start with |: {stripped}")
+            continue
+        cells = [_unquoted(cell) for cell in stripped.strip("|").split("|")]
+        first = cells[0] if cells else ""
+        if first.casefold() == header.casefold() or all(
+            TABLE_SEPARATOR_PATTERN.fullmatch(cell) for cell in cells if cell
+        ):
+            continue
+        if not id_pattern.fullmatch(first):
+            raise HandoffError(f"{label} has an invalid row: {stripped}")
+        if len(cells) < width:
+            raise HandoffError(f"{label} {first} needs {width} cells")
+        rows.append(cells[: width - 1] + ["|".join(cells[width - 1 :]).strip()])
+    ids = [row[0] for row in rows]
+    repeated = sorted({value for value in ids if ids.count(value) > 1})
+    if repeated:
+        raise HandoffError(f"{label} repeats " + ", ".join(repeated))
+    # id_pattern fixes a one-letter prefix, so the ids sort by their number.
+    expected = [f"{ids[0][0]}{number}" for number in range(1, len(ids) + 1)] if ids else []
+    if sorted(ids, key=lambda value: int(value[1:])) != expected:
+        raise HandoffError(f"{label} ids must be contiguous from 1")
+    return rows
+
+
+def _probe_section(text: str, heading: str, label: str) -> Optional[str]:
+    """Body of one exact `## <heading>` section; a near-miss heading is an error.
+
+    The probe gates key on this heading, so a misspelled or re-levelled one
+    must fail loudly instead of reading as an intent written before the probe.
+    """
+
+    live = _strip_comments(text)
+    exact = re.findall(rf"(?m)^## {re.escape(heading)}[ \t]*$", live)
+    near = [
+        line.strip()
+        for line in re.findall(rf"(?im)^[ \t]*#{{1,6}}[ \t]*{re.escape(heading)}\b.*$", live)
+        if not re.fullmatch(rf"## {re.escape(heading)}", line.strip())
+    ]
+    if near:
+        raise HandoffError(f"{label} heading {near[0]!r} must be exactly '## {heading}'")
+    if len(exact) > 1:
+        raise HandoffError(f"{label} repeats ## {heading}")
+    if not exact:
+        return None
+    return _common.section_body(live, heading)
+
+
+def _criterion_disposition(
+    value: str, criteria: Dict[str, str], label: str
+) -> Optional[str]:
+    match = CRITERION_DISPOSITION_PATTERN.fullmatch(" ".join(value.split()))
+    if match is None:
+        return None
+    target = match.group(1)
+    if target not in criteria:
+        raise HandoffError(f"{label} names unknown {target}")
+    return target
+
+
+def edge_coverage(
+    intent: str, criteria: Dict[str, str]
+) -> Optional[Dict[str, Dict[str, str]]]:
+    """INTENT.md `## Edge coverage`, or None for an intent written before the probe.
+
+    Each row rules on one applicable edge of one success criterion:
+    `criterion SCn` (the edge is stated in a success criterion), `held-out`
+    (a named test must pin the ruling in Detail), or `dismissed` (Detail says
+    why it does not apply). Every criterion appears at least once, so a
+    skipped walk is visible rather than silent.
+    """
+
+    label = "INTENT.md Edge coverage"
+    body = _probe_section(intent, "Edge coverage", label)
+    if body is None:
+        return None
+    edges: Dict[str, Dict[str, str]] = {}
+    seen: Set[Tuple[str, str, str, str]] = set()
+    categories: Dict[str, Set[str]] = {}
+    for edge_id, criterion, category, disposition, detail in _probe_table(
+        body, label, "Edge", EDGE_ID_PATTERN, 5
+    ):
+        row_label = f"{label} {edge_id}"
+        if criterion not in criteria:
+            raise HandoffError(f"{row_label} names unknown criterion {criterion or 'none'}")
+        category = category.casefold()
+        if category not in EDGE_CATEGORIES + ("none",):
+            raise HandoffError(f"{row_label} has unknown category {category or 'none'}")
+        disposition = " ".join(disposition.split())
+        key = (criterion, category, disposition, _normalize_ws(detail))
+        if key in seen:
+            raise HandoffError(f"{row_label} repeats an earlier row")
+        seen.add(key)
+        categories.setdefault(criterion, set()).add(category)
+        target = _criterion_disposition(disposition, criteria, row_label)
+        if target is None and disposition not in {"held-out", "dismissed"}:
+            raise HandoffError(
+                f"{row_label} disposition must be criterion SCn, held-out, or dismissed"
+            )
+        if category == "none" and disposition != "dismissed":
+            raise HandoffError(f"{row_label} category none must be dismissed")
+        if target is None:
+            detail = _non_placeholder(detail, f"{row_label} Detail")
+        elif detail:
+            _reject_placeholder(detail, f"{row_label} Detail")
+        edges[edge_id] = {
+            "criterion": criterion,
+            "category": category,
+            "disposition": "criterion" if target else disposition,
+            "target": target or "",
+            "detail": detail,
+        }
+    if not edges:
+        raise HandoffError(f"{label} has no rows")
+    for criterion, raised in categories.items():
+        if "none" in raised and len(raised) > 1:
+            raise HandoffError(f"{label} {criterion} mixes category none with edges")
+    walked = {edge["criterion"] for edge in edges.values()}
+    unwalked = [criterion for criterion in criteria if criterion not in walked]
+    if unwalked:
+        raise HandoffError(f"{label} does not walk " + ", ".join(unwalked))
+    return edges
+
+
+def prohibitions(
+    intent: str, criteria: Dict[str, str]
+) -> Optional[Dict[str, Dict[str, str]]]:
+    """INTENT.md `## Prohibitions`, or None for an intent written before the probe.
+
+    Each row names what one criterion must never silently become:
+    `criterion SCn` (stated as a checkable success criterion), `judgment`
+    (the final reviewer judges it; Detail says what to look for), or
+    `dismissed`. Criterion `all` is allowed only for a dismissed row, so work
+    no person touches needs one row instead of one per criterion.
+    """
+
+    label = "INTENT.md Prohibitions"
+    body = _probe_section(intent, "Prohibitions", label)
+    if body is None:
+        return None
+    rows: Dict[str, Dict[str, str]] = {}
+    for prohibition_id, criterion, must_not, disposition, detail in _probe_table(
+        body, label, "Prohibition", PROHIBITION_ID_PATTERN, 5
+    ):
+        row_label = f"{label} {prohibition_id}"
+        disposition = " ".join(disposition.split())
+        if criterion.casefold() == "all":
+            if disposition != "dismissed":
+                raise HandoffError(f"{row_label} criterion all must be dismissed")
+            criterion = "all"
+        elif criterion not in criteria:
+            raise HandoffError(f"{row_label} names unknown criterion {criterion or 'none'}")
+        target = _criterion_disposition(disposition, criteria, row_label)
+        if target is None and disposition not in {"judgment", "dismissed"}:
+            raise HandoffError(
+                f"{row_label} disposition must be criterion SCn, judgment, or dismissed"
+            )
+        if disposition != "dismissed":
+            must_not = _non_placeholder(must_not, f"{row_label} Must not")
+        elif must_not:
+            _reject_placeholder(must_not, f"{row_label} Must not")
+        if target is None:
+            detail = _non_placeholder(detail, f"{row_label} Detail")
+        elif detail:
+            _reject_placeholder(detail, f"{row_label} Detail")
+        rows[prohibition_id] = {
+            "criterion": criterion,
+            "must_not": must_not,
+            "disposition": "criterion" if target else disposition,
+            "target": target or "",
+            "detail": detail,
+        }
+    if not rows:
+        raise HandoffError(f"{label} has no rows")
+    walked = {row["criterion"] for row in rows.values()}
+    if "all" in walked:
+        # `all` records that no person is affected at all, so it stands alone.
+        if len(rows) != 1 or next(iter(rows.values()))["must_not"].casefold() != "none":
+            raise HandoffError(f"{label} criterion all must be the only row, with Must not none")
+        return rows
+    unwalked = [criterion for criterion in criteria if criterion not in walked]
+    if unwalked:
+        raise HandoffError(f"{label} does not walk " + ", ".join(unwalked))
+    return rows
+
+
+def evidence_tags(intent: str, criteria: Dict[str, str]) -> Dict[str, List[str]]:
+    """Per criterion, the held-out edges and judgment prohibitions a `met` verdict must cite."""
+
+    tags: Dict[str, List[str]] = {}
+    for edge_id, edge in (edge_coverage(intent, criteria) or {}).items():
+        if edge["disposition"] == "held-out":
+            tags.setdefault(edge["criterion"], []).append(edge_id)
+    for prohibition_id, row in (prohibitions(intent, criteria) or {}).items():
+        if row["disposition"] == "judgment":
+            tags.setdefault(row["criterion"], []).append(prohibition_id)
+    return tags
+
+
+def _cites(text: str, tag: str) -> bool:
+    """A citation of an E#/N# id as a word, not inside a path, name, or longer id."""
+
+    return re.search(rf"(?<![A-Za-z0-9_./\\-]){re.escape(tag)}(?![A-Za-z0-9_])", text) is not None
+
+
+def _held_out_checks(plan: str) -> Dict[str, Tuple[str, str]]:
+    body = _common.section_body(plan, "Held-out checks")
+    if body is None:
+        return {}
+    label = "PLAN.md Held-out checks"
+    checks: Dict[str, Tuple[str, str]] = {}
+    for line in _strip_comments(body).splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if cells[0].casefold() == "edge" or all(
+            TABLE_SEPARATOR_PATTERN.fullmatch(cell) for cell in cells if cell
+        ):
+            continue
+        if len(cells) != 3 or not EDGE_ID_PATTERN.fullmatch(cells[0]):
+            raise HandoffError(f"{label} has an invalid row: {stripped}")
+        edge_id, task_id, test = (_unquoted(cell) for cell in cells)
+        if edge_id in checks:
+            raise HandoffError(f"{label} repeats {edge_id}")
+        # A pytest-style node id (`tests/x.py::test_y`) names its file before `::`.
+        test = _canonical_repo_path(test.split("::", 1)[0], f"{label} {edge_id} Test")
+        checks[edge_id] = (task_id, test)
+    return checks
+
+
+def _verify_without_comments(task_text: str) -> str:
+    body = _section(task_text, "Verify")
+    block = VERIFY_BLOCK_PATTERN.search(body)
+    if block is None:
+        return ""
+    return _normalize_ws(re.sub(r"(?m)(?:^|\s)#.*$", "", block.group("block")))
+
+
+def _validate_held_out_checks(
+    plan: str,
+    edges: Optional[Dict[str, Dict[str, str]]],
+    tasks: Dict[str, str],
+) -> Dict[str, str]:
+    """Each held-out edge maps to one task whose Verify runs the named test."""
+
+    held_out = sorted(
+        (edge_id for edge_id, edge in (edges or {}).items() if edge["disposition"] == "held-out"),
+        key=lambda value: int(value[1:]),
+    )
+    checks = _held_out_checks(plan)
+    label = "PLAN.md Held-out checks"
+    missing = [edge_id for edge_id in held_out if edge_id not in checks]
+    if missing:
+        raise HandoffError(f"{label} omits held-out " + ", ".join(missing))
+    extra = sorted(set(checks) - set(held_out), key=lambda value: int(value[1:]))
+    if extra:
+        raise HandoffError(f"{label} names edges that are not held-out: " + ", ".join(extra))
+    for edge_id in held_out:
+        task_id, test = checks[edge_id]
+        if task_id not in tasks:
+            raise HandoffError(f"{label} {edge_id} names unknown {task_id}")
+        text = tasks[task_id]
+        criterion = (edges or {})[edge_id]["criterion"]
+        if criterion not in _owned_criteria(text, task_id):
+            raise HandoffError(
+                f"{label} {edge_id} belongs to {criterion}, which {task_id} does not own"
+            )
+        files = [_posix_path(path) for path in _frontmatter_files(text)]
+        if test not in files:
+            raise HandoffError(f"{label} {edge_id} test {test} is not listed in {task_id} files")
+        if any(other != test and other.startswith(test + "/") for other in files):
+            raise HandoffError(f"{label} {edge_id} test {test} names a directory, not a test file")
+        if not _verify_mentions_a_file(_verify_without_comments(text), [test]):
+            raise HandoffError(f"{task_id} Verify must run held-out test {test} for {edge_id}")
+        acceptance = " ".join(_acceptance_items(text, task_id).values())
+        if not _cites(acceptance, edge_id):
+            raise HandoffError(f"{task_id} Acceptance criteria must state held-out {edge_id}")
+    return {edge_id: checks[edge_id][0] for edge_id in held_out}
+
+
+def validate_intent_probes(root: Path, project_dir: str = DEFAULT_PROJECT_DIR) -> None:
+    """Probe-table check for leaving define; a no-op without INTENT.md or its tables."""
+
+    path = root / _intent_path(project_dir)
+    if not path.is_file():
+        return
+    intent = _read(root, _intent_path(project_dir))
+    live = _strip_comments(intent)
+    if not re.search(r"(?im)^[ \t]*#{1,6}[ \t]*(edge coverage|prohibitions)\b", live):
+        return
+    criteria = _success_criteria(intent)
+    edge_coverage(intent, criteria)
+    prohibitions(intent, criteria)
+
+
+def validate_intent(
+    root: Path, project_dir: str = DEFAULT_PROJECT_DIR
+) -> Dict[str, object]:
+    """Check INTENT.md success criteria and its spec-reach probe tables before approval."""
+
+    intent = _read(root, _intent_path(project_dir))
+    criteria = _success_criteria(intent)
+    _surfaces(intent, "INTENT.md")
+    edges = edge_coverage(intent, criteria)
+    rows = prohibitions(intent, criteria)
+    return {
+        "phase": "define",
+        "criteria": sorted(criteria, key=lambda value: int(value[2:])),
+        "edge_coverage": "absent" if edges is None else len(edges),
+        "held_out": sorted(
+            (edge_id for edge_id, edge in (edges or {}).items() if edge["disposition"] == "held-out"),
+            key=lambda value: int(value[1:]),
+        ),
+        "prohibitions": "absent" if rows is None else len(rows),
+        "judgment": sorted(
+            (row_id for row_id, row in (rows or {}).items() if row["disposition"] == "judgment"),
+            key=lambda value: int(value[1:]),
+        ),
+    }
+
+
 def _task_texts(root: Path, project_dir: str) -> Dict[str, str]:
     tasks_dir = root / project_dir / "tasks"
     if not tasks_dir.is_dir():
@@ -860,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:
@@ -965,6 +1419,20 @@ def _task_deps(task_text: str, task_id: str) -> List[str]:
     return _inline_ids(rendered, "T", f"{task_id} deps")
 
 
+def _dependency_reachable(graph: Dict[str, List[str]], start: str, target: str) -> bool:
+    seen: Set[str] = set()
+    pending = list(graph[start])
+    while pending:
+        task_id = pending.pop()
+        if task_id in seen:
+            continue
+        if task_id == target:
+            return True
+        seen.add(task_id)
+        pending.extend(graph[task_id])
+    return False
+
+
 def _canonical_repo_path(value: str, label: str) -> str:
     cleaned = value.strip().strip("`\"'")
     path = PurePosixPath(cleaned)
@@ -1077,12 +1545,42 @@ 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"
+                    and _task_scalar(tasks[right], right, "status") == "done"
+                ):
+                    continue
+                # Dependency-ordered tasks serialize safely; only unordered
+                # same-wave overlap races on a shared file.
+                if _dependency_reachable(graph, left, right) or _dependency_reachable(
+                    graph, right, left
+                ):
+                    continue
                 raise HandoffError(
                     f"same-wave file overlap between {left} and {right}: {', '.join(overlap)}"
                 )
@@ -1116,11 +1614,12 @@ def _validate_task_graph(
 
 
 def plan_brief_inputs(
-    root: Path, project_dir: str = DEFAULT_PROJECT_DIR
+    root: Path, project_dir: str = DEFAULT_PROJECT_DIR, *, initial: bool = True
 ) -> Tuple[Dict[str, str], Dict[str, Set[str]]]:
+    """Validate the plan graph, requiring clean unlanded tasks only at approval."""
     tasks = _task_texts(root, project_dir)
     wave_depths, _ = _plan_waves(_read(root, f"{project_dir}/plan/PLAN.md"))
-    return tasks, _validate_task_graph(wave_depths, tasks, initial=True)
+    return tasks, _validate_task_graph(wave_depths, tasks, initial=initial)
 
 
 def _intent_path(project_dir: str) -> str:
@@ -1283,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):
@@ -1475,6 +1991,9 @@ def validate_plan(
             continue
         if not _verify_mentions_a_file(command, _frontmatter_files(text)):
             raise HandoffError(f"{task_id} Verify must name a path from files")
+    edges = edge_coverage(intent, criteria)
+    prohibitions(intent, criteria)
+    held_out = _validate_held_out_checks(plan, edges, tasks)
     return {
         "phase": "plan",
         "criteria": sorted(criteria),
@@ -1482,6 +2001,7 @@ def validate_plan(
         "tasks": len(tasks),
         "waves": waves,
         "surfaces": {surface: task for surface, (task, _) in owners.items()},
+        "held_out": held_out,
     }
 
 
@@ -1543,17 +2063,27 @@ def validate_wave_evidence(
             assigned[task_id].add(criterion)
     owned = _owned_by_wave(tasks, assigned, wave)
     text = _read(root, review_path.as_posix())
+    is_last_cycle = cycle >= _max_wave_cycle(root, project_dir, wave)
     if _line_value(text, "Cycle:") != str(cycle):
         raise HandoffError(f"{name} Cycle field does not match its filename")
-    if _line_value(text, "Depth:") != expected_depth:
+    recorded_depth = _line_value(text, "Depth:")
+    if recorded_depth not in VALID_REVIEW_DEPTHS:
+        raise HandoffError(f"{name} Depth does not match PLAN.md")
+    if is_last_cycle and recorded_depth != expected_depth:
         raise HandoffError(f"{name} Depth does not match PLAN.md")
     lens_fields = re.findall(r"(?m)^Lens:[ \t]*(\S.*?)[ \t]*$", text)
     if lens is None and lens_fields:
         raise HandoffError(f"{name} must not declare a review lens")
     if lens is not None and lens_fields != [lens]:
         raise HandoffError(f"{name} Lens field does not match its filename")
+    overall = _line_value(text, "Wave verdict:")
+    if overall not in {"pass", "blocked"}:
+        raise HandoffError(f"{name} Wave verdict is invalid")
     reviewed = _line_value(text, "Tasks reviewed:")
-    if not reviewed.isdigit() or int(reviewed) != len(expected_tasks):
+    enforce_plan_tasks = is_last_cycle and overall != "blocked"
+    if not reviewed.isdigit() or int(reviewed) < 1:
+        raise HandoffError(f"{name} Tasks reviewed does not match Wave {wave}")
+    if enforce_plan_tasks and int(reviewed) != len(expected_tasks):
         raise HandoffError(f"{name} Tasks reviewed does not match Wave {wave}")
 
     lines = text.splitlines()
@@ -1562,17 +2092,34 @@ def validate_wave_evidence(
         match = WAVE_TASK_HEADING.fullmatch(line)
         if match:
             task_headings.append((index, match))
+    if len(task_headings) != int(reviewed):
+        raise HandoffError(f"{name} Tasks reviewed does not match Wave {wave}")
     reviewed_tasks = [match.group("task") for _, match in task_headings]
-    if reviewed_tasks != expected_tasks:
-        raise HandoffError(
-            f"{name} must review exactly {', '.join(expected_tasks)} in plan order"
-        )
+    if enforce_plan_tasks:
+        if reviewed_tasks != expected_tasks:
+            raise HandoffError(
+                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 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 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
@@ -1589,15 +2136,25 @@ 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")
         task_verdicts.append(verdict)
 
-    overall = _line_value(text, "Wave verdict:")
-    if overall not in {"pass", "blocked"}:
-        raise HandoffError(f"{name} Wave verdict is invalid")
+    if not is_last_cycle:
+        return {
+            "phase": "wave",
+            "wave": wave,
+            "cycle": cycle,
+            "owned": owned if owned else [],
+            "review": review,
+            "verdict": overall,
+        }
+
     if overall == "pass" and "fail" in task_verdicts:
         raise HandoffError(f"{name} Wave verdict is pass while a task failed")
     try:
@@ -1634,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")
@@ -1652,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
@@ -1692,6 +2252,7 @@ def validate_final(
     intent = _read(root, _intent_path(project_dir))
     criteria = _success_criteria(intent)
     surface_of = criterion_surfaces(root, project_dir)
+    tags = evidence_tags(intent, criteria)
     relative = f"{project_dir}/review/FINAL.md"
     text = _read(root, relative) if final_text is None else final_text
     reviewed_head = _reviewed_head(text, relative)
@@ -1731,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]
@@ -1769,6 +2330,16 @@ def validate_final(
                 raise HandoffError(
                     f"FINAL.md {sc_id} met verdict must have no Finding or Fix direction"
                 )
+            # Honest verifier: a spec-tagged criterion is met only on cited
+            # evidence for each tag; otherwise the reviewer records unverifiable.
+            cited = " ".join((check, observed, reference))
+            uncited = [tag for tag in tags.get(sc_id, []) if not _cites(cited, tag)]
+            if uncited:
+                raise HandoffError(
+                    f"FINAL.md {sc_id} is met without cited evidence for "
+                    + ", ".join(uncited)
+                    + "; cite each held-out check or judgment, or record unverifiable"
+                )
         elif finding.casefold() == "none" or fix_direction.casefold() == "none":
             raise HandoffError(
                 f"FINAL.md {sc_id} {verdict} verdict requires a Finding and Fix direction"
@@ -1889,10 +2460,15 @@ def validate_patch_findings(
             source, source_text, locator
         )
         if evidence != source_evidence:
-            raise HandoffError(f"{source} locator {locator} evidence does not match its source")
+            evidence_field = "Finding" if source.endswith("FINAL.md") else "Found"
+            raise HandoffError(
+                f"{source} locator {locator} Evidence must equal the source's "
+                f"{evidence_field} field; copy it verbatim: {source_evidence!r}"
+            )
         if fix_direction != source_fix_direction:
             raise HandoffError(
-                f"{source} locator {locator} fix direction does not match its source"
+                f"{source} locator {locator} Fix direction must equal the source's "
+                f"Fix direction field; copy it verbatim: {source_fix_direction!r}"
             )
         sources.append(source)
 
@@ -1910,7 +2486,8 @@ def validate_patch_findings(
 def parser() -> argparse.ArgumentParser:
     argument_parser = argparse.ArgumentParser(description=__doc__)
     argument_parser.add_argument(
-        "phase", choices=("research", "decide", "roadmap", "patch", "plan", "wave", "final")
+        "phase",
+        choices=("intent", "research", "decide", "roadmap", "patch", "plan", "wave", "final"),
     )
     argument_parser.add_argument("--repo", type=Path, required=True)
     argument_parser.add_argument(
@@ -1938,6 +2515,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             result = validate_wave(repo, arguments.project_dir, arguments.review)
         else:
             validators = {
+                "intent": validate_intent,
                 "research": validate_research,
                 "decide": validate_decide,
                 "roadmap": validate_roadmap,