@opengsd/gsd-path 1.5.0 → 1.6.0

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

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

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import sys
+import traceback
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -33,7 +34,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -41,6 +42,13 @@ def _load_pipeline_modules():
             "scripts._common",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared_scripts))
         import archive_milestone

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

@@ -202,7 +202,11 @@ def native_record(args):
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
                     'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
         if data is not None and data.get('identity') != identity:
-            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+            recorded = data.get('identity')
+            recorded = recorded if isinstance(recorded, dict) else {}
+            differing = ', '.join(f'{field}: {value}, record has {recorded.get(field)}'
+                                  for field, value in identity.items() if recorded.get(field) != value)
+            raise PolicyError(f'record belongs to another assignment or milestone/track/cycle ({differing})')
         if args.action == 'release':
             if data is None or not args.terminal_result:
                 raise PolicyError('release requires an existing record and terminal-result evidence')

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

@@ -12,6 +12,14 @@ Supported first-release hosts: Claude Code and Codex. Handle plugin and
 standalone skill installations separately; a plugin toggle does not remove
 manually registered hooks or globally installed skills.
 
+Path ships onto the default branch of `origin`, with any name. The router
+records that name in STATE `default_branch` at initialization; the helper's
+`preview` and `prepare` commands do not check it. Before the router
+initializes the project, run `git remote set-head origin --auto` so that the
+record is correct.
+Pull-request shipping supports GitHub.com only. For any other host, tell the
+user that the project ships with `direct` or `external-landing`.
+
 This skill prepares an import. The Path router owns initialization and branch
 binding; define owns intent approval. Migration does not copy Core phase
 positions into Path state or turn Core test results into Path gate receipts.

package/skills/gsd-path-migrate/references/operating-rules.md

@@ -38,8 +38,8 @@ bundles this file; spawned agents follow their role brief instead.
   the lookahead planning track for the next milestone; it follows the same
   marker rule, owns no task frontmatter, and never binds a branch.
 - STATE.integration_default is the project closeout choice and
-  STATE.integration is the current milestone choice. Both are `direct` or
-  `pull-request`; STATE.integration_source is `default` or `milestone` and
+  STATE.integration is the current milestone choice. Both are `direct`,
+  `pull-request`, or `external-landing`; STATE.integration_source is `default` or `milestone` and
   preserves explicit override provenance. Older v2 state defaults to `direct`,
   and modes may be changed only through `pipeline_state.py
   configure-integration` before build. A next milestone resets its current
@@ -82,7 +82,9 @@ bundles this file; spawned agents follow their role brief instead.
   `isolation.py attest` may stand in for it: one `.project/`-only commit that
   names the base, the attested HEAD, the declared files that changed, the
   task Verify recorded as passing at that HEAD, and the ruling verbatim.
-  `recover` reports it as `attested`, never as a proven landing.
+  `recover` reports it as `attested`, never as a proven landing. Attestation
+  matches the declared files literally: work that is only below a declared
+  directory can land but cannot be attested.
 - All pipeline work for a milestone lives on `gsd-path/M00N` (M001, M002,
   …) bound in STATE.branch. The next milestone binds a new unused
   `gsd-path/M00N` at the remote default after the previous ship integrates.
@@ -90,6 +92,12 @@ bundles this file; spawned agents follow their role brief instead.
   branch — either Path's direct merge or a Path-owned PR merged by the user.
   The bound branch never receives merges or back-merges and is never the
   GitHub default.
+- The default branch is the one that STATE `default_branch` records at
+  initialization; a STATE file without the field means `main`. `main` and
+  `origin/main` in these rules mean that branch. Never change the record and
+  never take the name from a later `origin/HEAD` lookup. For a member
+  repository, the branch is the one that its `.project/MEMBERS.md` section
+  records as `Default branch`; a section without the field means `main`.
 - After initialization writes STATE.md, and before entering the first pipeline
   phase in an existing Git repository, the router calls
   `scripts/pipeline_git.py bind-initial` with the selected M00N and exact

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

@@ -20,6 +20,15 @@ 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.
+
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
 operation before adopting external storage; review the resulting Git diff.

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

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

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import sys
+import traceback
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -33,7 +34,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -41,6 +42,13 @@ def _load_pipeline_modules():
             "scripts._common",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared_scripts))
         import archive_milestone

package/skills/gsd-path-migrate/scripts/migrate_core.py

@@ -10,6 +10,8 @@ import shutil
 import stat
 import sys
 
+import _common
+
 
 def hook_inventory(settings):
     if settings.is_symlink() or not settings.is_file():

package/skills/gsd-path-migrate/scripts/model_policy.py

@@ -202,7 +202,11 @@ def native_record(args):
         identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
                     'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
         if data is not None and data.get('identity') != identity:
-            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+            recorded = data.get('identity')
+            recorded = recorded if isinstance(recorded, dict) else {}
+            differing = ', '.join(f'{field}: {value}, record has {recorded.get(field)}'
+                                  for field, value in identity.items() if recorded.get(field) != value)
+            raise PolicyError(f'record belongs to another assignment or milestone/track/cycle ({differing})')
         if args.action == 'release':
             if data is None or not args.terminal_result:
                 raise PolicyError('release requires an existing record and terminal-result evidence')

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

@@ -119,6 +119,9 @@ as stated in Lookahead mode.
      in the same wave. Same-wave tasks may share files only when one
      transitively depends on the other through `deps`; the build executes
      them in dependency layers.
+   - Require an optional `supersedes` field to be a list of different task
+     ids; each one names an existing task of an earlier wave, in the same
+     repo, that shares a declared file with the task.
    - Reject a declared dependency that carries neither data nor a prerequisite
      effect. A `deps` edge is valid only when the dependent consumes a symbol,
      signature, schema, endpoint, file format, or path named in that

package/skills/gsd-path-plan/references/build-recovery.md

@@ -69,6 +69,19 @@ checks landed-task preservation and restored intent ownership, restores review
 evidence only for unchanged contracts, and creates the normal journaled plan
 checkpoint. A failed approval leaves recovery open.
 
+A wave keeps its review evidence when INTENT.md, its own `## Wave N` section,
+its task files, and every other non-wave PLAN.md section are byte-identical to
+the recovery base. Two edits are exempt: the value of the `max_review_cycles`
+and `wave_budget` lines in `## Config`, and all of `## Dependency notes`. In
+`## Config` only those two values may change; any other edit there, a comment
+edit included, drops the evidence of every wave, as does any other non-wave
+edit. A `- review_panel:` line that is added, removed, or changed anywhere in
+PLAN.md also drops the evidence of every wave. The approval result reports
+this in `recovery_reviews`: `restored` lists the waves that kept their evidence, and
+`review_again` lists each wave that lost it, with the reason. Review every
+`review_again` wave again after build resumes; completion refuses a wave
+without a passing review.
+
 Return through `plan/done → build/active` with event `build started`. The dispatch
 driver uses a separate record directory for this recovery base, while retaining
 the milestone budget ledger. Resume only from the new approved task inventory.

package/skills/gsd-path-plan/references/operating-rules.md

@@ -38,8 +38,8 @@ bundles this file; spawned agents follow their role brief instead.
   the lookahead planning track for the next milestone; it follows the same
   marker rule, owns no task frontmatter, and never binds a branch.
 - STATE.integration_default is the project closeout choice and
-  STATE.integration is the current milestone choice. Both are `direct` or
-  `pull-request`; STATE.integration_source is `default` or `milestone` and
+  STATE.integration is the current milestone choice. Both are `direct`,
+  `pull-request`, or `external-landing`; STATE.integration_source is `default` or `milestone` and
   preserves explicit override provenance. Older v2 state defaults to `direct`,
   and modes may be changed only through `pipeline_state.py
   configure-integration` before build. A next milestone resets its current
@@ -82,7 +82,9 @@ bundles this file; spawned agents follow their role brief instead.
   `isolation.py attest` may stand in for it: one `.project/`-only commit that
   names the base, the attested HEAD, the declared files that changed, the
   task Verify recorded as passing at that HEAD, and the ruling verbatim.
-  `recover` reports it as `attested`, never as a proven landing.
+  `recover` reports it as `attested`, never as a proven landing. Attestation
+  matches the declared files literally: work that is only below a declared
+  directory can land but cannot be attested.
 - All pipeline work for a milestone lives on `gsd-path/M00N` (M001, M002,
   …) bound in STATE.branch. The next milestone binds a new unused
   `gsd-path/M00N` at the remote default after the previous ship integrates.
@@ -90,6 +92,12 @@ bundles this file; spawned agents follow their role brief instead.
   branch — either Path's direct merge or a Path-owned PR merged by the user.
   The bound branch never receives merges or back-merges and is never the
   GitHub default.
+- The default branch is the one that STATE `default_branch` records at
+  initialization; a STATE file without the field means `main`. `main` and
+  `origin/main` in these rules mean that branch. Never change the record and
+  never take the name from a later `origin/HEAD` lookup. For a member
+  repository, the branch is the one that its `.project/MEMBERS.md` section
+  records as `Default branch`; a section without the field means `main`.
 - After initialization writes STATE.md, and before entering the first pipeline
   phase in an existing Git repository, the router calls
   `scripts/pipeline_git.py bind-initial` with the selected M00N and exact

package/skills/gsd-path-plan/references/planner.md

@@ -83,7 +83,7 @@ plan order above, which still keeps plan-invalidating risk in wave 1.
   owning task's Approach.
 - Make `files` exhaustive, including imports, routes, generated artifacts,
   tests, and wiring. Require disjoint files for same-wave tasks that are not
-  dependency-ordered.
+  dependency-ordered. A declared directory overlaps every path below it.
 - Write an Interface contract in every task: `None` for independent tasks;
   for any tasks that exchange a symbol, signature, schema, endpoint, file
   format, or path, the exact shapes both sides code against — identical text
@@ -96,6 +96,18 @@ plan order above, which still keeps plan-invalidating risk in wave 1.
   this task's work is skipped. That command must name a path from `files`,
   and must not be PLAN.md's project Verify unless an SC this task owns names
   that command. Criteria and Verify are the contract; Approach is guidance.
+  A task that lists a file of an earlier-wave task must also pass that
+  task's Verify to land. When it changes that behavior on purpose, list the
+  tests that Verify runs in its `files`.
+- Add `supersedes: [<task id>]` only when INTENT.md requires this task to
+  remove or replace behavior of an earlier-wave task, and that task's Verify
+  cannot pass after the change. The named task must be in an earlier wave,
+  in the same repo, and share a file with this task. Its Verify is then
+  retired: it does not run at this landing or at a later landing. State the
+  replacement in this task's acceptance criteria. This task's Verify then
+  runs in its place for each later task that shares a file with the named
+  task, so it must check the replacement behavior for all files of that
+  task.
 - In a multi-repo milestone (`.project/MEMBERS.md` lists members), each task
   changes exactly one repo. Give a member task `repo: <member>`; its `files`
   and Verify are relative to that member's root, and its Verify runs there.

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

@@ -20,6 +20,15 @@ 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.
+
 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.