@opengsd/gsd-path 1.4.0 → 1.6.0

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

@@ -17,10 +17,12 @@ import os
 import re
 import shutil
 import sys
+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
 
@@ -52,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",
@@ -62,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
@@ -106,6 +115,16 @@ KINDS = ("checkpoint", "task", "member-task", "uncommitted-archive", "lookahead"
 PROMOTION_PREFIX = "router: promote lookahead milestone "
 ABANDON_PREFIX = "build: abandon milestone "
 INTEGRATE_PREFIX = "integrate: "
+SHIP_LOG_ONLY_LINE = re.compile(
+    r"- (?P<date>\d{4}-\d{2}-\d{2}) — ship — (?P<event>[^\r\n]+)\n\Z"
+)
+SHIPMENT_RECORD_LINE = re.compile(
+    r"- (?P<date>\d{4}-\d{2}-\d{2}) — shipped — (?P<event>[^\r\n]+)\n\Z"
+)
+SHIPMENT_EVENTS = {
+    "archive preflight passed; shipment recorded",
+    "archive preflight passed; shipment recorded; program complete",
+}
 
 
 class UndoError(RuntimeError):
@@ -375,6 +394,80 @@ def pending_transaction(repo: Path) -> Optional[dict[str, object]]:
         raise UndoError(str(error)) from error
 
 
+def _valid_state_event_line(line: str, phase: str) -> bool:
+    pattern = SHIP_LOG_ONLY_LINE if phase == "ship" else SHIPMENT_RECORD_LINE
+    match = pattern.fullmatch(line)
+    if match is None:
+        return False
+    try:
+        event_date = date.fromisoformat(match.group("date"))
+    except ValueError:
+        return False
+    event = match.group("event")
+    return event_date.isoformat() == match.group("date") and event == " ".join(event.split())
+
+
+def _owned_ship_log_events(
+    prepared_state: str,
+    current_state: str,
+    phase: object,
+    status: object,
+) -> Optional[str]:
+    """Return only ship log lines appended around a helper-owned archive event.
+
+    The prepared text must remain byte-for-byte unchanged. For shipped/done,
+    record-shipment changes only phase and status before appending its one
+    generated shipment event, so validate that exact prefix and event shape.
+    """
+    if (phase, status) == ("ship", "active"):
+        if current_state == prepared_state:
+            return ""
+        if not current_state.startswith(prepared_state):
+            return None
+        suffix = current_state[len(prepared_state):]
+        separator = "" if prepared_state.endswith("\n") else "\n"
+        if separator:
+            if not suffix.startswith(separator):
+                return None
+            suffix = suffix[len(separator):]
+        lines = suffix.splitlines(keepends=True)
+        if not lines or "".join(lines) != suffix:
+            return None
+        if not all(_valid_state_event_line(line, "ship") for line in lines):
+            return None
+        return separator + suffix
+
+    if (phase, status) != ("shipped", "done"):
+        return None
+    try:
+        shipped_prefix = pipeline_state._set_frontmatter(
+            prepared_state,
+            {"phase": "shipped", "status": "done"},
+        )
+    except PipelineStateError:
+        return None
+    if not current_state.startswith(shipped_prefix):
+        return None
+    suffix = current_state[len(shipped_prefix):]
+    separator = "" if shipped_prefix.endswith("\n") else "\n"
+    if separator:
+        if not suffix.startswith(separator):
+            return None
+        suffix = suffix[len(separator):]
+    lines = suffix.splitlines(keepends=True)
+    if not lines or "".join(lines) != suffix:
+        return None
+    shipment_event = lines[-1]
+    if not _valid_state_event_line(shipment_event, "shipped"):
+        return None
+    if SHIPMENT_RECORD_LINE.fullmatch(shipment_event).group("event") not in SHIPMENT_EVENTS:
+        return None
+    ship_events = lines[:-1]
+    if not all(_valid_state_event_line(line, "ship") for line in ship_events):
+        return None
+    return separator + "".join(ship_events) if ship_events else ""
+
+
 def _archive_metadata_error(
     repo: Path,
     state_fields: dict[str, object],
@@ -420,8 +513,13 @@ def _archive_metadata_error(
         if final_review.exists() or gap_reviews:
             reviewed_head, _ = archive_milestone.parse_final_review(archive_path)
             archive_milestone.validate_gap_reviews(archive_path, reviewed_head)
-            if reviewed_head != _optional_rev(repo, "HEAD"):
-                return "archive undo final review does not match current HEAD"
+            if not archive_milestone.reviewed_head_covers(
+                repo, reviewed_head, _optional_rev(repo, "HEAD")
+            ):
+                return (
+                    "archive undo final review does not match current HEAD; "
+                    f"{archive_milestone._common.RUNTIME_PIN_ALLOWANCE}"
+                )
             expected_inventory.add("review/FINAL.md")
             expected_inventory.update(
                 path.relative_to(archive_path).as_posix() for path in gap_reviews
@@ -476,10 +574,14 @@ def _archive_metadata_error(
         "archive",
         configured,
     )
-    current_state = (repo / ".project" / "STATE.md").read_text(encoding="utf-8")
+    current_state = (repo / ".project" / "STATE.md").read_bytes().decode("utf-8")
     phase = state_fields.get("phase")
     status = state_fields.get("status")
+    ship_events = _owned_ship_log_events(prepared_state, current_state, phase, status)
     if (phase, status) == ("ship", "active"):
+        if ship_events is None:
+            return "archive undo found unowned STATE.md changes"
+        prepared_state += ship_events
         if current_state != prepared_state:
             return "archive undo found unowned STATE.md changes"
         if ".project/ROADMAP.md" in dirty:
@@ -487,14 +589,13 @@ def _archive_metadata_error(
         return None
     if (phase, status) != ("shipped", "done"):
         return "archive undo requires ship/active or shipped/done"
+    if ship_events is None:
+        return "archive undo found unowned shipment STATE.md changes"
+    prepared_state += ship_events
 
     prepared = _state_from_text(prepared_state, "prepared archive STATE.md")
-    events = (
-        "archive preflight passed; shipment recorded",
-        "archive preflight passed; shipment recorded; program complete",
-    )
     rendered_states = []
-    for event in events:
+    for event in SHIPMENT_EVENTS:
         try:
             _, _, rendered = _render_transition(
                 prepared,
@@ -679,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:
@@ -701,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")
@@ -768,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:
@@ -988,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/gsd-path-undo/scripts/worktree_paths.py

@@ -22,6 +22,27 @@ else:
         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:
     result = _common.run_git(primary, *args)
     if result.returncode:
@@ -82,6 +103,33 @@ 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", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
@@ -91,9 +139,13 @@ def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) ->
     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")
+        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:

package/skills/path/DEFINE.md

@@ -100,6 +100,10 @@ Obtain a confident answer in every area before finishing:
    give every named surface at least one success criterion observable
    there. A criterion satisfied by a passing test alone does not cover a
    surface.
+9. **Edges and prohibitions** — once the success criteria are drafted, run
+   the [spec-reach probes](references/spec-probes.md): every applicable edge
+   and every kept prohibition gets the user's ruling in INTENT.md
+   `## Edge coverage` and `## Prohibitions`.
 
 ## Program mode
 
@@ -149,7 +153,10 @@ State ownership. There is no re-interview of charter or roadmap scope:
    `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
    `Review panel:` copied from CHARTER.md (default
    the configured preference when CHARTER omits it). The confirmation may override the copied
-   panel value; do not invent `detected` or a named list. When brownfield,
+   panel value; do not invent `detected` or a named list. Run the
+   [spec-reach probes](references/spec-probes.md) over the derived criteria
+   and draft `## Edge coverage` and `## Prohibitions` with recommended
+   rulings. When brownfield,
    fill `## Current state` from the map, record doc-vs-code rulings as in
    Brownfield mode, and add protected existing behavior under Scope out.
    Write Ground truth paths from the track root: `.project` normally, or
@@ -157,10 +164,16 @@ State ownership. There is no re-interview of charter or roadmap scope:
    active `research/` paths.
 3. Present one confirmation, not an interview: playback the derivation (and
    brownfield ground truth when present), link the resolved absolute INTENT.md
-   path, and ask approve or adjust. A requested change that contradicts the
+   path, and ask approve or adjust. The confirmation lists each proposed edge
+   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.
@@ -254,7 +267,15 @@ question. The rules change for every primary mode:
    the brownfield map already established. Milestone mode skips this step.
 5. Stop when coverage is complete or the user says `enough`. Record remaining
    uncertainty under `## Open questions` with `RESEARCH` or `NEEDS-USER`.
-6. Classify the proposed milestone lane before writing the approval draft.
+   `enough` does not skip the next step.
+6. In standard mode, run the [spec-reach probes](references/spec-probes.md)
+   over the drafted success criteria: one question round for edges, then one
+   for kept prohibitions, each with a recommended ruling first. A ruling
+   observable where the user sees the work becomes or amends a success
+   criterion; write every ruling into `## Edge coverage` and
+   `## Prohibitions`. Program mode skips this step (each milestone runs it
+   in milestone mode); milestone mode runs it inside its confirmation.
+7. Classify the proposed milestone lane before writing the approval draft.
    Milestone mode keeps `Lane: milestone` and skips this classification.
    Program mode writes CHARTER.md instead of INTENT.md. Otherwise choose
    `quick` when scope fits at most two deliverable-sized tasks (project
@@ -275,6 +296,11 @@ question. The rules change for every primary mode:
 ## Output contract
 
 At approval, retain the already reviewed `Lane:` value and its one-line reason.
+Before every approval question on INTENT.md, run the bundled `python3
+<absolute-bundled-script> intent --repo <absolute-root>` helper
+(`scripts/check_handoffs.py`, plus `--project-dir .project/next` in
+lookahead). It checks the success criteria, Surfaces, and both probe tables;
+fix a failure in the draft before asking. It approves nothing.
 Before presenting an approval draft without a CHARTER or explicit panel choice,
 read `settings.review_panel.value` from the selected runtime's `path_config.py
 show --repo <absolute-root>` (bundle for legacy projects; off for older selected
@@ -302,5 +328,8 @@ Use the executable phase handoff in AGENTS.md for the next action.
 - In brownfield mode, state mapped facts for correction; never re-ask them.
 - Treat solution-shaped problems as hypotheses and uncover the underlying pain.
 - Preserve vetoes and corrections verbatim.
+- Never rule on an edge's behavior or a prohibition yourself; recommend,
+  then record the user's ruling. An edge the user has not ruled on is a
+  required answer, including under pre-approval.
 - Wrap up when every coverage-checklist area is answered or the user signals
   done, and tag remaining gaps.

package/skills/path/PLAN.md

@@ -115,9 +115,13 @@ 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.
+   - 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
@@ -157,6 +161,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 —

package/skills/path/RESEARCH.md

@@ -84,6 +84,17 @@ settled brownfield input.
    template before dispatch. Record every standard dimension exactly once as
    `dispatched` or `skipped` with a reason, and assign every research question
    to at least one dispatched dimension. No question may remain unassigned.
+   Copy each question to exactly one `Question assignments` row. Assign one or
+   more dispatched dimension slugs there, each in its own code span and
+   separated by commas, as in:
+
+   ```md
+   - `[RESEARCH] Which approach is viable?` → `stack`, `pitfalls`
+   ```
+
+   List a dimension only once per row. Every dispatched dimension must own at
+   least one question, and its evidence file must answer every question
+   assigned to it. Use `- none` only when there are no research questions.
 2. Decide which standard dimensions have work: dispatch a dimension only when
    it has at least one assigned `RESEARCH` question from INTENT.md or
    CHARTER.md. Unsettled choices and risks need that source question before

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

@@ -159,7 +159,12 @@ so the position is unchanged. Then:
    then stop and do not invent a patch finding. A `not-met`,
    `unverifiable`, or blocked gap with valid evidence sets `ship/blocked`,
    writes `.project/review/PATCH-FINDINGS.md` from the patch-findings template,
-   and runs `python3 <absolute check_handoffs.py> patch --repo <absolute repo
+   copying the full `Risk: ...` line into each gap finding's Locator, its
+   `Found` field into Evidence, and its `Fix direction` field verbatim. For a
+   `FINAL.md` finding, use its `SC<n>` id as Locator and copy its `Finding` and
+   `Fix direction` fields verbatim. The patch validator requires these source
+   field values to match exactly; do not shorten or paraphrase them. Run
+   `python3 <absolute check_handoffs.py> patch --repo <absolute repo
    root>`. Present the blocked outcome, link the resolved absolute
    PATCH-FINDINGS.md path, and state that patch planning is next. The manifest
    contains exactly those FINAL.md and gap rows. When routed by an active
@@ -262,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.
@@ -305,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,
@@ -339,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
@@ -349,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,