@opengsd/gsd-path 1.0.0 → 1.2.0

package/README.md

@@ -15,6 +15,18 @@ Support means the installer and dispatch contract exist. See the
 [host trust matrix](https://github.com/open-gsd/gsd-path/blob/main/docs/trust-validation/HOST-MATRIX.md) for live milestone
 proof and each host's guard tier.
 
+<!-- release-docs -->
+**Latest npm release:** [@opengsd/gsd-path@1.2.0](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.2.0) — [release notes](CHANGELOG.md#120---2026-09-20)
+
+**Recent highlights**
+- add Path settings and project history dashboard
+- add optional Jev evidence screening
+- store worktrees and pinned runtimes outside project checkouts
+- centralize sub-agent model selection policy
+- reuse unchanged host receipts for releases
+
+<!-- /release-docs -->
+
 ## Documentation
 
 **Start at [DOCS.md](DOCS.md)** — install, use, understand, and update in one hub.
@@ -27,22 +39,195 @@ proof and each host's guard tier.
 | **[UPDATE.md](UPDATE.md)** | Refresh skills, hooks, or contracts |
 | [WORKFLOW.md](WORKFLOW.md) | Phase-by-phase agent SOP |
 | [HOOKS.md](HOOKS.md) | Optional archive/git guard hooks |
+| [Jev screening](skills/gsd-path/references/jev-review.md) | Optional evidence screening; disabled by default, no SDK required |
+| [daemon/README.md](daemon/README.md) | Dashboard, menu-bar app, and monitoring setup |
+| [CHANGELOG.md](CHANGELOG.md) | Published release notes |
+| [RELEASE.md](RELEASE.md) | Maintainer CI and npm release cycle |
 | [GUIDE.md](GUIDE.md) | Pointer to the guides above |
 
+## What's new — September 19, 2026
+
+These changes are merged into the source checkout; npm installs use the latest
+published release.
+
+- **Dashboard settings and history:** edit Path settings, browse project files
+  and Git versions, and load full recorded evidence. See the
+  [dashboard guide](daemon/README.md#project-history-and-files).
+- **Model and effort policy:** set user, project, host, and task choices through
+  one resolver. Recorded assignments stay pinned; unsupported explicit choices
+  stop the affected dispatch. See the
+  [model policy](skills/gsd-path/references/model-policy.md).
+- **External worktrees and pinned runtimes:** new parallel task, verification,
+  and integration worktrees live outside project checkouts. Projects pin runtime
+  versions by content digest, with explicit upgrade, restore, and legacy migration
+  commands. See
+  [worktree locations](DOCS.md#worktree-locations) and
+  [runtime versions](DOCS.md#project-runtime-versions).
+- **Clearer project updates:** the dashboard shows project runtime versions and
+  update results. After verified integration, ordinary branches can resume
+  product work while archived milestones remain protected. See
+  [update guidance](UPDATE.md#update-the-project-runtime-and-guard-hooks).
+- **Optional Jev screening:** reviewers can request advisory checks of selected
+  criteria and evidence. It is disabled by default and never replaces recorded
+  verification or review gates. See
+  [Jev screening](skills/gsd-path/references/jev-review.md).
+
+## Install from npm
+
+Requires **Node.js 18.17+** for the npm installer and **Python 3.9+** for
+project contracts and pipeline helpers. Install and sign in to a supported
+coding-agent host separately; GSD Path installs its skills, not the host itself.
+The public npm package is **[@opengsd/gsd-path](https://www.npmjs.com/package/@opengsd/gsd-path)**.
+
 ```bash
-# New user
-node scripts/install.mjs --all --dry-run && node scripts/install.mjs --all
-cd your-repo && node scripts/install.mjs --all --project "$(pwd)"
-# In agent: invoke the router (see Install summary below)
+# Interactive installer: choose hosts, install scope, contracts, and hooks
+npx @opengsd/gsd-path@latest
 
-# Already installed
-node scripts/install.mjs --update
-cd your-repo && node scripts/install.mjs --update --project "$(pwd)"   # also refresh .gsd-path/
+# Or preview and install skills for all supported hosts
+npx @opengsd/gsd-path@latest --all --dry-run
+npx @opengsd/gsd-path@latest --all
+
+# Add contracts and the status runtime to your project
+npx @opengsd/gsd-path@latest --all --project /path/to/your-repo
+
+# Update existing installs
+npx @opengsd/gsd-path@latest --update
+npx @opengsd/gsd-path@latest --update --project /path/to/your-repo
+```
+
+Use host flags such as `--claude --codex` instead of `--all` to select hosts.
+For project-local skills, run from your project directory and add `--local`
+to install and update commands. `--project PATH` selects where contracts are
+written; it does not change the directory used by `--local`. Run
+`npx @opengsd/gsd-path@latest --help` for all options. After installing, invoke
+`$path` in Codex or `/path` on slash-command hosts to start the pipeline.
+See [Install (summary)](#install-summary) for the host list and source-checkout commands.
+The npm command installs the latest published release; a source checkout may
+contain newer changes.
+
+### Start your first project
+
+1. Open your project folder in your coding-agent host. Existing repositories
+   need Git; GitHub repository creation and pull-request operations also need
+   an authenticated GitHub CLI (`gh`).
+2. Start or reload the host session so it discovers the installed skills.
+3. Invoke `$path` in Codex, or `/path` on slash-command hosts. The router
+   identifies the project and guides you through the required inputs and approvals.
+4. Resume later from the same folder with the router. Use `$path status`
+   (Codex) or `/path status` to inspect progress without advancing.
+
+For a missing skill or an install problem, run:
+
+```bash
+npx @opengsd/gsd-path@latest --doctor --project /path/to/your-repo
+```
+
+Add `--local` when checking project-local skills, from that project directory.
+See [QUICK.md](QUICK.md) for the first-run checklist and [HOOKS.md](HOOKS.md)
+for optional Git and host guard hooks.
+
+For project-owned model and effort choices, see the
+[dispatch model policy](skills/gsd-path/references/model-policy.md).
+
+Use `$path config` (Codex) or `/path config` to view and change user defaults or
+project settings. Dashboard users can open **Settings → Path settings** for the
+same shipping, model/effort, and future review-panel controls. See
+[Path settings](skills/gsd-path/references/config.md) for precedence and locks.
+
+## Dashboard and menu-bar toolbar
+
+The optional **OpenGSD Path monitor** shows your projects without opening each
+project's `.project/` files. It watches the folders you choose and reads project
+state without advancing phase gates. Explicit Path settings saves use the
+validated configuration helper; background monitoring remains read-only.
+The monitor is a separate install from the npm skills package.
+
+### Dashboard
+
+The project board shows blocked, active, and shipped work, with milestone and
+phase progress, task counts, last activity, and available usage data. Use the
+[dashboard controls](daemon/README.md#dashboard) to filter or search projects,
+switch between Board and Milestones, refresh status, and manage settings.
+
+![OpenGSD Path project board showing sample projects, status filters, milestone progress, tasks, and usage](docs/images/dashboard-board.png)
+
+Click a project to see its milestone roadmap, tasks, success criteria, review
+results, verification history, and activity. Usage includes tokens and turns
+from supported host session logs; cost estimates require model prices in the
+daemon configuration.
+
+![Project dashboard showing the history viewer link, milestone progress, expandable evidence, and usage with sample data](docs/images/dashboard-project.png)
+
+*Dashboard screenshots captured from the current source on September 19, 2026,
+using the repository's sample projects.*
+
+Open **History & files** to browse project files and archived milestones,
+preview Markdown, or read a file at a selected Git commit. Relative document
+links keep that selected version. **Records & sources → Load full records**
+loads recorded usage, verification, activity, and indexed host turns on demand,
+with coverage details that make missing or invalid data visible.
+
+Open **Settings → Path settings** to change user defaults or project overrides
+for shipping mode, model and effort choices, and future review panels. Each
+setting shows its source and any lock reason; changes are saved explicitly.
+
+The **Plugin** settings page shows each watched project's runtime version and
+provides an explicit **Update** action with progress and failure details.
+Updating global skills does not update a project's pinned runtime.
+
+### macOS menu bar
+
+Click the OpenGSD Path menu-bar icon for a compact project list with phase
+meters and task progress. Click a project to open its dashboard page. The
+bottom toolbar opens the dashboard, plugin settings, and watched folders;
+it also provides rescan, appearance, and quit controls. The daemon row shows
+its running state and provides restart and stop controls. Option-click the
+menu-bar icon to open the dashboard directly.
+
+<img src="docs/images/macos-menu-bar.png" alt="OpenGSD Path native macOS panel with sample projects and its bottom toolbar" width="400">
+
+*Screenshots show the current UI with sample project data. The native panel is
+captured in its preview window.*
+
+### Install the monitor
+
+The monitor requires Python 3.9+. From a source checkout, preview the setup,
+then install (macOS/Linux shell):
+
+```bash
+git clone https://github.com/open-gsd/gsd-path.git
+cd gsd-path
+PYTHONPATH=daemon python3 -m gsd_daemon install --dry-run
+PYTHONPATH=daemon python3 -m gsd_daemon install
+```
+
+On Windows, after cloning and entering `gsd-path`, use PowerShell:
+
+```powershell
+$env:PYTHONPATH = "daemon"
+python -m gsd_daemon install --dry-run
+python -m gsd_daemon install
 ```
 
-Interactive: `npx @opengsd/gsd-path` with no flags opens the OpenGSD wizard (pick hosts, scope, contracts, hooks; dry-run first)
+On Windows, launch the installed shortcut for this session before opening the
+dashboard. It starts automatically at future logins:
 
-npm (once published to npm): `npx @opengsd/gsd-path --all` · Help: `node scripts/install.mjs --help`
+```powershell
+Start-Process "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\gsd-path-daemon.lnk"
+```
+
+Open **http://127.0.0.1:8765**, then use **Settings → Watched folders** to add
+your project folders. The installer creates an isolated Python environment and
+configures autostart. On macOS it also builds and installs the native menu-bar
+app; this requires macOS 12+ and Xcode Command Line Tools (`swiftc`). On
+macOS, use `--no-tray` for the dashboard only. Linux autostart runs the
+dashboard; launch the optional tray separately with
+`~/.gsd-path/venv/bin/gsd-path-daemon tray`. Windows uses a tray-and-dashboard
+Startup shortcut; see the [daemon guide](daemon/README.md) for platform details.
+
+See the [daemon guide](daemon/README.md) for configuration, usage pricing,
+manual startup, and platform setup, or the [macOS guide](daemon/macos/README.md)
+for native menu-bar details.
 
 ## Skills
 
@@ -91,7 +276,7 @@ flowchart TD
     B --> W{"wave loop"}
     W -->|"briefs linted at base SHA"| C["parallel coders, isolated worktrees"]
     C -->|"streaming: dependents dispatch as deps land"| V{"wave review"}
-    V -->|"full — or deep: contract + adversarial lenses"| F{"verdict"}
+    V -->|"full / verify-only / deep"| F{"verdict"}
     F -->|"blocked → criterion triage"| W
     F -->|"pass → next wave"| W
     F -->|"all waves pass"| S["6 · ship — final review"]
@@ -109,6 +294,16 @@ flowchart TD
     A -->|"program complete"| PC["stop"]
 ```
 
+Starting in an empty folder without Git leaves that folder unchanged until
+repository setup. The router asks whether to create a new GitHub repository or
+use an existing repository. For a new repository, approve the exact owner/name,
+visibility, default-checkout path, `gsd-path/M001` branch, and linked-worktree
+path before creation. The starting folder is proposed as the linked worktree,
+with a distinct default checkout beside it, so the agent keeps working where
+it started. Only an approved empty directory can be reused; nonempty folders
+and symlinks remain protected. Pipeline state is created after repository
+setup. See the [repository setup procedure](WORKFLOW.md#new-github-repository-creation).
+
 For an existing Git repository, initialization writes STATE.md first. Before
 entering inspect or define, the router fetches `origin/main`, creates or adopts
 `gsd-path/M001` there, and records the binding in state. Build only uses that
@@ -123,6 +318,8 @@ advance past an unresolved required follow-up.
 
 **Build, under the hood:**
 
+- For intent corrections or structural plan repair during a blocked build,
+  follow the [build recovery contract](skills/gsd-path/references/build-recovery.md).
 - Task briefs are linted against the real base tree (`check_task_briefs.py`)
   before any agent is dispatched, and every coder runs a preflight — paths
   exist or are declared, interface contracts match siblings verbatim — so a
@@ -146,9 +343,11 @@ advance past an unresolved required follow-up.
 
 Invoke the router explicitly to start or advance a phase. Once a project has an
 owned `.project/STATE.md`, a plain prompt such as “continue the project” answers
-read-only with the current handoff and names the next skill; it never advances
-a phase or edits state. Phase skills stop at their handoff; invoke the router
-again to continue.
+read-only with the current handoff and uses the runtime’s `handoff.next`; it
+never advances a phase or edits state. An active router continues across completed phases
+until required input, approval, or a block. A phase invoked directly stops at
+its handoff; invoke the router again to continue. Chat and the dashboard use
+the same executable phase handoff from the status runtime.
 The discussion sidecar is the exception: it can be invoked at any non-shipped
 phase and returns only a durable conversation record.
 
@@ -203,10 +402,14 @@ top-level `SYNTHESIS.md`) remain active project metadata.
 
 ## Install (summary)
 
-Node 18.17+. Project installs also require Python 3.9+. Validates package,
+Node 18.17+ for the Node installer; Python 3.9+ for project installs and pipeline
+helpers. Validates package,
 backs up existing skills, and rolls back on failure.
 **Always** `--dry-run` first when unsure.
 
+The commands below run from a source checkout. For npm, replace
+`node scripts/install.mjs` with `npx @opengsd/gsd-path@latest`.
+
 ```bash
 node scripts/install.mjs --all --dry-run
 node scripts/install.mjs --all
@@ -271,6 +474,7 @@ make install && make verify    # same path as GitHub Actions CI
 | `HOOKS.md` | Guard hooks |
 | `skills/` | Canonical skills and generated aliases declared in [the resource manifest](scripts/skill-resources.json) |
 | `platforms/` | Host dispatch adapters |
+| `daemon/` | Project monitor, dashboard, and tray apps |
 | `scripts/install.mjs` | Installer (npm `gsd-path` bin) |
 | `scripts/install.py` | Python installer |
 | `AGENTS.md` | Operating rules (installed to projects) |

package/RUNTIME.md

@@ -13,6 +13,10 @@ It does not dispatch models or supply owner approvals.
 Use the absolute `workflow_run.py` path in the active skill's scripts directory.
 All commands require `--repo <absolute repository root>`.
 
+Initial inspection also uses `prepare-inspect` and `finish-inspect`. Their
+inputs, receipt handling, and entry conditions are owned by the
+[inspection procedure](skills/gsd-path-inspect/SKILL.md#process).
+
 | Command | Required input | Result |
 | --- | --- | --- |
 | `route` | Optional `--project-dir .project/next` | Canonical route; follow its action even when it blocks or requests recovery. |
@@ -70,8 +74,9 @@ skeptic attempts under `skeptics/`.
 
 The child command is owner-supplied shell words. The driver runs it with the
 isolated worktree as its working directory and the self-contained brief on
-stdin; the owner's flags decide the child's permissions and model. Verified
-templates: `claude -p --output-format json <owner permission flags>` and
+stdin; the owner's flags decide the child's permissions. Model and effort
+controls follow the [dispatch model policy](skills/gsd-path/references/model-policy.md#cli-lifecycle).
+Verified templates: `claude -p --output-format json <owner permission flags>` and
 `codex exec --json <owner sandbox flags>`. A coder child ends its final message with
 `RESULT: <task id> ready|blocked`; no line means blocked. A Log delta whose
 first entry after the last recorded `Orchestrator answer:` leads with
@@ -79,8 +84,9 @@ first entry after the last recorded `Orchestrator answer:` leads with
 a timeout or nonzero exit is a failure even if the child wrote a question.
 Canonical reviewer children instead return the `Wave verdict:` line in their
 validated review artifact; they do not need a `RESULT:` line.
-Panel children write family findings without a Wave verdict. The panel command
-replaces literal `{model}` in its child command with the resolved family slug.
+Panel children write family findings without a Wave verdict. The `{model}`
+command example above is the legacy form; capability-based commands use the
+argument slots defined in the dispatch model policy.
 `--wave` is required and pins the parent-selected wave, including on resumed
 calls. In `round`, an unfinished earlier wave blocks dispatch before the bookkeeping
 checkpoint. Child completion is recorded in `exit.json`; the parent alone
@@ -89,6 +95,9 @@ For `review`, `panel`, and `skeptics`, when the child process is gone and `finis
 unset, the driver rereads that attempt's state and exit receipt before
 collecting the result or blocking with
 `child wrapper exited without recording a result`.
+Review starts from a clean base. A same-cycle retry may dispatch a missing lens
+at that unchanged base while verified, already-collected review artifacts remain
+uncommitted. Altered artifacts or unrelated changes block recovery.
 `--wait`, `--child-timeout`, and `--capacity` (concurrent children) have
 no defaults. `--max-attempts` defaults to 2 dispatches per task per milestone,
 the build contract's one logged redispatch after the first attempt; question
@@ -192,7 +201,9 @@ python3 <token_budget.py> admit --ledger <absolute ledger> --task <next logical
 The metric is the host's `output_tokens`, including its reported reasoning output;
 reasoning is not added again. Input and cached input are not included. Resumptions
 reuse the ledger and task identity. Each CLI invocation uses its immutable event
-file. Re-observing that file is idempotent; new invocations accumulate. Native
+file. Re-observing that file is idempotent. For per-invocation versus cumulative
+resume counters, follow the [dispatch accounting contract](platforms/shared-agents/dispatch.md#configured-output-budgets):
+new invocations must charge only new output. Native
 single-invocation child sessions and Claude `--output-format json` usage
 receipts are supported. Resumed native child logs with
 ambiguous cumulative counters fail closed; use separate CLI run receipts instead.

package/UPDATE.md

@@ -14,10 +14,10 @@ Pulled new gsd-path / ran npx @opengsd/gsd-path@latest
 └─ Skills feel stale or router shows old behavior?
    ├─ Global install     → install.mjs --update
    ├─ Project-local      → install.mjs --update --local  (from repo root)
-   ├─ Project runtime    → install.mjs --update --project PATH  (refreshes .gsd-path/, keeps contracts)
+   ├─ Project wiring     → install.mjs --update --project PATH  (keeps contracts and selected runtime)
    └─ npm only           → npx @opengsd/gsd-path@latest --update
 
-Installed with --hooks and upgraded guard scripts
+Installed with --hooks and need to refresh wiring
 └─ install.mjs --hooks-refresh --project PATH
    └─ Also refresh native settings / git hooks?
       → --hooks-refresh-full [--claude] [--codex] [--cursor]
@@ -40,7 +40,7 @@ AGENTS.md or WORKFLOW.md template changed upstream
 | Global skills (`~/.claude/skills`, …) | Yes | `--update` |
 | Project-local skills (`.cursor/skills`, …) | Yes | `--update --local` |
 | `.gsd-path/guard_hook.py`, `git_guard.py` | Yes | `--hooks-refresh` or `--update --project PATH` |
-| `.gsd-path/runtime/*.py` | Yes | `--hooks-refresh` or `--update --project PATH` |
+| Project runtime | Explicit upgrade only | [Runtime lifecycle](DOCS.md#project-runtime-versions) |
 | Native hook settings + git hooks | Yes | `--hooks-refresh-full` (host flag creates missing config) |
 | Guards for an existing project | Yes | `--hooks-init` (preserves project contracts) |
 | `AGENTS.md`, `WORKFLOW.md` | **No** | Manual merge |
@@ -57,7 +57,8 @@ updates roll back all selected targets.
 An initial `--hooks` install merges valid native settings for explicitly selected Claude,
 Codex, or Cursor hosts; other existing project contract and guard files are refused.
 `--update --project PATH` keeps `AGENTS.md`, `WORKFLOW.md`, and `.claude/CLAUDE.md`
-and refreshes the managed `.gsd-path/` files, native settings, and git hooks.
+and refreshes managed hook wiring, native settings, and git hooks. For runtime
+changes or legacy installations, follow the [runtime lifecycle](DOCS.md#project-runtime-versions).
 Use `--hooks-init` to add guards to an existing project without changing its
 `AGENTS.md` or `WORKFLOW.md`. It inspects and merges native configs only for
 the selected hosts; configs for unselected hosts remain untouched.
@@ -120,16 +121,33 @@ You can update proactively with [commands above](#update-skills) without waiting
 
 ## Update the project runtime and guard hooks
 
-After any `--project` install, refresh the project status runtime with:
+The Dashboard's **Plugin → Watched projects → Runtime version** column shows
+each project's installed runtime release. Global skill versions are separate;
+a global update does not update project runtimes. Use the project's **Update**
+button to refresh its runtime and existing guards. Install and update actions
+show progress, success or failure, and installer output.
+
+If the daemon's plugin source checkout has local changes, project Update uses
+that local build and says so in its result. It does not pull remote changes over
+local edits. Clean source checkouts still refresh before a project update.
+
+Older unstamped installs show **Unknown — version metadata unavailable**.
+This does not establish that their runtime is outdated or broken. **Update**
+uses the guarded migration for legacy runtime directories and an upgrade for
+version-pinned runtimes. Migration leaves a reviewable Git diff and refuses
+modified or unknown runtime files; the dashboard shows the failure reason.
+See [Project runtime versions](DOCS.md#project-runtime-versions) for manual
+migration and preview commands. Use `--doctor --project PATH` to check runtime files.
+
+For upgrades, exact-version restoration, or legacy migration, follow
+[Project runtime versions](DOCS.md#project-runtime-versions). To refresh hook wiring:
 
 ```bash
 node scripts/install.mjs --hooks-refresh --project /path/to/repo
 ```
 
-This refresh works for hookless project installs. It overwrites the managed
-project status runtime and also refreshes managed guard scripts when they are
-installed. Guard files must contain `gsd-path guard`; runtime files must
-contain `gsd-path project runtime`.
+This refresh retains the selected runtime and leaves hookless installs hookless.
+Guard files must contain `gsd-path guard`.
 
 Include existing native settings and git hooks, and create missing settings for
 explicitly selected hosts:
@@ -164,7 +182,8 @@ To adopt upstream template changes:
 1. Open new templates in the gsd-path repo or npm package
 2. `diff` against your project copies
 3. Merge manually
-4. Refresh or initialize hooks to install the matching `.gsd-path/runtime/`
+4. Follow the [runtime lifecycle](DOCS.md#project-runtime-versions) when adopting
+   runtime changes. Use `--hooks-refresh-full` when host wiring needs a refresh.
 5. Never delete active `.project/` milestone state
 
 An in-flight milestone whose `INTENT.md` or `ROADMAP.md` predates `Surfaces:`
@@ -186,7 +205,7 @@ Unrecognized or foreign `.project/` state is never auto-migrated — the router
 | Skills still old | Restart session; confirm root with `--update --dry-run` |
 | Update rolled back | Read installer error; fix path overlap; retry |
 | `--hooks-refresh` rejects an unmanaged guard | Move the foreign guard aside, then rerun refresh; use `--hooks-init` if guards are wanted |
-| `--hooks-refresh` rejects an unmanaged runtime file | Back up or merge that file, move it aside, then rerun refresh |
+| Runtime missing, invalid, or legacy | Follow [runtime restoration or migration](DOCS.md#project-runtime-versions) |
 | Undo skill update | Copy from `disabled-gsd-skills` next to skills root |
 | npm vs clone confusion | Pick one: `npx @opengsd/gsd-path@latest --update` **or** clone + `install.mjs --update` |
 | Router still shows update line | Run update; or ignore — notice is informational |

package/WORKFLOW.md

@@ -5,6 +5,13 @@ Idea to shipped code through a gated pipeline. The `gsd-path` router reads
 Every handoff is on disk; the any-phase discussion sidecar also records its
 dialogue and answers on disk. AGENTS.md supplies the shared operating rules.
 
+**Path scope.** `.project/` paths describe the consuming project's artifacts.
+References to `skills/`, `scripts/`, `platforms/`, `RUNTIME.md`, and `HOOKS.md`
+describe the GSD Path source checkout, which an application need not contain.
+For execution in an installed project, resolve each role, template, and helper
+from the active skill's bundled absolute paths. Source-relative links below
+are navigation within the GSD Path source checkout, not installed-file claims.
+
 **Program flow.** When the work is a multi-milestone program, define runs in
 program mode and writes `.project/CHARTER.md` (enduring scope and vetoes),
 research and decide work at program scope, and the roadmap phase slices the
@@ -28,7 +35,7 @@ is the single-milestone flow below.
 
 Use the host-specific child-agent tool defined by the runtime dispatch contract
 bundled in the `gsd-path` skill, or the build contract's
-[dispatch driver](RUNTIME.md#dispatch-driver) when the owner supplies a child
+[dispatch driver](https://github.com/open-gsd/gsd-path/blob/main/RUNTIME.md#dispatch-driver) when the owner supplies a child
 command. Spawn independent work up to the available
 child capacity and batch any remainder. Every spawned agent has isolated
 context, so its brief must include the absolute role path, exact input paths,
@@ -90,18 +97,20 @@ unpublished work; it never invents `git reset`.
 
 <!-- gsd-path/plain-prompt-reentry/v1 -->
 
-Project installs include the router's read-only status engine at
-`.gsd-path/runtime/` and its stable launcher at `.gsd-path/status_runtime.py`.
+Project installs record the selected runtime in `.gsd-path/runtime.json` and
+keep a stable launcher at `.gsd-path/status_runtime.py`. Runtime implementation
+lives under `~/.gsd-path/runtimes/`; clones and named checkouts inherit the
+declaration. Missing versions require explicit restoration, not a download
+during status or guard execution.
 On any turn that did not explicitly invoke a GSD Path
 skill, an owned `.project/STATE.md` activates re-entry. Informational prompts
 finish read-only and end with the current **Outcome** / **Review** / **Next**
-handoff. Mutation prompts make no changes and point to the status result's
-`next_skill` only when `route.action` is `run-phase`. Every other route reports
-its exact `route.action` and `route.reason`. The status engine never initializes state
-or advances a phase.
+handoff. Both informational and mutation replies use the status result's
+`handoff.next` for **Next**. Mutation prompts make no changes. The status engine
+never initializes state or advances a phase.
 
 The optional pre-tool guard backs this up where it has deterministic evidence.
-See [HOOKS.md](HOOKS.md#what-gets-blocked) for write restrictions, including
+See [HOOKS.md](https://github.com/open-gsd/gsd-path/blob/main/HOOKS.md#what-gets-blocked) for write restrictions, including
 closed milestone branches and target worktrees. Shell provenance
 cannot prove which skill initiated a command, so the always-loaded AGENTS.md
 contract owns shell cases.
@@ -113,7 +122,11 @@ gate. Resolve and preview the GitHub owner/name, visibility, normal default
 checkout, `gsd-path/M001` branch, and a distinct linked-worktree path.
 Create no repository, checkout, worktree, pipeline state, journal, or preview
 file until the user approves every target; present the pre-creation review
-inline from the bootstrap helper's read-only `preview` result.
+inline from the bootstrap helper's read-only `preview` result. An existing
+empty invocation folder may be the linked worktree with approved
+`--reuse-empty-worktree`; Git populates it in place. Keep the workspace journal
+outside that folder. Preserve nonempty folders and choose another target;
+never delete the invocation folder or its state to pass a preview.
 
 After approval, the bundled bootstrap helper writes an exact transaction
 journal under the approved workspace before mutation. Its `create` command
@@ -137,8 +150,9 @@ at `inspect/active|blocked`. **Output:**
 
 When STATE.md is absent, the router runs the bundled
 `scripts/detect_project.py initialize --repo <absolute-root> --template
-<absolute-state-template>` helper before asking anything and routes from its
-returned JSON. `brownfield` initializes `inspect/active` and routes here;
+<absolute-state-template> --require-git` helper before asking anything and routes from its
+returned JSON. `route: setup-repository` leaves a non-Git folder unchanged and
+asks for repository setup before creating state. `brownfield` initializes `inspect/active` and routes here;
 `greenfield` initializes `define/active` and skips to define; `orphan` blocks.
 Owned state routes by STATE.md without rerunning the helper. Reserve `classify`
 for read-only inspection; do not re-derive a verdict from a directory listing.
@@ -214,8 +228,8 @@ milestone` instead: research and decide run only when the roadmap entry lists
 open questions, and planning writes a Settled-only milestone SYNTHESIS.md from
 the program synthesis before dispatching the planner. The quick lane skips
 research and decide — planning enters directly from `define/done`, writes
-a Settled-only SYNTHESIS.md and a single wave (verify-only review depth
-permitted, at most two tasks) without a planner agent, and the rest of the
+a Settled-only SYNTHESIS.md and a single wave (full or deep review depth,
+at most two tasks) without a planner agent, and the rest of the
 pipeline runs unchanged. A quick plan that outgrows those bounds corrects the
 lane to `standard` and reroutes through research.
 
@@ -366,6 +380,12 @@ build's re-entry transition instead).
 **Input:** the approved plan and tasks. **Output:** committed code, updated
 task files, and wave reviews.
 
+A blocked build returns through the guarded
+[build recovery contract](skills/gsd-path/references/build-recovery.md) when
+approved intent must change or the remaining task inventory needs repair.
+It preserves landed work, re-gates changed contracts, and returns through a new
+plan approval checkpoint. Ship and archived milestones cannot use this path.
+
 The build contract is not restated here. Branch binding, the wave loop, task
 isolation and landing, wave review, fix batching, completion, and milestone
 abandon live only in the canonical
@@ -477,8 +497,7 @@ The ship phase closes the milestone with exactly one commit on the bound
 branch: the shipped STATE.md, the final-review artifacts, and the archive
 move with its MANIFEST.md, staged from `.project/` only, subject
 `ship: M00N — <milestone-slug>` and a body naming `Archive:` and
-`Reviewed-HEAD:`. Every other commit on the bound branch
-belongs to the build orchestrator. The commit must contain only `.project/`
+`Reviewed-HEAD:`. The ship commit must contain only `.project/`
 paths. There is no untracked-project fallback. Every pipeline commit carries
 the subject and field body defined by its canonical phase contract; task-land
 fields live only in the
@@ -645,7 +664,7 @@ with their exact ordered source-file and row list.
   research/evidence-codebase.md   brownfield ground truth (inspect)
   research/DOCS-AUDIT.md     doc-vs-code verdicts and remediation queue
   research/RESEARCH.md       research dispatch/question/output manifest
-  research/evidence-*.md     four required evidence dimensions
+  research/evidence-*.md     evidence for dispatched dimensions; RESEARCH.md records skips
   research/SYNTHESIS.md      decision artifact; authoritative after decide gate
   plan/PLAN.md               waves, config, and project verify
   tasks/T###-slug.md         full contract, clean base SHA, status

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Disk-backed AI agent pipeline. Docs: DOCS.md (start here), QUICK.md, FULL.md, UPDATE.md",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-gsd/gsd-path.git"
+  },
+  "bugs": {
+    "url": "https://github.com/open-gsd/gsd-path/issues"
+  },
+  "homepage": "https://github.com/open-gsd/gsd-path#readme",
   "type": "module",
   "bin": {
     "gsd-path": "scripts/install.mjs"
@@ -11,6 +19,7 @@
     "plugin.json",
     "scripts/install.mjs",
     "scripts/install.py",
+    "scripts/runtime_store.py",
     "scripts/migrate_core.py",
     "scripts/core_hook_gate.py",
     "scripts/core_hook_settings.py",
@@ -18,7 +27,10 @@
     "scripts/wizard.mjs",
     "scripts/skill-resources.json",
     "scripts/_common.py",
+    "scripts/worktree_paths.py",
+    "scripts/build_recovery.py",
     "scripts/state_checkpoint.py",
+    "scripts/roadmap.py",
     "scripts/state_promote.py",
     "scripts/discussion_validate.py",
     "scripts/integration.py",
@@ -30,7 +42,10 @@
     "scripts/check_handoffs.py",
     "scripts/check_docs_audit.py",
     "scripts/check_task_briefs.py",
+    "scripts/path_config.py",
+    "scripts/model_policy.py",
     "scripts/review_panel.py",
+    "scripts/jev_review.py",
     "scripts/review_findings.py",
     "scripts/check_update.py",
     "scripts/guard_hook.py",
@@ -43,11 +58,13 @@
     "scripts/loop_run.py",
     "scripts/workflow_run.py",
     "scripts/dispatch_driver.py",
+    "scripts/task_context.py",
     "scripts/lean_verification.py",
     "scripts/token_budget.py",
     "scripts/pipeline_undo.py",
     "scripts/pipeline_diagnose.py",
     "README.md",
+    "CHANGELOG.md",
     "MIGRATE.md",
     "RUNTIME.md",
     "DOCS.md",
@@ -75,6 +92,11 @@
     "test:daemon": "PYTHONPATH=daemon python3 -m unittest discover -s tests -p 'test_daemon_*.py'",
     "verify": "npm test && npm run test:python && python3 scripts/sync_skill_resources.py --check",
     "verify:release": "npm run verify && python3 scripts/check_trust_evidence.py --repo .",
+    "release:docs": "node scripts/update_release_docs.mjs",
+    "release:bump": "node scripts/bump_version.mjs --bump auto",
     "prepublishOnly": "npm run verify:release"
+  },
+  "devDependencies": {
+    "yaml": "^2.9.1"
   }
 }

package/platforms/claude/dispatch.md

@@ -27,10 +27,10 @@ Apply this contract whenever a GSD Path skill delegates work:
   a colliding target.
 - Resolve the phase's linked role brief to an absolute path. Include that path
   in the prompt and require the agent to read it before acting.
-- Tier hints: when the host advertises model or reasoning-effort selection,
-  request `heavy` for `plan`, `plan_patch`, `decide`, and `roadmap`, and
-  `light` for `inspect_docs` and `docs_audit`; when it offers no such
-  selection, do not override the model except on a review-panel child, which receives the exact slug from `scripts/review_panel.py resolve`. Do not ask Claude Code to create
+- Model selection: before every child launch or continuation, follow
+  [the model-policy contract](model-policy.md) and apply its recorded
+  native arguments. It owns defaults, project settings, task overrides,
+  capability failures, and reassignment. Do not ask Claude Code to create
   another worktree: GSD Path supplies the exact repository or
   linked-worktree root in the brief, and the child must work only there.
   Host isolation: none.