@opengsd/gsd-path 1.3.1 → 1.5.0

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

@@ -27,25 +27,35 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Iterator, Mapping, Optional, Sequence
 
-try:
-    from isolation import (
+if __package__:
+    from .isolation import (
         IsolationError,
         authorized_task_worktree,
         checkpoint as isolation_checkpoint,
         collect_artifact_recoveries,
     )
-    import _common
-    import roadmap
-except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-    if error.name not in {"isolation", "_common", "roadmap"}:
-        raise
-    from scripts.isolation import (
-        IsolationError,
-        authorized_task_worktree,
-        checkpoint as isolation_checkpoint,
-        collect_artifact_recoveries,
-    )
-    from scripts import _common, roadmap
+    from . import _common
+    from . import roadmap
+else:
+    try:
+        from isolation import (
+            IsolationError,
+            authorized_task_worktree,
+            checkpoint as isolation_checkpoint,
+            collect_artifact_recoveries,
+        )
+        import _common
+        import roadmap
+    except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
+        if error.name not in {"isolation", "_common", "roadmap"}:
+            raise
+        from scripts.isolation import (
+            IsolationError,
+            authorized_task_worktree,
+            checkpoint as isolation_checkpoint,
+            collect_artifact_recoveries,
+        )
+        from scripts import _common, roadmap
 
 try:  # pragma: no cover - exercised only on Windows
     import fcntl
@@ -66,6 +76,8 @@ PHASES = (
     "shipped",
 )
 STATUSES = ("active", "done", "blocked")
+PRE_APPROVAL_KINDS = ("intent", "plan")
+PRE_APPROVAL_MARKER = "pre-approval: "
 STATE_FIELDS = (
     "pipeline",
     "project",
@@ -79,7 +91,7 @@ STATE_FIELDS = (
     "integration_source",
 )
 LEGACY_STATE_FIELDS = STATE_FIELDS[:7]
-INTEGRATION_MODES = ("direct", "pull-request")
+INTEGRATION_MODES = ("direct", "pull-request", "external-landing")
 INTEGRATION_SOURCES = ("default", "milestone")
 NULL = "null"
 SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
@@ -129,6 +141,8 @@ CROSS_PHASE_TRANSITIONS = {
     ("decide", "done", "plan", "active"),
     ("roadmap", "done", "define", "active"),
     ("plan", "done", "build", "active"),
+    ("plan", "active", "define", "active"),
+    ("plan", "blocked", "define", "active"),
     ("build", "blocked", "define", "active"),
     ("build", "blocked", "plan", "active"),
     ("build", "active", "ship", "active"),
@@ -181,11 +195,24 @@ def _run_git(
     *arguments: str,
     check: bool = True,
 ) -> subprocess.CompletedProcess[str]:
+    command = _common.git_command(repo, *arguments)
     result = subprocess.run(
-        ["git", "-C", str(repo), *arguments],
+        command,
         capture_output=True,
-        text=True,
+        encoding="utf-8", errors="replace",
     )
+    if (
+        check
+        and result.returncode != 0
+        and arguments
+        and arguments[0] == "commit"
+        and _common.git_index_lock_retryable(result.stderr)
+    ):
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            encoding="utf-8", errors="replace",
+        )
     if check and result.returncode != 0:
         detail = result.stderr.strip() or result.stdout.strip()
         raise PipelineStateError(f"git {' '.join(arguments)} failed: {detail}")
@@ -410,14 +437,17 @@ def undo_transaction(repo: Path) -> Optional[dict[str, object]]:
         "archive_fingerprint",
         "discussion",
     }
+    if value.get("kind") == "member-task":
+        # A member landing undo also names the member reset it performs first.
+        expected |= {"member", "landing", "member_parent"}
     if set(value) != expected or value.get("schema") != UNDO_TRANSACTION_SCHEMA:
         raise PipelineStateError("undo transaction has invalid fields")
     if value.get("repo") != str(resolved):
         raise PipelineStateError("undo transaction belongs to another worktree")
     kind = value.get("kind")
-    if kind not in {"checkpoint", "uncommitted-archive"}:
+    if kind not in {"checkpoint", "uncommitted-archive", "member-task"}:
         raise PipelineStateError("undo transaction has invalid kind")
-    for field in ("expected_head", "parent"):
+    for field in ("expected_head", "parent") + (("landing", "member_parent") if kind == "member-task" else ()):
         field_value = value.get(field)
         if not isinstance(field_value, str) or not re.fullmatch(
             r"[0-9a-f]{40,64}", field_value
@@ -433,10 +463,12 @@ def undo_transaction(repo: Path) -> Optional[dict[str, object]]:
         raise PipelineStateError("undo transaction has invalid worktree fingerprint")
     archive = value.get("archive")
     archive_fingerprint = value.get("archive_fingerprint")
-    if kind == "checkpoint" and (
+    if kind in {"checkpoint", "member-task"} and (
         archive is not None or archive_fingerprint is not None
     ):
-        raise PipelineStateError("checkpoint undo transaction cannot name an archive")
+        raise PipelineStateError(f"{kind} undo transaction cannot name an archive")
+    if kind == "member-task" and not isinstance(value.get("member"), str):
+        raise PipelineStateError("member-task undo transaction has invalid member")
     if kind == "uncommitted-archive" and (
         not isinstance(archive, str) or ARCHIVE_RE.fullmatch(archive) is None
     ):
@@ -563,12 +595,15 @@ def _pending_answers(repo: Path) -> tuple[list[dict[str, str]], Optional[str]]:
     if not answers.exists() and not answers.is_symlink():
         return [], None
     try:
-        try:
-            from discussion_records import DiscussionError, pending_records
-        except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-            if error.name != "discussion_records":
-                raise
-            from scripts.discussion_records import DiscussionError, pending_records
+        if __package__:
+            from .discussion_records import DiscussionError, pending_records
+        else:
+            try:
+                from discussion_records import DiscussionError, pending_records
+            except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
+                if error.name != "discussion_records":
+                    raise
+                from scripts.discussion_records import DiscussionError, pending_records
     except ModuleNotFoundError as error:
         if error.name not in {"scripts", "scripts.discussion_records"}:
             raise
@@ -624,6 +659,29 @@ def _completion_status(repo: Path, state: Mapping[str, object], project_dir: str
     return {"status": "verified", "proof": proof}
 
 
+def _member_status(repo: Path, state: Mapping[str, object]) -> Optional[list]:
+    """Locked members and their ship close, when this milestone has a member lock."""
+    if __package__:
+        from scripts import members
+    else:
+        import members
+    archive = state.get("archive")
+    locks = [repo / ".project" / "build" / "members.json"]
+    if isinstance(archive, str) and archive not in {"", "null"}:
+        locks.insert(0, repo / archive.rstrip("/") / "build" / "members.json")
+    lock = next((path for path in locks if path.is_file()), None)
+    if lock is None:
+        return None
+    closed = {}
+    match = re.fullmatch(r"gsd-path/M(\d{3,})", str(state.get("branch") or ""))
+    if match is not None:
+        common = Path(_run_git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.strip())
+        closed = {row["name"]: row.get("status") for row in members.milestone_member_close(common, int(match.group(1)))}
+    entries = json.loads(lock.read_text(encoding="utf-8"))["members"]
+    return [{"name": entry["name"], "branch": entry["branch"], "close": closed.get(entry["name"])}
+            for entry in entries]
+
+
 def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]:
     """Report owned state, route, and git facts without advancing a phase."""
     resolved = _repo_root(repo)
@@ -658,7 +716,8 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         "collect_artifact": None,
     }
     completion = _completion_status(resolved, state, project_dir)
-    return {
+    member_rows = _member_status(resolved, state) if has_git and project_dir == ".project" else None
+    result = {
         "schema": STATUS_SCHEMA,
         "advance": False,
         "completion": completion,
@@ -688,6 +747,9 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         "next_skill": _next_skill(route if isinstance(route, dict) else {}),
         "handoff": phase_handoff(state, route, _track_root(resolved, project_dir) / "STATE.md", completion),
     }
+    if member_rows is not None:
+        result["members"] = member_rows
+    return result
 
 
 def phase_handoff(state: Mapping[str, object], route: Mapping[str, object], path: Path,
@@ -759,7 +821,7 @@ def _valid_patch_findings(repo: Path) -> bool:
             str(repo),
         ],
         capture_output=True,
-        text=True,
+        encoding="utf-8", errors="replace",
     )
     return result.returncode == 0
 
@@ -791,6 +853,8 @@ def _selected_initial_branch(project: Path, state: PipelineState) -> str:
         if archive.is_symlink() or not archive.is_dir():
             raise PipelineStateError(f"archive root must be a real directory: {archive}")
         for child in archive.iterdir():
+            if _common.is_ignored_junk(child):
+                continue
             match = re.fullmatch(r"(\d{3,})-[a-z0-9][a-z0-9-]*", child.name)
             if (
                 child.is_symlink()
@@ -862,36 +926,13 @@ def _legacy_bind_next_landing(repo: Path, state: PipelineState) -> str:
     return landing
 
 
-def _bind_next_recovery(
+def _bind_next_journal_recovery(
     repo: Path,
     state: PipelineState,
+    path: Path,
+    transaction: dict[str, object],
+    current: Optional[str],
 ) -> Optional[dict[str, object]]:
-    journal_root = _git_path(repo, BIND_NEXT_JOURNAL_DIR)
-    if not journal_root.exists() and not journal_root.is_symlink():
-        return None
-    if journal_root.is_symlink() or not journal_root.is_dir():
-        raise PipelineStateError(f"bind-next journal root must be a real directory: {journal_root}")
-
-    matches: list[tuple[Path, dict[str, object]]] = []
-    for path in sorted(journal_root.glob("*.json")):
-        transaction = _read_json(path)
-        if transaction.get("schema") not in {
-            LEGACY_BIND_NEXT_JOURNAL_SCHEMA,
-            BIND_NEXT_JOURNAL_SCHEMA,
-        }:
-            raise PipelineStateError(f"bind-next journal has invalid schema: {path}")
-        if transaction.get("repo") != str(repo):
-            raise PipelineStateError(f"bind-next journal belongs to another worktree: {path}")
-        if transaction.get("previous_branch") == state.branch:
-            matches.append((path, transaction))
-    if not matches:
-        return None
-    if len(matches) != 1:
-        raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
-    if state.phase != "shipped" or state.status != "done":
-        raise PipelineStateError("bind-next journal requires STATE shipped/done")
-
-    path, transaction = matches[0]
     required = (
         "branch",
         "previous_branch",
@@ -973,7 +1014,32 @@ def _bind_next_recovery(
     if stage not in {"prepared", "switched", "retired"}:
         raise PipelineStateError("bind-next journal has invalid stage")
 
-    current = _current_branch(repo)
+    stale_retired = False
+    if stage == "retired":
+        target_ref = _run_git(
+            repo,
+            "show-ref",
+            "--verify",
+            "--quiet",
+            f"refs/heads/{branch}",
+            check=False,
+        )
+        if target_ref.returncode not in {0, 1}:
+            detail = (target_ref.stderr or target_ref.stdout).strip()
+            raise PipelineStateError(
+                f"could not check bind-next target branch {branch}: {detail}"
+            )
+        target_exists = target_ref.returncode == 0
+        stale_retired = current not in {previous, branch} or not target_exists
+    if stale_retired:
+        # If the completed target is gone while the previous branch is checked
+        # out, still prove that branch has not moved away from the recorded ship.
+        if current == previous:
+            head = _run_git(repo, "rev-parse", "HEAD").stdout.strip()
+            if head != ship:
+                raise PipelineStateError("bind-next previous branch is not at journal ship")
+        return None
+
     if current not in {previous, branch}:
         raise PipelineStateError("bind-next journal does not own the current branch")
     if current == previous and stage != "prepared":
@@ -1008,6 +1074,52 @@ def _bind_next_recovery(
     return result
 
 
+def _bind_next_recovery(
+    repo: Path,
+    state: PipelineState,
+) -> Optional[dict[str, object]]:
+    journal_root = _git_path(repo, BIND_NEXT_JOURNAL_DIR)
+    if not journal_root.exists() and not journal_root.is_symlink():
+        return None
+    if journal_root.is_symlink() or not journal_root.is_dir():
+        raise PipelineStateError(f"bind-next journal root must be a real directory: {journal_root}")
+
+    matches: list[tuple[Path, dict[str, object]]] = []
+    for path in sorted(journal_root.glob("*.json")):
+        transaction = _read_json(path)
+        if transaction.get("schema") not in {
+            LEGACY_BIND_NEXT_JOURNAL_SCHEMA,
+            BIND_NEXT_JOURNAL_SCHEMA,
+        }:
+            raise PipelineStateError(f"bind-next journal has invalid schema: {path}")
+        if transaction.get("repo") != str(repo):
+            raise PipelineStateError(f"bind-next journal belongs to another worktree: {path}")
+        if transaction.get("previous_branch") == state.branch:
+            matches.append((path, transaction))
+    if not matches:
+        return None
+    if state.phase != "shipped" or state.status != "done":
+        if len(matches) != 1:
+            raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
+        raise PipelineStateError("bind-next journal requires STATE shipped/done")
+
+    current = _current_branch(repo)
+    recoveries: list[dict[str, object]] = []
+    for path, transaction in matches:
+        recovery = _bind_next_journal_recovery(
+            repo,
+            state,
+            path,
+            transaction,
+            current,
+        )
+        if recovery is not None:
+            recoveries.append(recovery)
+    if len(recoveries) > 1:
+        raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
+    return recoveries[0] if recoveries else None
+
+
 def _pending_discussion_block(repo: Path, phase: Optional[str]) -> Optional[str]:
     pending, error = _pending_answers(repo)
     if error:
@@ -1028,7 +1140,7 @@ def route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]:
             result["recovery"] = recovery
             if route.get("phase") == "define":
                 route["mode"] = "corrections"
-            elif route.get("phase") == "plan":
+            elif route.get("phase") == "plan" and recovery.get("source", "build") == "build":
                 route["mode"] = "build-repair"
     if route["action"] == "run-phase" and result["state"]["archive"] is None:
         reason = _pending_discussion_block(_repo_root(repo), route.get("phase"))
@@ -1381,8 +1493,11 @@ def _append_event(
 
 @contextlib.contextmanager
 def _state_lock(project: Path) -> Iterator[None]:
-    if fcntl is None:  # pragma: no cover - Windows CI is not used
-        raise PipelineStateError("state locking is unavailable on this platform")
+    if fcntl is None:
+        # Windows cannot flock a directory.
+        with _common.directory_mutex(project):
+            yield
+        return
     descriptor = os.open(project, os.O_RDONLY)
     try:
         fcntl.flock(descriptor, fcntl.LOCK_EX)
@@ -1408,27 +1523,21 @@ def _atomic_write(path: Path, content: str) -> None:
             and os.path.samestat(path_status, temporary_status)
         ):
             temporary.unlink()
-            directory = os.open(path.parent, os.O_RDONLY)
-            try:
-                os.fsync(directory)
-            finally:
-                os.close(directory)
+            _common.fsync_directory(path.parent)
     if temporary.exists() or temporary.is_symlink():
         raise PipelineStateError(f"atomic-write temporary path already exists: {temporary}")
     descriptor: Optional[int] = None
     try:
-        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
-        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        descriptor = os.open(
+            temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _common.O_BINARY, 0o666
+        )
+        with os.fdopen(descriptor, "wb") as handle:
             descriptor = None
-            handle.write(content)
+            handle.write(content.encode("utf-8"))
             handle.flush()
             os.fsync(handle.fileno())
-        os.replace(temporary, path)
-        directory = os.open(path.parent, os.O_RDONLY)
-        try:
-            os.fsync(directory)
-        finally:
-            os.close(directory)
+        _common.replace(temporary, path)
+        _common.fsync_directory(path.parent)
     finally:
         if descriptor is not None:
             os.close(descriptor)
@@ -1622,6 +1731,8 @@ def _validate_transition(
         },
         ("define", "done", "plan", "active"): {"planning started"},
         ("decide", "done", "plan", "active"): {"planning started"},
+        ("plan", "active", "define", "active"): {"plan intent corrections requested"},
+        ("plan", "blocked", "define", "active"): {"plan intent corrections requested"},
         ("ship", "blocked", "plan", "active"): {"patch plan reopened"},
         ("ship", "active", "shipped", "done"): {
             "archive preflight passed; shipment recorded",
@@ -1668,26 +1779,26 @@ def transition_state(
         if recovery_context and recovery_context["active"]:
             if (state.milestone, state.branch, state.archive) != (after.milestone, after.branch, after.archive):
                 raise PipelineStateError("build recovery must preserve milestone identity")
-        if state.phase == "build" and after.phase in {"define", "plan"}:
-            recovery = _build_recovery().begin(resolved, state, after, event)
-            rendered = _append_event(
-                rendered, after.phase,
-                _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
-            )
         if after.status != "blocked":
             reason = _pending_discussion_block(
                 resolved, after.phase if after.status == "active" else None
             )
             if reason:
                 raise PipelineStateError(reason)
-        if state.phase in {"research", "decide"} and (
+        leaving_define = (state.phase, after.phase, after.status) == ("define", "define", "done")
+        if leaving_define or (state.phase in {"research", "decide"} and (
             after.phase != state.phase or after.status == "done"
-        ):
-            try:
-                import check_handoffs
-            except ImportError:  # pragma: no cover - package imports used by tests
-                from scripts import check_handoffs
+        )):
+            if __package__:
+                from . import check_handoffs
+            else:
+                try:
+                    import check_handoffs
+                except ImportError:  # pragma: no cover - package imports used by tests
+                    from scripts import check_handoffs
             validator = {
+                # Approved intent carries its spec-reach probe tables complete.
+                "define": check_handoffs.validate_intent_probes,
                 "research": check_handoffs.validate_research_artifacts,
                 "decide": check_handoffs.validate_decide_artifacts,
             }[state.phase]
@@ -1695,6 +1806,25 @@ def transition_state(
                 validator(resolved, project_dir)
             except check_handoffs.HandoffError as error:
                 raise PipelineStateError(f"{state.phase} handoff failed: {error}") from error
+        if (project_dir == ".project" and (state.phase, state.status) == ("plan", "done")
+                and (after.phase, after.status) == ("build", "active")):
+            _lock_build_members(resolved)
+        if state.phase == "build" and after.phase in {"define", "plan"}:
+            recovery = _build_recovery().begin(resolved, state, after, event)
+            rendered = _append_event(
+                rendered, after.phase,
+                _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
+            )
+        elif (
+            state.phase == "plan"
+            and state.status in {"active", "blocked"}
+            and (after.phase, after.status) == ("define", "active")
+        ):
+            recovery = _build_recovery().begin(resolved, state, after, event)
+            rendered = _append_event(
+                rendered, after.phase,
+                _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
+            )
         _atomic_write(path, rendered)
     return {
         "schema": STATE_SCHEMA,
@@ -1705,6 +1835,17 @@ def transition_state(
     }
 
 
+def _lock_build_members(repo: Path) -> None:
+    if __package__:
+        from scripts import members
+    else:
+        import members
+    try:
+        members.lock_build_members(repo)
+    except members.MembersError as error:
+        raise PipelineStateError(f"build start: {error}") from error
+
+
 def _build_recovery():
     if __package__:
         from scripts import build_recovery
@@ -1776,6 +1917,55 @@ def configure_integration(
     }
 
 
+def _log_events(text: str) -> list[str]:
+    return [line.split(" — ", 2)[-1] for line in text.splitlines()
+            if line.startswith("- ") and " — " in line]
+
+
+def pre_approve(repo: Path, grant: Optional[str], use: Optional[str]) -> dict[str, object]:
+    """Record an owner's pre-approval grant, or record one granted gate's use."""
+    resolved = _repo_root(repo)
+    project = _track_root(resolved, ".project")
+    with _state_lock(project):
+        state, text, path = load_state(resolved)
+        if grant is not None:
+            kinds = grant.split(",")
+            if not kinds or len(set(kinds)) != len(kinds) or not set(kinds) <= set(PRE_APPROVAL_KINDS):
+                raise PipelineStateError(
+                    f"pre-approval kinds must be distinct values from: {', '.join(PRE_APPROVAL_KINDS)}"
+                )
+            if state.milestone is not None:
+                raise PipelineStateError("pre-approval is granted only before milestone intent approval")
+            event = PRE_APPROVAL_MARKER + json.dumps({"kinds": kinds}, sort_keys=True)
+        else:
+            events = _log_events(text)
+            starts = [index for index, event in enumerate(events) if event.startswith(PRE_APPROVAL_MARKER)]
+            if not starts:
+                raise PipelineStateError("no pre-approval grant is recorded")
+            try:
+                recorded = json.loads(events[starts[-1]][len(PRE_APPROVAL_MARKER):])
+                kinds = recorded["kinds"]
+            except (ValueError, TypeError, KeyError) as error:
+                raise PipelineStateError("invalid pre-approval record") from error
+            if not isinstance(kinds, list):
+                raise PipelineStateError("invalid pre-approval record")
+            if (_build_recovery().context(resolved, text) or {}).get("active") or (project / "review/PATCH-FINDINGS.md").exists():
+                raise PipelineStateError("pre-approval never covers build recovery or patch planning")
+            if use not in kinds:
+                raise PipelineStateError(f"pre-approval does not grant {use}")
+            # The canonical approval event, not this record, consumes the grant.
+            approvals = events[starts[-1] + 1:].count("milestone intent approved")
+            expected = {"intent": ("define", "active", 0), "plan": ("plan", "active", 1)}[use]
+            if (state.phase, state.status, approvals) != expected or (
+                (state.milestone is None) != (use == "intent")
+            ):
+                raise PipelineStateError(f"pre-approval for {use} is used or out of scope")
+            event = f"pre-authorized approval: {use}"
+        rendered = _append_event(text, state.phase, event)
+        _atomic_write(path, rendered)
+    return {"schema": STATE_SCHEMA, "status": "recorded", "event": event, "state": state.json()}
+
+
 def _shipment_roadmap(text: str, state: PipelineState, archive: str) -> str:
     if state.milestone is None or state.branch is None:
         raise PipelineStateError("shipment state must name milestone and branch")
@@ -2016,7 +2206,8 @@ def _commit_message(subject: str, body_fields: Mapping[str, str]) -> str:
 def _validate_next_layout(next_root: Path, state: PipelineState) -> None:
     phase_index = LOOKAHEAD_PHASES.index(state.phase)
     for path in next_root.rglob("*"):
-        relative = path.relative_to(next_root)
+        # POSIX form: a WindowsPath never equals the PurePosixPath layout below.
+        relative = PurePosixPath(path.relative_to(next_root).as_posix())
         if path.is_symlink():
             raise PipelineStateError(f"lookahead artifacts must not be symlinks: {path}")
         if path.is_dir():
@@ -2028,6 +2219,8 @@ def _validate_next_layout(next_root: Path, state: PipelineState) -> None:
             continue
         if not path.is_file():
             raise PipelineStateError(f"lookahead has unsafe artifact: {path}")
+        if _common.is_ignored_junk(path):
+            continue
         artifact = relative.as_posix()
         required_phase = LOOKAHEAD_FIXED_ARTIFACTS.get(artifact)
         if required_phase is None and LOOKAHEAD_EVIDENCE_RE.fullmatch(artifact):
@@ -2112,6 +2305,11 @@ def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
     configure.add_argument("--project-dir", default=".project")
     configure.add_argument("--scope", required=True, choices=("default", "milestone"))
     configure.add_argument("--mode", required=True, choices=INTEGRATION_MODES)
+    pre = subparsers.add_parser("pre-approve")
+    pre.add_argument("--repo", required=True, type=Path)
+    pre_mode = pre.add_mutually_exclusive_group(required=True)
+    pre_mode.add_argument("--grant")
+    pre_mode.add_argument("--use", choices=PRE_APPROVAL_KINDS)
     shipment = subparsers.add_parser("record-shipment")
     shipment.add_argument("--repo", required=True, type=Path)
     shipment.add_argument("--archive", required=True)
@@ -2200,6 +2398,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 base,
                 landing,
             )
+        elif args.command == "pre-approve":
+            result = pre_approve(args.repo, args.grant, args.use)
         elif args.command == "record-shipment":
             result = record_shipment(args.repo, args.archive, args.event)
         elif args.command == "configure-integration":

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

@@ -205,7 +205,7 @@ def select_fetched_base(
     resolved = subprocess.run(
         ["git", "-C", str(root), "rev-parse", "--verify", f"{remote_default}^{{commit}}"],
         capture_output=True,
-        text=True,
+        encoding="utf-8", errors="replace",
         check=False,
     )
     if resolved.returncode != 0 or resolved.stdout.strip() != base:

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

@@ -470,7 +470,7 @@ def merge_artifacts(
         lines.append(artifact["text"].rstrip())
         lines.append("")
     output.parent.mkdir(parents=True, exist_ok=True)
-    output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+    output.write_bytes(("\n".join(lines).rstrip() + "\n").encode("utf-8"))
     return {
         "output": str(output.resolve()),
         "families": families,