@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-issues/scripts/preflight-models.mjs

@@ -0,0 +1,736 @@
+#!/usr/bin/env node
+// resolve-issues fast path for model selection.
+//
+// One command: discover → tier (shared harness-runtime catalog) → recommend
+// implementer + fill explorer + fill diagnoser + fill reviewer ≠ implementer. Prints a ready
+// ask payload the orchestrator hands straight to the harness's native question
+// tool (see references/shared-modules.md) without reading longer workflow
+// doctrine before model selection.
+//
+// Maintenance (sync / bank) is deferred until AFTER the human answers — never
+// block the picker on catalog writes.
+//
+// Usage:
+//   node preflight-models.mjs --harness <pi|codex|claude-code> [--risk routine|high]
+//        [--available id,id,...] [--human-named id,id,...] [--implementer id[@effort]] [--ask-only]
+//
+// --implementer pins the implementer: it is the only option, and the run never
+// falls back to a recommended model when the pinned one is not available.
+//
+// Exit: 0 whenever it ran (a result with `ok: false` and a `code` of `no-slot-eligible` or
+// `pinned-implementer-unavailable` is the answer, not a failure) · 2 usage or crash
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  detectHarness,
+  discover,
+} from '../../harness-runtime/discover-models.mjs'
+import {
+  tierProposals,
+  pointsFromTiers,
+  isSlotEligible,
+  DEFAULT_EFFORT,
+  readCatalog,
+  pathForHarness,
+  readSeed,
+  defaultSeedPath,
+  findSeedEntry,
+} from '../../harness-runtime/model-catalog.mjs'
+
+export const RISK = Object.freeze(['routine', 'high'])
+
+// Preferred fills when discovery actually yielded the id (resolve-issues defaults).
+// Reviewer: the frontier band's home role is review (model-catalog.md). Since
+// 2026-09-23 the primary is gpt-6-astra@medium and the fallback (when the
+// implementer IS Astra — a human pick; resolve-issues never recommends frontier for
+// implementation) is gpt-5.6-sol@medium. Both are synthesized below-catalog
+// policy points (the catalog banks `high` per rule 6); the model ids are the
+// two frontier points by the official DeepSWE v1.1 board at high (73.2%±3.4,
+// 69.4%±1.4) and the *effort* comes from the local blinded review benchmark
+// (docs/research/2026-09-23-reviewer-benchmark-astra-vs-sol.md): Astra-medium
+// matched Sol-medium's useful-finding yield in under half the wall-clock time
+// and beat Astra-high on yield; Sol-high found three more at 3.5x the time.
+// Independence is by model id, never by effort.
+export const TEAM_REVIEWER_POLICY = Object.freeze({
+  pi: {
+    primary: { id: 'openai/gpt-6-astra', family: 'openai', effort: 'medium', tier: 'frontier' },
+    fallback: { id: 'openai/gpt-5.6-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+  },
+  codex: {
+    primary: { id: 'gpt-6-astra', family: 'openai', effort: 'medium', tier: 'frontier' },
+    fallback: { id: 'gpt-5.6-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+  },
+  'claude-code': {
+    primary: { id: 'gpt-6-astra', family: 'openai', effort: 'medium', tier: 'frontier' },
+    fallback: { id: 'gpt-5.6-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+  },
+})
+
+// Implementer ladders: ordered per risk and harness, first discovered point
+// wins. Order set by the team on 2026-09-23 over the DeepSWE v1.1 evidence in
+// the catalog notes (official board where a model has a run, vendor launch
+// figure otherwise). A frontier point reaches the recommendation only through
+// these ladders; the reviewer slot then switches to a distinct model id (an
+// Astra implementation is reviewed by gpt-5.6-sol@medium; every other rung by
+// gpt-6-astra@medium, a different family for the Grok/MiMo rungs).
+//
+// High risk (reordered 2026-09-30 by the team: gpt-6.1-sol@high first, 75.2
+// vendor at about a fifth of Astra's cost per task, then the rest unchanged):
+// gpt-6.1-sol@high → gpt-6-astra@high (73.2%±3.4 official, top of the board) →
+// gpt-5.6-sol@high (69.4%±1.4 official; slowest point in the local review
+// benchmark) → grok-4.7@high (71.0 vendor, $2/$6, not on the official board;
+// kept behind the two official frontier points until Datacurve runs it), over
+// gpt-5.5@high (64.4%±3.1, retiring from Codex 2026-10-14).
+//
+// Routine (reordered 2026-09-28 by the team: gpt-6-sol@high first, then
+// luna, grok-4.6, mimo; the evidence notes below are unchanged): gpt-6-luna@high (balanced-coder by human classification — OpenAI
+// published no high point, 66.6 vendor is at max; $0.10/$0.50. Pi smoke on one
+// small tool task: high 30s vs max 62s vs Terra@high 29s at ~1/20 the cost, so
+// high keeps Terra's latency at near-zero spend; max was too slow) →
+// grok-4.6@high (deep-reasoner; 65.2%±1.5 official, $2/$6) → mimo-v2.6-pro@high
+// (frontier; 71.9 vendor, $0.44/$0.87; MiMo's API has thinking on/off only, so
+// `high` labels that single point — behind grok-4.6 until an official run and
+// local trajectory evidence exist) → gpt-6-sol@high (deep-reasoner; 65.3 vendor;
+// replaced gpt-5.6-terra@high on 2026-09-27, ADR 0009). On 2026-09-30 every
+// gpt-6-sol rung became gpt-6.1-sol (75.2 vendor at high, frontier; Codex now
+// lists gpt-6-sol as previous generation), in the same positions. Only the OpenAI rungs
+// exist on Codex (it lists no Grok or MiMo ids). A rung discovery does not
+// yield is skipped; past the ladder the tier order applies.
+//
+// Escalation fix workers (test-first, last-try) always take the high-risk ladder
+// (gpt-6.1-sol@high first since 2026-09-30), whatever the run's risk (team
+// decision 2026-09-28).
+export const TEAM_IMPLEMENTER_PREFERENCE = Object.freeze({
+  routine: {
+    pi: [
+      { id: 'openai/gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'openai/gpt-6-luna', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+      { id: 'xai/grok-4.6', family: 'xai', effort: 'high', tier: 'deep-reasoner' },
+      { id: 'xiaomi/mimo-v2.6-pro', family: 'xiaomi', effort: 'high', tier: 'frontier' },
+    ],
+    codex: [
+      { id: 'gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-6-luna', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+    ],
+    'claude-code': [
+      { id: 'gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-6-luna', family: 'openai', effort: 'high', tier: 'balanced-coder' },
+      { id: 'grok-4.6', family: 'xai', effort: 'high', tier: 'deep-reasoner' },
+      { id: 'mimo-v2.6-pro', family: 'xiaomi', effort: 'high', tier: 'frontier' },
+    ],
+  },
+  high: {
+    pi: [
+      { id: 'openai/gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'openai/gpt-6-astra', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'openai/gpt-5.6-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'xai/grok-4.7', family: 'xai', effort: 'high', tier: 'frontier' },
+    ],
+    codex: [
+      { id: 'gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-6-astra', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-5.6-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+    ],
+    'claude-code': [
+      { id: 'gpt-6.1-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-6-astra', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'gpt-5.6-sol', family: 'openai', effort: 'high', tier: 'frontier' },
+      { id: 'grok-4.7', family: 'xai', effort: 'high', tier: 'frontier' },
+    ],
+  },
+})
+
+// Explorer: gpt-6.1-sol@medium first (ADR 0009 named gpt-6-sol; replaced
+// 2026-09-30; 73 vendor at medium), then the routine implementer ladder without
+// its gpt-6.1-sol@high rung. The medium point is below the catalog's banked `high`, so it is a
+// policy point synthesized from a discovered id, like the reviewer's; when
+// discovery does not yield gpt-6.1-sol, the fill falls through to the routine
+// ladder.
+export const TEAM_EXPLORER_POLICY = Object.freeze({
+  pi: { id: 'openai/gpt-6.1-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+  codex: { id: 'gpt-6.1-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+  'claude-code': { id: 'gpt-6.1-sol', family: 'openai', effort: 'medium', tier: 'frontier' },
+})
+
+export const TEAM_EXPLORER_DEFAULT = Object.freeze(
+  Object.fromEntries(
+    Object.entries(TEAM_IMPLEMENTER_PREFERENCE.routine).map(([harness, ladder]) => [
+      harness,
+      [TEAM_EXPLORER_POLICY[harness], ...ladder.filter((rung) => rung.id !== TEAM_EXPLORER_POLICY[harness].id)],
+    ]),
+  ),
+)
+
+const TIER_RANK = Object.freeze({
+  frontier: 0,
+  'deep-reasoner': 1,
+  'balanced-coder': 2,
+})
+
+function usage() {
+  return `preflight-models — discover + recommend implementer, fill explorer + reviewer (resolve-issues fast path)
+
+Usage:
+  node preflight-models.mjs --harness <pi|codex|claude-code> [--risk routine|high]
+       [--available <id,id,...>] [--human-named <id,id,...>] [--implementer <id[@effort]>] [--ask-only]
+
+Output JSON:
+  { harness, risk, discovery, models, implementer, explorer, diagnoser, reviewer, ask, deferred }
+
+--ask-only prints only the ask block (for piping into a question UI).
+--implementer pins the implementer (the only option); exit 4 when it is not an
+available slot-eligible point. Never substitute another model.
+Deferred: run catalog sync/bank AFTER the human answers — never before the ask.`
+}
+
+function parseList(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+export function parseArgs(argv) {
+  const out = {
+    harness: null,
+    risk: 'routine',
+    available: [],
+    humanNamed: [],
+    implementer: null,
+    askOnly: false,
+    help: false,
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h' || a === 'help') out.help = true
+    else if (a === '--ask-only') out.askOnly = true
+    else if (a === '--harness') out.harness = argv[++i]
+    else if (a === '--risk') out.risk = argv[++i]
+    else if (a === '--available') out.available = parseList(argv[++i])
+    else if (a === '--human-named') out.humanNamed = parseList(argv[++i])
+    else if (a === '--implementer') out.implementer = argv[++i]
+    else if (a.startsWith('--harness=')) out.harness = a.slice('--harness='.length)
+    else if (a.startsWith('--risk=')) out.risk = a.slice('--risk='.length)
+    else if (a.startsWith('--available=')) out.available = parseList(a.slice('--available='.length))
+    else if (a.startsWith('--human-named=')) out.humanNamed = parseList(a.slice('--human-named='.length))
+    else if (a.startsWith('--implementer=')) out.implementer = a.slice('--implementer='.length)
+    else throw new Error(`unknown argument: ${a}`)
+  }
+  if (out.implementer !== null && (typeof out.implementer !== 'string' || !out.implementer.trim())) throw new Error('--implementer needs a model id')
+  return out
+}
+
+/**
+ * The point a pin names: `id@effort` matches that operating point exactly; a
+ * bare `id` takes the floor effort when banked, else the id's first point.
+ */
+export function findPinnedPoint(points, pin) {
+  const text = String(pin || '').trim()
+  if (!text) return null
+  const at = text.lastIndexOf('@')
+  const id = at > 0 ? text.slice(0, at) : text
+  const effort = at > 0 ? text.slice(at + 1) : null
+  const same = points.filter((p) => p.id === id)
+  if (effort) return same.find((p) => p.effort === effort) || null
+  return same.find((p) => p.effort === DEFAULT_EFFORT) || same[0] || null
+}
+
+function familyOf(id, hinted) {
+  if (hinted) return hinted
+  if (id.includes('/')) return id.slice(0, id.indexOf('/'))
+  return 'unknown'
+}
+
+/** Prefer banked catalog family, then seed, then id prefix. */
+export function resolveFamily(harness, id, { catalog = null, seed = null } = {}) {
+  const banked = (catalog?.models || []).find((m) => m && m.id === id)
+  if (banked?.family) return banked.family
+  const seeded = seed ? findSeedEntry(seed, harness, id) : null
+  if (seeded?.family) return seeded.family
+  return familyOf(id)
+}
+
+function pointKey(id, effort) {
+  return `${id}@${effort || DEFAULT_EFFORT}`
+}
+
+/** Expand tierProposals().models into slot-eligible operating points. */
+export function slotPoints(tieredModels, { harness, catalog = null, seed = null } = {}) {
+  const points = []
+  for (const model of tieredModels) {
+    const entries = Object.keys(model.tiers || {}).length
+      ? pointsFromTiers(model.tiers)
+      : []
+    const family = resolveFamily(harness, model.id, { catalog, seed })
+    for (const p of entries) {
+      if (!isSlotEligible(p.tier)) continue
+      points.push({
+        id: model.id,
+        effort: p.effort || DEFAULT_EFFORT,
+        tier: p.tier,
+        family,
+        source: model.source,
+        citation: model.citation || null,
+        key: pointKey(model.id, p.effort || DEFAULT_EFFORT),
+      })
+    }
+  }
+  return points
+}
+
+function preferRisk(tier, risk) {
+  if (risk === 'high') {
+    if (tier === 'deep-reasoner') return 0
+    if (tier === 'balanced-coder') return 1
+    return 2 // frontier is never recommended by tier alone (only via the team ladder)
+  }
+  // routine
+  if (tier === 'balanced-coder') return 0
+  if (tier === 'deep-reasoner') return 1
+  return 2
+}
+
+/**
+ * Recommend implementer. The team ladder for the risk/harness is consulted
+ * first (high risk: gpt-6.1-sol, gpt-6-astra, gpt-5.6-sol, then grok-4.7, all
+ * @high — the ladder is the only way a frontier point becomes the
+ * recommendation; routine: gpt-6.1-sol@high, gpt-6-luna@high, grok-4.6@high,
+ * then mimo-v2.6-pro@high). Without a ladder hit
+ * the tier order applies: routine → balanced-coder; high → deep-reasoner;
+ * frontier is listed but never recommended by tier alone.
+ */
+export function recommendImplementer(points, risk = 'routine', harness = null) {
+  if (!points.length) return null
+  const ladder = harness ? TEAM_IMPLEMENTER_PREFERENCE[risk]?.[harness] || [] : []
+  for (const preferred of ladder) {
+    const preferredPoint = findPreferredPoint(points, preferred)
+    if (preferredPoint && preferredPoint.tier === preferred.tier) return preferredPoint
+  }
+  const sorted = [...points].sort((a, b) => {
+    const ra = preferRisk(a.tier, risk)
+    const rb = preferRisk(b.tier, risk)
+    if (ra !== rb) return ra - rb
+    // Prefer the floor effort when tied; then stable id.
+    if (a.effort !== b.effort) {
+      if (a.effort === DEFAULT_EFFORT) return -1
+      if (b.effort === DEFAULT_EFFORT) return 1
+      return a.effort < b.effort ? -1 : 1
+    }
+    return a.id.localeCompare(b.id)
+  })
+  // First non-frontier if any; else first point (single-model / only-frontier harness)
+  return sorted.find((p) => p.tier !== 'frontier') || sorted[0]
+}
+
+/**
+ * Escalation fix-worker fill (test-first, last-try): the high-risk implementer ladder
+ * (gpt-6.1-sol, gpt-6-astra, gpt-5.6-sol, then grok-4.7, all @high), whatever
+ * the run's risk.
+ */
+export function fillDiagnoser(points, harness) {
+  const fill = recommendImplementer(points, 'high', harness)
+  return { fill: fill || null, reason: fill ? 'high-risk-ladder' : 'none' }
+}
+
+function findPreferredPoint(points, preferred) {
+  if (!preferred) return null
+  return points.find(
+    (p) => p.id === preferred.id && (p.effort || DEFAULT_EFFORT) === (preferred.effort || DEFAULT_EFFORT),
+  ) || null
+}
+
+// Reviewer and explorer policy may deliberately use a below-catalog effort. The
+// catalog continues to describe pushed capability points (high/xhigh/max);
+// discovery of the model id is still required before this role-specific point
+// exists.
+function findPolicyPoint(points, preferred, { source, citation }) {
+  if (!preferred) return null
+  const discovered = points.find((p) => p.id === preferred.id)
+  if (!discovered) return null
+  if ((preferred.effort || DEFAULT_EFFORT) === DEFAULT_EFFORT) {
+    return findPreferredPoint(points, preferred)
+  }
+  return {
+    ...discovered,
+    effort: preferred.effort,
+    tier: preferred.tier,
+    source,
+    citation,
+    key: pointKey(preferred.id, preferred.effort),
+  }
+}
+
+const REVIEW_POLICY_SOURCE = Object.freeze({
+  source: 'team-review-policy',
+  citation: 'docs/research/2026-09-23-reviewer-benchmark-astra-vs-sol.md',
+})
+const EXPLORER_POLICY_SOURCE = Object.freeze({
+  source: 'team-explorer-policy',
+  citation: 'docs/adr/0009-orchestrator-coordinates-only.md',
+})
+
+function findReviewerPolicyPoint(points, preferred) {
+  return findPolicyPoint(points, preferred, REVIEW_POLICY_SOURCE)
+}
+
+/**
+ * Explorer fill: gpt-6.1-sol@medium when gpt-6.1-sol is discovered, then the
+ * routine implementer ladder without its gpt-6.1-sol@high rung (gpt-6-luna@high,
+ * grok-4.6@high, then mimo-v2.6-pro@high), first discovered rung wins;
+ * without a rung, the balanced-coder tier.
+ */
+export function fillExplorer(points, harness) {
+  const ladder = TEAM_EXPLORER_DEFAULT[harness] || []
+  const policy = TEAM_EXPLORER_POLICY[harness]
+  let preferredPoint = null
+  for (const preferred of ladder) {
+    const candidate = preferred === policy
+      ? findPolicyPoint(points, preferred, EXPLORER_POLICY_SOURCE)
+      : findPreferredPoint(points, preferred)
+    if (candidate) {
+      preferredPoint = candidate
+      if (candidate.tier === preferred.tier) return { fill: candidate, reason: 'team-default' }
+    }
+  }
+  const balanced = points
+    .filter((p) => p.tier === 'balanced-coder')
+    .sort((a, b) => {
+      if (a.effort === DEFAULT_EFFORT && b.effort !== DEFAULT_EFFORT) return -1
+      if (b.effort === DEFAULT_EFFORT && a.effort !== DEFAULT_EFFORT) return 1
+      return a.id.localeCompare(b.id)
+    })
+  const fill = balanced[0] || null
+  return {
+    fill,
+    reason: fill ? (preferredPoint ? 'ladder' : 'balanced-coder') : 'none',
+  }
+}
+
+/**
+ * Reviewer fill is implementer-aware and must differ by model id:
+ * Astra implementer -> gpt-5.6-sol@medium; otherwise -> gpt-6-astra@medium. If that
+ * policy point is unavailable, the existing diversity-first ladder applies.
+ */
+export function rankReviewers(points, implementer, harness) {
+  const policy = TEAM_REVIEWER_POLICY[harness] || null
+  const deepPool = points.filter((p) => p.tier === 'deep-reasoner' || p.tier === 'frontier')
+  const pool = deepPool.length ? deepPool : points
+  const scored = pool.map((p) => {
+    const sameId = p.id === implementer.id
+    const sameFamily = p.family && implementer.family && p.family === implementer.family
+    let diversity
+    if (sameId) diversity = 5
+    else if (!sameFamily && p.tier === 'deep-reasoner') diversity = 0
+    else if (!sameFamily && p.tier === 'frontier') diversity = 1
+    else if (sameFamily && p.tier === 'deep-reasoner') diversity = 2
+    else if (!sameFamily) diversity = 3
+    else diversity = 4
+    return { ...p, diversity, tierRank: TIER_RANK[p.tier] ?? 9 }
+  })
+  scored.sort((a, b) => {
+    if (a.diversity !== b.diversity) return a.diversity - b.diversity
+    if (a.tierRank !== b.tierRank) return a.tierRank - b.tierRank
+    return a.id.localeCompare(b.id)
+  })
+
+  const primaryPoint = findReviewerPolicyPoint(points, policy?.primary)
+  const fallbackPoint = findReviewerPolicyPoint(points, policy?.fallback)
+
+  const ranking = []
+  const rankedIds = new Set()
+  for (const candidate of [primaryPoint, fallbackPoint, ...scored]) {
+    if (!candidate || rankedIds.has(candidate.id)) continue
+    rankedIds.add(candidate.id)
+    ranking.push(candidate)
+  }
+
+  const implementerIsPrimary = implementer.id === policy?.primary?.id
+  const policyFill = implementerIsPrimary ? fallbackPoint : primaryPoint
+  const fill = policyFill && policyFill.id !== implementer.id
+    ? policyFill
+    : scored.find((p) => p.id !== implementer.id) || scored[0]
+  let reason
+  if (fill?.id === primaryPoint?.id) reason = 'team-default'
+  else if (fill?.id === fallbackPoint?.id && implementerIsPrimary) reason = 'implementer-aware-default'
+  else reason = fill?.id === implementer.id ? 'no-distinct-candidate' : 'ladder'
+
+  return {
+    fill,
+    reason,
+    ranking,
+    teamDefaultApplied: reason === 'team-default' || reason === 'implementer-aware-default',
+    reducedDiversity: !!(fill && implementer && fill.family && fill.family === implementer.family && fill.id !== implementer.id),
+    notIndependent: !!(fill && implementer && fill.id === implementer.id),
+  }
+}
+
+function optionFromPoint(p, { recommended = false, role, ladderRung = 0 }) {
+  const why =
+    role === 'implementer'
+      ? ladderRung
+        ? `team ladder rung ${ladderRung}${recommended ? '' : ' — next discovered rung'}`
+        : p.tier === 'balanced-coder'
+          ? 'routine implementer band'
+          : p.tier === 'deep-reasoner'
+            ? 'deep-reasoner for risk-heavy work'
+            : p.tier === 'frontier'
+              ? recommended
+                ? 'frontier — team implementer ladder preference'
+                : 'frontier (alternate only — not the recommendation)'
+              : p.tier
+      : p.tier
+  return {
+    id: p.key, // operating point id for the picker; parse back to model+effort
+    modelId: p.id,
+    label: `${p.id} @ ${p.effort}`,
+    description: `${p.tier}${recommended ? ' · recommended' : ''} · ${why}`,
+    family: p.family,
+    effort: p.effort,
+    tier: p.tier,
+  }
+}
+
+/** Native question UIs typically allow 2–4 options. Keep the rest as `alternates`. */
+export const ASK_OPTION_LIMIT = 4
+
+function slotFillPayload(slot) {
+  if (!slot?.fill) return null
+  return {
+    id: slot.fill.key,
+    modelId: slot.fill.id,
+    effort: slot.fill.effort,
+    family: slot.fill.family,
+    tier: slot.fill.tier,
+    reason: slot.reason,
+    reducedDiversity: slot.reducedDiversity || false,
+    notIndependent: slot.notIndependent || false,
+  }
+}
+
+/**
+ * The ask's options are the team ladder for this risk/harness, in ladder order,
+ * limited to the rungs discovery actually yielded, then the remaining points by
+ * risk-matched band and id. The ladder is the policy; before 2026-09-23 the
+ * options were band-then-id, which pushed the ladder rungs (gpt-5.6-sol,
+ * grok-4.7, gpt-6-sol) into `alternates` behind whichever deep-reasoners sorted
+ * first by id, and native pickers never show alternates. One frontier point is
+ * kept visible only when none of the primary options is frontier already.
+ */
+export function buildAsk(implementer, points, reviewer, { risk = 'routine', explorer = null, diagnoser = null, harness = null, pinned = false } = {}) {
+  if (pinned) {
+    return {
+      header: 'Implementer',
+      question: 'The implementer is pinned for this run; it is the only option. (Explorer + reviewer are filled automatically; reviewer ≠ implementer.)',
+      recommended: implementer.key,
+      pinned: true,
+      options: [{ ...optionFromPoint(implementer, { recommended: true, role: 'implementer' }), description: `${implementer.tier} · pinned` }],
+      alternates: [],
+      explorerFill: slotFillPayload(explorer),
+      diagnoserFill: slotFillPayload(diagnoser),
+      reviewerFill: slotFillPayload(reviewer),
+    }
+  }
+  const seen = new Set()
+  const ordered = []
+  const ladderRungByKey = new Map()
+  const push = (p) => {
+    if (!p || seen.has(p.key)) return
+    seen.add(p.key)
+    ordered.push(p)
+  }
+  push(implementer)
+  const ladder = harness ? TEAM_IMPLEMENTER_PREFERENCE[risk]?.[harness] || [] : []
+  ladder.forEach((preferred, index) => {
+    const point = findPreferredPoint(points, preferred)
+    if (point && point.tier === preferred.tier) {
+      ladderRungByKey.set(point.key, index + 1)
+      push(point)
+    }
+  })
+  // Then the remaining points by risk-matched band, then id.
+  const rest = [...points].sort((a, b) => preferRisk(a.tier, risk) - preferRisk(b.tier, risk) || a.id.localeCompare(b.id))
+  for (const p of rest) push(p)
+  let primary = ordered.slice(0, ASK_OPTION_LIMIT)
+  const frontier = ordered.find((p) => p.tier === 'frontier' && p.key !== implementer?.key)
+  if (frontier && !primary.some((p) => p.tier === 'frontier') && primary.length === ASK_OPTION_LIMIT) {
+    primary = [...primary.slice(0, ASK_OPTION_LIMIT - 1), frontier]
+  }
+  const primaryKeys = new Set(primary.map((p) => p.key))
+  const optionFor = (p, recommended) =>
+    optionFromPoint(p, { recommended, role: 'implementer', ladderRung: ladderRungByKey.get(p.key) || 0 })
+  const options = primary.map((p) => optionFor(p, p.key === implementer?.key))
+  const alternates = ordered.filter((p) => !primaryKeys.has(p.key)).map((p) => optionFor(p, false))
+
+  return {
+    header: 'Implementer',
+    question: 'Which model should implement every issue in this run? (Explorer + reviewer are filled automatically; reviewer ≠ implementer.)',
+    recommended: implementer?.key || null,
+    options,
+    alternates,
+    explorerFill: slotFillPayload(explorer),
+    diagnoserFill: slotFillPayload(diagnoser),
+    reviewerFill: slotFillPayload(reviewer),
+  }
+}
+
+export function buildPreflightModels({
+  harness,
+  risk = 'routine',
+  available = [],
+  humanNamed = [],
+  implementer: pin = null,
+  env = process.env,
+  discoverFn = discover,
+  tierFn = tierProposals,
+} = {}) {
+  if (!harness) throw new Error('harness is required')
+  if (!RISK.includes(risk)) throw new Error(`risk must be one of ${RISK.join('|')}`)
+
+  const discovery = discoverFn(harness, env, {
+    spawnModelIds: available,
+    humanNamedModelIds: humanNamed,
+  })
+  const seenIds = discovery.discovered.map((d) => d.id)
+  const tiered = tierFn(harness, seenIds)
+  const catalog = readCatalog(pathForHarness(harness, env))
+  const seed = readSeed(defaultSeedPath())
+  const points = slotPoints(tiered.models, { harness, catalog, seed })
+  const implementer = pin ? findPinnedPoint(points, pin) : recommendImplementer(points, risk, harness)
+  if (pin && !implementer) {
+    return {
+      ok: false,
+      code: 'pinned-implementer-unavailable',
+      pinned: pin,
+      harness,
+      risk,
+      discovery,
+      models: tiered,
+      points: points.map((p) => p.key),
+      implementer: null,
+      explorer: null,
+      diagnoser: null,
+      reviewer: null,
+      ask: null,
+      reason: `${pin} is not an available slot-eligible model here; block the run, never substitute another implementer`,
+    }
+  }
+  if (!implementer) {
+    return {
+      ok: false,
+      code: 'no-slot-eligible',
+      harness,
+      risk,
+      discovery,
+      models: tiered,
+      points: [],
+      implementer: null,
+      explorer: null,
+      diagnoser: null,
+      reviewer: null,
+      ask: null,
+      deferred: {
+        afterConfirm: [
+          'model-catalog.mjs sync --harness <h> --seen <ids>',
+          'model-catalog.mjs bank / bank-from-seed for any human confirmation',
+        ],
+      },
+    }
+  }
+  const explorer = fillExplorer(points, harness)
+  const diagnoser = fillDiagnoser(points, harness)
+  const reviewer = rankReviewers(points, implementer, harness)
+  const ask = buildAsk(implementer, points, reviewer, { risk, explorer, diagnoser, harness, pinned: !!pin })
+  return {
+    ok: true,
+    ...(pin ? { pinned: pin } : {}),
+    harness,
+    risk,
+    discovery: {
+      completeness: discovery.completeness,
+      discovered: discovery.discovered,
+      notes: discovery.notes,
+    },
+    models: tiered,
+    points,
+    implementer,
+    explorer: {
+      fill: explorer.fill,
+      reason: explorer.reason,
+    },
+    diagnoser: {
+      fill: diagnoser.fill,
+      reason: diagnoser.reason,
+    },
+    reviewer: {
+      fill: reviewer.fill,
+      reason: reviewer.reason,
+      ranking: reviewer.ranking.map((p) => p.key),
+      teamDefaultApplied: reviewer.teamDefaultApplied,
+      reducedDiversity: reviewer.reducedDiversity,
+      notIndependent: reviewer.notIndependent,
+    },
+    ask,
+    deferred: {
+      afterConfirm: [
+        `model-catalog.mjs sync --harness ${harness} --seen ${seenIds.join(',')}`,
+        'bank confirmations only after the human answers — never before the ask',
+      ],
+      doNotReadBeforeAsk: [
+        'harness-runtime/references/model-catalog.md',
+      ],
+    },
+  }
+}
+
+export function runCli(argv, env = process.env) {
+  let args
+  try {
+    args = parseArgs(argv)
+  } catch (e) {
+    console.error(`preflight-models: ${e.message}`)
+    console.error(usage())
+    return 2
+  }
+  if (args.help) {
+    console.log(usage())
+    return 0
+  }
+  const harness = args.harness || detectHarness(env)
+  if (!harness) {
+    console.error('preflight-models: pass --harness <pi|codex|claude-code>')
+    return 2
+  }
+  if (!RISK.includes(args.risk)) {
+    console.error(`preflight-models: --risk must be ${RISK.join('|')}`)
+    return 2
+  }
+
+  let result
+  try {
+    result = buildPreflightModels({
+      harness,
+      risk: args.risk,
+      available: args.available,
+      humanNamed: args.humanNamed,
+      implementer: args.implementer,
+      env,
+    })
+  } catch (e) {
+    console.error(`preflight-models: ${e.message}`)
+    return 2
+  }
+
+  if (!result.ok) {
+    console.log(JSON.stringify(result, null, 2))
+    return 0
+  }
+  if (args.askOnly) {
+    console.log(JSON.stringify(result.ask, null, 2))
+    return 0
+  }
+  console.log(JSON.stringify(result, null, 2))
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}