@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/gsd-path/ROADMAP.md

@@ -27,7 +27,8 @@ return to `$gsd-path` for ownership checking. Legal entry is
 yet, `roadmap/active|blocked`, or a
 milestone-boundary re-slice: `inspect/active` or `define/active` with no
 approved INTENT.md for the next milestone and a user request to re-scope the
-remaining `pending` entries,
+remaining `pending` entries or, at `define/active` only, to change the scope
+of the `active` entry,
 or `roadmap/active` with STATE.milestone null and an `abandoned` entry in
 ROADMAP.md (the post-abandon re-slice the build orchestrator hands off).
 Enter from `decide/done` only with `pipeline_state.py transition`, exact
@@ -35,6 +36,8 @@ expected phase/status/milestone/branch/archive fields, event `roadmap started`,
 and `--set-phase roadmap --set-status active`; never edit STATE directly. In a
 milestone-boundary re-slice, preserve the entering `inspect/active` or
 `define/active` state throughout the re-slice.
+A `define/active` state that the router reports in `corrections` mode already
+has an approved INTENT.md; it blocks.
 Any later phase blocks; mid-milestone
 re-scope is never legal — finish or ship the active milestone first. A
 `decide/done` state with ROADMAP.md already present is milestone-scope decide;
@@ -71,8 +74,11 @@ precondition fails.
    give `.project/ROADMAP.before-reslice.md` with the instruction to preserve
    `shipped` entries byte-for-byte except Status/Archive/Integrated fields and
    to never modify `abandoned` entries at all. For a milestone-boundary
-   re-slice, also preserve the existing `active` entry byte-for-byte; only
-   `pending` entries are in scope.
+   re-slice entered at `inspect/active`, also preserve the existing `active`
+   entry byte-for-byte; only `pending` entries are in scope. Entered at
+   `define/active`, the `active` entry may also change as the user ruled, but
+   its heading (id and slug) and its Status, Depends on, Archive, and
+   Integrated fields stay unchanged.
    The output is exactly `.project/ROADMAP.md` — no other location is
    canonical.
 3. Gate ROADMAP.md:
@@ -96,8 +102,11 @@ precondition fails.
    - On a re-slice, `shipped` entries differ from
      `.project/ROADMAP.before-reslice.md` only in Status/Archive/Integrated;
      `abandoned` entries are byte-for-byte identical.
-   - On a milestone-boundary re-slice, the prior `active` entry is byte-for-byte
-     identical to `.project/ROADMAP.before-reslice.md`.
+   - On a milestone-boundary re-slice entered at `inspect/active`, the prior
+     `active` entry is byte-for-byte identical to
+     `.project/ROADMAP.before-reslice.md`. Entered at `define/active`, it
+     stays the only `active` entry and keeps its heading and its Status,
+     Depends on, Archive, and Integrated fields.
 4. Redispatch one complete corrected brief under logical task name `roadmap`,
    following the runtime dispatch contract and including all gate failures.
    Allow one revision round. If it still fails, keep the entering
@@ -160,7 +169,8 @@ precondition fails.
 
    The helper owns roadmap selection, expected state, baseline cleanup and
    the approval checkpoint. It journals before mutation, retains the baseline
-   bytes for recovery, and refuses changes to settled or active entries.
+   bytes for recovery, and refuses changes to settled entries and every
+   `active` entry change that step 2 does not permit.
    A milestone-boundary re-slice retains Inspect or Define; a post-abandon
    re-slice enters Inspect. Require its typed result to report `status:
    approved`, the requested kind, milestone and returned commit. After an

package/skills/gsd-path/SHIP.md

@@ -159,7 +159,12 @@ so the position is unchanged. Then:
    then stop and do not invent a patch finding. A `not-met`,
    `unverifiable`, or blocked gap with valid evidence sets `ship/blocked`,
    writes `.project/review/PATCH-FINDINGS.md` from the patch-findings template,
-   and runs `python3 <absolute check_handoffs.py> patch --repo <absolute repo
+   copying the full `Risk: ...` line into each gap finding's Locator, its
+   `Found` field into Evidence, and its `Fix direction` field verbatim. For a
+   `FINAL.md` finding, use its `SC<n>` id as Locator and copy its `Finding` and
+   `Fix direction` fields verbatim. The patch validator requires these source
+   field values to match exactly; do not shorten or paraphrase them. Run
+   `python3 <absolute check_handoffs.py> patch --repo <absolute repo
    root>`. Present the blocked outcome, link the resolved absolute
    PATCH-FINDINGS.md path, and state that patch planning is next. The manifest
    contains exactly those FINAL.md and gap rows. When routed by an active
@@ -262,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.
@@ -305,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,
@@ -339,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
@@ -349,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

@@ -24,6 +24,14 @@ python3 <absolute dispatch_driver.py> round --repo <absolute primary> --wave <N>
   [--child-timeout <owner seconds>]
 ```
 
+Use the absolute `dispatch_driver.py` from the active installed
+`gsd-path-build` skill when orchestrating a consuming project's build; that
+copy resolves role briefs and templates from its own skill bundle. The
+repository or npm package also supports the top-level `scripts/dispatch_driver.py`:
+when a default is not beside that script, it resolves from the shipped
+`skills/gsd-path` bundle. Explicit `--role-brief`, `--task-template`, and
+`--template` paths override those defaults and must name existing files.
+
 `round` owns the entry transition described in Preconditions and branch
 binding, checkpointed as `build: start milestone`, and sets `build/blocked`
 on a dependency deadlock or a blocked
@@ -120,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.
@@ -134,8 +146,27 @@ 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
+   gates later waves: `ready` selects unfinished later tasks with a `## Review
+   findings` section that depend on it, sets `current_wave` to the earliest
+   repair wave, and adds `repair_for_wave` with the source wave. When no such
+   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>
@@ -196,7 +227,7 @@ dispatch contract and perform steps 1–5 by hand.
    a later round unlocked by fresh landings records the later HEAD — and
    lint every ready task's brief with the bundled
    `scripts/check_task_briefs.py --repo <absolute repo root> --base <recorded
-   base>` and re-check Intent coverage with
+   base> --project-dir <routed project dir>` and re-check Intent coverage with
    `python3 <absolute check_handoffs.py> plan --repo <absolute repo root>`
    before creating any worktree; a lint or coverage failure is a documented plan
    defect — repair it against INTENT.md and SYNTHESIS.md, then re-establish
@@ -248,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
@@ -274,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.
@@ -488,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/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

package/skills/gsd-path/references/docs-auditor.md

@@ -59,6 +59,11 @@ actually does. Read-only: change nothing outside your single output file.
 5. **Classify remediation** for every non-verified claim: `fix-doc`,
    `fix-code`, or `NEEDS-USER` when the right side of the conflict is not
    yours to decide.
+   Number queue rows with unique, strictly increasing positive integers; they
+   need not be contiguous. A row that persists from the prior audit keeps its
+   number. A new row takes a number greater than every prior queue number and
+   every `## User rulings` Queue #. Never reuse a retired number: a ruling
+   stays bound to the item it was made for.
 
 ## Rules
 

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