@opengsd/gsd-path 1.6.1 → 1.7.0

package/skills/gsd-path-roadmap/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-roadmap/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-roadmap/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-roadmap/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-roadmap/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-ship/SKILL.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
@@ -89,7 +90,14 @@ so the position is unchanged. Then:
    head and holds the exact output; there is no reusable ledger entry.
    Single-repo re-entry at the same command and commit reuses the execution,
    including a failed one, and finishes interrupted collection without running
-   the command again.
+   the command again. The one exception is an owner-diagnosed host failure (for
+   example a host toolchain version the project does not pin): re-run
+   `workflow_run.py prepare-final` with `--rerun` to retire the recorded
+   execution, run the command again, and append a second ledger entry marked
+   `rerun` — the failed entry stays as history. Product failures never take
+   `--rerun`; they go through the patch plan. The sidecar inherits the
+   orchestrator environment, PATH included, by design: the Verify must run the
+   project's own toolchain, so a host/PATH mismatch is a host failure.
    Missing legacy output requires evidence reconciliation, not a blind rerun.
    Any non-zero result stops this step; preserve its stderr and diagnose through
    the bundled forensics contract. Do not launch reviewers while project Verify
@@ -145,7 +153,8 @@ so the position is unchanged. Then:
    verdict `met` with a non-`none` Check or Reference, and every criterion
    listed in PLAN.md's Surface contract requires a matching `Surface` field
    and a non-`none` Check. A non-zero exit is
-   `ship/blocked`; never rerun project Verify to repair the evidence.
+   `ship/blocked`; never rerun project Verify to repair the evidence (a
+   host-caused command failure uses the `prepare-final --rerun` route above).
 6. Redispatch one complete corrected brief for a missing or invalid reviewer
    artifact under the same logical task name, following the runtime dispatch
    contract. Before dispatch, record the invalid destination's exact SHA-256.
@@ -274,7 +283,16 @@ The persisted `STATE.archive` field is the transaction identity.
    `awaiting-merge`, report the member PR
    link, stop, and rerun the same command after the user merges it; never
    merge a member PR yourself. When it returns `integrated`, keep its `body`
-   for the ship commit below.
+   for the ship commit below. When it refuses with
+   `member reviewed HEAD reached <default> outside Path`, the member's work
+   was already published past its reviewed HEAD by an earlier user-approved
+   step: present the member, its reviewed HEAD, and the live default-branch
+   tip, and ask the user whether to adopt that landing. Only on an explicit
+   user approval rerun the same command with
+   `--adopt-landed-member <member>=<live tip SHA>`; the helper then publishes
+   the bound branch and an `adopted-landing` milestone tag at that tip and
+   makes no merge. A mismatched or stale SHA is refused, and a later rerun
+   validates the adoption without the flag.
 5. Only after preflight passes, record shipment through the journaled helper;
    for a program it atomically replaces both ROADMAP.md and STATE.md, setting
    the current entry to `Status: shipped` with the exact `Archive:` pointer:
@@ -329,7 +347,13 @@ The persisted `STATE.archive` field is the transaction identity.
      `build/rebase-adoption.json`) may advance the ref from the adopted head
      to its immediate, canonical `.project/`-only ship child under an exact-SHA
      lease after the helper proves the clean ship state, receipt, and archived
-     tasks. Every other value blocks. If origin/main advances
+     tasks, and a strict ancestor of the ship commit — a build task may have
+     legitimately pushed the bound branch as a deploy pin (#464) — is adopted
+     only after the user approves, by rerunning with
+     `integrate --adopt-published-bound <live 40-hex SHA>`; the helper requires
+     the SHA to equal the live tip exactly and fast-forwards under the same
+     exact lease, and direct integration only. Every other value blocks. If
+     origin/main advances
      after the local merge but rejects the push, a retry may discard and
      rebuild only the unpublished canonical merge and tag under the helper's
      existing recovery checks.
@@ -416,10 +440,15 @@ Run this recovery setup from a separate checkout, outside the closed primary
 worktree's guard.
 
 1. Create separate disposable trust and validation checkouts from the same
-   published origin and `STATE.branch`. This separation is required because an
-   explicit runtime upgrade changes the trust checkout's declaration and launcher,
-   while archive validation requires a clean checkout. Never use the primary
-   worktree for either role.
+   published origin and its default branch (checking out `STATE.branch` when
+   it still exists; a rebase-merged pull request may have deleted it). This
+   separation is required because an explicit runtime upgrade changes the
+   trust checkout's declaration and launcher, while archive validation
+   requires a clean checkout. Never use the primary worktree for either role.
+   A rebase-merged milestone additionally needs the original ship commits to
+   resolve — use a checkout that fetched and retained them (the primary
+   always does; a clone that never fetched the bound branch does not), and a
+   checkout whose originals were collected cannot carry a full validation.
 2. From the trusted fixed GSD Path checkout, preview and then explicitly upgrade only the
    disposable trust checkout's managed trust anchor:
 
@@ -447,6 +476,11 @@ worktree's guard.
    python3 -B <verified-runtime>/archive_milestone.py validate-integrated --repo <validation-root> --slug <STATE.milestone>
    ```
 
+   When the validation checkout is on the default branch after the milestone
+   closed (the bound branch is gone), pass `--historical`; a rebase-merged
+   landing is then accepted only through the milestone tag's Ship/Landing
+   pair plus a re-proven rebase replay.
+
 4. A pass restores the normal shipped handoff without another commit or
    publication action. Remove only the disposable checkouts. A failure is a
    new validation finding: report it with the primary worktree's archived

package/skills/gsd-path-ship/references/reviewer-final.md

@@ -1,6 +1,16 @@
 ## Final integration mode
 
 Use only final-review.md. Treat INTENT.md success criteria as the rubric.
+To locate each task's authoritative accepted evidence instead of joining
+task Logs, ledger rows, and gap artifacts by hand, run
+`python3 <absolute build_state.py> evidence-manifest --repo
+<absolute primary> --project-dir .project --head <reviewed HEAD>`:
+it classifies every task as `ledger`, `log-only`, `rejected`,
+`superseded`, or `missing` and names the receipt, and reports the member
+project Verify as `gap-embedded` only from a passing `final-gap-1.md` at
+the reviewed HEAD — a
+`log-only` task is accepted through its retained isolated-Verify Log, and
+an absent ledger row is explained, never treated as data loss.
 Each `### SCn —` heading must have every word of the criterion in INTENT.md
 `## Success criteria`: join indented continuation lines and sub-bullets
 with a single space. You can keep or remove the `- ` markers of the

package/skills/gsd-path-ship/references/reviewer-wave.md

@@ -8,19 +8,45 @@ tasks in this wave as the rubric. For each task:
    Never infer either SHA from task ids, branch position, or nearby history.
 2. Fail a missing, malformed, or invalid SHA. Inspect the commit with
    `git show --format=fuller --stat --patch <commit> --`.
-3. In the supplied verify sidecar at `base`, apply only the complete
-   binary patch from `commit^..commit` for the task's declared product files
-   and inspect the diff. Use the orchestrator's recorded isolated Verify
-   output in that task's Log as the Verify evidence. Do not re-run the
-   task Verify command or PLAN.md's project Verify. Re-run a command only
-   when the recorded output plus the isolated diff cannot check the
-   criterion. Never use the primary worktree or branch tip as task
-   evidence. Do not create or remove Git worktrees yourself.
-4. Mark `pass` or `fail`. Before the evidence separator (` — `), copy the
-   complete task acceptance or interface criterion (see Review file format
-   below). Do not substitute an AC id or summary: finding grouping binds
-   this text to the task. Give the observed result, `file:line`, and
+3. Select the inspection mode your brief supplies and record it — never
+   improvise a third:
+   - **Reconstructed product** (default): the brief supplies a verify
+     sidecar at `base`. In it, apply only the complete binary patch from
+     `commit^..commit` for the task's declared product files and inspect
+     the diff. Use the orchestrator's recorded isolated Verify output in
+     that task's Log as the Verify evidence.
+   - **Immutable patch**: the brief supplies one later combined checkout
+     with report-write authority only. Inspect the immutable objects
+     directly — `git show`/`git diff` on the recorded commits — and prove
+     the identity before judging: (a) the landing commit's parent
+     `commit^` equals the task file's recorded `base` (or the patch's
+     resulting blobs at `base` equal the landing commit's blobs for the
+     declared files), and (b) any file judged from the combined checkout
+     has its blob there equal to the landing commit's blob at that path.
+     Without both identities the review blocks: a mismatch means the
+     supplied checkout is not the reviewed product.
+   In both modes: do not re-run the task Verify command or PLAN.md's
+   project Verify; re-run a command only when the recorded output plus
+   the diff cannot check the criterion. Never use the primary worktree
+   or branch tip as task evidence. Do not create or remove Git worktrees
+   yourself.
+4. Mark `pass` or `fail`. Before the evidence separator (` — `), name the
+   criterion (see Review file format below): copy the complete task
+   acceptance or interface criterion verbatim, or — on a `pass` line only —
+   cite the criterion by its stable id in the task's numbered acceptance or
+   interface list (`T012/AC3`, `T012/IF2`) together with the evidence. A
+   `fail` line always copies the criterion verbatim: finding grouping binds
+   that text to the task. Give the observed result, `file:line`, and
    concrete fix direction for each failure.
+5. Account for every claim. Each acceptance criterion (`T012/AC3`) and
+   interface bullet (`T012/IF2`) of the task must appear in its
+   section as an evidence reference, a finding, or an explicitly
+   authorized disposition — a bare line naming the id with
+   `disposition: <authority and date> (<Cn>): <reason>`, where `Cn` is a
+   numbered INTENT.md correction. No citation, or a `Cn` that
+   `## Corrections` does not define, fails the gate. One observation may
+   support several claims when each is identified by its id. The wave gate
+   rejects a review that leaves a claim unaccounted for.
 
 A Log entry `orchestrator regression Verify of <task id> retired: superseded
 by <task id>` is not evidence: judge the superseding task's acceptance
@@ -30,8 +56,12 @@ criteria. The same applies to the entry `orchestrator regression Verify of
 Then check each INTENT.md success criterion owned by a task in this wave
 against that same isolated product. In each `### SCn —` heading, copy the
 complete criterion text from INTENT.md `## Success criteria` (see Review
-file format below). Mark `pass` or `fail` with evidence; a failed owned SC
-blocks the wave. Omit the Intent coverage section when no task in the wave owns
+file format below). Write the headings in ascending SC id order (SC2 before
+SC4), and separate the id from the text with an em dash (—). Mark `pass`
+or `fail` with evidence; a failed owned SC blocks the wave. Under a `pass`
+SC, record each subclaim a numbered INTENT.md correction excludes as
+`- Excluded by <Cn>: <subclaim>`; the gate rejects an exclusion under a
+failing SC or one that cites an undefined correction. Omit the Intent coverage section when no task in the wave owns
 an SC. When INTENT.md `## Edge coverage` or `## Prohibitions` has rows for
 an owned SC, judge it against those rulings too: cite each `held-out` edge
 id with its held-out test's recorded output and each `judgment` prohibition
@@ -40,8 +70,12 @@ fails the SC.
 
 Allow changed paths only in the task's `files` plus its assigned task file.
 Within the task file, allow orchestrator-owned `base`, `worktree`,
-`task_branch`, `status`, and `agent` fields plus append-only Log
-entries; block contract-body changes in the task commit. Warn on disabled tests
+`task_branch`, `status`, and `agent` fields — and, on a member task,
+`member_base` — plus append-only Log entries; block contract-body changes
+in the task commit. `base` names the task's starting commit in the
+coordinator repository; `member_base` names the starting commit in the
+member repository from which the member task branch and isolate were
+created. Warn on disabled tests
 or Verify commands that cannot fail unless either defeats a criterion. Set the
 wave verdict to `pass` only when every task passes and every owned INTENT
 success criterion for the wave passes.
@@ -65,10 +99,14 @@ criterion text does not match. Apply the rules before you write the file.
   `- ❌ ` for fail. Each task section and each `### SCn —` block needs one
   or more lines with the marker of its own verdict. A failed task needs a
   `- ❌ ` criterion line, also when other text describes the failure.
-- **Criterion text.** In a task evidence line and in a `### SCn —` heading,
-  copy every word of the criterion. Join wrapped lines and sub-bullets with
-  one space. You can keep or remove the `- ` markers of the sub-bullets.
-  A changed, added, removed or moved word does not match.
+- **Criterion text.** In a `### SCn —` heading and on every `- ❌ ` fail
+  line, copy every word of the criterion. Join wrapped lines and
+  sub-bullets with one space. You can keep or remove the `- ` markers of
+  the sub-bullets. A changed, added, removed or moved word does not
+  match. On a `- ✅ ` pass line, name the criterion either by copying it
+  verbatim or by citing its stable id in the task's numbered acceptance
+  or interface list (`T001/AC1`, `T001/IF2`) together with the evidence;
+  the wave gate does not compare pass-line criterion text.
 - **Angle brackets.** Text such as `<b>` or `<path>` outside backticks reads
   as an unfilled template placeholder and is rejected. Write literal markup
   and code in backticks inside a sentence, for example: the output has
@@ -116,8 +154,9 @@ runtime checks freshness and derives the final view from these records.
 ## Deep review lenses
 
 A `deep` wave spawns two independent reviewers in parallel, each with a fresh
-context and its own verify sidecar at the recorded review base. Every
-Wave mode rule above applies to both lenses.
+context and its own isolated workspace at the recorded review base (a verify
+sidecar in reconstructed mode, or the supplied combined checkout in immutable
+mode). Every Wave mode rule above applies to both lenses.
 
 - **Contract** — logical task name
   `review_wave_<wave>_cycle_<cycle>_contract`; stages

package/skills/gsd-path-ship/references/reviewer.md

@@ -5,16 +5,18 @@ Verify written GSD Path expectations and block failures. Never fix code.
 ## Brief contract
 
 - Require the mode, all inputs, exact canonical output path, applicable
-  template, repository root, and orchestrator-created verify sidecar
-  root by absolute path. Wave mode also requires the absolute INTENT.md
-  path. The brief must also name the staged output path under
-  that sidecar.
+  template, and repository root by absolute path. Wave mode also requires
+  the absolute INTENT.md path and names the inspection mode: a verify
+  sidecar root for reconstructed-product review, or one combined checkout
+  with report-write authority for immutable-patch review. The brief must
+  also name the staged output path under that workspace.
 - Read AGENTS.md and the template before reviewing.
-- Write only the exact assigned review output under the supplied verify sidecar
+- Write only the exact assigned review output under the supplied workspace
   at its staged `.project/review/` path. The orchestrator validates and
   atomically transfers that file to the canonical primary `.project/review/`
   path after collection. Temporary patch/test effects are allowed solely
-  inside supplied sidecars. Never edit a product path or any other
+  inside supplied sidecars; an immutable-mode combined checkout carries
+  report-write authority only. Never edit a product path or any other
   primary-worktree path. Stop on a missing input or template.
 
 ## Load the assigned mode

package/skills/gsd-path-ship/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-ship/references/spec-probes.md

@@ -96,6 +96,23 @@ Present the kept items with a recommended ruling and record each as a row:
 Work that affects no person directly records a single row instead, and no
 other: `| N1 | all | none | dismissed | <why no person is affected> |`.
 
+## Absence criteria
+
+A criterion that claims absence ("X does not exist", "no X anywhere",
+"never Y"), including one written from a prohibition, has no end until it
+says where to look. Each review can look somewhere new, so the build loops
+to the cycle cap. Every absence criterion states:
+
+- the search space: the files, surfaces, or artifacts to check;
+- the check: the command or observation that covers that space;
+- the absent result: the output that counts as absent.
+
+When one is missing, propose a bounded form in the same question round as
+the edges, recommended form first, and amend the criterion after the user
+rules. Do not choose the search space yourself: a narrower space is a scope
+ruling. Under pre-approval, an unbounded absence criterion is a required
+answer: stop and ask.
+
 ## INTENT.md tables
 
 ```markdown
@@ -131,7 +148,8 @@ rechecked; a near-miss heading fails the gate rather than switching it off.
   the owning task's Approach so the coder knows the line.
 - **Review.** A row pins the reading of its criterion. A reviewer does not
   pass a reading that contradicts a ruling in either table, and cites each
-  held-out edge and judgment prohibition id with its evidence.
+  held-out edge and judgment prohibition id with its evidence. An absence
+  criterion is judged over its stated search space only.
 - **Final review.** A criterion that carries a held-out edge or a judgment
   prohibition is `met` only when its Check, Observed, or Reference cites
   every such id with the evidence: the held-out test's recorded passing