@opengsd/gsd-path 1.1.0 → 1.3.0

package/skills/gsd-path-discuss/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())

package/skills/gsd-path-discuss/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())