roadmodel 0.2.96__tar.gz → 0.2.97__tar.gz

{roadmodel-0.2.96 → roadmodel-0.2.97}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.96
+Version: 0.2.97
 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

{roadmodel-0.2.96/roadmodel/data → roadmodel-0.2.97/docs/claude-commands}/roadmap-refresh.md

@@ -221,7 +221,15 @@ complexity, novel or not; its Model rationale names them), then:
   not exist: a Complete step's ladder is the record of what ran, an `In
   progress` step's is what an agent is running, and a written phase's
   records what wrote its roadmap, so those keep their layout. That is a
-  layout fix, not a new pick, and takes no `Settings updated` line. A
+  layout fix, not a new pick, and takes no `Settings updated` line. Then
+  run `roadmodel rerank <every roadmap file>` (roadmodel 0.2.97 on): it
+  gives each of those ladder tables the ranks this release computes, so a
+  change to how roadmodel ranks reaches every step not yet run. It reads
+  the classification from the ladder's note (`Ranked for …`), else from the
+  only classification whose ladder has the same Picks. It adds a `Settings
+  updated` line where a rank changed. It reports any ladder it cannot
+  place: classify that step from its Model rationale and re-run with
+  `--hint FILE:SECTION=category/complexity[/novel]`. A
   ladder written before roadmodel 0.2.93 has Model / Backup / Platform /
   Effort (/ AA Index) / Thinking rows and no Runner-up: on a step that has
   not shipped, or a phase not yet written, replace it with the ladder

{roadmodel-0.2.96/roadmodel/data → roadmodel-0.2.97/docs/claude-commands}/roadmap-step.md

@@ -115,7 +115,11 @@ the dials and make sure it is set.
   Price rows. Level is the bare level of that platform's own dial (`High`
   is Intelligence High on Codex, Effort High on Claude Code and
   Antigravity). The ✓ in a column's header marks the one its **Runs:**
-  line names. A 0.2.94 ladder is three lists instead (`- Pick:`,
+  line names. From roadmodel 0.2.97 the three ranks of a column come from
+  three makers (a tight pool is a maker's); where too few are funded, a
+  missing rank is the Pick one level lower, its Level marked ↓, and the
+  note line says which classification the ladder was ranked for. A 0.2.94
+  ladder is three lists instead (`- Pick:`,
   `- Runner-up:`, `- Backup:` under each column's bold heading), and a
   0.2.93 one a table with rows `1 · Pick`, `2 · Runner-up` and
   `3 · Backup`, each followed by Platform, Effort, Thinking and AA Index
@@ -129,7 +133,8 @@ the dials and make sure it is set.
   subscription that pays for that column's Pick's platform:
   - `headroom`: run that column's Pick.
   - `tight`: run the first of that column's Runner-up and Backup whose
-    pool reads `headroom`, else the Cost column's Pick.
+    pool reads `headroom` or that is marked ↓ (the Pick one level lower,
+    which uses less of the tight pool), else the Cost column's Pick.
   - `exhausted`: run the first of that column's Runner-up and Backup
     whose pool reads `headroom`, else its Backup.
 

{roadmodel-0.2.96/roadmodel/data → roadmodel-0.2.97/docs/templates}/phase-roadmap-template.md

@@ -774,11 +774,18 @@ that owns it.}}
      platform has the toggle, and every AA Index and Price
      already assumes it. A note line under the table explains
      ✓ and Price, and a `**Conversation:**` line closes the
-     ladder. The ranks follow the column's own rule, not the
-     AA Index: Cost ranks the cheapest first, so its AA Index
-     may rise down the column. The Backup reads `none` when
-     the Runner-up already holds the
-     only other maker's models. Every model is the latest
+     ladder. Each rank comes from its own maker (roadmodel
+     0.2.97 on), because a tight usage pool is a maker's: the
+     Runner-up is the column's recommendation with the Pick's
+     maker left out, and the Backup leaves out both makers
+     above it. Where the user-context funds too few makers, a
+     missing rank is the Pick's own model one level lower,
+     its Level marked ↓ (it uses less of a tight pool), and
+     `none` below the dial's lowest level. The note line
+     names the classification the ladder was ranked for. The
+     ranks follow the column's own rule, not the AA Index:
+     Cost ranks each maker's cheapest adequate option, so its
+     AA Index may rise down the column. Every model is the latest
      version of its series, never an older one (GPT-6 Sol
      where GPT-6.1 Sol runs, Opus 5 where Opus 5.5 does).
      Set the Conversation line to **Continue** only when the

{roadmodel-0.2.96 → roadmodel-0.2.97}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.96"
+version = "0.2.97"
 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.96/docs/templates → roadmodel-0.2.97/roadmodel/data}/phase-roadmap-template.md

@@ -774,11 +774,18 @@ that owns it.}}
      platform has the toggle, and every AA Index and Price
      already assumes it. A note line under the table explains
      ✓ and Price, and a `**Conversation:**` line closes the
-     ladder. The ranks follow the column's own rule, not the
-     AA Index: Cost ranks the cheapest first, so its AA Index
-     may rise down the column. The Backup reads `none` when
-     the Runner-up already holds the
-     only other maker's models. Every model is the latest
+     ladder. Each rank comes from its own maker (roadmodel
+     0.2.97 on), because a tight usage pool is a maker's: the
+     Runner-up is the column's recommendation with the Pick's
+     maker left out, and the Backup leaves out both makers
+     above it. Where the user-context funds too few makers, a
+     missing rank is the Pick's own model one level lower,
+     its Level marked ↓ (it uses less of a tight pool), and
+     `none` below the dial's lowest level. The note line
+     names the classification the ladder was ranked for. The
+     ranks follow the column's own rule, not the AA Index:
+     Cost ranks each maker's cheapest adequate option, so its
+     AA Index may rise down the column. Every model is the latest
      version of its series, never an older one (GPT-6 Sol
      where GPT-6.1 Sol runs, Opus 5 where Opus 5.5 does).
      Set the Conversation line to **Continue** only when the

{roadmodel-0.2.96/docs/claude-commands → roadmodel-0.2.97/roadmodel/data}/roadmap-refresh.md

@@ -221,7 +221,15 @@ complexity, novel or not; its Model rationale names them), then:
   not exist: a Complete step's ladder is the record of what ran, an `In
   progress` step's is what an agent is running, and a written phase's
   records what wrote its roadmap, so those keep their layout. That is a
-  layout fix, not a new pick, and takes no `Settings updated` line. A
+  layout fix, not a new pick, and takes no `Settings updated` line. Then
+  run `roadmodel rerank <every roadmap file>` (roadmodel 0.2.97 on): it
+  gives each of those ladder tables the ranks this release computes, so a
+  change to how roadmodel ranks reaches every step not yet run. It reads
+  the classification from the ladder's note (`Ranked for …`), else from the
+  only classification whose ladder has the same Picks. It adds a `Settings
+  updated` line where a rank changed. It reports any ladder it cannot
+  place: classify that step from its Model rationale and re-run with
+  `--hint FILE:SECTION=category/complexity[/novel]`. A
   ladder written before roadmodel 0.2.93 has Model / Backup / Platform /
   Effort (/ AA Index) / Thinking rows and no Runner-up: on a step that has
   not shipped, or a phase not yet written, replace it with the ladder

{roadmodel-0.2.96/docs/claude-commands → roadmodel-0.2.97/roadmodel/data}/roadmap-step.md

@@ -115,7 +115,11 @@ the dials and make sure it is set.
   Price rows. Level is the bare level of that platform's own dial (`High`
   is Intelligence High on Codex, Effort High on Claude Code and
   Antigravity). The ✓ in a column's header marks the one its **Runs:**
-  line names. A 0.2.94 ladder is three lists instead (`- Pick:`,
+  line names. From roadmodel 0.2.97 the three ranks of a column come from
+  three makers (a tight pool is a maker's); where too few are funded, a
+  missing rank is the Pick one level lower, its Level marked ↓, and the
+  note line says which classification the ladder was ranked for. A 0.2.94
+  ladder is three lists instead (`- Pick:`,
   `- Runner-up:`, `- Backup:` under each column's bold heading), and a
   0.2.93 one a table with rows `1 · Pick`, `2 · Runner-up` and
   `3 · Backup`, each followed by Platform, Effort, Thinking and AA Index
@@ -129,7 +133,8 @@ the dials and make sure it is set.
   subscription that pays for that column's Pick's platform:
   - `headroom`: run that column's Pick.
   - `tight`: run the first of that column's Runner-up and Backup whose
-    pool reads `headroom`, else the Cost column's Pick.
+    pool reads `headroom` or that is marked ↓ (the Pick one level lower,
+    which uses less of the tight pool), else the Cost column's Pick.
   - `exhausted`: run the first of that column's Runner-up and Backup
     whose pool reads `headroom`, else its Backup.
 

{roadmodel-0.2.96 → roadmodel-0.2.97}/src/roadmodel/__init__.py

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

{roadmodel-0.2.96 → roadmodel-0.2.97}/src/roadmodel/cli.py

@@ -730,6 +730,180 @@ def relayout_command(paths: tuple[Path, ...], check: bool) -> None:
         raise SystemExit(1)
 
 
+@cli.command("rerank")
+@click.argument(
+    "paths",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    default=False,
+    help="Report the ladders without rewriting them; exit 1 if any would change.",
+)
+@click.option(
+    "--hint",
+    "hints",
+    multiple=True,
+    metavar="FILE:SECTION=CATEGORY/COMPLEXITY[/novel]",
+    help="Classification for a ladder whose note names none and whose Picks match "
+    "several (e.g. 'phase31.6-roadmap.md:Step 5=coding/high').",
+)
+@click.option(
+    "--user-context",
+    "user_context_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Path to user-context.md override.",
+)
+def rerank_command(
+    paths: tuple[Path, ...], check: bool, hints: tuple[str, ...], user_context_path: Path | None
+) -> None:
+    """Re-rank each roadmap's ladder tables by this release's rules.
+
+    For every ladder table under a step that has not started, or a phase whose
+    roadmap does not exist, prints the ladder this release ranks for the same
+    classification: the one its note names, else the one a --hint gives, else
+    the only one whose Picks match the table's. A ladder whose Runner-up or
+    Backup changes gains a `> Settings updated` line beneath it. Complete and
+    In progress steps, and written phases, keep their ladder; a ladder whose
+    classification stays unclear is reported and left as it is.
+    """
+    import datetime as _dt
+    from collections import Counter
+
+    from roadmodel import ladder_layout
+
+    text_ctx = _scoring_user_context(user_context_path)
+    budget = scoring.declared_budget(text_ctx).lower()
+    cache: dict[tuple[tuple[str, str, bool], bool], dict[str, Any] | None] = {}
+
+    def ladder_for(key: tuple[str, str, bool], phase: bool) -> dict[str, Any] | None:
+        if (key, phase) not in cache:
+            task = scoring.Task(key[0], key[1], key[2], budget)
+            cache[(key, phase)] = scoring.settings_ladder(task, text_ctx, phase=phase)
+        return cache[(key, phase)]
+
+    def picks(got: dict[str, Any]) -> tuple[tuple[str, str], ...]:
+        return tuple(
+            (str(got["columns"][t]["model"]), str(got["columns"][t]["level_cell"]))
+            for t in scoring.LADDER_TIERS
+        )
+
+    def ranks(got: dict[str, Any]) -> tuple[tuple[str, ...], ...]:
+        cols = [got["columns"][t] for t in scoring.LADDER_TIERS]
+        return tuple(
+            tuple("none" if o is None else str(o["model"]) for o in opts)
+            for opts in (cols, [c["runner_up"] for c in cols], [c["backup"] for c in cols])
+        )
+
+    hinted: dict[tuple[str, str], tuple[str, str, bool]] = {}
+    for hint in hints:
+        where, _, what = hint.partition("=")
+        name, _, section = where.partition(":")
+        parts = what.strip().lower().split("/")
+        if len(parts) not in (2, 3) or not name or not section:
+            raise click.ClickException(f"--hint {hint!r}: use FILE:SECTION=CATEGORY/COMPLEXITY")
+        hinted[(name.strip(), section.strip())] = (parts[0], parts[1], parts[2:] == ["novel"])
+    keys = scoring.table_keys()
+    today = _dt.date.today().isoformat()
+    pending = 0
+    unresolved: list[str] = []
+    for path in paths:
+        text = path.read_text(encoding="utf-8")
+        lines = text.split("\n")
+        counts: Counter[str] = Counter()
+        replacements: dict[int, tuple[int, str]] = {}
+        for block in ladder_layout.table_ladders(text, phase_written=_phase_written(path.parent)):
+            if block.done:
+                counts["kept"] += 1
+                continue
+            key = block.ranked_for or hinted.get((path.name, block.section))
+            if key is None:
+                matches = [
+                    k for k in keys if (g := ladder_for(k, block.phase)) and picks(g) == block.picks
+                ]
+                tables = {
+                    str((ladder_for(k, block.phase) or {})["markdown"]).split("\n\n")[0]
+                    for k in matches
+                }
+                if len(tables) != 1:
+                    counts["unresolved"] += 1
+                    found = ", ".join(
+                        "/".join(map(str, k[:2])) + ("/novel" if k[2] else "") for k in matches
+                    )
+                    unresolved.append(
+                        f"{path}: {block.section or 'ladder'} — "
+                        + (
+                            f"Picks match {found}"
+                            if matches
+                            else "no classification reproduces its Picks"
+                        )
+                    )
+                    continue
+                key = matches[0]
+                guessed = len(matches) > 1
+            else:
+                guessed = False
+            got = ladder_for(key, block.phase)
+            if got is None:
+                counts["unresolved"] += 1
+                unresolved.append(f"{path}: {block.section or 'ladder'} — no ladder for {key}")
+                continue
+            md = str(got["markdown"])
+            if guessed:
+                # Several classifications rank this ladder alike: the table is
+                # right, but naming one of them in the note would be a guess.
+                md = _drop_ranked_for(md)
+            if block.conversation and block.conversation != "New":
+                md = md.replace(
+                    "**Conversation:** New", f"**Conversation:** {block.conversation}", 1
+                )
+            if md == "\n".join(lines[block.start : block.end]):
+                counts["unchanged"] += 1
+                continue
+            if picks(got) != block.picks:
+                runs = scoring.LADDER_TIERS.index(str(got["runs"]))
+                was = " · ".join(block.picks[runs]) if len(block.picks) > runs else "—"
+                md += (
+                    f"\n\n> Settings updated {today} (rerank): was {was}. Re-ranked for "
+                    f"{key[0]}, {key[1]} complexity, each column's ranks from three makers."
+                )
+            elif ranks(got) != block.ranks:
+                md += (
+                    f"\n\n> Settings updated {today} (rerank): each column's Runner-up and "
+                    "Backup now come from makers other than its Pick; every Pick is unchanged."
+                )
+            replacements[block.start] = (block.end, md)
+            counts["reranked"] += 1
+        if replacements and not check:
+            path.write_text(ladder_layout.replace_ladders(text, replacements), encoding="utf-8")
+        pending += len(replacements)
+        if counts:
+            click.echo(
+                f"{path}: {counts['reranked']} re-ranked, {counts['unchanged']} unchanged, "
+                f"{counts['kept']} kept, {counts['unresolved']} unresolved"
+            )
+    for line in unresolved:
+        click.echo(f"  unresolved {line}; pass --hint or run /roadmap-refresh")
+    if check and pending:
+        raise SystemExit(1)
+
+
+def _drop_ranked_for(markdown: str) -> str:
+    """``markdown`` with its note's "Ranked for …" sentence removed and the
+    note re-wrapped at 80 columns."""
+    parts = markdown.split("\n\n")
+    for i, part in enumerate(parts):
+        flat = " ".join(part.split())
+        if flat.startswith("Ranked for "):
+            rest = re.sub(r"^Ranked for [^.]*\.\s*", "", flat)
+            parts[i] = textwrap.fill(rest, width=80, break_long_words=False)
+    return "\n\n".join(p for p in parts if p)
+
+
 def _phase_written(directory: Path) -> Callable[[str], bool]:
     """Whether a phase's roadmap exists beside the project roadmap:
     ``phase<id>-roadmap.md`` or ``phase<id>-<slug>-roadmap.md``, the id as the

{roadmodel-0.2.96 → roadmodel-0.2.97}/src/roadmodel/ladder_layout.py

@@ -42,6 +42,7 @@ RANKS: Final[tuple[tuple[str, str], ...]] = (
 FIELDS: Final[tuple[str, ...]] = ("Model", "Platform", "Level", "AA", "Price")
 INDENT: Final[str] = " " * 4
 RUNS_MARK: Final[str] = "✓"
+STEP_MARK: Final[str] = "↓"
 WIDTH: Final[int] = 80
 NONE: Final[str] = "—"
 _SEP: Final[str] = " · "
@@ -81,6 +82,9 @@ class Option:
     price: float | None = None
     # False when the level's token use is a typical model's, not measured.
     price_measured: bool = True
+    # The Pick's own model a level or two lower, filling a rank no other
+    # maker could (marked ↓).
+    stepped_down: bool = False
 
 
 def level_key(word: str) -> str | None:
@@ -100,7 +104,7 @@ def _cells(option: Option | None) -> list[str]:
     return [
         f"**{option.model}**",
         option.platform,
-        option.level,
+        option.level + (f" {STEP_MARK}" if option.stepped_down else ""),
         NONE if option.aa is None else option.aa,
         price_cell(option),
     ]
@@ -120,6 +124,7 @@ def ladder_markdown(
     *,
     runs: str | None,
     conversation: str | None,
+    ranked_for: str | None = None,
 ) -> str:
     """The ladder's table, its note, then its Conversation line. A rank is
     printed when any column carries it (a ladder older than the Runner-up has
@@ -128,7 +133,7 @@ def ladder_markdown(
     column reads `none` alone)."""
     head = ["", *(t.capitalize() + (f" {RUNS_MARK}" if t == runs else "") for t in TIERS)]
     rows = [head]
-    priced = unmeasured = False
+    priced = unmeasured = stepped = False
     for label, key in RANKS:
         if not any(key in columns[t] for t in TIERS):
             continue
@@ -144,7 +149,15 @@ def ladder_markdown(
         unmeasured |= any(
             o is not None and o.price is not None and not o.price_measured for o in opts
         )
-    notes = [f"{RUNS_MARK} runs by default."] if runs else []
+        stepped |= any(o is not None and o.stepped_down for o in opts)
+    notes = [f"Ranked for {ranked_for}."] if ranked_for else []
+    if runs:
+        notes.append(f"{RUNS_MARK} runs by default.")
+    if stepped:
+        notes.append(
+            f"{STEP_MARK} the Pick one level lower: no other maker is funded, and a "
+            "lower level uses less of a tight pool."
+        )
     if priced:
         notes.append(
             "Price: list $ per 1M tokens (3 in : 1 out) × the tokens the model "
@@ -420,3 +433,143 @@ def relayout(
         converted += 1
         i = end
     return "\n".join(out), converted, kept
+
+
+# --------------------------------------------------------------------------- #
+# Re-ranking the tables this release writes
+# --------------------------------------------------------------------------- #
+
+_TABLE_RE: Final = re.compile(r"^\|\s*\|\s*Cost\b")
+_RANKED_FOR_RE: Final = re.compile(
+    r"Ranked for ([a-z-]+), (low|medium|high) complexity(, novel)?\."
+)
+_SECTION_RE: Final = re.compile(r"^(?:## (Step \S+)|### (Phase [0-9A-Za-z.]+)|### (\S+))")
+
+
+@dataclass(frozen=True)
+class TableLadder:
+    """A ladder table (0.2.95 on) in a roadmap, with the lines it spans: the
+    table, its note, its Conversation line and its Runs paragraph."""
+
+    start: int
+    end: int
+    section: str
+    phase: bool
+    done: bool
+    picks: tuple[tuple[str, str], ...]
+    ranks: tuple[tuple[str, ...], ...]
+    ranked_for: tuple[str, str, bool] | None
+    conversation: str | None
+
+
+def _skip_blank(lines: list[str], i: int) -> int:
+    while i < len(lines) and not lines[i].strip():
+        i += 1
+    return i
+
+
+def _block_end(lines: list[str], i: int) -> int:
+    """The index past a ladder's note paragraph, Conversation line and Runs
+    paragraph (each optional, in that order), from just past its table."""
+    k = _skip_blank(lines, i)
+    if k < len(lines) and lines[k].startswith(
+        ("Ranked for ", f"{RUNS_MARK} ", "Price: ", f"{STEP_MARK} ")
+    ):
+        while k < len(lines) and lines[k].strip():
+            k += 1
+        i = k
+    k = _skip_blank(lines, i)
+    if k < len(lines) and lines[k].startswith("**Conversation:**"):
+        i = k + 1
+    k = _skip_blank(lines, i)
+    if k < len(lines) and lines[k].startswith("**Runs:**"):
+        while k < len(lines) and lines[k].strip():
+            k += 1
+        i = k
+    return i
+
+
+def table_ladders(
+    text: str, *, phase_written: Callable[[str], bool] | None = None
+) -> list[TableLadder]:
+    """Every ladder table in ``text``, each with its section (`Step 5`,
+    `Phase 32`), whether it sits under a phase heading, whether its step or
+    phase is done (Complete, In progress, or a written phase), its Picks and
+    every rank's models, the classification its note names, and its
+    Conversation value."""
+    lines = text.split("\n")
+    out: list[TableLadder] = []
+    section, phase, done = "", False, False
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if m := _SECTION_RE.match(line):
+            section = m.group(1) or m.group(2) or m.group(3)
+            phase = m.group(2) is not None
+            done = "✅" in line or bool(
+                phase and phase_written and phase_written(section.split(" ", 1)[1])
+            )
+        elif re.match(r"^#{1,2} ", line):
+            section, phase, done = "", False, False
+        elif status := _STATUS_RE.match(line):
+            done = done or status.group(1).startswith(("Complete", "In progress"))
+        elif line.startswith("**Phase roadmap settings**"):
+            # The session that writes a phase roadmap, under any heading
+            # (pyfinlab's `### F1 —` workstreams): a phase ladder.
+            phase = True
+        if not (_TABLE_RE.match(line) and i + 1 < len(lines) and _RULE_RE.match(lines[i + 1])):
+            i += 1
+            continue
+        j = i + 2
+        cells: dict[str, dict[str, list[str]]] = {}
+        rank = ""
+        while j < len(lines) and lines[j].startswith("|"):
+            label, *values = _table_cells(lines[j])
+            name = label.replace("&nbsp;", "").strip()
+            if name.startswith("**"):
+                rank = name.strip("*")
+                cells[rank] = {}
+            elif rank:
+                cells[rank][name] = [v.strip("*").replace(f" {STEP_MARK}", "") for v in values]
+            j += 1
+        end = _block_end(lines, j)
+        block = "\n".join(lines[j:end])
+        found = _RANKED_FOR_RE.search(" ".join(block.split()))
+        conv = next((m.group(1) for ln in lines[j:end] if (m := _CONVERSATION_RE.match(ln))), None)
+        pick = cells.get("Pick", {})
+        picks = tuple(zip(pick.get("Model", []), pick.get("Level", []), strict=False))
+        ranks = tuple(tuple(cells[r].get("Model", [])) for r in cells)
+        out.append(
+            TableLadder(
+                start=i,
+                end=end,
+                section=section,
+                phase=phase,
+                done=done,
+                picks=picks,
+                ranks=ranks,
+                ranked_for=(
+                    (found.group(1), found.group(2), bool(found.group(3))) if found else None
+                ),
+                conversation=conv,
+            )
+        )
+        i = end
+    return out
+
+
+def replace_ladders(text: str, replacements: Mapping[int, tuple[int, str]]) -> str:
+    """``text`` with each ladder starting at line ``start`` (a key) replaced,
+    through its ``end`` line, by the given Markdown."""
+    lines = text.split("\n")
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if i in replacements:
+            end, md = replacements[i]
+            out.extend(md.split("\n"))
+            i = end
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out)

{roadmodel-0.2.96 → roadmodel-0.2.97}/src/roadmodel/scoring.py

@@ -1981,7 +1981,7 @@ def _backup_for(
 ) -> Backup | None:
     """The rung's backup: the substitute from another maker that does the job
     as well as the rung, for the least. ``avoid`` leaves out further
-    candidates (a Settings ladder's runner-up, :func:`_ranked_backup`).
+    candidates.
 
     Over the pool's models from a maker other than the rung model's, each at
     its measured efforts, draw the frontier and keep its adequate points,
@@ -2304,8 +2304,9 @@ RUN_COLUMN: Final[dict[str, str]] = {"cheap": "cost", "balanced": "balanced", "b
 # The rule a step's runner applies to the pools on the day (roadmap-step §3).
 RUN_RULE: Final[str] = (
     "If that column's usage pool reads `tight` or `exhausted`, run the first of its "
-    "Runner-up and Backup whose pool has headroom; with neither, a `tight` column runs "
-    "the Cost column and an `exhausted` one its Backup."
+    "Runner-up and Backup whose pool has headroom; on a `tight` pool an option marked ↓ "
+    "(the Pick one level lower) also runs. With none, a `tight` column runs the Cost "
+    "column and an `exhausted` one its Backup."
 )
 # Dial levels a roadmap never pins: Codex's `ultra` and Claude Code's
 # Ultracode add parallel agents one planning document does not need.
@@ -2387,10 +2388,17 @@ def ladder_price_by_name(
 
 
 def _option(
-    c: Candidate, level: str, bench: dict[str, Any], catalog: dict[str, Any]
+    c: Candidate,
+    level: str,
+    bench: dict[str, Any],
+    catalog: dict[str, Any],
+    *,
+    stepped_down: bool = False,
 ) -> dict[str, Any]:
     """One ranked option of a ladder column: ``c`` run at ``level``, with its
-    dial and level, its Thinking toggle, its AA Index and its price there."""
+    dial and level, its Thinking toggle, its AA Index and its price there;
+    ``stepped_down`` when it is the Pick one or two levels lower, filling a
+    rank no other maker could."""
     dial = _DIAL_NAMES.get(c.platform_id, "Effort")
     price = ladder_price(c.model_id, level, catalog)
     return {
@@ -2412,6 +2420,7 @@ def _option(
         "price_usd_per_1m": None if price is None else price[0],
         "price_measured": None if price is None else price[1],
         "thinking_cell": _thinking_cell(c, catalog),
+        "stepped_down": stepped_down,
     }
 
 
@@ -2426,57 +2435,22 @@ def _layout_option(o: dict[str, Any] | None) -> _layout.Option | None:
         aa=_aa_cell(o["aa_index"]),
         price=o["price_usd_per_1m"],
         price_measured=bool(o["price_measured"]),
+        stepped_down=bool(o.get("stepped_down")),
     )
 
 
-def _series_ids(model_id: str, catalog: dict[str, Any]) -> list[str]:
-    """``model_id`` and every catalog model in its series
-    (:mod:`roadmodel.series`): GPT-6 Sol beside GPT-6.1 Sol."""
-    own = _series.series(model_id)
-    ids = (str(m.get("id", "")) for m in catalog.get("models", []) if isinstance(m, dict))
-    return [model_id, *(i for i in ids if own and i != model_id and _series.series(i) == own)]
-
-
-def _ranked_backup(
-    rung: Rung,
-    second: Rung | None,
-    pool: list[Candidate],
-    task: Task,
-    headroom: str,
-    bench: dict[str, Any],
-    catalog: dict[str, Any],
-    aa_band: float,
-) -> Backup | None:
-    """A Settings column's Backup, ranked under its pick and runner-up
-    (``second``): the pick's backup (:func:`_backup_for`, another maker's)
-    that is not the runner-up's series, from a maker neither row above uses
-    where one meets the task's bar, so the three rows span as many makers as
-    the pool holds. A runner-up from the pick's own maker leaves the pick's
-    backup as it is. None when the runner-up holds the only other maker's
-    series: it already stands in for an outage or an exhausted pool."""
-    if second is None or second.candidate.provider == rung.candidate.provider:
-        return rung.backup
-    taken = second.candidate
-    own = frozenset(_series_ids(taken.model_id, catalog))
-
-    def same_series(c: Candidate) -> bool:
-        return c.model_id in own
-
-    third = _backup_for(
-        rung,
-        pool,
-        task,
-        headroom,
-        bench,
-        catalog,
-        aa_band,
-        avoid=lambda c: c.provider == taken.provider or same_series(c),
-    )
-    if third is not None and third.candidate.requirement_penalty == 0:
-        return third
-    return (
-        _backup_for(rung, pool, task, headroom, bench, catalog, aa_band, avoid=same_series) or third
-    )
+def _step_down(c: Candidate, level: str, steps: int, catalog: dict[str, Any]) -> str | None:
+    """``level`` on ``c``'s own dial, ``steps`` rungs lower (High → Medium);
+    None below the dial's lowest rung, or on a surface with no dial."""
+    if c.platform_id in _DIAL_NAMES and _DIAL_NAMES[c.platform_id] is None:
+        return None
+    levels = native_levels(c.platform_id, c.model_id, catalog=catalog) or list(EFFORT_LADDER)
+    levels = [lv for lv in levels if normalize_level(lv) not in _NEVER_PINNED]
+    names = [normalize_level(lv) for lv in levels]
+    here = normalize_level(level)
+    if here not in names or names.index(here) < steps:
+        return None
+    return levels[names.index(here) - steps]
 
 
 def _deepest_level(c: Candidate, catalog: dict[str, Any]) -> str:
@@ -2503,21 +2477,27 @@ def settings_ladder(
     day instead of the roadmap being refreshed. ``phase`` is a phase-roadmap
     session: it runs Quality, at the deepest rung its dial allows.
 
-    Each column ranks three options, each with its effort and its AA
-    Intelligence Index there (:func:`ladder_aa_index`):
+    Each column ranks three options from three makers, each with its effort,
+    its AA Intelligence Index (:func:`ladder_aa_index`) and its price there.
+    A tight pool is a maker's (for this operator a maker is a subscription),
+    so a fallback from the Pick's own maker would draw on the pool that just
+    ran short (2026-10-25: Quality ranked Opus 5.5, then Fable 5.1):
 
     - Pick: the column's rung (:func:`ladder`).
-    - Runner-up: the column's rung with the pick's whole series off the
-      table, so it is never an older version of the pick (GPT-6 Sol under
-      GPT-6.1 Sol), from any maker.
-    - Backup: another maker's substitute for the pick, never the runner-up's
-      series (:func:`_ranked_backup`).
-
-    The ranks follow the column's own rule, not the AA Index: Cost ranks the
-    cheapest first, so its AA Index may rise down the column. Returns the
-    columns and the ladder's Markdown (:mod:`roadmodel.ladder_layout`: a
-    list per column, one option a line); None when no pool model carries an
-    AA Index."""
+    - Runner-up: the column's rung with every model of the Pick's maker off
+      the table.
+    - Backup: the column's rung with both makers above off the table.
+
+    Where the pool holds too few makers, a missing rank is the Pick's own
+    model one level lower on its dial (``stepped_down``; ↓ in the table),
+    which uses less of a tight pool; with one maker, the Runner-up and Backup
+    step down one and two levels. None below the dial's lowest level.
+
+    The ranks follow the column's own rule, not the AA Index: Cost ranks each
+    maker's cheapest adequate option, so its AA Index may rise down the
+    column. Returns the columns and the ladder table's Markdown
+    (:mod:`roadmodel.ladder_layout`); None when no pool model carries an AA
+    Index."""
     cat = catalog if catalog is not None else _cost._load_catalog()
     bench = benchmarks if benchmarks is not None else _load_benchmarks()
     off = list(unavailable_models or [])
@@ -2539,8 +2519,14 @@ def settings_ladder(
     lad = read([])
     if lad is None:
         return None
-    headroom = consumption_headroom(user_context_text or "")
-    aa_band = _aa_band(bench, cat)
+    # Every catalog model, by its maker: a rank leaves out the makers above
+    # it. The whole catalog, not the pool: with GPT-6.1 Sol off the table the
+    # pool takes GPT-6 Sol back, the same maker.
+    by_maker: dict[str, set[str]] = {}
+    for m in cat.get("models", []):
+        mid = str(m.get("id", ""))
+        maker = _cost.model_provider(mid, cat) or str(m.get("provider", "unknown"))
+        by_maker.setdefault(maker, set()).add(mid)
 
     def level_of(tier: str, r: Rung) -> str:
         return _deepest_level(r.candidate, cat) if phase and tier == "quality" else r.level
@@ -2548,20 +2534,27 @@ def settings_ladder(
     columns: dict[str, dict[str, Any]] = {}
     for tier in LADDER_TIERS:
         rung = lad.rungs[tier]
-        rest = read(_series_ids(rung.candidate.model_id, cat))
-        second = None if rest is None else rest.rungs[tier]
-        backup = _ranked_backup(rung, second, lad.settings, task, headroom, bench, cat, aa_band)
-        columns[tier] = {
-            **_option(rung.candidate, level_of(tier, rung), bench, cat),
-            "runner_up": (
+        pick_level = level_of(tier, rung)
+        pick = _option(rung.candidate, pick_level, bench, cat)
+        ranked: list[dict[str, Any] | None] = [pick]
+        makers = [rung.candidate.provider]
+        while len(ranked) < 3:
+            rest = read(sorted(m for maker in makers for m in by_maker.get(maker, ())))
+            nxt = None if rest is None else rest.rungs[tier]
+            if nxt is None or nxt.candidate.provider in makers:
+                break
+            ranked.append(_option(nxt.candidate, level_of(tier, nxt), bench, cat))
+            makers.append(nxt.candidate.provider)
+        steps = 1
+        while len(ranked) < 3:
+            lower = _step_down(rung.candidate, pick_level, steps, cat)
+            ranked.append(
                 None
-                if second is None
-                else _option(second.candidate, level_of(tier, second), bench, cat)
-            ),
-            "backup": (
-                None if backup is None else _option(backup.candidate, backup.level, bench, cat)
-            ),
-        }
+                if lower is None
+                else _option(rung.candidate, lower, bench, cat, stepped_down=True)
+            )
+            steps += 1
+        columns[tier] = {**pick, "runner_up": ranked[1], "backup": ranked[2]}
     runs = "quality" if phase else RUN_COLUMN.get(task.budget, "balanced")
     lists = _layout.ladder_markdown(
         {
@@ -2574,6 +2567,10 @@ def settings_ladder(
         },
         runs=runs,
         conversation="New",
+        ranked_for=(
+            f"{task.category}, {task.complexity} complexity"
+            + (", novel" if task.novel and task.complexity == "high" else "")
+        ),
     )
     why = (
         "a phase-roadmap session runs Quality (quality first)"