@opengsd/gsd-path 1.6.1 → 1.7.0

package/skills/gsd-path/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/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

package/skills/gsd-path/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/scripts/archive_milestone.py

@@ -781,7 +781,14 @@ def validate_panel_skip_receipt(path: Path, expected_mode: str) -> None:
         not isinstance(item, dict)
         or set(item) != {"family", "reason"}
         or item["family"] not in KNOWN_FAMILIES
-        or item["reason"] not in {"parent family", "not advertised", "cap"}
+        # review_panel resolve writes every one of these reasons (#460);
+        # the receipt must validate whatever the helper can produce.
+        or item["reason"] not in {
+            "parent family",
+            "not advertised",
+            "cap",
+            "excluded reviewer family",
+        }
         for item in skipped
     ):
         raise ArchiveError(f"{path.name} has invalid skipped families")
@@ -1998,6 +2005,62 @@ def member_ship_rows(project: Path, archive: Path, ship_commit: str) -> list:
     return rows
 
 
+def tag_metadata_fields(project: Path, tag_ref: str) -> dict[str, str]:
+    """The Key: value fields of an annotated milestone tag's message."""
+    message = require_git_success(
+        run_git(project, "for-each-ref", "--format=%(contents)", tag_ref),
+        "inspect milestone tag",
+    )
+    fields: dict[str, str] = {}
+    for line in message.splitlines():
+        match = re.fullmatch(r"(Mode|Pull-Request|Ship|Landing): (.+)", line)
+        if match:
+            if match.group(1) in fields:
+                raise ArchiveError("milestone tag repeats metadata")
+            fields[match.group(1)] = match.group(2)
+    return fields
+
+
+def accept_rebased_ship(
+    project: Path, archive: Path, ship_commit: str, reviewed_head: str
+) -> Optional[str]:
+    """Accept the rebased ship copy a rebase merge landed, keyed by the milestone tag.
+
+    Historical validation only (issue #450): after a rebase merge the landed
+    ship copy's parent is never the reviewed HEAD, so the strict check cannot
+    pass over landed history. Acceptance requires the milestone tag to name
+    exactly this commit as its Landing, the original ship commit the tag
+    names to still resolve, the strict invariant re-proven against the
+    original ship's parent, and the rebase replay to hold. Returns the tag's
+    original Ship sha, or None when the landing is not a proven rebase: a
+    landing whose originals no longer resolve anywhere is refused, because
+    the per-task landing proofs elsewhere in validation pin the original
+    commits and a tag receipt alone cannot carry a full validation.
+    """
+    tag_ref = f"refs/tags/milestone/{archive.name}"
+    if run_git(project, "rev-parse", "--verify", "--quiet", tag_ref).returncode != 0:
+        return None
+    try:
+        fields = tag_metadata_fields(project, tag_ref)
+    except ArchiveError:
+        return None
+    if fields.get("Mode") != "pull-request":
+        return None
+    original = fields.get("Ship")
+    if not original or fields.get("Landing") != ship_commit:
+        return None
+    if run_git(project, "cat-file", "-e", f"{original}^{{commit}}").returncode != 0:
+        return None
+    original_parent = require_git_success(
+        run_git(project, "rev-parse", f"{original}^"), "resolve original ship parent"
+    )
+    if not reviewed_head_covers(project, reviewed_head, original_parent):
+        return None
+    if _common.rebase_landing_problem(project, original, ship_commit) is not None:
+        return None
+    return original
+
+
 def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
@@ -2093,11 +2156,17 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
 
     members = member_ship_rows(project, archive, ship_commit)
     ship_parent = require_git_success(run_git(project, "rev-parse", f"{ship_commit}^"), "resolve ship parent")
+    rebased_ship: Optional[str] = None
     if not reviewed_head_covers(project, reviewed_head, ship_parent):
-        raise ArchiveError(
-            f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
-            f"{_common.RUNTIME_PIN_ALLOWANCE}"
+        rebased_ship = (
+            accept_rebased_ship(project, archive, ship_commit, reviewed_head)
+            if historical else None
         )
+        if rebased_ship is None:
+            raise ArchiveError(
+                f"FINAL.md Reviewed HEAD {reviewed_head} does not match ship parent {ship_parent}; "
+                f"{_common.RUNTIME_PIN_ALLOWANCE}"
+            )
     require_canonical_commit_body(
         project,
         ship_commit,
@@ -2141,6 +2210,8 @@ def validate(repo: Path, *, historical: bool = False) -> dict:
         )
 
     result = {"archive": configured, "commit": ship_commit}
+    if rebased_ship is not None:
+        result["rebased_ship"] = rebased_ship
     if members:
         result["members"] = members
     return result
@@ -2178,6 +2249,15 @@ def parser() -> argparse.ArgumentParser:
     )
     validate_integrated_parser.add_argument("--repo", required=True, type=Path)
     validate_integrated_parser.add_argument("--slug", required=True)
+    validate_integrated_parser.add_argument(
+        "--historical",
+        action="store_true",
+        help=(
+            "validate from the landed default branch after the milestone closed "
+            "(the bound branch may be gone; a rebase-merged landing is proven "
+            "through the milestone tag)"
+        ),
+    )
 
     refresh_parser = subparsers.add_parser(
         "refresh-origin",
@@ -2190,6 +2270,17 @@ def parser() -> argparse.ArgumentParser:
         help="after preflight, integrate each locked member in lock order before the ship commit",
     )
     close_members_parser.add_argument("--repo", required=True, type=Path)
+    close_members_parser.add_argument(
+        "--adopt-landed-member",
+        action="append",
+        default=[],
+        metavar="MEMBER=SHA",
+        help=(
+            "user-approved recovery for a member whose reviewed HEAD already reached its "
+            "default branch outside Path; MEMBER=SHA names the live default-branch tip "
+            "to adopt as the landing"
+        ),
+    )
 
     integrate_parser = subparsers.add_parser(
         "integrate",
@@ -2197,6 +2288,16 @@ def parser() -> argparse.ArgumentParser:
     )
     integrate_parser.add_argument("--repo", required=True, type=Path)
     integrate_parser.add_argument("--slug", required=True)
+    integrate_parser.add_argument(
+        "--adopt-published-bound",
+        metavar="SHA",
+        help=(
+            "user-approved recovery when origin's bound branch is a strict ancestor "
+            "of the ship commit (a build task pushed it as a deploy pin, #464); "
+            "the 40-hex SHA must equal the live remote tip exactly; the publish "
+            "fast-forwards under the existing exact lease. Direct integration only"
+        ),
+    )
 
     abandon_parser = subparsers.add_parser(
         "abandon",
@@ -2225,13 +2326,34 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         elif arguments.command == "abandon":
             result = abandon(arguments.repo, arguments.slug, arguments.reason)
         elif arguments.command == "validate-integrated":
-            result = integration.validate_integrated(arguments.repo, arguments.slug)
+            result = integration.validate_integrated(
+                arguments.repo, arguments.slug, historical=arguments.historical
+            )
         elif arguments.command == "refresh-origin":
             result = integration.refresh_origin(arguments.repo)
         elif arguments.command == "close-members":
-            result = integration.close_members(arguments.repo)
+            adopt: dict[str, str] = {}
+            for item in arguments.adopt_landed_member:
+                name, separator, sha = item.partition("=")
+                if not name or not separator or not re.fullmatch(r"[0-9a-f]{40}", sha):
+                    parser_error = (
+                        f"--adopt-landed-member expects MEMBER=SHA (40-hex), got {item!r}"
+                    )
+                    print(parser_error, file=sys.stderr)
+                    return 2
+                adopt[name] = sha
+            result = integration.close_members(arguments.repo, adopt=adopt or None)
         elif arguments.command == "integrate":
-            result = integration.integrate(arguments.repo, arguments.slug)
+            adopt_bound = arguments.adopt_published_bound
+            if adopt_bound is not None:
+                adopt_bound = adopt_bound.lower()
+            if adopt_bound is not None and not re.fullmatch(r"[0-9a-f]{40}", adopt_bound):
+                print(
+                    f"--adopt-published-bound expects a 40-hex SHA, got {adopt_bound!r}",
+                    file=sys.stderr,
+                )
+                return 2
+            result = integration.integrate(arguments.repo, arguments.slug, adopt_bound)
         else:
             result = validate(arguments.repo)
     except (ArchiveError, OSError) as error:

package/skills/gsd-path/scripts/build_recovery.py

@@ -144,7 +144,13 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
             raise state.PipelineStateError(f"invalid recovery task path: {path.name}")
         text = state._read_real_file(path, path.name)
         fields = task_fields(text, path.name)
-        if fields.get("status") not in {"pending", "done"}:
+        if fields.get("status") == "withdrawn":
+            # A cited tombstone is settled inventory; recovery skips it (#483).
+            if not state._common.withdrawn_citations(text):
+                raise state.PipelineStateError(
+                    f"withdrawn task lacks an owner citation: {path.name}"
+                )
+        elif fields.get("status") not in {"pending", "done"}:
             raise state.PipelineStateError(f"settle task ownership before recovery: {path.name}")
         if fields["status"] == "pending" and any(
             fields.get(key) != "null" for key in ("agent", "base", "worktree", "task_branch")
@@ -250,7 +256,24 @@ def validate_review_backup(repo: Path, recovery: dict, directory: Path) -> None:
               for path in directory.rglob("*")
               if path.is_file() and not state._common.is_ignored_junk(path)} if directory.exists() else {}
     if actual != expected:
-        raise state.PipelineStateError("review backup differs from the recovery base")
+        extra = sorted(set(actual) - set(expected))
+        changed = sorted(
+            name for name in set(actual) & set(expected) if actual[name] != expected[name]
+        )
+        missing = sorted(set(expected) - set(actual))
+        detail = ""
+        if extra:
+            detail += f" files in the review backup that the recovery base does not have: {', '.join(extra)}."
+        if changed:
+            detail += f" files differing from the recovery base: {', '.join(changed)}."
+        if missing:
+            detail += f" files at the recovery base missing from the review backup: {', '.join(missing)}."
+        raise state.PipelineStateError(
+            "review backup differs from the recovery base." + detail
+            + " prepare-build-recovery must run before re-planning touches any recovery"
+            " artifact; remove the extra files and restore the missing or changed ones"
+            " to the recovery base's content, then rerun prepare"
+        )
 
 
 def prepare(repo: Path) -> dict: