@opengsd/gsd-path 1.3.1 → 1.4.0

package/scripts/lean_verification.py

@@ -22,8 +22,8 @@ else:
 
 
 def _git(repo, *arguments):
-    return subprocess.run(["git", "-C", str(repo), *arguments],
-                          capture_output=True, text=True, check=True).stdout.strip()
+    return subprocess.run(["git", "-C", str(repo), *arguments], capture_output=True,
+                          encoding="utf-8", errors="surrogateescape", check=True).stdout.strip()
 
 
 def _reusable_wave(repo, expected_head):
@@ -71,7 +71,25 @@ def _reusable_wave(repo, expected_head):
     return relative, text, criteria, reviewed
 
 
-def _final_view(relative, text, criteria, reviewed, head):
+def _surface_name(value, expected):
+    """The surface a wave review's Surface field names, without the reviewer's detail.
+
+    Reviewers write the PLAN surface name and often a note after it
+    ("count.py CLI — entry `python count.py`, run from the root"). Keep exactly
+    the expected name when the field starts with it and the detail is set off by
+    a comma, dash, colon, semicolon, or parenthesis; otherwise keep the text before
+    the first comma, which FINAL.md validation then compares with the plan.
+    """
+    named = " ".join(contracts._unquoted(value).split())
+    if expected:
+        name = " ".join(expected.split())
+        rest = named[len(name):] if named.casefold().startswith(name.casefold()) else None
+        if rest is not None and (not rest or re.match(r"\s*[,;:(]|\s+[—–-]\s", rest)):
+            return expected
+    return named.partition(",")[0]
+
+
+def _final_view(relative, text, criteria, reviewed, head, surfaces=None):
     coverage = contracts._section(text, "Intent coverage")
     headings = list(re.finditer(r"(?m)^### (SC[1-9]\d*) — (.+): pass\s*$", coverage))
     blocks = {}
@@ -96,22 +114,32 @@ def _final_view(relative, text, criteria, reviewed, head):
                   f"- **Reference**: {relative} — {criterion}",
                   "- **Finding**: none", "- **Fix direction**: none"]
         if "Surface" in fields:
-            lines.append(f"- **Surface**: {contracts._unquoted(fields['Surface']).partition(',')[0]}")
+            expected = (surfaces or {}).get(criterion)
+            lines.append(f"- **Surface**: {_surface_name(fields['Surface'], expected)}")
         lines.append("")
     return "\n".join(lines)
 
 
+def _locked_members(repo):
+    lock = repo / ".project/build/members.json"
+    return json.loads(lock.read_text(encoding="utf-8"))["members"] if lock.is_file() else []
+
+
 def reuse_final(repo, expected_head):
     """Materialize a final view only when the existing proof still covers it."""
     repo = Path(repo).resolve()
     try:
+        # Wave reviews name only the coordinator head, so a member milestone needs its own final review.
+        if _locked_members(repo):
+            raise contracts.HandoffError("member milestone needs a final review of the member heads")
         relative, text, criteria, reviewed = _reusable_wave(repo, expected_head)
-        final = _final_view(relative, text, criteria, reviewed, expected_head)
+        final = _final_view(relative, text, criteria, reviewed, expected_head,
+                            contracts.criterion_surfaces(repo))
         contracts.validate_final(repo, final_text=final)
         destination = repo / ".project/review/FINAL.md"
         if destination.is_symlink():
             raise contracts.HandoffError("FINAL.md must be a real file")
-        if destination.exists() and destination.read_text() != final:
+        if destination.exists() and destination.read_text(encoding="utf-8") != final:
             raise contracts.HandoffError("existing final evidence needs explicit reconciliation")
         if not destination.exists():
             _common.atomic_write(destination, final)
@@ -123,9 +151,36 @@ def reuse_final(repo, expected_head):
 
 def _gap_view(command, head, execution, waves):
     passed = execution["exit_code"] == 0
+    members = execution.get("members")
+    output = ""
+    if members:
+        observed = "exact stdout and stderr are in the Output section; member heads are not in the ledger key"
+        reference = "project Verify at " + head + " with members " + ", ".join(
+            f"{name} {tip}" for name, tip in members.items())
+        stdout, stderr = execution["stdout"], execution["stderr"]
+        fence = "`" * max([3] + [len(run) + 1 for run in re.findall(r"`+", stdout + "\n" + stderr)])
+        stdout_end = "" if not stdout or stdout.endswith("\n") else "\n"
+        stderr_end = "" if not stderr or stderr.endswith("\n") else "\n"
+        output = f"""
+
+## Output
+
+### stdout
+
+{fence}
+{stdout}{stdout_end}{fence}
+
+### stderr
+
+{fence}
+{stderr}{stderr_end}{fence}"""
+    else:
+        members = {}
+        observed = "exact stdout and stderr are in the command/commit ledger entry"
+        reference = f".project/build/verify-ledger.jsonl — {head}, command above"
     return f"""# Gap Review — 1: project Verify
 
-Reviewed HEAD: {head}
+Reviewed HEAD: {head}{"".join(f"{chr(10)}Member reviewed HEAD: {name} {tip}" for name, tip in members.items())}
 Gap verdict: {'pass' if passed else 'blocked'}
 Risk: project Verify
 Waves checked: {', '.join(str(wave) for wave in waves)}
@@ -133,13 +188,13 @@ Waves checked: {', '.join(str(wave) for wave in waves)}
 ## Checked evidence
 
 - **Check**: `{command}`
-- **Observed**: Exit {execution['exit_code']}; exact stdout and stderr are in the command/commit ledger entry.
-- **Reference**: .project/build/verify-ledger.jsonl — {head}, command above
+- **Observed**: Exit {execution['exit_code']}; {observed}.
+- **Reference**: {reference}
 
 ## Finding
 
 - **Found**: Project Verify {'passed' if passed else 'failed'} at the reviewed commit.
-- **Fix direction**: {'none' if passed else 'Resolve the recorded command failure before shipping.'}
+- **Fix direction**: {'none' if passed else 'Resolve the recorded command failure before shipping.'}{output}
 """
 
 
@@ -147,8 +202,11 @@ def _require_ship_inputs(repo, expected_head):
     contracts._require_state(repo, "ship", "active", ".project")
     if _git(repo, "rev-parse", "HEAD") != expected_head:
         raise contracts.HandoffError("primary HEAD changed")
+    isolation.prune_host_scratch(repo / ".project")
+    # Ignored, untracked entries (.DS_Store) never ship, so they are not artifacts.
+    visible = _common.git_visible_entries(repo / ".project")
     unexpected = sorted(path.name for path in (repo / ".project").iterdir()
-                        if path.name not in isolation.PROJECT_ENTRIES)
+                        if path.name not in isolation.PROJECT_ENTRIES and path.name in visible)
     if unexpected:
         raise contracts.HandoffError("unsupported .project artifacts: " + ", ".join(unexpected))
     dirty = isolation.uncommitted_paths(repo)
@@ -176,8 +234,11 @@ def verify_project(repo, expected_head):
     plan = contracts._read(repo, ".project/plan/PLAN.md")
     command = contracts._line_value(plan, "Project verify:")
     _, waves = contracts._plan_waves(plan)
-    lookup = build_state.verify_lookup(str(repo), command, expected_head)
-    entry = lookup["entry"]
+    # Member heads are not in the ledger key, so a member milestone always runs again.
+    members = _locked_members(repo)
+    if members:
+        isolation.check_member_verify_collision(members, "project-verify")
+    entry = None if members else build_state.verify_lookup(str(repo), command, expected_head)["entry"]
     relative = ".project/review/final-gap-1.md"
     destination = repo / relative
     if destination.is_symlink():
@@ -199,19 +260,38 @@ def verify_project(repo, expected_head):
                 )
         _retire_execution(repo, expected_head, execution)
         view = _gap_view(command, expected_head, execution, waves)
-        if not destination.exists() or destination.read_text() != view:
+        if not destination.exists() or destination.read_text(encoding="utf-8") != view:
             _common.atomic_write(destination, view)
         return {"passed": entry["result"] == "pass", "reused": True,
                 "path": str(destination), "execution": execution}
     sidecar = isolation.isolate_verify(repo, expected_head, "project-verify")
     worktree = Path(sidecar["worktree"])
-    completed = subprocess.run(["bash", "-c", command], cwd=worktree,
-                               text=True, capture_output=True)
+    try:
+        sidecars = isolation.isolate_member_verify(repo, worktree) if members else None
+    except BaseException:
+        isolation.retire(repo, worktree, sidecar["branch"], force=False)
+        raise
+    try:
+        try:
+            completed = subprocess.run(_common.bash_argv(command), cwd=worktree,
+                                       encoding="utf-8", errors="replace", capture_output=True)
+            if sidecars:
+                isolation.check_member_verify(sidecars)
+        finally:
+            if sidecars:
+                isolation.retire_member_verify(sidecars)
+    except BaseException:
+        isolation.clean_verify(repo, worktree, expected_head, sidecar["branch"])
+        isolation.retire(repo, worktree, sidecar["branch"], force=False)
+        raise
     execution = {"exit_code": completed.returncode, "stdout": completed.stdout,
                  "stderr": completed.stderr, "worktree": str(worktree), "branch": sidecar["branch"]}
     passed = completed.returncode == 0
-    build_state.verify_record(str(repo), command, expected_head,
-                              "pass" if passed else "fail", execution=execution)
+    if members:
+        execution["members"] = {name: record["tip"] for name, record in sidecars.items()}
+    else:
+        build_state.verify_record(str(repo), command, expected_head,
+                                  "pass" if passed else "fail", execution=execution)
     isolation.clean_verify(repo, worktree, expected_head, sidecar["branch"])
     _common.atomic_write(worktree / relative, _gap_view(command, expected_head, execution, waves))
     collection = isolation.collect_artifact(repo, worktree, expected_head, sidecar["branch"],
@@ -227,7 +307,7 @@ def prepare_final(repo, expected_head):
         return {"status": "blocked", "verification": verification,
                 "reason": "project Verify failed; use its recorded output"}
     final = reuse_final(repo, expected_head)
-    if not final["reused"] and (Path(repo) / ".project/review/FINAL.md").exists():
+    if not _locked_members(Path(repo)) and not final["reused"] and (Path(repo) / ".project/review/FINAL.md").exists():
         try:
             valid = contracts.validate_final(Path(repo))
             if valid["verdict"] == "pass":

package/scripts/loop_run.py

@@ -32,10 +32,10 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Iterator, Optional, Sequence
 
-if sys.platform == "win32":
-    import msvcrt
-else:
-    import fcntl
+try:
+    from . import _common
+except ImportError:
+    import _common
 
 
 class LoopError(RuntimeError):
@@ -119,25 +119,8 @@ def log_path(fields: dict) -> Path:
 def log_lock(fields: dict) -> Iterator[None]:
     path = log_path(fields)
     path.parent.mkdir(parents=True, exist_ok=True)
-    lock_path = path.with_name(f".{path.name}.lock")
-    with lock_path.open("a+b") as handle:
-        if sys.platform == "win32":
-            handle.seek(0, os.SEEK_END)
-            if handle.tell() == 0:
-                handle.write(b"\0")
-                handle.flush()
-            handle.seek(0)
-            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
-        else:
-            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
-        try:
-            yield
-        finally:
-            if sys.platform == "win32":
-                handle.seek(0)
-                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
-            else:
-                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+    with _common.exclusive_lock(path.with_name(f".{path.name}.lock")):
+        yield
 
 
 def load_log(fields: dict) -> list[dict]:
@@ -528,15 +511,22 @@ def command_claim(fields: dict) -> dict:
 
 
 def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
-    """Run one spec command; a hung command counts as failed (exit None)."""
+    """Run one spec command; a hung command counts as failed (exit None).
+
+    POSIX runs /bin/sh as shell=True did; Windows runs Git for Windows bash, not
+    cmd.exe. A timeout kills the whole process group, so a grandchild cannot
+    keep the output pipes open.
+    """
+    argv = _common.bash_argv(command) if os.name == "nt" else ["/bin/sh", "-c", command]
+    process = _common.popen_group(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     try:
-        completed = subprocess.run(
-            command, shell=True, capture_output=True, text=True, check=False, timeout=timeout
-        )
-    except subprocess.TimeoutExpired as expired:
-        output = (expired.stdout or b"").decode(errors="replace") + (expired.stderr or b"").decode(errors="replace")
+        stdout, stderr = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _common.kill_tree(process)
+        stdout, stderr = process.communicate()
+        output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")
         return None, f"{output}\ntimed out at the admitted wall-clock deadline"
-    return completed.returncode, completed.stdout + completed.stderr
+    return process.returncode, (stdout + stderr).decode("utf-8", errors="replace")
 
 
 def command_verify(fields: dict, claim_identifier: Optional[str]) -> dict: