@opengsd/gsd-path 1.5.0 → 1.6.0

package/skills/gsd-path-undo/references/runtime-selection.md

@@ -20,6 +20,15 @@ references to bundled copies of those helpers. Other skill helpers, templates,
 and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
 invocations so execution does not create bytecode in the runtime store.
 
+The selected runtime is authoritative for each helper in its `manifest.json`;
+this includes `review_findings.py` and `task_context.py`. A selected runtime
+that was published before a helper became a runtime file does not list that
+helper: run the bundled copy until the project runtime is upgraded.
+`dispatch_driver.py` and `workflow_run.py` always run from the installed skill
+bundle, because they read role briefs and templates from it; a skill update
+replaces them, a runtime upgrade does not. The driver reloads the helper modules
+that it imports from the selected runtime.
+
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
 operation before adopting external storage; review the resulting Git diff.

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

@@ -25,7 +25,8 @@ import signal
 import subprocess
 import time
 from pathlib import Path
-from typing import BinaryIO, Iterator, List, Optional, Sequence
+from typing import BinaryIO, Iterable, Iterator, List, Optional, Sequence, Tuple
+
 
 # Chosen by what imports, not os.name, so tests can emulate Windows on POSIX.
 try:
@@ -161,6 +162,33 @@ def project_ignore_error(repo: Path) -> Optional[str]:
             + ". Anchor the product rule (for example `/build/`) in a task that owns it.")
 
 
+_DEFAULT_BRANCH_RE = re.compile(
+    r"[^\s#\"'\\~^:?*\[\x00-\x1f\x7f-][^\s#\"'\\~^:?*\[\x00-\x1f\x7f]*"
+)
+_RESERVED_BRANCH_PREFIXES = ("gsd-path/", "gsd-path-integrate/", "gsd-path-task/")
+
+
+def valid_default_branch(name: str) -> bool:
+    """A git branch name that STATE frontmatter can hold and Path does not reserve."""
+    return (
+        bool(_DEFAULT_BRANCH_RE.fullmatch(name))
+        and name != "null"
+        and not name.startswith(_RESERVED_BRANCH_PREFIXES)
+        and not name.endswith(("/", ".", ".lock"))
+        and not any(part in name for part in ("..", "//", "/.", "@{"))
+    )
+
+
+def origin_default_branch(repo: Path) -> str:
+    """The origin default branch that initialization records; an unset origin/HEAD means main."""
+    result = run_git(repo, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    prefix = "refs/remotes/origin/"
+    remote_ref = result.stdout.strip()
+    if result.returncode != 0 or not remote_ref.startswith(prefix):
+        return "main"
+    return remote_ref.removeprefix(prefix)
+
+
 def section_body(text: str, heading: str) -> Optional[str]:
     """The text under `## <heading>` up to the next `## `, or None when absent."""
     match = re.search(
@@ -169,6 +197,79 @@ def section_body(text: str, heading: str) -> Optional[str]:
     return match.group("body") if match else None
 
 
+def overlapping_paths(left: Sequence[str], right: Sequence[str]) -> List[str]:
+    """Return the sorted paths that two task `files` lists both cover.
+
+    An entry covers itself and the paths below it. For a declared directory
+    and a path below it, the result names the lower path. The callers have no
+    task base, so this does not ask if an entry is a file: the task-brief
+    lint rejects a path below a file at the base.
+    """
+    return sorted(
+        {
+            max(one, other, key=len)
+            for one in left
+            for other in right
+            if one == other or one.startswith(other + "/") or other.startswith(one + "/")
+        }
+    )
+
+
+# The `- ` of an indented sub-bullet line. A line that would then read as a
+# numbered item (`- 2. text`) keeps its marker, so both readings of a source
+# have the same criteria.
+SUB_BULLET_MARKER = re.compile(r"(?m)^([ \t]+)-[ \t]+(?![ \t]*\d+\.\s)")
+
+
+def without_sub_bullet_markers(source: str) -> str:
+    """`source` with the `- ` marker of each indented sub-bullet line removed."""
+    return SUB_BULLET_MARKER.sub(r"\1", source)
+
+
+class Criterion(str):
+    """A criterion as its parser joins it, with the `- ` markers of its sub-bullet lines.
+
+    `bare` is the same criterion parsed from `without_sub_bullet_markers(source)`.
+    The joined text cannot tell a marker from a minus sign; the source lines can.
+    """
+
+    bare: str
+
+    def __new__(cls, text: str, bare: str) -> "Criterion":
+        criterion = super().__new__(cls, text)
+        criterion.bare = bare
+        return criterion
+
+
+def quotes_criterion(quote: str, criterion: str) -> bool:
+    """Whether a review quote is `criterion`, for every reader.
+
+    Only whitespace is collapsed. The quote must equal the criterion with all
+    the markers of its sub-bullet lines or with none of them; every other
+    character, a hyphen inside a line too, is compared.
+    """
+    forms = (criterion, getattr(criterion, "bare", criterion))
+    return " ".join(quote.split()) in {" ".join(form.split()) for form in forms}
+
+
+def quoted_criterion(item: str, criteria: Sequence[str]) -> Optional[Tuple[int, int]]:
+    """Index of the criterion quoted at the start of `item`, and where the quote ends.
+
+    A criterion can contain ` — ` itself, so each separator and the end of
+    `item` is a candidate, the longest quote first. A criterion as written
+    wins over any criterion read without its sub-bullet markers.
+    """
+    ends = [match.start() for match in re.finditer("(?= —(?: |$))|$", item)][::-1]
+    for bare in (False, True):
+        for end in ends:
+            quote = " ".join(item[:end].split())
+            for index, criterion in enumerate(criteria):
+                form = getattr(criterion, "bare", criterion) if bare else criterion
+                if quote == " ".join(form.split()):
+                    return index, end
+    return None
+
+
 def task_verify_command(task_text: str) -> str:
     """The Verify shell text, excluding the closing fence's separator newline."""
     body = section_body(task_text, "Verify")
@@ -176,6 +277,11 @@ def task_verify_command(task_text: str) -> str:
     return block.group("block").removesuffix("\n") if block else ""
 
 
+def fix_verify(commands: Iterable[str]) -> str:
+    """The Verify of a fix task: each distinct source Verify in its own subshell, under `set -e`."""
+    return "set -e\n" + "\n".join(f"(\n{command}\n)" for command in dict.fromkeys(commands))
+
+
 def latest_verify_entry(entries: list, command: str, commit: str,
                         repo: Optional[str] = None) -> Optional[dict]:
     """Rows are keyed by (command, repo, commit); a row without `repo` is a coordinator row."""

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

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import sys
+import traceback
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -33,7 +34,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -41,6 +42,13 @@ def _load_pipeline_modules():
             "scripts._common",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared_scripts))
         import archive_milestone

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

@@ -202,7 +202,11 @@ def native_record(args):
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
                     'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
         if data is not None and data.get('identity') != identity:
-            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+            recorded = data.get('identity')
+            recorded = recorded if isinstance(recorded, dict) else {}
+            differing = ', '.join(f'{field}: {value}, record has {recorded.get(field)}'
+                                  for field, value in identity.items() if recorded.get(field) != value)
+            raise PolicyError(f'record belongs to another assignment or milestone/track/cycle ({differing})')
         if args.action == 'release':
             if data is None or not args.terminal_result:
                 raise PolicyError('release requires an existing record and terminal-result evidence')

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

@@ -22,6 +22,7 @@ from datetime import date
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 import tempfile
+import traceback
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
@@ -53,7 +54,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -63,6 +64,13 @@ def _load_pipeline_modules():
             "scripts.state_checkpoint",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared))
         import archive_milestone
@@ -772,14 +780,15 @@ def _member_undo_parent(repo: Path, member: str, landing: str) -> str:
     bound = entry["branch"]
     if _run_git(checkout, "rev-parse", f"refs/heads/{bound}").stdout.strip() != landing:
         raise UndoError(f"member {member} {bound} moved past this landing")
-    _require_member_unpublished(checkout, member, landing, bound)
+    _require_member_unpublished(repo, checkout, member, landing, bound)
     return _run_git(checkout, "rev-parse", f"{landing}^").stdout.strip()
 
 
-def _require_member_unpublished(checkout: Path, member: str, landing: str, bound: str) -> None:
-    for ref, where in (("refs/remotes/origin/main", "origin/main"), (f"refs/remotes/origin/{bound}", f"origin/{bound}")):
+def _require_member_unpublished(repo: Path, checkout: Path, member: str, landing: str, bound: str) -> None:
+    for branch in (isolation.member_default_branch(repo, member), bound):
+        ref = f"refs/remotes/origin/{branch}"
         if _run_git(checkout, "merge-base", "--is-ancestor", landing, ref, check=False).returncode == 0:
-            raise UndoError(f"member {member} landing is already on {where}")
+            raise UndoError(f"member {member} landing is already on origin/{branch}")
 
 
 def _require_no_member_landing_journal(repo: Path) -> None:
@@ -794,7 +803,7 @@ def _undo_member_landing(repo: Path, transaction: dict[str, object]) -> None:
     checkout, _, entry = isolation._member_context(repo, member)
     tip = _run_git(checkout, "rev-parse", f"refs/heads/{entry['branch']}").stdout.strip()
     if tip == transaction["member_parent"]:
-        _require_member_unpublished(checkout, member, str(transaction["landing"]), entry["branch"])
+        _require_member_unpublished(repo, checkout, member, str(transaction["landing"]), entry["branch"])
         return
     if tip != transaction["landing"]:
         raise UndoError(f"member {member} bound branch moved during undo")
@@ -861,7 +870,7 @@ def classify_undo(repo: Path) -> dict[str, object]:
             [f"an in-progress helper journal exists ({names}); resume that transaction first"]
         )
     if git.get("ancestor_of_origin_main"):
-        return _blocked(["HEAD is an ancestor of origin/main; undo would rewrite shipped history"])
+        return _blocked(["HEAD is an ancestor of the origin default branch; undo would rewrite shipped history"])
 
     product = _product_dirty(dirty)
     if product:
@@ -1081,7 +1090,7 @@ def _require_unpublished_reset(repo: Path, expected_branch: str) -> None:
     if git.get("published"):
         raise UndoError("HEAD became published on its recorded remote branch")
     if git.get("ancestor_of_origin_main"):
-        raise UndoError("HEAD became published through origin/main")
+        raise UndoError("HEAD became published through the origin default branch")
 
 
 def _remove_untracked_tree(repo: Path, relative: str) -> None:

package/skills/path/DEFINE.md

@@ -168,8 +168,12 @@ State ownership. There is no re-interview of charter or roadmap scope:
    and prohibition ruling for the user to accept or change; it never rules on
    them silently. A requested change that contradicts the
    charter or the resolved roadmap entry is a scope change — this phase never
-   edits the roadmap; surface it to the user for a `$gsd-path-roadmap` re-slice
-   at the next milestone boundary.
+   edits the roadmap; surface it to the user for a `$gsd-path-roadmap`
+   re-slice. Before intent approval, that re-slice keeps `define/active` and
+   can change the scope of this milestone's `active` entry; after its
+   approval, draft INTENT.md again from the changed entry. In `corrections`
+   mode the intent is already approved, so the re-slice waits for the next
+   milestone boundary.
 4. On approval, finalize per the Output contract, setting `milestone` to the
    resolved entry's slug. The router continues with milestone-scoped research
    when the entry lists open questions, otherwise planning.

package/skills/path/PLAN.md

@@ -119,6 +119,9 @@ as stated in Lookahead mode.
      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.
+   - Require an optional `supersedes` field to be a list of different task
+     ids; each one names an existing task of an earlier wave, in the same
+     repo, that shares a declared file with the task.
    - 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

package/skills/path/ROADMAP.md

@@ -27,7 +27,8 @@ return to `$gsd-path` for ownership checking. Legal entry is
 yet, `roadmap/active|blocked`, or a
 milestone-boundary re-slice: `inspect/active` or `define/active` with no
 approved INTENT.md for the next milestone and a user request to re-scope the
-remaining `pending` entries,
+remaining `pending` entries or, at `define/active` only, to change the scope
+of the `active` entry,
 or `roadmap/active` with STATE.milestone null and an `abandoned` entry in
 ROADMAP.md (the post-abandon re-slice the build orchestrator hands off).
 Enter from `decide/done` only with `pipeline_state.py transition`, exact
@@ -35,6 +36,8 @@ expected phase/status/milestone/branch/archive fields, event `roadmap started`,
 and `--set-phase roadmap --set-status active`; never edit STATE directly. In a
 milestone-boundary re-slice, preserve the entering `inspect/active` or
 `define/active` state throughout the re-slice.
+A `define/active` state that the router reports in `corrections` mode already
+has an approved INTENT.md; it blocks.
 Any later phase blocks; mid-milestone
 re-scope is never legal — finish or ship the active milestone first. A
 `decide/done` state with ROADMAP.md already present is milestone-scope decide;
@@ -71,8 +74,11 @@ precondition fails.
    give `.project/ROADMAP.before-reslice.md` with the instruction to preserve
    `shipped` entries byte-for-byte except Status/Archive/Integrated fields and
    to never modify `abandoned` entries at all. For a milestone-boundary
-   re-slice, also preserve the existing `active` entry byte-for-byte; only
-   `pending` entries are in scope.
+   re-slice entered at `inspect/active`, also preserve the existing `active`
+   entry byte-for-byte; only `pending` entries are in scope. Entered at
+   `define/active`, the `active` entry may also change as the user ruled, but
+   its heading (id and slug) and its Status, Depends on, Archive, and
+   Integrated fields stay unchanged.
    The output is exactly `.project/ROADMAP.md` — no other location is
    canonical.
 3. Gate ROADMAP.md:
@@ -96,8 +102,11 @@ precondition fails.
    - On a re-slice, `shipped` entries differ from
      `.project/ROADMAP.before-reslice.md` only in Status/Archive/Integrated;
      `abandoned` entries are byte-for-byte identical.
-   - On a milestone-boundary re-slice, the prior `active` entry is byte-for-byte
-     identical to `.project/ROADMAP.before-reslice.md`.
+   - On a milestone-boundary re-slice entered at `inspect/active`, the prior
+     `active` entry is byte-for-byte identical to
+     `.project/ROADMAP.before-reslice.md`. Entered at `define/active`, it
+     stays the only `active` entry and keeps its heading and its Status,
+     Depends on, Archive, and Integrated fields.
 4. Redispatch one complete corrected brief under logical task name `roadmap`,
    following the runtime dispatch contract and including all gate failures.
    Allow one revision round. If it still fails, keep the entering
@@ -160,7 +169,8 @@ precondition fails.
 
    The helper owns roadmap selection, expected state, baseline cleanup and
    the approval checkpoint. It journals before mutation, retains the baseline
-   bytes for recovery, and refuses changes to settled or active entries.
+   bytes for recovery, and refuses changes to settled entries and every
+   `active` entry change that step 2 does not permit.
    A milestone-boundary re-slice retains Inspect or Define; a post-abandon
    re-slice enters Inspect. Require its typed result to report `status:
    approved`, the requested kind, milestone and returned commit. After an

package/skills/path/SHIP.md

@@ -267,7 +267,11 @@ The persisted `STATE.archive` field is the transaction identity.
    `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
+   journals each one. Each member closes onto the default branch that
+   MEMBERS.md records for it (`main` when its section has no
+   `Default branch`); when the command reports
+   `remote default must be <recorded>`, stop and report it. 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.
@@ -310,8 +314,10 @@ The persisted `STATE.archive` field is the transaction identity.
    milestone is not shipped until integration below passes.
 7. Integrate only after the postcommit `validate` passes, with the recorded
    ship commit and exact reviewed HEAD unchanged. Run `python3 <absolute archive_milestone.py> integrate --repo <root> --slug <STATE.milestone>`.
-   This helper validates the ship commit, fetches origin, requires remote
-   default `main`, and follows the locked `STATE.integration` mode:
+   This helper validates the ship commit, fetches origin, requires the remote
+   default to equal STATE `default_branch` (`main` when the field is absent),
+   and follows the locked `STATE.integration` mode. `main` and `origin/main`
+   below mean that recorded branch:
 
    - `direct` owns the resumable merge transaction. It creates the canonical
      named integration worktree, performs the hook-verified `--no-ff` merge,
@@ -344,6 +350,22 @@ The persisted `STATE.archive` field is the transaction identity.
      landing SHA. A closed unmerged PR, squash, rebase, merge queue, moved
      head, duplicate PR, or non-GitHub.com origin blocks. The remote bound
      branch may be absent after a valid merge because GitHub may auto-delete it.
+   - `external-landing` is for an origin where Path cannot open the review
+     itself, such as GitLab, Gitea, or GitHub Enterprise Server. It needs no
+     forge CLI. The helper publishes the bound branch at the exact ship commit,
+     never pushes `main`, and returns `status: awaiting-merge` with `branch`,
+     `merge_subject`, and `merge_body`. Present **Outcome**, and state in
+     **Next** that the user must open a merge request from `branch` to `main`
+     in their own forge and merge it with a merge commit. The merge commit
+     message must be exactly `merge_subject`, a blank line, then `merge_body`;
+     show both values verbatim in a code block. Stop this ship invocation;
+     Path never opens or merges the request. The forge may delete the source
+     branch after the merge. On rerun after the merge, the helper requires exactly
+     one commit with that subject on `origin/main` first-parent history, that
+     exact body, and two parents with the ship commit as second parent. It
+     then writes and pushes the annotated milestone tag containing the ship
+     SHA and landing SHA. A squash, rebase, fast-forward, or different merge
+     message blocks.
 
    A passing run returns the same proof exposed by `validate-integrated`.
    A non-zero result blocks; rerun the exact `integrate` command to resume a
@@ -354,7 +376,7 @@ The persisted `STATE.archive` field is the transaction identity.
    continuing. Never merge into or re-ship the closed branch.
    For a later validation recheck with origin network access, run
    `python3 <absolute archive_milestone.py> validate-integrated --repo <root> --slug <STATE.milestone>`.
-   Both integration modes refresh the remote-default and mirrored milestone-tag
+   All integration modes refresh the remote-default and mirrored milestone-tag
    refs when an `origin` remote exists. Without that remote, validation resolves
    the existing remote-default refs locally, preserving offline direct-mode
    fixtures. PR mode also revalidates the PR identity, state, merge provenance,

package/skills/path/SKILL.md

@@ -179,6 +179,23 @@ selects a milestone branch.
      `define/active`; report that no brownfield signal fired, and route to
      the bundled [define contract](DEFINE.md).
 
+## Default branch
+
+`initialize` records the default branch of `origin` one time, as STATE
+`default_branch`. It reads the local `refs/remotes/origin/HEAD`; when that ref
+is unset it records `main`. When the repository has an `origin`, run
+`git remote set-head origin --auto` before `initialize`, so that the record is
+the default branch of the forge. A STATE file without the field means `main`.
+
+`<default_branch>` in the commands below is the `default_branch` value in the
+`validate`, `route`, and `status` JSON, beside `state`. Never edit the field,
+and never take the name from a later `origin/HEAD` lookup. When a helper
+reports that the remote default differs from the recorded one, stop and report
+it. In a project with members, STATE `default_branch` is the default branch of
+the coordinator only. `members.py add` records the default branch of each
+member in `.project/MEMBERS.md`; the member helpers read that record. The
+names can differ.
+
 ## Integration choice
 
 New state uses the user shipping default (built-in: `direct`) for
@@ -190,7 +207,7 @@ helper; never edit these fields by hand:
 python3 <absolute-bundled-pipeline-state.py> configure-integration \
   --repo <absolute-root> \
   --scope <default-or-milestone> \
-  --mode <direct-or-pull-request>
+  --mode <direct|pull-request|external-landing>
 ```
 
 `default` changes the project setting and changes the current milestone only
@@ -212,16 +229,23 @@ milestone boundary, never during build or ship. Resolve the bundled
 `scripts/members.py` to an absolute path and use it; never edit MEMBERS.md
 or a member marker by hand.
 
-- To add an existing repository, it needs a GitHub.com `origin` whose default
-  is `main`, a clean worktree, and no active milestone of its own. Ask for the
-  member name, checkout path, and integration (`direct`, `pull-request`, or
-  `default`, which follows the milestone's choice), then run
+- To add an existing repository, it needs a GitHub.com `origin`, a clean
+  worktree, and no active milestone of its own. Its default branch can have
+  any name. Run `git remote set-head origin --auto` in the member first: `add`
+  reads the member's local `origin/HEAD` one time and records the name in
+  MEMBERS.md as `Default branch`; an unset `origin/HEAD` records `main`. Ask
+  for the member name, checkout path, and integration (`direct`,
+  `pull-request`, or `default`, which follows the milestone's choice), then run
   `python3 <members.py> add --repo <absolute-root> --name <name> --checkout <path> --integration <mode>`.
+  When `validate` or member close later reports
+  `remote default must be <recorded>`, stop and report it; never edit the
+  record.
 - To create a new member repository, present the exact `owner/name`,
   visibility, and checkout path as the **Review** surface and get approval
   first, as for a new GitHub repository. Then run the same command with
   `--create <owner/name> --visibility <visibility>`. It journals the approved
-  target before creating anything; rerun the identical command to resume.
+  target before creating anything; rerun the identical command to resume. A
+  new member repository uses `main`.
 - After adding a member, tell the user to install its guard hooks:
   `npx @opengsd/gsd-path@latest --member-of <absolute-root> --project <member checkout>`.
 - `python3 <members.py> validate --repo <absolute-root>` checks every member;
@@ -269,8 +293,8 @@ integration ancestry, cleanliness, and journal ownership before continuing.
 After it returns, continue the state transition or lookahead promotion below.
 Do not reconstruct this classification from Git output or Log prose.
 When the route returns `allow_remote_absent: true`, also pass
-`--allow-missing-previous`; this is valid only because a merged PR may have
-auto-deleted the published bound branch.
+`--allow-missing-previous`; this is valid only because the forge may have
+auto-deleted the published bound branch after the merge.
 
 Before ordinary routing, inspect `STATE.archive`.
 
@@ -328,7 +352,7 @@ promotion, `resume-next-handoff` resumes the verified `bind-next` transaction,
 `resume-undo` invokes `$gsd-path-undo` with the returned kind and expected HEAD,
 `block` stops with the returned reason. `bind-initial`
 means initialization is complete and phase work must wait for the initial
-router binding: resolve the exact fetched `origin/main` SHA, call `bind-initial` as
+router binding: resolve the exact fetched `origin/<default_branch>` SHA, call `bind-initial` as
 above with `route.branch`, then persist its returned branch with
 `pipeline_state.py transition` using the route result's `state` phase and status plus its
 null branch and archive as expected fields. Set `--set-branch` to the helper's
@@ -371,7 +395,8 @@ on `NEEDS-USER`. Planning owns the single build-approval gate; never ask a
 second time. One user-driven exception to normal routing: at a program milestone
 boundary — `inspect/active` or `define/active` with no approved INTENT.md for
 the next milestone — a user request to re-scope the remaining `pending`
-entries routes to the bundled [roadmap contract](ROADMAP.md) in re-slice mode.
+entries, or at `define/active` the `active` entry, routes to the bundled
+[roadmap contract](ROADMAP.md) in re-slice mode.
 
 ## Lookahead planning (program flow)
 
@@ -400,7 +425,9 @@ template](templates/state.md) with `pipeline: gsd-path/v2`, `phase:
 inspect`, `status: active`, the selector's exact returned `milestone` slug as
 `milestone`, `branch: null`, and `archive: null`. Copy the active project's
 `integration_default` into both integration mode fields and set
-`integration_source: default`. Then follow the bundled
+`integration_source: default`. Set `default_branch` to the active project's
+value; when the active STATE.md has no `default_branch` line, delete that line
+from the new file. Then follow the bundled
 phase contracts in their Lookahead mode — inspect, define (milestone +
 brownfield), research (only when the entry lists open questions), decide, and
 plan — rooted at `.project/next/`.
@@ -424,14 +451,14 @@ bundled integration check (`validate-integrated`); pending integration routes
 back to ship, never here. Preserve the previous archive path, ship SHA,
 integration SHA, and build branch in the state Log. Before fetching or binding
 the next program branch, fetch origin and resolve the exact current
-`origin/main` SHA. For a program roadmap, resolve the branch from that exact
+`origin/<default_branch>` SHA. For a program roadmap, resolve the branch from that exact
 fetched commit through the bundled helper. With a saved lookahead track, run:
 
 ```text
 python3 <absolute-bundled-promote-lookahead.py> select-base \
   --repo <absolute-primary-root> \
-  --base <exact-origin-main-sha> \
-  --remote-default origin/main \
+  --base <exact-remote-default-sha> \
+  --remote-default origin/<default_branch> \
   --lookahead
 ```
 
@@ -440,8 +467,8 @@ Without a saved lookahead track, run:
 ```text
 python3 <absolute-bundled-promote-lookahead.py> select-base \
   --repo <absolute-primary-root> \
-  --base <exact-origin-main-sha> \
-  --remote-default origin/main
+  --base <exact-remote-default-sha> \
+  --remote-default origin/<default_branch>
 ```
 
 When the helper returns `status: complete`, report program completion and stop;
@@ -457,21 +484,22 @@ python3 <absolute-bundled-pipeline-git.py> bind-next \
   --branch <selected-branch> \
   --previous-branch <STATE.branch> \
   --ship <exact-ship-sha> \
-  --remote-default origin/main \
-  --base <exact-origin-main-sha> \
+  --remote-default origin/<default_branch> \
+  --base <exact-remote-default-sha> \
   --landing <validate-integrated-landing-sha>
 ```
 
 Add `--allow-missing-previous` when `validate-integrated` returned
-`mode: pull-request` and `origin/<STATE.branch>` is absent. GitHub may delete
-that head branch after merge; the local branch and exact ship SHA still bind
-the handoff. The helper independently verifies the published pull-request
-milestone tag and merge topology before accepting the missing branch.
+`mode: pull-request` or `mode: external-landing` and `origin/<STATE.branch>`
+is absent. The forge may delete that source branch after merge; the local
+branch and exact ship SHA still bind the handoff. The helper independently
+verifies the published milestone tag for `STATE.integration` and the merge
+topology before accepting the missing branch.
 
 The helper requires the previous branch, while it still exists locally, to
 remain at the ship SHA, proves the ship commit is integrated into the exact
 base, rejects local or remote branch collisions,
-and switches the clean primary worktree without tracking main. It then
+and switches the clean primary worktree without tracking the default branch. It then
 retires the integrated previous branch — deleted locally and on origin; the
 ship commit stays reachable from the integration merge and its tag. Repeating the
 same command while the new branch is current at the unchanged base is the
@@ -488,7 +516,7 @@ Log, then:
     --repo <absolute-primary-root> \
     --milestone <next-slug> \
     --branch gsd-path/M00N \
-    --base <exact-current-origin-main-sha> \
+    --base <exact-current-remote-default-sha> \
     --landing <exact-milestone-merge-sha>
   ```