@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-define/scripts/state_checkpoint.py

@@ -17,12 +17,15 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional, Sequence
 
-try:
-    from isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
-except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-    if error.name != "isolation":
-        raise
-    from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+if __package__:
+    from .isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+else:
+    try:
+        from isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+    except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
+        if error.name != "isolation":
+            raise
+        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 
 
 if __package__:
@@ -66,6 +69,11 @@ def _sha256(content: str) -> str:
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
 
+def _is_junk_file(path: Path) -> bool:
+    # Drift digests skip OS junk by name: Finder rewrites it whatever its ignore status.
+    return path.name in pipeline_state._common.OS_JUNK_NAMES and path.is_file() and not path.is_symlink()
+
+
 def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
     if path.is_symlink() or not path.is_dir():
         raise PipelineStateError(f"promotion path must be a real directory: {path}")
@@ -74,7 +82,7 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
         if child.is_symlink():
             raise PipelineStateError(f"promotion path contains a symlink: {child}")
         relative = child.relative_to(path).as_posix()
-        if PurePosixPath(relative).parts[0] in excluded:
+        if PurePosixPath(relative).parts[0] in excluded or _is_junk_file(child):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -87,15 +95,15 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
 
 
 def _checkpoint_artifact_digest(project: Path, mutable_paths: set[str]) -> str:
-    """Hash every approval artifact except the helper-owned metadata files."""
+    """Hash approval artifacts except helper-owned metadata and OS junk."""
     digest = hashlib.sha256()
     for child in sorted(project.rglob("*")):
         if child.is_symlink():
             raise PipelineStateError(f"checkpoint path contains a symlink: {child}")
         relative = child.relative_to(project).as_posix()
-        # Unsupported entries (OS junk) are refused by the checkpoint itself; leaving them
-        # out lets a refused approval resume after the owner removes them.
-        if relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES:
+        # Finder can rewrite OS junk during approval; it must not cause artifact drift.
+        if (relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES
+                or _is_junk_file(child)):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -333,11 +341,7 @@ def _converge_checkpoint_file(path: Path, before: str, after: str, label: str) -
 
 def _unlink_checkpoint_journal(path: Path) -> None:
     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 _resume_checkpoint_locked(
@@ -439,41 +443,85 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
         return
+    if __package__:
+        from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    else:
+        try:
+            from check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+        except ModuleNotFoundError as error:  # pragma: no cover - package imports
+            if error.name != "check_task_briefs":
+                raise
+            from scripts.check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ModuleNotFoundError as error:
+            if error.name != "check_handoffs":
+                raise
+            from scripts import check_handoffs
     try:
-        from check_task_briefs import BriefError, validate_task_briefs
-    except ModuleNotFoundError as error:  # pragma: no cover - package imports
-        if error.name != "check_task_briefs":
-            raise
-        from scripts.check_task_briefs import BriefError, validate_task_briefs
-    try:
-        import check_handoffs
-    except ModuleNotFoundError as error:
-        if error.name != "check_handoffs":
-            raise
-        from scripts import check_handoffs
-    try:
-        tasks, dependency_files = check_handoffs.plan_brief_inputs(repo, project_dir)
-        landed_bases = {}
-        for task_id, text in tasks.items():
-            if check_handoffs._task_scalar(text, task_id, "status") != "done":
-                continue
-            agent = check_handoffs._task_scalar(text, task_id, "agent")
-            if agent in {"", "null"}:
-                raise BriefError(f"{task_id} landed task has no recorded agent")
-            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
-            try:
-                landed_bases[task_id] = require_commit(repo, require_full_sha(recorded_base))
-            except IsolationError as error:
-                raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
+        member_base = _member_bases(repo)
+        tasks, dependency_files, landed_bases = plan_validation_bases(
+            repo, project_dir, member_base, initial=True
+        )
         validate_task_briefs(
             repo, head.stdout.strip(), f"{project_dir}/tasks",
             dependency_files=dependency_files, landed_bases=landed_bases,
+            member_base=member_base,
         )
+        if project_dir == ".project/next":
+            # Promotion checks lookahead member tasks from the bases their briefs were checked at.
+            named = {
+                str(check_handoffs._strict_frontmatter(text, task_id).get("repo"))
+                for task_id, text in tasks.items()
+                if check_handoffs._strict_frontmatter(text, task_id).get("repo")
+                and check_handoffs._task_scalar(text, task_id, "status") != "done"
+            }
+            if named:
+                bases = {name: member_base(name)[1] for name in sorted(named)}
+                milestone = pipeline_state.load_state(repo, project_dir)[0].milestone
+                path = _lookahead_member_bases_path(repo, str(milestone))
+                path.parent.mkdir(parents=True, exist_ok=True)
+                pipeline_state._common.atomic_write(path, json.dumps(
+                    {"schema": LOOKAHEAD_MEMBER_BASES_SCHEMA, "milestone": milestone, "bases": bases},
+                    indent=2, sort_keys=True) + "\n")
     except (BriefError, check_handoffs.HandoffError) as error:
         raise PipelineStateError(f"task brief validation failed: {error}") from error
 
 
+LOOKAHEAD_MEMBER_BASES_SCHEMA = "gsd-path/lookahead-member-bases/v1"
+
+
+def _lookahead_member_bases_path(repo: Path, milestone: str) -> Path:
+    common = pipeline_state._run_git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.strip()
+    return Path(common) / "gsd-path" / "lookahead-member-bases" / f"{milestone}.json"
+
+
+def _lookahead_member_bases(repo: Path, milestone: str) -> Optional[dict]:
+    path = _lookahead_member_bases_path(repo, milestone)
+    if not path.is_file():
+        return None
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if value.get("schema") != LOOKAHEAD_MEMBER_BASES_SCHEMA or value.get("milestone") != milestone:
+        return None
+    return value.get("bases")
+
+
+def _shipped_member_merges(repo: Path, landing: str) -> dict:
+    """Member merges named by the ship commit the integration landing merged."""
+    if __package__:
+        from .pipeline_git import ship_member_rows
+    else:
+        from pipeline_git import ship_member_rows
+    ship = pipeline_state._run_git(repo, "rev-parse", "--verify", "--quiet", f"{landing}^2", check=False)
+    if ship.returncode != 0:
+        return {}
+    message = pipeline_state._run_git(repo, "show", "-s", "--format=%B", ship.stdout.strip()).stdout
+    return {row["name"]: row["merge"] for row in ship_member_rows(message)}
+
+
 def checkpoint_approval(
     repo: Path,
     kind: str,
@@ -1027,6 +1075,46 @@ def _classify_plan_drift(
         }
     approved = _approved_task_contracts(repo, checkpoint)
     current = _task_contracts_at(repo, revision)
+    if __package__:
+        from . import check_handoffs
+    else:
+        import check_handoffs
+    # Member task paths live in member repos: compare each member from the base its brief
+    # was checked at to the member merge the shipped milestone made (both fixed commits).
+    task_repos = {
+        task_id: str(check_handoffs._strict_frontmatter(contract.text, contract.path).get("repo") or "")
+        for task_id, contract in approved.items()
+    }
+    active_member_tasks = {
+        task_id for task_id, name in task_repos.items()
+        if name and check_handoffs._task_scalar(approved[task_id].text, task_id, "status") != "done"
+    }
+    active_members = {task_repos[task_id] for task_id in active_member_tasks}
+    member_changes: dict[str, list] = {}
+    if active_members:
+        bases = _lookahead_member_bases(repo, str(state.milestone)) or {}
+        if any(name not in bases for name in active_members):
+            return {
+                "class": "unverifiable",
+                "checkpoint": checkpoint,
+                "task_ids": [],
+                "changed_paths": [],
+                "contract_paths": [],
+                "member_tasks": True,
+                "reason": "member bases were not recorded at plan approval",
+            }
+        if __package__:
+            from . import members
+        else:
+            import members
+        checkouts = {item["name"]: Path(item["checkout"]) for item in members.read_members(repo)}
+        merges = _shipped_member_merges(repo, landing or revision)
+        for name in active_members:
+            member_changes[name] = [
+                item for item in pipeline_state._run_git(
+                    checkouts[name], "diff", "--no-renames", "--name-only", "-z", bases[name], merges[name]
+                ).stdout.split("\0") if item
+            ] if name in merges else []
 
     contract_paths: set[str] = set()
     flagged_ids: set[str] = set()
@@ -1050,9 +1138,12 @@ def _classify_plan_drift(
 
     product_paths: set[str] = set()
     for task_id, contract in approved.items():
+        member = task_repos.get(task_id)
+        if member and task_id not in active_member_tasks:
+            continue
         matches = sorted(
-            changed_path
-            for changed_path in changed
+            (f"{member}:{changed_path}" if member else changed_path)
+            for changed_path in (member_changes[member] if member else changed)
             if any(
                 changed_path == path
                 or changed_path.startswith(f"{path.rstrip('/')}/")

package/skills/gsd-path-define/scripts/state_promote.py

@@ -82,6 +82,8 @@ def _promotion_event(
         if isinstance(task_ids, list) and task_ids:
             return f"{prefix}; plan drift flagged tasks {', '.join(task_ids)}"
         return f"{prefix}; plan contract changed after approval"
+    if drift_class == "unverifiable" and drift.get("member_tasks"):
+        return f"{prefix}; plan drift unverifiable because member bases were not recorded at plan approval"
     if drift_class == "unverifiable":
         return f"{prefix}; plan drift unverifiable because approval checkpoint is missing"
     return prefix

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

@@ -13,10 +13,34 @@ 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 _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    try:
+        if __package__:
+            from . import pipeline_git as pg
+        else:
+            from scripts import pipeline_git as pg
+    except ImportError:
+        try:
+            import pipeline_git as pg
+        except ImportError:
+            pg = None
+    if pg is not None:
+        return pg.worktree_list_porcelain(primary)
+    try:
+        output = _git(primary, "worktree", "list", "--porcelain", "-z")
+        return output, True
+    except ValueError:
+        output = _git(primary, "worktree", "list", "--porcelain")
+        return output, False
 
 
 def _git(primary: Path, *args: str) -> str:
@@ -27,7 +51,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 +92,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)
@@ -76,17 +103,52 @@ def _workspace(primary: Path, pin: bool) -> Path:
     return workspace
 
 
+def release_workspace(primary: Path) -> bool:
+    """Forget the pinned placement receipt once no linked worktrees remain.
+
+    Lets GSD_PATH_WORKTREE_ROOT (or a new default) apply again at the next
+    milestone's first allocation. Returns True when a receipt was removed;
+    any remaining linked worktree (including one only still registered) keeps
+    the pin.
+    """
+    primary = primary.resolve()
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    receipt = common / "gsd-path" / "workspaces" / f"{_identity(primary)}.json"
+    if not receipt.is_file():
+        return False
+    output, nul_separated = _worktree_list_porcelain(primary)
+    records = output.split("\0\0") if nul_separated else [
+        block for block in output.strip().split("\n\n") if block.strip()
+    ]
+    for record in records:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        for field in fields:
+            if field.startswith("worktree ") and Path(field[len("worktree "):]).resolve() != primary:
+                return False
+    receipt.unlink()
+    return True
+
+
 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")
+    output, nul_separated = _worktree_list_porcelain(primary)
+    if nul_separated:
+        records = output.split("\0\0")
+    else:
+        records = [block for block in output.strip().split("\n\n") if block.strip()]
     for record in records:
-        fields = record.split("\0")
-        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        # 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-define/templates/intent.md

@@ -57,6 +57,36 @@ paragraph the user signed off on — do not edit without a new sign-off.>
 1. <criterion — a thing you can run/measure/see>
 2. ...
 
+## Edge coverage
+
+<!-- Written by define's edge probe (references/spec-probes.md). Walk every
+     success criterion; each applicable edge gets one row ruled by the user.
+     Disposition: criterion SCn (stated in that criterion) | held-out (a named
+     test pins the ruling written in Detail) | dismissed (Detail says why the
+     edge cannot occur). Every SCn appears at least once; a criterion with no
+     data shape gets category none, dismissed. Categories: boundary,
+     adjacency, empty, encoding, ordering, precision, idempotency,
+     concurrency, none. `check_handoffs.py intent` gates this table. -->
+
+| Edge | Criterion | Category | Disposition | Detail |
+|------|-----------|----------|-------------|--------|
+| E1 | SC1 | <category> | <disposition> | <ruling, examples, or dismissal reason> |
+
+## Prohibitions
+
+<!-- Written by define's prohibition probe. What each criterion must never
+     silently become: values, safety, privacy, fairness, transparency. Not
+     routine engineering, not generic security canon.
+     Disposition: criterion SCn (checkable; stated in that criterion) |
+     judgment (final reviewer judges it; Detail says what to look for) |
+     dismissed. A single row with Criterion `all`, Must not `none`, and
+     disposition dismissed, and no other row, records work that affects no
+     person directly. -->
+
+| Prohibition | Criterion | Must not | Disposition | Detail |
+|-------------|-----------|----------|-------------|--------|
+| N1 | SC1 | <what it must never become> | <disposition> | <what the reviewer looks for, or why dismissed> |
+
 ## Scope: in
 
 <The smallest version that hits the success criteria. Bullet list.>

package/skills/gsd-path-define/templates/state.md

@@ -10,7 +10,7 @@ branch: null        # bound per milestone as gsd-path/M00N; after integration
                     # the router rebinds before any next-milestone file change
                     # the bound branch is never main; ship integrates it there
 archive: null       # persisted archive transaction path; never recomputed
-integration_default: direct # direct | pull-request; project setting
+integration_default: direct # direct | pull-request | external-landing; project setting
 integration: direct # current milestone; may override the default before build
 integration_source: default # default | milestone; preserves override provenance
 ---

package/skills/gsd-path-discuss/SKILL.md

@@ -3,7 +3,8 @@ name: gsd-path-discuss
 description: Hold an explicit, evidence-grounded discussion about an active GSD Path milestone from any phase, preserve the verbatim dialogue and answer records under .project/discuss/, use local code and existing artifacts before focused research, challenge unsupported assumptions, and identify the phase owner for follow-up. Use only when the user explicitly invokes $gsd-path-discuss to ask questions, explore a decision, request a progress explanation, or close a discussion without advancing the pipeline.
 ---
 
-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 Discussion
 

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