@opengsd/gsd-path 1.3.0 → 1.4.0

package/skills/gsd-path-undo/scripts/path_config.py

@@ -174,13 +174,13 @@ def set_value(repo, scope, key, value, reset=False):
     if scope == 'project':
         state, _, _ = sibling('pipeline_state').load_state(repo)
         branch = subprocess.run(['git', '-C', str(repo), 'branch', '--show-current'],
-                                capture_output=True, text=True)
+                                capture_output=True, encoding="utf-8", errors="replace")
         if branch.returncode or not state.branch or branch.stdout.strip() != state.branch:
             raise ValueError('Run the router to bind the project branch before editing settings.')
         head = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--verify', 'HEAD'], capture_output=True)
         if head.returncode == 0:
             closed = subprocess.run([sys.executable, '-B', str(Path(__file__).with_name('git_guard.py')),
-                                     'closed-milestone'], cwd=repo, capture_output=True, text=True)
+                                     'closed-milestone'], cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
             if closed.returncode:
                 raise ValueError(closed.stderr.strip() or 'Cannot verify the milestone branch is open.')
     if scope == 'project' and key == 'integration':

package/skills/gsd-path-undo/scripts/pipeline_undo.py

@@ -25,22 +25,30 @@ from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
 def _load_pipeline_modules():
-    try:
-        import archive_milestone
-        import isolation
-        import pipeline_git
-        import pipeline_state
-        import state_checkpoint
+    if __package__:
+        from . import archive_milestone
+        from . import isolation
+        from . import pipeline_git
+        from . import pipeline_state
+        from . import state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
-    except ModuleNotFoundError as error:
-        if error.name not in {
-            "archive_milestone",
-            "isolation",
-            "pipeline_git",
-            "pipeline_state",
-            "state_checkpoint",
-        }:
-            raise
+    else:
+        try:
+            import archive_milestone
+            import isolation
+            import pipeline_git
+            import pipeline_state
+            import state_checkpoint
+            return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
+        except ModuleNotFoundError as error:
+            if error.name not in {
+                "archive_milestone",
+                "isolation",
+                "pipeline_git",
+                "pipeline_state",
+                "state_checkpoint",
+            }:
+                raise
     try:
         from scripts import archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
@@ -94,7 +102,7 @@ UNDO_TRANSACTION_SCHEMA = pipeline_state.UNDO_TRANSACTION_SCHEMA
 UNDO_TRANSACTION_NAME = pipeline_state.UNDO_TRANSACTION_NAME
 ROADMAP_APPROVAL_SUBJECT = "roadmap: program roadmap approved"
 TASK_SUBJECT_RE = re.compile(r"^(T\d{3,}): .+")
-KINDS = ("checkpoint", "task", "uncommitted-archive", "lookahead")
+KINDS = ("checkpoint", "task", "member-task", "uncommitted-archive", "lookahead")
 PROMOTION_PREFIX = "router: promote lookahead milestone "
 ABANDON_PREFIX = "build: abandon milestone "
 INTEGRATE_PREFIX = "integrate: "
@@ -528,6 +536,7 @@ def _prepare_transaction(
     branch: str,
     archive: Optional[str],
     discussion: Optional[dict[str, bytes]],
+    member_fields: Optional[dict[str, str]] = None,
 ) -> dict[str, object]:
     transaction = {
         "schema": UNDO_TRANSACTION_SCHEMA,
@@ -545,6 +554,8 @@ def _prepare_transaction(
         ),
         "discussion": _encode_discussion(discussion),
     }
+    if member_fields is not None:
+        transaction.update(member_fields)
     _write_json(_git_path(repo, UNDO_TRANSACTION_NAME), transaction)
     return transaction
 
@@ -641,7 +652,7 @@ def _transaction_recovery_stage(
     expected_head = str(transaction["expected_head"])
     parent = str(transaction["parent"])
     current = _optional_rev(repo, "HEAD")
-    if transaction["kind"] == "checkpoint":
+    if transaction["kind"] in {"checkpoint", "member-task"}:
         allowed = {expected_head, parent}
     else:
         allowed = {expected_head}
@@ -662,8 +673,60 @@ def _transaction_recovery_stage(
     return "reset"
 
 
+def _member_undo_parent(repo: Path, member: str, landing: str) -> str:
+    """The member landing's parent, while that landing is the unpublished bound tip."""
+    checkout, _, entry = isolation._member_context(repo, member)
+    bound = entry["branch"]
+    if _run_git(checkout, "rev-parse", f"refs/heads/{bound}").stdout.strip() != landing:
+        raise UndoError(f"member {member} {bound} moved past this landing")
+    _require_member_unpublished(checkout, member, landing, bound)
+    return _run_git(checkout, "rev-parse", f"{landing}^").stdout.strip()
+
+
+def _require_member_unpublished(checkout: Path, member: str, landing: str, bound: str) -> None:
+    for ref, where in (("refs/remotes/origin/main", "origin/main"), (f"refs/remotes/origin/{bound}", f"origin/{bound}")):
+        if _run_git(checkout, "merge-base", "--is-ancestor", landing, ref, check=False).returncode == 0:
+            raise UndoError(f"member {member} landing is already on {where}")
+
+
+def _require_no_member_landing_journal(repo: Path) -> None:
+    directory = isolation.common_git_dir(repo).joinpath(*isolation.MEMBER_LANDING_DIR)
+    if any(directory.glob("*.json")):
+        raise UndoError("member landing journal is pending; recover member landing first")
+
+
+def _undo_member_landing(repo: Path, transaction: dict[str, object]) -> None:
+    """Reset the member bound branch first; a resumed undo finds it already reset."""
+    member = str(transaction["member"])
+    checkout, _, entry = isolation._member_context(repo, member)
+    tip = _run_git(checkout, "rev-parse", f"refs/heads/{entry['branch']}").stdout.strip()
+    if tip == transaction["member_parent"]:
+        _require_member_unpublished(checkout, member, str(transaction["landing"]), entry["branch"])
+        return
+    if tip != transaction["landing"]:
+        raise UndoError(f"member {member} bound branch moved during undo")
+    if _member_undo_parent(repo, member, str(transaction["landing"])) != transaction["member_parent"]:
+        raise UndoError(f"member {member} landing parent changed during undo")
+    bound = Path(isolation.member_bound_checkout(repo, member)["checkout"])
+    if _run_git(bound, "status", "--porcelain", "--untracked-files=all").stdout:
+        raise UndoError(f"member {member} bound checkout is dirty")
+    _run_git(bound, "reset", "--hard", str(transaction["member_parent"]))
+
+
 def _finish_transaction(repo: Path, transaction: dict[str, object]) -> None:
+    if transaction["kind"] == "member-task":
+        with isolation._member_landing_lock(repo):
+            _finish_transaction_locked(repo, transaction)
+        return
+    _finish_transaction_locked(repo, transaction)
+
+
+def _finish_transaction_locked(repo: Path, transaction: dict[str, object]) -> None:
+    if transaction["kind"] == "member-task":
+        _require_no_member_landing_journal(repo)
     stage = _transaction_recovery_stage(repo, transaction)
+    if transaction["kind"] == "member-task":
+        _undo_member_landing(repo, transaction)
     if stage == "prepared":
         _require_unpublished_reset(repo, str(transaction["branch"]))
         _reset_to(repo, str(transaction["parent"]))
@@ -675,11 +738,7 @@ def _finish_transaction(repo: Path, transaction: dict[str, object]) -> None:
         _remove_untracked_tree(repo, archive)
     path = _git_path(repo, UNDO_TRANSACTION_NAME)
     path.unlink()
-    descriptor = os.open(path.parent, os.O_RDONLY)
-    try:
-        os.fsync(descriptor)
-    finally:
-        os.close(descriptor)
+    pipeline_state._common.fsync_directory(path.parent)
 
 
 def classify_undo(repo: Path) -> dict[str, object]:
@@ -821,6 +880,28 @@ def classify_undo(repo: Path) -> dict[str, object]:
         proof_error = _task_proof_error(resolved, head)
         if proof_error:
             return _blocked([f"task landing ownership is unproven: {proof_error}"])
+        record = isolation.MEMBER_RECORD_RE.search(body)
+        if record is not None:
+            try:
+                _require_no_member_landing_journal(resolved)
+                member_parent = _member_undo_parent(resolved, record["member"], record["landing"])
+            except (IsolationError, UndoError, PipelineStateError) as error:
+                return _blocked([f"member landing undo is unsafe: {error}"])
+            return {
+                "kind": "member-task",
+                "branch": recorded_branch,
+                "head": head,
+                "parent": parent,
+                "subject": subject,
+                "member": record["member"],
+                "landing": record["landing"],
+                "member_parent": member_parent,
+                "effects": [
+                    f"reset member {record['member']} bound branch to {member_parent}",
+                    f"reset {recorded_branch} to {parent}",
+                ],
+                "blocked": [],
+            }
         return {
             "kind": "task",
             "branch": recorded_branch,
@@ -978,6 +1059,20 @@ def apply_undo(repo: Path, kind: str, expected_head: str) -> dict[str, object]:
             discussion,
         )
         _finish_transaction(resolved, transaction)
+    elif kind == "member-task":
+        with isolation._member_landing_lock(resolved):
+            _require_no_member_landing_journal(resolved)
+            if preview(resolved)["target"] != target:
+                raise UndoError("member task undo target changed after preview")
+            if _worktree_changes(resolved):
+                raise UndoError("worktree changed after member task undo preview")
+            _require_unpublished_reset(resolved, str(target["branch"]))
+            transaction = _prepare_transaction(
+                resolved, kind, expected_head, str(target["parent"]), str(target["branch"]), None, None,
+                {"member": str(target["member"]), "landing": str(target["landing"]),
+                 "member_parent": str(target["member_parent"])},
+            )
+            _finish_transaction_locked(resolved, transaction)
     elif kind == "task":
         parent = target["parent"]
         if not parent:

package/skills/gsd-path-undo/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,

package/skills/gsd-path-undo/scripts/worktree_paths.py

@@ -13,10 +13,13 @@ import os
 import tempfile
 from pathlib import Path
 
-try:
-    import _common
-except ImportError:
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:
+        from scripts import _common
 
 
 def _git(primary: Path, *args: str) -> str:
@@ -27,7 +30,10 @@ def _git(primary: Path, *args: str) -> str:
 
 
 def _identity(path: Path) -> str:
-    return hashlib.sha256(os.fsencode(path)).hexdigest()
+    digest = hashlib.sha256(os.fsencode(path)).hexdigest()
+    # Two identities nest in every managed path; full digests would use about
+    # 130 of Windows' 260-character MAX_PATH before any repository content.
+    return digest[:16] if os.name == "nt" else digest
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
@@ -65,7 +71,7 @@ def _workspace(primary: Path, pin: bool) -> Path:
         receipt.parent.mkdir(parents=True, exist_ok=True)
         fd, temporary = tempfile.mkstemp(dir=receipt.parent)
         try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
                 json.dump({"primary": str(primary), "root": str(workspace)}, handle)
             try:
                 os.link(temporary, receipt)
@@ -78,15 +84,19 @@ def _workspace(primary: Path, pin: bool) -> Path:
 
 def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
     primary = primary.resolve()
-    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+    if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
         raise ValueError("invalid managed worktree kind or name")
+    if kind == "bound":
+        return _workspace(primary, pin) / kind / name
     legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
               if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
     branch = f"refs/heads/gsd-path-{kind}/{name}"
     records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
     for record in records:
         fields = record.split("\0")
-        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+        # Compare as paths: git prints forward slashes on Windows.
+        worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
+        if legacy in worktrees and f"branch {branch}" in fields:
             return legacy
     # Keep collision checks and missing-directory recovery at the old location.
     if os.path.lexists(legacy):

package/skills/path/BUILD.md

@@ -3,7 +3,8 @@ name: gsd-path-build
 description: Execute or resume an approved GSD Path plan with isolated task worktrees, deterministic commits, and independent wave review. Use only when the user explicitly invokes $gsd-path-build or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Build Orchestrator
 
@@ -100,6 +101,11 @@ rule; never invoke an explicit-only sibling skill yourself.
 checkpoint `.project/` records uses this helper. Record the exact full HEAD
 before the first metadata change in that checkpoint, then run:
 
+Before dispatch, also checkpoint a pre-existing `.project/build/verify-ledger.jsonl`
+when it is an ignored regular file absent from HEAD, even if Git reports no
+other pending paths. The `build:` checkpoint validates and force-adds only
+that ledger; a malformed ledger blocks the checkpoint.
+
 Explicit configuration edits in `.project/config.json` and
 `.project/model-policy.json` are expected bookkeeping. Include them in the next
 normal checkpoint before a clean dispatch base; they may remain pending while

package/skills/path/DECIDE.md

@@ -3,7 +3,8 @@ name: gsd-path-decide
 description: Decide implementation direction from approved intent and complete research evidence, recording settled choices in SYNTHESIS.md. Use only when the user explicitly invokes $gsd-path-decide or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Decide Phase
 
@@ -24,7 +25,11 @@ checking. Legal entry is `research/done` or `decide/active|blocked`. On
 `research/done`, enter with `pipeline_state.py transition`, expected
 phase/status `research/done`, exact branch and archive values, event `decision
 synthesis started`, and set phase/status `decide/active` (plus the same
-lookahead project dir); never edit STATE directly. `decide/done` or any later phase blocks rather
+lookahead project dir). Resume `decide/blocked` through the same helper with
+the complete current state as expected, `--set-phase decide --set-status
+active`, event `decision synthesis resumed`, and the same lookahead project
+dir when supplied. Require the returned track state to be `decide/active`;
+never edit STATE directly. `decide/done` or any later phase blocks rather
 than replacing decisions beneath an existing plan. When an active router
 supplies the lookahead track root `.project/next/`, evaluate these
 preconditions against the track instead; see Lookahead mode. Require
@@ -60,8 +65,10 @@ rules are unchanged; never write an active-path artifact.
 
 1. Read the local [synthesis template](templates/synthesis.md),
    `.project/research/RESEARCH.md`, and the bundled `scripts/check_handoffs.py`;
-   resolve each to an absolute path. Run the research hand-off validator before
-   dispatch so decide receives a complete, intentional evidence set.
+   resolve each to an absolute path. At `decide/active`, before dispatch, run
+   `python3 <absolute check_handoffs.py> research --repo <absolute root>
+   [--project-dir .project/next]` so decide receives a complete, intentional
+   evidence set.
 2. Read the local [decider role](references/decider.md), then follow
    the local [runtime dispatch contract](references/dispatch.md) with
    deterministic logical task name `decide`. Give it absolute paths to the role,

package/skills/path/DEFINE.md

@@ -3,7 +3,8 @@ name: gsd-path-define
 description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Define Phase
 
@@ -281,6 +282,12 @@ runtimes without config support). Include that preference in the draft.
 Retain `Review panel:` as reviewed: the CHARTER copy, the explicit user choice,
 or the configured future preference. Quick lane keeps the panel off.
 
+When the active router recorded an `intent` pre-approval grant and the draft
+needs no answer from the user, run the router's `workflow_run.py preauthorize
+--kind intent` before asking. On `complete`, present Outcome and Review, say
+the owner's pre-approval passed this gate, and continue as approved. On
+`blocked`, ask as usual.
+
 After approval, finalize `.project/intent/INTENT.md` and run
 `pipeline_state.py transition` with expected `define/active`, the exact
 current milestone/branch/archive values, event `milestone intent approved`,

package/skills/path/DOCS-AUDIT.md

@@ -3,7 +3,8 @@ name: gsd-path-docs-audit
 description: Verify Markdown claims against the actual code, commands, and GSD Path artifacts. Use only when the user explicitly invokes $gsd-path-docs-audit or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Docs Audit
 
@@ -59,7 +60,8 @@ would dirty execution, invalidate review, or mutate shipped history.
    non-`.project` worktree changes, the orchestrator creates a verify sidecar
    with `python3 <absolute isolation.py> isolate-verify --repo <absolute
    primary> --base <HEAD> --name docs-audit` for project commands. The auditor
-   writes only its assigned output under that sidecar. Gate it there before
+   writes only its assigned output under that sidecar; its `Repo root` header
+   still names the absolute primary. Gate it there before
    collection. Then run `python3 <absolute isolation.py> collect-artifact
    --repo <absolute primary> --source <returned worktree> --base <recorded
    HEAD> --branch <returned branch> --source-path
@@ -74,8 +76,8 @@ would dirty execution, invalidate review, or mutate shipped history.
    it carries `none`. The auditor writes that baseline as `Audited HEAD`.
 2. Gate the artifact with the bundled helper: write the frozen inventory to
    a temporary file (one path per line) and run
-   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --inventory
-   <file> [--prior-audit <temporary prior-audit file>] [--changed <temporary
+   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --primary
+   <absolute primary> --inventory <file> [--prior-audit <temporary prior-audit file>] [--changed <temporary
    changed-set file>]`.
    It enforces the contract — every doc with at least one testable claim has
    a claims table, every claim a valid type and verdict with evidence, every

package/skills/path/INSPECT.md

@@ -3,7 +3,8 @@ name: gsd-path-inspect
 description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Inspect Phase
 
@@ -112,15 +113,15 @@ Preparation never changes phase state; neither command dispatches agents.
    includes its path and revision for project commands; expected new pipeline
    artifacts do not make product code dirty. Each agent writes only its
    assigned output under that sidecar and keeps it there for the gates in step
-   3. Otherwise no
+   3; its `Repo root` header still names the absolute primary. Otherwise no
    project command may run. The docs-auditor brief carries current HEAD as the
    audit baseline only when its verify sidecar was created at HEAD; otherwise
    it carries `none`. The auditor writes that baseline as `Audited HEAD`.
 3. Gate both artifacts against their templates: the codebase evidence needs
    a filled `## Map` plus findings as observed — no quota, but an empty
    findings section must say why; the docs audit must pass the bundled
-   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --audit
-   <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>`, where
+   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --primary
+   <absolute primary> --audit <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>`, where
    the audit path is `.project/research/DOCS-AUDIT.md` normally and
    `.project/next/research/DOCS-AUDIT.md` in Lookahead mode; add
    `--prior-audit <temporary prior-audit file>` when one was preserved and

package/skills/path/PLAN.md

@@ -3,7 +3,8 @@ name: gsd-path-plan
 description: Create and validate dependency-ordered GSD Path build waves and complete task contracts. Use only when the user explicitly invokes $gsd-path-plan or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Planning Phase
 
@@ -226,6 +227,11 @@ as stated in Lookahead mode.
    Before asking for approval, require exactly one panel artifact for non-off
    Config: `PLAN-PANEL.md` for `ready`, or `PLAN-PANEL.skipped.json` for
    `skipped`. Off Config requires neither. A mismatch blocks approval.
+   When the active router recorded a `plan` pre-approval grant, first run
+   `python3 <absolute workflow_run.py> preauthorize --repo <absolute root>
+   --kind plan`. On `complete`, present Outcome and Review, say the owner's
+   pre-approval passed this gate, and continue at step 6 as approved. On
+   `blocked`, ask as below.
    Ask one explicit next question: whether to approve this plan and start the
    build. When PLAN-PANEL.md has `Actionable: 0` or the panel did not run,
    list `Approve and start build (recommended)` first, with `Request changes`

package/skills/path/RESEARCH.md

@@ -3,7 +3,8 @@ name: gsd-path-research
 description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Research Phase
 

package/skills/path/ROADMAP.md

@@ -3,7 +3,8 @@ name: gsd-path-roadmap
 description: Slice an approved GSD Path program charter into a dependency-ordered roadmap of independently shippable milestones. Use only when the user explicitly invokes $gsd-path-roadmap or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Roadmap Phase
 

package/skills/path/SHIP.md

@@ -3,7 +3,8 @@ name: gsd-path-ship
 description: Verify a completed GSD Path milestone, manage evidence-backed patch decisions, request final shipping approval, and archive the validated result. Use only when the user explicitly invokes $gsd-path-ship or an active $gsd-path router or build orchestrator explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Ship Phase
 
@@ -82,10 +83,13 @@ so the position is unchanged. Then:
    This owns pending-discussion and landing checks, project Verify isolation,
    execution, output recording, collection, cleanup, and final-review reuse.
    Keep its JSON receipt; do not reconstruct those operations in shell calls.
-   Exact stdout/stderr live once in `.project/build/verify-ledger.jsonl`;
-   `final-gap-1.md` is the generated view referencing that entry. Re-entry at
-   the same command and commit reuses the execution, including a failed one,
-   and finishes interrupted collection without running the command again.
+   For a single-repo milestone, exact stdout/stderr live once in
+   `.project/build/verify-ledger.jsonl`; `final-gap-1.md` is the generated view
+   referencing that entry. For a member milestone, the gap records each member
+   head and holds the exact output; there is no reusable ledger entry.
+   Single-repo re-entry at the same command and commit reuses the execution,
+   including a failed one, and finishes interrupted collection without running
+   the command again.
    Missing legacy output requires evidence reconciliation, not a blind rerun.
    Any non-zero result stops this step; preserve its stderr and diagnose through
    the bundled forensics contract. Do not launch reviewers while project Verify
@@ -121,9 +125,10 @@ so the position is unchanged. Then:
    step 3 or create a fresh sidecar with `isolate-verify --name review-final`
    and dispatch the integration reviewer under logical task name
    `review_final`, assigning only
-   `.project/review/FINAL.md`. Its complete brief includes the exact recorded
-   project Verify ledger entry, every collected gap verdict so Overall verdict is
-   consistent with them, and PLAN.md's `## Surface contract` when INTENT.md
+   `.project/review/FINAL.md`. Its complete brief includes the project Verify
+   evidence from the ledger or the member milestone's gap output, every
+   collected gap verdict so Overall verdict is consistent with them, and
+   PLAN.md's `## Surface contract` when INTENT.md
    names surfaces — that reviewer performs each Walkthrough and records the
    surface and what it showed on every criterion the contract lists. Collect FINAL.md and retire its sidecar through the
    same helper flow.
@@ -253,6 +258,14 @@ The persisted `STATE.archive` field is the transaction identity.
    at the current HEAD is the only artifact-producing remedy. The archive helper independently binds every FINAL.md
    `SCn` heading id and normalized text to the archived INTENT.md; a renamed or
    easier criterion blocks even if the earlier handoff gate was bypassed.
+   For a multi-repo milestone (the archive holds `build/members.json`), run
+   `python3 <absolute archive_milestone.py> close-members --repo <root>`
+   after preflight passes and before recording shipment. It closes each
+   locked member in lock order in that member's integration mode and
+   journals each one. When it returns `awaiting-merge`, report the member PR
+   link, stop, and rerun the same command after the user merges it; never
+   merge a member PR yourself. When it returns `integrated`, keep its `body`
+   for the ship commit below.
 5. Only after preflight passes, record shipment through the journaled helper;
    for a program it atomically replaces both ROADMAP.md and STATE.md, setting
    the current entry to `Status: shipped` with the exact `Archive:` pointer:
@@ -270,10 +283,14 @@ The persisted `STATE.archive` field is the transaction identity.
    idempotent after completion. Stage only
    `.project/` paths, inspect the staged path list against the transaction and
    create the ship phase's one commit with exact subject
-   `ship: M00N — <milestone-slug>` and a body of exactly two consecutive lines,
+   `ship: M00N — <milestone-slug>`. For a single-repo milestone, its body has
+   exactly two consecutive lines,
    `Archive: .project/archive/<NNN>-<slug>` then
    `Reviewed-HEAD: <reviewed SHA>`, with no comment lines or blank line between them.
-   Write the subject, a blank line, and the two body lines to a message file,
+   A multi-repo milestone's body is exactly the `body` that `close-members`
+   returned: those two lines, then one `Member-Reviewed-HEAD:` and one
+   `Member:` line per member.
+   Write the subject, a blank line, and the body lines to a message file,
    then use `git commit -F <message-file>`. M00N and NNN come from STATE.archive.
    There is no untracked-project exception and no product or older-archive
    path may enter this commit.

package/skills/path/SKILL.md

@@ -3,13 +3,29 @@ name: path
 description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $path or $gsd-path. The status argument reports state without advancing; config views or edits settings without advancing. Do not infer this skill from generic project, next-step, or resume requests.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 ## Configuration mode
 
 When the first argument is `config`, read [Path settings](references/config.md)
 and complete that request without initializing state or advancing a phase.
 
+## Pre-approval
+
+`--pre-approve <kinds>` in the arguments (`intent`, `plan`, or `intent,plan`)
+grants those gates ahead of time for this run, for unattended quick lanes.
+After `.project/STATE.md` exists and before milestone intent approval, run
+`python3 <absolute pipeline_state.py> pre-approve --repo <absolute root>
+--grant <kinds>` once; its Log record is the grant. Write only the kinds the
+owner passed. A refused grant stops the run with the helper's message. Ship,
+roadmap, patch selection, and repository setup are never pre-approved. At a
+granted gate, the define or plan contract runs `python3 <absolute
+workflow_run.py> preauthorize --repo <absolute root> --kind <kind>` before
+asking: `complete` passes the gate through its normal approval command;
+`blocked` asks the owner as usual. A grant never answers an interview
+question, ruling, or `NEEDS-USER` item.
+
 # GSD Path Router
 
 Determine the current pipeline phase, report it briefly, and run the next valid
@@ -188,6 +204,34 @@ The current value resets from the project default at the next milestone.
 Both settings lock when build starts. A lookahead STATE inherits the active
 project's `integration_default` and uses it for `integration`.
 
+## Member repositories
+
+A coordinator project can change other repositories (members) in the same
+milestone; `.project/MEMBERS.md` lists them. Change members only at a
+milestone boundary, never during build or ship. Resolve the bundled
+`scripts/members.py` to an absolute path and use it; never edit MEMBERS.md
+or a member marker by hand.
+
+- To add an existing repository, it needs a GitHub.com `origin` whose default
+  is `main`, a clean worktree, and no active milestone of its own. Ask for the
+  member name, checkout path, and integration (`direct`, `pull-request`, or
+  `default`, which follows the milestone's choice), then run
+  `python3 <members.py> add --repo <absolute-root> --name <name> --checkout <path> --integration <mode>`.
+- To create a new member repository, present the exact `owner/name`,
+  visibility, and checkout path as the **Review** surface and get approval
+  first, as for a new GitHub repository. Then run the same command with
+  `--create <owner/name> --visibility <visibility>`. It journals the approved
+  target before creating anything; rerun the identical command to resume.
+- After adding a member, tell the user to install its guard hooks:
+  `npx @opengsd/gsd-path@latest --member-of <absolute-root> --project <member checkout>`.
+- `python3 <members.py> validate --repo <absolute-root>` checks every member;
+  `repair` rewrites stale markers; `detect --checkout <path>` reports whether a
+  repository is a member and of which coordinator.
+
+Build locks the members that tasks name and works in Path-owned member
+branches `gsd-path/<project>-M00N`. Ship runs `close-members` after preflight
+to merge each member in lock order, then ships the coordinator.
+
 ## Transaction recovery first
 
 For a helper failure, use the diagnostic in the sibling bundle: