@opengsd/gsd-path 1.1.0 → 1.2.0

package/skills/gsd-path-inspect/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":

package/skills/gsd-path-inspect/scripts/worktree_paths.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Placement shared by task isolation, verification, and integration."""
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+try:
+    import _common
+except ImportError:
+    from scripts import _common
+
+
+def _git(primary: Path, *args: str) -> str:
+    result = _common.run_git(primary, *args)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "cannot inspect worktree placement")
+    return result.stdout.rstrip("\n")
+
+
+def _identity(path: Path) -> str:
+    return hashlib.sha256(os.fsencode(path)).hexdigest()
+
+
+def _workspace(primary: Path, pin: bool) -> Path:
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    identity = _identity(primary)
+    receipt = common / "gsd-path" / "workspaces" / f"{identity}.json"
+    try:
+        data = json.loads(receipt.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        pass
+    else:
+        if (not isinstance(data, dict) or data.get("primary") != str(primary)
+                or not isinstance(data.get("root"), str)
+                or not Path(data["root"]).is_absolute()):
+            raise ValueError(f"invalid worktree placement receipt: {receipt}")
+        return Path(data["root"])
+
+    root = Path(os.environ.get("GSD_PATH_WORKTREE_ROOT") or Path.home() / ".gsd-path" / "projects").expanduser()
+    if not root.is_absolute():
+        raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
+    root = root.resolve()
+    parent = root
+    while not parent.exists():
+        parent = parent.parent
+    ancestor = _common.run_git(parent, "rev-parse", "--git-common-dir")
+    same_repository = (
+        ancestor.returncode == 0
+        and (parent / ancestor.stdout.strip()).resolve() == common
+    )
+    if root.is_relative_to(primary) or same_repository:
+        raise ValueError(f"managed worktree root must be outside this repository's worktrees: {root}")
+    workspace = root / _identity(common) / identity
+    if pin:
+        receipt.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(dir=receipt.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"primary": str(primary), "root": str(workspace)}, handle)
+            try:
+                os.link(temporary, receipt)
+            except FileExistsError:
+                return _workspace(primary, False)
+        finally:
+            os.unlink(temporary)
+    return workspace
+
+
+def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    primary = primary.resolve()
+    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+        raise ValueError("invalid managed worktree kind or name")
+    legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
+              if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
+    branch = f"refs/heads/gsd-path-{kind}/{name}"
+    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    for record in records:
+        fields = record.split("\0")
+        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+            return legacy
+    # Keep collision checks and missing-directory recovery at the old location.
+    if os.path.lexists(legacy):
+        return legacy
+    return _workspace(primary, pin) / kind / name

package/skills/gsd-path-loop/SKILL.md

@@ -3,6 +3,8 @@ name: gsd-path-loop
 description: Use only when the user explicitly invokes $gsd-path-loop. Runs one bounded loop pass from a LOOP.md spec — gate checks, independent verification, one fix worker, telemetry. Autonomy lives in the external scheduler that invokes this skill; the skill never schedules itself.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Loop
 
 One invocation = one bounded pass. The bundled deterministic helper

package/skills/gsd-path-loop/references/runtime-selection.md

@@ -0,0 +1,25 @@
+# Project runtime selection
+
+Before running a project runtime helper, check for
+`<absolute-project>/.gsd-path/runtime.json`. When present, run the stable launcher:
+
+```sh
+python3 -B <absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project> --runtime-path
+```
+
+Use `python` only when it is the compatible Python 3.9+ interpreter. A failure
+stops helper execution: follow the exact-version restore action in the error.
+Do not install, upgrade, or fall back to the current plugin's runtime implicitly.
+
+The returned directory is the verified Project runtime. Resolve helper names
+present in its `manifest.json` from that directory, including status, state,
+isolation, integration, archive, recovery, build-state, final-verification, and guard helpers.
+The workflow runner resolves its subprocess helpers from this same directory;
+helper imports stay within the selected runtime. This rule overrides
+references to bundled copies of those helpers. Other skill helpers, templates,
+and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
+invocations so execution does not create bytecode in the runtime store.
+
+With no declaration, retain the legacy helper lookup. An existing
+`.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
+operation before adopting external storage; review the resulting Git diff.

package/skills/gsd-path-loop/scripts/_common.py

@@ -9,6 +9,11 @@ consuming module keep working.
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import os
 import re

package/skills/gsd-path-loop/scripts/discussion_records.py

@@ -7,6 +7,9 @@ import json
 import os
 import shutil
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path

package/skills/gsd-path-loop/scripts/loop_run.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Deterministic gates for a GSD Path LOOP.md loop spec.
 
 The loop skill (a model) reads the prose sections of a LOOP.md; this helper
@@ -23,6 +24,7 @@ import os
 import re
 import subprocess
 import sys
+sys.dont_write_bytecode = True
 import time
 import uuid
 from contextlib import contextmanager

package/skills/gsd-path-loop/scripts/model_policy.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Resolve explicit sub-agent model choices without model reasoning."""
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+sys.dont_write_bytecode = True
+from pathlib import Path
+
+try:
+    from ._common import atomic_write
+    from .loop_run import log_lock
+    from .review_panel import family_of_slug
+except ImportError:
+    from _common import atomic_write
+    from loop_run import log_lock
+    from review_panel import family_of_slug
+
+FIELDS = ('model', 'effort')
+HEAVY = ('plan', 'plan_patch', 'decide', 'roadmap')
+LIGHT = ('inspect_docs', 'docs_audit')
+SCHEMA = 'gsd-path/model-selection/v1'
+
+
+class PolicyError(ValueError):
+    """An explicit selection cannot be honored."""
+
+
+def object_value(value, label):
+    if not isinstance(value, dict):
+        raise PolicyError(f'{label} must be an object')
+    return value
+
+
+def read_json(path):
+    try:
+        return object_value(json.loads(Path(path).read_text(encoding='utf-8')), str(path))
+    except (OSError, ValueError) as error:
+        raise PolicyError(f'{path}: {error}') from error
+
+
+def settings(value, label):
+    object_value(value, label)
+    if set(value) - set(FIELDS):
+        raise PolicyError(f'{label}: unknown model setting')
+    for field, setting in value.items():
+        if not isinstance(setting, str) or not setting.strip() or setting != setting.strip():
+            raise PolicyError(f'{label}.{field} must be a nonempty string (or inherit)')
+    return value
+
+
+def policy_path(repo, project_dir):
+    project = Path(repo) / project_dir
+    return (project.parent if project.name == 'next' else project) / 'model-policy.json'
+
+
+def load_policy(repo, project_dir):
+    path = policy_path(repo, project_dir)
+    data = read_json(path) if path.exists() else {}
+    if set(data) - {'roles', 'hosts'}:
+        raise PolicyError(f'{path}: unknown policy field')
+    groups = [('roles', object_value(data.get('roles', {}), 'roles'))]
+    for host, group in object_value(data.get('hosts', {}), 'hosts').items():
+        groups.append((f'hosts.{host}', object_value(group, f'hosts.{host}')))
+    for label, group in groups:
+        for role, choice in group.items():
+            settings(choice, f'{label}.{role}')
+    return data
+
+
+def resolve(repo, project_dir, role, capabilities, overrides, previous=None):
+    """Resolve each field once; a saved selection bypasses changed project policy."""
+    caps = object_value(capabilities, 'capabilities')
+    host = caps.get('host')
+    if not isinstance(host, str) or not host:
+        raise PolicyError(f'{role}: host identity is required for model selection')
+    if previous is not None:
+        if (previous.get('schema'), previous.get('role'), previous.get('host')) != (SCHEMA, role, host):
+            raise PolicyError(f'{role}: recorded selection belongs to another role or host')
+        selected = dict(previous['selected'])
+        sources = dict(previous['sources'])
+        policy_hash = previous['policy_hash']
+        for field, value in settings(overrides, 'task').items():
+            if value != selected[field]:
+                raise PolicyError(f'explicit {field}={value!r} differs from the pinned selection; reassign explicitly')
+        if (selected['model'] == 'inherit' and previous.get('effective_model')
+                and caps.get('inherited_model') != previous['effective_model']):
+            raise PolicyError('recorded inherited model no longer matches the advertised identity')
+    else:
+        policy = load_policy(repo, project_dir)
+        try:
+            from .path_config import user_defaults
+        except ImportError:
+            from path_config import user_defaults
+        try:
+            defaults = user_defaults().get('models', {})
+        except (OSError, ValueError, RuntimeError) as error:
+            raise PolicyError(str(error)) from error
+        selected = dict.fromkeys(FIELDS, 'inherit')
+        sources = dict.fromkeys(FIELDS, 'default')
+        tier = 'heavy' if role in HEAVY else 'light' if role in LIGHT else None
+        hint = ('high' if tier == 'heavy' else 'low') if host == 'codex' and tier else tier
+        hint = caps.get('effort_hints', {}).get(tier, hint)
+        if hint in caps.get('effort', {}).get('values', []):
+            selected['effort'] = hint
+        for label, group in (
+            (f'user.roles.{role}', defaults.get('roles', {}).get(role, {})),
+            (f'user.hosts.{host}.{role}', defaults.get('hosts', {}).get(host, {}).get(role, {})),
+            (f'roles.{role}', policy.get('roles', {}).get(role, {})),
+            (f'hosts.{host}.{role}', policy.get('hosts', {}).get(host, {}).get(role, {})),
+            ('task', settings(overrides, 'task')),
+        ):
+            for field, value in group.items():
+                selected[field], sources[field] = value, label
+        policy_hash = hashlib.sha256(json.dumps({'user': defaults, 'project': policy}, sort_keys=True).encode()).hexdigest()
+    native, cli, controls = {}, {}, {}
+    for field, value in selected.items():
+        spec = object_value(caps.get(field, {}), f'capabilities.{field}')
+        controls[field] = spec.get('args', [])
+        if value == 'inherit':
+            cli[field] = []
+            continue
+        if value not in spec.get('values', []):
+            raise PolicyError(f'{role}: {sources[field]} requests {field}={value!r}, unavailable on {host}')
+        native_field = spec.get('field')
+        if native_field:
+            if not isinstance(native_field, str) or not re.fullmatch(r'[A-Za-z_]\w*', native_field):
+                raise PolicyError(f'{host}: invalid native field for {field}')
+            if native_field in native:
+                raise PolicyError(f'{host}: model and effort use the same native field')
+            native[native_field] = value
+        args = spec.get('args', [])
+        if not isinstance(args, list) or any(not isinstance(arg, str) for arg in args):
+            raise PolicyError(f'{host}: {field} args must be an argument list')
+        if args and not any('{value}' in arg for arg in args):
+            raise PolicyError(f'{host}: {field} args must deliver {{value}}')
+        cli[field] = [arg.replace('{value}', value) for arg in args]
+    return {'schema': SCHEMA, 'role': role, 'host': host, 'selected': selected,
+            'sources': sources, 'native': native, 'cli': cli, 'controls': controls, 'policy_hash': policy_hash,
+            'effective_model': (selected['model'] if selected['model'] != 'inherit'
+                                else caps.get('inherited_model')),
+            'identity_evidence': 'requested controls; host execution is recorded by the dispatcher'}
+
+
+def validate_panel(selection, family, excluded=()):
+    model = selection['effective_model']
+    actual = family_of_slug(model) if model else None
+    if actual != family or actual in excluded:
+        raise PolicyError(f'panel model {model!r} must belong to independent family {family}')
+
+
+def command_args(argv, selection):
+    """Expand whole-argument slots only. Never parse or rewrite arbitrary host commands."""
+    result = list(argv)
+    if any('{model}' in arg for arg in result):
+        raise PolicyError('legacy model placeholder is incompatible with capability-based dispatch')
+    for field in FIELDS:
+        slot = '{' + field + '_args}'
+        explicit = selection['sources'][field] != 'default'
+        args = selection['cli'][field]
+        # Only match the controls declared by the adapter, not guessed CLI syntax.
+        templates = selection['controls'][field]
+        prefixes = [arg.split('{value}')[0] for arg in templates if '{value}' in arg and arg != '{value}']
+        flags = [arg for arg in templates if arg.startswith('-') and '{value}' not in arg]
+        if any(any(arg.startswith(prefix) for prefix in prefixes)
+               or (not prefixes and any(arg == flag or arg.startswith(flag + '=') for flag in flags))
+               for arg in result):
+            raise PolicyError(f'fixed {field} controls conflict with policy selection')
+        if result.count(slot) > 1 or any(slot in arg and arg != slot for arg in result):
+            raise PolicyError(f'{slot} must occur once as a whole argument')
+        if slot not in result:
+            if explicit:
+                raise PolicyError(f'explicit {field} requires a {slot} slot in the child command')
+            if selection['selected'][field] != 'inherit':
+                raise PolicyError(f'{field} hint requires a {slot} slot in the child command')
+            continue
+        if selection['selected'][field] != 'inherit' and not args:
+            raise PolicyError(f'host does not advertise CLI arguments for {field}')
+        index = result.index(slot)
+        result[index:index + 1] = args
+    return result
+
+
+def task_settings(path):
+    # Reuse the task contract parser; nested or duplicate overrides are not accepted.
+    try:
+        from .check_handoffs import _strict_frontmatter
+    except ImportError:
+        from check_handoffs import _strict_frontmatter
+    fields = _strict_frontmatter(Path(path).read_text(encoding='utf-8'), str(path))
+    return settings({key: fields[key] for key in FIELDS if key in fields}, str(path))
+
+
+def native_record(args):
+    """The parent owns lifecycle; release requires its recorded terminal-result receipt."""
+    record = args.record.resolve()
+    with log_lock({'log': str(record)}):
+        data = read_json(record) if record.exists() else None
+        identity = {'repo': str(args.repo.resolve()), 'project_dir': args.project_dir,
+                    'scope': args.scope, 'assignment': args.assignment, 'role': args.role}
+        if data is not None and data.get('identity') != identity:
+            raise PolicyError('record belongs to another assignment or milestone/track/cycle')
+        if args.action == 'release':
+            if data is None or not args.terminal_result:
+                raise PolicyError('release requires an existing record and terminal-result evidence')
+            data.update(active=False, terminal_result=args.terminal_result)
+        else:
+            if args.capabilities is None:
+                raise PolicyError('capabilities are required')
+            if args.action == 'reassign' and (data is None or data['active'] or not args.ruling):
+                raise PolicyError('reassign requires an inactive assignment and an explicit owner ruling')
+            caps = read_json(args.capabilities)
+            overrides = task_settings(args.task) if args.task else {}
+            for field in FIELDS:
+                value = getattr(args, field)
+                if value is not None:
+                    if field in overrides and overrides[field] != value:
+                        raise PolicyError('reassignment conflicts with the approved task contract')
+                    overrides[field] = value
+            if data and args.action == 'reassign':
+                changed_fields = set(overrides)
+                overrides = dict(data['selection']['selected'], **overrides)
+            previous = data['selection'] if data and args.action == 'resolve' else None
+            selection = resolve(args.repo, args.project_dir, args.role, caps, overrides, previous)
+            if data and args.action == 'reassign':
+                for field in FIELDS:
+                    if field not in changed_fields:
+                        selection['sources'][field] = data['selection']['sources'][field]
+            if (args.panel_family and selection['sources']['model'] == 'default'
+                    and selection['selected']['model'] == 'inherit' and args.panel_model):
+                selection = resolve(args.repo, args.project_dir, args.role, caps,
+                                    dict(overrides, model=args.panel_model), previous)
+            for field in FIELDS:
+                if selection['selected'][field] != 'inherit' and not caps.get(field, {}).get('field'):
+                    raise PolicyError(f'host does not advertise a native field for {field}')
+            if args.panel_family:
+                validate_panel(selection, args.panel_family, args.exclude_family)
+            history = data.get('history', []) if data else []
+            if data and args.action == 'reassign':
+                history = [*history, {'selection': data['selection'], 'ruling': args.ruling,
+                                     'terminal_result': data.get('terminal_result')}]
+            data = {'identity': identity, 'selection': selection, 'history': history,
+                    'active': args.action == 'resolve'}
+        atomic_write(record, json.dumps(data, indent=2, sort_keys=True) + '\n')
+        return {'status': 'ready', **data}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=('resolve', 'release', 'reassign'))
+    parser.add_argument('--repo', type=Path, required=True)
+    parser.add_argument('--project-dir', default='.project')
+    parser.add_argument('--scope', required=True, help='milestone, track and review cycle identity')
+    parser.add_argument('--assignment', required=True)
+    parser.add_argument('--role', required=True)
+    parser.add_argument('--record', type=Path, required=True)
+    parser.add_argument('--capabilities', type=Path)
+    parser.add_argument('--task', type=Path)
+    parser.add_argument('--model')
+    parser.add_argument('--effort')
+    parser.add_argument('--ruling')
+    parser.add_argument('--terminal-result')
+    parser.add_argument('--panel-family')
+    parser.add_argument('--panel-model', help='default model from the panel roster; policy may override it')
+    parser.add_argument('--exclude-family', action='append', default=[])
+    try:
+        result = native_record(parser.parse_args(argv))
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        print(json.dumps({'status': 'blocked', 'reason': str(error)}))
+        return 1
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())