@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/gsd-path-build/scripts/workflow_run.py

@@ -2,9 +2,12 @@
 """Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
 
 import argparse
+import hashlib
 import json
+import os
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 try:
@@ -16,14 +19,20 @@ except ImportError:  # bundled copy inside a skill's scripts directory
 class StepFailed(RuntimeError):
     pass
 
+INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
+                    ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
+
 
 def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
-                 task_id: str = None, round_size: int = None) -> dict:
+                 task_id: str = None, round_size: int = None, inspection: Path = None,
+                 mapper_reviewed: bool = False) -> dict:
     steps = []
+    outputs = {}
     scripts = Path(__file__).resolve().parent
+    helpers = scripts
 
-    def step(script, *arguments):
-        command = [sys.executable, "-B", str(scripts / script), *arguments]
+    def step(script, *arguments, raw=False):
+        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}
@@ -32,6 +41,8 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             sys.stderr.write(completed.stderr)
         if completed.returncode:
             raise StepFailed(script)
+        if raw:
+            return completed.stdout
         try:
             receipt["result"] = json.loads(completed.stdout)
         except json.JSONDecodeError as error:
@@ -40,8 +51,114 @@ 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":
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if project_dir != ".project" or state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("initial inspection requires the active inspect track")
+            specs = INSPECTION_SPECS
+            if any((repo / project_dir / "research" / spec[3]).exists() or
+                   (repo / project_dir / "research" / spec[3]).is_symlink() for spec in specs):
+                raise StepFailed("prior inspection evidence requires the re-inspection contract")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if branch != state["branch"]:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            inventory = step("check_docs_audit.py", "--repo", str(repo), "--emit-inventory", raw=True)
+            resources = scripts.parent
+            if not (resources / "references").is_dir():
+                resources = resources / "skills/gsd-path"
+            for _, role, template, _ in specs:
+                for path in (resources / "references" / f"{role}.md", resources / "templates" / f"{template}.md"):
+                    if not path.is_file():
+                        raise StepFailed(f"missing inspection resource: {path}")
+            staging = Path(tempfile.mkdtemp(prefix="gsd-path-inspect-"))
+            inventory_file = staging / "inventory.txt"
+            inventory_file.write_text(inventory, encoding="utf-8")
+            assignments = []
+            for task_name, role, template, filename in specs:
+                isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
+                                "--base", expected_head, "--name", task_name.replace("_", "-"))
+                role_path = resources / "references" / f"{role}.md"
+                template_path = resources / "templates" / f"{template}.md"
+                output = f"{project_dir}/research/{filename}"
+                brief_file = staging / f"{task_name}.md"
+                brief = (f"Logical task: {task_name}\nRead and follow role: {role_path}\n"
+                         f"Template: {template_path}\nRepository and command cwd: {isolated['worktree']}\n"
+                         f"Recorded baseline and Audited HEAD: {isolated['base']}\n"
+                         f"Write only: {Path(isolated['worktree']) / output}\n"
+                         "Use only this supplied sidecar for project commands; do not create worktrees.\n"
+                         "The parent owns gates, collection, retirement, and phase state.\n"
+                         "Exclude .git, node_modules, .project/archive, and installed GSD Path and path skill bundles.\n")
+                if task_name == "inspect_docs":
+                    brief += ("Alignment mode: false. No prior audit or changed set.\n"
+                              "Frozen inventory follows; use it exactly, without rediscovery:\n" + inventory)
+                brief_file.write_text(brief, encoding="utf-8")
+                assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
+                                    "template": str(template_path), "output": output,
+                                    "brief_file": str(brief_file)})
+            receipt_file = staging / "inspection.json"
+            outputs["inspection"] = {"repo": str(repo), "base": expected_head,
+                                     "inventory_file": str(inventory_file),
+                                     "inventory_sha256": hashlib.sha256(inventory_file.read_bytes()).hexdigest(),
+                                     "assignments": assignments, "receipt_file": str(receipt_file)}
+            _common.atomic_write(receipt_file, json.dumps(outputs["inspection"], sort_keys=True) + "\n")
+        elif action == "finish-inspect":
+            if not mapper_reviewed or inspection is None or project_dir != ".project":
+                raise StepFailed("finish-inspect requires the prepared active track and mapper review")
+            prepared = json.loads(inspection.read_text(encoding="utf-8"))
+            if prepared["repo"] != str(repo) or prepared["base"] != expected_head:
+                raise StepFailed("inspection receipt does not match repository and expected HEAD")
+            assignments = {a["task_name"]: a for a in prepared["assignments"]}
+            if len(prepared["assignments"]) != len(INSPECTION_SPECS) or set(assignments) != {s[0] for s in INSPECTION_SPECS}:
+                raise StepFailed("inspection receipt must name both original assignments")
+            for task_name, _, _, filename in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                if assignment["base"] != expected_head or assignment["output"] != f".project/research/{filename}":
+                    raise StepFailed("inspection assignment changed its baseline or output")
+            inventory_file = Path(prepared["inventory_file"])
+            if hashlib.sha256(inventory_file.read_bytes()).hexdigest() != prepared["inventory_sha256"]:
+                raise StepFailed("frozen inspection inventory changed")
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("inspection completion requires inspect/active")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if state["branch"] != branch:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            docs = assignments["inspect_docs"]
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--audit", docs["output"],
+                 "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text().splitlines():
+                raise StepFailed("audit does not name the supplied inspection baseline")
+            for task_name, _, _, _ in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                step("isolation.py", "collect-artifact", "--repo", str(repo),
+                     "--source", assignment["worktree"], "--base", expected_head,
+                     "--branch", assignment["branch"], "--source-path", assignment["output"],
+                     "--destination-path", assignment["output"])
+                step("isolation.py", "retire", "--repo", str(repo), "--worktree", assignment["worktree"],
+                     "--branch", assignment["branch"])
+            expected = [part for key, value in state.items()
+                        for part in (f"--expect-{key}", "null" if value is None else str(value))]
+            step("pipeline_state.py", "transition", *common, *expected,
+                 "--set-phase", "inspect", "--set-status", "done", "--event", "inspection artifacts passed")
         elif action == "lint-round":
             head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
                                   cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
@@ -87,28 +204,31 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             if action == "approve-plan":
                 step("pipeline_state.py", "approve", *common, "--kind", "plan",
                      "--expected-head", expected_head)
-    except (StepFailed, OSError, subprocess.CalledProcessError) as error:
+    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
         return {"status": "blocked", "reason": str(error), "steps": steps,
                 "next": "$gsd-path-forensics"}
-    return {"status": "complete", "steps": steps}
+    return {"status": "complete", "steps": steps, **outputs}
 
 
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final"))
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"))
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
     parser.add_argument("--expected-head")
     parser.add_argument("--task-id")
     parser.add_argument("--round-size", type=int)
+    parser.add_argument("--inspection", type=Path)
+    parser.add_argument("--mapper-reviewed", action="store_true")
     arguments = parser.parse_args(argv)
-    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final"} and not arguments.expected_head:
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"} and not arguments.expected_head:
         parser.error(f"{arguments.action} requires --expected-head")
     if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
         parser.error("prepare-task requires --task-id and --round-size")
     result = run_workflow(arguments.repo.resolve(), arguments.action,
                           arguments.project_dir, arguments.expected_head,
-                          arguments.task_id, arguments.round_size)
+                          arguments.task_id, arguments.round_size, arguments.inspection,
+                          arguments.mapper_reviewed)
     print(json.dumps(result, sort_keys=True))
     return 0 if result["status"] == "complete" else 1
 

package/skills/gsd-path-build/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-build/templates/skeptic.md

@@ -1,7 +1,7 @@
 # Skeptic — wave <N>, cycle <C>
 
 <!-- Written by one finding-skeptic child. Advisory to fix-task batching
-     only: the inherit reviewer owns Wave verdict. -->
+     only: the canonical reviewer owns Wave verdict. -->
 
 - Criterion: <the failed criterion, verbatim from the lens file>
 - Criterion locator: <t001_ac2 | t001_files | sc3>

package/skills/gsd-path-build/templates/task.md

@@ -8,6 +8,8 @@ agent: null         # orchestrator-owned: set at dispatch
 base: null          # orchestrator-owned: clean layer SHA for isolated Verify
 worktree: null      # orchestrator-owned: isolated task worktree while active
 task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
+# Optional explicit dispatch overrides: model: <advertised slug|inherit>
+# effort: <advertised effort|inherit>
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

package/skills/gsd-path-build/templates/wave-panel.md

@@ -1,6 +1,6 @@
 # Panel — wave <N>, cycle <C>
 
-<!-- Written by one review-panel child. Advisory only: the inherit reviewer
+<!-- Written by one review-panel child. Advisory only: the canonical reviewer
      owns Wave verdict. Kind criterion may be presented to the user when
      Severity is high; preference stays a warning. -->
 

package/skills/gsd-path-build/templates/wave-review.md

@@ -17,7 +17,7 @@ Wave verdict: <pass | blocked — blocked if any task fails>
 Cycle: <C>
 Depth: <full | deep | verify-only — verify-only is orchestrator-written from
         its isolated Verify evidence; no independent reviewer ran>
-Lens: <contract | adversarial — deep reviews only; empty or omitted
+Lens: <contract | adversarial — deep reviews only; leave this value empty or omit the line
        otherwise>
 Tasks reviewed: <count>
 

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

@@ -3,6 +3,8 @@ name: gsd-path-decide
 description: Decide implementation direction from approved intent and complete research evidence, recording settled choices in SYNTHESIS.md. Use only when the user explicitly invokes $gsd-path-decide or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Decide Phase
 
 Dispatch one reasoning-intensive decider and validate its decision artifact.
@@ -98,12 +100,8 @@ rules are unchanged; never write an active-path artifact.
    branch and archive values, `--set-phase decide --set-status done`, and an
    event naming the validated synthesis path. Include `--project-dir
    .project/next` in lookahead and require returned `decide/done`. Confirm the
-   settled outcome, link SYNTHESIS.md again, and name
-   the next phase: the roadmap phase in program scope, planning otherwise.
-   When routed by an active `$gsd-path`, return control to
-   that router. When invoked directly, stop and tell the user to explicitly
-   invoke `$gsd-path`, which routes to that next phase; do not invoke an
-   explicit-only sibling skill yourself.
+   settled outcome, link SYNTHESIS.md again, and use the executable phase
+   handoff in AGENTS.md.
 
 ## Rules
 

package/skills/gsd-path-decide/references/dispatch.md

@@ -7,10 +7,7 @@ use exactly one matching branch:
 - A `spawn_agent` tool exposing `task_name`, `agent_type`, and `fork_turns` is
   Codex. Use `fork_turns: "none"`; coders use the built-in `worker` type and
   every other role uses `default`. Reuse a completed logical target with
-  `followup_task`. For Codex reasoning effort, use `high` for the portable
-  `heavy` tier and `low` for the portable `light` tier; leave reasoning effort
-  unset for the session-default tier, and never pass `heavy` or `light` as a
-  literal Codex value.
+  `followup_task`.
 - A `spawn_agent` tool without those Codex fields is Zed. Spawn one isolated,
   full-capability child per brief. Zed children are not resumable, so retries
   use a fresh child and a complete prompt.
@@ -26,7 +23,7 @@ use exactly one matching branch:
   the complete new prompt for later work. Wait for a colliding active child and
   collect results with `wait_commands_or_subagents`.
 - A `Task` tool advertising the custom `gsd-path` subagent is Cursor. Use that
-  model-inheriting, full-capability child. Resume it by returned agent ID when
+  full-capability child. Resume it by returned agent ID when
   available; otherwise retry with a fresh child and a complete prompt.
 - A `Task` tool advertising the built-in `general` subagent is OpenCode. Use
   that child; if an installed OpenCode v2 host exposes the renamed `subagent`
@@ -65,20 +62,10 @@ For every branch:
 - Resolve the phase's linked role brief to an absolute path, include it in the
   prompt, and require the child to read it before acting. The role brief
   supplies the read-only boundary for auditors and reviewers.
-- Tier hints: use the portable `heavy` tier for `plan`, `plan_patch`, `decide`,
-  and `roadmap`, the portable `light` tier for `inspect_docs` and `docs_audit`,
-  and the session-default tier for every other role. Apply the Codex mapping
-  above when its schema advertises reasoning-effort selection. On every other
-  host, use only an exact native equivalent advertised by that host; otherwise
-  do not override the model or reasoning effort. The only exception is a
-  review-panel child: when the host advertises model selection, pass the exact
-  slug returned by `scripts/review_panel.py resolve` for that family. Never
-  override the model on the canonical reviewer, planner, coder, or any other
-  role.
-  Host isolation: none. The child's working directory is the exact absolute
-  root GSD Path supplied; a host SHA checkout or extra worktree is a contract
-  failure. Never ask the host to create a worktree. Give the child the exact
-  repository or linked-worktree root supplied by GSD Path.
+- Model selection: before every child launch or continuation, follow
+  [the model-policy contract](model-policy.md) and apply its recorded
+  native arguments. It owns defaults, project settings, task overrides,
+  capability failures, and reassignment. Host isolation: none. Use the exact GSD Path supplied root; create no extra checkout.
 - Send a self-contained prompt with absolute input, template, and output paths
   plus the child's bounded responsibility. Every brief also names the absolute
   `AGENTS.md` and `WORKFLOW.md` paths (or explicitly says they are absent), the
@@ -122,6 +109,12 @@ directory for the full logical session; resumptions reuse it. Record completed
 parent CLI run events and each native child's session events with stable logical
 task names before the next dispatch. The helper reads host counters and refuses
 incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 Run `admit` for the next task and stop dispatch on a blocked result. Preserve
 its output in the dispatch evidence. This gates observed usage only: concurrent
 or in-flight work can overrun before the host reports usage. Codex CLI has no

package/skills/gsd-path-decide/references/model-policy.md

@@ -0,0 +1,139 @@
+# Dispatch model policy
+
+Before native dispatch, run the bundled `scripts/model_policy.py`. CLI dispatch
+uses the same resolver inside `dispatch_driver.py`. The helper owns model and
+effort decisions; apply its output instead of choosing again in prose.
+
+## Project choices
+
+Use `<repo>/.project/model-policy.json`, including when the active track is
+`.project/next`. This file owns project overrides. It is not phase status.
+No file is required to retain existing behavior. `path config` can also set user
+defaults in `~/.gsd-path/config.json` under `models`. Project common roles override
+user host and common roles. Within each scope, host roles override common roles.
+Task overrides still win, and recorded assignments stay pinned.
+
+```json
+{
+  "roles": {"coder": {"model": "inherit"}},
+  "hosts": {"codex": {"plan": {"effort": "high"}}}
+}
+```
+
+Values are exact advertised model/effort strings or `inherit`. This example
+illustrates configuration; it is not a cost-saving preset. Set concrete models
+only from the current host's advertised choices. Host-specific role settings
+override common role settings. Task settings override both, independently for
+model and effort; omitted fields retain the next applicable value. Explicit
+`inherit` removes that field's override. There are no automatic fallbacks.
+
+Role keys are `coder`, `reviewer` (wave, final, and gap review), `review_panel`,
+`skeptic`, `inspect_codebase`, `inspect_docs`, `docs_audit`, `research`, `decide`,
+`roadmap`, `plan`, and `plan_patch`. Use the logical task name as the assignment,
+not as the role. Keep each panel family and review lens a distinct assignment.
+
+The helper retains heavy effort hints for plan, plan_patch, decide, and roadmap;
+light hints for inspect_docs and docs_audit; otherwise effort inherits. Codex
+maps these hints to high/low. Other hosts use only advertised equivalents.
+Hints are conditional; unsupported explicit settings stop the affected child.
+
+Coders may have scalar `model:` and `effort:` fields in their task frontmatter.
+These are part of the approved task contract. Pass the task file with `--task`.
+For other roles, pass assignment-specific `--model` or `--effort` when the owner
+explicitly overrides the role choice. Coder settings do not affect reviewers.
+
+## Advertised capabilities
+
+Capture the current child tool's schema and advertised choices in a JSON file
+outside the product tree. For each supported control, provide its native field,
+allowed values, and, for CLI dispatch, its documented argument template. Omit
+unsupported controls. The values below are fixture examples, not a host catalog:
+
+```json
+{
+  "host": "codex",
+  "model": {"field": "model", "values": ["example-model"],
+            "args": ["--model", "{value}"]},
+  "effort": {"field": "reasoning_effort", "values": ["low", "high"],
+             "args": ["-c", "model_reasoning_effort={value}"]}
+}
+```
+
+`effort_hints` may map heavy/light to exact advertised equivalents. Supply
+`inherited_model` only when the host exposes its identity. Never infer models,
+fields, or CLI flags from a host name. Every existing host uses this contract,
+including hosts with no model or effort controls. Their explicit unsupported
+settings block; their default inheritance remains usable.
+
+## Native lifecycle
+
+Resolve the bundled helper to an absolute path. Use one record under the Git
+common directory's `gsd-path/model-selection/` directory per assignment. Scope
+the path and `--scope` to the milestone, active/lookahead track, and review cycle
+where applicable; later work must not reuse an earlier record.
+
+```text
+python3 -B <helper> resolve --repo <primary> --scope <milestone/track/cycle> --assignment <logical-name> --role <role> --record <absolute-record> --capabilities <advertised-json>
+```
+
+Only `status: ready` authorizes launch. Apply `selection.native` exactly to
+the advertised child tool, preserving the host adapter's other controls and
+GSD Path task isolation. The recorded selection applies to a fresh child too.
+If an existing child is still active, reattach or send its continuation;
+resolving again does not authorize launching a second copy. When a host cannot
+change model/effort on a resumed child, a changed selection requires a fresh
+child after terminal completion of the earlier one.
+
+After terminal completion, release the assignment with `release` using the
+same identity arguments and `--terminal-result <host-completion-evidence>`.
+To change the selection, use `reassign` with the same identity, current
+capabilities, explicit model/effort changes, and `--ruling <verbatim-owner-ruling>`.
+It requires an inactive assignment and preserves prior selection history.
+Resolve again before starting the replacement. A project-policy edit alone
+does not change an existing selection. Task-contract edits still require their
+legal pipeline path.
+
+For panel children, first resolve membership with `review_panel.py resolve`,
+passing `--parent-slug` when known and repeating `--exclude-family` for every
+known parent and canonical-reviewer family (including all deep review lenses).
+Apply these exclusions before persisting membership. Detected membership skips
+excluded families; explicitly named conflicts block. Pass its selected model through `--panel-model`, and pass `--panel-family` plus
+`--exclude-family` for known parent and
+canonical-reviewer families. Persist and reuse the panel roster. Policy cannot
+waive family independence or change canonical review authority. A changed
+panel roster requires a new legal review assignment.
+
+Requested controls are durable evidence. When the host hides the inherited
+model identity, exact effective-model continuity across fresh children remains
+unproven; report that limitation rather than asserting an identity.
+
+## CLI lifecycle
+
+Pass `--model-capabilities <advertised-json>` to the driver. Commands use whole
+argument slots `{model_args}` and `{effort_args}`; the resolver expands these
+to argument arrays. They are not shell substitutions. Remove fixed model and
+effort flags when using these slots; conflicting controls block dispatch.
+Commands with explicit policy choices must expose the corresponding slots,
+including when an explicit choice is `inherit`. Unconfigured legacy commands
+without a capability file retain their existing behavior.
+An existing legacy assignment with no recorded selection keeps its saved
+command across retries, even if project policy or capabilities are later added.
+It cannot use `reassign-model`; model controls require a new explicit assignment.
+
+Review and skeptic commands accept `--model` and `--effort` for that assignment.
+For distinct panel families or review lenses, pass `--model-overrides <json>`:
+a mapping from exact logical assignment names to model/effort objects. Each
+entry applies only to its named assignment; conflicting explicit inputs block.
+A common panel model must satisfy every selected family, so use these scoped
+overrides when families need different models. Family checks remain mandatory.
+Coders read their task overrides. Panels with capabilities use the argument
+slots; legacy panel commands may retain their existing `{model}` placeholder.
+
+The driver persists selection before launch and retains it on retry. Use
+`dispatch_driver.py reassign-model --repo <primary> --task-id <logical-name>
+--model-capabilities <advertised-json> --model <slug> --ruling <owner-ruling>`
+for an inactive unfinished assignment. Finished work and pinned panel rosters
+require a new legal assignment. Earlier attempt evidence is retained.
+
+Compare total cost only with observed usage and outcomes, including retries.
+These controls do not establish cost savings, pricing, or quality rankings.

package/skills/gsd-path-decide/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-decide/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