instar 0.28.113 → 0.28.115

package/upgrades/side-effects/phase-5-test-mode-routes.md

@@ -0,0 +1,201 @@
+# Side-Effects Review — Phase 5 test-mode HTTP routes
+
+**Cycle:** Phase 5 wiring step 1 — test-friendly endpoints + scenario validation
+**Spec:** `specs/provider-portability/11-cost-aware-routing.md` (approved 2026-05-15)
+**Reviewer status:** awaiting fresh second-pass.
+
+## Summary of the change
+
+Adds three HTTP endpoints to `src/server/routes.ts` that expose the
+already-shipped Phase 5 components through a test-friendly surface:
+
+- `GET /providers/routing/decide?...` — exercises
+  `CostAwareRoutingPolicy.decide()` against synthetic adapters. Accepts
+  `fakeRemainingUsd` / `fakeTotalUsd` / `fakeUnknown=1` to drive each row
+  of the six-row decision matrix without needing real adapters or a real
+  Anthropic UsageMeterProvider.
+- `GET /providers/cost-state/diff?...` — exercises
+  `CostStateTracker.isMaterialShift()` between two synthetic snapshots
+  shaped from the query params. Returns the shift reason or null.
+- `GET /providers/framework-router/route?taskPrompt=...&userId=...` —
+  exercises `FrameworkModelRouter.route()` with stub IntelligenceProvider
+  + in-memory PreferenceStore so the endpoint works on agents whose
+  better-sqlite3 native module isn't built for the running Node version
+  (e.g., deep-signal as of this session).
+
+Each endpoint constructs ephemeral Phase 5 instances per call. None of
+them mutate `Registry` or any persistent state; the in-memory
+PreferenceStore is per-request.
+
+The endpoints exist to be driven by the new test-driver-as-self pattern
+(`~/.instar/agents/echo/.claude/scripts/run-v1-scenarios.{sh,py}` +
+`.instar/scenarios/v1.0.0/`). They are the load-bearing piece for the
+autonomous-mode stop-condition standard Justin set tonight (scenarios
+must pass before autonomous can exit).
+
+## Files touched (in /instar-dev scope)
+
+- `src/server/routes.ts` — three new routes appended before the
+  `return router` block. ~190 added lines, no existing lines modified
+  beyond the anchor.
+
+## Decision-point inventory
+
+| Decision | Layer | Mode |
+|---|---|---|
+| Routing matrix row → adapter | Test-mode endpoint | signal-only (no production effect) |
+| Material shift detection | Test-mode endpoint | signal-only |
+| Framework + model pick | Test-mode endpoint | signal-only |
+
+All three endpoints are read-only from the caller's view. They construct
+ephemeral instances; no global state is mutated; no Telegram or external
+side effects fire.
+
+## 1. Over-block
+
+The endpoints don't block anything. They run on the existing auth-gated
+router and reject without bearer token, matching every other endpoint.
+
+## 2. Under-block
+
+Sensitive concerns to verify:
+
+- **The `fakeRemainingUsd` / `fakeTotalUsd` / `fakeUnknown` query
+  parameters bypass real UsageMeterProvider lookups.** This is
+  intentional and the only path through the endpoint — there is no
+  "production" mode where it queries the real meter. If callers want
+  real-state routing decisions, they need a different endpoint that
+  doesn't exist yet (tracked as Phase 5 follow-up).
+- **The in-memory PreferenceStore stub for the framework-router endpoint
+  means caller preferences don't persist across calls.** Acceptable for
+  test-mode; real persistence requires the production PreferenceStore
+  with a working better-sqlite3 build. Documented inline in the endpoint
+  comments.
+- **Endpoint is auth-gated** via the existing `authMiddleware`.
+
+## 3. Level-of-abstraction fit
+
+HTTP endpoints in `src/server/routes.ts` is the right layer:
+- Same pattern as every other test-friendly endpoint in the file
+  (e.g., `/internal/stop-gate/evaluate` is similarly synthetic-input).
+- Co-located with the auth middleware, no special routing needed.
+- The Phase 5 components are imported via dynamic `await import()` to
+  keep the route module's static import surface unchanged — no risk of
+  breaking other consumers of routes.ts via accidental side imports.
+
+## 4. Signal vs authority compliance
+
+- The endpoints are **signal-only**. Calling them does not register
+  adapters, set the routing policy, or mutate any persistent state.
+- The CostAwareRoutingPolicy, CostStateTracker, and FrameworkModelRouter
+  classes themselves carry the authority — these endpoints just expose
+  their decision functions to HTTP.
+- No new structural enforcement; no decision gates are removed or
+  weakened.
+
+## 5. Interactions
+
+- **Registry**: not touched. Adapters are not registered by these
+  endpoints. `setRoutingPolicy` is not called.
+- **Pre-existing routes**: not modified. The anchor (`return router`)
+  is unchanged in semantics; the new routes are appended before it.
+- **Test suite**: the existing unit tests for CostAwareRoutingPolicy /
+  CostStateTracker (23 tests) and the existing FrameworkModelRouter
+  tests continue to cover the underlying logic. The new endpoints don't
+  introduce coverage gaps in those classes.
+- **The PreferenceStore stub does NOT touch the real database** that
+  the `instar route` CLI uses. The CLI's behavior is unaffected.
+- **better-sqlite3 dependency** in the real PreferenceStore is sidestepped
+  via the in-memory stub. Agents with broken native modules can still
+  use the test-mode endpoint. Production routing via the `instar route`
+  CLI is unchanged — it still requires the working native build.
+
+## 6. External surfaces
+
+- Adds three new URL paths to the public HTTP surface. Documented in
+  `instar-dev` skill convention; no breaking changes to existing paths.
+- Auth-gated; no unauthenticated information disclosure.
+
+## 7. Rollback cost
+
+Revert one commit. The endpoints disappear; all existing functionality
+continues unchanged. The test driver in echo's home becomes a no-op
+against any agent without the deployed routes — gracefully reports
+"FAIL ... status 404" rather than corrupting anything.
+
+Total rollback: under 5 minutes. No data loss.
+
+## Conclusion
+
+This is a test-surface addition that exposes already-existing Phase 5
+logic through HTTP for the test-driver-as-self standard. No production
+behavior changes; no security surface widens beyond the existing
+auth-gated read endpoints.
+
+## Test evidence
+
+The driver at `~/.instar/agents/echo/.claude/scripts/run-v1-scenarios.{sh,py}`
+runs the catalog at `~/.instar/agents/echo/.instar/scenarios/v1.0.0/`
+against deep-signal. Results after deploying this commit's changes:
+
+```
+PASS 00-smoke-ping
+PASS 01-health-baseline
+PASS 02-capabilities-routing
+PASS 03-spec12-env-scrub-deployed
+PASS 04-route-decision-baseline
+PASS 05-route-decision-low-credit
+PASS 06-route-decision-unknown-credit
+PASS 07-route-decision-healthy-credit
+PASS 08-route-decision-non-anthropic-defers
+PASS 09-cost-state-shift-detection
+PASS 10-framework-router-anthropic-default
+
+── Summary ──
+  total:    11
+  pass:     11
+  fail:     0
+```
+
+All scenarios validate the endpoints end-to-end on a live agent —
+deep-signal in this case. Echo drove the test loop entirely (sent
+synthetic Telegram messages, polled deep-signal's responses, ran HTTP
+assertions on the new endpoints).
+
+## Second-pass review
+
+Independent reviewer (fresh subagent, no shared context) read the
+artifact, the implementation in `src/server/routes.ts`, the scenario
+catalog, and the spec. Verdict: **CONCUR**.
+
+Endpoints individually verified:
+- `/providers/routing/decide` — CORRECT. Constructs ephemeral
+  CostAwareRoutingPolicy per call, no global state mutation, auth-gated,
+  exercises every row of the spec's six-row decision matrix.
+- `/providers/cost-state/diff` — CORRECT. Pure-function call into
+  `isMaterialShift`, two synthetic snapshots, no `snapshot()` invocation.
+- `/providers/framework-router/route` — CORRECT WITH CAVEAT (resolved).
+  The stub PreferenceStore satisfies the get/set/clear surface
+  FrameworkModelRouter consumes (verified against source). Real
+  PreferenceStore SQLite path is never opened, so `instar route` CLI is
+  unaffected.
+
+Reviewer issues (all addressed below or filed as non-blocking
+follow-ups):
+
+1. **LOW (FIXED) — Unvalidated numeric coercion**. NaN from `Number("abc")`
+   would silently propagate to deferred-routing branches. Fixed in same
+   commit: both endpoints now reject with 400 on non-finite values.
+2. **INFO — PreferenceStore is a class, not an interface**. Future
+   additions to the router's store surface would break the stub silently.
+   Filed as follow-up: extract `PreferenceStoreLike` interface; not
+   blocking — current router only calls get/set/clear.
+3. **INFO — Dynamic await import() is correctly scoped**. Per-handler
+   imports don't pollute routes.ts static graph; Node's ESM cache means
+   no per-request state leakage.
+
+Production-path impact: ZERO. Registry untouched, no `setRoutingPolicy`,
+no PreferenceStore DB writes, no adapter registration. `instar route`
+CLI fully isolated from the test-mode endpoints.
+
+**Verdict: CONCUR.**

package/upgrades/side-effects/phase-5b1-preference-store-trigger-gate.md

@@ -0,0 +1,78 @@
+# Side-effects review — Phase 5b.1 (PreferenceStore + TriggerGate)
+
+**Version / slug:** `phase-5b1-preference-store-trigger-gate`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (pure storage + pure logic, complete branch coverage in unit tests)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md` (Phase 5b spec, locked + approved 2026-05-15)
+
+## Summary of the change
+
+First implementation slice of Phase 5b. Lands the two purely-deterministic components that the UX rides on:
+
+1. **`PreferenceStore`** (`src/providers/uxConfirm/PreferenceStore.ts`) — sqlite-backed cache keyed by `(userId, taskPattern)`. Stores the framework+model pick plus the state-at-confirm-time fields the TriggerGate needs (cost-state snapshot, catalog version, confidence). Provides `get`, `set`, `clear`, `clearAll`, `listPatterns`. Uses `better-sqlite3` per the existing instar storage pattern (StopGateDb, FeatureRegistry, UpdateChecker). Supports `:memory:` for tests.
+
+2. **`TriggerGate`** (`src/providers/uxConfirm/TriggerGate.ts`) — pure function `runTriggerGate(inputs)` that returns one of four discriminated outcomes: `silent-use`, `ask-new-pattern`, `ask-cost-shift`, `ask-low-confidence`. Priority order matches the spec: new-pattern > cost-shift > low-confidence > silent-use. Composes with `CostStateTracker.isMaterialShift` from Phase 5c.
+
+The other Phase 5b components (TaskClassifier, TelegramConfirmer, OverrideDetector, FrameworkModelRouter composition root) are deferred to subsequent slices.
+
+Files touched:
+- `src/providers/uxConfirm/PreferenceStore.ts` — new, 162 LOC.
+- `src/providers/uxConfirm/TriggerGate.ts` — new, 132 LOC.
+- `tests/unit/providers/uxConfirm/PreferenceStore.test.ts` — new, 11 cases.
+- `tests/unit/providers/uxConfirm/TriggerGate.test.ts` — new, 12 cases.
+
+## Decision-point inventory
+
+This change ADDS the central decision point of Phase 5b — the gate that decides whether to ask the user. The store is supporting infrastructure.
+
+- **`runTriggerGate(inputs) → outcome`** — `add`. Pure function. No blocking authority of its own; returns an outcome that the (not-yet-implemented) UX layer interprets. Per signal-vs-authority, the gate is the deterministic policy and the UX is the surface — they're correctly separated.
+- **`PreferenceStore.{get,set,clear,clearAll,listPatterns}`** — `add`. Storage primitives. No decision logic.
+
+The four-outcome shape (`silent-use | ask-new-pattern | ask-cost-shift | ask-low-confidence`) is the contract the UX consumes. It is exhaustive — every input produces exactly one outcome.
+
+## Signal vs authority
+
+- `runTriggerGate` is a stateless function. Inputs include cached preference, current cost-state snapshot, current catalog version, current confidence. Output is the outcome. No side effects, no blocking — purely a decision producer.
+- `PreferenceStore` is storage. It doesn't decide anything; it just persists what the user confirmed. Cache invalidation is the gate's job.
+- The split keeps the UX layer free of decision logic: it just renders the outcome.
+
+## Over-block / under-block analysis
+
+**Over-block (asking too often):**
+- A catalog version that bumps for cosmetic reasons (typo fix, doc shuffle) would trigger ask-low-confidence even when no fitness data changed. Mitigated by spec §"Open questions deferred to Phase 5c" — version bumps should only fire on meaningful catalog changes. Operationally, the catalog author decides.
+- A user with a flaky `readSdkCredit` could see false ask-cost-shift outcomes if the snapshot bounces around. Mitigated by Phase 5c's known→unknown transition detector — bouncing snapshots produce the same "state-became-unknown" reason and the user can ignore it.
+
+**Under-block (not asking when we should):**
+- A catalog edit that drops confidence without bumping the version string would NOT fire the gate. By convention (spec §"Acceptance criteria #4"), version bump is mandatory when confidence changes — but conventions aren't enforced. Future hardening: store a checksum of the catalog row, not just the version string. Deferred.
+- A user who confirmed during a billing period that then resets: the new snapshot will have totalUsd back to full, remainingUsd back to full. The tracker reports `sdk-credit-state-became-known` if reset went via null, or `recovered-above-safety-margin` if no null in between. Both are material shifts that fire the gate — so this is correctly handled.
+
+## Level-of-abstraction fit
+
+- The store and gate live in a new `src/providers/uxConfirm/` directory parallel to `src/providers/`. The naming signals that this is the consume-and-confirm UX surface — distinct from the routing math (`costAwareRouting.ts`) and the registry primitives.
+- `TriggerGate` imports `CostStateTracker` from Phase 5c. This is the documented integration point.
+- `PreferenceStore` imports nothing from `src/core/` except types — keeps the provider-portability subsystem self-contained.
+
+## Interactions
+
+- **Phase 5c (`CostStateTracker`)** — `TriggerGate` calls `isMaterialShift` to detect cost-shift triggers. Composes cleanly.
+- **Phase 5a (catalogs)** — `confidenceAtCache` uses the catalog's confidence label scheme (`HIGH | MEDIUM | LOW | PROVISIONAL`). When the Phase 5a artifacts evolve, the gate keeps working as long as those labels remain the canonical scheme.
+- **No existing source file is modified.** This commit is purely additive.
+
+## External surfaces
+
+- New exports: `PreferenceStore`, `FrameworkModelPreference`, `PreferenceStoreOptions`, `ConfidenceLevel`, `runTriggerGate`, `TriggerGateInputs`, `TriggerGateOutcome`.
+- New sqlite table when applied to a state directory: `framework_model_preferences` (created on first use via `CREATE TABLE IF NOT EXISTS`).
+- No new endpoint, no new CLI command, no new config field.
+
+## Rollback cost
+
+Trivial. `git revert` removes four files. The sqlite file (when one is created in production) becomes orphaned but does no harm — no runtime code consumes the schema yet in this commit (the composition root wiring happens later). Future rollbacks after wiring would also be safe since the schema is `CREATE IF NOT EXISTS`.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/` — 23/23 pass (11 store, 12 gate).
+- Gate test coverage: every priority path (new-pattern, cost-shift, low-confidence-dropped, low-confidence-LOW, low-confidence-PROVISIONAL, silent-use, version-bumped-but-confidence-unchanged) has at least one case plus three priority-ordering cases.
+- Store test coverage: get/set/clear/clearAll/listPatterns, per-user isolation, JSON roundtrip for `CostStateSnapshot`, null `agentSdkCredit` roundtrip, overwrite-on-duplicate.
+- No real-API verification needed — both classes are deterministic pure-logic / storage. Wiring into a live runtime is a later slice.

package/upgrades/side-effects/phase-5b2-task-classifier-override-detector.md

@@ -0,0 +1,83 @@
+# Side-effects review — Phase 5b.2 (TaskClassifier + OverrideDetector)
+
+**Version / slug:** `phase-5b2-task-classifier-override-detector`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (two narrow LLM-backed classifiers with strict parsers and fail-safe-to-no-override / fail-safe-to-unclassified-sentinel paths; full branch coverage)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md`
+
+## Summary of the change
+
+Second implementation slice of Phase 5b. Lands the two LLM-backed classifiers the UX needs:
+
+1. **`TaskClassifier`** (`src/providers/uxConfirm/TaskClassifier.ts`) — maps a task prompt to a stable kebab-case slug (the `taskPattern` cache key used by Phase 5b.1's PreferenceStore). Fast-tier IntelligenceProvider call with a curated one-shot prompt. Strict slug validator (lowercase-with-hyphens, 3–80 chars, no embedded sentinel). Errors and malformed output collapse to `UNCLASSIFIED_PATTERN` so the TriggerGate routes through `ask-new-pattern` (the safe outcome).
+
+2. **`OverrideDetector`** (`src/providers/uxConfirm/OverrideDetector.ts`) — passively inspects user messages for routing overrides ("use Gemini for this one", "always use Codex for refactors"). Fast-tier call with JSON output. Returns a discriminated union: `{ overrideRequested: false }` or `{ overrideRequested: true, framework?, model?, scope }`. Slugs are normalized against the caller's known-frameworks / known-models lists; out-of-list slugs are discarded rather than propagated downstream. Empty / whitespace messages return no-override without calling the LLM.
+
+The other Phase 5b components (TelegramConfirmer, FrameworkModelRouter composition root) remain to land in subsequent slices.
+
+Files touched:
+- `src/providers/uxConfirm/TaskClassifier.ts` — new, 164 LOC.
+- `src/providers/uxConfirm/OverrideDetector.ts` — new, 188 LOC.
+- `tests/unit/providers/uxConfirm/TaskClassifier.test.ts` — new, 13 cases.
+- `tests/unit/providers/uxConfirm/OverrideDetector.test.ts` — new, 20 cases (12 parsing + 8 phrasing variants per spec AC #6).
+
+## Decision-point inventory
+
+This change adds two signal producers — neither is a blocking authority.
+
+- **`TaskClassifier.classify`** — `add`. Returns a pattern slug. PreferenceStore (Phase 5b.1) keys cache rows by this slug; TriggerGate (Phase 5b.1) reads the cached row. The classifier doesn't decide anything itself.
+- **`OverrideDetector.detect`** — `add`. Returns a structured override request or no-override. The UX layer (not yet implemented) decides what to do with the result. The detector doesn't apply overrides itself.
+
+Both classifiers fail-safe in the same direction: when they can't produce confident output, they return the value that triggers the user being asked. False-negative (missed override) means the user gets the cached pick — they can override again. False-positive (spurious unclassified) means the UX asks — annoying but never wrong.
+
+## Signal vs authority
+
+Both classes are signal producers. Per the locked principle that brittle/low-context filters cannot have blocking authority:
+
+- The detection is LLM-backed (intelligent), not regex-backed, per the "intelligence over string matching" rule.
+- Even the LLM doesn't have blocking authority — the UX layer above interprets the structured result and decides whether to act on it.
+- All parsing failures collapse to the safe outcome (unclassified / no-override), never to a confident wrong answer.
+
+## Over-block / under-block analysis
+
+**TaskClassifier — over-classify (asking too often):**
+- The fallback path produces `unclassified` which Phase 5b.1's TriggerGate treats as `ask-new-pattern`. If the LLM has a flaky day, the user sees more confirmation prompts. Acceptable — a few extra prompts are a cheap price for not silently auto-using a wrong cache key.
+
+**TaskClassifier — under-classify (silent miss):**
+- Distinct-shape tasks colliding to the same slug means the user's "yes" to one carries to the other. Mitigation: the curated prompt examples bias toward 2-4 segment slugs that retain enough specificity ("code-refactor-typescript" not "code"). The classifier's max slug length (80 chars) leaves room for granularity when the LLM picks it.
+
+**OverrideDetector — false-positive (spurious override):**
+- Detecting an override when the user is just musing ("I wonder if Gemini would handle this better") would apply a routing change the user didn't intend. Mitigation: the JSON contract requires the model to set `override: true` explicitly, and the in-prompt examples include a "follow-up clarifications → false" rule. Production tuning may require additional negative examples.
+
+**OverrideDetector — false-negative (missed override):**
+- Missing a user's "use Gemini" means the cached pick runs. The user can re-issue the override or use `/route` explicitly. Same correction loop as TaskClassifier — not silently wrong, just slightly less convenient.
+
+## Level-of-abstraction fit
+
+- Both classifiers live in `src/providers/uxConfirm/` next to the gate and store they feed. No cross-cutting concerns.
+- `TaskClassifier` does NOT depend on the framework / model catalogs — it produces a slug that's independent of routing. This keeps Phase 5b survivable across catalog churn.
+- `OverrideDetector` takes the known-frameworks / known-models lists as constructor args. The application layer wires the current catalog state through. No baked-in catalog references.
+
+## Interactions
+
+- **Phase 5b.1 (`PreferenceStore`, `TriggerGate`)** — `TaskClassifier`'s output is `PreferenceStore`'s cache key; `TriggerGate` consumes the cached row to decide whether to invoke the UX flow.
+- **`IntelligenceProvider`** — both classifiers route through the existing fast-tier abstraction. No new credential surface, no new provider integration.
+- **No existing source file is modified.** Pure addition.
+
+## External surfaces
+
+- New exports: `TaskClassifier`, `TaskClassifierOptions`, `ClassifyInput`, `ClassifyResult`, `UNCLASSIFIED_PATTERN`; `OverrideDetector`, `OverrideDetectorOptions`, `OverrideDetectInput`, `OverrideDetectResult`, `OverrideScope`.
+- No new endpoint, no new CLI command, no new config field, no new LLM credential pathway.
+
+## Rollback cost
+
+Trivial. `git revert` removes four files. No persistent state, no runtime callsite consumes these yet — TelegramConfirmer is the next slice and will be the first consumer.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/` — 56/56 pass (11 + 12 from 5b.1; 13 classifier + 20 detector from this slice).
+- TaskClassifier branch coverage: ok path, leading-prefix strip, quotes strip, lowercase normalization, illegal chars → fallback, too-short → fallback, too-long → fallback, sentinel-echo → fallback, provider-throws → fallback, fast-tier opts, prompt embedding, tag append, truncation, custom template.
+- OverrideDetector branch coverage: empty bypass, JSON-false → no-override, throws → no-override, non-JSON → no-override, known-list normalization (framework + model), unknown-slug discard, all-null cheaper-one path, invalid-scope default, JSON-amid-prose extraction, fast-tier opts, truncation.
+- Spec AC #6 (8+ phrasing variants): all 8 cases pass with the production-prompt-shaped LLM responses.

package/upgrades/side-effects/phase-5b3-telegram-confirmer.md

@@ -0,0 +1,76 @@
+# Side-effects review — Phase 5b.3 (TelegramConfirmer)
+
+**Version / slug:** `phase-5b3-telegram-confirmer`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (the confirmer is a thin coordinator over a transport interface + the already-tested OverrideDetector; the shorthand parsers are deterministic and exhaustively tested; the only authority added is the user's reply itself)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md` §"Confirmation prompt shape" and §"Edge cases"
+
+## Summary of the change
+
+Third implementation slice of Phase 5b. Lands the blocking suggest-and-confirm round-trip — `TelegramConfirmer` in `src/providers/uxConfirm/TelegramConfirmer.ts`. The confirmer:
+
+1. Sends a structured prompt via a thin `ConfirmationTransport` abstraction (`send` + `awaitReply`).
+2. Blocks on the next reply on that topic for up to `timeoutMs` (default 5 minutes).
+3. Parses the reply through four deterministic shorthand checks (`ok|c|yes|y|go|👍` → confirm-cache, `one-shot|oneshot|once` → confirm-no-cache, `/route reset` → reset, `no|n` → decline), then falls through to the LLM-backed `OverrideDetector` (Phase 5b.2) for free-text.
+4. Returns a discriminated `ConfirmationResult`: `confirmed | overridden | reset | default-no-reply`.
+
+The `ConfirmationTransport` interface is intentionally thin so the confirmer is unit-testable without spinning up real Telegram. Production wiring composes a `TelegramAdapter` into a transport that delivers `send` to a topic and resolves `awaitReply` from the inbound message stream — that wiring is part of the composition root in the next slice.
+
+Files touched:
+- `src/providers/uxConfirm/TelegramConfirmer.ts` — new, 230 LOC.
+- `tests/unit/providers/uxConfirm/TelegramConfirmer.test.ts` — new, 30 cases.
+
+## Decision-point inventory
+
+This change adds the **user-facing confirmation surface** of Phase 5b. The user's reply IS the authority; the confirmer just decodes it.
+
+- **`TelegramConfirmer.confirm(prompt)`** — `add`. Drives the round-trip. Returns the user's structured decision.
+- **`TelegramConfirmer.parseReply(reply, prompt)`** — `add`. Pure-ish (the LLM call inside is async-pure given fixed reply). The shorthand checks are deterministic, brittle-by-design — they only activate on exact match.
+- **`formatConfirmationPrompt(prompt)`** — `add`. Pure rendering function.
+
+The four shorthand patterns are deliberately string-matching, which would normally violate the "intelligence over string matching" rule. But: they have no blocking authority — a missed shorthand falls through to the LLM-backed `OverrideDetector`. So the shorthand path is a fast-path optimization, not a decision authority. The signal-vs-authority constraint is satisfied: the LLM is always the safety net.
+
+## Signal vs authority
+
+- The shorthand parser is a fast-path; the LLM detector is the safety net.
+- The confirmer does NOT decide what to do with the result — it returns the discriminated outcome. The composition root above (next slice) decides whether to update the PreferenceStore, run the task with the new pick, or auto-default after a no-reply.
+
+## Over-block / under-block analysis
+
+**Over-block (treating ambiguous reply as an override):**
+- A user typing "yeah" gets classified as overridden-scope-this-task with no named pick (because "yeah" isn't in the confirm shorthand list). This propagates to the composition root which, per spec edge case §"Reply is unparseable", should re-ask once with the shorthand reminder. That re-ask logic lives in the composition root (next slice). The confirmer's job is just to surface the outcome.
+- A user replying with "okay sounds good" — the LLM detector sees no override request → confirmer returns overridden-no-named-pick. Same recovery path as above.
+
+Tunable: the shorthand list could be expanded (e.g., include "okay" / "sounds good"). Deferring until production produces real data — false-positive cost is one extra prompt; false-negative cost would be applying a wrong override.
+
+**Under-block (missing a real override):**
+- The LLM detector fail-safes to no-override on errors. Same conservative direction as the rest of Phase 5b.
+
+## Level-of-abstraction fit
+
+- The `ConfirmationTransport` interface is the thinnest possible abstraction over the Telegram-specific operations needed: send to topic, await reply with timeout. Adapter implementations live in the messaging layer; this layer doesn't reach into Telegram internals.
+- The confirmer doesn't depend on `TelegramAdapter` directly — only the transport interface. Same code drives a Slack confirmer, an iMessage confirmer, etc., when those land.
+
+## Interactions
+
+- **Phase 5b.2 (`OverrideDetector`)** — confirmer delegates free-text parsing to the detector.
+- **Phase 5b.1 (`PreferenceStore`)** — confirmer returns the outcome; the composition root above writes to the store. The confirmer does NOT write to the store directly (separation of concerns: decoding vs persisting).
+- **No existing source file is modified.** Pure addition.
+
+## External surfaces
+
+- New exports: `TelegramConfirmer`, `TelegramConfirmerOptions`, `ConfirmationTransport`, `ConfirmationPrompt`, `ConfirmationResult`, `ConfirmationReason`, `formatConfirmationPrompt`.
+- No new endpoint, no new CLI command, no new config field. The composition root next slice will introduce the wiring + new config field if any.
+- The shorthand reply contract (`ok|c|yes|y|go|👍|no|n|one-shot|oneshot|once|/route reset`) is now part of the user-facing surface. Future changes should be additive only.
+
+## Rollback cost
+
+Trivial. `git revert` removes two files. No persistent state, no runtime callsite consumes this yet — the composition root is the next slice.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/` — 86/86 pass (cumulative across five files: store 11, gate 12, classifier 13, detector 20, confirmer 30).
+- Confirmer test coverage: prompt-shape, reason-text variants, transport ordering (send-before-await), timeout → default-no-reply, custom timeoutMs, default timeoutMs, eight confirm shorthand variants, four one-shot shorthand variants, four reset shorthand variants, four decline shorthand variants, LLM-override (this-task + this-pattern), ambiguous-free-text fallback.
+- No real-API verification needed — confirmer composes pure stubs in tests. Live Telegram round-trip verification happens at integration time as part of the composition-root slice.

package/upgrades/side-effects/phase-5b4-framework-model-router.md

@@ -0,0 +1,88 @@
+# Side-effects review — Phase 5b.4 (FrameworkModelRouter composition root)
+
+**Version / slug:** `phase-5b4-framework-model-router`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (composition root over five already-tested components; every flow path covered by deterministic unit tests against in-memory store + stub catalog + stub confirmer)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md`
+
+## Summary of the change
+
+Fourth implementation slice of Phase 5b — the composition root that ties every previous slice together. `FrameworkModelRouter` lives in `src/providers/uxConfirm/FrameworkModelRouter.ts` and implements the full decision flow from §"Decision flow" of the spec.
+
+Routes a task by:
+
+1. Classifying via `TaskClassifier` → `taskPattern`.
+2. Short-circuiting on unclassified or non-Telegram-topic origin → catalog default with note source.
+3. Looking up cached preference in `PreferenceStore`.
+4. Capturing current cost state via `CostStateTracker.snapshot()`.
+5. Running `runTriggerGate` to decide silent-use or ask.
+6. On ask: calling `TelegramConfirmer.confirm(prompt)` with the right reason kind and detail.
+7. Applying the confirmation result — updating cache on `confirmed` (with cache) or `overridden` (this-pattern scope); clearing cache on `reset`; never caching on `confirmed-one-shot`, `overridden-this-task`, or any auto-default path.
+
+Returns a `RouteResult` with `{ framework, model, taskPattern, source, catalogDefault }`. The `source` field is the audit trail — eight distinct values cover every flow path so downstream code (and the dashboard's historical view) can show exactly why this pick was made.
+
+The `CatalogProvider` interface abstracts over Phase 5a's catalogs (`08-model-fitness-catalog.md`, `09-framework-fitness-catalog.md`). The router doesn't read markdown — a CatalogProvider implementation does, and the router consumes its three methods (`currentVersion`, `defaultFor`, `confidenceFor`).
+
+Files touched:
+- `src/providers/uxConfirm/FrameworkModelRouter.ts` — new, 248 LOC.
+- `tests/unit/providers/uxConfirm/FrameworkModelRouter.test.ts` — new, 13 cases covering all eight `source` outcomes plus confirmer-invocation arguments.
+
+## Decision-point inventory
+
+This change is the central Phase 5b decision authority. Every UX outcome flows through it.
+
+- **`FrameworkModelRouter.route(input)`** — `add`. The authority for "which framework+model runs this task." Returns a structured result; doesn't itself dispatch the task — that's a downstream concern.
+- **Cache-write decisions** — `add`. Implemented internally:
+  - `confirmed` + `cache: true` → write cache.
+  - `confirmed-one-shot` (`cache: false`) → do NOT write cache.
+  - `overridden-this-pattern` → write cache with overridden framework/model.
+  - `overridden-this-task` → do NOT write cache.
+  - `reset` → clear cache.
+  - All auto-default paths → no cache change.
+
+The eight-value `RouteSource` enum exhaustively covers every flow. TypeScript's discriminated-union checks ensure no case is dropped.
+
+## Signal vs authority
+
+The router IS the authority. It composes five signal producers (classifier, store, gate, confirmer, tracker) into a single decision. Each producer is fail-safe in its own direction (classifier→unclassified, gate→silent-use only when truly safe, confirmer→default-no-reply on timeout) so the router's worst-case behavior is "pick the catalog default with a noted source" — never wrong, occasionally over-cautious.
+
+## Over-block / under-block analysis
+
+**Over-block (silent auto-default when user wanted a prompt):**
+- Background work (no `telegramTopicId`) always auto-defaults, by design. This is locked behavior per Justin's Rule 1.
+- Unclassified pattern (classifier returned fallback) also auto-defaults rather than risking a wrong cache key. Spec §"Edge cases" mandates this.
+
+**Under-block (cache-write without user intent):**
+- The router writes cache only on explicit `confirmed:cache=true` or `overridden:scope=this-pattern`. Both come from the user's reply via the confirmer. No silent cache writes.
+- `auto-defaulted-no-reply` does NOT update the cache — important: a user who walks away during a confirmation should not have their state mutated.
+
+## Level-of-abstraction fit
+
+- The router doesn't reach into Telegram, sqlite, or LLM internals. It composes interfaces. The `CatalogProvider` abstraction means Phase 5a catalog changes don't ripple here.
+- All five injected components are constructor params — easy to test, easy to swap implementations (alternative messaging adapter, different catalog provider, alternative classifier model).
+
+## Interactions
+
+- **Phase 5b.1 (`PreferenceStore`, `TriggerGate`)** — direct dependencies. The router writes the store and reads via the gate.
+- **Phase 5b.2 (`TaskClassifier`, `OverrideDetector`)** — classifier is a direct dep; detector is consumed transitively via the confirmer.
+- **Phase 5b.3 (`TelegramConfirmer`)** — direct dep; confirmation is delegated.
+- **Phase 5c (`CostStateTracker`)** — direct dep; the gate consumes the tracker via the router's pass-through.
+- **Phase 5a artifacts (catalogs)** — consumed through `CatalogProvider`. The actual provider implementation that reads `08-model-fitness-catalog.md` and `09-framework-fitness-catalog.md` is NOT in this commit — that's part of the final wiring slice.
+- **No existing source file is modified.** Pure addition.
+
+## External surfaces
+
+- New exports: `FrameworkModelRouter`, `FrameworkModelRouterOptions`, `CatalogProvider`, `RouteInput`, `RouteResult`, `RouteSource`.
+- No new endpoint, no new CLI command, no new config field. Production wiring (server.ts composition root, real CatalogProvider implementation, wiring TelegramAdapter into ConfirmationTransport) lands in the final slice — `Phase 5b.5: wire into server startup`.
+
+## Rollback cost
+
+Trivial. `git revert` removes two files. No persistent state, no runtime callsite consumes the router yet.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/` — 99/99 pass cumulative (11 store + 12 gate + 13 classifier + 20 detector + 30 confirmer + 13 router).
+- Router test coverage: every `RouteSource` value is asserted by at least one test (cached-silent, confirmed, confirmed-one-shot, overridden-this-task, overridden-this-pattern, reset-defaulted, auto-defaulted-no-topic, auto-defaulted-no-reply, auto-defaulted-unclassified). Cache-write assertions verify each path's effect on the store. The confirmer-argument test asserts the right reason kind and prompt fields make it to the confirmer.
+- No real-API verification needed — composition root over already-tested components. Live integration (real Telegram, real LLM, real catalog) lands at the wiring slice.

package/upgrades/side-effects/phase-5b5a-static-catalog-provider.md

@@ -0,0 +1,80 @@
+# Side-effects review — Phase 5b.5.a (StaticCatalogProvider)
+
+**Version / slug:** `phase-5b5a-static-catalog-provider`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (hand-curated data tables with deterministic lookup; no decision logic, no LLM, no I/O)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md` (acceptance criteria #1 — implementable CatalogProvider)
+
+## Summary of the change
+
+First fragment of Phase 5b.5 (the production-wiring slice). Lands the concrete `CatalogProvider` implementation that the `FrameworkModelRouter` consumes — a hand-curated TypeScript module derived from the Phase 5a catalog markdown (`08-model-fitness-catalog.md`, `09-framework-fitness-catalog.md`).
+
+### Why hand-curated vs markdown parser
+
+The catalog markdown is the human source-of-truth — it contains 10x more data than the router needs (justifications, source citations, "avoid for" sections, etc.). A markdown parser would have two failure modes:
+
+1. **Over-fit current structure** → brittle. The catalog evolves as new research lands; new sections, reordered headings, and reworded bullets would each be a breaking change.
+2. **Under-extract** → lossy. Even a robust parser would mis-classify ambiguous confidence markers and miss task patterns not explicitly tabulated.
+
+A hand-curated runtime catalog forces a deliberate update when the markdown changes meaningfully — a feature, not a bug. The runtime catalog only needs: defaults per task pattern, confidence per (pattern, framework, model) tuple, a version string. All of which fit comfortably in static tables.
+
+### Contents
+
+- `CATALOG_VERSION = '2026-05-15.v0.1'` — date-stamped version that Phase 5b's TriggerGate compares against the cached snapshot.
+- `DEFAULTS_BY_PATTERN` — 20 curated task patterns mapped to `{ framework, model, confidence }`. Patterns chosen to cover the common task shapes the classifier emits (`code-generation`, `code-refactor-typescript`, `web-research`, `summarize-meeting-transcript`, `shell-one-liner`, `agentic-execution`, etc.).
+- `GLOBAL_DEFAULT` — Claude Code + Opus 4.7 @ LOW confidence — the safe fallback for unknown patterns.
+- `CONFIDENCE_BY_FRAMEWORK_MODEL` — per-tuple confidence baselines for non-default combinations (e.g., user overriding to Codex CLI for a refactor task).
+- `StaticCatalogProvider` class implementing the `CatalogProvider` interface.
+
+Files touched:
+- `src/providers/uxConfirm/StaticCatalogProvider.ts` — new, 180 LOC (mostly data tables + the lookup methods).
+- `tests/unit/providers/uxConfirm/StaticCatalogProvider.test.ts` — new, 16 cases.
+
+## Decision-point inventory
+
+This change ADDS a data source. It is itself a tiny decision point (which framework+model is the default for a pattern) but every "decision" is a static lookup — no LLM, no I/O, no async.
+
+- **`defaultFor(taskPattern)`** — `add`. Static table lookup with global fallback.
+- **`confidenceFor(taskPattern, framework, model)`** — `add`. Static table lookup with three-tier resolution: (1) match the documented default → cite its confidence; (2) match the framework|model baseline → cite that; (3) PROVISIONAL fallback.
+- **`currentVersion()`** — `add`. Constant getter (or constructor-overridable for tests).
+
+No new gates, sentinels, watchdogs, or filters. No blocking surface.
+
+## Signal vs authority
+
+This is pure data. The `FrameworkModelRouter` (Phase 5b.4) is the authority that consumes the data — not this provider.
+
+## Over-block / under-block analysis
+
+**Over-block:** Hand-curated tables can lag the markdown. If a new task pattern lands in the catalog markdown without being added here, the router routes it through `GLOBAL_DEFAULT` (Claude Code + Opus 4.7 LOW) — which fires `ask-new-pattern` on the gate side and gets re-confirmed by the user. Self-healing: the next time someone updates this file, they pick up the lag and the pattern auto-resolves to its proper default.
+
+**Under-block:** If a confidence rating in the markdown drops without being reflected here, the gate won't fire `ask-low-confidence` for that combination. Mitigation: when updating the markdown, bump `CATALOG_VERSION` AND update `CONFIDENCE_BY_FRAMEWORK_MODEL`. A future addition (Phase 5b.5.b or later) could add a build-time validator that diffs the markdown against the table.
+
+## Level-of-abstraction fit
+
+The provider lives in `src/providers/uxConfirm/` alongside the router that consumes it. It depends only on the `CatalogProvider` interface and the `ConfidenceLevel` type — no other provider-portability infrastructure. Clean isolation.
+
+## Interactions
+
+- **Phase 5b.4 (`FrameworkModelRouter`)** — direct consumer. Router constructed with `new StaticCatalogProvider()` in production wiring.
+- **Phase 5a catalog markdown** — source-of-truth that this file mirrors. Hand-maintained in lockstep.
+- **No existing source file is modified.** Pure addition.
+
+## External surfaces
+
+- New exports: `StaticCatalogProvider`, `StaticCatalogProviderOptions`, `CATALOG_VERSION`.
+- No new endpoint, no new CLI command, no new config field.
+- The `CATALOG_VERSION` string is part of Phase 5b's cache-invalidation contract — bumping it forces every cached preference to re-evaluate on next gate run. Bump deliberately.
+
+## Rollback cost
+
+Trivial. `git revert` removes two files. No persistent state.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/StaticCatalogProvider.test.ts` — 16/16 pass.
+- Cumulative uxConfirm coverage: 115 tests passing (99 prior + 16 new).
+- Test coverage: version default + override, six curated pattern defaults (code-generation, code-refactor-typescript, web-research, summarize-meeting-transcript, shell-one-liner, agentic-execution), global fallback for unknown patterns, default-pick confidence precision, non-default baseline lookup, translation-proxy combinations, unknown-tuple PROVISIONAL fallback, knownPatterns().
+- No real-API verification needed — purely deterministic.