@opengsd/gsd-path 1.6.1 → 1.7.0

package/skills/gsd-path-docs-audit/scripts/loop_run.py

@@ -530,10 +530,15 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
         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()
+            # Windows communicate() reads in threads that hold each pipe's lock,
+            # so close() would block until an orphaned grandchild (bash forks
+            # commands it runs from a script file) exits; leave them to the
+            # daemon reader threads there.
+            if os.name != "nt":
+                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")

package/skills/gsd-path-docs-audit/scripts/members.py

@@ -34,9 +34,17 @@ MEMBERS_FILE = "MEMBERS.md"
 MARKER_SCHEMA = "gsd-path/member/v1"
 MARKER_KEYS = {"schema", "coordinator", "project", "name"}
 NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
-FIELDS = ("Checkout", "Remote", "Integration")
+FIELDS = ("Checkout", "Remote", "Integration", "Prepare")
+# The first three are required; Prepare (isolate provisioning, #463) and
+# Default branch are optional.
+REQUIRED_FIELDS = ("Checkout", "Remote", "Integration")
 # Optional: `add` records it one time; a row without it means main.
 DEFAULT_BRANCH_FIELD = "Default branch"
+# Optional: a shell command run inside each fresh member isolate before any
+# Verify (#463). It provisions what a bare worktree lacks — submodules from
+# the primary checkout's object store, gitignored build inputs — and must
+# copy, never link, outside the isolate (#462).
+PREPARE_FIELD = "Prepare"
 INTEGRATIONS = ("default", "direct", "pull-request")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([^/\s]+)/([^/\s]+)"
@@ -206,10 +214,15 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
         return []
     if path.is_symlink() or not path.is_file():
         raise MembersError("MEMBERS.md must be a regular file")
+    return parse_members(path.read_text(encoding="utf-8"))
+
+
+def parse_members(text: str) -> list[dict[str, str]]:
+    """Parse MEMBERS.md text."""
     members: list[dict[str, str]] = []
     current: Optional[dict[str, str]] = None
     preamble: list[str] = []
-    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+    for number, line in enumerate(text.splitlines(), 1):
         if line.startswith("## "):
             name = line[3:].strip()
             if not NAME_RE.fullmatch(name):
@@ -241,7 +254,7 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
     if len(set(names)) != len(names):
         raise MembersError("MEMBERS.md repeats a member name")
     for member in members:
-        missing = [field for field in FIELDS if not member.get(field.lower())]
+        missing = [field for field in REQUIRED_FIELDS if not member.get(field.lower())]
         if missing:
             raise MembersError(f"MEMBERS.md member {member['name']} lacks {', '.join(missing)}")
         if member["integration"] not in INTEGRATIONS:
@@ -510,6 +523,7 @@ def render(members: Sequence[dict[str, str]]) -> str:
         f"Checkout: {member['checkout']}\n"
         f"Remote: {member['remote']}\n"
         f"Integration: {member['integration']}\n"
+        + (f"{PREPARE_FIELD}: {member['prepare']}\n" if "prepare" in member else "")
         # A row that never had the field keeps none, so old rows are not rewritten.
         + (f"{DEFAULT_BRANCH_FIELD}: {member['default_branch']}\n" if "default_branch" in member else "")
         for member in members

package/skills/gsd-path-docs-audit/scripts/pipeline_state.py

@@ -1407,6 +1407,12 @@ def _route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
             mode="milestone" if status == "done" else "normal",
             reason=f"state is {phase}/{status}",
         )
+    if phase == "plan" and status == "blocked":
+        return _route_result(
+            state,
+            "block",
+            reason="plan is blocked; resolve the correction or user decision named by the plan gate before resuming",
+        )
     if phase == "plan" and status != "done":
         return _route_result(state, "run-phase", phase="plan", reason=f"state is {phase}/{status}")
     if phase == "plan":
@@ -2373,9 +2379,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.project_dir,
             )
         elif args.command == "approve" and (args.defer_checkpoint or args.patch):
-            if args.expected_head is not None:
+            if args.defer_checkpoint and args.expected_head is not None:
                 raise PipelineStateError(
-                    "--expected-head is not accepted with --defer-checkpoint or --patch"
+                    "--expected-head is not accepted with --defer-checkpoint"
                 )
             result = state_checkpoint.defer_approval(
                 args.repo,
@@ -2384,6 +2390,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.milestone,
                 args.patch,
             )
+            if args.expected_head is not None:
+                result["expected_head_accepted"] = args.expected_head
         elif args.command == "approve":
             if args.expected_head is None:
                 raise PipelineStateError(

package/skills/gsd-path-docs-audit/scripts/state_checkpoint.py

@@ -458,6 +458,21 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
         return
+    if project_dir == ".project":
+        # Unsupported .project entries must surface at approval, before build,
+        # where removing them is cheapest (#466). Like the checkpoint, judge
+        # each git-visible entry by whether it still exists in the worktree.
+        project = repo / ".project"
+        unsupported = sorted(
+            name
+            for name in pipeline_state._common.git_visible_entries(project) - PROJECT_ENTRIES
+            if (project / name).exists() or (project / name).is_symlink()
+        )
+        if unsupported:
+            raise PipelineStateError(
+                "unsupported .project artifacts: " + ", ".join(unsupported)
+                + "; remove or relocate them before approving the plan"
+            )
     if __package__:
         from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     else:

package/skills/gsd-path-docs-audit/scripts/worktree_paths.py

@@ -7,11 +7,13 @@ import sys
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 
+import contextlib
 import hashlib
 import json
 import os
 import tempfile
 from pathlib import Path
+from typing import Optional
 
 if __package__:
     from . import _common
@@ -22,7 +24,39 @@ else:
         from scripts import _common
 
 
+# Run-scoped cache for read-only consumers (#469): recovery resolves a
+# placement per task, and each resolution lists the whole worktree registry
+# and re-reads the placement receipt. Within one read-only run none of that
+# can change, so the listing and the derived workspace answer once. Flows
+# that create, move, or retire worktrees never enter this scope.
+_PLACEMENT_CACHE: Optional[dict] = None
+
+
+@contextlib.contextmanager
+def readonly_placement_cache():
+    global _PLACEMENT_CACHE
+    if _PLACEMENT_CACHE is not None:  # already inside a read-only run
+        yield
+        return
+    _PLACEMENT_CACHE = {"porcelain": {}, "workspace": {}}
+    try:
+        yield
+    finally:
+        _PLACEMENT_CACHE = None
+
+
 def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    if _PLACEMENT_CACHE is not None:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["porcelain"]:
+            return _PLACEMENT_CACHE["porcelain"][key]  # type: ignore[index]
+        output = _worktree_list_porcelain_uncached(primary)
+        _PLACEMENT_CACHE["porcelain"][key] = output
+        return output
+    return _worktree_list_porcelain_uncached(primary)
+
+
+def _worktree_list_porcelain_uncached(primary: Path) -> tuple[str, bool]:
     try:
         if __package__:
             from . import pipeline_git as pg
@@ -58,6 +92,17 @@ def _identity(path: Path) -> str:
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
+    if _PLACEMENT_CACHE is not None and not pin:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["workspace"]:
+            return _PLACEMENT_CACHE["workspace"][key]  # type: ignore[index]
+        workspace = _workspace_uncached(primary, False)
+        _PLACEMENT_CACHE["workspace"][key] = workspace
+        return workspace
+    return _workspace_uncached(primary, pin)
+
+
+def _workspace_uncached(primary: Path, pin: bool) -> Path:
     common = Path(_git(primary, "rev-parse", "--git-common-dir"))
     common = (primary / common).resolve()
     identity = _identity(primary)

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

@@ -20,6 +20,42 @@ 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.
 
+When the runtime enforcing an active task cannot finish it, one narrowly
+authorized recovery exists:
+`python3 -B <absolute isolation.py> runtime-hotfix --repo <absolute primary>
+--task-id <id> --runtime <64-hex runtime digest printed by runtime_store.py publish>
+--authorized-by <the owner ruling>` validates the replacement runtime,
+re-runs that task's Verify in a fresh sidecar at the recorded base under the
+replacement pin, and records the receipt twice: a Log line in the task file
+naming the task, base, and both runtime digests, and an identical blob behind
+the local ref `refs/gsd-path/runtime-hotfix/<task>-<base>`. Only a Log line
+whose exact twin that ref holds later admits `.gsd-path/runtime.json` into that
+task's landing, and only when the pin names exactly the receipt's runtime; any
+other task, base, a Log line alone, or a bare mention authorizes nothing, and a
+failing re-run refuses the hotfix. Limits: the command serves only a serial
+task working in the primary and refuses parallel or member tasks; the ref is
+local repository state, so a clone without it cannot land the pin and the
+proof fails closed. The guard applies two rules to agent shell commands. It
+denies any command where `runtime-hotfix` directly follows `isolation.py`, stdin
+`-`, or an `isolation` module operand (`-m isolation`, `-Bm isolation`,
+`-misolation`). It also denies every Git command with a word, including global
+`-c` options and inline variable assignments, that contains `refs/gsd-path/` or
+`runtime-hotfix`. This deliberately blocks read-only uses such as
+`git log refs/gsd-path/<ref>` or `git log --grep runtime-hotfix`, and commit
+messages or branch names that contain `runtime-hotfix`. Limits: it cannot see a copied or renamed
+`isolation.py`, a refspec stored in a Git config file, a ref write made from
+inside another program, a direct edit of files under `.git/`, or shell
+expansion that splits both protected words, such as
+`refs/gs{d,}-path/task-authorizations/<task>`.
+
+Publishing a runtime to the shared store is project-free:
+`python3 -B <absolute runtime_store.py> publish --source <absolute package root>`
+verifies and publishes the content-addressed runtime, printing its version,
+digest, and store path as JSON; `--provenance` records a note in that output
+only. Publication alone neither authorizes execution nor changes a project's
+trusted runtime — a project runs the bytes only when its own pin names that
+digest.
+
 The selected runtime is authoritative for each helper in its `manifest.json`;
 this includes `review_findings.py` and `task_context.py`. A selected runtime
 that was published before a helper became a runtime file does not list that

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

@@ -14,6 +14,7 @@ import sys
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 
+import atexit
 import contextlib
 import errno
 import json
@@ -23,9 +24,10 @@ import shlex
 import shutil
 import signal
 import subprocess
+import tempfile
 import time
 from pathlib import Path
-from typing import BinaryIO, Iterable, Iterator, List, Optional, Sequence, Tuple
+from typing import BinaryIO, Iterable, Iterator, List, Optional, Sequence, Set, Tuple
 
 
 # Chosen by what imports, not os.name, so tests can emulate Windows on POSIX.
@@ -65,6 +67,23 @@ VERIFY_LEDGER_PATH = ".project/build/verify-ledger.jsonl"
 VERIFY_RESULTS = ("pass", "fail")
 VERIFY_LEDGER_SCHEMA = "gsd-path/verify-ledger/v2"
 VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
+# The owner citation a withdrawn task tombstone must carry in its Log (#483).
+# One definition shared by every gate that reads the representation.
+WITHDRAWN_CITATION = re.compile(
+    r"^- Withdrawn — (?P<date>\d{4}-\d{2}-\d{2}): (?P<ruling>.+)$", re.MULTILINE)
+
+
+def withdrawn_citations(task_text: str) -> list[str]:
+    """The owner citations in a withdrawn task's Log, as `date: ruling`.
+
+    The Log is the append-only record of rulings; a Withdrawn line in any
+    other section is not the citation the gates accept (#483).
+    """
+    body = section_body(task_text, "Log")
+    if body is None:
+        return []
+    return [f"{m.group('date')}: {m.group('ruling')}"
+            for m in WITHDRAWN_CITATION.finditer(body)]
 
 REVIEW_BULLET_HEADING_PATTERN = re.compile(r"^#{2,3} ")
 REVIEW_BULLET_FIELD_LABEL_PATTERN = re.compile(r"^- \*\*[^*]+\*\*:")
@@ -197,6 +216,19 @@ def section_body(text: str, heading: str) -> Optional[str]:
     return match.group("body") if match else None
 
 
+def contract_shapes(body: str) -> Set[str]:
+    """The whitespace-normalized `- ` entries of an Interface contract body.
+
+    HTML comments are dropped and continuation lines join their entry. A
+    body that says only `None` has no shapes.
+    """
+    cleaned = re.sub(r"(?s)<!--.*?-->", "", body).strip()
+    if " ".join(cleaned.split()) in {"", "None", "- None"}:
+        return set()
+    entries = re.split(r"(?m)^-[ \t]+", cleaned)
+    return {shape for shape in (" ".join(entry.split()) for entry in entries) if shape}
+
+
 def overlapping_paths(left: Sequence[str], right: Sequence[str]) -> List[str]:
     """Return the sorted paths that two task `files` lists both cover.
 
@@ -875,8 +907,50 @@ def find_bash() -> str:
     )
 
 
+def _remove_quietly(path: str) -> None:
+    try:
+        os.remove(path)
+    except OSError:
+        pass
+
+
+def _command_script_dir() -> str:
+    """A temp directory for command scripts that cannot dirty the running tree.
+
+    TMPDIR/TEMP/TMP may point into the tree being verified, and a script file
+    there shows up in git status and blocks landings (#448), so fall back to a
+    system directory when the environment temp sits inside the current tree.
+    """
+    candidate = os.path.realpath(tempfile.gettempdir())
+    tree = os.path.realpath(os.getcwd())
+    if candidate != tree and not candidate.startswith(tree + os.sep):
+        return candidate
+    for fallback in (
+        os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "Temp"),
+        "/var/tmp",
+        "/tmp",
+    ):
+        resolved = os.path.realpath(fallback)
+        if os.path.isdir(resolved) and resolved != tree and not resolved.startswith(tree + os.sep):
+            return resolved
+    raise OSError("no temp directory outside the current worktree for a command script")
+
+
 def bash_argv(command: str) -> List[str]:
-    return [find_bash(), "-c", command]
+    if os.name != "nt":
+        return [find_bash(), "-c", command]
+    # Git for Windows' bash (MSYS2) cuts an argument that carries a double
+    # quote near 8 KB before bash sees it, so a long Verify dies mid-script
+    # or silently passes when the cut lands in comments (#448). Run the exact
+    # bytes from a temp file outside every worktree instead.
+    bash = find_bash()
+    descriptor, path = tempfile.mkstemp(
+        prefix="gsd-path-command-", suffix=".sh", dir=_command_script_dir()
+    )
+    with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(command)
+    atexit.register(_remove_quietly, path)
+    return [bash, path]
 
 
 # cmd.exe re-parses the arguments of a .cmd or .bat target, so these would

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

@@ -530,10 +530,15 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
         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()
+            # Windows communicate() reads in threads that hold each pipe's lock,
+            # so close() would block until an orphaned grandchild (bash forks
+            # commands it runs from a script file) exits; leave them to the
+            # daemon reader threads there.
+            if os.name != "nt":
+                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")

package/skills/gsd-path-forensics/scripts/pipeline_diagnose.py

@@ -24,16 +24,20 @@ from typing import Callable, Optional, Sequence
 def _load_diagnose_modules():
     if __package__:
         from . import archive_milestone
+        from . import build_state
         from . import detect_project
         from . import discussion_records
+        from . import discussion_validate
         from . import integration
         from . import isolation
         from . import pipeline_git
         from . import pipeline_state
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -42,16 +46,20 @@ def _load_diagnose_modules():
     else:
         try:
             import archive_milestone
+            import build_state
             import detect_project
             import discussion_records
+            import discussion_validate
             import integration
             import isolation
             import pipeline_git
             import pipeline_state
             return (
                 archive_milestone,
+                build_state,
                 detect_project,
                 discussion_records,
+                discussion_validate,
                 integration,
                 isolation,
                 pipeline_git,
@@ -60,8 +68,10 @@ def _load_diagnose_modules():
         except ModuleNotFoundError as error:
             if error.name not in {
                 "archive_milestone",
+                "build_state",
                 "detect_project",
                 "discussion_records",
+                "discussion_validate",
                 "integration",
                 "isolation",
                 "pipeline_git",
@@ -71,8 +81,10 @@ def _load_diagnose_modules():
     try:
         from scripts import (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -80,8 +92,10 @@ def _load_diagnose_modules():
         )
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -91,8 +105,10 @@ def _load_diagnose_modules():
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
+            "scripts.build_state",
             "scripts.detect_project",
             "scripts.discussion_records",
+            "scripts.discussion_validate",
             "scripts.integration",
             "scripts.isolation",
             "scripts.pipeline_git",
@@ -109,16 +125,20 @@ def _load_diagnose_modules():
         shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared))
         import archive_milestone
+        import build_state
         import detect_project
         import discussion_records
+        import discussion_validate
         import integration
         import isolation
         import pipeline_git
         import pipeline_state
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -128,8 +148,10 @@ def _load_diagnose_modules():
 
 (
     archive_milestone,
+    build_state,
     detect_project,
     discussion_records,
+    discussion_validate,
     integration,
     isolation,
     pipeline_git,
@@ -137,6 +159,9 @@ def _load_diagnose_modules():
 ) = _load_diagnose_modules()
 DetectError = detect_project.DetectError
 classify = detect_project.classify
+BuildStateError = build_state.BuildStateError
+build_ready = build_state.ready
+review_cycle_counts = discussion_validate.review_cycle_counts
 IsolationError = isolation.IsolationError
 _registered_worktrees = isolation._registered_worktrees
 _worktree_report = isolation._worktree_report
@@ -231,7 +256,15 @@ def _state_template() -> Path:
 
 
 def _command(module: object, *arguments: object) -> str:
-    script = Path(str(getattr(module, "__file__"))).resolve()
+    return _script_command(Path(str(getattr(module, "__file__"))), *arguments)
+
+
+def _dispatch_command(*arguments: object) -> str:
+    return _script_command(Path(str(build_state.__file__)).with_name("dispatch_driver.py"), *arguments)
+
+
+def _script_command(path: Path, *arguments: object) -> str:
+    script = path.resolve()
     def text(value: object) -> str:
         # Agents paste this into Git Bash on Windows, where unquoted
         # backslashes are escapes; forward slashes need no quoting.
@@ -354,6 +387,74 @@ def _leftover_worktrees(repo: Path) -> list[dict[str, object]]:
     return leftovers
 
 
+def _build_completion_findings(repo: Path) -> list[dict[str, str]]:
+    """Mirror dispatch complete's build gates so a completion refusal is diagnosable.
+
+    Runs the same checks `dispatch_driver.py complete` runs, under the same
+    precondition (every wave's tasks done, no blocked review holding them), and
+    names the review set or typed build state that complete would refuse on.
+    """
+    try:
+        ready_result = build_ready(str(repo), allow_done=True)
+    except BuildStateError as error:
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                f"{error.code}: {error}",
+                _dispatch_command("complete", "--repo", repo)
+                + "  # reports the same typed blocker; follow its recovery (reconcile "
+                "failed or blocked tasks, resolve a dependency deadlock before new dispatch)",
+            )
+        ]
+    blocked = ready_result.get("blocked_review")
+    if blocked:
+        wave, cycle = blocked["wave"], blocked["cycle"]
+        waiting = ", ".join(
+            str(item) for item in blocked.get("waiting_waves") or []
+        )
+        if any((repo / ".project" / "tasks").glob(f"*-fix-wave-{wave}-cycle-{cycle}.md")):
+            retry = (
+                _dispatch_command("review", "--repo", repo, "--wave", wave, "--cycle", cycle + 1)
+                + "  # add the owner's --child-command; the source wave's next review cycle "
+                "in full at the current HEAD; "
+                "pass --repair-evidence when review_findings.py repair-evidence accepts a landed repair"
+            )
+        else:
+            retry = (
+                _dispatch_command("fix-tasks", "--repo", repo, "--wave", wave, "--cycle", cycle)
+                + "  # then land the repair wave; the source wave's next review cycle judges it"
+            )
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                f"wave {wave} review cycle {cycle} is blocked "
+                + (f"and holds waiting waves {waiting}" if waiting else "and holds completion"),
+                retry,
+            )
+        ]
+    if ready_result.get("current_wave") is not None:
+        return []
+    try:
+        review_cycle_counts(repo / ".project")
+    except archive_milestone.ArchiveError as error:
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                str(error),
+                "compare each PLAN.md wave with the .project/review/wave-N.cycleC.md "
+                "files, then run the missing cycle's review: "
+                + _dispatch_command("review", "--repo", repo)
+                + " with that wave's --wave and --cycle and the owner's --child-command; "
+                "a repair wave is judged by "
+                "its source wave's next cycle",
+            )
+        ]
+    return []
+
+
 def diagnose(repo: Path) -> dict[str, object]:
     resolved = repo.resolve()
     if not resolved.is_dir():
@@ -567,6 +668,8 @@ def diagnose(repo: Path) -> dict[str, object]:
                                 "$gsd-path-ship",
                             )
                         )
+        elif state.get("phase") == "build" and state.get("status") in {"active", "done"}:
+            findings.extend(_build_completion_findings(resolved))
 
     undo_transaction = by_name["undo-transaction"]
     route_action = (

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

@@ -7,11 +7,13 @@ import sys
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 
+import contextlib
 import hashlib
 import json
 import os
 import tempfile
 from pathlib import Path
+from typing import Optional
 
 if __package__:
     from . import _common
@@ -22,7 +24,39 @@ else:
         from scripts import _common
 
 
+# Run-scoped cache for read-only consumers (#469): recovery resolves a
+# placement per task, and each resolution lists the whole worktree registry
+# and re-reads the placement receipt. Within one read-only run none of that
+# can change, so the listing and the derived workspace answer once. Flows
+# that create, move, or retire worktrees never enter this scope.
+_PLACEMENT_CACHE: Optional[dict] = None
+
+
+@contextlib.contextmanager
+def readonly_placement_cache():
+    global _PLACEMENT_CACHE
+    if _PLACEMENT_CACHE is not None:  # already inside a read-only run
+        yield
+        return
+    _PLACEMENT_CACHE = {"porcelain": {}, "workspace": {}}
+    try:
+        yield
+    finally:
+        _PLACEMENT_CACHE = None
+
+
 def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    if _PLACEMENT_CACHE is not None:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["porcelain"]:
+            return _PLACEMENT_CACHE["porcelain"][key]  # type: ignore[index]
+        output = _worktree_list_porcelain_uncached(primary)
+        _PLACEMENT_CACHE["porcelain"][key] = output
+        return output
+    return _worktree_list_porcelain_uncached(primary)
+
+
+def _worktree_list_porcelain_uncached(primary: Path) -> tuple[str, bool]:
     try:
         if __package__:
             from . import pipeline_git as pg
@@ -58,6 +92,17 @@ def _identity(path: Path) -> str:
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
+    if _PLACEMENT_CACHE is not None and not pin:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["workspace"]:
+            return _PLACEMENT_CACHE["workspace"][key]  # type: ignore[index]
+        workspace = _workspace_uncached(primary, False)
+        _PLACEMENT_CACHE["workspace"][key] = workspace
+        return workspace
+    return _workspace_uncached(primary, pin)
+
+
+def _workspace_uncached(primary: Path, pin: bool) -> Path:
     common = Path(_git(primary, "rev-parse", "--git-common-dir"))
     common = (primary / common).resolve()
     identity = _identity(primary)