@opengsd/gsd-path 1.1.0 → 1.3.0

package/scripts/path_config.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Show and edit Path preferences without advancing a pipeline phase."""
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True
+
+ROLES = ('coder', 'reviewer', 'review_panel', 'skeptic', 'inspect_codebase',
+         'inspect_docs', 'docs_audit', 'research', 'decide', 'roadmap', 'plan', 'plan_patch')
+HOSTS = ('codex', 'claude', 'grok', 'opencode', 'copilot', 'qwen', 'antigravity',
+         'cursor', 'zed', 'kiro', 'kimi')
+
+
+def sibling(name):
+    import importlib
+    return importlib.import_module(f'{__package__}.{name}' if __package__ else name)
+
+
+def safe_path(path):
+    # Resolve host aliases (macOS /var) at the repo/home boundary, not here.
+    for item in (path, path.parent):
+        if item.is_symlink():
+            raise ValueError(f'unsafe symlink: {item}')
+    if path.exists() and (not path.is_file() or path.stat().st_nlink != 1):
+        raise ValueError(f'expected a regular unlinked file: {path}')
+    return path
+
+
+def read_object(path):
+    safe_path(path)
+    if not path.exists():
+        return {}
+    value = json.loads(path.read_text(encoding='utf-8'))
+    if not isinstance(value, dict):
+        raise ValueError(f'{path} must contain an object')
+    return value
+
+
+def user_path():
+    return Path.home().resolve() / '.gsd-path/config.json'
+
+
+def model_key(key):
+    bits = key.split('.')
+    if len(bits) == 4 and bits[:2] == ['models', 'roles']:
+        role, field = bits[2:]
+    elif len(bits) == 5 and bits[:2] == ['models', 'hosts'] and bits[2] in HOSTS:
+        role, field = bits[3:]
+    else:
+        raise ValueError(f'unknown setting: {key}')
+    if role not in ROLES or field not in ('model', 'effort'):
+        raise ValueError(f'unknown setting: {key}')
+    return bits
+
+
+def flatten(data, prefix=''):
+    result = {}
+    for key, value in data.items():
+        name = f'{prefix}.{key}' if prefix else key
+        if isinstance(value, dict):
+            result.update(flatten(value, name))
+        else:
+            result[name] = value
+    return result
+
+
+def validate_value(key, value):
+    if not isinstance(value, str) or not value or value != value.strip():
+        raise ValueError(f'{key} requires a nonempty string')
+    if key == 'integration':
+        if value not in ('direct', 'pull-request'):
+            raise ValueError('integration must be direct or pull-request')
+    elif key == 'review_panel':
+        if any(char.isspace() for char in value):
+            raise ValueError('use off, detected, or comma-separated families without spaces')
+        sibling('review_panel').parse_review_panel_value(value)
+    else:
+        model_key(key)
+
+
+def validate_models(data):
+    if not isinstance(data, dict) or set(data) - {'roles', 'hosts'}:
+        raise ValueError('models must contain roles and/or hosts')
+    for group, entries in data.items():
+        if not isinstance(entries, dict):
+            raise ValueError(f'models.{group} must be an object')
+        groups = [('roles', entries)] if group == 'roles' else [(f'hosts.{host}', roles) for host, roles in entries.items()]
+        for prefix, roles in groups:
+            if not isinstance(roles, dict) or (prefix.startswith('hosts.') and prefix[6:] not in HOSTS):
+                raise ValueError(f'unknown or malformed model group: {prefix}')
+            for role, fields in roles.items():
+                if role not in ROLES or not isinstance(fields, dict):
+                    raise ValueError(f'unknown or malformed role: {role}')
+                for field, value in fields.items():
+                    validate_value(f'models.{prefix}.{role}.{field}', value)
+    return data
+
+
+def preferences(path, user=False):
+    data = read_object(path)
+    allowed = {'integration', 'review_panel', 'models'} if user else {'review_panel'}
+    if set(data) - allowed:
+        raise ValueError(f'{path}: unknown setting')
+    for key, value in data.items():
+        if key == 'models':
+            validate_models(value)
+        else:
+            validate_value(key, value)
+    return data
+
+
+def user_defaults():
+    return preferences(user_path(), user=True)
+
+
+def initial_state(text):
+    mode = user_defaults().get('integration', 'direct')
+    for key in ('integration_default', 'integration'):
+        text = re.sub(rf'(?m)^{key}: direct\b', f'{key}: {mode}', text)
+    return text
+
+
+def show(repo, scope='project'):
+    defaults = user_defaults()
+    values = {'integration': {'value': defaults.get('integration', 'direct'),
+                              'source': str(user_path()) if 'integration' in defaults else 'built-in'},
+              'review_panel': {'value': defaults.get('review_panel', 'off'),
+                               'source': str(user_path()) if 'review_panel' in defaults else 'built-in'}}
+    models = {key: {'value': value, 'source': str(user_path())}
+              for key, value in flatten(defaults.get('models', {}), 'models').items()}
+    result = {'scope': scope, 'settings': values, 'models': models, 'roles': ROLES,
+              'hosts': HOSTS, 'locked': None, 'approved_review_panel': None}
+    if scope == 'project':
+        state_api = sibling('pipeline_state')
+        repo = state_api._repo_root(repo)
+        state, text, path = state_api.load_state(repo)
+        config = repo / '.project/config.json'
+        local = preferences(config)
+        if 'review_panel' in local:
+            values['review_panel'] = {'value': local['review_panel'], 'source': str(config)}
+        policy_path = repo / '.project/model-policy.json'
+        policy = validate_models(read_object(policy_path))
+        models.update({key: {'value': value, 'source': str(policy_path)}
+                       for key, value in flatten(policy, 'models').items()})
+        values['integration'] = {'value': state.integration_default, 'source': str(path),
+                                 'current': state.integration, 'current_source': state.integration_source}
+        locked = state.phase in ('build', 'ship', 'shipped') or sibling('build_recovery').context(repo, text)
+        values['integration']['locked'] = 'Shipping mode is locked when build starts.' if locked else None
+        if state.phase in ('ship', 'shipped') or state.archive:
+            result['locked'] = 'Project settings are locked during ship and after shipment.'
+        panel = sibling('review_panel')
+        paths = [repo / '.project/plan/PLAN.md', repo / '.project/intent/INTENT.md', repo / '.project/CHARTER.md']
+        texts = [p.read_text(encoding='utf-8') if safe_path(p).exists() else None for p in paths]
+        approved = panel.parse_sources(*texts)
+        result['approved_review_panel'] = {'value': ','.join(approved['families']) if approved['mode'] == 'named' else approved['mode'],
+                                          'source': approved['source']}
+    return result
+
+
+def set_value(repo, scope, key, value, reset=False):
+    repo = repo.resolve()
+    if not reset:
+        validate_value(key, value)
+    elif key not in ('integration', 'review_panel'):
+        model_key(key)
+    current = show(repo, scope)
+    if current['locked']:
+        raise ValueError(current['locked'])
+    if scope == 'project':
+        state, _, _ = sibling('pipeline_state').load_state(repo)
+        branch = subprocess.run(['git', '-C', str(repo), 'branch', '--show-current'],
+                                capture_output=True, text=True)
+        if branch.returncode or not state.branch or branch.stdout.strip() != state.branch:
+            raise ValueError('Run the router to bind the project branch before editing settings.')
+        head = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--verify', 'HEAD'], capture_output=True)
+        if head.returncode == 0:
+            closed = subprocess.run([sys.executable, '-B', str(Path(__file__).with_name('git_guard.py')),
+                                     'closed-milestone'], cwd=repo, capture_output=True, text=True)
+            if closed.returncode:
+                raise ValueError(closed.stderr.strip() or 'Cannot verify the milestone branch is open.')
+    if scope == 'project' and key == 'integration':
+        if reset:
+            raise ValueError('choose an explicit project shipping mode')
+        sibling('pipeline_state').configure_integration(repo, 'default', value)
+        return show(repo, scope)
+    path = user_path() if scope == 'user' else repo / '.project' / ('model-policy.json' if key.startswith('models.') else 'config.json')
+    safe_path(path)
+    safe_path(path.with_name(f'.{path.name}.lock'))
+    lock = (sibling('pipeline_state')._state_lock(repo / '.project') if scope == 'project'
+            else sibling('loop_run').log_lock({'log': str(path)}))
+    with lock:
+        current = show(repo, scope)
+        if current['locked']:
+            raise ValueError(current['locked'])
+        data = read_object(path)
+        bits = key.split('.')
+        if scope == 'project' and bits[0] == 'models':
+            bits = bits[1:]
+        node = data
+        for bit in bits[:-1]:
+            node = node.setdefault(bit, {})
+        if reset:
+            node.pop(bits[-1], None)
+        else:
+            node[bits[-1]] = value
+        safe_path(path)
+        safe_path(path.with_name(f'.{path.name}.gsd-path-tmp'))
+        sibling('_common').atomic_write(path, json.dumps(data, indent=2, sort_keys=True) + '\n')
+    return show(repo, scope)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=('show', 'validate', 'set', 'reset'))
+    parser.add_argument('key', nargs='?')
+    parser.add_argument('value', nargs='?')
+    parser.add_argument('--scope', choices=('user', 'project'), default='project')
+    parser.add_argument('--repo', type=Path, default=Path.cwd())
+    args = parser.parse_args()
+    try:
+        declaration = args.repo / '.gsd-path/runtime.json'
+        if args.scope == 'project' and (declaration.exists() or declaration.is_symlink()):
+            runtime = sibling('status_runtime').resolve_runtime(args.repo.resolve())
+            helper = runtime / 'path_config.py'
+            if not helper.is_file():
+                raise ValueError('Update the selected project runtime to use Path settings.')
+            if helper.resolve() != Path(__file__).resolve():
+                return subprocess.call([sys.executable, '-B', str(helper), *sys.argv[1:]])
+        if args.action in ('set', 'reset'):
+            if not args.key or (args.action == 'set' and args.value is None):
+                raise ValueError('set requires KEY VALUE; reset requires KEY')
+            result = set_value(args.repo, args.scope, args.key, args.value, args.action == 'reset')
+        else:
+            result = show(args.repo, args.scope)
+        print(json.dumps(result))
+        return 0
+    except (OSError, ValueError, RuntimeError) as error:
+        print(json.dumps({'error': str(error)}))
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/scripts/pipeline_diagnose.py

@@ -12,6 +12,9 @@ import argparse
 import json
 import shlex
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Callable, Optional, Sequence
 

package/scripts/pipeline_git.py

@@ -17,6 +17,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Optional, Sequence
 

package/scripts/pipeline_state.py

@@ -19,6 +19,9 @@ import shutil
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from dataclasses import asdict, dataclass
 from datetime import date
 from pathlib import Path, PurePosixPath
@@ -615,7 +618,7 @@ def _completion_status(repo: Path, state: Mapping[str, object], project_dir: str
         import integration
     try:
         proof = integration.validate_integrated(
-            repo, str(state.get("milestone") or ""), refresh=False)
+            repo, str(state.get("milestone") or ""), refresh=False, historical=True)
     except (integration.ArchiveError, OSError) as error:
         return {"status": "unverified", "reason": str(error)}
     return {"status": "verified", "proof": proof}

package/scripts/pipeline_undo.py

@@ -17,6 +17,9 @@ import os
 import re
 import shutil
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 import tempfile
 from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence

package/scripts/promote_lookahead.py

@@ -12,6 +12,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Optional, Sequence
 

package/scripts/review_panel.py

@@ -15,6 +15,9 @@ import argparse
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path
 from typing import Iterable, Optional, Sequence
 
@@ -214,6 +217,7 @@ def resolve_panel(
     advertised: Sequence[str],
     parent_family: Optional[str] = None,
     parent_slug: Optional[str] = None,
+    excluded_families: Sequence[str] = (),
 ) -> dict:
     inferred_parent = parent_family or (
         family_of_slug(parent_slug) if parent_slug else None
@@ -244,7 +248,12 @@ def resolve_panel(
             "named review_panel families are not advertised: " + ", ".join(missing)
         )
 
+    if config["mode"] == "named" and set(wanted) & set(excluded_families):
+        raise ReviewPanelError("named review_panel must use an independent family")
     for family in wanted:
+        if family in excluded_families:
+            skipped.append({"family": family, "reason": "excluded reviewer family"})
+            continue
         if family == inferred_parent:
             skipped.append({"family": family, "reason": "parent family"})
             continue
@@ -488,6 +497,7 @@ def parser() -> argparse.ArgumentParser:
     result.add_argument("--advertised", default="")
     result.add_argument("--parent-family")
     result.add_argument("--parent-slug")
+    result.add_argument("--exclude-family", action="append", choices=KNOWN_FAMILIES, default=[])
     result.add_argument("--kind", choices=("plan", "wave"))
     result.add_argument("--inputs", default="")
     result.add_argument("--output", type=Path)
@@ -541,6 +551,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             split_csv(arguments.advertised),
             arguments.parent_family,
             arguments.parent_slug,
+            arguments.exclude_family,
         )
         return emit(resolved)
     except ReviewPanelError as error:

package/scripts/roadmap.py

@@ -3,6 +3,11 @@
 """Interpret Roadmap text for selection, approval, promotion and milestone close."""
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import re
 from typing import Optional
 

package/scripts/runtime_store.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Own immutable project runtimes, explicit upgrades, restoration and migration."""
+import hashlib
+import base64
+import json
+import os
+from pathlib import Path
+import shutil
+import shlex
+import tempfile
+from contextlib import contextmanager
+
+try:
+    from . import status_runtime
+except ImportError:
+    import status_runtime
+
+RUNTIME_FILES = (
+    "pipeline_state.py", "roadmap.py", "check_handoffs.py", "check_task_briefs.py",
+    "isolation.py", "discussion_records.py", "pipeline_git.py", "promote_lookahead.py",
+    "detect_project.py", "pipeline_diagnose.py", "pipeline_undo.py", "archive_milestone.py",
+    "review_panel.py", "_common.py", "worktree_paths.py", "build_recovery.py",
+    "state_checkpoint.py", "state_promote.py", "discussion_validate.py", "integration.py",
+    "build_state.py", "lean_verification.py", "check_docs_audit.py",
+    "path_config.py", "model_policy.py", "loop_run.py",
+)
+GUARDS = ("guard_hook.py", "git_guard.py")
+
+
+def guard_launcher(name):
+    if name not in GUARDS:
+        raise ValueError("unknown runtime guard")
+    return ("#!/usr/bin/env python3\n# gsd-path guard — stable runtime launcher\n"
+            "import sys\nsys.dont_write_bytecode = True\nfrom pathlib import Path\n"
+            "from status_runtime import run_guard\n"
+            "try:\n"
+            f"    run_guard(Path(__file__).resolve().parent.parent, {name!r})\n"
+            "except (OSError, ValueError) as error:\n"
+            "    print(str(error), file=sys.stderr)\n"
+            f"    raise SystemExit({2 if name == 'guard_hook.py' else 1})\n")
+
+
+def source_manifest(source):
+    version = json.loads((source / "package.json").read_text())["version"]
+    files = {}
+    for name in (*RUNTIME_FILES, *GUARDS, "status_runtime.py"):
+        path = source / "scripts" / name
+        if path.is_symlink():
+            raise ValueError(f"symlinked runtime source: {path}")
+        files[name] = hashlib.sha256(path.read_bytes()).hexdigest()
+    manifest = {"version": version, "files": files}
+    pin = {"schema": status_runtime.RUNTIME_SCHEMA, "version": version,
+           "digest": status_runtime.manifest_digest(manifest)}
+    return manifest, pin
+
+
+def pin_text(pin):
+    return json.dumps(pin, indent=2, sort_keys=True) + "\n"
+
+
+@contextmanager
+def publication_lock(parent, digest):
+    """The OS releases this external lock even if publication is interrupted."""
+    lock = parent / ("." + digest + ".lock")
+    if lock.is_symlink():
+        raise ValueError(f"unsafe runtime publication lock: {lock}")
+    descriptor = os.open(lock, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        if os.name == "nt":
+            import msvcrt
+            if os.fstat(descriptor).st_size == 0:
+                os.write(descriptor, b"\0")
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        yield
+    finally:
+        os.close(descriptor)
+
+
+def publish(source, *, expected=None, dry_run=False, repair=False):
+    manifest, pin = source_manifest(source)
+    if expected is not None and any(pin[key] != expected.get(key) for key in pin):
+        raise ValueError(f"source does not match declared runtime {expected['version']} ({expected['digest']}); use its matching package")
+    if dry_run:
+        return pin
+    parent = status_runtime.runtime_home()
+    if any(p.is_symlink() for p in (parent, parent.parent)):
+        raise ValueError(f"unsafe runtime storage: {parent}")
+    parent.mkdir(parents=True, exist_ok=True)
+    destination = parent / pin["digest"]
+    if destination.is_symlink():
+        raise ValueError(f"unsafe runtime storage: {destination}")
+    if destination.exists():
+        try:
+            status_runtime.validate_runtime(pin)
+            return pin
+        except ValueError:
+            if not repair:
+                raise
+    with tempfile.TemporaryDirectory(prefix=".runtime-stage-", dir=parent) as temporary:
+        staging = Path(temporary) / "runtime"
+        staging.mkdir()
+        for name, digest in manifest["files"].items():
+            shutil.copyfile(source / "scripts" / name, staging / name)
+            if hashlib.sha256((staging / name).read_bytes()).hexdigest() != digest:
+                raise ValueError(f"runtime source changed while installing: {name}")
+        (staging / "manifest.json").write_text(pin_text(manifest), encoding="utf-8")
+        # Serialize publication/repair, including two explicit restorations.
+        previous = Path(temporary) / "previous"
+        with publication_lock(parent, pin["digest"]):
+            if destination.exists():
+                try:
+                    status_runtime.validate_runtime(pin)
+                    return pin
+                except ValueError:
+                    if not repair:
+                        raise
+                    destination.rename(previous)
+            try:
+                staging.rename(destination)
+                status_runtime.validate_runtime(pin)
+            except BaseException:
+                if previous.exists() and not destination.exists():
+                    previous.rename(destination)
+                raise
+    return pin
+
+
+def prepare(source, project, *, dry_run=False):
+    declaration = project / ".gsd-path/runtime.json"
+    if os.path.lexists(declaration):
+        pin = status_runtime.declaration(project)
+        status_runtime.validate_runtime(pin)
+        return pin
+    if os.path.lexists(project / ".gsd-path/runtime"):
+        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)
+
+
+def atomic_config(path, content):
+    if path.is_symlink() or path.parent.is_symlink():
+        raise ValueError(f"unsafe project runtime configuration: {path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(prefix=f".{path.name}.gsd-path-tmp-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(content.encode("utf-8"))
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def migration_journal(project):
+    identity = hashlib.sha256(os.fsencode(project.resolve())).hexdigest()
+    return Path.home() / ".gsd-path" / "runtime-migrations" / (identity + ".json")
+
+
+def recover_migration(project):
+    journal = migration_journal(project)
+    if not os.path.lexists(journal):
+        return
+    if journal.is_symlink():
+        raise ValueError(f"unsafe runtime migration journal: {journal}")
+    data = json.loads(journal.read_text())
+    recorded_project = data.get("project")
+    if (data.get("schema") != "gsd-path/runtime-migration/v1"
+            or not isinstance(recorded_project, str)
+            or Path(recorded_project).resolve() != project.resolve()):
+        raise ValueError(f"invalid runtime migration journal: {journal}")
+    allowed = {".gsd-path/runtime.json", ".gsd-path/status_runtime.py"}
+    allowed.update(".gsd-path/" + n for n in GUARDS)
+    allowed.update(".gsd-path/runtime/" + n for n in RUNTIME_FILES)
+    entries = data.get("files")
+    if not isinstance(entries, dict) or not set(entries) <= allowed:
+        raise ValueError(f"invalid runtime migration paths: {journal}")
+    # Refuse to overwrite edits made after interruption.
+    for relative, change in entries.items():
+        path = project / relative
+        if path.is_symlink() or path.parent.is_symlink():
+            raise ValueError(f"unsafe migration recovery path: {path}")
+        current = base64.b64encode(path.read_bytes()).decode() if path.exists() else None
+        if current not in (change["before"], change["after"]):
+            raise ValueError(f"migration recovery would overwrite a changed file: {path}")
+    for relative, change in entries.items():
+        path = project / relative
+        if change["before"] is None:
+            path.unlink(missing_ok=True)
+        else:
+            atomic_config(path, base64.b64decode(change["before"]).decode("utf-8"))
+    journal.unlink()
+
+
+def operate(source, project, action, *, dry_run=False):
+    if project.is_symlink() or (project / ".gsd-path").is_symlink():
+        raise ValueError("unsafe project runtime directory")
+    if action == "restore":
+        pin = status_runtime.declaration(project)
+        publish(source, expected=pin, dry_run=dry_run, repair=True)
+        return pin
+    if action == "upgrade":
+        status_runtime.declaration(project)
+        pin = publish(source, dry_run=dry_run)
+        if not dry_run:
+            launcher = project / ".gsd-path/status_runtime.py"
+            original = launcher.read_text(encoding="utf-8")
+            replacement = (source / "scripts/status_runtime.py").read_text(encoding="utf-8")
+            # Both launchers understand the same declaration schema. Publishing
+            # the compatible launcher first leaves the old selection usable.
+            if replacement != original:
+                atomic_config(launcher, replacement)
+            try:
+                atomic_config(project / ".gsd-path/runtime.json", pin_text(pin))
+            except BaseException:
+                if replacement != original:
+                    atomic_config(launcher, original)
+                raise
+        return pin
+    if action != "migrate":
+        raise ValueError("unknown runtime operation")
+    # Migration changes only reviewed managed files and never stages or commits.
+    import subprocess
+    if not dry_run:
+        recover_migration(project)
+    runtime = project / ".gsd-path/runtime"
+    if runtime.is_symlink() or not runtime.is_dir():
+        raise ValueError("migration requires a real legacy runtime directory")
+    entries = list(runtime.iterdir())
+    if {p.name for p in entries} - set(RUNTIME_FILES):
+        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()]
+    for path in managed:
+        if path.is_symlink() or not path.is_file():
+            raise ValueError(f"unsafe migration file: {path}")
+        marker = ("gsd-path project runtime" if path.parent == runtime else
+                  "gsd-path project status launcher" if path.name == "status_runtime.py" else "gsd-path guard")
+        if marker not in path.read_text(encoding="utf-8"):
+            raise ValueError(f"unmanaged migration file: {path}")
+        relative = path.relative_to(project).as_posix()
+        tracked = subprocess.run(["git", "ls-files", "--error-unmatch", "--", relative], cwd=project, capture_output=True)
+        if tracked.returncode == 0:
+            clean = subprocess.run(["git", "status", "--porcelain", "--", relative], cwd=project, capture_output=True, check=True)
+            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}")
+    pin = publish(source, dry_run=dry_run)
+    if dry_run:
+        return pin
+    originals = {p: p.read_bytes() for p in managed}
+    declaration = project / ".gsd-path/runtime.json"
+    if os.path.lexists(declaration):
+        raise ValueError("runtime declaration already exists; refusing legacy migration")
+    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})
+    updates.update({p: guard_launcher(p.name).encode() for p in managed if p.name in GUARDS})
+    changes = {p.relative_to(project).as_posix(): {
+        "before": base64.b64encode(originals[p]).decode() if p in originals else None,
+        "after": base64.b64encode(content).decode() if content is not None else None,
+    } for p, content in updates.items()}
+    journal = migration_journal(project)
+    atomic_config(journal, pin_text({"schema": "gsd-path/runtime-migration/v1", "project": str(project.resolve()), "files": changes}))
+    try:
+        for path, content in updates.items():
+            if content is None:
+                path.unlink()
+            else:
+                atomic_config(path, content.decode("utf-8"))
+        runtime.rmdir()
+    except BaseException:
+        recover_migration(project)
+        raise
+    journal.unlink()
+    return pin