@opengsd/gsd-path 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -66,3 +66,35 @@ 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
+
+## [1.3.1] - 2026-09-22
+
+### Changed
+- Clarify legacy runtime backup guidance
+- Consolidate legacy runtime migration guidance
+- prepare 1.3.1 patch candidate
+- Clarify legacy runtime migration documentation
+- update release notes for v1.3.0
+
+### Fixed
+- describe untracked legacy migration in help
+- preserve older untracked runtimes during migration

package/DOCS.md

@@ -398,12 +398,19 @@ files. The supplied package must match both the version and digest; custom sourc
 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
+For an old `.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.
+edits to tracked runtime files or unknown files first. When untracked managed
+files differ from the supplied package, migration saves those files' original
+bytes under `~/.gsd-path/runtime-migrations/backups/` and prints the backup
+directory for review. 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

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.1](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.3.1) — [release notes](CHANGELOG.md#131---2026-09-22)
 
 **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
+- describe untracked legacy migration in help
+- preserve older untracked runtimes during migration
+- Clarify legacy runtime backup guidance
+- Consolidate legacy runtime migration guidance
+- prepare 1.3.1 patch candidate
 
 <!-- /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. See [Project runtime versions](DOCS.md#project-runtime-versions)
+for migration safety checks and backups. Migration 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).
@@ -134,8 +160,8 @@ 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.
+version-pinned runtimes. Migration leaves a reviewable Git diff; the dashboard
+shows the failure reason when it stops.
 See [Project runtime versions](DOCS.md#project-runtime-versions) for manual
 migration and preview commands. Use `--doctor --project PATH` to check runtime files.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-path",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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 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:
@@ -2840,6 +2839,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 _release_install_locks(locks, created)
             print(f"runtime: {runtime_action} {pin['version']} ({pin['digest']})"
                   + (" (dry run)" if arguments.dry_run else ""))
+            if pin.get("backup"):
+                print(f"legacy runtime backup: {pin['backup']}")
             return 0
         except (InstallerError, OSError, ValueError) as error:
             print(f"error: {error}", file=sys.stderr)

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)
 
 
@@ -232,6 +235,7 @@ def operate(source, project, action, *, dry_run=False):
         raise ValueError("legacy runtime contains unknown files; preserve and resolve them before migration")
     managed = entries + [project / ".gsd-path/status_runtime.py"]
     managed += [project / ".gsd-path" / n for n in GUARDS if (project / ".gsd-path" / n).exists()]
+    divergent = []
     for path in managed:
         if path.is_symlink() or not path.is_file():
             raise ValueError(f"unsafe migration file: {path}")
@@ -246,7 +250,7 @@ def operate(source, project, action, *, dry_run=False):
             if clean.stdout:
                 raise ValueError(f"locally modified migration file: {path}")
         elif path.read_bytes() != (source / "scripts" / path.name).read_bytes():
-            raise ValueError(f"untracked migration file differs from source: {path}")
+            divergent.append(path)
     pin = publish(source, dry_run=dry_run)
     if dry_run:
         return pin
@@ -254,6 +258,17 @@ def operate(source, project, action, *, dry_run=False):
     declaration = project / ".gsd-path/runtime.json"
     if os.path.lexists(declaration):
         raise ValueError("runtime declaration already exists; refusing legacy migration")
+    backup = None
+    if divergent:
+        backup_root = migration_journal(project).parent / "backups"
+        if backup_root.is_symlink():
+            raise ValueError(f"unsafe runtime migration backup directory: {backup_root}")
+        backup_root.mkdir(parents=True, exist_ok=True)
+        backup = Path(tempfile.mkdtemp(prefix="legacy-", dir=backup_root))
+        for path in divergent:
+            saved = backup / path.relative_to(project / ".gsd-path")
+            saved.parent.mkdir(parents=True, exist_ok=True)
+            saved.write_bytes(originals[path])
     updates = {project / ".gsd-path/status_runtime.py": (source / "scripts/status_runtime.py").read_bytes(),
                declaration: pin_text(pin).encode()}
     updates.update({p: None for p in entries})
@@ -275,4 +290,4 @@ def operate(source, project, action, *, dry_run=False):
         recover_migration(project)
         raise
     journal.unlink()
-    return pin
+    return {**pin, "backup": str(backup)} if backup else pin

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?", [