@opengsd/gsd-path 1.1.0 → 1.3.0

package/skills/path/DEFINE.md

@@ -3,6 +3,8 @@ name: gsd-path-define
 description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Define Phase
 
 Turn a project idea or approved roadmap entry into an approved intent artifact.
@@ -110,12 +112,13 @@ the charter instead of the single-milestone checklist:
 4. **Constraints** — program-level stack, budget, deadline, integrations.
 5. **Program success criteria** — observable when the last milestone ships.
 6. **Review panel** — optional durable default (`off` | `detected` | named
-   families). Default `off`. This value persists on CHARTER.md; later
+   families). Use the configured future preference unless the user chooses
+   otherwise (see Output contract). This value persists on CHARTER.md; later
    milestone INTENT files copy it and may override.
 
 Read the local [charter template](templates/charter.md), write the approval
-draft to `.project/CHARTER.md` including `Review panel:` (default `off`;
-never invent `detected` or a named list), and run the same playback-approval
+draft to `.project/CHARTER.md` including the configured or explicitly chosen
+`Review panel:` value, and run the same playback-approval
 loop as the standard Process. On approval, retain the reviewed
 `Review panel:` value on CHARTER.md, run `pipeline_state.py transition` with
 expected `define/active`, milestone/branch/archive all at their exact current
@@ -144,7 +147,7 @@ State ownership. There is no re-interview of charter or roadmap scope:
    Risks and Open questions from the entry (tagged `RESEARCH`/`NEEDS-USER`),
    `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
    `Review panel:` copied from CHARTER.md (default
-   `off` when CHARTER omits it). The confirmation may override the copied
+   the configured preference when CHARTER omits it). The confirmation may override the copied
    panel value; do not invent `detected` or a named list. When brownfield,
    fill `## Current state` from the map, record doc-vs-code rulings as in
    Brownfield mode, and add protected existing behavior under Scope out.
@@ -271,9 +274,12 @@ question. The rules change for every primary mode:
 ## Output contract
 
 At approval, retain the already reviewed `Lane:` value and its one-line reason.
-Retain `Review panel:` as reviewed: the CHARTER copy or the user's override
-in milestone/lookahead mode, the CHARTER value in program mode, or `off`
-when the user did not choose a panel and no CHARTER default exists.
+Before presenting an approval draft without a CHARTER or explicit panel choice,
+read `settings.review_panel.value` from the selected runtime's `path_config.py
+show --repo <absolute-root>` (bundle for legacy projects; off for older selected
+runtimes without config support). Include that preference in the draft.
+Retain `Review panel:` as reviewed: the CHARTER copy, the explicit user choice,
+or the configured future preference. Quick lane keeps the panel off.
 
 After approval, finalize `.project/intent/INTENT.md` and run
 `pipeline_state.py transition` with expected `define/active`, the exact

package/skills/path/DOCS-AUDIT.md

@@ -3,6 +3,8 @@ name: gsd-path-docs-audit
 description: Verify Markdown claims against the actual code, commands, and GSD Path artifacts. Use only when the user explicitly invokes $gsd-path-docs-audit or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Docs Audit
 
 Answer one question with evidence: **does the project do what its documents

package/skills/path/INSPECT.md

@@ -3,6 +3,8 @@ name: gsd-path-inspect
 description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Inspect Phase
 
 Establish ground truth about an existing project before intent is defined.

package/skills/path/PLAN.md

@@ -3,6 +3,8 @@ name: gsd-path-plan
 description: Create and validate dependency-ordered GSD Path build waves and complete task contracts. Use only when the user explicitly invokes $gsd-path-plan or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Planning Phase
 
 Dispatch one planner, gate its artifacts, and obtain the single approval that
@@ -214,8 +216,8 @@ as stated in Lookahead mode.
      statuses do not load this template. For each selected family, spawn one independent child
      with logical task name `review_plan_panel_<family>`, the reviewer role
      in plan-panel mode, the plan-panel template, and the exact helper-returned
-     model slug when the host advertises model selection. Never override the
-     model on the planner. Each child stages its family file under a
+     model slug through the dispatch model-policy contract. Planner choices
+     use that same contract. Each child stages its family file under a
      disposable root; the parent validates and copies those files, removes
      any stale `<track>/review/PLAN-PANEL.skipped.json`, then runs
      `python3 <absolute review_panel.py> merge --kind plan --inputs <family

package/skills/path/RESEARCH.md

@@ -3,6 +3,8 @@ name: gsd-path-research
 description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Research Phase
 
 Dispatch independent researchers and gate their evidence. Keep synthesis out

package/skills/path/ROADMAP.md

@@ -3,6 +3,8 @@ name: gsd-path-roadmap
 description: Slice an approved GSD Path program charter into a dependency-ordered roadmap of independently shippable milestones. Use only when the user explicitly invokes $gsd-path-roadmap or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Roadmap Phase
 
 Dispatch one roadmapper, gate its roadmap, and obtain the single approval that

package/skills/path/SHIP.md

@@ -3,6 +3,8 @@ name: gsd-path-ship
 description: Verify a completed GSD Path milestone, manage evidence-backed patch decisions, request final shipping approval, and archive the validated result. Use only when the user explicitly invokes $gsd-path-ship or an active $gsd-path router or build orchestrator explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Ship Phase
 
 Reuse proven review scope; dispatch reviewers for remaining claims. They never fix
@@ -174,8 +176,9 @@ so the position is unchanged. Then:
 
 ## Archive transaction
 
-Resolve the project's guard-owned `.gsd-path/runtime/archive_milestone.py` and
-`.gsd-path/runtime/pipeline_state.py` to absolute paths for `prepare`,
+Resolve the declared runtime with `python3 -B
+<project>/.gsd-path/status_runtime.py --repo <project> --runtime-path`; use
+`archive_milestone.py` and `pipeline_state.py` from that verified directory for `prepare`,
 `render-manifest`, `preflight`, `record-shipment`, `validate`, `integrate`, and
 `validate-integrated`. Invoke them with `python3`; the files need not be
 executable. Skill-bundle copies are not the guard's trust anchor, even when
@@ -364,27 +367,35 @@ Run this recovery setup from a separate checkout, outside the closed primary
 worktree's guard.
 
 1. Create separate disposable trust and validation checkouts from the same
-   published origin and `STATE.branch`. This separation is required because a
-   managed runtime refresh may dirty a checkout when `.gsd-path/` is tracked,
+   published origin and `STATE.branch`. This separation is required because an
+   explicit runtime upgrade changes the trust checkout's declaration and launcher,
    while archive validation requires a clean checkout. Never use the primary
    worktree for either role.
-2. From the trusted fixed GSD Path checkout, preview and then refresh only the
+2. From the trusted fixed GSD Path checkout, preview and then explicitly upgrade only the
    disposable trust checkout's managed trust anchor:
 
    ```bash
-   node <trusted-gsd-path>/scripts/install.mjs --hooks-refresh --dry-run --project <trust-root>
-   node <trusted-gsd-path>/scripts/install.mjs --hooks-refresh --project <trust-root>
+   node <trusted-gsd-path>/scripts/install.mjs --runtime-upgrade --dry-run --project <trust-root>
+   node <trusted-gsd-path>/scripts/install.mjs --runtime-upgrade --project <trust-root>
+   ```
+
+   Confirm that the preview identifies the intended fixed version and digest.
+   Upgrade changes only the disposable trust project's declaration and compatible
+   launcher. For a legacy trust checkout with no declaration, use the explicit
+   `--runtime-migrate` preview and migration first. Resolve the upgraded runtime:
+
+   ```bash
+   python3 -B <trust-root>/.gsd-path/status_runtime.py --repo <trust-root> --runtime-path
    ```
 
-   Continue only when the preview names managed `.gsd-path/` runtime or guard
-   files and no `.project/` path. The installer owns the atomic refresh and
-   refuses unmanaged or unsafe runtime entries.
-3. Use only the refreshed project-local trust anchor to refresh publication
+   Use the returned absolute directory as `<verified-runtime>` below. Stop on any
+   error; do not substitute the validation checkout's older selected runtime.
+3. Use only this verified upgraded runtime to refresh publication
    refs in the clean validation checkout and validate its integrated milestone:
 
    ```bash
-   python3 <trust-root>/.gsd-path/runtime/archive_milestone.py refresh-origin --repo <validation-root>
-   python3 <trust-root>/.gsd-path/runtime/archive_milestone.py validate-integrated --repo <validation-root> --slug <STATE.milestone>
+   python3 -B <verified-runtime>/archive_milestone.py refresh-origin --repo <validation-root>
+   python3 -B <verified-runtime>/archive_milestone.py validate-integrated --repo <validation-root> --slug <STATE.milestone>
    ```
 
 4. A pass restores the normal shipped handoff without another commit or

package/skills/path/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: path
-description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $path or $gsd-path. The status argument reports state without advancing. Do not infer this skill from generic project, next-step, or resume requests.
+description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $path or $gsd-path. The status argument reports state without advancing; config views or edits settings without advancing. Do not infer this skill from generic project, next-step, or resume requests.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
+## Configuration mode
+
+When the first argument is `config`, read [Path settings](references/config.md)
+and complete that request without initializing state or advancing a phase.
+
 # GSD Path Router
 
 Determine the current pipeline phase, report it briefly, and run the next valid
@@ -11,11 +18,13 @@ Any text the user is expected to send back verbatim (a ruling, an approval
 command, a reply) goes in its own fenced code block, never a blockquote or
 inline prose, so it pastes cleanly.
 
-When the project's `.gsd-path/runtime/` exists, resolve bundled helper paths
-for `pipeline_state.py`, `pipeline_git.py`, `archive_milestone.py`,
-`promote_lookahead.py`, `discussion_records.py`, and `pipeline_diagnose.py`
-to that runtime. It is the guard-approved location on a closed milestone.
-Use the skill bundle only when no project-local runtime exists.
+When `.gsd-path/runtime.json` exists, run `python3 -B
+<absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project>
+--runtime-path`. Use the returned verified directory for its bundled helpers.
+A missing or invalid selected runtime stops execution with its explicit restore
+action; never substitute the installed plugin's helpers. Legacy projects without
+a declaration may use `.gsd-path/runtime/`, or the skill bundle when that directory
+is absent. An explicit `--runtime-migrate` produces the reviewed migration diff.
 
 ## Status-only mode
 
@@ -66,7 +75,12 @@ GitHub repository and no owned `.project/STATE.md` is active for that request.
    Derive `gsd-path/M001` as the branch. The default checkout is
    `<resolved-workspace>/<repo-name>`; propose the distinct sibling
    `<resolved-workspace>/<repo-name>-gsd-path` as the linked worktree. When
-   starting in an empty non-Git folder, propose that existing folder as the
+   the user prefers a managed primary, offer an explicit path below
+   `~/.gsd-path/projects/` (or `GSD_PATH_WORKTREE_ROOT`) instead. Pass the
+   approved absolute path through `--worktree`; its parent must already exist
+   for preview. Keep this choice separate from helper-owned task, verify, and
+   integration placement. Never relocate an existing primary.
+   When starting in an empty non-Git folder, propose that existing folder as the
    linked worktree with `--reuse-empty-worktree`, and a distinct absent default
    checkout beside it. Use the parent as workspace so the journal stays outside
    the worktree. Preserve the invocation folder and all its contents; never
@@ -151,8 +165,8 @@ selects a milestone branch.
 
 ## Integration choice
 
-New state starts with `integration_default: direct`, `integration: direct`, and
-`integration_source: default`.
+New state uses the user shipping default (built-in: `direct`) for
+`integration_default` and `integration`, with `integration_source: default`.
 When the user asks to change closeout behavior before build, use the state
 helper; never edit these fields by hand:
 

package/skills/path/references/build-native.md

@@ -37,7 +37,9 @@ its sidecar, copies it to the canonical path, retires the sidecar, and only
 after every lens settles concludes: a passing cycle with no panel is
 checkpointed; with a panel configured (`panel_required: true`) run `panel
 --wave <N> --cycle <C> --advertised <slugs> [--parent-slug <slug>]
---child-command '<owner command with {model}>'`, which resolves the panel,
+--child-command '<owner command>'`, using the
+[model-policy CLI contract](model-policy.md#cli-lifecycle). The panel command
+resolves membership,
 persists a skipped receipt or runs one panelist per family in its own
 sidecar, merges the family files, and makes the single on-pass checkpoint;
 `blocked` returns the `review_findings.py collect` grouping; when its
@@ -53,7 +55,9 @@ The driver never writes a `verify-only` file (`status: not-applicable`);
 approved artifacts or the user, record it with `answer --task-id <id>
 --answer '<answer> — <citation>'`, and call `round` again, which redispatches
 the retained isolate; `blocked` names the task, reason, and output and leaves
-the isolate in place — apply the recovery, retry, or plan-defect procedure in
+an existing isolate in place. A model-selection rejection before launch creates
+no isolate; follow the [model-policy contract](model-policy.md). For other
+blocks, apply the recovery, retry, or plan-defect procedure in
 steps 1–2 by hand, then call `round` again. The driver counts dispatches per
 task per milestone and stops at `--max-attempts` (default 2: the first
 dispatch plus this contract's one logged redispatch); owner token limits, when
@@ -351,12 +355,16 @@ dispatch contract and perform steps 1–5 by hand.
      against that evidence and the diff; anything it cannot
      confirm from them is a finding, not a pass. Never spawn a review panel
      at `verify-only`.
-   - After the canonical inherit reviewer (or orchestrator-written
+   - After the canonical reviewer (or orchestrator-written
      `verify-only` file) is collected, run the optional review panel only
      for `full` and `deep`. Inspect advertised model slugs and run
      `python3 <absolute review_panel.py> resolve --plan <absolute PLAN.md>
      --intent <absolute INTENT.md> --advertised <comma slugs>
-     --parent-slug <current model slug when known>` and `--charter
+     --parent-slug <current model slug when known>
+     --exclude-family <known canonical-reviewer family>`; repeat
+     `--exclude-family` for every known parent and canonical-reviewer family,
+     including all deep review lenses, before persisting the roster. Omit
+     unknown identities. Also pass `--charter
      <absolute .project/CHARTER.md>` when that file exists. `status: off`
      continues with no current-cycle panel artifact. For `skipped`,
      persist the helper's exact JSON stdout as
@@ -368,16 +376,16 @@ dispatch contract and perform steps 1–5 by hand.
      the reviewer role in wave-panel mode, the wave-panel template, and the
      exact helper-returned model slug when the host advertises model
      selection. On `deep`, each panel brief is the adversarial lens only.
-     Never override the model on the canonical reviewer. Each child stages
+     Resolve model choices through the dispatch model-policy contract. Each child stages
      its family file in its own verify sidecar from `isolate-verify`
      (`--name wave-<N>-cycle-<C>-panel-<family>`); the parent validates
      those files and runs `python3 <absolute review_panel.py> merge --kind
      wave --wave <N> --cycle <C> --inputs <family files> --output
      <absolute .project/review/wave-N.cycleC.panel.md> --mode
-     <detected|named>`. The inherit reviewer remains the only Wave verdict.
+     <detected|named>`. The canonical reviewer remains the only Wave verdict.
      Do not average panel findings into that verdict or auto-create fix
      tasks from preference findings.
-   - After the canonical inherit reviewer file (and each deep lens file) is
+   - After the canonical reviewer file (and each deep lens file) is
      on the primary path, run
      `python3 <absolute check_handoffs.py> wave --repo <absolute primary>
      --review <canonical wave-review path>`. A non-zero exit is a blocked

package/skills/path/references/config.md

@@ -0,0 +1,57 @@
+# Path settings
+
+`$path config` (or `/path config`) is independent of phase routing. Resolve
+`scripts/path_config.py` from the selected project runtime; without a declaration,
+use the router skill's bundled helper (`gsd-path` or its `path` alias). Copies in
+other phase skills support internal imports; they are not config CLI entry points.
+An older selected runtime without this helper requires
+an explicit runtime upgrade; never substitute it.
+
+Run `python3 -B <absolute-helper> show --repo <absolute-root>` for an initialized
+project. Without STATE.md use `show --scope user`. Show returned values, sources,
+recorded review panel, current milestone shipping mode, and lock reasons.
+Do not initialize state, bind a branch, dispatch a phase, approve, or commit.
+
+For bare `config`, show settings and ask which scope and setting to change.
+Offer user defaults and, when initialized, project settings. For explicit
+arguments, pass the action to the same helper:
+
+```text
+show --scope user
+validate --scope project --repo <absolute-root>
+set integration pull-request --scope project --repo <absolute-root>
+set review_panel detected --scope user
+set models.roles.coder.model inherit --scope project --repo <absolute-root>
+set models.hosts.codex.plan.effort high --scope project --repo <absolute-root>
+reset models.roles.coder.model --scope project --repo <absolute-root>
+```
+
+Write only the user's explicit selection. Use exact host-advertised model/effort
+values; unavailable values block dispatch. `inherit` clears a control override;
+`reset` removes this scope's setting and exposes defaults. Project shipping needs
+an explicit mode; milestone overrides use configure-integration. Report the
+returned source and when it applies. Errors stop the request; never repair by hand.
+
+## Ownership and timing
+
+- User defaults: `~/.gsd-path/config.json`. Shipping affects newly initialized
+  projects. Model choices affect new assignments; recorded assignments stay pinned.
+- Project shipping: STATE.md, written by configure-integration. It locks when
+  build starts. Project-default changes preserve explicit milestone overrides.
+- Project models: `.project/model-policy.json`. Precedence is user common roles,
+  user host roles, project common roles, project host roles, then task overrides,
+  independently for model and effort. Existing effort hints remain.
+- Future review preference: `.project/config.json`, then user default, then off.
+  Define presents it in the approval draft when no CHARTER or explicit user choice
+  applies. Approved INTENT/PLAN values remain authoritative; quick lane keeps off.
+- Project writes require the bound branch; ship and shipped projects are locked.
+  Config cannot advance phases or edit archives.
+
+Config leaves project edits for the pipeline's next normal metadata checkpoint.
+In-flight task landings preserve these edits. Project preferences persist outside
+milestone archives so later milestones keep them.
+
+Dashboard Path settings calls this same helper for watched projects, using their
+selected runtime. Background monitoring stays read-only. Existing watched-folder
+and appearance controls stay separate. No background writes or automatic pipeline
+execution are authorized by this settings exception.

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

package/skills/path/references/jev-review.md

@@ -0,0 +1,82 @@
+# Optional Jev evidence screening
+
+Jev screens selected criterion/evidence pairs for a wave or final reviewer.
+It is disabled by default. Normal Path review needs no account, API key, SDK,
+or network access. This helper uses Python's standard library.
+
+## Enable or disable
+
+Set these environment variables in the session that launches the reviewing
+agent; child agents must inherit them to use Jev:
+
+| Variable | Value |
+| --- | --- |
+| `GSD_PATH_JEV` | Exactly `1` enables screening. Unset it to disable. |
+| `TYPESAFE_API_KEY` | Your TypeSafe API key, supplied through the environment. |
+| `GSD_PATH_JEV_TIMEOUT_SECONDS` | Positive finite seconds chosen by the owner for the HTTP socket timeout. There is no default. |
+
+Enabling this option permits the selected criterion and evidence text to be
+sent to TypeSafe's hosted API. Supply only material authorized for that service.
+Do not include credentials, environment dumps, or unrelated repository content.
+Having a key alone does not enable Jev. Do not put keys in commands or artifacts.
+
+## Reviewer procedure
+
+1. Use only still-uncovered criteria from the assigned wave/final review and
+   the corresponding evidence already available in the supplied verify sidecar.
+   Keep existing rules for isolated evidence, command reuse, and provenance.
+2. Pass JSON through stdin to `python3 -B <absolute skill scripts/jev_review.py>`
+   from that sidecar. Resolve the helper as `../scripts/jev_review.py` relative
+   to this reference directory. Do not create another project report. The input
+   has exactly this shape; replace the illustrative revision and contents:
+
+   ```json
+   {
+     "reviewed_head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+     "items": [
+       {
+         "id": "T001-AC1",
+         "criterion": "Reject an empty name.",
+         "evidence": "Recorded isolated Verify: test_empty_name passed."
+       }
+     ]
+   }
+   ```
+
+   Use the full review SHA supplied by the orchestrator, unique nonempty item
+   IDs, verbatim criterion text, and selected evidence text. Empty evidence is
+   allowed. The SHA is caller-supplied context; the helper does not prove Git
+   ancestry or that the text actually came from that revision.
+3. Read the JSON status. `disabled` means ordinary review. `unavailable` means
+   ordinary review with the explicit reason recorded in the assigned artifact.
+   Neither is a failed criterion. The helper exits zero for these optional
+   outcomes and makes no automatic retries. Correct invalid input/configuration
+   before an explicit retry; keep a service failure visible and continue review.
+4. For `ok`, inspect per-item `supported`, `partial`, `unsupported`, or `unclear`
+   answers, their probabilities, and confidence. Independently examine suggested
+   gaps under the existing rubric. A Jev answer is neither executable evidence
+   nor an independent review verdict. It cannot satisfy or waive a criterion,
+   change a gate, select a route, or authorize publication.
+5. Keep the advisory JSON receipt in the assigned review artifact's notes or
+   evidence prose, outside fixed-format verdict fields. An `ok` receipt includes
+   the supplied revision, SHA-256 of the exact canonical request, versioned model,
+   item IDs and answers, and token usage. An `unavailable` receipt includes the
+   reason and, only after request construction, the revision and request hash;
+   it has no model, answers, or usage. A `disabled` receipt contains only the
+   status and advisory marker. Retain the selected input with that evidence if it
+   is not already reconstructible from cited sources. Keep all canonical verdicts and template
+   structure unchanged. Reuse the recorded advisory when its exact request and
+   review revision remain unchanged; skip screening for a reused proven review.
+
+## Service behavior
+
+The helper calls only `https://api.typesafe.ai/v1/systemone` with the documented
+version `jev-1.13.0`. It does not follow redirects, echo provider error bodies,
+write files, or install packages. Missing keys/timeouts, HTTP and network errors,
+and invalid input/responses return `unavailable`. There is no confidence cutoff:
+the existing reviewer owns acceptance. Real model accuracy and savings must be
+evaluated on chosen evidence before relying on this advisory signal.
+
+Sources: [HTTP API](https://docs.typesafe.ai/api),
+[models](https://docs.typesafe.ai/models),
+[confidence](https://docs.typesafe.ai/confidence).

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