@opengsd/gsd-path 1.5.0 → 1.6.0

package/skills/gsd-path/SHIP.md

@@ -267,7 +267,11 @@ The persisted `STATE.archive` field is the transaction identity.
    `python3 <absolute archive_milestone.py> close-members --repo <root>`
    after preflight passes and before recording shipment. It closes each
    locked member in lock order in that member's integration mode and
-   journals each one. When it returns `awaiting-merge`, report the member PR
+   journals each one. Each member closes onto the default branch that
+   MEMBERS.md records for it (`main` when its section has no
+   `Default branch`); when the command reports
+   `remote default must be <recorded>`, stop and report it. When it returns
+   `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.
@@ -310,8 +314,10 @@ The persisted `STATE.archive` field is the transaction identity.
    milestone is not shipped until integration below passes.
 7. Integrate only after the postcommit `validate` passes, with the recorded
    ship commit and exact reviewed HEAD unchanged. Run `python3 <absolute archive_milestone.py> integrate --repo <root> --slug <STATE.milestone>`.
-   This helper validates the ship commit, fetches origin, requires remote
-   default `main`, and follows the locked `STATE.integration` mode:
+   This helper validates the ship commit, fetches origin, requires the remote
+   default to equal STATE `default_branch` (`main` when the field is absent),
+   and follows the locked `STATE.integration` mode. `main` and `origin/main`
+   below mean that recorded branch:
 
    - `direct` owns the resumable merge transaction. It creates the canonical
      named integration worktree, performs the hook-verified `--no-ff` merge,
@@ -344,6 +350,22 @@ The persisted `STATE.archive` field is the transaction identity.
      landing SHA. A closed unmerged PR, squash, rebase, merge queue, moved
      head, duplicate PR, or non-GitHub.com origin blocks. The remote bound
      branch may be absent after a valid merge because GitHub may auto-delete it.
+   - `external-landing` is for an origin where Path cannot open the review
+     itself, such as GitLab, Gitea, or GitHub Enterprise Server. It needs no
+     forge CLI. The helper publishes the bound branch at the exact ship commit,
+     never pushes `main`, and returns `status: awaiting-merge` with `branch`,
+     `merge_subject`, and `merge_body`. Present **Outcome**, and state in
+     **Next** that the user must open a merge request from `branch` to `main`
+     in their own forge and merge it with a merge commit. The merge commit
+     message must be exactly `merge_subject`, a blank line, then `merge_body`;
+     show both values verbatim in a code block. Stop this ship invocation;
+     Path never opens or merges the request. The forge may delete the source
+     branch after the merge. On rerun after the merge, the helper requires exactly
+     one commit with that subject on `origin/main` first-parent history, that
+     exact body, and two parents with the ship commit as second parent. It
+     then writes and pushes the annotated milestone tag containing the ship
+     SHA and landing SHA. A squash, rebase, fast-forward, or different merge
+     message blocks.
 
    A passing run returns the same proof exposed by `validate-integrated`.
    A non-zero result blocks; rerun the exact `integrate` command to resume a
@@ -354,7 +376,7 @@ The persisted `STATE.archive` field is the transaction identity.
    continuing. Never merge into or re-ship the closed branch.
    For a later validation recheck with origin network access, run
    `python3 <absolute archive_milestone.py> validate-integrated --repo <root> --slug <STATE.milestone>`.
-   Both integration modes refresh the remote-default and mirrored milestone-tag
+   All integration modes refresh the remote-default and mirrored milestone-tag
    refs when an `origin` remote exists. Without that remote, validation resolves
    the existing remote-default refs locally, preserving offline direct-mode
    fixtures. PR mode also revalidates the PR identity, state, merge provenance,

package/skills/gsd-path/SKILL.md

@@ -179,6 +179,23 @@ selects a milestone branch.
      `define/active`; report that no brownfield signal fired, and route to
      the bundled [define contract](DEFINE.md).
 
+## Default branch
+
+`initialize` records the default branch of `origin` one time, as STATE
+`default_branch`. It reads the local `refs/remotes/origin/HEAD`; when that ref
+is unset it records `main`. When the repository has an `origin`, run
+`git remote set-head origin --auto` before `initialize`, so that the record is
+the default branch of the forge. A STATE file without the field means `main`.
+
+`<default_branch>` in the commands below is the `default_branch` value in the
+`validate`, `route`, and `status` JSON, beside `state`. Never edit the field,
+and never take the name from a later `origin/HEAD` lookup. When a helper
+reports that the remote default differs from the recorded one, stop and report
+it. In a project with members, STATE `default_branch` is the default branch of
+the coordinator only. `members.py add` records the default branch of each
+member in `.project/MEMBERS.md`; the member helpers read that record. The
+names can differ.
+
 ## Integration choice
 
 New state uses the user shipping default (built-in: `direct`) for
@@ -190,7 +207,7 @@ helper; never edit these fields by hand:
 python3 <absolute-bundled-pipeline-state.py> configure-integration \
   --repo <absolute-root> \
   --scope <default-or-milestone> \
-  --mode <direct-or-pull-request>
+  --mode <direct|pull-request|external-landing>
 ```
 
 `default` changes the project setting and changes the current milestone only
@@ -212,16 +229,23 @@ milestone boundary, never during build or ship. Resolve the bundled
 `scripts/members.py` to an absolute path and use it; never edit MEMBERS.md
 or a member marker by hand.
 
-- To add an existing repository, it needs a GitHub.com `origin` whose default
-  is `main`, a clean worktree, and no active milestone of its own. Ask for the
-  member name, checkout path, and integration (`direct`, `pull-request`, or
-  `default`, which follows the milestone's choice), then run
+- To add an existing repository, it needs a GitHub.com `origin`, a clean
+  worktree, and no active milestone of its own. Its default branch can have
+  any name. Run `git remote set-head origin --auto` in the member first: `add`
+  reads the member's local `origin/HEAD` one time and records the name in
+  MEMBERS.md as `Default branch`; an unset `origin/HEAD` records `main`. Ask
+  for the member name, checkout path, and integration (`direct`,
+  `pull-request`, or `default`, which follows the milestone's choice), then run
   `python3 <members.py> add --repo <absolute-root> --name <name> --checkout <path> --integration <mode>`.
+  When `validate` or member close later reports
+  `remote default must be <recorded>`, stop and report it; never edit the
+  record.
 - To create a new member repository, present the exact `owner/name`,
   visibility, and checkout path as the **Review** surface and get approval
   first, as for a new GitHub repository. Then run the same command with
   `--create <owner/name> --visibility <visibility>`. It journals the approved
-  target before creating anything; rerun the identical command to resume.
+  target before creating anything; rerun the identical command to resume. A
+  new member repository uses `main`.
 - After adding a member, tell the user to install its guard hooks:
   `npx @opengsd/gsd-path@latest --member-of <absolute-root> --project <member checkout>`.
 - `python3 <members.py> validate --repo <absolute-root>` checks every member;
@@ -269,8 +293,8 @@ integration ancestry, cleanliness, and journal ownership before continuing.
 After it returns, continue the state transition or lookahead promotion below.
 Do not reconstruct this classification from Git output or Log prose.
 When the route returns `allow_remote_absent: true`, also pass
-`--allow-missing-previous`; this is valid only because a merged PR may have
-auto-deleted the published bound branch.
+`--allow-missing-previous`; this is valid only because the forge may have
+auto-deleted the published bound branch after the merge.
 
 Before ordinary routing, inspect `STATE.archive`.
 
@@ -328,7 +352,7 @@ promotion, `resume-next-handoff` resumes the verified `bind-next` transaction,
 `resume-undo` invokes `$gsd-path-undo` with the returned kind and expected HEAD,
 `block` stops with the returned reason. `bind-initial`
 means initialization is complete and phase work must wait for the initial
-router binding: resolve the exact fetched `origin/main` SHA, call `bind-initial` as
+router binding: resolve the exact fetched `origin/<default_branch>` SHA, call `bind-initial` as
 above with `route.branch`, then persist its returned branch with
 `pipeline_state.py transition` using the route result's `state` phase and status plus its
 null branch and archive as expected fields. Set `--set-branch` to the helper's
@@ -371,7 +395,8 @@ on `NEEDS-USER`. Planning owns the single build-approval gate; never ask a
 second time. One user-driven exception to normal routing: at a program milestone
 boundary — `inspect/active` or `define/active` with no approved INTENT.md for
 the next milestone — a user request to re-scope the remaining `pending`
-entries routes to the bundled [roadmap contract](ROADMAP.md) in re-slice mode.
+entries, or at `define/active` the `active` entry, routes to the bundled
+[roadmap contract](ROADMAP.md) in re-slice mode.
 
 ## Lookahead planning (program flow)
 
@@ -400,7 +425,9 @@ template](templates/state.md) with `pipeline: gsd-path/v2`, `phase:
 inspect`, `status: active`, the selector's exact returned `milestone` slug as
 `milestone`, `branch: null`, and `archive: null`. Copy the active project's
 `integration_default` into both integration mode fields and set
-`integration_source: default`. Then follow the bundled
+`integration_source: default`. Set `default_branch` to the active project's
+value; when the active STATE.md has no `default_branch` line, delete that line
+from the new file. Then follow the bundled
 phase contracts in their Lookahead mode — inspect, define (milestone +
 brownfield), research (only when the entry lists open questions), decide, and
 plan — rooted at `.project/next/`.
@@ -424,14 +451,14 @@ bundled integration check (`validate-integrated`); pending integration routes
 back to ship, never here. Preserve the previous archive path, ship SHA,
 integration SHA, and build branch in the state Log. Before fetching or binding
 the next program branch, fetch origin and resolve the exact current
-`origin/main` SHA. For a program roadmap, resolve the branch from that exact
+`origin/<default_branch>` SHA. For a program roadmap, resolve the branch from that exact
 fetched commit through the bundled helper. With a saved lookahead track, run:
 
 ```text
 python3 <absolute-bundled-promote-lookahead.py> select-base \
   --repo <absolute-primary-root> \
-  --base <exact-origin-main-sha> \
-  --remote-default origin/main \
+  --base <exact-remote-default-sha> \
+  --remote-default origin/<default_branch> \
   --lookahead
 ```
 
@@ -440,8 +467,8 @@ Without a saved lookahead track, run:
 ```text
 python3 <absolute-bundled-promote-lookahead.py> select-base \
   --repo <absolute-primary-root> \
-  --base <exact-origin-main-sha> \
-  --remote-default origin/main
+  --base <exact-remote-default-sha> \
+  --remote-default origin/<default_branch>
 ```
 
 When the helper returns `status: complete`, report program completion and stop;
@@ -457,21 +484,22 @@ python3 <absolute-bundled-pipeline-git.py> bind-next \
   --branch <selected-branch> \
   --previous-branch <STATE.branch> \
   --ship <exact-ship-sha> \
-  --remote-default origin/main \
-  --base <exact-origin-main-sha> \
+  --remote-default origin/<default_branch> \
+  --base <exact-remote-default-sha> \
   --landing <validate-integrated-landing-sha>
 ```
 
 Add `--allow-missing-previous` when `validate-integrated` returned
-`mode: pull-request` and `origin/<STATE.branch>` is absent. GitHub may delete
-that head branch after merge; the local branch and exact ship SHA still bind
-the handoff. The helper independently verifies the published pull-request
-milestone tag and merge topology before accepting the missing branch.
+`mode: pull-request` or `mode: external-landing` and `origin/<STATE.branch>`
+is absent. The forge may delete that source branch after merge; the local
+branch and exact ship SHA still bind the handoff. The helper independently
+verifies the published milestone tag for `STATE.integration` and the merge
+topology before accepting the missing branch.
 
 The helper requires the previous branch, while it still exists locally, to
 remain at the ship SHA, proves the ship commit is integrated into the exact
 base, rejects local or remote branch collisions,
-and switches the clean primary worktree without tracking main. It then
+and switches the clean primary worktree without tracking the default branch. It then
 retires the integrated previous branch — deleted locally and on origin; the
 ship commit stays reachable from the integration merge and its tag. Repeating the
 same command while the new branch is current at the unchanged base is the
@@ -488,7 +516,7 @@ Log, then:
     --repo <absolute-primary-root> \
     --milestone <next-slug> \
     --branch gsd-path/M00N \
-    --base <exact-current-origin-main-sha> \
+    --base <exact-current-remote-default-sha> \
     --landing <exact-milestone-merge-sha>
   ```
 

package/skills/gsd-path/references/build-native.md

@@ -128,6 +128,10 @@ dispatch contract and perform steps 1–5 by hand.
        rerun `recover`. The original lineage must stay reachable: keep a local
        branch on the old tip until the milestone ships. Adopted tasks report
        `attested` with `provenance: owner-authorized-rebase`.
+   - `block` with a `leftover` path: the task is landed, and that path is what
+     a failed removal left of its isolate; it holds nothing that Git does not
+     have. Do not set `build/blocked`. Stop with the returned reason; after
+     the path is removed, rerun `recover`.
    - `block` for any other reason: set `build/blocked` with the returned
      reason and stop.
    - `none`: take no recovery action for that task.
@@ -142,6 +146,13 @@ dispatch contract and perform steps 1–5 by hand.
    order, or overlap-check tasks in prose. Readiness is continuous, not
    layered: a task becomes selectable the moment its last dependency lands,
    even while unrelated tasks still run, so rerun `ready` after each landing.
+   Two tasks that each share a file with the same `done` task of an earlier
+   wave never run together: `ready` returns one and holds the other until the
+   first is `done`. The second then starts from a base that has the first
+   landing, and the step 5 rerun of the earlier Verify checks both edits. A
+   task with a retained isolate keeps its turn. A task that a `supersedes`
+   field retires still counts: the superseding task never runs together
+   with a task that shares a file with the superseded task.
    A `NEEDS-ORCHESTRATOR` block stays unselectable until its `Orchestrator
    answer` is recorded in the task Log and the task is back to `pending`.
    An all-done wave whose latest canonical review cycle has any blocked lens
@@ -151,6 +162,11 @@ dispatch contract and perform steps 1–5 by hand.
    repair remains, `ready` returns no tasks and adds `blocked_review` (`wave`,
    `cycle`, `waiting_waves`); a later passing canonical review cycle releases
    the waiting waves.
+   `unreviewed_waves`, when present, lists earlier waves whose tasks are all
+   `done` and that have no canonical review file. A repair wave is not
+   listed: the next review cycle of its source wave judges it. `ready` reports
+   the listed waves and does not hold the returned tasks: run step 6 for each
+   listed wave before you dispatch.
    Its typed errors are the recovery rule:
    - `task-recovery-required`: for each listed failed or blocked task run
      `python3 <absolute build_state.py> reconcile --repo <absolute primary>
@@ -263,7 +279,8 @@ dispatch contract and perform steps 1–5 by hand.
    defective task contract before establishing the round base. Run ready work
    up to capacity. Verify commands marked `Heavy: yes` (`verify_heavy` in the
    ready set) run one at a time across every concurrent task, including the
-   step 5 rerun; light ones are unconstrained. Do not wait for the whole
+   step 5 rerun; light ones are unconstrained. `verify_heavy` is also true
+   when step 5 reruns a heavy Verify of an earlier task. Do not wait for the whole
    round before unlocking dependents: each task landing in step 5 re-opens
    step 2, and a newly ready
    task dispatches in a fresh round at the current clean HEAD while unrelated
@@ -289,8 +306,35 @@ dispatch contract and perform steps 1–5 by hand.
      native child tools; no child command is needed. It reproduces serial work
      in its prepared sidecar, runs authoritative Verify, records exact output,
      lands through `isolation.py`, records eligible ledger evidence, and retires
-     the isolate. A `landed` receipt proves those steps; do not run them again
-     or author another implementation narrative. A blocked receipt preserves
+     the isolate. Authoritative Verify is the task's own Verify, then the
+     Verify of each `done` task of an earlier wave, in the same repo, that
+     shares a declared file with this task. `finish` selects those commands;
+     never select them by hand. An earlier command does not run again in two
+     cases only: it is identical to the own Verify, or the own Verify is the
+     unchanged Verify that `fix-tasks` wrote from the task's `deps` and the
+     command belongs to one of them. A Verify that only contains the command
+     text does not replace the rerun. A failed earlier-task Verify blocks the landing as a
+     failed own Verify does. The receipt (`regressions`) and the task Log
+     entry `orchestrator regression Verify of <task id>` name the earlier
+     task. The ledger records only the own command.
+     A plan-approved `supersedes` field retires the Verify of each earlier
+     task that it names: `finish` does not run that Verify for the task, or
+     for a task that lands after the task is `done`. The receipt (`retired`)
+     and the task Log entry `orchestrator regression Verify of <task id>
+     retired: superseded by <task id>` name both tasks. When the generated
+     Verify of a fix task loses only the copy of a retired Verify, the
+     `retired` entry has the key `part` and the Log entry is `orchestrator
+     regression Verify of <fix task id>: part of <task id> retired:
+     superseded by <task id>`. The superseding
+     task inherits the role of each task that it names, also through a
+     chain: after it is `done`, its Verify runs in the place of the retired
+     Verify for each later landing that shares a file with a superseded
+     task, also in its own wave. The Log entry is `orchestrator regression
+     Verify of <task id> (supersedes <task id>)`.
+     A `landed` receipt proves those steps; do not run them again
+     or author another implementation narrative. A `cleanup_warning` on a
+     landing means only that the isolate was not removed: the task is landed,
+     and the next `round` or `finish` checks the isolate again. A blocked receipt preserves
      its failure evidence and follows the recovery rule, never a manual bypass.
      Keep the pre-finish declared-path check above. Each landing re-opens step 2
      so ready dependents can run while unrelated children remain in flight.
@@ -503,26 +547,69 @@ dispatch contract and perform steps 1–5 by hand.
      again.
    - Otherwise batch `fix_batches` into complete fix tasks from the task
      template — one task per batch, never one per finding — each carrying
-     its groups' failed criteria and observed evidence verbatim. A group
+     its groups' failed criteria and observed evidence verbatim. Each batch
+     is in one repo: a batch with `repo` is for that member and its fix task
+     has `repo: <member>`; a batch without `repo` is for the coordinator. A
+     finding whose source tasks are in two repos gives one batch for each
+     repo. A group
      with `repeat` true is evidence its earlier fix failed, never a new
      finding; a re-review never spawns a duplicate fix task for a finding
-     already carried. Write each fix task to `.project/tasks/` with `wave`
+     that a fix task not yet `done` already carries in the same repo. A
+     repeat after its fix
+     landed gets the next fix task. After a build recovery, a changed wave
+     is reviewed again from cycle 1; the fix tasks and PLAN.md repair wave
+     of the review that recovery set aside do not count for the new one.
+     Write each fix task to `.project/tasks/` with `wave`
      set to the current wave or a newly appended `## Wave N` heading in
-     PLAN.md before dispatch. Its dependencies include every source task in
-     the batch; its files match the batch. In `## Review findings`, use one
+     PLAN.md before dispatch. Its dependencies include every source task of
+     the batch that is in the same repo, and every landed fix task of the
+     same source wave and repo that carried one of its findings; its Verify
+     runs the Verify of those source tasks; its files are the batch files or a subset of them, never
+     none. When a finding names a fix site outside the batch files, follow
+     [build recovery](build-recovery.md) to plan, which adds a repair task
+     with those files, the batch's `## Review findings` and the same
+     dependencies; `repair-evidence` accepts that task. In
+     `## Review findings`, use one
      `### <locator>` block per group, `Criterion: <verbatim criterion>`, and
      every observation verbatim. Run the repair through the same isolated
      layer loop, even when its appended wave repairs an earlier blocked wave.
+     An appended repair wave has the highest wave number and still runs before
+     the pending waves, because `ready` gates them on the blocked wave (step
+     2). Do not renumber waves or move the repair wave.
      After landing, call `review_findings.py repair-evidence --repo <primary>
      --wave <source wave> --cycle <source cycle> --task <repair id>` and save
-     its JSON as the repair evidence for the next review. The helper validates
+     its JSON as the repair evidence for the next review. The helper selects
+     the batch by the repair's locators and repo, then validates
      the carried batch, original and repair landings, isolated product scope,
-     unchanged source reports and reusable Verify. On success, brief the next
+     unchanged source reports and reusable Verify. For a member repair it
+     checks the product in the member repository, against the member commits
+     and the member Verify record, and the receipt adds `member`,
+     `member_base` and `member_commit`. Another change to the checked files
+     is accepted only when it is the landing of a linked repair: a `done`
+     task of the same repo that carries one of the repair's findings in
+     `## Review findings`, with the same locator and criterion, and is
+     joined to the repair by `deps`. A finding on an acceptance criterion of
+     a fix task counts as the finding that this fix task carries with the
+     same criterion; the same criterion text under another locator is
+     another finding. Linked
+     repairs in the repair base are in `earlier_repairs`. Linked repairs
+     after the repair are in `later_repairs`; then the landing and the
+     recorded Verify of the last one are the evidence, and `chain_files`
+     lists the files checked from the repair base to the tip: those of the
+     repair and of every later linked repair. From the repair base to the
+     parent of the repair landing, no landing can change these files, also
+     not a linked one. On success, brief the next
      original-wave review with this receipt and the reviewer role's
      **Re-review after a proven repair** contract. Reuse command evidence;
      the new review judges the repaired product against the original criteria.
      Preserve prior verdicts and source tasks. On helper rejection, resolve
      the evidence blocker rather than redispatching an already proven fix.
+     When the blocker cannot be resolved, for example `repair base contains
+     unlinked changes to original product` or `product changed after the
+     repair landing` because a task that is not a linked repair changed the
+     same files, run the next review cycle of the source wave in full at the
+     current HEAD, without the receipt. This is the supported fallback: it
+     needs no ruling and no plan change.
    At the cap, record all attempts in the STATE.md log and ask the user —
    through an interactive user-input tool when available — after linking
    the resolved absolute blocking wave review, every deep lens file for the

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

@@ -51,9 +51,13 @@ costs the run.
 2. Satisfy every acceptance criterion and every owned INTENT success
    criterion within the Approach constraints, matching conventions in the
    listed files.
-3. Edit only exact paths in `files`, plus the task file's Log. There is no
-   exception for imports, routes, generated files, or wiring.
-4. Run Verify. Fix failures only within the allowed paths.
+3. Edit only paths in `files`, plus the task file's Log. A declared
+   directory covers the files below it; a declared file covers only itself.
+   There is no exception for imports, routes, generated files, or wiring.
+4. Run Verify. Fix failures only within the allowed paths. The orchestrator
+   also runs the Verify of each earlier-wave task that shares a file with
+   yours. A Log entry `orchestrator regression Verify of <task id>` with
+   `fail` names a task you broke; make its Verify pass too.
 5. Append the implementation and Verify result to Log. On a block, append the
    specific reason. Do not edit frontmatter state.
 

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