roadmodel 0.2.83__tar.gz → 0.2.85__tar.gz

{roadmodel-0.2.83 → roadmodel-0.2.85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.83
+Version: 0.2.85
 Summary: BYO-key CLI that recommends the right AI model, platform, and settings for a prompt.
 Project-URL: Homepage, https://roadmodel.ai
 Project-URL: Repository, https://github.com/nathanramoscfa/roadmodel
@@ -607,6 +607,7 @@ server and the reasoning-effort default in parity automatically.
 | `roadmodel recommend --model`    | Override the specific model ID on the chosen provider.                             |
 | `roadmodel recommend --user-context PATH` | Override the user-context.md location for this invocation.                |
 | `roadmodel score --category C --complexity X` | Rank (model, platform, effort) candidates in code for a classified task — no engine call. See [docs/scoring-model.md](docs/scoring-model.md). |
+| `roadmodel backup --category C --complexity X --model M --effort E` | Name the cross-maker backup for a pick, by the rule /recommend uses — no engine call. Prints the roadmap Settings Backup cell, and first a `MODEL` cell when a newer version of the pick's model (same platform, no dearer) scores level or better at its effort. |
 | `roadmodel catalog show`         | Print the bundled `model-selector.txt` (use `--doc tier-cost-scale` for the price doc). |
 | `roadmodel catalog path`         | Print the on-disk path of the bundled catalog document (same `--doc` flag).        |
 | `roadmodel context show`         | Print the resolved `user-context.md` file.                                         |

{roadmodel-0.2.83 → roadmodel-0.2.85}/README.md

@@ -356,6 +356,7 @@ server and the reasoning-effort default in parity automatically.
 | `roadmodel recommend --model`    | Override the specific model ID on the chosen provider.                             |
 | `roadmodel recommend --user-context PATH` | Override the user-context.md location for this invocation.                |
 | `roadmodel score --category C --complexity X` | Rank (model, platform, effort) candidates in code for a classified task — no engine call. See [docs/scoring-model.md](docs/scoring-model.md). |
+| `roadmodel backup --category C --complexity X --model M --effort E` | Name the cross-maker backup for a pick, by the rule /recommend uses — no engine call. Prints the roadmap Settings Backup cell, and first a `MODEL` cell when a newer version of the pick's model (same platform, no dearer) scores level or better at its effort. |
 | `roadmodel catalog show`         | Print the bundled `model-selector.txt` (use `--doc tier-cost-scale` for the price doc). |
 | `roadmodel catalog path`         | Print the on-disk path of the bundled catalog document (same `--doc` flag).        |
 | `roadmodel context show`         | Print the resolved `user-context.md` file.                                         |

{roadmodel-0.2.83 → roadmodel-0.2.85}/docs/claude-commands/roadmap-refresh.md

@@ -180,8 +180,21 @@ exclusion in the selector, and include a backup model.
   A changed backup alone counts as a difference; name it in that line.
 - Every table carries a `Backup` row directly under `Model`: the
   selector's BACKUP with its own platform and dial in one cell
-  (`GPT-5.6 Terra — Codex · Intelligence Medium`), or `None`. A table
-  written before roadmodel 0.2.41 has no such row: add it from the
+  (`GPT-5.6 Terra — Codex · Intelligence Medium`), or `None`. Where
+  `roadmodel` is installed, the cell is the one `roadmodel backup
+  --category <c> --complexity <x> [--novel] --model <the step's model>
+  --effort <the step's effort>` prints for the step's classification —
+  the rule /recommend backs a pick up by, which takes the cheaper of two
+  substitutes the benchmarks cannot tell apart — and it outranks the
+  selector's BACKUP. When the command also prints a `MODEL` line, that
+  cell replaces the step's model — a newer version of the same model
+  (GPT-6 Sol → GPT-6.1 Sol), on the same platform, no dearer, that
+  scores level or better at the step's effort; the selector's letters
+  are measured at each model's top effort, and a step that runs lower
+  can reverse them. That is a difference: rewrite the table, its Model
+  rationale and its selection block with the `MODEL` cell, keep the
+  Backup cell printed with it, and add the `Settings updated` line.
+  A table written before roadmodel 0.2.41 has no such row: add it from the
   backup the step already names (its Model rationale's closing
   sentence, or its entry in the Model selection blocks) — a layout
   fix, not a new pick, so it takes no `Settings updated` line.

{roadmodel-0.2.83 → roadmodel-0.2.85}/docs/templates/prompt-phase-roadmap.md

@@ -103,7 +103,20 @@ selector in `@planning/model-selector.txt` (prices from
 You are the engine — do not call any external API. Honor every
 availability exclusion in the selector, and write each step's backup
 model into its Settings table's Backup row, with the backup's own
-platform and dial.
+platform and dial. Where `roadmodel` is installed, the Backup row is
+the cell `roadmodel backup --category <c> --complexity <x> [--novel]
+--model <the step's model> --effort <the step's effort>` prints for the
+step's own classification: the rule /recommend backs a pick up by, in
+code, which takes the cheaper of two substitutes the benchmarks cannot
+tell apart. The selector's BACKUP stands only where it is not
+installed. When the command also prints a `MODEL` line, that cell
+replaces the step's model: a newer version of the same model (GPT-6 Sol
+→ GPT-6.1 Sol), on the same platform, no dearer, that scores level or
+better at the step's effort. The selector's letters are measured at each
+model's top effort, and a step that runs lower can reverse them. Write
+the `MODEL` cell into the Model row, the Model rationale and the step's
+selection block, citing the newer model's figures at the step's effort,
+and keep the Backup cell printed with it.
 
 Honor the template's style rules: 80-column prose, zero `{{...}}`
 tokens left, `**Status:** Not started` directly under the title and

{roadmodel-0.2.83 → roadmodel-0.2.85}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.83"
+version = "0.2.85"
 description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
 readme = "README.md"
 requires-python = ">=3.11"

{roadmodel-0.2.83 → roadmodel-0.2.85}/roadmodel/data/prompt-phase-roadmap.md

@@ -103,7 +103,20 @@ selector in `@planning/model-selector.txt` (prices from
 You are the engine — do not call any external API. Honor every
 availability exclusion in the selector, and write each step's backup
 model into its Settings table's Backup row, with the backup's own
-platform and dial.
+platform and dial. Where `roadmodel` is installed, the Backup row is
+the cell `roadmodel backup --category <c> --complexity <x> [--novel]
+--model <the step's model> --effort <the step's effort>` prints for the
+step's own classification: the rule /recommend backs a pick up by, in
+code, which takes the cheaper of two substitutes the benchmarks cannot
+tell apart. The selector's BACKUP stands only where it is not
+installed. When the command also prints a `MODEL` line, that cell
+replaces the step's model: a newer version of the same model (GPT-6 Sol
+→ GPT-6.1 Sol), on the same platform, no dearer, that scores level or
+better at the step's effort. The selector's letters are measured at each
+model's top effort, and a step that runs lower can reverse them. Write
+the `MODEL` cell into the Model row, the Model rationale and the step's
+selection block, citing the newer model's figures at the step's effort,
+and keep the Backup cell printed with it.
 
 Honor the template's style rules: 80-column prose, zero `{{...}}`
 tokens left, `**Status:** Not started` directly under the title and

{roadmodel-0.2.83 → roadmodel-0.2.85}/roadmodel/data/roadmap-refresh.md

@@ -180,8 +180,21 @@ exclusion in the selector, and include a backup model.
   A changed backup alone counts as a difference; name it in that line.
 - Every table carries a `Backup` row directly under `Model`: the
   selector's BACKUP with its own platform and dial in one cell
-  (`GPT-5.6 Terra — Codex · Intelligence Medium`), or `None`. A table
-  written before roadmodel 0.2.41 has no such row: add it from the
+  (`GPT-5.6 Terra — Codex · Intelligence Medium`), or `None`. Where
+  `roadmodel` is installed, the cell is the one `roadmodel backup
+  --category <c> --complexity <x> [--novel] --model <the step's model>
+  --effort <the step's effort>` prints for the step's classification —
+  the rule /recommend backs a pick up by, which takes the cheaper of two
+  substitutes the benchmarks cannot tell apart — and it outranks the
+  selector's BACKUP. When the command also prints a `MODEL` line, that
+  cell replaces the step's model — a newer version of the same model
+  (GPT-6 Sol → GPT-6.1 Sol), on the same platform, no dearer, that
+  scores level or better at the step's effort; the selector's letters
+  are measured at each model's top effort, and a step that runs lower
+  can reverse them. That is a difference: rewrite the table, its Model
+  rationale and its selection block with the `MODEL` cell, keep the
+  Backup cell printed with it, and add the `Settings updated` line.
+  A table written before roadmodel 0.2.41 has no such row: add it from the
   backup the step already names (its Model rationale's closing
   sentence, or its entry in the Model selection blocks) — a layout
   fix, not a new pick, so it takes no `Settings updated` line.

{roadmodel-0.2.83 → roadmodel-0.2.85}/src/roadmodel/__init__.py

@@ -1,2 +1,2 @@
 # src/roadmodel/__init__.py
-__version__ = "0.2.83"
+__version__ = "0.2.85"

{roadmodel-0.2.83 → roadmodel-0.2.85}/src/roadmodel/cli.py

@@ -418,6 +418,23 @@ def recommend(
     click.echo(_format_structured_text(structured), nl=False)
 
 
+def _scoring_user_context(user_context_path: Path | None) -> str:
+    """The user-context text the scorer reads: ``--user-context``, else
+    ROADMODEL_USER_CONTEXT, else the default path; empty when none exists. A
+    path named explicitly that does not exist is an error."""
+    if user_context_path is not None and not user_context_path.expanduser().exists():
+        raise UserContextNotFoundError(user_context_path.expanduser())
+    env_user_context = os.environ.get("ROADMODEL_USER_CONTEXT")
+    if (
+        user_context_path is None
+        and env_user_context
+        and not Path(env_user_context).expanduser().exists()
+    ):
+        raise UserContextNotFoundError(Path(env_user_context).expanduser())
+    resolved = user_context.resolve(cli_path=user_context_path)
+    return user_context.read(resolved) if resolved.exists() else ""
+
+
 @cli.command("score")
 @click.option(
     "--category",
@@ -474,17 +491,7 @@ def score_command(
     funding, consumption headroom and Usage-pool status from user-context.md.
     Every term is printed so a pick can be audited line by line.
     """
-    if user_context_path is not None and not user_context_path.expanduser().exists():
-        raise UserContextNotFoundError(user_context_path.expanduser())
-    env_user_context = os.environ.get("ROADMODEL_USER_CONTEXT")
-    if (
-        user_context_path is None
-        and env_user_context
-        and not Path(env_user_context).expanduser().exists()
-    ):
-        raise UserContextNotFoundError(Path(env_user_context).expanduser())
-    resolved = user_context.resolve(cli_path=user_context_path)
-    text = user_context.read(resolved) if resolved.exists() else ""
+    text = _scoring_user_context(user_context_path)
     posture = (budget or scoring.declared_budget(text)).lower()
     try:
         task = scoring.Task(
@@ -504,6 +511,112 @@ def score_command(
     click.echo(scoring.render_text(ranking, limit=top))
 
 
+@cli.command("backup")
+@click.option(
+    "--category",
+    required=True,
+    type=click.Choice(list(scoring.CATEGORIES), case_sensitive=False),
+    help="PRIMARY task category of the pick.",
+)
+@click.option(
+    "--complexity",
+    required=True,
+    type=click.Choice(list(scoring.COMPLEXITIES), case_sensitive=False),
+    help="Overall complexity of the pick's task.",
+)
+@click.option("--novel", is_flag=True, default=False, help="High complexity AND novel.")
+@click.option("--model", required=True, help="The pick's model: catalog id or name.")
+@click.option("--effort", required=True, help="The pick's effort, as its dial names it.")
+@click.option(
+    "--budget",
+    type=click.Choice(list(scoring.BUDGETS), case_sensitive=False),
+    default=None,
+    help="Budget posture; defaults to the user-context's declared Budget priority.",
+)
+@click.option(
+    "--output",
+    type=click.Choice(["text", "json"], case_sensitive=False),
+    default="text",
+    show_default=True,
+)
+@click.option(
+    "--user-context",
+    "user_context_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Path to user-context.md override.",
+)
+def backup_command(
+    category: str,
+    complexity: str,
+    novel: bool,
+    model: str,
+    effort: str,
+    budget: str | None,
+    output: str,
+    user_context_path: Path | None,
+) -> None:
+    """Name the cross-maker backup for a pick, in code — no engine call.
+
+    The rule /recommend backs each pick up by: another maker's model that does
+    the job as well, for the least; where the benchmarks cannot tell two
+    substitutes apart, the cheaper. Prints the roadmap Settings Backup cell.
+
+    When a newer version of the pick's model (same maker and series, on the
+    same platform, no dearer) scores level or better at the pick's effort, it
+    first prints that model on a MODEL line: the step runs it instead, and the
+    backup printed is its backup.
+    """
+    text = _scoring_user_context(user_context_path)
+    posture = (budget or scoring.declared_budget(text)).lower()
+    try:
+        task = scoring.Task(category.lower(), complexity.lower(), novel, posture)
+        successor = scoring.successor_for_pick(task, text, model, effort)
+        runs = successor.candidate.model_id if successor is not None else model
+        backup = scoring.backup_for_pick(task, text, runs, effort)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    cell = scoring.backup_cell(backup) if backup is not None else "None"
+    model_cell = scoring.backup_cell(successor) if successor is not None else None
+    if output.lower() == "json":
+        payload: dict[str, Any] = {
+            "model": None,
+            "model_cell": model_cell,
+            "backup": None,
+            "cell": cell,
+        }
+        if successor is not None:
+            s = successor.candidate
+            payload["model"] = {
+                "model_id": s.model_id,
+                "model": s.model_name,
+                "platform_id": s.platform_id,
+                "platform": s.platform_name,
+                "effort": successor.effort,
+                "native_effort": successor.native,
+                "replaces": successor.replaces,
+            }
+        if backup is not None:
+            c = backup.candidate
+            payload["backup"] = {
+                "model_id": c.model_id,
+                "model": c.model_name,
+                "platform_id": c.platform_id,
+                "platform": c.platform_name,
+                "effort": backup.effort,
+                "native_effort": backup.native,
+            }
+        click.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+        return
+    if successor is not None:
+        click.echo(f"MODEL    {model_cell}")
+        click.echo(
+            f"         replaces {successor.replaces}: a newer version, no dearer, "
+            "level or better at this effort"
+        )
+    click.echo(f"BACKUP   {cell}")
+
+
 @cli.command("cost")
 @click.option("--model", required=True, help="Catalog model id or display name.")
 @click.option("--platform", required=True, help="Access method id or display name.")

{roadmodel-0.2.83 → roadmodel-0.2.85}/src/roadmodel/scoring.py

@@ -137,8 +137,19 @@ _RANK_SCALED_KEYS: Final[frozenset[str]] = frozenset(
 
 # Editorial letter → quality points. Midpoints of five equal bands.
 LETTER_QUALITY: Final[dict[str, float]] = {"S": 90.0, "A": 70.0, "B": 50.0, "C": 30.0, "D": 10.0}
-# When AA has measured the model: weight on the scaled evidence vs the letter.
+# When AA has measured the model in speed: weight on the scaled evidence vs
+# the letter (speed's letter is an estimate, not derived from tokens/s).
 EVIDENCE_WEIGHT: Final[float] = 0.7
+# The five derived categories: update/derive_ratings.py letters them from the
+# very benchmark CATEGORY_EVIDENCE names, so a measured model's letter there
+# is a staircase of evidence already counted. Blending it in adds no
+# information, only a cliff at each band edge: GPT-6 Astra's 52.7 on the AA
+# Index reads S and GPT-6.1 Sol's 51.8 reads A, six quality points for 0.9
+# of index. A model measured there is scored on its evidence alone; its
+# letter stands in only where AA has not measured it.
+DERIVED_LETTER_CATEGORIES: Final[frozenset[str]] = frozenset(
+    {"coding", "planning", "agentic", "long-context", "knowledge"}
+)
 # A letter with no AA measurement behind it is an editorial prior, not
 # evidence: discount it so a measured model wins an otherwise-tied letter.
 UNMEASURED_DISCOUNT: Final[float] = 5.0
@@ -886,7 +897,8 @@ def _quality(
     level: str | None = None,
 ) -> tuple[float, str, str]:
     """The model's quality for the task's category: its headline evidence, or
-    with ``level`` its evidence at that effort, blended with its letter."""
+    with ``level`` its evidence at that effort; in speed blended with its
+    letter, in a derived category (:data:`DERIVED_LETTER_CATEGORIES`) alone."""
     raw_tiers = model.get("tiers")
     tiers: dict[str, Any] = raw_tiers if isinstance(raw_tiers, dict) else {}
     letter = str(tiers.get(task.category, "C")).upper()
@@ -898,6 +910,8 @@ def _quality(
     points = _evidence_points(str(model.get("id", "")), task, bench, scale, level)
     if points is None:
         return max(0.0, letter_q - UNMEASURED_DISCOUNT), "letter", letter
+    if task.category in DERIVED_LETTER_CATEGORIES:
+        return points, f"aa:{CATEGORY_EVIDENCE[task.category]}", letter
     q = EVIDENCE_WEIGHT * points + (1.0 - EVIDENCE_WEIGHT) * letter_q
     return q, f"aa:{CATEGORY_EVIDENCE[task.category]}+letter", letter
 
@@ -1244,10 +1258,24 @@ def rank(
     backup: Candidate | None = None
     warning: str | None = None
     if primary is not None:
-        for c in candidates[1:]:
-            if c.provider != primary.provider and c.funding != "unfunded":
-                backup = c
-                break
+        others = [
+            c for c in candidates[1:] if c.provider != primary.provider and c.funding != "unfunded"
+        ]
+        if others:
+            # The best-scoring other maker's model, else the cheapest one the
+            # evidence cannot tell from it (:func:`_near_tied`), whatever the
+            # posture: at budget best the score barely prices a model, and a
+            # fraction of an AA point within noise would buy a dearer backup.
+            ref = others[0]
+            band = _aa_band(bench, cat)
+
+            def aa(c: Candidate) -> float | None:
+                return _evidence(bench, c.model_id, FRONTIER_INDEX, c.evidence_level)
+
+            backup = min(
+                (c for c in others if _near_tied(c, aa(c), ref, aa(ref), task.category, band)),
+                key=lambda c: (c.effective_cost_usd, -c.score, c.model_id),
+            )
         if backup is None:
             funded_providers = sorted({c.provider for c in candidates if c.funding != "unfunded"})
             warning = (
@@ -1452,6 +1480,33 @@ def _level_with(a: Candidate, b: Candidate, category: str) -> bool:
     return a.evidence_points >= b.evidence_points - TIE_BAND.get(category, DEFAULT_TIE_BAND)
 
 
+def _near_tied(
+    a: Candidate,
+    a_aa: float | None,
+    b: Candidate,
+    b_aa: float | None,
+    category: str,
+    aa_band: float,
+) -> bool:
+    """Whether the evidence cannot tell ``a`` from ``b``: each level with the
+    other in the category (:func:`_level_with`, both ways), and their AA
+    Indexes (``a_aa``, ``b_aa``) no more than ``aa_band`` apart where both are
+    measured. One-way levelness is not enough: every stronger model is level
+    with a weaker one."""
+    return (
+        _level_with(a, b, category)
+        and _level_with(b, a, category)
+        and (a_aa is None or b_aa is None or abs(a_aa - b_aa) <= aa_band)
+    )
+
+
+def _aa_band(bench: dict[str, Any], catalog: dict[str, Any]) -> float:
+    """The AA Index's noise band in its own points: DEFAULT_TIE_BAND on the
+    0–100 scale it is read on, mapped back onto the index's measured range."""
+    gscale = _evidence_scale(catalog, bench, FRONTIER_INDEX)
+    return 0.0 if gscale is None else DEFAULT_TIE_BAND * (gscale.hi - gscale.lo) / 100.0
+
+
 def _tie_break(p: FrontierPoint, category: str) -> tuple[float, float]:
     """Between points level in the category: the higher AA Index, then the
     cheaper. Speed work too: QUALITY is the ladder's top, and COST and
@@ -1680,8 +1735,9 @@ def ladder(
       adequate point above COST.
     - Each rung carries a BACKUP from another maker (:func:`_backup_for`):
       the cheapest point on the other makers' frontier that does the job as
-      well as the rung, else the nearest below it. ``backup_warning`` says why
-      a rung has none.
+      well as the rung, else the strongest substitute, giving way to a
+      cheaper one the evidence cannot tell from it. ``backup_warning`` says
+      why a rung has none.
 
     None when no pool model carries an AA Index (no frontier to read)."""
     cat = catalog if catalog is not None else _cost._load_catalog()
@@ -1826,8 +1882,7 @@ def ladder(
     cost_rung = settle(_below(cost_rung, balanced_rung, cat))
     # General capability is level within the same noise band, read on the
     # AA Index's own 0–100 scale (the planning evidence).
-    gscale = _evidence_scale(cat, bench, FRONTIER_INDEX)
-    aa_band = 0.0 if gscale is None else DEFAULT_TIE_BAND * (gscale.hi - gscale.lo) / 100.0
+    aa_band = _aa_band(bench, cat)
     rungs = {
         r.tier: replace(r, backup=_backup_for(r, settings, task, headroom, bench, cat, aa_band))
         for r in (cost_rung, balanced_rung, quality_rung)
@@ -1894,10 +1949,13 @@ def _backup_for(
     those already paid for ahead of per-token ones. A point matches the rung
     when it stands level with it in the task's category
     (:func:`_level_with`) and in general capability (an AA Index no more than
-    ``aa_band`` below). The backup is the cheapest match; with none, the
+    ``aa_band`` below). The reference is the cheapest match; with none, the
     substitute the QUALITY rule would pick (:func:`_top`: strongest in the
     category, a near tie going to the higher AA Index); with no adequate
-    point, the one that falls shortest of the bar. It runs at its
+    point, the one that falls shortest of the bar. The backup is the cheapest
+    of the points within the noise bands of the reference both ways
+    (:func:`_near_tied`): the evidence cannot tell them apart, so paying more
+    buys nothing it can show. It runs at its
     point's measured effort, else at the rung's posture's effort, on its own
     platform. None when the pool holds no other
     maker's model."""
@@ -1924,13 +1982,26 @@ def _backup_for(
             if _level_with(p.candidate, r.candidate, task.category)
             and (r.aa_index is None or aa(p) >= r.aa_index - aa_band)
         ]
-        chosen = (
+        ref = (
             min(matches, key=lambda p: (p.price_usd, -aa(p)))
             if matches
             else _top(near, task.category)
         )
     else:
-        chosen = max(front, key=_nearest)
+        ref = max(front, key=_nearest)
+    # Of the points the evidence cannot tell from the reference, the cheapest:
+    # a near-identical model at a quarter of the price is not passed over for
+    # a fraction of an AA point. A peer may fall short of the bar where the
+    # reference clears it, by less than the noise: a shortfall the evidence
+    # cannot show. A prepaid reference keeps a prepaid backup.
+    prepaid = ref.candidate.scarcity < 1.0
+    peers = [
+        p
+        for p in front
+        if (p.candidate.scarcity < 1.0 or not prepaid)
+        and _near_tied(p.candidate, p.aa_index, ref.candidate, ref.aa_index, task.category, aa_band)
+    ]
+    chosen = min(peers, key=lambda p: (p.price_usd, -p.candidate.score))
     c = chosen.candidate
     if c.evidence_level is not None:
         effort = c.evidence_level
@@ -1940,6 +2011,251 @@ def _backup_for(
     return Backup(chosen, effort, native_level(c.platform_id, c.model_id, effort, catalog=catalog))
 
 
+def _model_ref_id(ref: str, catalog: dict[str, Any]) -> str:
+    """The catalog id ``ref`` names, matched spelling-free as
+    recommend._model_key does ("Claude Opus 5.5", "Opus 5.5" and
+    "claude-opus-5-5" are one model); ``ref`` itself on a miss."""
+
+    def key(text: str) -> str:
+        words = re.split(r"[\s_.-]+", text.lower())
+        return " ".join(sorted(w for w in words if w and w != "claude"))
+
+    want = key(ref)
+    for m in catalog.get("models", []):
+        if isinstance(m, dict) and want in {key(str(m.get("id", ""))), key(str(m.get("name", "")))}:
+            return str(m.get("id", ""))
+    return ref
+
+
+@dataclass(frozen=True)
+class _Pick:
+    """A pick made outside the ladder (a roadmap step's Settings), with the
+    pool and scales it is read against (:func:`_pick`)."""
+
+    candidate: Candidate  # the model, on the platform the pool reaches it best
+    level: str  # the scorer's level it runs at
+    ranking: Ranking
+    base: Task
+    models: dict[str, dict[str, Any]]
+    bench: dict[str, Any]
+    composite: dict[str, Any]
+    scales: tuple[EvidenceScale | None, EvidenceScale | None]
+    catalog: dict[str, Any]
+
+    def at(self, c: Candidate, level: str | None) -> Candidate:
+        """``c`` read at ``level`` (None: its headline row; see :func:`_at_level`)."""
+        return _at_level(
+            c,
+            level,
+            self.models[c.model_id],
+            self.base,
+            self.composite,
+            self.scales,
+            self.ranking.lam,
+            self.ranking.k_points_per_decade,
+        )
+
+    def measured(self, model_id: str) -> bool:
+        return self.level in measured_levels(self.bench, model_id)
+
+
+def _pick(
+    task: Task,
+    user_context_text: str,
+    model: str,
+    effort: str,
+    unavailable_models: list[str] | None,
+    catalog: dict[str, Any] | None,
+    benchmarks: dict[str, Any] | None,
+) -> _Pick:
+    """``model`` (catalog id or name) run at ``effort`` (a scorer or native
+    level) for ``task``, over the pool /recommend ranks. ValueError when the
+    model is not one this user-context can reach."""
+    cat = catalog if catalog is not None else _cost._load_catalog()
+    bench = benchmarks if benchmarks is not None else _load_benchmarks()
+    model_id = _model_ref_id(model, cat)
+    base = Task(task.category, task.complexity, task.novel, "balanced")
+    ranking = rank(
+        base,
+        user_context_text,
+        unavailable_models=unavailable_models,
+        catalog=cat,
+        benchmarks=bench,
+        effort_aware=False,
+    )
+    picked = next((c for c in ranking.candidates if c.model_id == model_id), None)
+    models = {str(m.get("id", "")): m for m in cat.get("models", []) if isinstance(m, dict)}
+    if picked is None or model_id not in models:
+        raise ValueError(f"{model!r} is not a model this user-context can reach")
+    composite = with_composites(bench)
+    scales = (
+        _evidence_scale(cat, composite, CATEGORY_EVIDENCE[base.category]),
+        _evidence_scale(cat, composite, CATEGORY_EVIDENCE["planning"]),
+    )
+    return _Pick(
+        picked, _scorer_level(effort), ranking, base, models, bench, composite, scales, cat
+    )
+
+
+def backup_for_pick(
+    task: Task,
+    user_context_text: str,
+    model: str,
+    effort: str,
+    *,
+    unavailable_models: list[str] | None = None,
+    catalog: dict[str, Any] | None = None,
+    benchmarks: dict[str, Any] | None = None,
+) -> Backup | None:
+    """The backup for a pick made outside the ladder (a roadmap step's
+    Settings): ``model`` (catalog id or name) run at ``effort`` (a scorer or
+    native level), backed up by the rule a /recommend rung follows
+    (:func:`_backup_for`), over the same pool, so the two never disagree.
+    ``task.budget`` sets the posture an unmeasured backup's effort follows.
+    None when the pool holds no other maker's model. ValueError when the
+    model is not one this user-context can reach."""
+    p = _pick(task, user_context_text, model, effort, unavailable_models, catalog, benchmarks)
+    funded = [c for c in p.ranking.candidates if c.funding != "unfunded"]
+    pool = funded or p.ranking.candidates
+    headroom = consumption_headroom(user_context_text or "")
+    settings = effort_settings(
+        pool,
+        p.base,
+        headroom,
+        lam=p.ranking.lam,
+        k=p.ranking.k_points_per_decade,
+        catalog=p.catalog,
+        benchmarks=p.bench,
+    )
+    model_id = p.candidate.model_id
+    at = p.at(p.candidate, p.level if p.measured(model_id) else None)
+    point = FrontierPoint(
+        at, _evidence(p.bench, model_id, FRONTIER_INDEX, at.evidence_level), frontier_price(at)
+    )
+    tier = next(t for t, b in TIER_BUDGET.items() if b == task.budget)
+    return _backup_for(
+        Rung(tier, point, p.level),
+        settings,
+        task,
+        headroom,
+        p.bench,
+        p.catalog,
+        _aa_band(p.bench, p.catalog),
+    )
+
+
+def _series(model_id: str) -> frozenset[str]:
+    """A model id's name words, its version numbers and the vendor prefix
+    aside: `gpt-6-sol` and `gpt-6.1-sol` are one series, `gpt-6-sol` and
+    `gpt-6-luna` two. Mirrors update/rating_guard.py same_series."""
+    return frozenset(re.findall(r"[a-z]+", model_id.lower())) - {"claude"}
+
+
+def _version(model_id: str) -> tuple[int, ...]:
+    return tuple(int(n) for n in re.findall(r"\d+", model_id))
+
+
+@dataclass(frozen=True)
+class Successor:
+    """A newer version of a pick's model that runs in its place
+    (:func:`successor_for_pick`)."""
+
+    candidate: Candidate  # the newer model, read at the pick's effort
+    effort: str  # the scorer's level
+    native: str | None
+    replaces: str  # the pick's model name
+
+    @property
+    def level(self) -> str:
+        return self.native or self.effort
+
+
+def successor_for_pick(
+    task: Task,
+    user_context_text: str,
+    model: str,
+    effort: str,
+    *,
+    unavailable_models: list[str] | None = None,
+    catalog: dict[str, Any] | None = None,
+    benchmarks: dict[str, Any] | None = None,
+) -> Successor | None:
+    """The newer version of ``model`` a pick made outside the ladder should run
+    instead: the same maker's next release in the same series (GPT-6 Sol →
+    GPT-6.1 Sol), funded on the pick's platform, no dearer per token, and, run
+    at ``effort``, level with it in the task's category (:func:`_level_with`)
+    and at least as high on the AA Intelligence Index. The newest such version;
+    None when there is none. ValueError when ``model`` is not one this
+    user-context can reach.
+
+    The selector reads each model's letters at its top effort, and a step that
+    runs lower can reverse them: GPT-6 Sol letters S in coding and GPT-6.1 Sol
+    A on a 3-point SciCode gap at max, yet at medium 6.1 Sol leads it on
+    Terminal-Bench 4.0 by 29 points at the same price. The two are compared
+    at ``effort`` where AA has measured both there, else on their headline
+    rows, so neither is credited with a run the other is not."""
+    p = _pick(task, user_context_text, model, effort, unavailable_models, catalog, benchmarks)
+    old = p.candidate
+    series, version = _series(old.model_id), _version(old.model_id)
+    best: Successor | None = None
+    for c in p.ranking.candidates:
+        if (
+            c.platform_id != old.platform_id
+            or c.provider != old.provider
+            or _series(c.model_id) != series
+            or _version(c.model_id) <= version
+            or c.blended_price_usd > old.blended_price_usd
+        ):
+            continue
+        both = p.measured(old.model_id) and p.measured(c.model_id)
+        level = p.level if both else None
+        was, now = p.at(old, level), p.at(c, level)
+        aa_was = _evidence(p.bench, old.model_id, FRONTIER_INDEX, level)
+        aa_now = _evidence(p.bench, c.model_id, FRONTIER_INDEX, level)
+        if not _level_with(now, was, task.category):
+            continue
+        if aa_now is None or (aa_was is not None and aa_now < aa_was):
+            continue
+        if best is not None and (
+            _version(c.model_id),
+            -c.blended_price_usd,
+        ) <= (_version(best.candidate.model_id), -best.candidate.blended_price_usd):
+            continue
+        native = native_level(c.platform_id, c.model_id, p.level, catalog=p.catalog)
+        best = Successor(now, p.level, native, old.model_name)
+    return best
+
+
+# A platform's effort dial as a Settings table names it (docs/settings-display.md):
+# Intelligence on OpenAI's reasoning surfaces, Effort elsewhere; Cursor has none.
+_DIAL_NAMES: Final[dict[str, str | None]] = {
+    "codex-cli": "Intelligence",
+    "codex-api": "Intelligence",
+    "openai-api": "Intelligence",
+    "cursor": None,
+}
+_LEVEL_WORDS: Final[dict[str, str]] = {
+    "minimal": "Minimal",
+    "low": "Low",
+    "medium": "Medium",
+    "high": "High",
+    "xhigh": "XHigh",
+    "max": "Max",
+    "ultra": "Ultra",
+}
+
+
+def backup_cell(backup: Backup | Successor) -> str:
+    """``backup`` as a roadmap Settings table's Backup cell:
+    ``GPT-6.1 Sol — Codex · Intelligence XHigh``. A :class:`Successor` reads
+    the same way, as the model the step runs."""
+    c = backup.candidate
+    dial = _DIAL_NAMES.get(c.platform_id, "Effort")
+    level = _LEVEL_WORDS.get(normalize_level(backup.level), backup.level)
+    head = f"{c.model_name} — {c.platform_name}"
+    return head if dial is None else f"{head} · {dial} {level}"
+
+
 def _below(lower: Rung, upper: Rung, catalog: dict[str, Any]) -> Rung:
     """``lower`` run at least one effort level below ``upper`` when both name
     the same model on the same platform and that path costs something