@opengsd/gsd-path 1.3.1 → 1.4.0

package/scripts/workflow_run.py

@@ -5,27 +5,45 @@ import argparse
 import hashlib
 import json
 import os
+import re
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
 
 try:
-    from scripts import _common
+    from scripts import _common, isolation
 except ImportError:  # bundled copy inside a skill's scripts directory
     import _common
+    import isolation
 
 
 class StepFailed(RuntimeError):
     pass
 
+
+def _table_rows(body):
+    """Cells of a Markdown table's data rows (header and separator skipped)."""
+    lines = [line.strip() for line in (body or "").splitlines() if line.strip().startswith("|")]
+    return [[cell.strip() for cell in re.split(r"(?<!\\)\|", line.strip("|"))] for line in lines[2:]]
+
 INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
                     ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
 
 
+def _task_member(repo: Path, project_dir: str, task_id: str):
+    """The `repo:` member a task names, or None for a coordinator task."""
+    for path in sorted((repo / project_dir / "tasks").glob(f"{task_id}-*.md")):
+        fields, error = isolation.task_frontmatter(path.read_text(encoding="utf-8"))
+        if error:
+            raise StepFailed(error)
+        return fields.get("repo")
+    return None
+
+
 def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
                  task_id: str = None, round_size: int = None, inspection: Path = None,
-                 mapper_reviewed: bool = False) -> dict:
+                 mapper_reviewed: bool = False, kind: str = None) -> dict:
     steps = []
     outputs = {}
     scripts = Path(__file__).resolve().parent
@@ -33,7 +51,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
 
     def step(script, *arguments, raw=False):
         command = [sys.executable, "-B", str(helpers / script), *arguments]
-        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        completed = subprocess.run(command, cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
         receipt = {"script": script, "command": command, "exit_code": completed.returncode,
                    "stdout": completed.stdout, "stderr": completed.stderr}
         steps.append(receipt)
@@ -50,12 +68,29 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
         return receipt["result"]
 
     common = ["--repo", str(repo), "--project-dir", project_dir]
+    next_step = "$gsd-path-forensics"
+
+    def gate_plan():
+        if step("discussion_records.py", "pending", "--repo", str(repo))["pending"]:
+            raise StepFailed("pending discussion requires its owner disposition")
+        step("check_handoffs.py", "plan", *common)
+        head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                              cwd=repo, capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
+        step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+             "--tasks-dir", f"{project_dir}/tasks")
+        panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                 "--intent", str(repo / project_dir / "intent/INTENT.md")]
+        charter = repo / ".project/CHARTER.md"
+        if charter.exists():
+            panel += ["--charter", str(charter)]
+        return step("review_panel.py", *panel)
+
     try:
         if os.path.lexists(repo / ".gsd-path/runtime.json"):
             resolved = subprocess.run(
                 [sys.executable, "-B", str(repo / ".gsd-path/status_runtime.py"),
                  "--repo", str(repo), "--runtime-path"],
-                cwd=repo, capture_output=True, text=True)
+                cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
             if resolved.returncode:
                 sys.stderr.write(resolved.stderr)
                 raise StepFailed(resolved.stderr.strip())
@@ -71,7 +106,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                    (repo / project_dir / "research" / spec[3]).is_symlink() for spec in specs):
                 raise StepFailed("prior inspection evidence requires the re-inspection contract")
             branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
-                                    capture_output=True, text=True, check=True).stdout.strip()
+                                    capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
             if branch != state["branch"]:
                 raise StepFailed("current branch differs from the recorded inspection branch")
             pending = step("discussion_records.py", "pending", "--repo", str(repo))
@@ -87,7 +122,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                         raise StepFailed(f"missing inspection resource: {path}")
             staging = Path(tempfile.mkdtemp(prefix="gsd-path-inspect-"))
             inventory_file = staging / "inventory.txt"
-            inventory_file.write_text(inventory, encoding="utf-8")
+            inventory_file.write_bytes(inventory.encode("utf-8"))
             assignments = []
             for task_name, role, template, filename in specs:
                 isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
@@ -100,13 +135,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                          f"Template: {template_path}\nRepository and command cwd: {isolated['worktree']}\n"
                          f"Recorded baseline and Audited HEAD: {isolated['base']}\n"
                          f"Write only: {Path(isolated['worktree']) / output}\n"
+                         f"Write header Repo root: {repo}\n"
                          "Use only this supplied sidecar for project commands; do not create worktrees.\n"
                          "The parent owns gates, collection, retirement, and phase state.\n"
                          "Exclude .git, node_modules, .project/archive, and installed GSD Path and path skill bundles.\n")
                 if task_name == "inspect_docs":
                     brief += ("Alignment mode: false. No prior audit or changed set.\n"
                               "Frozen inventory follows; use it exactly, without rediscovery:\n" + inventory)
-                brief_file.write_text(brief, encoding="utf-8")
+                brief_file.write_bytes(brief.encode("utf-8"))
                 assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
                                     "template": str(template_path), "output": output,
                                     "brief_file": str(brief_file)})
@@ -136,16 +172,16 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             if state["phase"] != "inspect" or state["status"] != "active":
                 raise StepFailed("inspection completion requires inspect/active")
             branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
-                                    capture_output=True, text=True, check=True).stdout.strip()
+                                    capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
             if state["branch"] != branch:
                 raise StepFailed("current branch differs from the recorded inspection branch")
             pending = step("discussion_records.py", "pending", "--repo", str(repo))
             if pending["pending"]:
                 raise StepFailed("pending discussion requires its owner disposition")
             docs = assignments["inspect_docs"]
-            step("check_docs_audit.py", "--repo", docs["worktree"], "--audit", docs["output"],
-                 "--inventory", str(inventory_file))
-            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text().splitlines():
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--primary", str(repo),
+                 "--audit", docs["output"], "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text(encoding="utf-8").splitlines():
                 raise StepFailed("audit does not name the supplied inspection baseline")
             for task_name, _, _, _ in INSPECTION_SPECS:
                 assignment = assignments[task_name]
@@ -161,10 +197,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                  "--set-phase", "inspect", "--set-status", "done", "--event", "inspection artifacts passed")
         elif action == "lint-round":
             head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
-                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+                                  cwd=repo, capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
             step("check_task_briefs.py", "--repo", str(repo), "--base", head,
                  "--tasks-dir", f"{project_dir}/tasks")
             step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task" and _task_member(repo, project_dir, task_id):
+            # A member task works in a sidecar of its member; its Verify runs there at finish.
+            step("isolation.py", "isolate-member-task", "--repo", str(repo),
+                 "--member", _task_member(repo, project_dir, task_id), "--task-id", task_id)
         elif action == "prepare-task":
             task = step("isolation.py", "isolate-task", "--repo", str(repo),
                         "--base", expected_head, "--task-id", task_id,
@@ -186,33 +226,64 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                 raise StepFailed("pending discussion requires its owner disposition")
             step("build_state.py", "verify-landed", *common, "--head", expected_head)
             step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
-        else:
-            pending = step("discussion_records.py", "pending", "--repo", str(repo))
-            if pending["pending"]:
+        elif action == "preauthorize":
+            # A block here is not a failure: the gate asks its owner as usual.
+            next_step = "ask the owner at this gate"
+            if project_dir != ".project" or kind not in {"intent", "plan"}:
+                raise StepFailed("pre-approval covers only intent or plan on the active track")
+            routed = step("pipeline_state.py", "route", *common)
+            if routed["route"].get("action") != "run-phase" or "recovery" in routed:
+                raise StepFailed("pre-approval needs an ordinary phase route")
+            if step("discussion_records.py", "pending", "--repo", str(repo))["pending"]:
                 raise StepFailed("pending discussion requires its owner disposition")
-            step("check_handoffs.py", "plan", *common)
-            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
-                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
-            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
-                 "--tasks-dir", f"{project_dir}/tasks")
-            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
-                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
-            charter = repo / ".project/CHARTER.md"
-            if charter.exists():
-                panel += ["--charter", str(charter)]
-            step("review_panel.py", *panel)
+            track = repo / project_dir
+            intent = (track / "intent/INTENT.md").read_text(encoding="utf-8")
+            lane = re.search(r"(?m)^Lane:\s*(.+)$", intent)
+            if not lane or lane.group(1).split("<!--", 1)[0].strip().strip("`") != "quick":
+                raise StepFailed("pre-approval covers only the quick lane")
+            intent = re.sub(r"(?s)<!--.*?-->", "", intent)
+            if re.search(r"(?m)^\s*-\s*\[(RESEARCH|NEEDS-USER)\]", _common.section_body(intent, "Open questions") or ""):
+                raise StepFailed("INTENT.md has open RESEARCH or NEEDS-USER questions")
+            audit_path = track / "research/DOCS-AUDIT.md"
+            if audit_path.exists():
+                audit = audit_path.read_text(encoding="utf-8")
+                queue = _table_rows(_common.section_body(audit, "Remediation queue"))
+                ruled = set()
+                for row in _table_rows(_common.section_body(audit, "User rulings")):
+                    if len(row) != 4 or row[1] not in {"fix-code", "fix-doc", "accept-drift"}:
+                        continue
+                    words = row[2].strip().strip('`"').strip()
+                    if words and words.casefold() != "none" and not re.fullmatch(r"<[^>]*>", words):
+                        ruled.add(row[0])
+                if any(len(row) == 6 and row[4] == "NEEDS-USER" and row[0] not in ruled for row in queue):
+                    raise StepFailed("DOCS-AUDIT.md has NEEDS-USER rows without a user ruling")
+            if kind == "plan":
+                if gate_plan()["mode"] != "off":
+                    raise StepFailed("pre-approval requires review_panel off")
+                plan = re.sub(r"(?s)<!--.*?-->", "", (track / "plan/PLAN.md").read_text(encoding="utf-8"))
+                config = _common.section_body(plan, "Config") or ""
+                skeptics = re.search(r"(?m)^[ \t]*-[ \t]*finding_skeptics:[ \t]*(\S+)", config)
+                if skeptics and skeptics.group(1) != "off":
+                    raise StepFailed("pre-approval requires finding_skeptics off")
+                # Quick-lane limit from project policy (gsd-path-plan Quick mode): one wave, at most two tasks.
+                if (len(re.findall(r"(?m)^## Wave \d+ — ", plan)) != 1
+                        or len(list((track / "tasks").glob("T[0-9][0-9][0-9]-*.md"))) > 2):
+                    raise StepFailed("pre-approval requires one wave and at most two tasks")
+            step("pipeline_state.py", "pre-approve", "--repo", str(repo), "--use", kind)
+        else:
+            gate_plan()
             if action == "approve-plan":
                 step("pipeline_state.py", "approve", *common, "--kind", "plan",
                      "--expected-head", expected_head)
     except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
         return {"status": "blocked", "reason": str(error), "steps": steps,
-                "next": "$gsd-path-forensics"}
+                "next": next_step}
     return {"status": "complete", "steps": steps, **outputs}
 
 
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"))
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect", "preauthorize"))
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
     parser.add_argument("--expected-head")
@@ -220,15 +291,18 @@ def main(argv=None):
     parser.add_argument("--round-size", type=int)
     parser.add_argument("--inspection", type=Path)
     parser.add_argument("--mapper-reviewed", action="store_true")
+    parser.add_argument("--kind", choices=("intent", "plan"))
     arguments = parser.parse_args(argv)
     if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"} and not arguments.expected_head:
         parser.error(f"{arguments.action} requires --expected-head")
     if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
         parser.error("prepare-task requires --task-id and --round-size")
+    if arguments.action == "preauthorize" and not arguments.kind:
+        parser.error("preauthorize requires --kind")
     result = run_workflow(arguments.repo.resolve(), arguments.action,
                           arguments.project_dir, arguments.expected_head,
                           arguments.task_id, arguments.round_size, arguments.inspection,
-                          arguments.mapper_reviewed)
+                          arguments.mapper_reviewed, arguments.kind)
     print(json.dumps(result, sort_keys=True))
     return 0 if result["status"] == "complete" else 1
 

package/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/gsd-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/gsd-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/gsd-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/gsd-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/gsd-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/gsd-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/gsd-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/gsd-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/gsd-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.