@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/gsd-path/DECIDE.md

@@ -3,6 +3,8 @@ name: gsd-path-decide
 description: Decide implementation direction from approved intent and complete research evidence, recording settled choices in SYNTHESIS.md. Use only when the user explicitly invokes $gsd-path-decide or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Decide Phase
 
 Dispatch one reasoning-intensive decider and validate its decision artifact.
@@ -98,12 +100,8 @@ rules are unchanged; never write an active-path artifact.
    branch and archive values, `--set-phase decide --set-status done`, and an
    event naming the validated synthesis path. Include `--project-dir
    .project/next` in lookahead and require returned `decide/done`. Confirm the
-   settled outcome, link SYNTHESIS.md again, and name
-   the next phase: the roadmap phase in program scope, planning otherwise.
-   When routed by an active `$gsd-path`, return control to
-   that router. When invoked directly, stop and tell the user to explicitly
-   invoke `$gsd-path`, which routes to that next phase; do not invoke an
-   explicit-only sibling skill yourself.
+   settled outcome, link SYNTHESIS.md again, and use the executable phase
+   handoff in AGENTS.md.
 
 ## Rules
 

package/skills/gsd-path/DEFINE.md

@@ -3,6 +3,8 @@ name: gsd-path-define
 description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Define Phase
 
 Turn a project idea or approved roadmap entry into an approved intent artifact.
@@ -36,16 +38,22 @@ ROADMAP.md exists), `roadmap/done`
 lookahead track at `define/active|blocked` also requires both current-track
 inspection artifacts and a Log entry proving `inspect/done` for the same
 milestone after its latest activation; otherwise route to inspect.
+The sole later-phase exception is a blocked build entered through the
+[build recovery contract](references/build-recovery.md). Follow its preparation
+and corrections procedure when the runtime returns mode `corrections`; keep
+the existing milestone identity and approval gate. Otherwise
 `define/done` or any later phase blocks rather than overwriting approved
 intent and leaving downstream artifacts stale. When an active router supplies
 the lookahead track root `.project/next/`, require its STATE.md to be a regular
 non-symlink file and evaluate this section against that track's state and
 paths; see Lookahead mode. If STATE.md is missing, run the bundled
 `python3 <absolute-bundled-script> initialize --repo <absolute-root>
---template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+--template <absolute-state-template> --require-git` helper (`scripts/detect_project.py`) and
 follow its returned JSON `verdict` / `route`. This is the only no-state
 boundary; do not run `classify` first or classify from a directory listing or
-conversation. If the command exits nonzero, returns `error`, or returns
+conversation. Handle `route: setup-repository` before the write gate: preserve
+the folder unchanged and return to `$gsd-path` for repository setup; no state
+was written. If the command exits nonzero, returns `error`, or returns
 `wrote_state: false`, report the error and block without routing or claiming
 STATE.md was written.
 - `owned` — continue under the existing-state rules above.
@@ -104,12 +112,13 @@ the charter instead of the single-milestone checklist:
 4. **Constraints** — program-level stack, budget, deadline, integrations.
 5. **Program success criteria** — observable when the last milestone ships.
 6. **Review panel** — optional durable default (`off` | `detected` | named
-   families). Default `off`. This value persists on CHARTER.md; later
+   families). Use the configured future preference unless the user chooses
+   otherwise (see Output contract). This value persists on CHARTER.md; later
    milestone INTENT files copy it and may override.
 
 Read the local [charter template](templates/charter.md), write the approval
-draft to `.project/CHARTER.md` including `Review panel:` (default `off`;
-never invent `detected` or a named list), and run the same playback-approval
+draft to `.project/CHARTER.md` including the configured or explicitly chosen
+`Review panel:` value, and run the same playback-approval
 loop as the standard Process. On approval, retain the reviewed
 `Review panel:` value on CHARTER.md, run `pipeline_state.py transition` with
 expected `define/active`, milestone/branch/archive all at their exact current
@@ -138,7 +147,7 @@ State ownership. There is no re-interview of charter or roadmap scope:
    Risks and Open questions from the entry (tagged `RESEARCH`/`NEEDS-USER`),
    `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
    `Review panel:` copied from CHARTER.md (default
-   `off` when CHARTER omits it). The confirmation may override the copied
+   the configured preference when CHARTER omits it). The confirmation may override the copied
    panel value; do not invent `detected` or a named list. When brownfield,
    fill `## Current state` from the map, record doc-vs-code rulings as in
    Brownfield mode, and add protected existing behavior under Scope out.
@@ -265,27 +274,20 @@ question. The rules change for every primary mode:
 ## Output contract
 
 At approval, retain the already reviewed `Lane:` value and its one-line reason.
-Retain `Review panel:` as reviewed: the CHARTER copy or the user's override
-in milestone/lookahead mode, the CHARTER value in program mode, or `off`
-when the user did not choose a panel and no CHARTER default exists.
+Before presenting an approval draft without a CHARTER or explicit panel choice,
+read `settings.review_panel.value` from the selected runtime's `path_config.py
+show --repo <absolute-root>` (bundle for legacy projects; off for older selected
+runtimes without config support). Include that preference in the draft.
+Retain `Review panel:` as reviewed: the CHARTER copy, the explicit user choice,
+or the configured future preference. Quick lane keeps the panel off.
 
 After approval, finalize `.project/intent/INTENT.md` and run
 `pipeline_state.py transition` with expected `define/active`, the exact
 current milestone/branch/archive values, event `milestone intent approved`,
 `--set-phase define --set-status done --set-milestone <milestone slug>`, and
 `--project-dir .project/next` in lookahead. Require returned `define/done` and
-the exact milestone. Report the next phase
-from the approved lane. For `Lane: standard`, research is next. For
-`Lane: quick`, planning is next and research and decide are skipped. For
-`Lane: milestone`, use the resolved roadmap entry matching the track STATE's
-`milestone`: milestone-scoped research is next when that entry lists open
-questions; otherwise planning is next and research and decide are skipped.
-Confirm the approved outcome, link the final INTENT.md again, and name that
-next phase before routing. When routed by an active `$gsd-path`, return control
-to that router so its bundled next contract can auto-advance to the named
-phase. When invoked directly, stop and tell the user to explicitly invoke
-`$gsd-path`, which selects that next phase; do not invoke an explicit-only
-sibling skill yourself.
+the exact milestone. Confirm the approved outcome and link INTENT.md again.
+Use the executable phase handoff in AGENTS.md for the next action.
 
 ## Rules
 

package/skills/gsd-path/DOCS-AUDIT.md

@@ -3,6 +3,8 @@ name: gsd-path-docs-audit
 description: Verify Markdown claims against the actual code, commands, and GSD Path artifacts. Use only when the user explicitly invokes $gsd-path-docs-audit or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Docs Audit
 
 Answer one question with evidence: **does the project do what its documents

package/skills/gsd-path/INSPECT.md

@@ -3,6 +3,8 @@ name: gsd-path-inspect
 description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Inspect Phase
 
 Establish ground truth about an existing project before intent is defined.
@@ -21,10 +23,12 @@ phase blocks.
 
 If STATE.md is missing, run the bundled
 `python3 <absolute-bundled-script> initialize --repo <absolute-root>
---template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+--template <absolute-state-template> --require-git` helper (`scripts/detect_project.py`) and
 follow its returned JSON `verdict` / `route`. This is the only no-state
 boundary; do not run `classify` first or classify from a directory listing or
-conversation. If the command exits nonzero, returns `error`, or returns
+conversation. Handle `route: setup-repository` before the write gate: preserve
+the folder unchanged and return to `$gsd-path` for repository setup; no state
+was written. If the command exits nonzero, returns `error`, or returns
 `wrote_state: false`, report the error and block without routing or claiming
 STATE.md was written.
 - `owned` — continue under the existing-state rules below.
@@ -47,6 +51,31 @@ same milestone; a later milestone's `inspect/active` is a new scan.
 
 ## Process
 
+For an initial `inspect/active` inspection on the `.project` track, with neither output
+artifact present and a clean Git product at the recorded HEAD, run the bundled
+`python3 <absolute workflow_run.py> prepare-inspect --repo <absolute root>
+--expected-head <recorded HEAD>` first. It performs the inventory freeze and
+both sidecar preparations from steps 1–2 and writes complete assignment briefs.
+Its state validation and pending-answer check satisfy those entry checks;
+reuse their results at this boundary.
+Use its returned `inspection.inventory_file` for the gate. Before dispatch, read
+and apply the [runtime dispatch contract](references/dispatch.md), including its
+host-specific context isolation. Dispatch each returned logical `task_name` in a fresh context with its `brief_file` path and the current
+user constraints, including configured budgets. The child reads that file;
+the parent does not read or rewrite the roles, templates, or generated briefs.
+When both children return, review the mapper's Map and Findings against its
+template as in step 3. After that review passes, run the bundled
+`python3 <absolute workflow_run.py> finish-inspect --repo <absolute root>
+--expected-head <recorded HEAD> --inspection <returned receipt_file>
+--mapper-reviewed`. This runs the docs gate, checks the audit baseline,
+collects and retires both sidecars, checks pending discussion, and records
+`inspect/done` through the canonical transition. Do not repeat those operations.
+Present step 4's ground truth and use step 5's caller handoff. A failure uses
+step 3's failure contract and the returned step evidence; do not blindly rerun
+the completion command or repeat already proven steps.
+Prior evidence, lookahead, or a dirty/non-Git product uses steps 1–2 below.
+Preparation never changes phase state; neither command dispatches agents.
+
 1. Before creating or changing `.project/` Markdown, freeze the helper's exact
    stdout from `python3 <absolute check_docs_audit.py> --repo <absolute root>
    --emit-inventory` in a temporary file. Do not rediscover or edit that
@@ -132,12 +161,7 @@ same milestone; a later milestone's `inspect/active` is a new scan.
    <current branch or null> --expect-archive <current archive or null>
    --set-phase inspect --set-status done`. This helper is the only ordinary
    STATE mutation; require its returned state to be `inspect/done`.
-   Identify `$gsd-path-define` as next. When this phase was routed by an
-   active `$gsd-path`, return control to that router so its bundled define
-   contract runs in brownfield mode (and milestone mode when ROADMAP.md
-   exists). When invoked directly, stop and tell the
-   user to explicitly invoke `$gsd-path`, which routes to define; do not invoke
-   an explicit-only sibling skill yourself.
+   Use the executable phase handoff in AGENTS.md.
 
 ## Lookahead mode
 

package/skills/gsd-path/PLAN.md

@@ -3,6 +3,8 @@ name: gsd-path-plan
 description: Create and validate dependency-ordered GSD Path build waves and complete task contracts. Use only when the user explicitly invokes $gsd-path-plan or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Planning Phase
 
 Dispatch one planner, gate its artifacts, and obtain the single approval that
@@ -29,8 +31,11 @@ Before dispatch, enter from `decide/done` or `define/done` with
 `--set-phase plan --set-status active`, and event `planning started`. Resume
 `plan/blocked` through the same helper with event `planning resumed`. Require
 the returned track state to be `plan/active`; never edit STATE directly.
-Any later phase blocks instead of replacing an approved plan. Patch mode is
-the only reopen exception: require an approved plan, no in-progress task, and
+For a blocked build, use the [build recovery contract](references/build-recovery.md).
+The runtime's `build-repair` mode owns structural changes to the remaining task
+inventory and the normal approval checkpoint; it is distinct from append-only
+patch mode. Otherwise later phases block instead of replacing an approved plan.
+Patch mode requires an approved plan, no in-progress task, and
 state `plan/done` or `ship/blocked`; any other state blocks. `build/done` is
 reserved exclusively for the build orchestrator's transition recovery and
 must return there instead of reopening planning. When an active router
@@ -74,10 +79,17 @@ router supplied lookahead mode. Every per-milestone path below, including
 review-panel evidence, is rooted there. Program inputs remain at `.project/`
 as stated in Lookahead mode.
 
-1. Read the local [plan template](templates/plan.md), [task template](templates/task.md),
-   [plan-panel template](templates/plan-panel.md), `scripts/check_handoffs.py`,
-   and `scripts/review_panel.py`; resolve them to absolute paths.
-2. Read the local [planner role](references/planner.md), then follow the
+1. Resolve the local [plan template](templates/plan.md), [task template](templates/task.md),
+   `scripts/check_handoffs.py`, and `scripts/review_panel.py` to absolute paths.
+   Quick mode reads the plan and task templates because the parent writes
+   those artifacts. Other modes pass their paths to the planner. Execute the
+   helpers through the commands below and consume their results; their Python
+   source is not planning input. Read helper source only when diagnosing a
+   concrete failure that the returned error and documented recovery cannot
+   explain.
+2. In quick mode, skip planner dispatch and follow Quick mode below; do not
+   load the planner role or dispatch contract. In other modes, resolve the
+   local [planner role](references/planner.md) for the child, then follow the
    local [runtime dispatch contract](references/dispatch.md) with deterministic
    logical task name `plan`. Give it absolute role, `AGENTS.md`, `WORKFLOW.md`,
    input, template, and output paths, including `.project/LESSONS.md` when it
@@ -133,7 +145,7 @@ as stated in Lookahead mode.
    - Require a `Review depth` value (`full`, `deep`, or `verify-only`) on
      every wave. Wave 1 and any wave touching authentication, authorization,
      payments, data migration, or concurrency requires `full` or `deep`;
-     quick-lane single waves may use `verify-only`. The planner assigns `deep`
+     this includes quick-lane single waves. The planner assigns `deep`
      sparingly to waves where a wrong merge is irreversible or
      security-critical.
    - When INTENT.md `Surfaces:` is not `none`, require a PLAN.md
@@ -199,11 +211,13 @@ as stated in Lookahead mode.
    - `status: error` or exit 2 — use the same guarded transition to set
      `plan/blocked` with an event naming the helper error, link PLAN.md, and stop.
      A named family that is not advertised is an assertion failure.
-   - `status: ready` — for each selected family, spawn one independent child
+   - `status: ready` — resolve the local
+     [plan-panel template](templates/plan-panel.md) for the reviewers; other
+     statuses do not load this template. For each selected family, spawn one independent child
      with logical task name `review_plan_panel_<family>`, the reviewer role
      in plan-panel mode, the plan-panel template, and the exact helper-returned
-     model slug when the host advertises model selection. Never override the
-     model on the planner. Each child stages its family file under a
+     model slug through the dispatch model-policy contract. Planner choices
+     use that same contract. Each child stages its family file under a
      disposable root; the parent validates and copies those files, removes
      any stale `<track>/review/PLAN-PANEL.skipped.json`, then runs
      `python3 <absolute review_panel.py> merge --kind plan --inputs <family
@@ -257,12 +271,8 @@ as stated in Lookahead mode.
    (event `patch plan approved`) without a plan checkpoint because build's
    patch re-entry commits the artifacts with its `build/active` transition.
    `pipeline_state.py transition` never approves a plan. Confirm approval,
-   link PLAN.md again, and state that
-   build starts next. Do not add another approval gate. When routed by an
-   active `$gsd-path`, return control to that router so its bundled build
-   contract starts. When invoked directly, stop and tell the user to explicitly
-   invoke `$gsd-path`, which routes to build; do not invoke an explicit-only
-   sibling skill yourself.
+   link PLAN.md again, and use the executable phase handoff in AGENTS.md.
+   The plan approval also authorizes build; do not add another approval gate.
 
 ## Ordering rules
 
@@ -273,8 +283,8 @@ as stated in Lookahead mode.
 ## Quick mode
 
 Legal entry: `define/done` where INTENT.md records `Lane: quick` (transition
-to `plan/active`, logging that research and decide were skipped for the
-quick lane). Quick mode dispatches no planner agent — the orchestrator writes
+to `plan/active` using exactly the Preconditions event `planning started`;
+record the skipped research and decide phases in the synthesis). Quick mode dispatches no planner agent — the orchestrator writes
 the artifacts directly:
 
 1. Write `.project/research/SYNTHESIS.md` containing only `## Settled` lines
@@ -282,7 +292,7 @@ the artifacts directly:
    plus a minimal `## For the planner` naming the walking skeleton. No
    invented decisions or runner-ups.
 2. Write `.project/plan/PLAN.md` with exactly one wave — `Review depth:
-   verify-only` permitted — and at most two deliverable-sized task files
+   full` or `deep` — and at most two deliverable-sized task files
    (project policy),
    honoring every task-contract rule above and `.project/LESSONS.md` when it
    exists. Write `review_panel: off` and `finding_skeptics: off` regardless

package/skills/gsd-path/RESEARCH.md

@@ -3,6 +3,8 @@ name: gsd-path-research
 description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Research Phase
 
 Dispatch independent researchers and gate their evidence. Keep synthesis out
@@ -143,12 +145,9 @@ settled brownfield input.
    dimensions, and question count. Include `--project-dir .project/next` for
    lookahead. Require the returned state to be `research/done`. Report the
    outcome, link the resolved absolute `RESEARCH.md` path,
-   summarize the dispatched evidence files, and name the decide phase as next.
-   The decide phase reads the manifest; it must not infer dispatch state from
-   a glob or free-form log. When routed by an active
-   `$gsd-path`, return control to that router. When invoked directly, stop and
-   tell the user to explicitly invoke `$gsd-path`, which routes to decide; do
-   not invoke an explicit-only sibling skill yourself.
+   summarize the dispatched evidence files, and use the executable phase
+   handoff in AGENTS.md. The next phase reads the manifest rather than
+   inferring dispatch state from a glob or free-form log.
 
 ## Rules
 

package/skills/gsd-path/ROADMAP.md

@@ -3,6 +3,8 @@ name: gsd-path-roadmap
 description: Slice an approved GSD Path program charter into a dependency-ordered roadmap of independently shippable milestones. Use only when the user explicitly invokes $gsd-path-roadmap or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Roadmap Phase
 
 Dispatch one roadmapper, gate its roadmap, and obtain the single approval that
@@ -143,69 +145,33 @@ precondition fails.
    retain the entering state for a milestone-boundary re-slice; otherwise keep
    `phase: roadmap`, `status: active`. Retain the baseline, revise, and re-gate
    against that same baseline.
-7. On approval in an established repository, record the exact full current
-   HEAD before changing ROADMAP.md or STATE.md. For a milestone-boundary
-   re-slice, keep its matching roadmap entry `active`, use `pipeline_state.py
-   transition` to record `program roadmap re-slice approved` while expecting
-   and retaining the complete entering `inspect/active` or `define/active`
-   state, then checkpoint the pending `.project/` artifacts with:
-
-   ```text
-   python3 <absolute isolation.py> checkpoint \
-     --repo <absolute root> --expected-head <recorded full HEAD> \
-     --subject "roadmap: program roadmap approved" \
-     --body "Why: approved roadmap checkpoint" \
-     --allow-path .project
-   ```
-
-   On a post-abandon re-slice, mark only the helper-selected pending entry
-   `active`, use `pipeline_state.py transition` with the complete current
-   `roadmap/active` state as expected to set `phase: inspect`, `status: active`,
-   `milestone` to the selected slug, preserve the bound branch, and set
-   `archive: null`, with an event naming the abandoned predecessor. Then use
-   the same `isolation.py checkpoint` command above. For a first roadmap
-   approval, run:
+7. On approval, record the full current HEAD and use the bundled approval
+   module. For a first roadmap approval use `--kind roadmap`; for either
+   re-slice use `--kind roadmap-reslice`. In a milestone-boundary re-slice,
+   `--milestone` is the unchanged active milestone; after abandon, it is the
+   helper-selected pending milestone reviewed by the user.
 
    ```text
    python3 <absolute pipeline_state.py> approve \
-     --repo <absolute root> --kind roadmap \
-     --milestone <selected first pending slug> \
-     --expected-head <recorded full HEAD>
+     --repo <absolute root> --kind roadmap-reslice \
+     --milestone <reviewed milestone slug> --expected-head <recorded full HEAD>
    ```
 
-   The helper journals before mutation, proves the selected entry is pending
-   and no entry is already active, marks it active, changes STATE from
-   `roadmap/active` to `roadmap/done` with that milestone and event `program
-   roadmap approved`, and checkpoints all pending `.project/` artifacts with
-   the canonical roadmap subject and body, subject to the
-   top-level allowlist in
-   [isolation.PROJECT_ENTRIES](scripts/isolation.py). Require its typed result to report
-   `schema: gsd-path/state-checkpoint/v1`, `status: approved`, `kind: roadmap`,
-   `project_dir: .project`, `state.status: done`, the selected milestone, and
-   the returned current commit. Rerun the same command after interruption; the
-   matching journal owns recovery.
-
-   For every re-slice, remove `.project/ROADMAP.before-reslice.md` only after
-   the state transition succeeds and before the checkpoint. Retain it through
-   every requested revision and failed approval attempt.
-
-   Defer either checkpoint only when the directory is not yet a Git repository
-   or `.project/REPOSITORY.md` records `Kind: new-github`. For a normal
-   approval, run the same `approve` command with `--defer-checkpoint` instead
-   of `--expected-head`; it marks the selected entry active and records
-   `roadmap/done` with event `program roadmap approved`. `pipeline_state.py
-   transition` never approves a roadmap. For
-   a milestone-boundary re-slice, use the retaining transition above; for a
-   post-abandon re-slice, use its transition above. The build transition
-   commit owns the pending artifacts. Confirm approval and link ROADMAP.md again. For
-   a milestone-boundary re-slice, state that the preserved inspect or define
-   phase resumes; for a post-abandon re-slice, state that inspect is next;
-   otherwise state that define (milestone mode) is next. Do not
-   add another approval gate. When routed by an active `$gsd-path`, return
-   control to that router so it routes the resulting state; never name define
-   as next when inspect was preserved or selected. When invoked directly, stop
-   and tell the user to explicitly invoke `$gsd-path`, which routes the same
-   result; do not invoke an explicit-only sibling skill yourself.
+   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.
+   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
+   interruption, follow the router's `resume-checkpoint` action; do not edit
+   state, delete the baseline or checkpoint separately.
+
+   Before Git exists, or during a `Kind: new-github` transaction, use the same
+   approval command with `--defer-checkpoint` instead of `--expected-head`.
+   That existing deferred path writes the metadata without a Git journal or
+   commit; the next build checkpoint owns it. Retain the baseline through
+   revisions and rejected approvals. Confirm approval, link ROADMAP.md again,
+   and use the executable phase handoff in AGENTS.md without another gate.
 
 ## Rules
 

package/skills/gsd-path/SHIP.md

@@ -3,13 +3,15 @@ name: gsd-path-ship
 description: Verify a completed GSD Path milestone, manage evidence-backed patch decisions, request final shipping approval, and archive the validated result. Use only when the user explicitly invokes $gsd-path-ship or an active $gsd-path router or build orchestrator explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Ship Phase
 
 Reuse proven review scope; dispatch reviewers for remaining claims. They never fix
 product code.
 
-Routing instructions below are caller handoffs under the AGENTS.md handoff
-rule; never invoke an explicit-only sibling skill yourself.
+After completion, use the executable phase handoff in AGENTS.md.
+Before completion, preserve the approval and recovery gates below.
 
 Require `pipeline: gsd-path/v2` in `.project/STATE.md`; a missing or different
 marker returns to `$gsd-path` for ownership checking. Read the local
@@ -174,8 +176,9 @@ so the position is unchanged. Then:
 
 ## Archive transaction
 
-Resolve the project's guard-owned `.gsd-path/runtime/archive_milestone.py` and
-`.gsd-path/runtime/pipeline_state.py` to absolute paths for `prepare`,
+Resolve the declared runtime with `python3 -B
+<project>/.gsd-path/status_runtime.py --repo <project> --runtime-path`; use
+`archive_milestone.py` and `pipeline_state.py` from that verified directory for `prepare`,
 `render-manifest`, `preflight`, `record-shipment`, `validate`, `integrate`, and
 `validate-integrated`. Invoke them with `python3`; the files need not be
 executable. Skill-bundle copies are not the guard's trust anchor, even when
@@ -269,8 +272,9 @@ The persisted `STATE.archive` field is the transaction identity.
    create the ship phase's one commit with exact subject
    `ship: M00N — <milestone-slug>` and a body of exactly two consecutive lines,
    `Archive: .project/archive/<NNN>-<slug>` then
-   `Reviewed-HEAD: <reviewed SHA>`, with no comment lines or blank line between them
-   (pass the body as one `-m` value or from a message file). M00N and NNN come from STATE.archive.
+   `Reviewed-HEAD: <reviewed SHA>`, with no comment lines or blank line between them.
+   Write the subject, a blank line, and the two body lines to a message file,
+   then use `git commit -F <message-file>`. M00N and NNN come from STATE.archive.
    There is no untracked-project exception and no product or older-archive
    path may enter this commit.
 6. Immediately run `python3 <absolute archive_milestone.py> validate --repo <root>`. It requires the committed shipped state, exact archive and
@@ -363,27 +367,35 @@ Run this recovery setup from a separate checkout, outside the closed primary
 worktree's guard.
 
 1. Create separate disposable trust and validation checkouts from the same
-   published origin and `STATE.branch`. This separation is required because a
-   managed runtime refresh may dirty a checkout when `.gsd-path/` is tracked,
+   published origin and `STATE.branch`. This separation is required because an
+   explicit runtime upgrade changes the trust checkout's declaration and launcher,
    while archive validation requires a clean checkout. Never use the primary
    worktree for either role.
-2. From the trusted fixed GSD Path checkout, preview and then refresh only the
+2. From the trusted fixed GSD Path checkout, preview and then explicitly upgrade only the
    disposable trust checkout's managed trust anchor:
 
    ```bash
-   node <trusted-gsd-path>/scripts/install.mjs --hooks-refresh --dry-run --project <trust-root>
-   node <trusted-gsd-path>/scripts/install.mjs --hooks-refresh --project <trust-root>
+   node <trusted-gsd-path>/scripts/install.mjs --runtime-upgrade --dry-run --project <trust-root>
+   node <trusted-gsd-path>/scripts/install.mjs --runtime-upgrade --project <trust-root>
+   ```
+
+   Confirm that the preview identifies the intended fixed version and digest.
+   Upgrade changes only the disposable trust project's declaration and compatible
+   launcher. For a legacy trust checkout with no declaration, use the explicit
+   `--runtime-migrate` preview and migration first. Resolve the upgraded runtime:
+
+   ```bash
+   python3 -B <trust-root>/.gsd-path/status_runtime.py --repo <trust-root> --runtime-path
    ```
 
-   Continue only when the preview names managed `.gsd-path/` runtime or guard
-   files and no `.project/` path. The installer owns the atomic refresh and
-   refuses unmanaged or unsafe runtime entries.
-3. Use only the refreshed project-local trust anchor to refresh publication
+   Use the returned absolute directory as `<verified-runtime>` below. Stop on any
+   error; do not substitute the validation checkout's older selected runtime.
+3. Use only this verified upgraded runtime to refresh publication
    refs in the clean validation checkout and validate its integrated milestone:
 
    ```bash
-   python3 <trust-root>/.gsd-path/runtime/archive_milestone.py refresh-origin --repo <validation-root>
-   python3 <trust-root>/.gsd-path/runtime/archive_milestone.py validate-integrated --repo <validation-root> --slug <STATE.milestone>
+   python3 -B <verified-runtime>/archive_milestone.py refresh-origin --repo <validation-root>
+   python3 -B <verified-runtime>/archive_milestone.py validate-integrated --repo <validation-root> --slug <STATE.milestone>
    ```
 
 4. A pass restores the normal shipped handoff without another commit or