@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-docs-audit/scripts/discussion_records.py

@@ -16,14 +16,20 @@ from pathlib import Path
 from typing import Iterator, Optional, Sequence
 
 def _load_pipeline_modules():
-    try:
-        import archive_milestone
-        import pipeline_state
-        import _common
+    if __package__:
+        from . import archive_milestone
+        from . import pipeline_state
+        from . import _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
-        if error.name not in {"archive_milestone", "pipeline_state", "_common"}:
-            raise
+    else:
+        try:
+            import archive_milestone
+            import pipeline_state
+            import _common
+            return _common, archive_milestone, pipeline_state
+        except ModuleNotFoundError as error:
+            if error.name not in {"archive_milestone", "pipeline_state", "_common"}:
+                raise
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
@@ -111,7 +117,7 @@ def record_count(directory: Path) -> int:
 def validate_or_empty(directory: Path) -> None:
     if directory.is_symlink() or not directory.is_dir():
         raise DiscussionError("discussion records must be a real directory")
-    if sorted(path.name for path in directory.iterdir()) != sorted(FILES):
+    if sorted(path.name for path in directory.iterdir() if not _common.is_ignored_junk(path)) != sorted(FILES):
         raise DiscussionError("discussion directory must contain exactly DIALOGUE.md and ANSWERS.md")
     if record_count(directory) == 0:
         if "### D" in (directory / "DIALOGUE.md").read_text(encoding="utf-8"):
@@ -170,7 +176,7 @@ def validate_contents(project: Path, files: dict) -> None:
     staging.mkdir()
     try:
         for name in FILES:
-            (staging / name).write_text(files[name], encoding="utf-8")
+            (staging / name).write_bytes(files[name].encode("utf-8"))
         validate_or_empty(staging)
     finally:
         shutil.rmtree(staging)
@@ -187,11 +193,11 @@ def initialize_records(discussion: Path, dialogue_template: Path, answers_templa
         shutil.rmtree(staging)
     staging.mkdir()
     try:
-        (staging / "DIALOGUE.md").write_text(
-            template_header(dialogue_template, "### D001"), encoding="utf-8"
+        (staging / "DIALOGUE.md").write_bytes(
+            template_header(dialogue_template, "### D001").encode("utf-8")
         )
-        (staging / "ANSWERS.md").write_text(
-            template_header(answers_template, "## Answer A001"), encoding="utf-8"
+        (staging / "ANSWERS.md").write_bytes(
+            template_header(answers_template, "## Answer A001").encode("utf-8")
         )
         os.replace(staging, discussion)
     finally:

package/skills/gsd-path-docs-audit/scripts/discussion_validate.py

@@ -14,12 +14,16 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
-try:
-    from pipeline_state import PipelineState
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts.pipeline_state import PipelineState
-    from scripts import _common
+if __package__:
+    from .pipeline_state import PipelineState
+    from . import _common
+else:
+    try:
+        from pipeline_state import PipelineState
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts.pipeline_state import PipelineState
+        from scripts import _common
 
 
 atomic_replace = _common.atomic_replace
@@ -105,7 +109,7 @@ def validate_discussion_directory(
 ) -> None:
     if directory.is_symlink() or not directory.is_dir():
         raise ArchiveError("discussion archive must be a real directory")
-    entries = sorted(path.name for path in directory.iterdir())
+    entries = sorted(path.name for path in directory.iterdir() if not _common.is_ignored_junk(path))
     if entries != sorted(DISCUSSION_FILES):
         raise ArchiveError("discussion archive must contain exactly DIALOGUE.md and ANSWERS.md")
     dialogue, answers = (directory / name for name in DISCUSSION_FILES)
@@ -463,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]:
@@ -490,10 +496,13 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
     if not archive_milestone.is_real_file(intent):
         raise ArchiveError("archived intent must be a real INTENT.md file")
     text = HTML_COMMENT_PATTERN.sub("", intent.read_text(encoding="utf-8"))
-    try:
-        import check_handoffs
-    except ImportError:
-        from scripts import check_handoffs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:
+            from scripts import check_handoffs
     try:
         criteria = check_handoffs._success_criteria(text)
     except check_handoffs.HandoffError as error:
@@ -502,10 +511,19 @@ def archived_intent_criteria(archive: Path) -> dict[int, str]:
 
 
 def parse_final_review(archive: Path) -> tuple:
-    try:
-        import check_handoffs
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts import check_handoffs
+    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:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
 
     final = archive / "review" / "FINAL.md"
     if not archive_milestone.is_real_file(final):
@@ -552,18 +570,21 @@ def parse_final_review(archive: Path) -> tuple:
 
     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]
@@ -583,22 +604,44 @@ 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:
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts import check_handoffs
+    try:
+        return check_handoffs.member_reviewed_heads(text, source)
+    except check_handoffs.HandoffError as error:
+        raise ArchiveError(str(error)) from error
 
 
 def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
     review = archive / "review"
+    member_heads = _member_heads((review / "FINAL.md").read_text(encoding="utf-8"), "FINAL.md")
+    lock = archive / "build" / "members.json"
+    locked = [item["name"] for item in json.loads(lock.read_text(encoding="utf-8"))["members"]] if lock.is_file() else []
+    if sorted(member_heads) != sorted(locked):
+        raise ArchiveError(
+            "FINAL.md Member reviewed HEAD lines must name each locked member: " + (", ".join(locked) or "none")
+        )
     candidates = sorted(path for path in review.iterdir() if path.name.startswith("final-gap-"))
     if not candidates:
         raise ArchiveError("final review requires at least one final-gap-N.md artifact")
@@ -626,6 +669,8 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
         gap_head = completed_field(lines, "Reviewed HEAD:", path.name).lower()
         if gap_head != reviewed_head:
             raise ArchiveError(f"{path.name} Reviewed HEAD does not match FINAL.md")
+        if _member_heads("\n".join(lines), path.name) != member_heads:
+            raise ArchiveError(f"{path.name} Member reviewed HEAD lines do not match FINAL.md")
         if completed_field(lines, "Gap verdict:", path.name) != "pass":
             raise ArchiveError(f"{path.name} gap review did not pass")
         risk = completed_field(lines, "Risk:", path.name)
@@ -655,10 +700,13 @@ def validate_gap_reviews(archive: Path, reviewed_head: str) -> None:
 
 
 def meaningful_review_evidence(lines: Sequence[str], marker: str, task_text: str = "") -> bool:
-    try:
-        from check_handoffs import task_review_observation
-    except ImportError:  # pragma: no cover - package import used by tests
-        from scripts.check_handoffs import task_review_observation
+    if __package__:
+        from .check_handoffs import task_review_observation
+    else:
+        try:
+            from check_handoffs import task_review_observation
+        except ImportError:  # pragma: no cover - package import used by tests
+            from scripts.check_handoffs import task_review_observation
 
     prefix = f"- {marker} "
     evidence = []
@@ -778,10 +826,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)
@@ -806,10 +858,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):
@@ -834,6 +908,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"
     ]
@@ -1047,10 +1124,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]):
@@ -1071,8 +1155,17 @@ def archive_file_inventory(archive: Path) -> Sequence[str]:
     for path in archive.rglob("*"):
         if path.is_symlink():
             raise ArchiveError(f"archive contents must not be symlinks: {path}")
-        if path.is_file() and path.name != "MANIFEST.md":
-            contents.append(path.relative_to(archive).as_posix())
+        if not path.is_file() or path.name == "MANIFEST.md":
+            continue
+        relative = path.relative_to(archive)
+        if _common.is_ignored_junk(path):
+            if len(relative.parts) == 1:
+                continue
+            original = archive.parent.parent / relative
+            project = archive.parent.parent.parent
+            if run_git(project, "check-ignore", "-q", "--", original.relative_to(project).as_posix()).returncode == 0:
+                continue
+        contents.append(relative.as_posix())
     return sorted(contents)
 
 
@@ -1175,7 +1268,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)
@@ -1219,14 +1312,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):