@opengsd/gsd-path 1.4.0 → 1.5.0

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

@@ -514,16 +514,28 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
     """Run one spec command; a hung command counts as failed (exit None).
 
     POSIX runs /bin/sh as shell=True did; Windows runs Git for Windows bash, not
-    cmd.exe. A timeout kills the whole process group, so a grandchild cannot
-    keep the output pipes open.
+    cmd.exe. A timeout kills the whole process group when possible; if output
+    pipes stay open, drain them with a short grace timeout and then close them.
     """
     argv = _common.bash_argv(command) if os.name == "nt" else ["/bin/sh", "-c", command]
     process = _common.popen_group(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdout = b""
+    stderr = b""
     try:
         stdout, stderr = process.communicate(timeout=timeout)
-    except subprocess.TimeoutExpired:
+    except subprocess.TimeoutExpired as expired:
         _common.kill_tree(process)
-        stdout, stderr = process.communicate()
+        try:
+            stdout, stderr = process.communicate(timeout=5)
+        except subprocess.TimeoutExpired as drained:
+            stdout = drained.stdout or expired.stdout or b""
+            stderr = drained.stderr or expired.stderr or b""
+            if process.stdout:
+                process.stdout.close()
+            if process.stderr:
+                process.stderr.close()
+            process.kill()
+            process.wait(timeout=5)
         output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")
         return None, f"{output}\ntimed out at the admitted wall-clock deadline"
     return process.returncode, (stdout + stderr).decode("utf-8", errors="replace")

package/skills/gsd-path-research/scripts/members.py

@@ -255,6 +255,7 @@ def check_member(
     coordinator_name: str,
     checkout: Path,
     recorded_remote: Optional[str] = None,
+    refuse_reserved_refs: bool = True,
 ) -> str:
     """Refuse a checkout that cannot join; return its origin URL."""
     if checkout.is_symlink() or not checkout.is_dir():
@@ -294,13 +295,14 @@ def check_member(
             raise MembersError(f"member STATE.md is unreadable: {error}") from error
         if state.milestone is not None and (state.phase, state.status) != ("shipped", "done"):
             raise MembersError(f"member has an active milestone: {state.milestone}")
-    prefixes = member_ref_prefixes(coordinator_name) + tuple(
-        "refs/remotes/origin/" + branch.format(coordinator_name) for branch in MEMBER_BRANCH_FORMATS
-    )
-    refs = _git(checkout, "for-each-ref", "--format=%(refname)").splitlines()
-    colliding = [ref for ref in refs if ref.startswith(prefixes)]
-    if colliding:
-        raise MembersError("member refs collide with coordinator names: " + ", ".join(colliding))
+    if refuse_reserved_refs:
+        prefixes = member_ref_prefixes(coordinator_name) + tuple(
+            "refs/remotes/origin/" + branch.format(coordinator_name) for branch in MEMBER_BRANCH_FORMATS
+        )
+        refs = _git(checkout, "for-each-ref", "--format=%(refname)").splitlines()
+        colliding = [ref for ref in refs if ref.startswith(prefixes)]
+        if colliding:
+            raise MembersError("member refs collide with coordinator names: " + ", ".join(colliding))
     return remote
 
 
@@ -620,7 +622,7 @@ def validate_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"])
+        check_member(root, state.project, checkout, member["remote"], refuse_reserved_refs=False)
         try:
             role = member_role(checkout)
         except MembersError as error:
@@ -639,7 +641,7 @@ def repair_members(repo: Path) -> list[dict[str, str]]:
     members = read_members(root)
     for member in members:
         checkout = Path(member["checkout"])
-        check_member(root, state.project, checkout, member["remote"])
+        check_member(root, state.project, checkout, member["remote"], refuse_reserved_refs=False)
         _refuse_foreign_marker(checkout.resolve(), root, state.project, member["name"])
     for member in members:
         checkout = Path(member["checkout"]).resolve()

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

@@ -13,7 +13,7 @@ sys.dont_write_bytecode = True
 ROLES = ('coder', 'reviewer', 'review_panel', 'skeptic', 'inspect_codebase',
          'inspect_docs', 'docs_audit', 'research', 'decide', 'roadmap', 'plan', 'plan_patch')
 HOSTS = ('codex', 'claude', 'grok', 'opencode', 'copilot', 'qwen', 'antigravity',
-         'cursor', 'zed', 'kiro', 'kimi')
+         'cursor', 'zed', 'kiro', 'kimi', 'muse')
 
 
 def sibling(name):
@@ -73,8 +73,8 @@ def validate_value(key, value):
     if not isinstance(value, str) or not value or value != value.strip():
         raise ValueError(f'{key} requires a nonempty string')
     if key == 'integration':
-        if value not in ('direct', 'pull-request'):
-            raise ValueError('integration must be direct or pull-request')
+        if value not in ('direct', 'pull-request', 'external-landing'):
+            raise ValueError('integration must be direct, pull-request, or external-landing')
     elif key == 'review_panel':
         if any(char.isspace() for char in value):
             raise ValueError('use off, detected, or comma-separated families without spaces')

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

@@ -146,6 +146,29 @@ def ship_commit_body(archive_path: str, reviewed_head: str, members: Sequence[di
     )
 
 
+_TRAILER_LINE = re.compile(r"^[A-Za-z-]+:\s")
+
+
+def ship_body_matches(body: str, expected_body: str) -> bool:
+    """True when body equals the contract or adds only optional git trailers after it."""
+    normalized = body.rstrip("\n")
+    expected = expected_body.rstrip("\n")
+    if normalized == expected:
+        return True
+    prefix = expected + "\n"
+    if not normalized.startswith(prefix):
+        return False
+    remainder = normalized[len(prefix):]
+    if not remainder:
+        return True
+    for line in remainder.splitlines():
+        if not line.strip():
+            return False
+        if not _TRAILER_LINE.match(line):
+            return False
+    return True
+
+
 def integrate_commit_body(
     archive_path: str,
     ship_commit: str,
@@ -270,22 +293,50 @@ def _symbolic_branch(repo: Path) -> str:
     return result.stdout.strip()
 
 
-def _branch_worktrees(repo: Path) -> dict[str, Path]:
-    """Return every checked-out local branch from Git's worktree registry."""
-    output = _run_git(repo, "worktree", "list", "--porcelain", "-z").stdout
+def worktree_list_porcelain(repo: Path) -> tuple[str, bool]:
+    """Return worktree list output and whether it is NUL-separated."""
+    result = _run_git(repo, "worktree", "list", "--porcelain", "-z", check=False)
+    if result.returncode == 0:
+        return result.stdout, True
+    result = _run_git(repo, "worktree", "list", "--porcelain", check=False)
+    if result.returncode != 0:
+        message = (result.stderr or result.stdout).strip() or "could not list worktrees"
+        raise PipelineGitError(message)
+    return result.stdout, False
+
+
+def branch_worktrees_from_porcelain(output: str, *, nul_separated: bool) -> dict[str, Path]:
     worktrees: dict[str, Path] = {}
-    current_path: Optional[Path] = None
-    for field in output.split("\0"):
-        if field.startswith("worktree "):
-            current_path = Path(field.removeprefix("worktree ")).resolve()
-        elif field.startswith("branch ") and current_path is not None:
-            ref = field.removeprefix("branch ")
-            prefix = "refs/heads/"
-            if ref.startswith(prefix):
-                worktrees[ref.removeprefix(prefix)] = current_path
+    if nul_separated:
+        current_path: Optional[Path] = None
+        for field in output.split("\0"):
+            if not field:
+                continue
+            if field.startswith("worktree "):
+                current_path = Path(field.removeprefix("worktree ")).resolve()
+            elif field.startswith("branch ") and current_path is not None:
+                ref = field.removeprefix("branch ")
+                prefix = "refs/heads/"
+                if ref.startswith(prefix):
+                    worktrees[ref.removeprefix(prefix)] = current_path
+        return worktrees
+    for block in output.strip().split("\n\n"):
+        fields = block.splitlines()
+        if not fields or not fields[0].startswith("worktree "):
+            continue
+        current_path = Path(fields[0].removeprefix("worktree ")).resolve()
+        for line in fields[1:]:
+            if line.startswith("branch refs/heads/"):
+                worktrees[line.removeprefix("branch refs/heads/")] = current_path
     return worktrees
 
 
+def _branch_worktrees(repo: Path) -> dict[str, Path]:
+    """Return every checked-out local branch from Git's worktree registry."""
+    output, nul_separated = worktree_list_porcelain(repo)
+    return branch_worktrees_from_porcelain(output, nul_separated=nul_separated)
+
+
 def _remote_ref_sha(repo: Path, ref: str) -> Optional[str]:
     if not _origin_remote_exists(repo):
         raise PipelineGitError("origin remote is not configured")

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

@@ -91,7 +91,7 @@ STATE_FIELDS = (
     "integration_source",
 )
 LEGACY_STATE_FIELDS = STATE_FIELDS[:7]
-INTEGRATION_MODES = ("direct", "pull-request")
+INTEGRATION_MODES = ("direct", "pull-request", "external-landing")
 INTEGRATION_SOURCES = ("default", "milestone")
 NULL = "null"
 SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
@@ -141,6 +141,8 @@ CROSS_PHASE_TRANSITIONS = {
     ("decide", "done", "plan", "active"),
     ("roadmap", "done", "define", "active"),
     ("plan", "done", "build", "active"),
+    ("plan", "active", "define", "active"),
+    ("plan", "blocked", "define", "active"),
     ("build", "blocked", "define", "active"),
     ("build", "blocked", "plan", "active"),
     ("build", "active", "ship", "active"),
@@ -193,11 +195,24 @@ def _run_git(
     *arguments: str,
     check: bool = True,
 ) -> subprocess.CompletedProcess[str]:
+    command = _common.git_command(repo, *arguments)
     result = subprocess.run(
-        ["git", "-C", str(repo), *arguments],
+        command,
         capture_output=True,
         encoding="utf-8", errors="replace",
     )
+    if (
+        check
+        and result.returncode != 0
+        and arguments
+        and arguments[0] == "commit"
+        and _common.git_index_lock_retryable(result.stderr)
+    ):
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            encoding="utf-8", errors="replace",
+        )
     if check and result.returncode != 0:
         detail = result.stderr.strip() or result.stdout.strip()
         raise PipelineStateError(f"git {' '.join(arguments)} failed: {detail}")
@@ -911,36 +926,13 @@ def _legacy_bind_next_landing(repo: Path, state: PipelineState) -> str:
     return landing
 
 
-def _bind_next_recovery(
+def _bind_next_journal_recovery(
     repo: Path,
     state: PipelineState,
+    path: Path,
+    transaction: dict[str, object],
+    current: Optional[str],
 ) -> Optional[dict[str, object]]:
-    journal_root = _git_path(repo, BIND_NEXT_JOURNAL_DIR)
-    if not journal_root.exists() and not journal_root.is_symlink():
-        return None
-    if journal_root.is_symlink() or not journal_root.is_dir():
-        raise PipelineStateError(f"bind-next journal root must be a real directory: {journal_root}")
-
-    matches: list[tuple[Path, dict[str, object]]] = []
-    for path in sorted(journal_root.glob("*.json")):
-        transaction = _read_json(path)
-        if transaction.get("schema") not in {
-            LEGACY_BIND_NEXT_JOURNAL_SCHEMA,
-            BIND_NEXT_JOURNAL_SCHEMA,
-        }:
-            raise PipelineStateError(f"bind-next journal has invalid schema: {path}")
-        if transaction.get("repo") != str(repo):
-            raise PipelineStateError(f"bind-next journal belongs to another worktree: {path}")
-        if transaction.get("previous_branch") == state.branch:
-            matches.append((path, transaction))
-    if not matches:
-        return None
-    if len(matches) != 1:
-        raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
-    if state.phase != "shipped" or state.status != "done":
-        raise PipelineStateError("bind-next journal requires STATE shipped/done")
-
-    path, transaction = matches[0]
     required = (
         "branch",
         "previous_branch",
@@ -1022,7 +1014,32 @@ def _bind_next_recovery(
     if stage not in {"prepared", "switched", "retired"}:
         raise PipelineStateError("bind-next journal has invalid stage")
 
-    current = _current_branch(repo)
+    stale_retired = False
+    if stage == "retired":
+        target_ref = _run_git(
+            repo,
+            "show-ref",
+            "--verify",
+            "--quiet",
+            f"refs/heads/{branch}",
+            check=False,
+        )
+        if target_ref.returncode not in {0, 1}:
+            detail = (target_ref.stderr or target_ref.stdout).strip()
+            raise PipelineStateError(
+                f"could not check bind-next target branch {branch}: {detail}"
+            )
+        target_exists = target_ref.returncode == 0
+        stale_retired = current not in {previous, branch} or not target_exists
+    if stale_retired:
+        # If the completed target is gone while the previous branch is checked
+        # out, still prove that branch has not moved away from the recorded ship.
+        if current == previous:
+            head = _run_git(repo, "rev-parse", "HEAD").stdout.strip()
+            if head != ship:
+                raise PipelineStateError("bind-next previous branch is not at journal ship")
+        return None
+
     if current not in {previous, branch}:
         raise PipelineStateError("bind-next journal does not own the current branch")
     if current == previous and stage != "prepared":
@@ -1057,6 +1074,52 @@ def _bind_next_recovery(
     return result
 
 
+def _bind_next_recovery(
+    repo: Path,
+    state: PipelineState,
+) -> Optional[dict[str, object]]:
+    journal_root = _git_path(repo, BIND_NEXT_JOURNAL_DIR)
+    if not journal_root.exists() and not journal_root.is_symlink():
+        return None
+    if journal_root.is_symlink() or not journal_root.is_dir():
+        raise PipelineStateError(f"bind-next journal root must be a real directory: {journal_root}")
+
+    matches: list[tuple[Path, dict[str, object]]] = []
+    for path in sorted(journal_root.glob("*.json")):
+        transaction = _read_json(path)
+        if transaction.get("schema") not in {
+            LEGACY_BIND_NEXT_JOURNAL_SCHEMA,
+            BIND_NEXT_JOURNAL_SCHEMA,
+        }:
+            raise PipelineStateError(f"bind-next journal has invalid schema: {path}")
+        if transaction.get("repo") != str(repo):
+            raise PipelineStateError(f"bind-next journal belongs to another worktree: {path}")
+        if transaction.get("previous_branch") == state.branch:
+            matches.append((path, transaction))
+    if not matches:
+        return None
+    if state.phase != "shipped" or state.status != "done":
+        if len(matches) != 1:
+            raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
+        raise PipelineStateError("bind-next journal requires STATE shipped/done")
+
+    current = _current_branch(repo)
+    recoveries: list[dict[str, object]] = []
+    for path, transaction in matches:
+        recovery = _bind_next_journal_recovery(
+            repo,
+            state,
+            path,
+            transaction,
+            current,
+        )
+        if recovery is not None:
+            recoveries.append(recovery)
+    if len(recoveries) > 1:
+        raise PipelineStateError("multiple bind-next journals claim the current STATE branch")
+    return recoveries[0] if recoveries else None
+
+
 def _pending_discussion_block(repo: Path, phase: Optional[str]) -> Optional[str]:
     pending, error = _pending_answers(repo)
     if error:
@@ -1077,7 +1140,7 @@ def route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]:
             result["recovery"] = recovery
             if route.get("phase") == "define":
                 route["mode"] = "corrections"
-            elif route.get("phase") == "plan":
+            elif route.get("phase") == "plan" and recovery.get("source", "build") == "build":
                 route["mode"] = "build-repair"
     if route["action"] == "run-phase" and result["state"]["archive"] is None:
         reason = _pending_discussion_block(_repo_root(repo), route.get("phase"))
@@ -1668,6 +1731,8 @@ def _validate_transition(
         },
         ("define", "done", "plan", "active"): {"planning started"},
         ("decide", "done", "plan", "active"): {"planning started"},
+        ("plan", "active", "define", "active"): {"plan intent corrections requested"},
+        ("plan", "blocked", "define", "active"): {"plan intent corrections requested"},
         ("ship", "blocked", "plan", "active"): {"patch plan reopened"},
         ("ship", "active", "shipped", "done"): {
             "archive preflight passed; shipment recorded",
@@ -1720,9 +1785,10 @@ def transition_state(
             )
             if reason:
                 raise PipelineStateError(reason)
-        if state.phase in {"research", "decide"} and (
+        leaving_define = (state.phase, after.phase, after.status) == ("define", "define", "done")
+        if leaving_define or (state.phase in {"research", "decide"} and (
             after.phase != state.phase or after.status == "done"
-        ):
+        )):
             if __package__:
                 from . import check_handoffs
             else:
@@ -1731,6 +1797,8 @@ def transition_state(
                 except ImportError:  # pragma: no cover - package imports used by tests
                     from scripts import check_handoffs
             validator = {
+                # Approved intent carries its spec-reach probe tables complete.
+                "define": check_handoffs.validate_intent_probes,
                 "research": check_handoffs.validate_research_artifacts,
                 "decide": check_handoffs.validate_decide_artifacts,
             }[state.phase]
@@ -1747,6 +1815,16 @@ def transition_state(
                 rendered, after.phase,
                 _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
             )
+        elif (
+            state.phase == "plan"
+            and state.status in {"active", "blocked"}
+            and (after.phase, after.status) == ("define", "active")
+        ):
+            recovery = _build_recovery().begin(resolved, state, after, event)
+            rendered = _append_event(
+                rendered, after.phase,
+                _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
+            )
         _atomic_write(path, rendered)
     return {
         "schema": STATE_SCHEMA,

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

@@ -18,14 +18,14 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional, Sequence
 
 if __package__:
-    from .isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+    from .isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 else:
     try:
-        from isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+        from isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
     except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
         if error.name != "isolation":
             raise
-        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 
 
 if __package__:
@@ -444,14 +444,14 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
         # Pre-Git approval defers base-dependent checks to build.
         return
     if __package__:
-        from .check_task_briefs import BriefError, _member_bases, validate_task_briefs
+        from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     else:
         try:
-            from check_task_briefs import BriefError, _member_bases, validate_task_briefs
+            from check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
         except ModuleNotFoundError as error:  # pragma: no cover - package imports
             if error.name != "check_task_briefs":
                 raise
-            from scripts.check_task_briefs import BriefError, _member_bases, validate_task_briefs
+            from scripts.check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     if __package__:
         from . import check_handoffs
     else:
@@ -462,28 +462,10 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
                 raise
             from scripts import check_handoffs
     try:
-        tasks, dependency_files = check_handoffs.plan_brief_inputs(repo, project_dir)
-        landed_bases = {}
         member_base = _member_bases(repo)
-        for task_id, text in tasks.items():
-            if check_handoffs._task_scalar(text, task_id, "status") != "done":
-                continue
-            agent = check_handoffs._task_scalar(text, task_id, "agent")
-            if agent in {"", "null"}:
-                raise BriefError(f"{task_id} landed task has no recorded agent")
-            member = check_handoffs._strict_frontmatter(text, task_id).get("repo")
-            base_repo = repo
-            if member is not None:
-                located = member_base(member) if isinstance(member, str) and member else None
-                if located is None:
-                    raise BriefError(f"repo: names no member in MEMBERS.md: {member}")
-                base_repo = located[0]
-            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
-            try:
-                landed_bases[task_id] = require_commit(base_repo, require_full_sha(recorded_base))
-            except IsolationError as error:
-                raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
+        tasks, dependency_files, landed_bases = plan_validation_bases(
+            repo, project_dir, member_base, initial=True
+        )
         validate_task_briefs(
             repo, head.stdout.strip(), f"{project_dir}/tasks",
             dependency_files=dependency_files, landed_bases=landed_bases,

package/skills/gsd-path-research/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/gsd-path-research/templates/research-handoff.md

@@ -14,12 +14,23 @@ Intent: `.project/intent/INTENT.md`
 <!-- Include every standard dimension exactly once. A custom dimension may
      supplement these rows, never replace a standard row. -->
 - `domain` — dispatched → `.project/research/evidence-domain.md` — <why this dimension ran>
-- `stack` — skipped → none — <why this dimension was skipped>
+- `stack` — dispatched → `.project/research/evidence-stack.md` — <why this dimension ran>
 - `pitfalls` — skipped → none — <why this dimension was skipped>
 - `similar` — skipped → none — <why this dimension was skipped>
 
 ## Question assignments
 
 <!-- Copy every [RESEARCH] question from INTENT.md exactly once. Use `- none`
-     only when INTENT.md has no [RESEARCH] questions. -->
-- `[RESEARCH] <question copied from INTENT.md>` → `domain`
+     only when INTENT.md has no [RESEARCH] questions. The question is a
+     CommonMark code span: choose a fence length not used by a backtick run in
+     the question (a longer fence is usually easiest), with one space of
+     padding on each side. Each row may target one or more dispatched
+     dimensions, each in its own code span and separated by commas. Every
+     dispatched dimension must receive a question and answer all its assigned
+     questions in its evidence file. For example:
+     - `` [RESEARCH] Does `Widget` match `sample.json`? `` → `domain`, `stack`
+     A question that ends in a backtick also needs padding, as in:
+     - `` [RESEARCH] Does the label end with `Widget`?` `` → `domain`
+     After removing the fence and CommonMark padding, the text must equal the
+     INTENT question exactly. -->
+- `` [RESEARCH] <question copied from INTENT.md> `` → `domain`, `stack`

package/skills/gsd-path-roadmap/references/dispatch.md

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