roadmodel 0.2.82__tar.gz → 0.2.84__tar.gz

{roadmodel-0.2.82 → roadmodel-0.2.84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.82
+Version: 0.2.84
 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. |
 | `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.82 → roadmodel-0.2.84}/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. |
 | `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.82 → roadmodel-0.2.84}/docs/claude-commands/roadmap-refresh.md

@@ -180,7 +180,13 @@ 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
+  (`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. 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

{roadmodel-0.2.82 → roadmodel-0.2.84}/docs/templates/prompt-phase-roadmap.md

@@ -103,7 +103,13 @@ 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.
 
 Honor the template's style rules: 80-column prose, zero `{{...}}`
 tokens left, `**Status:** Not started` directly under the title and

{roadmodel-0.2.82 → roadmodel-0.2.84}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.82"
+version = "0.2.84"
 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.82 → roadmodel-0.2.84}/roadmodel/data/prompt-phase-roadmap.md

@@ -103,7 +103,13 @@ 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.
 
 Honor the template's style rules: 80-column prose, zero `{{...}}`
 tokens left, `**Status:** Not started` directly under the title and

{roadmodel-0.2.82 → roadmodel-0.2.84}/roadmodel/data/roadmap-refresh.md

@@ -180,7 +180,13 @@ 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
+  (`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. 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

{roadmodel-0.2.82 → roadmodel-0.2.84}/scripts/update_projects.py

@@ -49,6 +49,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional
+from urllib.parse import urlsplit
 from xml.sax.saxutils import escape
 
 COMMANDS = (
@@ -1975,7 +1976,8 @@ def _parse_time(value: str) -> tuple[int, int]:
 def launchd_plist(python: Path, script: Path, hour: int, minute: int, log: Path) -> str:
     # stdout goes nowhere: `--log` already writes the run to the log, and
     # launchd capturing stdout into the same file recorded every run twice.
-    # stderr stays captured, so a crash before the log opens still lands there.
+    # --log also captures stderr after its safe open. launchd must not pre-open
+    # a path outside that validation; failures before log setup are discarded.
     return f"""<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1994,7 +1996,7 @@ def launchd_plist(python: Path, script: Path, hour: int, minute: int, log: Path)
   <dict><key>Hour</key><integer>{hour}</integer><key>Minute</key><integer>{minute}</integer></dict>
   <key>RunAtLoad</key><false/>
   <key>StandardOutPath</key><string>/dev/null</string>
-  <key>StandardErrorPath</key><string>{escape(str(log))}</string>
+  <key>StandardErrorPath</key><string>/dev/null</string>
   <key>EnvironmentVariables</key>
   <dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
 </dict>
@@ -2248,7 +2250,90 @@ CONTEXT_SYNC_CONFIG = CONFIG_DIR / "context-sync.json"
 CONTEXT_CLONE = CONFIG_DIR / "context-repo"
 USER_CONTEXT = CONFIG_DIR / "user-context.md"
 CONTEXT_FILE = "user-context.md"
-_REPO_SLUG_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_REPO_SLUG_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9_][A-Za-z0-9_.-]{0,99}")
+
+
+def _context_repo(value: str) -> str:
+    """One GitHub repository identity, with no local paths or URL credentials."""
+    if not isinstance(value, str) or any(ord(c) < 33 or ord(c) == 127 for c in value):
+        raise ValueError("Unsupported context repository.")
+    candidate = value
+    if value.startswith("git@github.com:"):
+        candidate = value[len("git@github.com:") :]
+    elif "://" in value:
+        parsed = urlsplit(value)
+        if (
+            parsed.hostname != "github.com"
+            or parsed.port is not None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError("Unsupported context repository.")
+        if parsed.scheme == "https":
+            if parsed.username is not None or parsed.password is not None:
+                raise ValueError("Unsupported context repository.")
+        elif parsed.scheme == "ssh":
+            if parsed.username != "git" or parsed.password is not None:
+                raise ValueError("Unsupported context repository.")
+        else:
+            raise ValueError("Unsupported context repository.")
+        candidate = parsed.path.removeprefix("/")
+    if candidate.endswith(".git"):
+        candidate = candidate[:-4]
+    if not _REPO_SLUG_RE.fullmatch(candidate):
+        raise ValueError("Unsupported context repository.")
+    return candidate.lower()
+
+
+def _context_visibility(repo: str) -> bool:
+    """Require authenticated, exact-identity PRIVATE metadata before carrying bytes."""
+    try:
+        gh = shutil.which("gh")
+        if not gh:
+            return False
+        result = subprocess.run(  # noqa: S603 — fixed gh API, canonical repository
+            [gh, "api", "--hostname", "github.com", f"repos/{repo}"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return False
+        data = json.loads(result.stdout)
+        return (
+            isinstance(data, dict)
+            and data.get("private") is True
+            and data.get("visibility") == "private"
+            and isinstance(data.get("full_name"), str)
+            and data["full_name"].lower() == repo
+        )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return False
+
+
+def _context_destination(repo: str) -> Optional[str]:
+    """Validate effective Git URL rewrites, configured transports and current branch."""
+    for args in (
+        ("remote", "get-url", "--all", "origin"),
+        ("remote", "get-url", "--push", "--all", "origin"),
+    ):
+        result = _git(*args, cwd=CONTEXT_CLONE)
+        values = result.stdout.splitlines()
+        if result.returncode or len(values) != 1 or _context_repo(values[0]) != repo:
+            return None
+    result = _git("symbolic-ref", "--quiet", "--short", "HEAD", cwd=CONTEXT_CLONE)
+    branch = result.stdout.strip()
+    if result.returncode or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", branch):
+        return None
+    if _git("check-ref-format", "--branch", branch, cwd=CONTEXT_CLONE).returncode:
+        return None
+    for name in (f"branch.{branch}.remote", f"branch.{branch}.pushRemote", "remote.pushDefault"):
+        result = _git("config", "--get-all", name, cwd=CONTEXT_CLONE)
+        if result.returncode not in (0, 1) or any(
+            v != "origin" for v in result.stdout.splitlines()
+        ):
+            return None
+    return branch
 
 
 def _git(*args: str, cwd: Path) -> subprocess.CompletedProcess[str]:
@@ -2270,42 +2355,37 @@ def _read_context_config() -> Optional[dict[str, str]]:
 
 def configure_context_sync(repo: str, source: Optional[str], dry_run: bool = False) -> str:
     """Record this machine's role. `source` given → it publishes that file;
-    omitted → it pulls. `repo` is `owner/name` (or a git URL / path)."""
-    if not (_REPO_SLUG_RE.match(repo) or "://" in repo or repo.startswith(("git@", "/"))):
-        raise SystemExit(f"--context-sync: expected OWNER/REPO, got {repo!r}")
+    omitted → it pulls. `repo` identifies a GitHub repository."""
+    try:
+        repo = _context_repo(repo)
+    except ValueError:
+        raise SystemExit("--context-sync: expected a canonical GitHub repository.") from None
     cfg: dict[str, str] = {"repo": repo, "role": "replica"}
     if source:
         src = Path(source).expanduser().resolve()
         if not src.is_file():
-            raise SystemExit(f"--context-source: no such file {src}")
+            raise SystemExit("--context-source: source file is unavailable.")
         cfg.update(role="source", source=str(src))
     if not dry_run:
         _private_dir(CONFIG_DIR)
         _replace_bytes(CONTEXT_SYNC_CONFIG, (json.dumps(cfg, indent=2) + "\n").encode())
-    where = f"publishing {cfg['source']}" if source else f"pulling into {USER_CONTEXT}"
-    return f"this machine is the user-context {cfg['role'].upper()}, {where}, via {repo}"
+    return f"this machine is the user-context {cfg['role'].upper()}; privacy verification required at each sync"
 
 
 def _ensure_clone(repo: str) -> Optional[str]:
-    """None on success, else why it failed. A slug clones through `gh` (which
-    carries the operator's GitHub auth for a PRIVATE repo); a URL or path
-    clones with plain git."""
+    """Clone only the independently verified GitHub repository through gh."""
     if (CONTEXT_CLONE / ".git").is_dir():
         _private_dir(CONTEXT_CLONE)
         return None
     _private_dir(CONTEXT_CLONE.parent)
-    if _REPO_SLUG_RE.match(repo) and shutil.which("gh"):
-        cmd = ["gh", "repo", "clone", repo, str(CONTEXT_CLONE)]
-    else:
-        url = f"https://github.com/{repo}.git" if _REPO_SLUG_RE.match(repo) else repo
-        cmd = ["git", "clone", url, str(CONTEXT_CLONE)]
+    cmd = ["gh", "repo", "clone", repo, str(CONTEXT_CLONE)]
     done = subprocess.run(  # noqa: S603 — literal argv built above from a validated repo, no shell
         cmd, capture_output=True, text=True, timeout=180
     )
     if done.returncode == 0:
         _private_dir(CONTEXT_CLONE)
         return None
-    return _tail(done.stderr or done.stdout, 2)
+    return "clone failed"
 
 
 def _digest(data: bytes) -> str:
@@ -2318,33 +2398,49 @@ def sync_user_context(dry_run: bool = False) -> list[str]:
     """Publish (source) or pull (replica) the user-context. Silent when this
     machine was never configured, so an operator with one machine sees
     nothing new."""
+    try:
+        return _sync_user_context(dry_run)
+    except (OSError, ValueError, KeyError, subprocess.SubprocessError):
+        return ["user-context sync: SKIPPED (private destination could not be verified)"]
+
+
+def _sync_user_context(dry_run: bool) -> list[str]:
     cfg = _read_context_config()
     if cfg is None:
         return []
     if dry_run:
-        return [f"user-context sync: {cfg['role']} via {cfg['repo']} (dry run: nothing sent)"]
-    failed = _ensure_clone(cfg["repo"])
+        return ["user-context sync: dry run; privacy unverified, nothing sent"]
+    repo = _context_repo(cfg["repo"])
+    if not _context_visibility(repo):
+        return ["user-context sync: SKIPPED (private destination could not be verified)"]
+    if CONTEXT_CLONE.exists() and (
+        not (CONTEXT_CLONE / ".git").is_dir() or not _context_destination(repo)
+    ):
+        return ["user-context sync: SKIPPED (clone destination could not be verified)"]
+    failed = _ensure_clone(repo)
     if failed:
-        return [f"user-context sync: SKIPPED (clone of {cfg['repo']} failed: {failed})"]
+        return ["user-context sync: SKIPPED (clone failed)"]
+    branch = _context_destination(repo)
+    if branch is None:
+        return ["user-context sync: SKIPPED (clone destination could not be verified)"]
     has_history = _git("rev-parse", "--verify", "HEAD", cwd=CONTEXT_CLONE).returncode == 0
     if has_history:
-        pulled = _git("pull", "--ff-only", "--quiet", cwd=CONTEXT_CLONE)
+        pulled = _git("pull", "--ff-only", "--quiet", "origin", branch, cwd=CONTEXT_CLONE)
         if pulled.returncode != 0:
-            return [f"user-context sync: SKIPPED (pull failed: {_tail(pulled.stderr, 2)})"]
+            return ["user-context sync: SKIPPED (pull failed)"]
     carried = CONTEXT_CLONE / CONTEXT_FILE
 
     if cfg["role"] == "source":
         src = Path(cfg["source"])
         if not src.is_file():
-            return [f"user-context sync: SKIPPED (source {src} is missing)"]
+            return ["user-context sync: SKIPPED (source file is unavailable)"]
         out: list[str] = []
         # An edit to a separate copy at the default path would never publish.
         if USER_CONTEXT.exists() and not USER_CONTEXT.is_symlink():
             if USER_CONTEXT.read_bytes() != src.read_bytes():
                 out.append(
-                    f"user-context sync: WARNING {USER_CONTEXT} is a separate copy that "
-                    f"differs from the source; edits there are NOT published. Point it at "
-                    f"{src}."
+                    "user-context sync: WARNING default context differs from the source; "
+                    "edits to that separate copy are NOT published."
                 )
         data = src.read_bytes()
         if carried.exists() and carried.read_bytes() == data:
@@ -2354,14 +2450,21 @@ def sync_user_context(dry_run: bool = False) -> list[str]:
         steps = (
             ("add", CONTEXT_FILE),
             ("commit", "--quiet", "-m", f"sync user-context {_digest(data)}"),
-            ("push", "--quiet", "-u", "origin", "HEAD"),
+            ("push", "--quiet", "-u", "origin", f"HEAD:refs/heads/{branch}"),
         )
         for step in steps:
+            if step[0] == "push" and (
+                not _context_visibility(repo) or _context_destination(repo) != branch
+            ):
+                return [
+                    *out,
+                    "user-context sync: SKIPPED (private destination changed before push)",
+                ]
             done = _git(*step, cwd=CONTEXT_CLONE)
             if done.returncode != 0:
                 return [
                     *out,
-                    f"user-context sync: FAILED at git {step[0]}: {_tail(done.stderr, 2)}",
+                    f"user-context sync: FAILED at git {step[0]}",
                 ]
         return [*out, f"user-context sync: published ({_digest(data)})"]
 

{roadmodel-0.2.82 → roadmodel-0.2.84}/src/roadmodel/__init__.py

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

{roadmodel-0.2.82 → roadmodel-0.2.84}/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,82 @@ 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.
+    """
+    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)
+        backup = scoring.backup_for_pick(task, text, model, effort)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    cell = scoring.backup_cell(backup) if backup is not None else "None"
+    if output.lower() == "json":
+        payload: dict[str, Any] = {"backup": None, "cell": cell}
+        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
+    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.82 → roadmodel-0.2.84}/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,108 @@ 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
+
+
+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."""
+    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")
+    funded = [c for c in ranking.candidates if c.funding != "unfunded"]
+    pool = funded or ranking.candidates
+    headroom = consumption_headroom(user_context_text or "")
+    lam, k = ranking.lam, ranking.k_points_per_decade
+    settings = effort_settings(pool, base, headroom, lam=lam, k=k, catalog=cat, benchmarks=bench)
+    composite = with_composites(bench)
+    scales = (
+        _evidence_scale(cat, composite, CATEGORY_EVIDENCE[base.category]),
+        _evidence_scale(cat, composite, CATEGORY_EVIDENCE["planning"]),
+    )
+    level = _scorer_level(effort)
+    measured = level in measured_levels(bench, model_id)
+    at = _at_level(
+        picked, level if measured else None, models[model_id], base, composite, scales, lam, k
+    )
+    point = FrontierPoint(
+        at, _evidence(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, level), settings, task, headroom, bench, cat, _aa_band(bench, cat)
+    )
+
+
+# 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) -> str:
+    """``backup`` as a roadmap Settings table's Backup cell:
+    ``GPT-6.1 Sol — Codex · Intelligence XHigh``."""
+    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