@opengsd/gsd-path 1.0.0 → 1.1.0

package/skills/gsd-path/DECIDE.md

@@ -98,12 +98,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

@@ -36,16 +36,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.
@@ -274,18 +280,8 @@ After approval, finalize `.project/intent/INTENT.md` and run
 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/INSPECT.md

@@ -21,10 +21,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 +49,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 +159,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

@@ -29,8 +29,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 +77,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 +143,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,7 +209,9 @@ 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
@@ -257,12 +269,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 +281,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 +290,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

@@ -143,12 +143,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

@@ -143,69 +143,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

@@ -8,8 +8,8 @@ description: Verify a completed GSD Path milestone, manage evidence-backed patch
 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
@@ -269,8 +269,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

package/skills/gsd-path/SKILL.md

@@ -24,10 +24,9 @@ When the invocation argument is exactly `status`, report and stop:
 1. Run `python3 <absolute-bundled-pipeline-state.py> status --repo
    <absolute-root>`. Treat the JSON as the only status authority. Do not
    initialize STATE.md, bind a branch, or create a repository from this mode.
-2. Present **Outcome** as `state.phase`/`state.status`, `route.action`,
-   `next_skill`, and the pending-answer count. **Review** links the JSON
-   `path` (STATE.md). **Next** names `next_skill` or the `route.reason` when
-   `route.action` is `block`, without invoking either.
+2. Present the returned `handoff.outcome`, `handoff.review`, and
+   `handoff.next` as **Outcome**, **Review**, and **Next**, plus the
+   pending-answer count. Use the host's invocation prefix.
 3. Do not run a phase contract, auto-advance, spawn agents, or apply undo.
 
 `$gsd-path status` (Codex) and `/gsd-path status` (other hosts) are the only
@@ -66,19 +65,27 @@ GitHub repository and no owned `.project/STATE.md` is active for that request.
    local workspace when absent; do not infer account ownership or visibility.
    Derive `gsd-path/M001` as the branch. The default checkout is
    `<resolved-workspace>/<repo-name>`; propose the distinct sibling
-   `<resolved-workspace>/<repo-name>-gsd-path` as the linked worktree. The user
+   `<resolved-workspace>/<repo-name>-gsd-path` as the linked worktree. When
+   starting in an empty non-Git folder, propose that existing folder as the
+   linked worktree with `--reuse-empty-worktree`, and a distinct absent default
+   checkout beside it. Use the parent as workspace so the journal stays outside
+   the worktree. Preserve the invocation folder and all its contents; never
+   delete it or STATE.md to satisfy a preview. A nonempty folder requires a
+   different target or an explicit recovery. The user
    may choose another workspace or worktree path before approval.
 2. Resolve the bundled `scripts/bootstrap_repository.py` to an absolute path.
    Run its `preview` command with the exact owner, repository, visibility,
    workspace, default checkout, linked worktree, and optional description. The
    helper checks authentication, remote state, path parents, and any matching
    transaction journal without mutation. `mode: create` means every target is
-   absent; `mode: resume` means the exact approved journal exists and the helper
+   absent, except an explicitly approved empty linked-worktree directory;
+   `mode: resume` means the exact approved journal exists and the helper
    can verify and adopt completed stages; `mode: complete` names an already
    initialized binding. Any ambiguity or unowned collision blocks.
 3. Present **Outcome** as a repository-creation preview. Present **Review** with
    the proposed GitHub URL, visibility, default-checkout path, GSD Path branch,
-   and linked-worktree path, all marked not yet created. Present **Next** as one
+   and linked-worktree path. Mark new targets not yet created and an existing
+   empty worktree folder as reused in place. Present **Next** as one
    choice: `Create repository and worktree (recommended)` for `mode: create`, or
    `Resume verified repository transaction (recommended)` for `mode: resume`,
    followed by `Change details` and `Cancel`. Present this review inline; do not
@@ -115,10 +122,15 @@ selects a milestone branch.
    mutation. In particular, never stamp the marker onto unowned state.
 2. With no STATE.md, run the bundled
    `python3 <absolute-bundled-script> initialize --repo <absolute-root>
-   --template <absolute-state-template>` helper
+   --template <absolute-state-template> --require-git` helper
    (`scripts/detect_project.py`) before asking anything. Do not classify
    brownfield, greenfield, or orphaned `.project/` from a directory listing or
-   conversation. If the command exits nonzero, returns `error`, or returns
+   conversation. Handle `route: setup-repository` before the write gate: the
+   helper left the folder unchanged and wrote no state. Ask whether to create
+   a new GitHub repository (recommended for an empty folder) or use an existing
+   repository. A new-repository choice enters the preview transaction above;
+   an existing-repository choice requires its path before continuing. Do not
+   bind a branch or enter a phase yet. 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. Otherwise follow the JSON `verdict` / `route` exactly.
    `initialize` classifies and, for brownfield or greenfield, writes STATE.md
@@ -283,11 +295,9 @@ python3 <absolute-bundled-pipeline-state.py> transition \
   --event "build started"
 ```
 
-Report normal progress in three labeled lines: **Outcome** names the phase and
-completed work, **Review** links the newest canonical artifact using its
-resolved absolute path when one exists, and **Next** names the action the
-router is taking or the single action required from the user. Resolve the
-routed track root first: `.project/` for the active track or `.project/next/`
+Report normal progress through the executable phase handoff in AGENTS.md.
+Use `handoff.router_next` while this router owns continuation.
+Resolve the routed track root first: `.project/` for the active track or `.project/next/`
 for lookahead. If that track root's `research/DOCS-AUDIT.md` has `planned: no`
 rulings, add one alignment-queue line and offer once to route them through the
 bundled [plan contract](PLAN.md); declining does not block.

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

@@ -0,0 +1,33 @@
+## Milestone abandon (program flow only)
+
+Abandon the active milestone only on an explicit user ruling — from the
+review-cycle-cap escalation, a decision invalidation, or a direct request.
+Require `.project/ROADMAP.md`; a single-milestone project has no abandon
+path — stop and let the user decide how to restart.
+
+1. Retire every recorded task worktree and branch with `isolation.py retire`
+   after confirming ownership, recording each discarded uncommitted diff's
+   exact path set and hash in the STATE.md log. Never discard work the
+   recorded metadata cannot own.
+2. Run the bundled `scripts/archive_milestone.py abandon --repo <absolute
+   repo root> --slug <milestone slug> --reason <user ruling, verbatim>`.
+   This one helper-owned transaction journals the exact request and starting
+   HEAD before mutation; archives the partial artifacts without review gates;
+   marks the exact ROADMAP entry `Status: abandoned` with its `Archive:` path;
+   appends `- <NNN>-<slug> — abandoned: <collapsed ruling>` exactly once to
+   LESSONS.md; transitions STATE to `roadmap/active` with `milestone: null`
+   and `archive: null`; and creates the checkpoint with exact subject `build:
+   abandon milestone <slug>` and body `Why: <collapsed ruling>`. The manifest
+   `Reason:` and checkpoint `Why:` are the same normalized ruling.
+3. Rerun the same command with the same slug and ruling after any interruption.
+   It resumes archive moves, metadata, state transition, or checkpoint from
+   the journaled starting HEAD; a changed slug, ruling, archive, branch, or
+   manifest reason blocks. Success returns the archive, exact checkpoint
+   commit, and `committed` or `already-complete` status. Never edit or commit
+   any part of this transaction manually and never select another sequence
+   number.
+4. Return to the router, which routes `roadmap/active` to the roadmap
+   contract in re-slice mode. The abandoned code stays on the build branch
+   until the next milestone's integration, then reaches the default branch as
+   inert history; the re-slice plans around it. Never revert product commits
+   yourself.