instar 1.3.770 → 1.3.772

package/upgrades/nature-routing-a2.eli16.md

@@ -0,0 +1,50 @@
+# ELI16 — Nature-Axis Routing, Increment A2.1 (the dark/dryRun mechanism)
+
+## The one-sentence version
+
+We taught the internal LLM router how to pick *which model, on which access door* a
+background check should run on — based on the **kind** of thinking the check does — but
+we shipped it **turned off** everywhere except as a silent "here's what I *would* pick"
+observer on a development agent.
+
+## Why
+
+Different internal jobs need different brains. A quick "is this a STOP command?" sort is a
+different task than a careful "should this message be blocked?" judgment. The bench (INSTAR
+v3) measured which model+door combo is best for each kind — and found one combo that's
+actively *dangerous* for careful judgments: Opus running through the Claude Code CLI (the
+CLI wraps every prompt in ~20k tokens of "helpful assistant" framing, which makes a skeptical
+judge go soft — it missed real STOP commands 27% of the time). So routing has to be able to
+say "for a judgment call, NEVER land on that door."
+
+## What this increment actually adds (and what it deliberately doesn't)
+
+**Adds (all pure, all dark):**
+- A **resolver** — a small, side-effect-free function: given a component, it works out the
+  task *nature*, walks an ordered list of `(door, model)` candidates, skips the ones that
+  aren't reachable, and returns the winner + the fallback tail. It has exactly four honest
+  outcomes: a route, "fall through to today's routing" (for a component we haven't mapped),
+  "no route — use your own backup" (for a low-stakes sorter when everything's down), or
+  **throw a distinct fail-closed error** (for a safety gate when everything's down — a gate
+  must fail shut, never open).
+- **FD4.1 — the concrete pin.** A2 finishes the job A1 left: the sanctioned Claude reserve
+  now pins to a *concrete* model id (`claude-sonnet-4-6`), not a tier nickname that could
+  drift. And a **deny-by-default allowlist** clamp: on the Claude door, a judgment/sort call
+  may ONLY use that one reserve id — anything else gets clamped down to it. (Open-ended
+  *writing* is exempt — that's where Opus-via-CLI is legitimately the best tool.)
+- The `sessions.natureRouting` **config knob** (seeded dark on update), the wiring, and the
+  full test suite.
+
+**Doesn't (tracked, not dropped):** the actual *re-routing* (enforcing mode), the injection
+map, the build-time lint, the live-config validator, the durable audit log + dashboard read
+surface, the critical-gate drift notice, and the Fable→Opus migration — those are the ordered
+A2.2 remainder. And **nothing** about the paid metered doors or the money/PIN go-live — that
+is Increment B, deferred and PIN-gated.
+
+## The safety promise
+
+When the feature is **off** (which is everywhere on the fleet), the router behaves **bit-for-bit
+like today** — same door, same model, same everything. That's the whole safety case, and there's
+a named test that asserts it (`natureRouting UNSET ⇒ selection unchanged`). On a dev agent it runs
+in **dryRun**: it computes and logs what it *would* pick, then still does exactly today's thing.
+Flipping it to actually re-route is a later, operator-driven step.

package/upgrades/side-effects/la4-degrade-clamp-a1.md

@@ -0,0 +1,77 @@
+# Side-Effects Review — LA4 unconditional degrade-path safety clamp (S4 Increment A1)
+
+**Spec:** docs/specs/nature-axis-routing.md (status: **converged — pending operator approval** — NOT yet
+approved; this ships as a **Tier-1** standalone safety narrowing, the smallest independently-landable
+unit the spec's FD9 defines as **A1**). **Parent standards:** "Structure > Willpower", "No Silent
+Degradation to Brittle Fallback", benchmark-cited routing (INSTAR-Bench v3, rules R1/R2).
+**Not dark-gated:** A1 is UNCONDITIONAL by design — it fires regardless of `sessions.natureRouting`.
+**Files:** src/core/IntelligenceRouter.ts, tests/unit/la4-degrade-path-clamp.test.ts,
+docs/specs/nature-axis-routing.md (+ .eli16.md + reports/nature-axis-routing-convergence.md — the
+converged spec docs riding to main), upgrades/la4-degrade-clamp-a1.eli16.md,
+upgrades/side-effects/la4-degrade-clamp-a1.md, upgrades/next/la4-degrade-clamp-a1.md.
+
+## What changed
+
+1. **IntelligenceRouter.ts — the degrade-to-default path (`evaluate()`, the `if (!primary)` block).**
+   The shipped router degrades a binary-missing routed framework to
+   `defaultProvider.evaluate(prompt, options)` UNCLAMPED. When `defaultFramework === 'claude-code'` and
+   `options.model === 'capable'`, that landing is Opus-via-Claude-CLI — the measured-banned route for a
+   bounded/gating verdict (99.1% clean-API vs 81.7% via the CLI; emergency-stop 73%). The merged S2 clamp
+   (`clampClaudeCliSwapModel`) only guarded the failure-swap LOOP, leaving this exit open (the spec's LA4
+   fail-open). A1 clamps this exit: for a bounded/gating call, `options.model` is passed through
+   `clampClaudeCliSwapModel(defaultFramework, options.model)` (the SAME `capable→balanced` reserve S2
+   uses), and a distinct `degrade-path-model-clamp (LA4)` degrade note is emitted.
+2. **Two new exported pure helpers** in the same module: `routingNatureFor(component)` (a read-only lookup
+   of the merged S1 `LLM_ROUTING_NATURE` map with the same per-operation "/segment" + `server:` key
+   handling `categoryForComponent` uses) and `isBoundedGatingDegrade(component, options)` — the FD4/CR6-3
+   predicate: TRUE iff `attribution.gating === true` OR the component maps to a non-`WRITE` chain. A
+   `WRITE`-chain component (its legitimate Opus-CLI quality lane) or an unmapped, non-gating call ⇒ FALSE
+   (left unchanged).
+3. **Spec docs ride to main** (same pattern as reviewer-door inc1): the converged nature-axis-routing spec
+   + its ELI16 + convergence report, with `status: "converged — pending operator approval"` and the
+   `review-convergence` tag preserved AS-IS (no `approved: true` — that is the operator's step).
+
+## Blast radius
+
+- **The clamp only ever NARROWS.** `clampClaudeCliSwapModel` returns `capable→balanced` only for
+  `claude-code`; every other door and every non-`capable` tier passes through unchanged. It never upgrades
+  a tier, never blocks a call, never touches WRITE.
+- **Scope is exactly R1/R2.** `isBoundedGatingDegrade` fires only for a mapped non-WRITE nature or an
+  explicit `attribution.gating` flag. An unmapped, non-gating degrade (the common "other" category) is
+  left byte-identical. A non-`claude-code` default door is never clamped (Opus-via-API is fine).
+- **No new config, no new route, no state.** Two pure functions + a few lines on an existing branch. The
+  static map read is O(1) and always available, so the predicate never depends on `natureRouting` being
+  set — which is what makes the clamp genuinely unconditional.
+- **Honest non-byte-identical deviation.** This is the ONE deliberate behavior change on the degrade path:
+  a binary-missing bounded/gating `capable` degrade with a `claude-code` default now yields Sonnet-CLI
+  instead of Opus-CLI. Strictly the safe direction (measured-worse route → sanctioned reserve). Every
+  other path is untouched.
+
+## Risk + mitigation
+
+- **Risk:** the clamp over-reaches and downgrades a legitimate Opus-CLI WRITE call. **Mitigation:**
+  `isBoundedGatingDegrade` keys on `chain !== 'WRITE'`; a WRITE component is exempt. Proven by a property
+  test over the whole `LLM_ROUTING_NATURE` map (predicate === `chain !== 'WRITE'` for every mapped row).
+- **Risk:** the clamp silently fails to fire when the feature is off (the exact fleet-default state where
+  the fail-open lives). **Mitigation:** the predicate reads only the static map + `attribution`, never
+  `natureRouting`; a test asserts the clamp fires with `natureRouting` UNSET, and separately that a
+  non-`claude-code` default is left alone (both-default-framework arms).
+- **Risk:** collateral change to unrelated calls. **Mitigation:** unmapped, non-gating degrade test
+  asserts `model` is passed through untouched (`capable` stays `capable`).
+
+## Framework generality
+
+Not applicable to the session-launch/inject abstraction (this touches the internal LLM router only). The
+clamp is keyed on the `claude-code` DOOR specifically because that door carries the measured harness
+penalty; codex-cli / gemini-cli / pi-cli defaults are correctly never clamped (Opus-via-those-doors is
+not the banned route). This is framework-correct, not a Claude-only assumption.
+
+## Tests
+
+`tests/unit/la4-degrade-path-clamp.test.ts` (13 cases): `routingNatureFor` key handling; the
+`isBoundedGatingDegrade` predicate incl. the whole-map property test; and the load-bearing `evaluate()`
+integration — the clamp fires on a bounded/gating degrade with `natureRouting` unset, fires on a
+gating-flagged unmapped call, does NOT over-clamp an unmapped non-gating call, does NOT clamp a
+non-`claude-code` default, and leaves a non-`capable` tier alone. Existing
+`opus-claude-cli-gating-guardrail.test.ts` (14) + `intelligence-router.test.ts` (17) +
+`provider-fallback-swap-timeout.test.ts` (11) stay green; `tsc` clean.

package/upgrades/side-effects/nature-routing-a2.md

@@ -0,0 +1,89 @@
+# Side-Effects Review — Nature-Axis Routing, Increment A2.1 (dark/dryRun mechanism)
+
+**Spec:** docs/specs/nature-axis-routing.md (status: **converged — pending operator approval**;
+`review-convergence` tag, NOT `approved:true` — the operator's step). This ships as a **Tier-1**
+change: the smallest independently-landable **dark** unit of FD9's Increment A2. **Parent standards:**
+"Structure > Willpower", "No Silent Degradation to Brittle Fallback", benchmark-cited routing
+(INSTAR-Bench v3, rules R1/R2/R8), the Maturation Path (dev-gated dark), Migration Parity.
+
+**Files:** src/data/llmBenchCoverage.ts, src/core/IntelligenceRouter.ts, src/core/types.ts,
+src/commands/server.ts, src/core/PostUpdateMigrator.ts, tests/unit/nature-routing-resolver.test.ts,
+tests/unit/migrate-nature-routing-dark.test.ts, upgrades/nature-routing-a2.eli16.md,
+upgrades/side-effects/nature-routing-a2.md, upgrades/next/nature-routing-a2.md.
+
+## What changed
+
+1. **src/data/llmBenchCoverage.ts — the DATA half.** New pure, read-only constants: `RoutingDoor`
+   (CLI + metered-API door taxonomy, FD1), `CLI_ROUTING_DOORS` / `METERED_ROUTING_DOORS`,
+   `ChainPosition` + `NATURE_ROUTING_DEFAULT_CHAINS` (the four v3 CLI-only chains, FD2 — metered
+   positions are present but always skipped in Increment A), `ROUTING_LABEL_TO_MODEL_ID` (FD-LABEL/
+   FD4.1 — benchmark-label → concrete model id), `CLAUDE_CODE_RESERVE_MODEL_ID` (the single
+   sanctioned `claude-sonnet-4-6` reserve, FD4 place 1), and `NATURE_ROUTING_CRITICAL_GATES` (FD6).
+   Importing this changes NO behavior — it is data actuated only when the feature is enabled.
+2. **src/core/IntelligenceRouter.ts — the resolver.** New pure exports: `resolveNatureAndChain`
+   (FD3 tighten rule `E,B ≥ D ≥ A`), `resolvePositionModelId` (FD4.1), `clampToReserveOnCleanDoor`
+   (FD4 place-3 allowlist clamp), `resolveRoute` (the stateless fold with the four outcomes),
+   `mergeNatureRoutingChains`, and the `RouterFailClosedError` typed error. Two new
+   `IntelligenceRouterOptions` fields (`resolveNatureRouting`, `onNatureRoutePlan`) and a new,
+   tightly-scoped block in `evaluate()` that OBSERVES when the feature is enabled.
+3. **src/core/types.ts** — the `attribution.nature` opt-in tightening field (FD3) and the
+   `sessions.natureRouting` config schema (type-only, NOT in ConfigDefaults, per the
+   absent-equals-unchanged rule that `componentFrameworks`/`dynamicMcp` follow).
+4. **src/commands/server.ts** — the construction wiring: `resolveNatureRouting` reads config LIVE
+   per call and resolves `enabled` through `resolveDevAgentGate` (live-in-dryRun on a dev agent,
+   dark on the fleet); `onNatureRoutePlan` is an env-gated observe-only breadcrumb.
+5. **src/core/PostUpdateMigrator.ts** — `migrateConfigNatureRoutingDark` seeds `sessions.natureRouting`
+   dark on existing agents (`schemaVersion:3`, `dryRun:true`, `metered.goLive:false`; `enabled`
+   OMITTED for the dev-gate — the #1001 enable-path-integrity pattern), existence-checked + idempotent.
+
+## Explicitly DEFERRED (tracked A2.2 remainder — NOT dropped)
+
+Read this as intentional scope, not omission. This increment ships the pure mechanism + dark/dryRun
+observation. The following are the ordered remainder, each a separate landable change:
+
+- **Enforcing SELECTION** (dryRun:false actually re-routes) — A2.1 wires OBSERVATION only; flipping
+  `dryRun:false` logs a one-time "enforcing not yet wired" warning and stays byte-identical (an honest
+  no-op, never a silent dead switch and never a mis-route).
+- **FD4 places 1 & 2** — the build-time lint (`scripts/lint-nature-chains.mjs`) and the resolve-time
+  live-config validator. **Place 3 (the runtime allowlist clamp) DOES ship here** and is the actual
+  runtime guarantee: it clamps every resolved claude-code FAST/SORT/JUDGE position to the sanctioned
+  reserve id at selection time — so even a hand-edited chain cannot open the banned Opus-via-CLI route.
+  Places 1-2 are defense-in-depth for the build + config-edit surfaces.
+- **FD5b injection-exposure map** + R-rule lints (FD5c) — inert in A2.1 anyway: the only injection-
+  restricted door (`groq-api`) and the R8 Flash-Lite pin are METERED doors, always skipped in Increment
+  A; no CLI door in any chain is injection-restricted.
+- **The durable audit** (`logs/nature-routing.jsonl`) + `GET /intelligence/routing` dryRun plan/diff/
+  `?trace` read surface, the **FD6 aggregated critical-gate drift notice** + baseline, the **FD8
+  Fable→Opus** migration, and the **CLAUDE.md** capability blurb.
+- **Increment B** (metered-door live routing + FD12 money/PIN go-live) — DEFERRED + PIN-gated, an
+  operator step, never autonomous. No metered door routes and no spend ledger is touched here.
+
+## Blast radius
+
+- **Byte-identical when off — THE safety case.** When `sessions.natureRouting` is absent OR
+  `enabled:false` (the fleet default), the new block in `evaluate()` is skipped entirely and selection
+  is bit-for-bit today's. Asserted by name: `natureRouting UNSET ⇒ selection unchanged, onNatureRoutePlan
+  NEVER called` (the same options object is passed through untouched).
+- **A1 is untouched.** `clampClaudeCliSwapModel` (A1's always-on degrade/swap clamp, returning the
+  `balanced` TIER token) is NOT modified — the new `clampToReserveOnCleanDoor` is a SEPARATE, nature-
+  routing-scoped, concrete-id clamp used only inside `resolveRoute`. Touching A1's fn would have changed
+  its shipped byte-identical behavior; a test asserts A1 still returns `{model:'balanced'}`.
+- **dryRun cannot mis-route.** In dryRun the resolver only computes + logs; a resolver throw
+  (critical-gate fail-closed) is swallowed and recorded, never surfaced to the call path.
+- **Hot path.** The observation block runs on every internal LLM call ONLY when the feature is enabled
+  (dev agents). It is a stateless fold over static maps + O(1) door-reachability reads (cached by the
+  provider cache); the breadcrumb log is env-gated so a dev agent's hot path stays quiet.
+- **Config.** The seed is dark, existence-checked, idempotent, `enabled` omitted — it can never
+  force-dark a dev agent nor clobber an operator's config.
+
+## Second-pass review (Phase 5 — required: touches a "gate" / routing-of-safety-gates)
+
+The change routes safety GATES, so it triggers the high-risk second pass. Independent audit focus:
+(a) can the banned Opus-via-CLI route open? — No: the place-3 allowlist clamp is deny-by-default and
+fires on every resolved claude-code bounded/gating position, including a hand-edited chain. (b) can a
+critical gate fail OPEN? — No: the empty-set branch throws a distinct `RouterFailClosedError` for a
+critical gate (never `no-route`, never legacy routing); a unit test asserts both a nature-B gate
+(`MessagingToneGate`) and the nature-A R2-critical gate (`MessageSentinel`) throw. (c) is "off" truly
+inert? — Yes, the byte-identical-when-off test proves it. **Reviewer verdict: Concur with the review.**
+The one residual is that enforcing SELECTION is deferred — but since it is not wired, it cannot
+mis-route; the runtime clamp already makes the future enforcing path safe on its own.