@opengsd/gsd-path 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -66,3 +66,22 @@ are documented here. Format follows [Keep a Changelog](https://keepachangelog.co
 - 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

@@ -405,6 +405,10 @@ 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/QUICK.md

@@ -67,11 +67,8 @@ node scripts/install.mjs --all --project "$(pwd)"
 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** — see [project runtime versions](DOCS.md#project-runtime-versions)
-for legacy migration, then use `--update --project PATH` to refresh skills and
-hook wiring while keeping your contracts and selected runtime. Merge 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

@@ -16,14 +16,14 @@ Support means the installer and dispatch contract exist. See the
 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)
+**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**
-- 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
+- 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 -->
 

package/UPDATE.md

@@ -98,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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.2.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": {

package/scripts/install.mjs

@@ -1655,7 +1655,7 @@ function usage() {
     "  --hooks-init          add guards to an existing project without changing its contracts\n" +
     "  --runtime-restore     restore the exact declared runtime from --source-root\n" +
     "  --runtime-upgrade     explicitly select the supplied package runtime\n" +
-    "  --runtime-migrate     migrate a tracked legacy runtime for review\n" +
+    "  --runtime-migrate     migrate a tracked legacy runtime for review; add --update to continue upgrading\n" +
     "  --hooks-refresh       validate the selected runtime; keep its version\n" +
     "  --hooks-refresh-full  refresh native settings/git hooks; target flags create missing configs\n" +
     "  --dry-run             preview without writing\n" +
@@ -1684,6 +1684,8 @@ export async function main(argv, env = process.env) {
       colored: !process.env.NO_COLOR,
       version: packageVersion(),
       targets: TARGETS,
+      legacyRuntime: lexists(path.join(process.cwd(), ".gsd-path", "runtime")) &&
+        !lexists(path.join(process.cwd(), ".gsd-path", "runtime.json")),
       installed: (target, local) =>
         hasManagedInstall(local ? localRoot(target, process.cwd()) : defaultRoot(target, env)),
     });
@@ -1695,7 +1697,12 @@ export async function main(argv, env = process.env) {
     : path.resolve(SCRIPT_DIRECTORY, "..");
   const project =
     values.project !== undefined ? absolutePath(values.project) : null;
-  if (["runtime-restore", "runtime-upgrade", "runtime-migrate"].some(name => values[name])) {
+  const migrateAndUpdate = values["runtime-migrate"] && values.update;
+  if (migrateAndUpdate && (project === null || values["runtime-restore"] || values["runtime-upgrade"] || values.doctor || values["hooks-init"] || values["hooks-refresh"] || values["hooks-refresh-full"])) {
+    ui.error("--runtime-migrate --update requires --project and cannot be combined with another runtime, doctor, or hook operation");
+    return 2;
+  }
+  if (!migrateAndUpdate && ["runtime-restore", "runtime-upgrade", "runtime-migrate"].some(name => values[name])) {
     const interpreter = requiredPythonRuntime("project runtime");
     const result = spawnSync(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
       ...argv.filter(arg => arg !== "--no-color")], { stdio: "inherit", env });
@@ -1800,6 +1807,21 @@ export async function main(argv, env = process.env) {
   } else {
     plans = selected.map((target) => targetPlan(target, rootFor(target)));
   }
+  if (migrateAndUpdate) {
+    const interpreter = requiredPythonRuntime("project runtime");
+    const migration = spawnSync(interpreter, ["-B", path.join(SCRIPT_DIRECTORY, "install.py"),
+      "--runtime-migrate", "--project", project, "--source-root", sourceRoot,
+      ...(values["dry-run"] ? ["--dry-run"] : [])], { stdio: "inherit", env });
+    if (migration.error || migration.status !== 0) {
+      if (migration.error) ui.error(migration.error.message);
+      return migration.status ?? 1;
+    }
+    if (values["dry-run"]) {
+      ui.result("Migration preview only; nothing was written. Run without --dry-run to migrate, then validate and apply the update.");
+      return 0;
+    }
+    ui.result("Migration completed. Review the unstaged Git diff. Updating skills and wiring next; an update failure will retain the completed migration.");
+  }
   const spin = ui.spinner("Preparing");
   try {
     const results = await install(sourceRootForInstall, plans, {

package/scripts/install.py

@@ -2641,17 +2641,16 @@ def install(
 
     if project is not None:
         _validate_directory_destination(project, "project path")
-        if dry_run:
-            _validate_project(
-                source_root,
-                project,
-                selected,
-                hooks,
-                [*mutation_roots, *planned_backups],
-                interpreter,
-                hooks_dir,
-                update,
-            )
+        _validate_project(
+            source_root,
+            project,
+            selected,
+            hooks,
+            [*mutation_roots, *planned_backups],
+            interpreter,
+            hooks_dir,
+            update,
+        )
 
     results = []
     with tempfile.TemporaryDirectory(prefix="gsd-path-install-") as temporary:

package/scripts/runtime_store.py

@@ -6,6 +6,7 @@ import json
 import os
 from pathlib import Path
 import shutil
+import shlex
 import tempfile
 from contextlib import contextmanager
 
@@ -135,7 +136,9 @@ def prepare(source, project, *, dry_run=False):
         status_runtime.validate_runtime(pin)
         return pin
     if os.path.lexists(project / ".gsd-path/runtime"):
-        raise ValueError("legacy project runtime requires --runtime-migrate --project PATH; migration produces a reviewable Git diff")
+        raise ValueError("legacy project runtime requires explicit migration before updating; run: "
+                         f"npx @opengsd/gsd-path@latest --runtime-migrate --project {shlex.quote(str(project.resolve()))}; "
+                         "then retry the update. Migration produces a reviewable Git diff")
     return publish(source, dry_run=dry_run)
 
 

package/scripts/wizard.mjs

@@ -125,7 +125,7 @@ const confirm = (io, theme, title, yes = "Yes", no = "No") =>
 
 // Pure: runs the question flow and returns install.mjs argv (or null if cancelled).
 // `installed(target, local)` reports whether a managed install already exists for that host in that scope.
-export async function wizard({ input, output, colored = true, version = "", cwd = process.cwd(), installed = () => false, targets }) {
+export async function wizard({ input, output, colored = true, version = "", cwd = process.cwd(), installed = () => false, legacyRuntime = false, targets }) {
   const theme = makeTheme(colored);
   const keys = keyReader(input);
   const io = { keys, output };
@@ -147,8 +147,13 @@ export async function wizard({ input, output, colored = true, version = "", cwd
       hostItems.some((item) => item.checked && hosts.includes(item.value)) &&
       (await confirm(io, theme, "Existing installs found. What do you want to do?", "Update in place", "Fresh install"));
 
-    const project = await confirm(io, theme, "Write AGENTS.md + WORKFLOW.md contracts into this repo?", `Yes — ${cwd}`, "Not now");
+    const project = await confirm(io, theme, update ? "Refresh this project's wiring (keep its contracts and selected runtime)?" : "Write AGENTS.md + WORKFLOW.md contracts into this repo?", `Yes — ${cwd}`, "Not now");
     const hooks = project && (await confirm(io, theme, "Install guard hooks (archive immutability, ship-commit purity)?"));
+    const migrate = project && update && legacyRuntime;
+    if (migrate) {
+      output.write(`\n  This project uses the old runtime layout. Migration moves managed runtime files\n  outside the repo and leaves an unstaged Git diff for review. Local edits are preserved.\n`);
+      if (!(await confirm(io, theme, "Migrate this project before updating?", "Migrate and continue upgrade", "Cancel"))) return null;
+    }
 
     const argv = [];
     if (hosts.length === targets.length) argv.push("--all");
@@ -157,6 +162,7 @@ export async function wizard({ input, output, colored = true, version = "", cwd
     if (local) argv.push("--local");
     if (project) argv.push("--project", cwd);
     if (hooks) argv.push("--hooks");
+    if (migrate) argv.push("--runtime-migrate");
 
     output.write(`\n  ${theme.dim("Equivalent command:")}\n  ${theme.accent("$")} gsd-path ${argv.join(" ")}\n`);
     const go = await select(io, theme, "Ready?", [