@opengsd/gsd-path 1.0.0 → 1.2.0

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

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -11,6 +16,31 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional
 
 
+if __package__:  # imported as scripts.state_promote
+    from . import pipeline_state, state_checkpoint
+    from .pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+else:  # standalone script or sibling import
+    import pipeline_state
+    import state_checkpoint
+    from pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+
+
 def _render_roadmap(
     text: str,
     previous_milestone: str,
@@ -243,9 +273,9 @@ def _completed_promotion(
     if _head_with_exact_message(repo, subject, fields) != head:
         raise PipelineStateError("completed promotion has the wrong commit message")
 
-    active_text = pipeline_state._git_text_at(repo, base, ".project/STATE.md")
-    next_text = pipeline_state._git_text_at(repo, base, ".project/next/STATE.md")
-    roadmap_text = pipeline_state._git_text_at(repo, base, ".project/ROADMAP.md")
+    active_text = state_checkpoint._git_text_at(repo, base, ".project/STATE.md")
+    next_text = state_checkpoint._git_text_at(repo, base, ".project/next/STATE.md")
+    roadmap_text = state_checkpoint._git_text_at(repo, base, ".project/ROADMAP.md")
     if active_text is None or next_text is None or roadmap_text is None:
         raise PipelineStateError("promotion parent is missing required metadata")
     active_state = pipeline_state._state_from_text(active_text, "promotion parent STATE.md")
@@ -265,7 +295,7 @@ def _completed_promotion(
         )
 
     _promotion_tree_mapping(repo, base, head)
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     expected_roadmap = _render_roadmap(
         roadmap_text,
         active_state.milestone,
@@ -273,11 +303,11 @@ def _completed_promotion(
         branch,
         landing,
     )
-    current_roadmap = pipeline_state._git_text_at(repo, head, ".project/ROADMAP.md")
+    current_roadmap = state_checkpoint._git_text_at(repo, head, ".project/ROADMAP.md")
     if current_roadmap != expected_roadmap:
         raise PipelineStateError("completed promotion has invalid ROADMAP.md")
 
-    current_state = pipeline_state._git_text_at(repo, head, ".project/STATE.md")
+    current_state = state_checkpoint._git_text_at(repo, head, ".project/STATE.md")
     if current_state is None:
         raise PipelineStateError("completed promotion has no STATE.md")
     event = re.escape(_promotion_event(drift, branch, landing, base))
@@ -438,10 +468,10 @@ def _prepare_promotion(
         if source.exists() or source.is_symlink():
             if destination.exists() or destination.is_symlink():
                 raise PipelineStateError(f"promotion destination already exists: {destination}")
-            tracks[name] = pipeline_state._tree_digest(source)
+            tracks[name] = state_checkpoint._tree_digest(source)
     if not tracks:
         raise PipelineStateError("lookahead track has no promotable artifacts")
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     roadmap_path = project / "ROADMAP.md"
     roadmap_text = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
     target_state = _promotion_state(
@@ -464,10 +494,10 @@ def _prepare_promotion(
         "landing": landing,
         "base": base,
         "tracks": tracks,
-        "residual_sha256": pipeline_state._tree_digest(next_root, tuple(tracks)),
-        "next_state_sha256": pipeline_state._sha256(next_text),
-        "active_state_sha256": pipeline_state._sha256(active_text),
-        "roadmap_sha256": pipeline_state._sha256(roadmap_text),
+        "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),
+        "roadmap_sha256": state_checkpoint._sha256(roadmap_text),
         "target_state": target_state,
         "target_roadmap": target_roadmap,
         "drift": drift,
@@ -521,7 +551,7 @@ def _resume_track_moves(project: Path, journal: dict[str, object], path: Path) -
         if not source_exists and not destination_exists:
             raise PipelineStateError(f"promotion lost both source and destination: {name}")
         candidate = source if source_exists else destination
-        if pipeline_state._tree_digest(candidate) != expected_digest:
+        if state_checkpoint._tree_digest(candidate) != expected_digest:
             raise PipelineStateError(f"promotion track drifted: {name}")
         if source_exists:
             source.rename(destination)
@@ -542,7 +572,7 @@ def _resume_metadata(project: Path, journal: dict[str, object], path: Path) -> N
             raise PipelineStateError("promotion journal has invalid metadata")
         if current == desired:
             continue
-        if pipeline_state._sha256(current) != expected_original:
+        if state_checkpoint._sha256(current) != expected_original:
             raise PipelineStateError(f"promotion metadata drifted: {target}")
         pipeline_state._atomic_write(target, desired)
         journal["stage"] = f"updated:{target.name}"
@@ -560,9 +590,9 @@ def _resume_next_removal(
         if residual.exists() or residual.is_symlink():
             raise PipelineStateError("promotion has both next track and residual staging")
         next_text = pipeline_state._read_real_file(next_root / "STATE.md", "next/STATE.md")
-        if pipeline_state._sha256(next_text) != journal.get("next_state_sha256"):
+        if state_checkpoint._sha256(next_text) != journal.get("next_state_sha256"):
             raise PipelineStateError("lookahead STATE drifted during promotion")
-        if pipeline_state._tree_digest(next_root) != journal.get("residual_sha256"):
+        if state_checkpoint._tree_digest(next_root) != journal.get("residual_sha256"):
             raise PipelineStateError("lookahead residual drifted during promotion")
         next_root.rename(residual)
         journal["stage"] = "next-staged"
@@ -574,7 +604,7 @@ def _resume_next_removal(
         raise PipelineStateError("promotion lost next track and residual staging")
     if residual.is_symlink() or not residual.is_dir():
         raise PipelineStateError(f"promotion residual must be a real directory: {residual}")
-    if pipeline_state._tree_digest(residual) != journal.get("residual_sha256"):
+    if state_checkpoint._tree_digest(residual) != journal.get("residual_sha256"):
         raise PipelineStateError("staged lookahead residual drifted during promotion")
 
 
@@ -714,30 +744,3 @@ def promote_next(
         "commit": commit,
         "drift": journal["drift"],
     }
-
-
-# pipeline_state imports this module, so the parent is resolved after the
-# definitions above. Parent functions are looked up on the module at call time
-# so patches applied to pipeline_state stay visible here.
-if __package__:  # imported as scripts.state_promote
-    from . import pipeline_state
-    from .pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )
-else:  # standalone script or sibling import
-    import pipeline_state
-    from pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )

package/skills/gsd-path-inspect/scripts/workflow_run.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    from scripts import _common
+except ImportError:  # bundled copy inside a skill's scripts directory
+    import _common
+
+
+class StepFailed(RuntimeError):
+    pass
+
+INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
+                    ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
+
+
+def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
+                 task_id: str = None, round_size: int = None, inspection: Path = None,
+                 mapper_reviewed: bool = False) -> dict:
+    steps = []
+    outputs = {}
+    scripts = Path(__file__).resolve().parent
+    helpers = scripts
+
+    def step(script, *arguments, raw=False):
+        command = [sys.executable, "-B", str(helpers / script), *arguments]
+        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        receipt = {"script": script, "command": command, "exit_code": completed.returncode,
+                   "stdout": completed.stdout, "stderr": completed.stderr}
+        steps.append(receipt)
+        if completed.stderr:
+            sys.stderr.write(completed.stderr)
+        if completed.returncode:
+            raise StepFailed(script)
+        if raw:
+            return completed.stdout
+        try:
+            receipt["result"] = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise StepFailed(f"{script} did not return JSON") from error
+        return receipt["result"]
+
+    common = ["--repo", str(repo), "--project-dir", project_dir]
+    try:
+        if os.path.lexists(repo / ".gsd-path/runtime.json"):
+            resolved = subprocess.run(
+                [sys.executable, "-B", str(repo / ".gsd-path/status_runtime.py"),
+                 "--repo", str(repo), "--runtime-path"],
+                cwd=repo, capture_output=True, text=True)
+            if resolved.returncode:
+                sys.stderr.write(resolved.stderr)
+                raise StepFailed(resolved.stderr.strip())
+            helpers = Path(resolved.stdout.strip())
+        if action == "route":
+            step("pipeline_state.py", "route", *common)
+        elif action == "prepare-inspect":
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if project_dir != ".project" or state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("initial inspection requires the active inspect track")
+            specs = INSPECTION_SPECS
+            if any((repo / project_dir / "research" / spec[3]).exists() or
+                   (repo / project_dir / "research" / spec[3]).is_symlink() for spec in specs):
+                raise StepFailed("prior inspection evidence requires the re-inspection contract")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if branch != state["branch"]:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            inventory = step("check_docs_audit.py", "--repo", str(repo), "--emit-inventory", raw=True)
+            resources = scripts.parent
+            if not (resources / "references").is_dir():
+                resources = resources / "skills/gsd-path"
+            for _, role, template, _ in specs:
+                for path in (resources / "references" / f"{role}.md", resources / "templates" / f"{template}.md"):
+                    if not path.is_file():
+                        raise StepFailed(f"missing inspection resource: {path}")
+            staging = Path(tempfile.mkdtemp(prefix="gsd-path-inspect-"))
+            inventory_file = staging / "inventory.txt"
+            inventory_file.write_text(inventory, encoding="utf-8")
+            assignments = []
+            for task_name, role, template, filename in specs:
+                isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
+                                "--base", expected_head, "--name", task_name.replace("_", "-"))
+                role_path = resources / "references" / f"{role}.md"
+                template_path = resources / "templates" / f"{template}.md"
+                output = f"{project_dir}/research/{filename}"
+                brief_file = staging / f"{task_name}.md"
+                brief = (f"Logical task: {task_name}\nRead and follow role: {role_path}\n"
+                         f"Template: {template_path}\nRepository and command cwd: {isolated['worktree']}\n"
+                         f"Recorded baseline and Audited HEAD: {isolated['base']}\n"
+                         f"Write only: {Path(isolated['worktree']) / output}\n"
+                         "Use only this supplied sidecar for project commands; do not create worktrees.\n"
+                         "The parent owns gates, collection, retirement, and phase state.\n"
+                         "Exclude .git, node_modules, .project/archive, and installed GSD Path and path skill bundles.\n")
+                if task_name == "inspect_docs":
+                    brief += ("Alignment mode: false. No prior audit or changed set.\n"
+                              "Frozen inventory follows; use it exactly, without rediscovery:\n" + inventory)
+                brief_file.write_text(brief, encoding="utf-8")
+                assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
+                                    "template": str(template_path), "output": output,
+                                    "brief_file": str(brief_file)})
+            receipt_file = staging / "inspection.json"
+            outputs["inspection"] = {"repo": str(repo), "base": expected_head,
+                                     "inventory_file": str(inventory_file),
+                                     "inventory_sha256": hashlib.sha256(inventory_file.read_bytes()).hexdigest(),
+                                     "assignments": assignments, "receipt_file": str(receipt_file)}
+            _common.atomic_write(receipt_file, json.dumps(outputs["inspection"], sort_keys=True) + "\n")
+        elif action == "finish-inspect":
+            if not mapper_reviewed or inspection is None or project_dir != ".project":
+                raise StepFailed("finish-inspect requires the prepared active track and mapper review")
+            prepared = json.loads(inspection.read_text(encoding="utf-8"))
+            if prepared["repo"] != str(repo) or prepared["base"] != expected_head:
+                raise StepFailed("inspection receipt does not match repository and expected HEAD")
+            assignments = {a["task_name"]: a for a in prepared["assignments"]}
+            if len(prepared["assignments"]) != len(INSPECTION_SPECS) or set(assignments) != {s[0] for s in INSPECTION_SPECS}:
+                raise StepFailed("inspection receipt must name both original assignments")
+            for task_name, _, _, filename in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                if assignment["base"] != expected_head or assignment["output"] != f".project/research/{filename}":
+                    raise StepFailed("inspection assignment changed its baseline or output")
+            inventory_file = Path(prepared["inventory_file"])
+            if hashlib.sha256(inventory_file.read_bytes()).hexdigest() != prepared["inventory_sha256"]:
+                raise StepFailed("frozen inspection inventory changed")
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("inspection completion requires inspect/active")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if state["branch"] != branch:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            docs = assignments["inspect_docs"]
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--audit", docs["output"],
+                 "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text().splitlines():
+                raise StepFailed("audit does not name the supplied inspection baseline")
+            for task_name, _, _, _ in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                step("isolation.py", "collect-artifact", "--repo", str(repo),
+                     "--source", assignment["worktree"], "--base", expected_head,
+                     "--branch", assignment["branch"], "--source-path", assignment["output"],
+                     "--destination-path", assignment["output"])
+                step("isolation.py", "retire", "--repo", str(repo), "--worktree", assignment["worktree"],
+                     "--branch", assignment["branch"])
+            expected = [part for key, value in state.items()
+                        for part in (f"--expect-{key}", "null" if value is None else str(value))]
+            step("pipeline_state.py", "transition", *common, *expected,
+                 "--set-phase", "inspect", "--set-status", "done", "--event", "inspection artifacts passed")
+        elif action == "lint-round":
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task":
+            task = step("isolation.py", "isolate-task", "--repo", str(repo),
+                        "--base", expected_head, "--task-id", task_id,
+                        "--round-size", str(round_size))
+            if task["mode"] == "serial":
+                step("isolation.py", "isolate-verify", "--repo", str(repo),
+                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+        elif action == "build-evidence":
+            proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            # The landing proof has one canonical home; lean final-review reuse allows only this path.
+            evidence = repo / project_dir / "build" / "evidence.json"
+            _common.atomic_write(evidence, json.dumps(proof, indent=2, sort_keys=True) + "\n")
+            steps.append({"script": "workflow_run.py", "evidence": str(evidence)})
+        elif action == "prepare-final":
+            if project_dir != ".project":
+                raise StepFailed("final review requires the active milestone")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
+        else:
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("check_handoffs.py", "plan", *common)
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
+            charter = repo / ".project/CHARTER.md"
+            if charter.exists():
+                panel += ["--charter", str(charter)]
+            step("review_panel.py", *panel)
+            if action == "approve-plan":
+                step("pipeline_state.py", "approve", *common, "--kind", "plan",
+                     "--expected-head", expected_head)
+    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
+        return {"status": "blocked", "reason": str(error), "steps": steps,
+                "next": "$gsd-path-forensics"}
+    return {"status": "complete", "steps": steps, **outputs}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"))
+    parser.add_argument("--repo", type=Path, required=True)
+    parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
+    parser.add_argument("--expected-head")
+    parser.add_argument("--task-id")
+    parser.add_argument("--round-size", type=int)
+    parser.add_argument("--inspection", type=Path)
+    parser.add_argument("--mapper-reviewed", action="store_true")
+    arguments = parser.parse_args(argv)
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"} and not arguments.expected_head:
+        parser.error(f"{arguments.action} requires --expected-head")
+    if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
+        parser.error("prepare-task requires --task-id and --round-size")
+    result = run_workflow(arguments.repo.resolve(), arguments.action,
+                          arguments.project_dir, arguments.expected_head,
+                          arguments.task_id, arguments.round_size, arguments.inspection,
+                          arguments.mapper_reviewed)
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result["status"] == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Placement shared by task isolation, verification, and integration."""
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+try:
+    import _common
+except ImportError:
+    from scripts import _common
+
+
+def _git(primary: Path, *args: str) -> str:
+    result = _common.run_git(primary, *args)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "cannot inspect worktree placement")
+    return result.stdout.rstrip("\n")
+
+
+def _identity(path: Path) -> str:
+    return hashlib.sha256(os.fsencode(path)).hexdigest()
+
+
+def _workspace(primary: Path, pin: bool) -> Path:
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    identity = _identity(primary)
+    receipt = common / "gsd-path" / "workspaces" / f"{identity}.json"
+    try:
+        data = json.loads(receipt.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        pass
+    else:
+        if (not isinstance(data, dict) or data.get("primary") != str(primary)
+                or not isinstance(data.get("root"), str)
+                or not Path(data["root"]).is_absolute()):
+            raise ValueError(f"invalid worktree placement receipt: {receipt}")
+        return Path(data["root"])
+
+    root = Path(os.environ.get("GSD_PATH_WORKTREE_ROOT") or Path.home() / ".gsd-path" / "projects").expanduser()
+    if not root.is_absolute():
+        raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
+    root = root.resolve()
+    parent = root
+    while not parent.exists():
+        parent = parent.parent
+    ancestor = _common.run_git(parent, "rev-parse", "--git-common-dir")
+    same_repository = (
+        ancestor.returncode == 0
+        and (parent / ancestor.stdout.strip()).resolve() == common
+    )
+    if root.is_relative_to(primary) or same_repository:
+        raise ValueError(f"managed worktree root must be outside this repository's worktrees: {root}")
+    workspace = root / _identity(common) / identity
+    if pin:
+        receipt.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(dir=receipt.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"primary": str(primary), "root": str(workspace)}, handle)
+            try:
+                os.link(temporary, receipt)
+            except FileExistsError:
+                return _workspace(primary, False)
+        finally:
+            os.unlink(temporary)
+    return workspace
+
+
+def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    primary = primary.resolve()
+    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+        raise ValueError("invalid managed worktree kind or name")
+    legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
+              if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
+    branch = f"refs/heads/gsd-path-{kind}/{name}"
+    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    for record in records:
+        fields = record.split("\0")
+        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+            return legacy
+    # Keep collision checks and missing-directory recovery at the old location.
+    if os.path.lexists(legacy):
+        return legacy
+    return _workspace(primary, pin) / kind / name

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

@@ -3,6 +3,8 @@ name: gsd-path-loop
 description: Use only when the user explicitly invokes $gsd-path-loop. Runs one bounded loop pass from a LOOP.md spec — gate checks, independent verification, one fix worker, telemetry. Autonomy lives in the external scheduler that invokes this skill; the skill never schedules itself.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Loop
 
 One invocation = one bounded pass. The bundled deterministic helper

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

@@ -0,0 +1,25 @@
+# Project runtime selection
+
+Before running a project runtime helper, check for
+`<absolute-project>/.gsd-path/runtime.json`. When present, run the stable launcher:
+
+```sh
+python3 -B <absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project> --runtime-path
+```
+
+Use `python` only when it is the compatible Python 3.9+ interpreter. A failure
+stops helper execution: follow the exact-version restore action in the error.
+Do not install, upgrade, or fall back to the current plugin's runtime implicitly.
+
+The returned directory is the verified Project runtime. Resolve helper names
+present in its `manifest.json` from that directory, including status, state,
+isolation, integration, archive, recovery, build-state, final-verification, and guard helpers.
+The workflow runner resolves its subprocess helpers from this same directory;
+helper imports stay within the selected runtime. This rule overrides
+references to bundled copies of those helpers. Other skill helpers, templates,
+and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
+invocations so execution does not create bytecode in the runtime store.
+
+With no declaration, retain the legacy helper lookup. An existing
+`.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
+operation before adopting external storage; review the resulting Git diff.

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

@@ -9,6 +9,11 @@ consuming module keep working.
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import os
 import re

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

@@ -7,6 +7,9 @@ import json
 import os
 import shutil
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Deterministic gates for a GSD Path LOOP.md loop spec.
 
 The loop skill (a model) reads the prose sections of a LOOP.md; this helper
@@ -23,6 +24,7 @@ import os
 import re
 import subprocess
 import sys
+sys.dont_write_bytecode = True
 import time
 import uuid
 from contextlib import contextmanager