fix(stage-router): warn when capable-first cannot offload via scorer

[ting-hong-shieh]

What

Warn when a capable_first stage router uses a confidence threshold that prevents the scorer from selecting the efficient tier. For example, 0.5 exceeds the efficient confidence ceiling of approximately 0.462117.

The warning runs when StageClassifier is constructed, covering the runner and Python bindings without logging on each request. It computes the ceiling through the existing scorer and uses the picker's closed probability band, including the exact boundary. Routing behavior is unchanged: hard de-escalation and an optional LLM classifier can still select efficient.

The documentation explains this limit and scopes the 0.5 recommendation to efficient_first.

Why

Closes #264.

The current TOML schema requires an explicit threshold, but capable_first with 0.5 still silently disables scorer-driven offloading. This implements the issue's warning option without changing scoring weights or introducing new public APIs.

Notes for reviewers

Start with StageClassifier::new in crates/libsy/src/algorithms/util/stage.rs. One regression test checks warning output and picker behavior at 0.45, the exact ceiling, and 0.5, plus the hard de-escalation escape path.

Validation:

• cargo test --workspace: 757 passed, 1 ignored before the test-only mutex cleanup; cargo test -p switchyard-libsy: 289 passed after it.
• cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --all --check: passed.
• uv run ruff check .: passed; uv run pytest tests/: 116 passed, 2 skipped.
• Strict MkDocs build: passed.
• A temporary adversarial test checked 56,250 signal combinations against the efficient ceiling and 65 adjacent floating-point thresholds for agreement between the warning and picker. It passed and was removed from the final diff.

Validation used the project's Python 3.14 interpreter for PyO3 and allowed local ports for mock HTTP servers. No live model benchmark was run; 0.45 is documented as below the ceiling, not as a calibrated recommendation.

Summary by CodeRabbit

• New Features

  • Added warnings in capable_first mode when production scoring cannot reach the configured confidence threshold for efficient selection.
  • Preserved hard de-escalation behavior and classifier exceptions for ambiguous cases.

• Documentation

  • Clarified confidence threshold comparisons, routing behavior, scorer limits, warning conditions, and threshold calibration guidance.
  • Specified that the recommended 0.5 threshold applies to efficient_first.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3f434bda-6b1c-45a9-a61d-587daadfa062

📥 Commits

Reviewing files that changed from the base of the PR and between f27abd6 and dc2bfc7.

📒 Files selected for processing (2)

• crates/libsy/src/algorithms/util/stage.rs
• docs/routing_algorithms/stage_router_routing.md

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

Changes

Stage threshold behavior

Layer / File(s)	Summary
Constructor warning and validation crates/libsy/src/algorithms/util/stage.rs	StageClassifier::new warns when capable_first uses a threshold at or above the efficient scorer ceiling. Tests cover threshold boundaries, picker behavior, ambiguous results, and hard de-escalation.
Routing rule documentation docs/routing_algorithms/stage_router_routing.md	The documentation requires confidence to be strictly greater than the threshold and describes capable_first, its scorer ceiling, warning behavior, exceptions, and efficient_first calibration.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to dc2bf

The warning and documentation changes are ready to merge; no concrete regressions remain identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a warning when capable_first cannot offload through the scorer.
Linked Issues check	✅ Passed	Issue #264 requires users to see when capable_first cannot use scorer-driven efficient-tier selection at the confidence ceiling. StageClassifier::new now computes the ceiling through `score_signal…
Out of Scope Changes check	✅ Passed	The changes stay within Issue #264. The Rust changes add the requested configuration warning and focused automated tests. The documentation changes explain the threshold boundary, picker-specific beha…

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

---

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[ayushag-nv]

++ @sabhatinas for review