@opengsd/gsd-path 1.4.0 → 1.6.0

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

@@ -467,15 +467,17 @@ def completed_field(lines: Sequence[str], field: str, artifact: str) -> str:
 
 
 def completed_bullet_field(lines: Sequence[str], field: str, artifact: str) -> str:
-    pattern = re.compile(rf"^- \*\*{re.escape(field)}\*\*:\s*(.*)$")
-    values = []
-    for line in lines:
-        match = pattern.fullmatch(line)
-        if match:
-            values.append(match.group(1).strip().strip("`"))
-    if len(values) != 1 or not values[0] or archive_milestone.contains_placeholder(values[0]):
+    matches = _common.find_review_bullet_field_values(lines, field)
+    if len(matches) != 1:
         raise ArchiveError(f"{artifact} requires one completed {field} field")
-    return values[0]
+    raw_value = matches[0].strip()
+    value = raw_value.strip("`")
+    # Scan the value as written. Removing an outer backtick first can unbalance
+    # every code span after a leading or trailing one. contains_placeholder
+    # already handles a wholly quoted placeholder such as `<command>`.
+    if not value or archive_milestone.contains_placeholder(raw_value):
+        raise ArchiveError(f"{artifact} requires one completed {field} field")
+    return value
 
 
 def section_lines(lines: Sequence[str], heading: str, artifact: str) -> Sequence[str]:
@@ -505,10 +507,17 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
         criteria = check_handoffs._success_criteria(text)
     except check_handoffs.HandoffError as error:
         raise ArchiveError(str(error)) from error
-    return {int(key[2:]): " ".join(value.split()) for key, value in criteria.items()}
+    # Each value keeps the form without sub-bullet markers that quotes_criterion reads.
+    return {int(key[2:]): value for key, value in criteria.items()}
 
 
 def parse_final_review(archive: Path) -> tuple:
+    reviewed_head, criteria, _raw_evidence = _final_review(archive)
+    return reviewed_head, criteria
+
+
+def _final_review(archive: Path) -> tuple:
+    """Parse FINAL.md and retain evidence as written for placeholder scans."""
     if __package__:
         from . import check_handoffs
     else:
@@ -555,25 +564,28 @@ def parse_final_review(archive: Path) -> tuple:
     if len(headings) != len(intent_criteria):
         raise ArchiveError("FINAL.md success criteria do not exactly cover INTENT.md")
     for _, number, criterion in headings:
-        if " ".join(criterion.split()) != intent_criteria[number]:
+        if not _common.quotes_criterion(criterion, intent_criteria[number]):
             raise ArchiveError(
                 f"FINAL.md SC{number} heading text differs from archived INTENT.md"
             )
 
     expected_fields = ("Verdict", "Check", "Observed", "Reference", "Finding", "Fix direction")
     criteria = []
+    raw_evidence = []
     for position, (heading_index, _, criterion) in enumerate(headings):
         section_start = heading_index + 1
         section_end = headings[position + 1][0] if position + 1 < len(headings) else criteria_end
+        section = lines[section_start:section_end]
         values = {}
-        for line in lines[section_start:section_end]:
-            match = re.fullmatch(r"- \*\*(Verdict|Check|Observed|Reference|Finding|Fix direction)\*\*:\s*(.*)", line)
-            if not match:
-                continue
-            key, value = match.groups()
-            if key in values:
+        raw_values = {}
+        for key in expected_fields:
+            matches = _common.find_review_bullet_field_values(section, key)
+            if len(matches) > 1:
                 raise ArchiveError(f"FINAL.md repeats {key} for {criterion}")
-            values[key] = value.strip().strip("`")
+            if len(matches) != 1:
+                raise ArchiveError(f"FINAL.md criterion is incomplete: {criterion}")
+            raw_values[key] = matches[0].strip()
+            values[key] = raw_values[key].strip("`")
         surface_values = [
             line.removeprefix("- **Surface**:").strip().strip("`")
             for line in lines[section_start:section_end]
@@ -593,18 +605,19 @@ def parse_final_review(archive: Path) -> tuple:
                     check_handoffs._surface_value(value, f"FINAL.md surface {field}")
                 except check_handoffs.HandoffError as error:
                     raise ArchiveError(str(error)) from error
-            elif not value or archive_milestone.contains_placeholder(value):
+            elif not value or archive_milestone.contains_placeholder(raw_values[field]):
                 raise ArchiveError(f"FINAL.md criterion is incomplete: {criterion}")
         if values["Verdict"] != "met":
             raise ArchiveError(f"FINAL.md criterion lacks passing evidence: {criterion}")
-        evidence = next(
-            (values[field] for field in ("Reference", "Check", "Observed") if values[field] != "none"),
+        evidence_field = next(
+            (field for field in ("Reference", "Check", "Observed") if values[field] != "none"),
             None,
         )
-        if evidence is None:
+        if evidence_field is None:
             raise ArchiveError(f"FINAL.md criterion lacks passing evidence: {criterion}")
-        criteria.append((criterion, "met", evidence))
-    return reviewed_head.lower(), criteria
+        criteria.append((criterion, "met", values[evidence_field]))
+        raw_evidence.append(raw_values[evidence_field])
+    return reviewed_head.lower(), criteria, raw_evidence
 
 
 def _member_heads(text: str, source: str) -> dict:
@@ -814,10 +827,14 @@ def validate_wave_review(
     expected_depth: str,
     expected_lens: Optional[str] = None,
     task_texts: Optional[dict[str, str]] = None,
+    *,
+    is_last_cycle: bool = True,
 ) -> Sequence[str]:
     lines = path.read_text(encoding="utf-8").splitlines()
     depth = completed_field(lines, "Depth:", path.name)
-    if depth != expected_depth:
+    if depth not in {"full", "deep", "verify-only"}:
+        raise ArchiveError(f"{path.name} has an invalid review depth")
+    if is_last_cycle and depth != expected_depth:
         raise ArchiveError(f"{path.name} has an invalid review depth")
     if expected_lens is not None:
         lens = completed_field(lines, "Lens:", path.name)
@@ -842,10 +859,32 @@ def validate_wave_review(
     normalized_expected = [
         (task_id, " ".join(title.split())) for task_id, title in expected_tasks
     ]
-    if actual_tasks != normalized_expected:
-        raise ArchiveError(
-            f"{path.name} tasks and titles do not match its wave task files in order"
-        )
+    expected_by_id = dict(normalized_expected)
+    enforce_plan_tasks = is_last_cycle and wave_verdict != "blocked"
+    if enforce_plan_tasks:
+        if actual_tasks != normalized_expected:
+            raise ArchiveError(
+                f"{path.name} tasks and titles do not match its wave task files in order"
+            )
+    else:
+        known_ids = set(expected_by_id)
+        for task_id in task_ids:
+            if task_id not in known_ids:
+                raise ArchiveError(
+                    f"{path.name} tasks and titles do not match its wave task files in order"
+                )
+        plan_order = [task_id for task_id, _title in normalized_expected]
+        reviewed_order = [task_id for task_id in plan_order if task_id in task_ids]
+        if task_ids != reviewed_order:
+            raise ArchiveError(
+                f"{path.name} tasks and titles do not match its wave task files in order"
+            )
+        for _index, task_id, title, _verdict in headings:
+            expected_title = expected_by_id.get(task_id)
+            if expected_title is not None and " ".join(title.split()) != expected_title:
+                raise ArchiveError(
+                    f"{path.name} tasks and titles do not match its wave task files in order"
+                )
 
     verdicts = []
     for position, (heading_index, _task_id, _title, verdict) in enumerate(headings):
@@ -870,6 +909,9 @@ def validate_wave_review(
             )
         verdicts.append(verdict)
 
+    if not is_last_cycle:
+        return verdicts
+
     coverage_indexes = [
         index for index, line in enumerate(lines) if line == "## Intent coverage"
     ]
@@ -910,10 +952,10 @@ def validate_wave_review(
             (index, match.group(1), " ".join(match.group(2).split()), match.group(3))
         )
     actual = [(sc_id, text) for _, sc_id, text, _ in criterion_headings]
-    normalized_expected_criteria = [
-        (sc_id, " ".join(text.split())) for sc_id, text in expected_criteria
-    ]
-    if actual != normalized_expected_criteria:
+    if len(actual) != len(expected_criteria) or any(
+        sc_id != expected_id or not _common.quotes_criterion(text, expected)
+        for (sc_id, text), (expected_id, expected) in zip(actual, expected_criteria)
+    ):
         raise ArchiveError(
             f"{path.name} Intent coverage does not match its owned success criteria"
         )
@@ -1083,10 +1125,17 @@ def review_cycle_counts(archive: Path) -> Sequence[int]:
                         depth,
                         lens,
                         task_texts,
+                        is_last_cycle=cycle == max(cycles),
                     )
                 )
 
         last_cycle = max(cycles)
+        for cycle, verdicts in wave_verdicts.items():
+            if cycle != last_cycle and "blocked" not in verdicts:
+                raise ArchiveError(
+                    f"superseded review cycle {cycle} for wave {wave} "
+                    "must include a blocked Wave verdict"
+                )
         if any(verdict != "pass" for verdict in wave_verdicts[last_cycle]):
             raise ArchiveError(f"last review cycle for wave {wave} did not pass")
         if any(task_verdict != "pass" for task_verdict in task_verdicts[last_cycle]):
@@ -1220,7 +1269,7 @@ def validate_manifest(project: Path, archive: Path, state: PipelineState) -> tup
     if fields["Final verdict:"] != "all criteria met; project verify passed":
         raise ArchiveError("manifest final verdict does not record the passed final gate")
 
-    reviewed_head, final_criteria = parse_final_review(archive)
+    reviewed_head, final_criteria, final_raw_evidence = _final_review(archive)
     validate_gap_reviews(archive, reviewed_head)
     task_files, attested = archive_milestone.landed_task_evidence(project, archive / "tasks", reviewed_head)
     cycle_counts = review_cycle_counts(archive)
@@ -1264,14 +1313,23 @@ def validate_manifest(project: Path, archive: Path, state: PipelineState) -> tup
             continue
         criteria_rows.append(cells)
         criteria_line_indexes.add(index)
+
+    def evidence_as_written(position: int, row: Sequence[str]) -> str:
+        # Manifest evidence stores FINAL.md's normalized value. Scan the source
+        # text when the row matches, so its inner code spans stay balanced.
+        if position < len(final_criteria) and tuple(row) == tuple(final_criteria[position]):
+            return final_raw_evidence[position]
+        return row[2]
+
     if not criteria_rows or any(
         len(row) != 3
         or not row[0]
         or row[1] != "met"
         or not row[2]
         or row[2] == "none"
-        or any(archive_milestone.contains_placeholder(cell) for cell in row[1:])
-        for row in criteria_rows
+        or archive_milestone.contains_placeholder(row[1])
+        or archive_milestone.contains_placeholder(evidence_as_written(position, row))
+        for position, row in enumerate(criteria_rows)
     ):
         raise ArchiveError("manifest success-criteria rows are incomplete")
     if [tuple(row) for row in criteria_rows] != list(final_criteria):