@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/path/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: path
-description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $path or $gsd-path. The status argument reports state without advancing. Do not infer this skill from generic project, next-step, or resume requests.
+description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $path or $gsd-path. The status argument reports state without advancing; config views or edits settings without advancing. Do not infer this skill from generic project, next-step, or resume requests.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
+## Configuration mode
+
+When the first argument is `config`, read [Path settings](references/config.md)
+and complete that request without initializing state or advancing a phase.
+
 # GSD Path Router
 
 Determine the current pipeline phase, report it briefly, and run the next valid
@@ -11,11 +18,13 @@ Any text the user is expected to send back verbatim (a ruling, an approval
 command, a reply) goes in its own fenced code block, never a blockquote or
 inline prose, so it pastes cleanly.
 
-When the project's `.gsd-path/runtime/` exists, resolve bundled helper paths
-for `pipeline_state.py`, `pipeline_git.py`, `archive_milestone.py`,
-`promote_lookahead.py`, `discussion_records.py`, and `pipeline_diagnose.py`
-to that runtime. It is the guard-approved location on a closed milestone.
-Use the skill bundle only when no project-local runtime exists.
+When `.gsd-path/runtime.json` exists, run `python3 -B
+<absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project>
+--runtime-path`. Use the returned verified directory for its bundled helpers.
+A missing or invalid selected runtime stops execution with its explicit restore
+action; never substitute the installed plugin's helpers. Legacy projects without
+a declaration may use `.gsd-path/runtime/`, or the skill bundle when that directory
+is absent. An explicit `--runtime-migrate` produces the reviewed migration diff.
 
 ## Status-only mode
 
@@ -24,10 +33,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 +74,32 @@ 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
+   the user prefers a managed primary, offer an explicit path below
+   `~/.gsd-path/projects/` (or `GSD_PATH_WORKTREE_ROOT`) instead. Pass the
+   approved absolute path through `--worktree`; its parent must already exist
+   for preview. Keep this choice separate from helper-owned task, verify, and
+   integration placement. Never relocate an existing primary.
+   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 +136,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
@@ -139,8 +165,8 @@ selects a milestone branch.
 
 ## Integration choice
 
-New state starts with `integration_default: direct`, `integration: direct`, and
-`integration_source: default`.
+New state uses the user shipping default (built-in: `direct`) for
+`integration_default` and `integration`, with `integration_source: default`.
 When the user asks to change closeout behavior before build, use the state
 helper; never edit these fields by hand:
 
@@ -283,11 +309,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/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.