@aperant/framework 0.15.0 → 0.17.0

package/dist/plugin/skills/apt-spar/SKILL.md

@@ -137,6 +137,8 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 
 Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 900000ms (15 min), configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. The MCP rung is a structured tool call, NOT a Bash invocation, so the Bash tool's 600000ms ceiling does NOT apply — the MCP rung can carry heavy-research partner runs (e.g. Claude Code partner doing multiple minutes of Read/Grep/Bash) where the Bash rungs would hit the host ceiling. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
 
+**Codex walk order (anti-staleness — do NOT infer it from prose).** The codex MCP rung is the ONLY codex transport that forces the agent to NAME a model, and a named model is a staleness vector (the upstream MCP server has no access to the user's config and silently substitutes a stale default; the agent could also substitute one from training memory). The self-resolving rungs (plugin shim → raw CLI) pass NO `--model` and let `codex exec` inherit `~/.codex/config.toml`, so they are staleness-proof by construction. Therefore, for the **codex** partner specifically, prefer the self-resolving plugin → CLI rungs in the common case and demote the MCP rung to **LAST**. Do NOT hand-order the rungs from this prose — run `apt-tools spar-resolve-partner --partner codex` and FOLLOW the preference it returns: walk in the order of its `recommended_walk` array (`["plugin","cli","mcp"]`) and treat `prefer_self_resolving: true` as authoritative. The generic `host.partner_transports.codex` array stays MCP-first (it is data shared with other consumers, not a spar walk order); the resolver's preference overrides it for codex only. **claude / gemini stay MCP-first** — their MCP rungs take only `{prompt}` and need no model, so there is no staleness vector and no walk change.
+
 If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
 ```
@@ -183,7 +185,7 @@ The table below shows the canonical command shape per (partner × rung); the act
 
 | Partner | Rung | Command | Notes |
 |---|---|---|---|
-| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is parsed from `~/.codex/config.toml`'s `model = "<value>"` line (see §5a below). | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. If `~/.codex/config.toml` is missing OR the `model =` line is absent/unparseable, treat MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server's built-in fallback is stale `gpt-5.3-codex`, which is exactly the bug we are fixing). |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is the `model` field returned by `apt-tools spar-resolve-partner --partner codex` (see §5a below). | **Demoted to LAST for codex** (see the codex walk-order note in §3) — attempt this rung only when the resolver returns `available: true`. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. When the resolver returns `available: false`, treat the MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server silently substitutes a stale hardcoded default model id, which is exactly the bug we are fixing). |
 | codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
 | codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. Verify with `codex --help`. |
 | claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. |
@@ -199,15 +201,21 @@ Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
 ## 5a. Codex MCP model resolution
 
-The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it falls back to a hardcoded stale `gpt-5.3-codex`, silently overriding the user's actual configured model. Resolve the model exactly once per spar invocation, before the rung-table walk:
+The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it silently substitutes a stale hardcoded default model id, overriding the user's actual configured model. **Aperant holds zero model names** — resolve the model LIVE via the deterministic resolver exactly once per spar invocation, before the rung-table walk:
 
 ```bash
-# Resolve the codex MCP model exactly once per spar invocation, before the rung table walk
-CODEX_MCP_MODEL="$(grep -E '^model = "[^"]+"' "$HOME/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/^model = "([^"]+)".*/\1/')"
-# If empty → codex MCP rung is UNAVAILABLE; fall through to plugin/CLI.
+# Resolve the codex partner model + transport preference LIVE, once per spar
+# invocation, before the rung-table walk. apt-tools reads ~/.codex/config.toml
+# fresh and never bakes a default.
+apt-tools spar-resolve-partner --partner codex
 ```
 
-If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value not double-quoted), treat the MCP rung as UNAVAILABLE and fall through to plugin → CLI. **Never invent a default** — the upstream MCP server's built-in `gpt-5.3-codex` fallback is exactly the bug this resolution path exists to fix.
+The command emits a JSON envelope `{available, model, source, reason, prefer_self_resolving, recommended_walk}`:
+
+- When `available: true`, pass the returned `model` field **VERBATIM** into the codex MCP tool call's `model` arg — do NOT transform it, and do NOT substitute a model from your own training memory.
+- When `available: false` (the envelope carries a machine `reason` of `config_missing` / `no_model_key` / `unparseable`), treat the codex MCP rung as **UNAVAILABLE** and fall through to plugin → CLI. **Never invent a default** — substituting any model name is exactly the staleness bug this resolution path exists to fix. The plugin and raw-CLI rungs pass no `--model` and let `codex exec` self-resolve from the user's live config, so the fall-through is always staleness-proof.
+
+Follow the envelope's `recommended_walk` / `prefer_self_resolving` for the rung order (see the codex walk-order note in §3) rather than ordering the rungs by hand.
 
 **Prompt-quoting safety.** The prompt is user-controlled (it comes from `[topic]` and/or conversation context) and may legitimately contain double quotes, dollar signs, backticks, or `$(...)` substitution that bash would otherwise expand or break on. NEVER interpolate `<prompt>` directly inside a double-quoted shell argument. Instead, pipe via a here-document so the shell treats the body as opaque text:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": "Mikalsen AI <hello@mikalsen.ai>",
   "type": "module",

package/skills/apt-pr-review/SKILL.md

@@ -480,12 +480,12 @@ The detector returns:
 ```json
 {
   "i18n":      { "engage": true,  "signals": [{ "kind": "...", "detail": "...", "tier": "strong|weak" }], "reason": "strong: locale-file src/locales/fr.json" },
-  "xplatform": { "engage": false, "signals": [], "reason": "no signals" }
+  "crossplatform": { "engage": false, "signals": [], "reason": "no signals" }
 }
 ```
 
 Engagement precedence (the detector encodes it; you just read the result):
-config `pr_review.specialists.{i18n,xplatform}` ∈ `auto|always|never` (default
+config `pr_review.specialists.{i18n,crossplatform}` ∈ `auto|always|never` (default
 `auto`) is checked FIRST and is absolute — `always` engages with no scan,
 `never` skips with no scan (even when the diff introduces the first locale
 file). Otherwise `auto` defers to the STRONG/WEAK tier scan.
@@ -500,17 +500,17 @@ verbatim, e.g. `config override: never`):
 // metadata.json (additive key)
 "conditional_specialists": {
   "i18n":      { "engaged": true,  "reason": "strong: locale-file src/locales/fr.json" },
-  "xplatform": { "engaged": false, "reason": "no signals" }
+  "crossplatform": { "engaged": false, "reason": "no signals" }
 }
 ```
 
 ```
 i18n: ENGAGED (strong: locale-file src/locales/fr.json)
-xplatform: SKIPPED (no platform signals; config: auto)
+crossplatform: SKIPPED (no platform signals; config: auto)
 ```
 
-Store `result.i18n.engage` and `result.xplatform.engage` as `ENGAGE_I18N` /
-`ENGAGE_XPLATFORM` for Phase 3.
+Store `result.i18n.engage` and `result.crossplatform.engage` as `ENGAGE_I18N` /
+`ENGAGE_CROSSPLATFORM` for Phase 3.
 
 **R3: pin the reviewed head SHA (PR reviews only).** After `gh pr diff` fetches into `pr-review-${REVIEW_ID}`, capture the SHA and pass it to `pr-review start-round`. All subsequent evidence reads within this round should reference this pinned SHA, not a fresh `gh pr view` call — otherwise a mid-round force-push invalidates cited line numbers.
 
@@ -839,7 +839,7 @@ DO NOT return full error output in your response -- write it to the file.
 node packages/framework/bin/apt-tools.mjs workflow advance . --id ${REVIEW_ID} --phase specialist-review
 ```
 
-**CRITICAL: Spawn all SELECTED review agents (6-8) in ONE message using parallel Agent tool calls.** The 6 core specialists ALWAYS spawn. Additionally append the **i18n** agent when `ENGAGE_I18N` is true and the **cross-platform** agent when `ENGAGE_XPLATFORM` is true (from Step 4b). So the set is 6, 7, or 8 agents — all in the SAME message.
+**CRITICAL: Spawn all SELECTED review agents (6-8) in ONE message using parallel Agent tool calls.** The 6 core specialists ALWAYS spawn. Additionally append the **i18n** agent when `ENGAGE_I18N` is true and the **cross-platform** agent when `ENGAGE_CROSSPLATFORM` is true (from Step 4b). So the set is 6, 7, or 8 agents — all in the SAME message.
 
 Each agent receives:
 1. The changed file list
@@ -909,10 +909,10 @@ Agent(
   prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
 )
 
-# Append ONLY if ENGAGE_XPLATFORM is true:
+# Append ONLY if ENGAGE_CROSSPLATFORM is true:
 Agent(
-  name: "xplatform-reviewer",
-  subagent_type: "apt-pr-review-xplatform",
+  name: "crossplatform-reviewer",
+  subagent_type: "apt-pr-review-crossplatform",
   description: "Cross-platform review of PR changes",
   prompt: "{CONSTRUCTED_PROMPT_WITH_FILLED_PLACEHOLDERS}",
 )
@@ -1027,7 +1027,7 @@ Review Directory: {REVIEW_DIR}
 
 Read all finding files from {REVIEW_DIR}/findings/ (excluding validated.md if it exists).
 The core finding files are: security.md, quality.md, logic.md, codebase-fit.md, test-integrity.md, performance.md.
-Additionally read i18n.md and/or xplatform.md when present (the conditional specialists write them only when engaged).
+Additionally read i18n.md and/or crossplatform.md when present (the conditional specialists write them only when engaged).
 
 For each finding in each file, run the hypothesis-validation process from your instructions.
 
@@ -1935,7 +1935,7 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 | `review.max_iterations` | number | 4 | Maximum fix-review iterations before stopping. |
 | `review.optional_agents` | string[] | [] | Reserved for future use. Additional specialist agents to spawn beyond the core 6. |
 | `pr_review.specialists.i18n` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional i18n specialist. `always` forces engage, `never` forces skip (over the detector AND over a diff-introduced signal), `auto`/absent defers to `detect-specialists`. Override is the TOP of the precedence chain (ID-01a). |
-| `pr_review.specialists.xplatform` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional cross-platform specialist. Same semantics as `pr_review.specialists.i18n`. |
+| `pr_review.specialists.crossplatform` | `"auto"\|"always"\|"never"` | `"auto"` | Override for the conditional cross-platform specialist. Same semantics as `pr_review.specialists.i18n`. |
 
 ---
 
@@ -1964,7 +1964,7 @@ Agent(
 | Test-integrity reviewer | `.claude/agents/apt-pr-review-test-integrity.md` | Read, Write, Grep, Glob | 3 |
 | Performance reviewer | `.claude/agents/apt-pr-review-performance.md` | Read, Write, Grep, Glob | 3 |
 | i18n reviewer **(conditional)** | `.claude/agents/apt-pr-review-i18n.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages i18n (or config `always`) |
-| Cross-platform reviewer **(conditional)** | `.claude/agents/apt-pr-review-xplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages xplatform (or config `always`) |
+| Cross-platform reviewer **(conditional)** | `.claude/agents/apt-pr-review-crossplatform.md` | Read, Write, Grep, Glob | 3 — spawned only when `detect-specialists` engages crossplatform (or config `always`) |
 | Finding validator | `.claude/agents/apt-pr-review-validator.md` | Read, Write, Grep, Glob | 4 |
 | Fix agent (x3) | `.claude/agents/apt-pr-review-fixer.md` | Read, Write, Edit, Bash, Grep, Glob | 6 |
 | Self-reviewer | `.claude/agents/apt-pr-review-self-reviewer.md` | Read, Write, Edit, Bash, Grep, Glob | 7 |

package/skills/apt-spar/SKILL.md

@@ -137,6 +137,8 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 
 Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 900000ms (15 min), configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. The MCP rung is a structured tool call, NOT a Bash invocation, so the Bash tool's 600000ms ceiling does NOT apply — the MCP rung can carry heavy-research partner runs (e.g. Claude Code partner doing multiple minutes of Read/Grep/Bash) where the Bash rungs would hit the host ceiling. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
 
+**Codex walk order (anti-staleness — do NOT infer it from prose).** The codex MCP rung is the ONLY codex transport that forces the agent to NAME a model, and a named model is a staleness vector (the upstream MCP server has no access to the user's config and silently substitutes a stale default; the agent could also substitute one from training memory). The self-resolving rungs (plugin shim → raw CLI) pass NO `--model` and let `codex exec` inherit `~/.codex/config.toml`, so they are staleness-proof by construction. Therefore, for the **codex** partner specifically, prefer the self-resolving plugin → CLI rungs in the common case and demote the MCP rung to **LAST**. Do NOT hand-order the rungs from this prose — run `apt-tools spar-resolve-partner --partner codex` and FOLLOW the preference it returns: walk in the order of its `recommended_walk` array (`["plugin","cli","mcp"]`) and treat `prefer_self_resolving: true` as authoritative. The generic `host.partner_transports.codex` array stays MCP-first (it is data shared with other consumers, not a spar walk order); the resolver's preference overrides it for codex only. **claude / gemini stay MCP-first** — their MCP rungs take only `{prompt}` and need no model, so there is no staleness vector and no walk change.
+
 If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
 ```
@@ -183,7 +185,7 @@ The table below shows the canonical command shape per (partner × rung); the act
 
 | Partner | Rung | Command | Notes |
 |---|---|---|---|
-| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is parsed from `~/.codex/config.toml`'s `model = "<value>"` line (see §5a below). | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. If `~/.codex/config.toml` is missing OR the `model =` line is absent/unparseable, treat MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server's built-in fallback is stale `gpt-5.3-codex`, which is exactly the bug we are fixing). |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is the `model` field returned by `apt-tools spar-resolve-partner --partner codex` (see §5a below). | **Demoted to LAST for codex** (see the codex walk-order note in §3) — attempt this rung only when the resolver returns `available: true`. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. When the resolver returns `available: false`, treat the MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server silently substitutes a stale hardcoded default model id, which is exactly the bug we are fixing). |
 | codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
 | codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. Verify with `codex --help`. |
 | claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. |
@@ -199,15 +201,21 @@ Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
 ## 5a. Codex MCP model resolution
 
-The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it falls back to a hardcoded stale `gpt-5.3-codex`, silently overriding the user's actual configured model. Resolve the model exactly once per spar invocation, before the rung-table walk:
+The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it silently substitutes a stale hardcoded default model id, overriding the user's actual configured model. **Aperant holds zero model names** — resolve the model LIVE via the deterministic resolver exactly once per spar invocation, before the rung-table walk:
 
 ```bash
-# Resolve the codex MCP model exactly once per spar invocation, before the rung table walk
-CODEX_MCP_MODEL="$(grep -E '^model = "[^"]+"' "$HOME/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/^model = "([^"]+)".*/\1/')"
-# If empty → codex MCP rung is UNAVAILABLE; fall through to plugin/CLI.
+# Resolve the codex partner model + transport preference LIVE, once per spar
+# invocation, before the rung-table walk. apt-tools reads ~/.codex/config.toml
+# fresh and never bakes a default.
+apt-tools spar-resolve-partner --partner codex
 ```
 
-If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value not double-quoted), treat the MCP rung as UNAVAILABLE and fall through to plugin → CLI. **Never invent a default** — the upstream MCP server's built-in `gpt-5.3-codex` fallback is exactly the bug this resolution path exists to fix.
+The command emits a JSON envelope `{available, model, source, reason, prefer_self_resolving, recommended_walk}`:
+
+- When `available: true`, pass the returned `model` field **VERBATIM** into the codex MCP tool call's `model` arg — do NOT transform it, and do NOT substitute a model from your own training memory.
+- When `available: false` (the envelope carries a machine `reason` of `config_missing` / `no_model_key` / `unparseable`), treat the codex MCP rung as **UNAVAILABLE** and fall through to plugin → CLI. **Never invent a default** — substituting any model name is exactly the staleness bug this resolution path exists to fix. The plugin and raw-CLI rungs pass no `--model` and let `codex exec` self-resolve from the user's live config, so the fall-through is always staleness-proof.
+
+Follow the envelope's `recommended_walk` / `prefer_self_resolving` for the rung order (see the codex walk-order note in §3) rather than ordering the rungs by hand.
 
 **Prompt-quoting safety.** The prompt is user-controlled (it comes from `[topic]` and/or conversation context) and may legitimately contain double quotes, dollar signs, backticks, or `$(...)` substitution that bash would otherwise expand or break on. NEVER interpolate `<prompt>` directly inside a double-quoted shell argument. Instead, pipe via a here-document so the shell treats the body as opaque text:
 

package/src/cli/commands/init.mjs

@@ -23,6 +23,7 @@ import {
 	mkdirSync,
 	readdirSync,
 	readFileSync,
+	unlinkSync,
 	writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -1276,6 +1277,34 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			}
 		}
 
+		// Orphan-removal sweep — the cross-platform PR-review agent was renamed
+		// from `apt-pr-review-xplatform` to `apt-pr-review-crossplatform`. The
+		// install pipeline writes the current agent set + a fresh manifest but
+		// has NO stale-removal pass (readManifest is consumed only by
+		// skill-installs.mjs + check-version.mjs, never pipeline.mjs), so a
+		// rename leaves the OLD-named file orphaned in every active runtime
+		// root. Targeted, best-effort unlink of that ONE basename from each
+		// requested runtime's install root (the agent lands under different
+		// per-runtime subdirs: claude→agents, pi→skills, windsurf→workflows).
+		// Mirrors runLegacyCleanup's conservative idempotent posture; ENOENT
+		// and any other unlink error is swallowed.
+		const ORPHANED_AGENT_BASENAME = 'apt-pr-review-xplatform.md'
+		const ORPHAN_AGENT_SUBDIRS = ['agents', 'skills', 'workflows', 'rules']
+		for (const runtimeId of effectiveAnswers.runtimes) {
+			const runtime = getRuntime(runtimeId)
+			if (!runtime?.installRoot) continue
+			for (const subdir of ORPHAN_AGENT_SUBDIRS) {
+				const orphanPath = join(installTarget, runtime.installRoot, subdir, ORPHANED_AGENT_BASENAME)
+				if (existsSync(orphanPath)) {
+					try {
+						unlinkSync(orphanPath)
+					} catch {
+						// best-effort — a missing/locked orphan must not fail init
+					}
+				}
+			}
+		}
+
 		const results = await installRuntimes(
 			effectiveAnswers.runtimes,
 			canonicalRoot,

package/src/cli/commands/pr-review/detect-specialists.mjs

@@ -2,7 +2,7 @@
  * commands/pr-review/detect-specialists.mjs — deterministic detector for the
  * two CONDITIONAL /apt:pr-review specialists (i18n + cross-platform).
  *
- * Restores the 2.8 `i18n-reviewer` + `xplatform` perspectives but gates their
+ * Restores the 2.8 `i18n-reviewer` + `crossplatform` perspectives but gates their
  * Phase-3 spawn on a reproducible, language/platform/ecosystem-agnostic scan
  * with a config override on top. The SKILL orchestrator NEVER decides
  * engagement by reading the diff itself — it calls this detector and obeys the
@@ -11,7 +11,7 @@
  * Engagement model (spec ID-01/ID-01a/ID-02/ID-02a/ID-03/ID-03a/ID-03b):
  *
  *   1. Config check FIRST and short-circuit (ID-01a). `.aperant/config.json`
- *      pr_review.specialists.{i18n,xplatform} ∈ {auto|always|never}, default
+ *      pr_review.specialists.{i18n,crossplatform} ∈ {auto|always|never}, default
  *      auto. `always` → engage (no scan); `never` → skip (no scan); only
  *      `auto`/absent proceeds. Config is the TOP of the precedence chain — a
  *      diff-introduced STRONG signal does NOT override `never`.
@@ -44,7 +44,7 @@ import { err, ok } from '../../util/result.mjs'
  * @typedef {{ engage: boolean, signals: Signal[], reason: string }} SpecialistDecision
  */
 
-// Manifests scanned for dependency-substring i18n/xplatform library markers.
+// Manifests scanned for dependency-substring i18n/crossplatform library markers.
 // No YAML/TOML parse — substring/regex on the raw text, mirroring
 // toolchain-detect.mjs:isBerryNodeLinker (R2).
 const MANIFEST_FILES = [
@@ -334,10 +334,10 @@ function scanSourceForI18nTokens(detailLabel, text) {
 	return found
 }
 
-// ── xplatform matchers ──────────────────────────────────────────────────────
+// ── crossplatform matchers ──────────────────────────────────────────────────────
 
 // Cross-platform app frameworks (STRONG) matched as manifest substrings.
-const XPL_FRAMEWORK_SUBSTRINGS = [
+const CROSSPLATFORM_FRAMEWORK_SUBSTRINGS = [
 	'electron',
 	'@tauri-apps',
 	'react-native',
@@ -358,13 +358,13 @@ const XPL_FRAMEWORK_SUBSTRINGS = [
  * @param {string} text
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function scanManifestForXplatform(manifestName, text) {
+function scanManifestForCrossplatform(manifestName, text) {
 	const found = []
 	const lower = text.toLowerCase()
-	for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+	for (const fw of CROSSPLATFORM_FRAMEWORK_SUBSTRINGS) {
 		if (lower.includes(fw)) {
 			found.push({
-				kind: 'xplatform-framework',
+				kind: 'crossplatform-framework',
 				detail: `${fw} in ${manifestName}`,
 				tier: 'strong',
 			})
@@ -378,7 +378,7 @@ function scanManifestForXplatform(manifestName, text) {
 
 // Compile-time platform guards (STRONG) — source-token regexes spanning
 // Rust / Go / C/C++ / CMake / Swift.
-const XPL_COMPILE_GUARD_RES = [
+const CROSSPLATFORM_COMPILE_GUARD_RES = [
 	{ re: /#\[cfg\(target_os/, label: '#[cfg(target_os' },
 	{ re: /\bcfg!\s*\(\s*windows\b/, label: 'cfg!(windows)' },
 	{ re: /\/\/go:build\s+(windows|darwin|linux)/, label: '//go:build <os>' },
@@ -393,7 +393,7 @@ const XPL_COMPILE_GUARD_RES = [
 ]
 
 // Lone runtime platform checks (WEAK).
-const XPL_WEAK_TOKEN_RES = [
+const CROSSPLATFORM_WEAK_TOKEN_RES = [
 	{ re: /\bprocess\.platform\b/, label: 'process.platform' },
 	{ re: /\bos\.platform\s*\(/, label: 'os.platform()' },
 	{ re: /\bsys\.platform\b/, label: 'sys.platform' },
@@ -405,28 +405,28 @@ const XPL_WEAK_TOKEN_RES = [
 ]
 
 /**
- * Scan one source blob for xplatform compile-guard (STRONG) + lone runtime
+ * Scan one source blob for crossplatform compile-guard (STRONG) + lone runtime
  * (WEAK) tokens.
  *
  * @param {string} detailLabel
  * @param {string} text
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function scanSourceForXplatformTokens(detailLabel, text) {
+function scanSourceForCrossplatformTokens(detailLabel, text) {
 	const found = []
-	for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+	for (const { re, label } of CROSSPLATFORM_COMPILE_GUARD_RES) {
 		if (re.test(text)) {
 			found.push({
-				kind: 'xplatform-guard',
+				kind: 'crossplatform-guard',
 				detail: `${label} in ${detailLabel}`,
 				tier: 'strong',
 			})
 		}
 	}
-	for (const { re, label } of XPL_WEAK_TOKEN_RES) {
+	for (const { re, label } of CROSSPLATFORM_WEAK_TOKEN_RES) {
 		if (re.test(text)) {
 			found.push({
-				kind: 'xplatform-runtime',
+				kind: 'crossplatform-runtime',
 				detail: `${label} in ${detailLabel}`,
 				tier: 'weak',
 			})
@@ -496,7 +496,7 @@ function detectCiMatrix(workflowName, text) {
 	}
 	if (osFamilies.size > 1) {
 		return {
-			kind: 'xplatform-ci-matrix',
+			kind: 'crossplatform-ci-matrix',
 			detail: `multi-OS CI matrix in ${workflowName} (${osFamilies.size} OS families)`,
 			tier: 'strong',
 		}
@@ -519,7 +519,7 @@ function detectPlatformDirSiblings(relPaths) {
 	const hasLinuxDir = relPaths.some((p) => p.split('/').includes('linux'))
 	if (hasWindowsDir && hasMacosDir && hasLinuxDir) {
 		found.push({
-			kind: 'xplatform-dir-siblings',
+			kind: 'crossplatform-dir-siblings',
 			detail: 'platform dir siblings windows/ + macos/ + linux/ co-present',
 			tier: 'strong',
 		})
@@ -531,7 +531,7 @@ function detectPlatformDirSiblings(relPaths) {
 	})
 	if (hasXcodeproj && hasGradle) {
 		found.push({
-			kind: 'xplatform-dir-siblings',
+			kind: 'crossplatform-dir-siblings',
 			detail: '*.xcodeproj + build.gradle co-presence',
 			tier: 'strong',
 		})
@@ -545,12 +545,14 @@ function detectPlatformDirSiblings(relPaths) {
  * @param {string[]} relPaths
  * @returns {Array<{kind:string, detail:string, tier:string}>}
  */
-function detectWeakXplatformFiles(relPaths) {
+function detectWeakCrossplatformFiles(relPaths) {
 	const found = []
 	for (const p of relPaths) {
 		const ext = extname(p.toLowerCase())
-		if (ext === '.plist') found.push({ kind: 'xplatform-file', detail: `plist ${p}`, tier: 'weak' })
-		else if (ext === '.rc') found.push({ kind: 'xplatform-file', detail: `rc ${p}`, tier: 'weak' })
+		if (ext === '.plist')
+			found.push({ kind: 'crossplatform-file', detail: `plist ${p}`, tier: 'weak' })
+		else if (ext === '.rc')
+			found.push({ kind: 'crossplatform-file', detail: `rc ${p}`, tier: 'weak' })
 	}
 	return found
 }
@@ -731,7 +733,7 @@ function applyScope(baselineSignals, diffSignals, diffTouchedPaths, scope) {
  * Read `.aperant/config.json:pr_review.specialists` (best-effort).
  *
  * @param {string} root
- * @returns {{ i18n?: string, xplatform?: string }}
+ * @returns {{ i18n?: string, crossplatform?: string }}
  */
 function readSpecialistConfig(root) {
 	try {
@@ -759,15 +761,15 @@ function normalizeMode(v) {
 /**
  * The core detector. Pure over its inputs (reads the filesystem at `root` and
  * the supplied `diffText`); returns the full
- * `{ i18n, xplatform }` decision object.
+ * `{ i18n, crossplatform }` decision object.
  *
  * @param {object} opts
  * @param {string} opts.root            absolute project dir
  * @param {string} [opts.diffText]      unified-diff text (optional)
  * @param {'repo'|'diff'} [opts.scope]  default 'repo'
- * @param {{i18n?:string, xplatform?:string}} [opts.config]  override config
+ * @param {{i18n?:string, crossplatform?:string}} [opts.config]  override config
  *        (read from .aperant/config.json when omitted)
- * @returns {{ i18n: SpecialistDecision, xplatform: SpecialistDecision }}
+ * @returns {{ i18n: SpecialistDecision, crossplatform: SpecialistDecision }}
  */
 export function detectSpecialists(opts) {
 	const root = resolve(opts.root)
@@ -776,7 +778,7 @@ export function detectSpecialists(opts) {
 	const diffText = opts.diffText ?? ''
 
 	const i18nMode = normalizeMode(config.i18n)
-	const xplatformMode = normalizeMode(config.xplatform)
+	const crossplatformMode = normalizeMode(config.crossplatform)
 
 	// Parse diff once (shared by both specialists).
 	const diff = diffText ? parseUnifiedDiff(diffText) : { touchedPaths: [], addedText: '' }
@@ -791,17 +793,17 @@ export function detectSpecialists(opts) {
 		collectDiff: collectI18nDiff,
 	})
 
-	// ── xplatform ───────────────────────────────────────────────────────────
-	const xplatform = decideSpecialist({
-		mode: xplatformMode,
+	// ── crossplatform ───────────────────────────────────────────────────────────
+	const crossplatform = decideSpecialist({
+		mode: crossplatformMode,
 		root,
 		diff,
 		scope,
-		collectBaseline: collectXplatformBaseline,
-		collectDiff: collectXplatformDiff,
+		collectBaseline: collectCrossplatformBaseline,
+		collectDiff: collectCrossplatformDiff,
 	})
 
-	return { i18n, xplatform }
+	return { i18n, crossplatform }
 }
 
 /**
@@ -880,7 +882,7 @@ function collectI18nDiff(diff) {
 	return dedupeSignals(signals)
 }
 
-function collectXplatformBaseline(root) {
+function collectCrossplatformBaseline(root) {
 	const signals = []
 	const files = walkFiles(root)
 
@@ -889,12 +891,12 @@ function collectXplatformBaseline(root) {
 		const abs = join(root, manifest)
 		if (!existsSync(abs)) continue
 		const text = readSafe(abs)
-		if (text) signals.push(...scanManifestForXplatform(manifest, text))
+		if (text) signals.push(...scanManifestForCrossplatform(manifest, text))
 	}
 	// pubspec.yaml present → Flutter (its presence alone is the flutter marker).
 	if (existsSync(join(root, 'pubspec.yaml'))) {
 		signals.push({
-			kind: 'xplatform-framework',
+			kind: 'crossplatform-framework',
 			detail: 'flutter (pubspec.yaml present)',
 			tier: 'strong',
 		})
@@ -930,9 +932,13 @@ function collectXplatformBaseline(root) {
 		) {
 			const text = readSafe(join(root, rel))
 			if (text) {
-				for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+				for (const { re, label } of CROSSPLATFORM_COMPILE_GUARD_RES) {
 					if (re.test(text)) {
-						signals.push({ kind: 'xplatform-guard', detail: `${label} in ${rel}`, tier: 'strong' })
+						signals.push({
+							kind: 'crossplatform-guard',
+							detail: `${label} in ${rel}`,
+							tier: 'strong',
+						})
 					}
 				}
 			}
@@ -941,25 +947,25 @@ function collectXplatformBaseline(root) {
 
 	// Platform dir siblings + weak files.
 	signals.push(...detectPlatformDirSiblings(files))
-	signals.push(...detectWeakXplatformFiles(files))
+	signals.push(...detectWeakCrossplatformFiles(files))
 
 	return dedupeSignals(signals)
 }
 
-function collectXplatformDiff(diff) {
+function collectCrossplatformDiff(diff) {
 	const signals = []
 	if (diff.addedText) {
 		const lowerAdded = diff.addedText.toLowerCase()
-		for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+		for (const fw of CROSSPLATFORM_FRAMEWORK_SUBSTRINGS) {
 			if (lowerAdded.includes(fw)) {
 				signals.push({
-					kind: 'xplatform-framework',
+					kind: 'crossplatform-framework',
 					detail: `${fw} (diff added line)`,
 					tier: 'strong',
 				})
 			}
 		}
-		signals.push(...scanSourceForXplatformTokens('diff', diff.addedText))
+		signals.push(...scanSourceForCrossplatformTokens('diff', diff.addedText))
 	}
 	// CI matrix introduced in the diff.
 	for (const rel of diff.touchedPaths) {
@@ -968,7 +974,7 @@ function collectXplatformDiff(diff) {
 			if (m) signals.push(m)
 		}
 	}
-	signals.push(...detectWeakXplatformFiles(diff.touchedPaths))
+	signals.push(...detectWeakCrossplatformFiles(diff.touchedPaths))
 	return dedupeSignals(signals)
 }
 
@@ -1018,6 +1024,6 @@ export function cmdDetectSpecialists(projectDir, extraArgs = []) {
 		command: 'pr-review-detect-specialists',
 		scope,
 		i18n: result.i18n,
-		xplatform: result.xplatform,
+		crossplatform: result.crossplatform,
 	})
 }

package/src/cli/commands/spar-resolve-partner.mjs

@@ -0,0 +1,85 @@
+/**
+ * commands/spar-resolve-partner.mjs — live partner-model resolver for `apt:spar`.
+ *
+ * Layer 1 cmd (returns { envelope, exitCode } via ok()/err() — never calls
+ * process.exit / output() / fail() directly; the Layer 2 wrapper in dispatch.mjs
+ * writes stdout and exits).
+ *
+ * `apt-tools spar-resolve-partner --partner <codex|claude|gemini>` returns the
+ * model the codex MCP rung must pass, read LIVE from `~/.codex/config.toml` with
+ * no baked default (Decision B + C). For claude / gemini the MCP rung needs no
+ * model arg, so the command returns `reason: 'self_resolving'` + `model: null`.
+ *
+ * Each envelope carries an EXPLICIT transport preference (plan-gate spar
+ * refinement #2): codex returns `prefer_self_resolving: true` +
+ * `recommended_walk: ['plugin','cli','mcp']` so the SKILL agent walks the
+ * self-resolving rungs first and only tries the model-naming MCP rung last. The
+ * `detect.mjs` `partner_transports` array stays MCP-first (ID-02); the agent
+ * follows THIS returned preference rather than inferring rung order from prose.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolveCodexSparModel } from '../host/codex-config.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Parse `--partner <id>` from the positional args. Defaults to `codex`
+ * (the only partner whose MCP rung requires a model arg).
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+function parsePartner(args) {
+	if (!Array.isArray(args)) return 'codex'
+	const idx = args.indexOf('--partner')
+	if (idx === -1 || idx === args.length - 1) return 'codex'
+	return String(args[idx + 1]).toLowerCase()
+}
+
+/**
+ * @param {string[]} [args]
+ * @returns {{ envelope: object, exitCode: number }}
+ */
+export function cmdSparResolvePartner(args = []) {
+	const partner = parsePartner(args)
+
+	if (partner === 'codex') {
+		const { available, model, source, reason } = resolveCodexSparModel({
+			home: homedir(),
+			existsSync,
+			readFileSync,
+		})
+		return ok({
+			status: 'ok',
+			command: 'spar-resolve-partner',
+			partner: 'codex',
+			available,
+			model,
+			source,
+			reason,
+			// Refinement #2 — explicit transport preference the SKILL FOLLOWS.
+			prefer_self_resolving: true,
+			recommended_walk: ['plugin', 'cli', 'mcp'],
+		})
+	}
+
+	if (partner === 'claude' || partner === 'gemini') {
+		return ok({
+			status: 'ok',
+			command: 'spar-resolve-partner',
+			partner,
+			available: true,
+			model: null,
+			source: null,
+			reason: 'self_resolving',
+			prefer_self_resolving: false,
+			recommended_walk: ['mcp', 'plugin', 'cli'],
+		})
+	}
+
+	return err(`Unknown partner: ${partner}. Expected codex, claude, or gemini.`, 1, {
+		command: 'spar-resolve-partner',
+		partner,
+	})
+}

package/src/cli/config/gitignore-drift.mjs

@@ -30,6 +30,7 @@ const SKIP_COMMANDS = new Set([
 	'health-check',
 	'toolchain-detect',
 	'host-detect',
+	'spar-resolve-partner', // read-only; spar parses its JSON stdout
 	'--version',
 	'--help',
 	'-v',

package/src/cli/config/post-merge-sweep.mjs

@@ -53,6 +53,7 @@ const SKIP_COMMANDS = new Set([
 	'health-check',
 	'toolchain-detect',
 	'host-detect',
+	'spar-resolve-partner', // read-only; spar parses its JSON stdout
 	'task', // recursion guard #1 — close-merged is a `task` subcommand
 	'--version',
 	'--help',