@opengsd/gsd-path 1.6.0 → 1.6.2

package/skills/gsd-path-ship/scripts/isolation.py

@@ -1219,9 +1219,17 @@ def _commit_member_source(sidecar: Path, journal: Dict[str, object], allowed: Se
         undeclared = undeclared_paths(sidecar, member_base, pending, allowed)
         if undeclared:
             raise IsolationError("undeclared paths: " + ", ".join(undeclared))
-        git_output(sidecar, "add", "-A", "--", *sorted(pending))
         body = member_commit_body(str(journal["task_file"]), sorted(pending), member_base, str(journal["base"]))
-        git_output(sidecar, "commit", "-q", "-m", str(journal["subject"]), "-m", body.strip())
+        # The paths and the body grow with the change set, so both go through
+        # stdin: a Windows command line holds about 32 KiB.
+        for arguments, text in (
+            (("add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"),
+             "".join(f"{path}\0" for path in sorted(pending))),
+            (("commit", "-q", "-F", "-"), _commit_message(str(journal["subject"]), body)),
+        ):
+            result = run_git(sidecar, *arguments, input=text)
+            if result.returncode != 0:
+                raise IsolationError((result.stderr or result.stdout).strip() or "git command failed")
     source = current_sha(sidecar)
     if source == member_base:
         raise IsolationError("no changes to land")
@@ -1669,6 +1677,25 @@ def committed_paths_since(repo: Path, base: str) -> Set[str]:
     )
 
 
+def _stage_paths(repo: Path, mode: str, paths: Set[str]) -> None:
+    """Stage `paths` with one `git add`.
+
+    One call for each path fails when a file replaces a tracked directory: the
+    first call drops the files below the directory from the index, and then
+    their pathspecs match no file. The `./` prefix stops pathspec magic, so a
+    name such as `:!b` cannot exclude another path of the set. Git names the
+    path in its error text.
+    """
+    if not paths:
+        return
+    added = run_git(
+        repo, "add", mode, "--pathspec-from-file=-", "--pathspec-file-nul",
+        input="".join(f"./{path}\0" for path in sorted(paths)),
+    )
+    if added.returncode != 0:
+        raise IsolationError(f"could not stage the change set: {added.stderr.strip()}")
+
+
 def ignored_legacy_ledger(repo: Path) -> bool:
     """True when a verify ledger absent from HEAD is hidden by an ignore rule.
 
@@ -1684,17 +1711,25 @@ def ignored_legacy_ledger(repo: Path) -> bool:
     return run_git(repo, "check-ignore", "-q", "--no-index", "--", VERIFY_LEDGER_PATH).returncode == 0
 
 
+def _commit_message(subject: str, body: str) -> str:
+    """The message for `git commit -F -`.
+
+    A landing body lists every changed path. As a `-m` argument it can exceed
+    the Windows command-line limit, so the message goes through stdin. Like
+    `-m`, the message ends its last line.
+    """
+    message = f"{subject}\n\n{body}"
+    return message if message.endswith("\n") else message + "\n"
+
+
 def _commit_pending(
     repo: Path, pending: Set[str], subject: str, body: str, forced: Set[str] = frozenset()
 ) -> str:
     reset = run_git(repo, "reset", "-q", "HEAD")
     if reset.returncode != 0:
         raise IsolationError("could not clear the index before commit")
-    for path in sorted(pending):
-        mode = "-f" if path in forced else "-A"
-        added = run_git(repo, "add", mode, "--", path)
-        if added.returncode != 0:
-            raise IsolationError(f"could not stage {path}: {added.stderr.strip()}")
+    _stage_paths(repo, "-A", pending - forced)
+    _stage_paths(repo, "-f", pending & forced)
     staged = _split_paths(
         git_output(
             repo,
@@ -1707,7 +1742,7 @@ def _commit_pending(
     )
     if staged != pending:
         raise IsolationError("staged paths do not match the uncommitted change set")
-    committed = run_git(repo, "commit", "-q", "-m", subject, "-m", body)
+    committed = run_git(repo, "commit", "-q", "-F", "-", input=_commit_message(subject, body))
     if committed.returncode != 0:
         raise IsolationError((committed.stderr or committed.stdout).strip() or "commit failed")
     return current_sha(repo)
@@ -1786,18 +1821,15 @@ def commit_allowed_changes(
     reset = run_git(repo, "reset", "-q", "HEAD")
     if reset.returncode != 0:
         raise IsolationError("could not clear the index before landing")
-    for path in sorted(staging):
-        added = run_git(repo, "add", "-A", "--", path)
-        if added.returncode != 0:
-            raise IsolationError(f"could not stage {path}: {added.stderr.strip()}")
+    _stage_paths(repo, "-A", staging)
     staged = _split_paths(
-        git_output(repo, "diff", "--cached", "--name-only", "--relative")
+        git_output(repo, "diff", "--no-renames", "--cached", "--name-only", "--relative")
     )
     if staged != staging:
         raise IsolationError("staged paths do not match the uncommitted change set")
     verified_tree = git_output(repo, "write-tree")
     verified_delta = _tree_delta(repo, base, verified_tree)
-    committed = run_git(repo, "commit", "-q", "-m", subject, "-m", body)
+    committed = run_git(repo, "commit", "-q", "-F", "-", input=_commit_message(subject, body))
     if committed.returncode != 0:
         raise IsolationError(
             (committed.stderr or committed.stdout).strip() or "commit failed"
@@ -4470,6 +4502,20 @@ def attest(
     }
 
 
+def _committed_ship_active(repo: Path) -> bool:
+    """True when the STATE.md committed at HEAD is ship/active."""
+
+    result = run_git(repo, "show", "HEAD:.project/STATE.md")
+    if result.returncode != 0:
+        return False
+    frontmatter = result.stdout.split("\n---", 1)[0]
+    fields = {
+        key: _unquote(value)
+        for key, value in re.findall(r"(?m)^(phase|status):(.*)$", frontmatter)
+    }
+    return fields.get("phase") == "ship" and fields.get("status") == "active"
+
+
 def checkpoint(
     repo: Path,
     expected_head: str,
@@ -4519,6 +4565,12 @@ def checkpoint(
                 "subject": subject.strip(),
             }
         raise IsolationError("primary HEAD differs from --expected-head")
+    if subject.strip().startswith("build:") and _committed_ship_active(repo):
+        raise IsolationError(
+            "STATE is ship/active: final review creates no pre-ship commit; leave its "
+            "outputs uncommitted for archive_milestone.py, and send findings through "
+            "the patch plan (see SHIP.md)"
+        )
     pending = uncommitted_paths(repo)
     forced: Set[str] = set()
     # Build only: an approval undo resets to a parent without the ledger and would drop it.

package/skills/gsd-path-ship/scripts/lean_verification.py

@@ -108,10 +108,14 @@ def _final_view(relative, text, criteria, reviewed, head, surfaces=None):
                 fields[field] = contracts._raw_source_field(block, field, relative)
         if "Surface" in fields and not {"Check", "Observed"}.issubset(fields):
             raise contracts.HandoffError(f"{criterion} lacks its recorded surface walkthrough")
+        reference = f"{relative} — {criterion}"
+        if "Observed" in fields and evidence:
+            # The reviewer may cite held-out and judgment ids on the evidence line.
+            reference += f"; evidence: {evidence}"
         lines += [f"### {criterion} — {title}", "", "- **Verdict**: met",
                   f"- **Check**: {fields.get('Check', 'none')}",
                   f"- **Observed**: {fields.get('Observed', evidence)}",
-                  f"- **Reference**: {relative} — {criterion}",
+                  f"- **Reference**: {reference}",
                   "- **Finding**: none", "- **Fix direction**: none"]
         if "Surface" in fields:
             expected = (surfaces or {}).get(criterion)

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

@@ -196,7 +196,14 @@ def task_settings(path):
 
 def native_record(args):
     """The parent owns lifecycle; release requires its recorded terminal-result receipt."""
+    # A relative path would resolve against cwd, which may be the immutable runtime store.
+    if not args.record.is_absolute():
+        raise PolicyError(f'--record must be an absolute path: {args.record}')
     record = args.record.resolve()
+    missing = f'release requires an existing record and terminal-result evidence: {record}'
+    # Check before log_lock creates the record directory and its lock file.
+    if args.action == 'release' and not record.exists():
+        raise PolicyError(missing)
     with log_lock({'log': str(record)}):
         data = read_json(record) if record.exists() else None
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
@@ -209,7 +216,7 @@ def native_record(args):
             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')
+                raise PolicyError(missing)
             data.update(active=False, terminal_result=args.terminal_result)
         else:
             if args.capabilities is None:

package/skills/gsd-path-ship/scripts/pipeline_git.py

@@ -484,7 +484,12 @@ def _require_tag_integration_proof(
         "1",
         landing,
     ).stdout.split()
-    if len(parents) != 3 or parents[2] != ship:
+    rebased = (
+        mode == "pull-request"
+        and len(parents) == 2
+        and _common.rebase_landing_problem(repo, ship, landing) is None
+    )
+    if not rebased and (len(parents) != 3 or parents[2] != ship):
         raise PipelineGitError(f"{mode} integration proof has invalid merge topology")
     first_parent = _run_git(repo, "rev-list", "--first-parent", base).stdout.splitlines()
     if landing not in first_parent:
@@ -694,6 +699,7 @@ def retire_previous_branch(
     expected_sha: str,
     *,
     allow_remote_absent: bool = False,
+    rebased: bool = False,
 ) -> None:
     """Delete an integrated previous bound branch, locally and on origin.
 
@@ -741,7 +747,8 @@ def retire_previous_branch(
     if _ref_exists(repo, tracking_ref):
         _run_git(repo, "update-ref", "-d", tracking_ref)
     if _ref_exists(repo, local_ref):
-        _run_git(repo, "branch", "-d", previous_branch)
+        # A rebased ship is not an ancestor of HEAD, so -d would refuse it.
+        _run_git(repo, "branch", "-D" if rebased else "-d", previous_branch)
 
 
 def _retire_members(repo: Path, ship_sha: str) -> None:
@@ -840,9 +847,15 @@ def bind_next_milestone_branch(
         landing_sha,
         check=False,
     )
-    if integrated.returncode == 1:
+    # A forge rebase merge lands copies of the ship commits (#418); the
+    # pull-request milestone tag must then prove the landing.
+    rebased = (
+        integrated.returncode == 1
+        and _common.rebase_landing_problem(repo, ship_sha, landing_sha) is None
+    )
+    if integrated.returncode == 1 and not rebased:
         raise PipelineGitError("milestone landing does not contain the ship commit")
-    if integrated.returncode != 0:
+    if integrated.returncode not in (0, 1):
         detail = integrated.stderr.strip() or integrated.stdout.strip()
         raise PipelineGitError(f"could not verify milestone landing: {detail}")
     landing_integrated = _run_git(
@@ -858,7 +871,7 @@ def bind_next_milestone_branch(
     if landing_integrated.returncode != 0:
         detail = landing_integrated.stderr.strip() or landing_integrated.stdout.strip()
         raise PipelineGitError(f"could not verify integrated branch: {detail}")
-    if allow_remote_absent:
+    if allow_remote_absent or rebased:
         proven_landing = _require_tag_integration_proof(
             repo,
             ship_sha,
@@ -994,6 +1007,7 @@ def bind_next_milestone_branch(
         allow_remote_absent=(
             allow_remote_absent or journal["stage"] in {"switched", "retired"}
         ),
+        rebased=rebased,
     )
     _retire_members(repo, ship_sha)
     journal["stage"] = "retired"

package/skills/gsd-path-ship/scripts/pipeline_state.py

@@ -1024,7 +1024,9 @@ def _bind_next_journal_recovery(
     )
     if resolved_landing.returncode != 0 or resolved_landing.stdout.strip() != landing:
         raise PipelineStateError("bind-next journal landing is not an existing full SHA")
-    if not _is_ancestor(repo, ship, landing):
+    if not _is_ancestor(repo, ship, landing) and _common.rebase_landing_problem(
+        repo, ship, landing
+    ) is not None:
         raise PipelineStateError("bind-next journal landing does not contain ship")
     if not _is_ancestor(repo, landing, base):
         raise PipelineStateError("bind-next journal landing is not an ancestor of base")

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

@@ -343,6 +343,67 @@ def _completed_promotion(
     }
 
 
+def _ruling_rows(text: str) -> dict[str, list[str]]:
+    """Map Queue # to the cells of each `## User rulings` table row."""
+    rows: dict[str, list[str]] = {}
+    in_rulings = False
+    for line in text.splitlines():
+        if line == "## User rulings":
+            in_rulings = True
+            continue
+        if in_rulings and line.startswith("## "):
+            break
+        if in_rulings and line.lstrip().startswith("|"):
+            cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+            if len(cells) == 4 and cells[0].isdigit():
+                rows[cells[0]] = cells
+    return rows
+
+
+def _superseded_carry_forward(
+    repo: Path,
+    active_state: PipelineState,
+    source: Path,
+    destination: Path,
+) -> bool:
+    """True when active research is only the shipped DOCS-AUDIT carry-forward
+    and the lookahead audit keeps every one of its rulings."""
+    if not active_state.archive or destination.is_symlink() or not destination.is_dir():
+        return False
+    archived = repo / active_state.archive / "research" / "DOCS-AUDIT.md"
+    active = destination / "DOCS-AUDIT.md"
+    lookahead = source / "DOCS-AUDIT.md"
+    entries = [
+        path for path in destination.iterdir() if not state_checkpoint._is_junk_file(path)
+    ]
+    if entries != [active] or any(
+        path.is_symlink() or not path.is_file() for path in (archived, active, lookahead)
+    ):
+        return False
+    carried = active.read_bytes()
+    if carried != archived.read_bytes():
+        return False
+    rulings = _ruling_rows(carried.decode("utf-8"))
+    if not any(cells[3] == "no" for cells in rulings.values()):
+        return False
+    kept = _ruling_rows(lookahead.read_text(encoding="utf-8"))
+    for number, cells in rulings.items():
+        other = kept.get(number)
+        # Plan may record a T### for a pending ruling; nothing else may change.
+        if (
+            other is None
+            or other[:3] != cells[:3]
+            or (
+                other[3] != cells[3]
+                and not (cells[3] == "no" and re.fullmatch(r"T\d{3}", other[3]))
+            )
+        ):
+            raise PipelineStateError(
+                f"lookahead DOCS-AUDIT.md does not keep carry-forward ruling #{number}"
+            )
+    return True
+
+
 def _prepare_promotion(
     repo: Path,
     project: Path,
@@ -475,12 +536,17 @@ def _prepare_promotion(
         raise PipelineStateError("lookahead STATE branch and archive must be null")
 
     tracks: dict[str, str] = {}
+    carry_forward: Optional[str] = None
     for name in PROMOTION_TRACKS:
         source = next_root / name
         destination = project / name
         if source.exists() or source.is_symlink():
             if destination.exists() or destination.is_symlink():
-                raise PipelineStateError(f"promotion destination already exists: {destination}")
+                if name != "research" or not _superseded_carry_forward(
+                    repo, active_state, source, destination
+                ):
+                    raise PipelineStateError(f"promotion destination already exists: {destination}")
+                carry_forward = state_checkpoint._tree_digest(destination)
             tracks[name] = state_checkpoint._tree_digest(source)
     if not tracks:
         raise PipelineStateError("lookahead track has no promotable artifacts")
@@ -507,6 +573,7 @@ def _prepare_promotion(
         "landing": landing,
         "base": base,
         "tracks": tracks,
+        "carry_forward_sha256": carry_forward,
         "residual_sha256": state_checkpoint._tree_digest(next_root, tuple(tracks)),
         "next_state_sha256": state_checkpoint._sha256(next_text),
         "active_state_sha256": state_checkpoint._sha256(active_text),
@@ -559,6 +626,15 @@ def _resume_track_moves(project: Path, journal: dict[str, object], path: Path) -
         destination = project / name
         source_exists = source.exists() or source.is_symlink()
         destination_exists = destination.exists() or destination.is_symlink()
+        carry_forward = journal.get("carry_forward_sha256")
+        if name == "research" and source_exists and destination_exists and carry_forward:
+            if state_checkpoint._tree_digest(destination) != carry_forward:
+                raise PipelineStateError("DOCS-AUDIT carry-forward drifted during promotion")
+            # The archive and the ship commit keep the carry-forward copy.
+            shutil.rmtree(destination)
+            journal["stage"] = "removed:carry-forward"
+            pipeline_state._write_json(path, journal)
+            destination_exists = False
         if source_exists and destination_exists:
             raise PipelineStateError(f"promotion has both source and destination: {name}")
         if not source_exists and not destination_exists:

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

@@ -136,8 +136,9 @@ bundles this file; spawned agents follow their role brief instead.
   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
+  commit; PR mode requires tag metadata and either a two-parent merge whose
+  second parent is the ship commit or a proven rebase merge of the ship
+  commits. 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

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

@@ -27,7 +27,8 @@ 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.
+that it imports from the selected runtime, and runs the subprocess helpers that
+the runtime lists (such as the fix-task brief lint) from it.
 
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`

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

@@ -361,6 +361,49 @@ def run_git(
     return _run_exact(git_command(repo, *arguments), input=input)
 
 
+def _patch_ids(repo: Path, commits: Sequence[str]) -> list[Optional[str]]:
+    """`git patch-id --stable` per commit, in order; None for an empty commit."""
+    log = run_git(repo, "log", "--no-walk=unsorted", "-p", "--binary", "--no-color",
+                  "--no-ext-diff", *commits)
+    if log.returncode != 0:
+        raise ValueError("could not read commit patches")
+    ids = run_git(repo, "patch-id", "--stable", input=log.stdout)
+    if ids.returncode != 0:
+        raise ValueError("could not compute patch ids")
+    by_commit = {commit: patch for patch, commit in (line.split() for line in ids.stdout.splitlines())}
+    return [by_commit.get(commit) for commit in commits]
+
+
+def rebase_landing_problem(repo: Path, ship: str, landing: str) -> Optional[str]:
+    """Why landing is not a forge rebase merge of ship, or None when it is (#418).
+
+    A rebase merge replays ship's own commits onto the default branch. Proof:
+    the first-parent run that ends at landing has one non-merge commit per
+    non-merge commit of landing..ship, with equal patch ids in the same order;
+    when that run starts at ship's fork point, landing's tree equals ship's.
+    """
+    listed = run_git(repo, "rev-list", "--reverse", "--topo-order", "--no-merges", f"{landing}..{ship}")
+    if listed.returncode != 0:
+        return "could not list the ship commits"
+    originals = listed.stdout.split()
+    if not originals:
+        return "landing already contains the ship commit"
+    walked = run_git(repo, "rev-list", "--first-parent", "--parents", "-n", str(len(originals)), landing)
+    rows = [line.split() for line in walked.stdout.splitlines()][::-1]
+    if walked.returncode != 0 or len(rows) != len(originals) or any(len(row) != 2 for row in rows):
+        return "landing is not a linear run of rebased commits"
+    try:
+        if _patch_ids(repo, originals) != _patch_ids(repo, [row[0] for row in rows]):
+            return "rebased commits do not replay the ship commits in order"
+    except ValueError as error:
+        return str(error)
+    fork = run_git(repo, "merge-base", ship, landing).stdout.strip()
+    trees = run_git(repo, "rev-parse", f"{ship}^{{tree}}", f"{landing}^{{tree}}").stdout.split()
+    if rows[0][1] == fork and (len(trees) != 2 or trees[0] != trees[1]):
+        return "rebased tree differs from the ship tree"
+    return None
+
+
 def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
     """Git argv for repo, including WSL drvfs workarounds when needed."""
     return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)

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

@@ -196,7 +196,14 @@ def task_settings(path):
 
 def native_record(args):
     """The parent owns lifecycle; release requires its recorded terminal-result receipt."""
+    # A relative path would resolve against cwd, which may be the immutable runtime store.
+    if not args.record.is_absolute():
+        raise PolicyError(f'--record must be an absolute path: {args.record}')
     record = args.record.resolve()
+    missing = f'release requires an existing record and terminal-result evidence: {record}'
+    # Check before log_lock creates the record directory and its lock file.
+    if args.action == 'release' and not record.exists():
+        raise PolicyError(missing)
     with log_lock({'log': str(record)}):
         data = read_json(record) if record.exists() else None
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
@@ -209,7 +216,7 @@ def native_record(args):
             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')
+                raise PolicyError(missing)
             data.update(active=False, terminal_result=args.terminal_result)
         else:
             if args.capabilities is None:

package/skills/path/BUILD.md

@@ -130,7 +130,9 @@ STATE.md-only "finalize" checkpoint for work already checkpointed. The helper
 refuses a `build:` checkpoint that deletes or renames a `.project/tasks/`
 brief unless the canonical `build: abandon milestone <slug>` checkpoint moves
 that same brief into `.project/archive/`; build adds fix tasks and repairs
-briefs, it never replans.
+briefs, it never replans. It also refuses a `build:` checkpoint while the
+committed STATE is `ship/active`: final-review outputs stay uncommitted until
+the ship commit.
 
 ## Execute from runtime receipts
 

package/skills/path/PLAN.md

@@ -263,8 +263,9 @@ as stated in Lookahead mode.
 
    Before approval, the helper validates the task graph and brief paths.
    Pending briefs may reference files supplied by transitive dependencies.
-   Landed briefs use their recorded historical base, with no dependency-file
-   allowance, so later file changes do not invalidate immutable briefs.
+   A landed brief is immutable history: the helper checks its `files` scope
+   at the recorded historical base and does not check the paths that its
+   prose and Verify name.
    This applies to plan re-approval too; the dispatch CLI remains HEAD-only
    with no overrides.
 

package/skills/path/SHIP.md

@@ -69,7 +69,8 @@ so the position is unchanged. Then:
    task logs prove it is the immediately preceding `ship/blocked` finding
    set, the approved patch tasks copied every finding verbatim, and those tasks
    are now done; otherwise it blocks. Git history preserves the superseded
-   finding, while final review itself still creates no pre-ship commit.
+   finding, while final review itself still creates no pre-ship commit
+   (`isolation.py checkpoint` refuses a `build:` checkpoint at `ship/active`).
 2. Derive a stable numbered list of cross-wave integration risks from
    interfaces and flows that span waves. List only genuine risks that could
    plausibly fail; never pad the list. Include PLAN.md's project Verify as
@@ -341,13 +342,18 @@ The persisted `STATE.archive` field is the transaction identity.
      PR is open, the helper returns `status: awaiting-merge`. Present
      **Outcome**, link
      the returned PR as **Review**, and state in **Next** that the user must
-     merge it with GitHub's merge-commit method. Stop this ship invocation;
-     Path never enables auto-merge or merges the PR. On rerun after a human
-     GitHub user merges it, the helper requires the PR head to remain the ship
-     commit and its landing to be a two-parent merge with that ship commit as
-     second parent on `origin/main` first-parent history. It then writes and
-     pushes the annotated milestone tag containing the PR URL, ship SHA, and
-     landing SHA. A closed unmerged PR, squash, rebase, merge queue, moved
+     merge it with GitHub's merge-commit or rebase method. Stop this ship
+     invocation; Path never enables auto-merge or merges the PR. On rerun after
+     a human GitHub user merges it, the helper requires the PR head to remain
+     the ship commit and its landing to be on `origin/main` first-parent
+     history as either a two-parent merge with that ship commit as second
+     parent, or a rebase merge: the last of a first-parent run of single-parent
+     commits whose `git patch-id --stable` values match, in order, the
+     non-merge commits from the landing to the ship commit (with equal trees
+     when `main` did not move). It then writes and pushes the annotated
+     milestone tag containing the PR URL, ship SHA, and landing SHA. A
+     milestone that was rebase-merged before this support existed recovers by
+     rerunning ship. A closed unmerged PR, squash, 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

package/skills/path/references/model-policy.md

@@ -70,7 +70,9 @@ settings block; their default inheritance remains usable.
 Resolve the bundled helper to an absolute path. Use one record under the Git
 common directory's `gsd-path/model-selection/` directory per assignment. Scope
 the path and `--scope` to the milestone, active/lookahead track, and review cycle
-where applicable; later work must not reuse an earlier record.
+where applicable; later work must not reuse an earlier record. The helper
+refuses a relative `--record`, and `release` of a missing record names the
+path and creates nothing.
 
 ```text
 python3 -B <helper> resolve --repo <primary> --scope <milestone/track/cycle> --assignment <logical-name> --role <role> --record <absolute-record> --capabilities <advertised-json>

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

@@ -136,8 +136,9 @@ bundles this file; spawned agents follow their role brief instead.
   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
+  commit; PR mode requires tag metadata and either a two-parent merge whose
+  second parent is the ship commit or a proven rebase merge of the ship
+  commits. 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

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

@@ -27,7 +27,8 @@ 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.
+that it imports from the selected runtime, and runs the subprocess helpers that
+the runtime lists (such as the fix-task brief lint) from it.
 
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`

package/skills/path/scripts/_common.py

@@ -361,6 +361,49 @@ def run_git(
     return _run_exact(git_command(repo, *arguments), input=input)
 
 
+def _patch_ids(repo: Path, commits: Sequence[str]) -> list[Optional[str]]:
+    """`git patch-id --stable` per commit, in order; None for an empty commit."""
+    log = run_git(repo, "log", "--no-walk=unsorted", "-p", "--binary", "--no-color",
+                  "--no-ext-diff", *commits)
+    if log.returncode != 0:
+        raise ValueError("could not read commit patches")
+    ids = run_git(repo, "patch-id", "--stable", input=log.stdout)
+    if ids.returncode != 0:
+        raise ValueError("could not compute patch ids")
+    by_commit = {commit: patch for patch, commit in (line.split() for line in ids.stdout.splitlines())}
+    return [by_commit.get(commit) for commit in commits]
+
+
+def rebase_landing_problem(repo: Path, ship: str, landing: str) -> Optional[str]:
+    """Why landing is not a forge rebase merge of ship, or None when it is (#418).
+
+    A rebase merge replays ship's own commits onto the default branch. Proof:
+    the first-parent run that ends at landing has one non-merge commit per
+    non-merge commit of landing..ship, with equal patch ids in the same order;
+    when that run starts at ship's fork point, landing's tree equals ship's.
+    """
+    listed = run_git(repo, "rev-list", "--reverse", "--topo-order", "--no-merges", f"{landing}..{ship}")
+    if listed.returncode != 0:
+        return "could not list the ship commits"
+    originals = listed.stdout.split()
+    if not originals:
+        return "landing already contains the ship commit"
+    walked = run_git(repo, "rev-list", "--first-parent", "--parents", "-n", str(len(originals)), landing)
+    rows = [line.split() for line in walked.stdout.splitlines()][::-1]
+    if walked.returncode != 0 or len(rows) != len(originals) or any(len(row) != 2 for row in rows):
+        return "landing is not a linear run of rebased commits"
+    try:
+        if _patch_ids(repo, originals) != _patch_ids(repo, [row[0] for row in rows]):
+            return "rebased commits do not replay the ship commits in order"
+    except ValueError as error:
+        return str(error)
+    fork = run_git(repo, "merge-base", ship, landing).stdout.strip()
+    trees = run_git(repo, "rev-parse", f"{ship}^{{tree}}", f"{landing}^{{tree}}").stdout.split()
+    if rows[0][1] == fork and (len(trees) != 2 or trees[0] != trees[1]):
+        return "rebased tree differs from the ship tree"
+    return None
+
+
 def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
     """Git argv for repo, including WSL drvfs workarounds when needed."""
     return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)