@opengsd/gsd-path 1.5.0 → 1.6.1

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

@@ -1,11 +1,11 @@
 ## Final integration mode
 
 Use only final-review.md. Treat INTENT.md success criteria as the rubric.
-Each `### SCn —` heading must match the criterion text as
-`check_handoffs._success_criteria` stores it from INTENT.md `## Success
-criteria`: indented continuation lines join with a single space and keep
-their `- ` list markers; the gate compares titles with `_normalize_ws`
-only. Exercise the running system and record `met`, `not-met`, or
+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
+sub-bullets; the gate compares every other word. Exercise the running
+system and record `met`, `not-met`, or
 `unverifiable` with checked command output or a precise file reference.
 When PLAN.md carries
 a `## Surface contract`, every criterion it lists under a surface is checked

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

@@ -17,19 +17,21 @@ tasks in this wave as the rubric. For each task:
    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 verbatim, joining wrapped
-   lines with spaces. Do not substitute an AC id or summary: finding grouping
-   binds this text to the task. Give the observed result, `file:line`, and
+   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
    concrete fix direction for each failure.
 
+A Log entry `orchestrator regression Verify of <task id> retired: superseded
+by <task id>` is not evidence: judge the superseding task's acceptance
+criteria. The same applies to the entry `orchestrator regression Verify of
+<fix task id>: part of <task id> retired: superseded by <task id>`.
+
 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
-criterion text exactly as `check_handoffs._success_criteria` stores it from
-INTENT.md `## Success criteria`: indented continuation lines are joined
-with a single space and keep their `- ` list markers in the compared text;
-only whitespace is normalized at the gate. Do not paraphrase or drop
-sub-bullets. 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
+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
 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
@@ -48,6 +50,30 @@ For cycle greater than 1, read the previous review, re-check every failure,
 and regression-check affected passes. State when the same criterion fails for
 a different reason. Use only the wave-review template.
 
+### Review file format
+
+`scripts/check_handoffs.py wave` rejects a review file that breaks one of
+these rules, and `scripts/review_findings.py` cannot group a failure whose
+criterion text does not match. Apply the rules before you write the file.
+
+- **Section order.** Put the `## T### —` sections in task id order (T001
+  before T002). The order of the PLAN.md wave table does not apply. A `pass`
+  review has one section for each task of the wave.
+- **Section heading.** Write `## T### — <title>: pass` or `: fail`, where
+  `<title>` is the exact `title:` value of the task file.
+- **Evidence lines.** An evidence line starts with `- ✅ ` for pass or
+  `- ❌ ` 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.
+- **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
+  `<b>hello</b>`.
+
 ### Re-review after a proven repair
 
 When the brief supplies a `review_findings.py repair-evidence` receipt, use
@@ -55,14 +81,21 @@ its isolated repair product for the linked original criteria, including owned
 INTENT criteria. The original faulty landing and earlier verdicts remain
 historical evidence; they do not force the later verdict to remain failed.
 Reconstruct the receipt's repair `base` plus only its `commit^..commit` patch
-for `files` inside the supplied sidecar. Read the repair task's recorded
-Verify, inspect the patch against the original unchanged contract, and reuse
+for `files` inside the supplied sidecar. For a member repair (the receipt
+names `member`), use `member_base` and `member_commit` in that member's
+repository. `earlier_repairs` are linked repairs of the same findings that
+are already in the repair base. When the receipt has `later_repairs`, linked
+repairs changed the same files after this repair: apply their patches in
+order too. Read the repair task's recorded
+Verify, or with `later_repairs` that of the last one, which is the receipt's
+`verification`; inspect the patch against the original unchanged contract, and reuse
 settled checks. Check unaffected criteria from their prior evidence plus the
 repair diff for regressions. Cite the receipt, repair landing and task Log in
 the new review. A receipt proves provenance, not acceptance: judge whether the
 repair actually satisfies the criterion. A missing or rejected receipt blocks
-using that repair; the parent resolves it rather than creating another product
-fix for the unchanged historical failure.
+using that repair; the parent resolves it, or briefs this review in full at
+the current HEAD without a receipt, rather than creating another product fix
+for the unchanged historical failure.
 
 ## Final scope in a quick full wave
 

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

@@ -20,6 +20,16 @@ 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.
 
+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
+helper: run the bundled copy until the project runtime is upgraded.
+`dispatch_driver.py` and `workflow_run.py` always run from the installed skill
+bundle, because they read role briefs and templates from it; a skill update
+replaces them, a runtime upgrade does not. The driver reloads the helper modules
+that it imports from the selected runtime, and runs the subprocess helpers that
+the runtime lists (such as the fix-task brief lint) from it.
+
 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/path/scripts/_common.py

@@ -25,7 +25,8 @@ import signal
 import subprocess
 import time
 from pathlib import Path
-from typing import BinaryIO, Iterator, List, Optional, Sequence
+from typing import BinaryIO, Iterable, Iterator, List, Optional, Sequence, Tuple
+
 
 # Chosen by what imports, not os.name, so tests can emulate Windows on POSIX.
 try:
@@ -161,6 +162,33 @@ def project_ignore_error(repo: Path) -> Optional[str]:
             + ". Anchor the product rule (for example `/build/`) in a task that owns it.")
 
 
+_DEFAULT_BRANCH_RE = re.compile(
+    r"[^\s#\"'\\~^:?*\[\x00-\x1f\x7f-][^\s#\"'\\~^:?*\[\x00-\x1f\x7f]*"
+)
+_RESERVED_BRANCH_PREFIXES = ("gsd-path/", "gsd-path-integrate/", "gsd-path-task/")
+
+
+def valid_default_branch(name: str) -> bool:
+    """A git branch name that STATE frontmatter can hold and Path does not reserve."""
+    return (
+        bool(_DEFAULT_BRANCH_RE.fullmatch(name))
+        and name != "null"
+        and not name.startswith(_RESERVED_BRANCH_PREFIXES)
+        and not name.endswith(("/", ".", ".lock"))
+        and not any(part in name for part in ("..", "//", "/.", "@{"))
+    )
+
+
+def origin_default_branch(repo: Path) -> str:
+    """The origin default branch that initialization records; an unset origin/HEAD means main."""
+    result = run_git(repo, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    prefix = "refs/remotes/origin/"
+    remote_ref = result.stdout.strip()
+    if result.returncode != 0 or not remote_ref.startswith(prefix):
+        return "main"
+    return remote_ref.removeprefix(prefix)
+
+
 def section_body(text: str, heading: str) -> Optional[str]:
     """The text under `## <heading>` up to the next `## `, or None when absent."""
     match = re.search(
@@ -169,6 +197,79 @@ def section_body(text: str, heading: str) -> Optional[str]:
     return match.group("body") if match else None
 
 
+def overlapping_paths(left: Sequence[str], right: Sequence[str]) -> List[str]:
+    """Return the sorted paths that two task `files` lists both cover.
+
+    An entry covers itself and the paths below it. For a declared directory
+    and a path below it, the result names the lower path. The callers have no
+    task base, so this does not ask if an entry is a file: the task-brief
+    lint rejects a path below a file at the base.
+    """
+    return sorted(
+        {
+            max(one, other, key=len)
+            for one in left
+            for other in right
+            if one == other or one.startswith(other + "/") or other.startswith(one + "/")
+        }
+    )
+
+
+# The `- ` of an indented sub-bullet line. A line that would then read as a
+# numbered item (`- 2. text`) keeps its marker, so both readings of a source
+# have the same criteria.
+SUB_BULLET_MARKER = re.compile(r"(?m)^([ \t]+)-[ \t]+(?![ \t]*\d+\.\s)")
+
+
+def without_sub_bullet_markers(source: str) -> str:
+    """`source` with the `- ` marker of each indented sub-bullet line removed."""
+    return SUB_BULLET_MARKER.sub(r"\1", source)
+
+
+class Criterion(str):
+    """A criterion as its parser joins it, with the `- ` markers of its sub-bullet lines.
+
+    `bare` is the same criterion parsed from `without_sub_bullet_markers(source)`.
+    The joined text cannot tell a marker from a minus sign; the source lines can.
+    """
+
+    bare: str
+
+    def __new__(cls, text: str, bare: str) -> "Criterion":
+        criterion = super().__new__(cls, text)
+        criterion.bare = bare
+        return criterion
+
+
+def quotes_criterion(quote: str, criterion: str) -> bool:
+    """Whether a review quote is `criterion`, for every reader.
+
+    Only whitespace is collapsed. The quote must equal the criterion with all
+    the markers of its sub-bullet lines or with none of them; every other
+    character, a hyphen inside a line too, is compared.
+    """
+    forms = (criterion, getattr(criterion, "bare", criterion))
+    return " ".join(quote.split()) in {" ".join(form.split()) for form in forms}
+
+
+def quoted_criterion(item: str, criteria: Sequence[str]) -> Optional[Tuple[int, int]]:
+    """Index of the criterion quoted at the start of `item`, and where the quote ends.
+
+    A criterion can contain ` — ` itself, so each separator and the end of
+    `item` is a candidate, the longest quote first. A criterion as written
+    wins over any criterion read without its sub-bullet markers.
+    """
+    ends = [match.start() for match in re.finditer("(?= —(?: |$))|$", item)][::-1]
+    for bare in (False, True):
+        for end in ends:
+            quote = " ".join(item[:end].split())
+            for index, criterion in enumerate(criteria):
+                form = getattr(criterion, "bare", criterion) if bare else criterion
+                if quote == " ".join(form.split()):
+                    return index, end
+    return None
+
+
 def task_verify_command(task_text: str) -> str:
     """The Verify shell text, excluding the closing fence's separator newline."""
     body = section_body(task_text, "Verify")
@@ -176,6 +277,11 @@ def task_verify_command(task_text: str) -> str:
     return block.group("block").removesuffix("\n") if block else ""
 
 
+def fix_verify(commands: Iterable[str]) -> str:
+    """The Verify of a fix task: each distinct source Verify in its own subshell, under `set -e`."""
+    return "set -e\n" + "\n".join(f"(\n{command}\n)" for command in dict.fromkeys(commands))
+
+
 def latest_verify_entry(entries: list, command: str, commit: str,
                         repo: Optional[str] = None) -> Optional[dict]:
     """Rows are keyed by (command, repo, commit); a row without `repo` is a coordinator row."""
@@ -255,6 +361,49 @@ def run_git(
     return _run_exact(git_command(repo, *arguments), input=input)
 
 
+def _patch_ids(repo: Path, commits: Sequence[str]) -> list[Optional[str]]:
+    """`git patch-id --stable` per commit, in order; None for an empty commit."""
+    log = run_git(repo, "log", "--no-walk=unsorted", "-p", "--binary", "--no-color",
+                  "--no-ext-diff", *commits)
+    if log.returncode != 0:
+        raise ValueError("could not read commit patches")
+    ids = run_git(repo, "patch-id", "--stable", input=log.stdout)
+    if ids.returncode != 0:
+        raise ValueError("could not compute patch ids")
+    by_commit = {commit: patch for patch, commit in (line.split() for line in ids.stdout.splitlines())}
+    return [by_commit.get(commit) for commit in commits]
+
+
+def rebase_landing_problem(repo: Path, ship: str, landing: str) -> Optional[str]:
+    """Why landing is not a forge rebase merge of ship, or None when it is (#418).
+
+    A rebase merge replays ship's own commits onto the default branch. Proof:
+    the first-parent run that ends at landing has one non-merge commit per
+    non-merge commit of landing..ship, with equal patch ids in the same order;
+    when that run starts at ship's fork point, landing's tree equals ship's.
+    """
+    listed = run_git(repo, "rev-list", "--reverse", "--topo-order", "--no-merges", f"{landing}..{ship}")
+    if listed.returncode != 0:
+        return "could not list the ship commits"
+    originals = listed.stdout.split()
+    if not originals:
+        return "landing already contains the ship commit"
+    walked = run_git(repo, "rev-list", "--first-parent", "--parents", "-n", str(len(originals)), landing)
+    rows = [line.split() for line in walked.stdout.splitlines()][::-1]
+    if walked.returncode != 0 or len(rows) != len(originals) or any(len(row) != 2 for row in rows):
+        return "landing is not a linear run of rebased commits"
+    try:
+        if _patch_ids(repo, originals) != _patch_ids(repo, [row[0] for row in rows]):
+            return "rebased commits do not replay the ship commits in order"
+    except ValueError as error:
+        return str(error)
+    fork = run_git(repo, "merge-base", ship, landing).stdout.strip()
+    trees = run_git(repo, "rev-parse", f"{ship}^{{tree}}", f"{landing}^{{tree}}").stdout.split()
+    if rows[0][1] == fork and (len(trees) != 2 or trees[0] != trees[1]):
+        return "rebased tree differs from the ship tree"
+    return None
+
+
 def git_command(repo: Path, *arguments: str) -> tuple[str, ...]:
     """Git argv for repo, including WSL drvfs workarounds when needed."""
     return ("git", "-C", str(repo), *git_drvfs_config_flags(repo), *arguments)

package/skills/path/scripts/build_recovery.py

@@ -22,6 +22,10 @@ MARKER = "build recovery: "
 RECOVERY_KEYS = frozenset({"base", "branch", "kind", "source"})
 
 
+# Only the value of a cap line is exempt; a comment or a line separator after it stays in the compared text.
+CAP_VALUE = re.compile(r"(?m)^(-[ \t]*(?:max_review_cycles|wave_budget):)[ \t\w.,$/:]*")
+
+
 def runtime():
     if __package__:
         from scripts import pipeline_state
@@ -58,8 +62,17 @@ def _parse_recovery_record(value: object) -> dict:
     return {**value, "source": source}
 
 
-def _recovery_base_proves_milestone(before, current, source: str) -> bool:
-    if before.branch != current.branch or before.milestone != current.milestone:
+def _recovery_base_proves_milestone(before, current, source: str, active: bool = True) -> bool:
+    if before.branch != current.branch:
+        return False
+    if before.milestone != current.milestone and (
+        # Issue #374: a legacy base records milestone null when define never
+        # named it. The owner names it at ship, after the build resumed, so
+        # only a closed build recovery accepts an unset base milestone; the
+        # bound branch already encodes M00N. A milestone named by the base
+        # must still equal the current one.
+        active or source != "build" or before.milestone is not None
+    ):
         return False
     if source == "plan":
         return (before.phase, before.status) in {("plan", "active"), ("plan", "blocked")}
@@ -99,7 +112,9 @@ def context(repo: Path, text: str | None = None) -> dict | None:
         if base_text is None:
             raise state.PipelineStateError("build recovery base has no STATE.md")
         before = state._state_from_text(base_text)
-        if not _recovery_base_proves_milestone(before, current, recovery.get("source", "build")):
+        if not _recovery_base_proves_milestone(
+            before, current, recovery.get("source", "build"), recovery["active"]
+        ):
             raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
     return recovery
 
@@ -289,61 +304,78 @@ def validate_plan(repo: Path) -> None:
         intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
         if state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md") != intent:
             raise state.PipelineStateError("plan repair cannot change approved intent")
-    unchanged = unchanged_waves(repo, recovery)
-    for path in (repo / ".project/review").iterdir():
-        match = re.match(r"wave-([1-9]\d*)[.]", path.name)
-        if match and int(match[1]) not in unchanged:
-            raise state.PipelineStateError("changed wave must be reviewed after build resumes")
+    if stale_review_reasons(repo, recovery, _review_waves(repo / ".project/review")):
+        raise state.PipelineStateError("changed wave must be reviewed after build resumes")
 
 
-def unchanged_waves(repo: Path, recovery: dict) -> set[int]:
-    """Reuse evidence only when its intent, wave contract, and task bytes match."""
+def _review_waves(directory: Path) -> set[int]:
+    return {int(match[1]) for path in directory.iterdir()
+            if (match := re.match(r"wave-([1-9]\d*)[.]", path.name))}
+
+
+def stale_review_reasons(repo: Path, recovery: dict, waves: set[int]) -> dict[int, str]:
+    """Say why a wave's preserved review is stale; a wave not returned has matching intent, plan, and task bytes."""
     state = runtime()
     project = repo / ".project"
     old_intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
     if state._read_real_file(project / "intent/INTENT.md", "INTENT.md") != old_intent:
-        return set()
+        return dict.fromkeys(waves, "INTENT.md changed")
     old_plan = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/plan/PLAN.md") or ""
     new_plan = state._read_real_file(project / "plan/PLAN.md", "PLAN.md")
+    panel_lines = r"(?m)^-[ \t]*review_panel:.*$"
+    if re.findall(panel_lines, old_plan) != re.findall(panel_lines, new_plan):
+        return dict.fromkeys(waves, "PLAN.md `review_panel` setting changed")
 
     def sections(text):
         return {match[1]: match[2] for match in re.finditer(
             r"(?ms)^## ([^\n]+)\n(.*?)(?=^## |\Z)", text,
         )}
 
+    def governing(plan):
+        # Non-wave settings govern every wave, including coverage and surfaces. Caps only bound
+        # later work and Dependency notes are prose, so neither changes what a passed review judged.
+        return {title: CAP_VALUE.sub(r"\1", body) if title == "Config" else body
+                for title, body in plan.items()
+                if not title.startswith("Wave ") and title != "Dependency notes"}
+
     old_sections, new_sections = sections(old_plan), sections(new_plan)
-    # Non-wave settings govern every wave, including coverage and surfaces.
-    if ({k: v for k, v in old_sections.items() if not k.startswith("Wave ")}
-            != {k: v for k, v in new_sections.items() if not k.startswith("Wave ")}):
-        return set()
+    old_governing, new_governing = governing(old_sections), governing(new_sections)
+    for title in sorted(old_governing.keys() | new_governing.keys()):
+        if old_governing.get(title) != new_governing.get(title):
+            return dict.fromkeys(waves, f"PLAN.md section `{title}` changed")
     old_tasks = checkpoint_runtime()._task_contracts_at(repo, recovery["base"], ".project/tasks")
     current = settled_tasks(repo)
-    unchanged = set()
-    for title, body in new_sections.items():
-        match = re.match(r"Wave ([1-9]\d*)\b", title)
-        if not match or old_sections.get(title) != body:
+    reasons = {}
+    for wave in waves:
+        section = {title: body for title, body in new_sections.items() if re.match(rf"Wave {wave}\b", title)}
+        if not section or any(old_sections.get(title) != body for title, body in section.items()):
+            reasons[wave] = f"PLAN.md section `Wave {wave}` changed"
             continue
-        wave = match[1]
         before = {Path(path).name: text for path, text in old_tasks.values()
-                  if task_fields(text, path).get("wave") == wave}
-        after = {name: text for name, (text, fields) in current.items() if fields.get("wave") == wave}
-        if before and before == after:
-            unchanged.add(int(wave))
-    return unchanged
+                  if task_fields(text, path).get("wave") == str(wave)}
+        after = {name: text for name, (text, fields) in current.items() if fields.get("wave") == str(wave)}
+        if not before or before != after:
+            reasons[wave] = f"wave {wave} task contracts changed"
+    return reasons
 
 
-def restore_unchanged_reviews(repo: Path) -> None:
+def restore_unchanged_reviews(repo: Path) -> dict | None:
+    """Restore reusable wave reviews and report every preserved wave, so a dropped review is visible at approval."""
     recovery = context(repo)
     if not recovery or not recovery["active"]:
-        return
-    unchanged = unchanged_waves(repo, recovery)
-    for path in review_backup(repo, recovery).iterdir():
+        return None
+    backup = review_backup(repo, recovery)
+    waves = _review_waves(backup)
+    reasons = stale_review_reasons(repo, recovery, waves)
+    for path in backup.iterdir():
         match = re.match(r"wave-([1-9]\d*)[.]", path.name)
-        if match and int(match[1]) in unchanged:
+        if match and int(match[1]) not in reasons:
             destination = repo / ".project/review" / path.name
             content = path.read_text(encoding="utf-8")
             if not destination.exists() or runtime()._read_real_file(destination, destination.name) != content:
                 runtime()._atomic_write(destination, content)
+    return {"restored": sorted(waves - reasons.keys()),
+            "review_again": [{"wave": wave, "reason": reasons[wave]} for wave in sorted(reasons)]}
 
 
 def inventory_checkpoint(repo: Path, head: str) -> bool: