@opengsd/gsd-path 1.1.0 → 1.2.0

package/skills/path/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/skills/path/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/skills/path/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/skills/path/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/skills/path/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/skills/path/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/skills/path/scripts/state_checkpoint.py

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import hashlib
 import json
 import os

package/skills/path/scripts/state_promote.py

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil

package/skills/path/scripts/status_runtime.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Launch the project status runtime across an atomic refresh handoff."""
+
+import argparse
+import hashlib
+import errno
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Sequence
+
+PROJECT_STATUS_MARKER = "gsd-path project status launcher"
+INSTALL_LOCK_OWNER = "owner.json"
+INSTALL_LOCK_SCHEMA = "gsd-path/install-lock/v2"
+
+
+def process_identity(pid: int):
+    if os.name == "nt":
+        command = [
+            "powershell.exe",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            f"(Get-Process -Id {pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks",
+        ]
+    else:
+        command = ["ps", "-o", "lstart=", "-p", str(pid)]
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=False)
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return f"{os.name}:{value}" if result.returncode == 0 and value else None
+
+
+def runtime_identity(runtime: Path):
+    try:
+        status = runtime.stat()
+    except FileNotFoundError:
+        return None
+    return (status.st_dev, status.st_ino, status.st_mtime_ns, status.st_size)
+
+
+def process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError as error:
+        return error.errno == errno.EPERM
+    return True
+
+
+def install_lock_active(lock: Path) -> bool:
+    if lock.is_symlink() or not lock.is_dir():
+        return False
+    try:
+        owner = json.loads((lock / INSTALL_LOCK_OWNER).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return False
+    pid = owner.get("pid")
+    valid_pid = isinstance(pid, int) and not isinstance(pid, bool) and pid > 0
+    identity = owner.get("identity")
+    if (
+        owner.get("schema") != INSTALL_LOCK_SCHEMA
+        or not valid_pid
+        or not isinstance(identity, str)
+    ):
+        return False
+    current_identity = process_identity(pid)
+    if current_identity is None:
+        return process_alive(pid)
+    return current_identity == identity
+
+
+RUNTIME_SCHEMA = "gsd-path/runtime/v1"
+
+
+def runtime_home() -> Path:
+    return Path.home() / ".gsd-path" / "runtimes"
+
+
+def declaration(repo: Path) -> dict:
+    path = repo / ".gsd-path" / "runtime.json"
+    if path.is_symlink() or path.parent.is_symlink():
+        raise ValueError(f"unsafe runtime declaration: {path}")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if (not isinstance(data, dict) or data.get("schema") != RUNTIME_SCHEMA
+            or not isinstance(data.get("version"), str)
+            or not isinstance(data.get("digest"), str)
+            or len(data["digest"]) != 64
+            or any(c not in "0123456789abcdef" for c in data["digest"])):
+        raise ValueError(f"invalid runtime declaration: {path}")
+    return data
+
+
+def manifest_digest(manifest: dict) -> str:
+    return hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def validate_runtime(data: dict) -> Path:
+    root = runtime_home() / data["digest"]
+    hint = (f"Runtime {data['version']} ({data['digest']}) is unavailable or invalid at {root}. "
+            "Run gsd-path --runtime-restore --project <project-root> "
+            "--source-root <matching-package-root> to restore this exact runtime.")
+    try:
+        if any(p.is_symlink() for p in (root, root.parent, root.parent.parent)):
+            raise ValueError("symlinked runtime storage")
+        manifest_path = root / "manifest.json"
+        if manifest_path.is_symlink():
+            raise ValueError("symlinked manifest")
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if (not isinstance(manifest, dict) or manifest_digest(manifest) != data["digest"]
+                or manifest.get("version") != data["version"]):
+            raise ValueError("manifest identity mismatch")
+        files = manifest.get("files")
+        if not isinstance(files, dict) or "pipeline_state.py" not in files:
+            raise ValueError("invalid runtime file inventory")
+        for name, expected in files.items():
+            if Path(name).name != name or not name.endswith(".py"):
+                raise ValueError("invalid runtime file name")
+            path = root / name
+            if path.is_symlink() or hashlib.sha256(path.read_bytes()).hexdigest() != expected:
+                raise ValueError(f"runtime file changed: {name}")
+        if set(p.name for p in root.iterdir()) != set(files) | {"manifest.json"}:
+            raise ValueError("unexpected runtime files")
+    except (OSError, ValueError, TypeError) as error:
+        raise ValueError(hint + f" ({error})") from error
+    return root
+
+
+def resolve_runtime(repo: Path) -> Path:
+    return validate_runtime(declaration(repo))
+
+
+def run_guard(repo: Path, name: str) -> None:
+    # Keep the guard's project identity while executing verified external bytes.
+    root = resolve_runtime(repo)
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(root))
+    code = compile((root / name).read_bytes(), str(root / name), "exec")
+    exec(code, {"__name__": "__main__", "__file__": str(repo / ".gsd-path" / name)})
+
+
+def launch(repo: Path) -> int:
+    parent = repo / ".gsd-path"
+    if os.path.lexists(parent / "runtime.json"):
+        try:
+            runtime = resolve_runtime(repo) / "pipeline_state.py"
+        except (OSError, ValueError) as error:
+            print(str(error), file=sys.stderr)
+            return 2
+        return subprocess.call([sys.executable, "-B", str(runtime), "status", "--repo", str(repo)],
+                               env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"})
+    runtime = parent / "runtime" / "pipeline_state.py"
+    lock = repo / ".gsd-path-install-lock"
+    command = [sys.executable, "-B", str(runtime), "status", "--repo", str(repo)]
+    environment = os.environ.copy()
+    environment["GIT_OPTIONAL_LOCKS"] = "0"
+    while True:
+        if install_lock_active(lock):
+            time.sleep(0.05)
+            continue
+        before = runtime_identity(runtime)
+        if before is None:
+            if install_lock_active(lock):
+                continue
+            if runtime_identity(runtime) is not None:
+                continue
+            if install_lock_active(lock):
+                continue
+            print(f"GSD Path status runtime is unavailable: {runtime}", file=sys.stderr)
+            return 2
+        try:
+            result = subprocess.run(
+                command, capture_output=True, check=False, env=environment
+            )
+        except OSError as error:
+            print(f"GSD Path status runtime failed: {error}", file=sys.stderr)
+            return 2
+        if install_lock_active(lock) or runtime_identity(runtime) != before:
+            continue
+        sys.stdout.write(result.stdout.decode())
+        sys.stderr.write(result.stderr.decode())
+        return result.returncode
+
+
+def main(argv: Sequence[str] = sys.argv[1:]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", required=True, type=Path)
+    parser.add_argument("--runtime-path", action="store_true")
+    args = parser.parse_args(argv)
+    if not args.repo.is_absolute():
+        print("GSD Path status repository must be absolute", file=sys.stderr)
+        return 2
+    if args.runtime_path:
+        try:
+            print(resolve_runtime(args.repo.resolve()))
+            return 0
+        except (OSError, ValueError) as error:
+            print(str(error), file=sys.stderr)
+            return 2
+    return launch(args.repo.resolve())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/path/scripts/workflow_run.py

@@ -4,6 +4,7 @@
 import argparse
 import hashlib
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -28,9 +29,10 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
     steps = []
     outputs = {}
     scripts = Path(__file__).resolve().parent
+    helpers = scripts
 
     def step(script, *arguments, raw=False):
-        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        command = [sys.executable, "-B", str(helpers / script), *arguments]
         completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
         receipt = {"script": script, "command": command, "exit_code": completed.returncode,
                    "stdout": completed.stdout, "stderr": completed.stderr}
@@ -49,6 +51,15 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
 
     common = ["--repo", str(repo), "--project-dir", project_dir]
     try:
+        if os.path.lexists(repo / ".gsd-path/runtime.json"):
+            resolved = subprocess.run(
+                [sys.executable, "-B", str(repo / ".gsd-path/status_runtime.py"),
+                 "--repo", str(repo), "--runtime-path"],
+                cwd=repo, capture_output=True, text=True)
+            if resolved.returncode:
+                sys.stderr.write(resolved.stderr)
+                raise StepFailed(resolved.stderr.strip())
+            helpers = Path(resolved.stdout.strip())
         if action == "route":
             step("pipeline_state.py", "route", *common)
         elif action == "prepare-inspect":