@opengsd/gsd-path 1.3.0 → 1.3.1

package/CHANGELOG.md

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

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.3.0](https://www.npmjs.com/package/@opengsd/gsd-path/v/1.3.0) — [release notes](CHANGELOG.md#130---2026-09-21)
+**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**
-- 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
+- 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

@@ -103,8 +103,8 @@ node scripts/install.mjs --update --claude --cursor
 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.
+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:
 
@@ -160,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.3.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; add --update to continue upgrading\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" +

package/scripts/install.py

@@ -2839,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

@@ -235,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}")
@@ -249,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
@@ -257,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})
@@ -278,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