@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-migrate/scripts/core_hook_gate.py

@@ -12,6 +12,9 @@ def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repo", required=True, action="append", type=Path)
     parser.add_argument("--command", required=True)
+    # Windows wrappers record bash: the host ran the original through Git Bash,
+    # and shell=True would run it through cmd.exe instead.
+    parser.add_argument("--shell", choices=("bash",))
     args = parser.parse_args()
     payload = sys.stdin.buffer.read()
     try:
@@ -26,7 +29,13 @@ def main():
     except (OSError, ValueError, RuntimeError):
         # An uncertain event keeps the original hook's protection and errors.
         pass
-    result = subprocess.run(args.command, shell=True, input=payload)
+    if args.shell == "bash":
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import _common
+
+        result = subprocess.run(_common.bash_argv(args.command), input=payload)
+    else:
+        result = subprocess.run(args.command, shell=True, input=payload)
     return result.returncode if result.returncode >= 0 else 128 - result.returncode
 
 

package/skills/gsd-path-migrate/scripts/core_hook_settings.py

@@ -8,7 +8,6 @@ import os
 from pathlib import Path
 import shlex
 import stat
-import subprocess
 import sys
 import tempfile
 
@@ -47,8 +46,15 @@ def plan(args):
     gate = Path(__file__).resolve().with_name("core_hook_gate.py")
     if not gate.is_file():
         raise ValueError(f"missing installed hook gate: {gate}")
-    argv = [sys.executable, "-B", str(gate), "--repo", str(repo), "--command", original]
-    replacement = subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+    if os.name == "nt":
+        # Claude Code runs Windows hook commands in Git Bash: quote for bash,
+        # use forward slashes, and have the gate run the original through bash
+        # rather than cmd.exe.
+        argv = [Path(sys.executable).as_posix(), "-B", gate.as_posix(), "--repo", repo.as_posix(),
+                "--shell", "bash", "--command", original]
+    else:
+        argv = [sys.executable, "-B", str(gate), "--repo", str(repo), "--command", original]
+    replacement = shlex.join(argv)
     entry["command"] = replacement
     after = (json.dumps(data, indent=2) + "\n").encode()
     receipt = {
@@ -60,7 +66,8 @@ def plan(args):
         "after": base64.b64encode(after).decode(),
     }
     # Settings may contain secrets; the review/rollback copy is owner-only.
-    with open(args.receipt, "x", encoding="utf-8", opener=lambda path, flags: os.open(path, flags, 0o600)) as handle:
+    with open(args.receipt, "x", encoding="utf-8", newline="\n",
+              opener=lambda path, flags: os.open(path, flags, 0o600)) as handle:
         json.dump(receipt, handle, indent=2)
         handle.write("\n")
     return {"status": "planned", "receipt": str(args.receipt.absolute())}

package/skills/gsd-path-migrate/scripts/discussion_records.py

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

package/skills/gsd-path-migrate/scripts/loop_run.py

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

package/skills/gsd-path-migrate/scripts/migrate_core.py

@@ -119,8 +119,8 @@ def prepare(repo, output, files, manifest):
             target.parent.mkdir(parents=True, exist_ok=True)
             target.write_bytes(content)
         manifest = dict(manifest, status="prepared", output=str(output))
-        (output / "manifest.json").write_text(
-            json.dumps(manifest, indent=2) + "\n", encoding="utf-8"
+        (output / "manifest.json").write_bytes(
+            (json.dumps(manifest, indent=2) + "\n").encode("utf-8")
         )
     except BaseException:
         shutil.rmtree(output)

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

@@ -13,7 +13,7 @@ sys.dont_write_bytecode = True
 ROLES = ('coder', 'reviewer', 'review_panel', 'skeptic', 'inspect_codebase',
          'inspect_docs', 'docs_audit', 'research', 'decide', 'roadmap', 'plan', 'plan_patch')
 HOSTS = ('codex', 'claude', 'grok', 'opencode', 'copilot', 'qwen', 'antigravity',
-         'cursor', 'zed', 'kiro', 'kimi')
+         'cursor', 'zed', 'kiro', 'kimi', 'muse')
 
 
 def sibling(name):
@@ -73,8 +73,8 @@ def validate_value(key, value):
     if not isinstance(value, str) or not value or value != value.strip():
         raise ValueError(f'{key} requires a nonempty string')
     if key == 'integration':
-        if value not in ('direct', 'pull-request'):
-            raise ValueError('integration must be direct or pull-request')
+        if value not in ('direct', 'pull-request', 'external-landing'):
+            raise ValueError('integration must be direct, pull-request, or external-landing')
     elif key == 'review_panel':
         if any(char.isspace() for char in value):
             raise ValueError('use off, detected, or comma-separated families without spaces')
@@ -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-migrate/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-plan/SKILL.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
 
@@ -114,9 +115,10 @@ as stated in Lookahead mode.
      In patch mode, tasks already `done` keep their landed metadata; only
      the appended patch tasks must start clean.
    - Require every dependency id to exist, forbid later-wave dependencies,
-     detect cycles, and forbid file overlap between planned tasks in the same
-     wave. Same-wave dependency chains are allowed only when their files do
-     not overlap; the build executes them in dependency layers.
+     detect cycles, and forbid unordered file overlap between planned tasks
+     in the same wave. Same-wave tasks may share files only when one
+     transitively depends on the other through `deps`; the build executes
+     them in dependency layers.
    - Reject a declared dependency that carries neither data nor a prerequisite
      effect. A `deps` edge is valid only when the dependent consumes a symbol,
      signature, schema, endpoint, file format, or path named in that
@@ -156,6 +158,13 @@ as stated in Lookahead mode.
      command's output — not an internal unit test.
      Require the surface to land in the same wave as the capability behind
      it, never in a later polish wave.
+   - When INTENT.md has `## Edge coverage`, require a PLAN.md
+     `## Held-out checks` row for every `held-out` edge and for no other
+     edge. The named test is in that task's `files`, the task's Verify runs
+     it, and the task's Acceptance criteria state the edge id and its ruling
+     (see [spec-reach probes](references/spec-probes.md)). An edge or
+     prohibition ruled `criterion SCn` needs no extra row; it is covered as
+     SCn. Put each `judgment` prohibition in its owning task's Approach.
    - Prove every intent constraint and synthesis decision is covered, that no
      scope-out veto appears in a task, and that `Project verify` is a real,
      non-placeholder command in PLAN.md. Every Verify — task and project —
@@ -226,6 +235,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-plan/references/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

package/skills/gsd-path-plan/references/operating-rules.md

@@ -0,0 +1,214 @@
+# Operating rules for phase work
+
+These rules extend the project `AGENTS.md` block. Every GSD Path skill
+bundles this file; spawned agents follow their role brief instead.
+
+## Files and state
+
+- `.project/discuss/DIALOGUE.md` and `.project/discuss/ANSWERS.md` are the
+  append-only memory for any-phase discussion. Read them before continuing an
+  existing thread; never treat chat history alone as durable context.
+- The discussion skill never commits. Every phase orchestrator treats only
+  complete append-only discussion records as expected bookkeeping and includes
+  them in its next normal `.project/` checkpoint; build does so before its next
+  clean layer base, and ship includes them in its transaction.
+- Write every output to the handoff path in WORKFLOW.md, using the absolute
+  bundled template path supplied by the active phase skill. An output that
+  needs verbal explanation is defective.
+- With no `.project/STATE.md`, route through the bundled
+  `scripts/detect_project.py initialize --repo <absolute-root> --template
+  <absolute-state-template> --require-git` helper; `route: setup-repository`
+  leaves the invocation folder unchanged and routes to repository setup before
+  state creation or branch binding. Never delete the invocation folder or its
+  state to satisfy bootstrap path checks. Do not classify from a directory listing
+  or conversation. Follow its JSON `verdict` and `route`. Reserve `classify`
+  for read-only inspection; do not use it as a state-initialization preflight.
+- `.project/STATE.md` tracks phase position. Parse and validate it only with
+  the bundled `scripts/pipeline_state.py validate` command, route with its
+  `route` command, and make ordinary phase transitions only with its
+  expected-state `transition`. A journaled transaction helper may write only
+  the state fields its contract explicitly owns. Never reproduce these
+  deterministic operations in model reasoning. The
+  orchestrator alone owns task frontmatter base, isolated worktree/branch,
+  status, and agent; the landing commit is proven from git by `isolation.py
+  recover`, never recorded. Require `pipeline: gsd-path/v2`; never
+  consume an ambiguous or differently owned state file. Artifacts outrank
+  summaries; reconcile STATE.md when it disagrees with task frontmatter.
+  During a program build, `.project/next/STATE.md` may hold
+  the lookahead planning track for the next milestone; it follows the same
+  marker rule, owns no task frontmatter, and never binds a branch.
+- STATE.integration_default is the project closeout choice and
+  STATE.integration is the current milestone choice. Both are `direct` or
+  `pull-request`; STATE.integration_source is `default` or `milestone` and
+  preserves explicit override provenance. Older v2 state defaults to `direct`,
+  and modes may be changed only through `pipeline_state.py
+  configure-integration` before build. A next milestone resets its current
+  choice from the project default.
+- Spawned agents have isolated context. Follow the installed runtime dispatch
+  contract and brief them with exact input and output paths, constraints, a
+  deterministic logical task name, and a bounded responsibility. Independent
+  briefs may run in parallel up to available child capacity; a dependent
+  brief runs as soon as its dependencies complete.
+
+## Stay in role
+
+- The codebase mapper and docs auditor observe and verify; they are strictly
+  read-only, report observations rather than judgments, and never resolve a
+  doc-vs-code conflict — that ruling belongs to the user.
+- Build, test, lint, and help commands are not presumed read-safe. Read-only
+  roles run project commands only in orchestrator-created disposable worktrees
+  at a recorded revision; otherwise they use static evidence or mark the check
+  unverifiable. They never create worktrees or run commands in the source tree.
+- Researchers gather evidence; they do not decide. A dimension is researched
+  only when it has open questions; the research phase records dispatched and
+  skipped dimensions. Brownfield adds `evidence-codebase.md` as settled input.
+- The decider works from existing evidence; it does not re-research. An
+  unresolved or uncited required decision fails the synthesis gate.
+- The planner reads both INTENT.md and SYNTHESIS.md and specs
+  deliverable-sized outcomes and constraints; every INTENT success criterion
+  maps to a task AC and Verify in PLAN.md Intent coverage. Coders own
+  implementation decisions inside those bounds.
+- Coders implement only their full task contract, including owned INTENT
+  success criteria read from INTENT.md, and append their result to the
+  task Log. They never change task state, review acceptance, stage, commit, or
+  freelance outside declared files.
+- The orchestrator dispatches, arbitrates, and creates task isolation and
+  verify sidecars through the bundled `scripts/isolation.py` helper — named
+  branches only, never a detached HEAD — lands task work serially, and
+  records each clean base in task frontmatter; `land` stamps the landed
+  state into the task's own commit, so a task has exactly one commit. It
+  writes no product code. When a done task's work already sits on the bound
+  branch without a landing commit, only an explicit owner ruling through
+  `isolation.py attest` may stand in for it: one `.project/`-only commit that
+  names the base, the attested HEAD, the declared files that changed, the
+  task Verify recorded as passing at that HEAD, and the ruling verbatim.
+  `recover` reports it as `attested`, never as a proven landing.
+- All pipeline work for a milestone lives on `gsd-path/M00N` (M001, M002,
+  …) bound in STATE.branch. The next milestone binds a new unused
+  `gsd-path/M00N` at the remote default after the previous ship integrates.
+  Integration at ship is the only path from the bound branch to the default
+  branch — either Path's direct merge or a Path-owned PR merged by the user.
+  The bound branch never receives merges or back-merges and is never the
+  GitHub default.
+- After initialization writes STATE.md, and before entering the first pipeline
+  phase in an existing Git repository, the router calls
+  `scripts/pipeline_git.py bind-initial` with the selected M00N and exact
+  fetched `origin/main` SHA. The helper alone checks worktree identity and
+  cleanliness, exact base, and every local, remote, and other-worktree
+  collision before creating or adopting the branch. The sole cleanliness
+  exception is untracked `.project/STATE.md`: validated v2 state in active
+  inspect or define, with null milestone, branch, and archive, in a real
+  directory containing only that regular file with no hard links. The helper
+  checks its identity and bytes across binding. Do not commit initialization
+  before binding. The router persists its
+  typed result in the new state. Build has no branch-creation authority.
+- After `validate-integrated` passes and before any next-milestone file
+  changes, the router calls the bundled `scripts/pipeline_git.py bind-next`
+  helper with the previous bound branch, exact ship SHA, and exact current
+  `origin/main` SHA. The helper moves the clean primary worktree to the new
+  unused `gsd-path/M00N` branch at that SHA without moving the previous
+  branch or entering the default checkout, then retires the integrated
+  previous branch — deleted locally and on origin; the ship commit stays
+  reachable from the integration merge and its annotated tag. The router
+  persists the new branch in STATE; a wrong-SHA or colliding branch blocks.
+  After validated PR integration, `bind-next --allow-missing-previous` may
+  retire only the local previous branch when GitHub already auto-deleted its
+  remote branch.
+  `bind-initial`, this handoff, and the approved new-repository bootstrap are
+  the only bound-branch creation authorities, and the handoff's retirement
+  push is the router's only bound-branch deletion authority. When a lookahead
+  track exists, the router then calls `scripts/pipeline_state.py promote-next`;
+  only that journaled helper moves the track, updates state and roadmap,
+  classifies plan drift, and writes the router promotion commit.
+- Build adopts the branch recorded in STATE.branch, never whatever is current
+  when a recorded branch exists. A new-GitHub REPOSITORY.md proves the
+  default checkout and first bound branch; later milestones may rebind
+  `gsd-path/M00N` without rewriting that artifact. Build ignores older
+  milestone ship and integrate commits inherited through main. A ship commit
+  for the current STATE.branch milestone must be an ancestor of origin/main;
+  if it is not, that milestone's integration is incomplete and control routes
+  to ship, not build. Direct mode requires the matching canonical `integrate:`
+  commit; PR mode requires tag metadata and a two-parent merge whose second
+  parent is the ship commit. A null branch returns
+  to the router; build never creates, selects, switches, or rebinds it.
+- The ship phase makes exactly one commit on the bound branch — the
+  `.project/`-only ship commit recording
+  STATE.md, the final-review artifacts, and the archive — and additionally
+  owns the integration leg. Direct mode creates and pushes one `--no-ff` merge
+  onto `main` with subject
+  `integrate: M00N — merge gsd-path/M00N into main`. Pull-request mode creates
+  or reuses one GitHub.com PR and waits for the user to merge it with a merge
+  commit; it never auto-merges. Both modes create one annotated
+  `milestone/<NNN>-<slug>` tag after merge validation.
+  The roadmap and
+  plan phases each make exactly one approval checkpoint commit
+  (`.project/`-only, deferred to the build transition commit during a
+  new-repository transaction or before Git exists). Their bundled
+  `pipeline_state.py approve` command journals before changing STATE or
+  ROADMAP.md and owns that canonical checkpoint; a routed
+  `resume-checkpoint` must finish before phase work. The router makes one
+  bookkeeping commit through `pipeline_state.py promote-next` when promoting a
+  lookahead track at a milestone boundary. Every other commit belongs to the
+  orchestrator.
+- Reviewers verify and block; they never fix. A block names the criterion,
+  observed result, evidence location, and concrete fix direction. An optional
+  review panel is advisory: the canonical reviewer remains the only wave
+  pass/fail, and panel findings never average or auto-replan. Same-model
+  agreement is not independent verification: matching verdicts from one
+  model family count as a single evidence path. Independence comes from
+  re-run commands, reconstructed patches, different sources, or a
+  different model family. Resolve panel
+  membership with the bundled `scripts/review_panel.py` helper; do not invent
+  model families or slugs. Create task isolation and verify sidecars with the
+  bundled `scripts/isolation.py` helper; do not invent `git worktree add` or
+  `--detach`. Undo unpublished pipeline work with `scripts/pipeline_undo.py`;
+  do not invent `git reset`. Diagnose a stuck pipeline with
+  `scripts/pipeline_diagnose.py`.
+- A bundled helper that exits non-zero stops the current step. Print its
+  stderr verbatim, run `scripts/pipeline_diagnose.py diagnose --repo
+  <absolute-root>` (bundled with `$gsd-path-forensics`), and report both.
+  Do not rerun the same command unchanged unless the helper's own contract
+  names that exact rerun as its interruption recovery. Never repair state or
+  Git by hand instead.
+- The discussion sidecar may run during any non-shipped phase. It grounds
+  answers in code and phase artifacts, may perform focused research when
+  needed, and writes only its discussion artifacts; it never changes phase
+  state or bypasses a phase gate.
+- During an uncommitted archive transaction, discussion writes a complete
+  active copy that extends the archived pair. The ship phase reruns `prepare`;
+  the helper validates the prefix and atomically reconciles both files.
+  Discussion never edits an archive directly or writes after shipment.
+- The loop runner wraps explicit skills in a bounded check → verify → fix →
+  verify pass driven by a LOOP.md spec. It never advances a phase gate
+  itself and never commits or pushes.
+- Fix tasks use the complete task template, not an abbreviated finding.
+
+## New GitHub repositories
+
+- Create a GitHub repository only from an explicit user request followed by an
+  approval of the exact owner/name, visibility, default-checkout path,
+  `gsd-path/M001` branch, and linked primary-worktree path. Before the
+  external action produces an artifact, present those proposed targets as the
+  inline **Review** surface using the active router's preview contract.
+  Do not write a
+  preview file into the invocation directory or another repository. Run the
+  bundled bootstrap helper's read-only `preview` command for this evidence.
+- After approval, the bootstrap helper persists the exact targets under the
+  approved workspace before the first external mutation. Its `create` command
+  creates or verifies the remote, checkout, branch, and linked worktree one
+  stage at a time. A matching journal permits explicit resume and adoption; a
+  collision without that journal blocks. The helper removes the journal only
+  after writing owned STATE.md and fixed-format `.project/REPOSITORY.md` in the
+  linked worktree.
+- During an approved new-repository transaction, the router may create the
+  first GSD Path branch and linked primary worktree at the verified
+  remote-default SHA and persist that branch in STATE.md and REPOSITORY.md.
+  Build must verify and adopt that exact binding from REPOSITORY.md, never a
+  free-form log. Task branches and task worktrees remain exclusively
+  build-orchestrator owned.
+- Keep the cloned default checkout clean on the remote default branch. Run the
+  pipeline from the linked GSD Path worktree; never initialize `.project/` in
+  the default checkout, reuse an existing branch or path (except an explicitly
+  approved empty linked-worktree folder via `--reuse-empty-worktree`), move an existing
+  repository, or recover a partial GitHub creation without the exact approved
+  journal and re-verification.

package/skills/gsd-path-plan/references/planner.md

@@ -38,8 +38,9 @@ the how.
    security-critical; `verify-only` suits polish and low-risk feature waves
    whose Verify commands meaningfully cover the criteria.
 
-Every dependency must be in an earlier wave or in the same wave with no file
-overlap. Produce an acyclic graph; same-wave chains execute in layers.
+Every dependency must be in an earlier wave or in the same wave. Same-wave
+tasks may share files only when one transitively depends on the other. Produce
+an acyclic graph; same-wave chains execute in layers.
 
 Declare a dependency only when something real crosses it: data — the dependent
 consumes a symbol, signature, schema, endpoint, file format, or path named in
@@ -72,8 +73,17 @@ plan order above, which still keeps plan-invalidating risk in wave 1.
   criterion may appear in only one surface block. Put the surface in the same
   wave as the capability behind it. A milestone with a surface is not done
   when only its internals run.
+- When INTENT.md carries `## Edge coverage` or `## Prohibitions` (read the
+  supplied [spec-reach probes](spec-probes.md)), treat every ruling as a hard
+  limit on its criterion. For each `held-out` edge, write one PLAN.md
+  `## Held-out checks` row: a test file in the owning task's `files`, a
+  Verify that runs it, and an Acceptance criterion that names the edge id
+  and states its ruling from Detail. Omit the section when no edge is
+  held-out. Put each `judgment` prohibition's Must not and Detail in the
+  owning task's Approach.
 - Make `files` exhaustive, including imports, routes, generated artifacts,
-  tests, and wiring. Require disjoint files for same-wave tasks.
+  tests, and wiring. Require disjoint files for same-wave tasks that are not
+  dependency-ordered.
 - Write an Interface contract in every task: `None` for independent tasks;
   for any tasks that exchange a symbol, signature, schema, endpoint, file
   format, or path, the exact shapes both sides code against — identical text
@@ -86,6 +96,14 @@ plan order above, which still keeps plan-invalidating risk in wave 1.
   this task's work is skipped. That command must name a path from `files`,
   and must not be PLAN.md's project Verify unless an SC this task owns names
   that command. Criteria and Verify are the contract; Approach is guidance.
+- In a multi-repo milestone (`.project/MEMBERS.md` lists members), each task
+  changes exactly one repo. Give a member task `repo: <member>`; its `files`
+  and Verify are relative to that member's root, and its Verify runs there.
+  Coordinator tasks omit `repo:`. Split work that spans repos into one task
+  per repo joined by an Interface contract. PLAN.md's project Verify runs
+  from the coordinator root and reaches a member as `../<member>`. Do not
+  plan a task for a member this milestone already closed at ship; plan it in
+  the next milestone.
 - Preserve every template field and its required initial value.
 
 Put the full-project build-and-test command in PLAN.md. Copy `Review panel:`
@@ -97,7 +115,7 @@ family list. Copy `Finding skeptics:` from INTENT.md into PLAN.md Config as
 invent `on`. Quick-lane plans always write both values as `off`.
 
 Before returning, check veto exclusion, decision coverage, Intent coverage,
-the Surface contract, dependencies, file overlap, task size, criteria, and
+the Surface contract, Held-out checks, dependencies, file overlap, task size, criteria, and
 Verify commands.
 
 Return a brief structured summary: wave count, task count, and the wave-1