@opengsd/gsd-path 1.1.0 → 1.3.0

package/AGENTS.md

@@ -127,7 +127,10 @@ full-repo suite on a tiny edit outrank the phase brief.
   with `-B .gsd-path/status_runtime.py --repo <absolute-root>`
   before any requested repository mutation. Treat its JSON as the only route
   authority.
-  A plain change request does not authorize work outside the pipeline: make no
+  When `completion.status` is `verified` and `git.branch` is an ordinary
+  branch (not `gsd-path/M###`), requested product work may proceed normally.
+  Archives and pipeline control files remain protected. Otherwise,
+  a plain change request does not authorize work outside the pipeline: make no
   changes and report **Outcome**, link the returned `path` under **Review**, and
   under **Next** use `handoff.next`. An explicit request to leave
   or bypass the pipeline is a user ruling;
@@ -253,7 +256,7 @@ full-repo suite on a tiny edit outrank the phase brief.
   orchestrator.
 - Reviewers verify and block; they never fix. A block names the criterion,
   observed result, evidence location, and concrete fix direction. An optional
-  review panel is advisory: the inherit reviewer remains the only wave
+  review panel is advisory: the canonical reviewer remains the only wave
   pass/fail, and panel findings never average or auto-replan. Same-model
   agreement is not independent verification: matching verdicts from one
   model family count as a single evidence path. Independence comes from

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to [@opengsd/gsd-path](https://www.npmjs.com/package/@opengsd/gsd-path)
+are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.1.0] - 2026-09-18
+
+### Added
+- Scoped npm package `@opengsd/gsd-path` with trusted publishing workflow
+- Release trust evidence validation and host matrix documentation
+
+### Changed
+- Release workflow and maintainer documentation for npm publication
+
+## [1.0.0] - 2026-09-15
+
+### Added
+- Initial public release of the disk-backed GSD Path pipeline
+- Multi-host installer, skills package, and project contracts
+
+## [1.2.0] - 2026-09-20
+
+### Added
+- 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
+
+### Changed
+- Correct stale release guidance and consolidate scope references
+- record passing eight-host release gate
+- validate corrected OpenCode release evidence
+- validate recovered Claude release evidence
+- record affected release gate results
+- preserve blocked host evaluations without receipt fallback
+- record passing Antigravity Kimi and Grok release runs
+- record remaining 1.2.0 release gate failures
+- record Kimi receipt and complete offline recheck
+- preserve 1.2.0 host receipts and release blockers
+- record v1.3.0 live release evidence and blockers
+- bump version to v1.3.0
+- Align release documentation with risk-based host validation
+- bump version to v1.2.0
+- Automate npm release docs, pack verification, and provenance (#133)
+- refresh README changes and dashboard screenshots
+- Refresh dashboard navigation and file history documentation
+- Clarify Jev receipt fields and consolidate documentation
+- Refresh dashboard update and guard documentation
+- Correct runtime installation, update, guard, and uninstall documentation
+- Correct model policy and dispatch documentation
+
+### Fixed
+- reuse unchanged host receipts for releases
+- verify prepared releases without advancing failed versions
+- scope release evidence to affected hosts
+- show project runtime updates and release completed milestone guards
+
+### Other
+- Fixed tests/package.test.mjs to invoke git_guard.py with pre-commit in a temporary Git repository instead of unsupported --help. The focused test failed before the fix and during restored-original sabotage. All 6 package tests now pass; resource sync and diff checks pass. Verified locally on Node 26; Node 18/20 CI reruns remain with the outer executor
+- Preserve historical commit selection across relative document links
+- Validate Jev probability normalization with CLI regression coverage
+- Record passing focused checks and isolation violation
+- Fix integration guard and runtime installer regression coverage
+- Fixed stale runtime paths in tests/test_git_guard.py using the installed runtime resolver. Both CI failures reproduced before the fix; all 38 Git guard tests now pass. Both corrected tests also caught a temporarily disabled native guard, which was restored. git diff --check passed. Only the test file changed; remote CI remains for the outer executor
+- Fix pinned runtime routing, guard blocking, and launcher bytes
+- Restore same-cycle recovery after partial review completion
+- Isolate assignment rejections and align native panel exclusions
+- Fix dispatch isolation, legacy pinning, and independent panel selection
+
+## [1.3.0] - 2026-09-21
+
+### Added
+- migrate legacy runtimes during upgrades
+
+### Changed
+- Clarify receipt reuse and consolidate release policy guidance
+- Clarify legacy upgrade guidance and verify syntax
+- update release notes for v1.2.0
+
+### Fixed
+- validate installer changes without live host reruns
+- preserve closed review cycles in host recovery
+- clarify owner gates and accept serial task release evidence
+
+### Other
+- Clarify reviewer ownership; live verification remains pending
+- Reject unretired verification worktrees and branches in release evidence

package/DOCS.md

@@ -44,7 +44,8 @@ GSD Path has two install layers:
 
 1. **Skills** — router + phase skills for your AI host(s)
 2. **Project contracts** (optional) — `AGENTS.md`, `WORKFLOW.md`, and the
-   read-only `.gsd-path/runtime/` status engine in the repo
+   tracked runtime declaration and stable status/guard launchers; runtime code
+   lives outside the checkout under `~/.gsd-path/runtimes/`
 
 ### Decision tree
 
@@ -223,6 +224,40 @@ route through `NEEDS-ORCHESTRATOR` instead of guesses.
 **Quick lane:** ≤2 tasks, one wave, no open questions — may skip research/decide
 ([FULL.md](FULL.md)).
 
+### Worktree locations
+
+The primary worktree stays in the folder you opened. Serial task work stays
+there too. New parallel task worktrees, verify sidecars, and integration
+worktrees share this managed layout:
+
+```text
+~/.gsd-path/projects/<repository-id>/<workspace-id>/{task,verify,integrate}/<name>
+```
+
+Set `GSD_PATH_WORKTREE_ROOT` to another absolute directory before the first
+helper-owned allocation in a workspace. The root must be outside the project's
+own worktrees; an unrelated repository tracking your home folder is allowed.
+Repository and workspace IDs are full SHA-256 hashes of the
+resolved Git common directory and primary path, so separate clones and
+primary folders do not share a location.
+
+The first allocation pins the workspace location in
+`<git-common-dir>/gsd-path/workspaces/<workspace-id>.json`. Later environment
+changes do not move it. Existing sibling worktrees remain at their original
+paths and retain the same recovery and cleanup checks. These folders contain
+active work and evidence; they are not a disposable cache. Relocation needs
+a separate migration; do not edit placement records or move folders manually.
+
+New repository setup can also use an explicitly approved managed primary
+path through the existing `--worktree` option. Its parent must already exist
+for the read-only preview. An approved empty invocation folder is still
+reused in place. This choice does not move the default checkout.
+
+In the dashboard's **Watched folders**, add the managed root explicitly;
+watching its home-directory parent does not traverse hidden `.gsd-path`.
+Discovery follows Git's registered bound branches back to the primary and
+applies exclusions there, so task and verify copies do not displace it.
+
 ### Key artifacts
 
 | Path | Role |
@@ -340,3 +375,40 @@ initializer. After a milestone ships, the next one inspects again.
 | Installer flags | `node scripts/install.mjs --help` |
 
 [Workflow runner and observed token budgets](RUNTIME.md) documents canonical gate receipts, serial verification preparation, and host budget limits.
+
+
+## Project runtime versions
+
+`.gsd-path/runtime.json` pins an exact runtime by package version and content
+digest. The runtime is stored under `~/.gsd-path/runtimes/<digest>/`; generated
+implementation files are not copied into project worktrees. Track the declaration
+and stable `.gsd-path` launchers as project configuration. Task isolation, Verify
+sidecars and Integration checkouts inherit this configuration through Git.
+
+Skill/plugin updates and `--hooks-refresh` retain the selected runtime. Use
+`gsd-path --runtime-upgrade --project /absolute/project` to explicitly select
+the supplied package's runtime and its compatible status launcher. Review those
+configuration changes before committing them. Existing versions remain available
+for other projects and branches.
+
+A new machine needs the selected runtime installed before status and guards can
+run. `gsd-path --runtime-restore --project /absolute/project --source-root
+/path/to/matching/package` restores that exact version without changing project
+files. The supplied package must match both the version and digest; custom source
+builds may share a release version while having different digests. No command
+silently substitutes a newer runtime, and status/guards never install or download.
+
+For an old tracked `.gsd-path/runtime/`, run `gsd-path --runtime-migrate --project
+/absolute/project --dry-run`, then the same command without `--dry-run` and review
+the Git diff. Migration removes the generated files from the checkout and writes
+the declaration and stable wiring. It does not stage or commit. Resolve local
+runtime edits or unknown files first. Interrupted migration is recovered by the
+same explicit command; its journal lives outside the checkout.
+
+To migrate and then update skills and project wiring in one invocation, follow
+[Legacy project runtime](UPDATE.md#legacy-project-runtime) for wizard consent,
+unattended commands, dry-run scope, and recovery after an update failure.
+
+An ignore rule alone cannot migrate tracked runtime files. This runtime lifecycle
+covers runtime code and launch wiring; project-local skill copies, retained skill
+backups, and mixed user/host settings remain separately owned installation output.

package/FULL.md

@@ -131,8 +131,9 @@ Install shared rules into a repo (refuses if managed files already exist):
 node scripts/install.mjs --all --project /path/to/project
 ```
 
-Writes `AGENTS.md`, `WORKFLOW.md`, and `.gsd-path/runtime/`; with Claude, also
-`.claude/CLAUDE.md`.
+Writes the [project contracts](DOCS.md#installing); with Claude, also
+`.claude/CLAUDE.md`. See [project runtime versions](DOCS.md#project-runtime-versions)
+for runtime storage, restoration, and legacy migration.
 Merge upgrades manually — the installer will not overwrite existing contracts.
 
 ### Guard hooks (optional)

package/HOOKS.md

@@ -59,9 +59,10 @@ Native configs for unselected hosts are ignored.
 
 | File | Purpose |
 | --- | --- |
-| `.gsd-path/guard_hook.py` | Pre-tool-use guard (stdin JSON → exit 2 + denial JSON) |
+| `.gsd-path/guard_hook.py` | Pre-tool-use guard (stdin JSON → exit 2 + denial JSON; runtime resolution failures exit 2 with stderr) |
 | `.gsd-path/git_guard.py` | Commit and publication validator |
-| `.gsd-path/runtime/` | Project-local pipeline helpers, including the read-only status engine |
+| `.gsd-path/runtime.json` | Tracked selected runtime version and digest |
+| `~/.gsd-path/runtimes/<digest>/` | Immutable external pipeline helpers and guards |
 | `.git/hooks/pre-commit` | Runs `git_guard.py` before commit |
 | `.git/hooks/commit-msg` | Runs `git_guard.py` with commit message |
 | `.git/hooks/pre-push` | Runs `git_guard.py` on every pushed ref update |
@@ -114,6 +115,12 @@ See [UPDATE.md](UPDATE.md).
 
 **`guard_hook.py`** (pre-tool-use):
 
+- direct product edits outside the routed build phase while milestone work
+  remains unfinished. After integration is verified, ordinary branches allow
+  product edits, including a dirty product worktree. The proof still checks
+  the shipped archive, canonical integration merge, annotated published tag,
+  and default-branch ancestry. Missing proof keeps protection active. Closed
+  milestone branches, archives, and pipeline control files remain protected.
 - non-read tool actions targeting archived paths or an existing ancestor of
   the archive tree; shell operands count an ancestor only for deletion or move
   commands
@@ -137,7 +144,7 @@ See [UPDATE.md](UPDATE.md).
 - shell commands that reference the archive unless the whole command is a
   recognized standalone read or a single-command invocation of the bundled
   `pipeline_state.py` / `archive_milestone.py` helper, resolved to a regular file
-  inside the guard-owned `.gsd-path/runtime/` directory (beside `guard_hook.py`
+  inside the verified runtime selected by `.gsd-path/runtime.json` (legacy projects use `.gsd-path/runtime/` beside `guard_hook.py`
   in the repository layout), using exactly `python` or `python3` with optional
   `-B`; non-empty supplied tool working directories are authoritative. Empty
   strings, including list items, are treated as absent: nested payloads inherit
@@ -176,16 +183,18 @@ such as `rm -rf scratch` passes the archive check; other guard rules still apply
 
 - modifies, deletes, or renames away tracked archive paths
 - `ship:` commits (case-insensitive) staging paths outside `.project/`
-- on unshipped pipeline lineage (the committed `STATE.md` names a bound
-  `gsd-path/M###` branch that is not `shipped/done`, and HEAD descends from
-  it — the bound branch itself, `gsd-path-task/` branches, sidecars, and any
-  branch cut from them): commits staging paths outside `.project/` (or the
+- while committed `STATE.md` names unfinished milestone work, including
+  `shipped/done` without verified integration: commits staging paths outside `.project/` (or the
   guard's own `.gsd-path/` and native hook settings) unless the phase is
   `build` and they are landing commits as `isolation.py land` writes them —
   subject `<task id>: <task title>` matching the task file at `Base:`, a full
   base SHA HEAD descends from, the staged task file, only that task's declared
   `files:`, and a `Files:` list of exactly the staged paths. Outside build the
-  reviewed HEAD is frozen; product fixes reopen through the patch plan
+  reviewed HEAD is frozen; product fixes reopen through the patch plan.
+  The validated integration merge is allowed to complete before publication
+  proof exists; an ordinary commit with an integration subject is not exempt
+- deleting the recorded branch or switching to another branch while carrying
+  unfinished state does not release product commit protection
 - pushes (to any remote) that move a `gsd-path/M###` ref anywhere but its
   strict ship commit, or delete it while it holds anything else; and pushes of
   any other ref whose commit carries a `STATE.md` that still owes a ship commit
@@ -268,6 +277,6 @@ not intercept subagent tools — treat coverage as orchestrator-level.
 | Tool denied editing archive | Pre-tool guard — use active paths, not archive |
 | Hook not running in Cursor | Run `--hooks-refresh-full --cursor --project /path/to/repo` |
 | `--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) |
 
 More: [DOCS.md](DOCS.md#help) · [UPDATE.md](UPDATE.md)

package/QUICK.md

@@ -64,12 +64,11 @@ cd /path/to/your/repo
 node scripts/install.mjs --all --project "$(pwd)"
 ```
 
-Installs `AGENTS.md`, `WORKFLOW.md`, and `.gsd-path/runtime/`
+Installs the [project contracts](DOCS.md#installing)
 (+ `.claude/CLAUDE.md` if Claude is selected).
 If those managed files already exist, a plain install **refuses and installs
-nothing** — use `--update --project PATH` to refresh skills and `.gsd-path/`
-while keeping your contracts, and merge project-contract changes by hand
-([UPDATE.md](UPDATE.md)).
+nothing** — use [the update guide](UPDATE.md) for existing installations,
+including [legacy runtime migration during upgrades](UPDATE.md#legacy-project-runtime).
 
 **Optional** archive/git guards:
 

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.3.0](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.3.0) — [release notes](CHANGELOG.md#130---2026-09-21)
+
+**Recent highlights**
+- migrate legacy runtimes during upgrades
+- validate installer changes without live host reruns
+- preserve closed review cycles in host recovery
+- clarify owner gates and accept serial task release evidence
+- Clarify receipt reuse and consolidate release policy guidance
+
+<!-- /release-docs -->
+
 ## Documentation
 
 **Start at [DOCS.md](DOCS.md)** — install, use, understand, and update in one hub.
@@ -27,10 +39,39 @@ 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
@@ -85,28 +126,54 @@ 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; it does not run pipeline commands or advance phase gates.
+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
-top toolbar to filter or search projects, refresh status, and open Settings for
-watched folders, plugin management, and appearance.
+[dashboard controls](daemon/README.md#dashboard) to filter or search projects,
+switch between Board and Milestones, refresh status, and manage settings.
 
-![OpenGSD Path dashboard showing sample projects, phase progress, and toolbar controls](docs/images/dashboard-board.png)
+![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 milestone progress, criteria, tasks, and usage with sample data](docs/images/dashboard-project.png)
+![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
 

package/RUNTIME.md

@@ -74,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
@@ -83,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
@@ -93,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

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.
@@ -97,6 +98,32 @@ node scripts/install.mjs --update --claude --cursor
 
 `--update` only refreshes hosts that **already have** GSD Path installed.
 
+### Legacy project runtime
+
+The interactive npm installer detects the old `.gsd-path/runtime/` layout when
+you choose to update project wiring. Choose **Migrate and continue upgrade** to
+migrate first, then update skills and wiring. Cancelling leaves the installation
+unchanged. Migration preserves locally modified files by stopping for you to
+resolve them; it never stages or commits changes.
+
+For unattended upgrades, migration requires explicit consent:
+
+```bash
+npx @opengsd/gsd-path@latest --update --runtime-migrate --project "/absolute/project" --dry-run
+npx @opengsd/gsd-path@latest --update --runtime-migrate --project "/absolute/project"
+```
+
+The combined dry run previews migration only and writes nothing. The real command
+migrates, then validates and applies the update. These are separate operations:
+if the update fails, the completed migration remains as an unstaged Git diff.
+Review it with `git status --short` and `git diff` in the project.
+
+Migration is needed once per project. For later updates, omit `--runtime-migrate`.
+For runtime selection after migration, see
+[Project runtime versions](DOCS.md#project-runtime-versions).
+Without migration consent, legacy project updates stop before writing files and
+print the exact migration command.
+
 ### After updating
 
 1. Restart your agent session (hosts reload skills on session start).
@@ -120,16 +147,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 +208,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 +231,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

@@ -97,8 +97,11 @@ 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**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Disk-backed AI agent pipeline. Docs: DOCS.md (start here), QUICK.md, FULL.md, UPDATE.md",
   "license": "MIT",
   "repository": {
@@ -19,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",
@@ -26,6 +27,7 @@
     "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",
@@ -40,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",
@@ -59,6 +64,7 @@
     "scripts/pipeline_undo.py",
     "scripts/pipeline_diagnose.py",
     "README.md",
+    "CHANGELOG.md",
     "MIGRATE.md",
     "RUNTIME.md",
     "DOCS.md",
@@ -86,6 +92,8 @@
     "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": {