instar 1.3.771 → 1.3.773

package/src/data/llmBenchCoverage.ts

@@ -684,3 +684,148 @@ export const LLM_ROUTING_NATURE: Readonly<Record<string, RoutingNature>> = {
   SessionSummarySentinel: { nature: 'D', chain: 'SORT' },
   'correction-learning': { nature: 'D', chain: 'SORT' },
 };
+
+/* ────────────────────────────────────────────────────────────────────────────
+ * S4 Increment A2 — nature-axis routing: door taxonomy, label registry, chains.
+ *
+ * These are the DATA half of the nature router (the resolver logic + wiring lives
+ * in src/core/IntelligenceRouter.ts). Everything here is pure, read-only config
+ * data — importing it changes NO behavior; it is actuated only when
+ * `sessions.natureRouting` is enabled (dev-gated dark; dryRun-first).
+ * Spec: docs/specs/nature-axis-routing.md — FD1 (doors), FD2 (chains), FD-LABEL/
+ * FD4.1 (label→id registry), FD4 (harness-door allowlist), FD6 (critical gates).
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * A RoutingDoor is a concrete access path to a model (FD1), in two classes:
+ *  - CLI doors — 1:1 with `IntelligenceFramework` (already wired).
+ *  - Metered-API doors — NEW, wired in Increment B behind the FD12 money/PIN
+ *    go-live. In Increment A they are DEFINED but always resolve as unavailable
+ *    (skipped) — so no metered/paid door ever routes in this increment.
+ */
+export type RoutingDoor =
+  | 'pi-cli'
+  | 'codex-cli'
+  | 'gemini-cli'
+  | 'claude-code'
+  | 'gemini-api'
+  | 'openrouter-api'
+  | 'groq-api';
+
+/** CLI doors — coincide exactly with the `IntelligenceFramework` id set. */
+export const CLI_ROUTING_DOORS: ReadonlySet<RoutingDoor> = new Set([
+  'pi-cli',
+  'codex-cli',
+  'gemini-cli',
+  'claude-code',
+]);
+
+/** Metered-API doors — Increment B; ALWAYS skipped (unavailable) in Increment A. */
+export const METERED_ROUTING_DOORS: ReadonlySet<RoutingDoor> = new Set([
+  'gemini-api',
+  'openrouter-api',
+  'groq-api',
+]);
+
+/**
+ * A chain position (FD2): `{ door, model }` plus static flags. `model` is a
+ * benchmark LABEL (`flash-lite`, `gpt-5.5`, `opus-4.8`) or a tier hint
+ * (`fast|balanced|capable`); FD-LABEL resolves it to a concrete model id.
+ */
+export interface ChainPosition {
+  readonly door: RoutingDoor;
+  readonly model: string;
+  /** Vault secret name backing a metered door (Increment B). */
+  readonly keyRef?: string;
+  /** Real-spend door — money-gated (Increment B). */
+  readonly moneyGated?: boolean;
+  /** `false` ⇒ this door must not take an injection-exposed call (FD5b; e.g. Groq). */
+  readonly injectionSafe?: boolean;
+  /** doc-tree / cartographer components may never route to any claude-code door (R6). */
+  readonly claudeBanned?: boolean;
+}
+
+export type NatureRoutingChains = Readonly<Record<RoutingChain, ReadonlyArray<ChainPosition>>>;
+
+/**
+ * FD2 — the four v3 CLI-only chain defaults (config default). Authored using ONLY
+ * Echo's real doors (no `openai-api`). Metered positions are present but resolve
+ * unavailable until Increment B. An operator MAY override a chain wholesale
+ * (subject to the FD4 resolve-time validation — a tracked A2.2 remainder).
+ */
+export const NATURE_ROUTING_DEFAULT_CHAINS: NatureRoutingChains = {
+  // Latency-sensitive quick-sort.
+  FAST: [
+    { door: 'gemini-api', model: 'flash-lite', keyRef: 'metered_gemini_bench', moneyGated: true },
+    { door: 'pi-cli', model: 'gpt-5.5' },
+  ],
+  // Background quick-sort.
+  SORT: [
+    { door: 'codex-cli', model: 'gpt-5.4-mini' },
+    { door: 'pi-cli', model: 'gpt-5.5' },
+    { door: 'gemini-api', model: 'flash-lite', keyRef: 'metered_gemini_bench', moneyGated: true },
+    { door: 'claude-code', model: 'balanced' }, // Sonnet-4.6 reserve
+  ],
+  // Careful judgment.
+  JUDGE: [
+    { door: 'pi-cli', model: 'gpt-5.5' },
+    { door: 'codex-cli', model: 'gpt-5.5' },
+    { door: 'openrouter-api', model: 'gpt-5.5', keyRef: 'metered_openrouter_bench', moneyGated: true },
+    { door: 'openrouter-api', model: 'opus-4.8', keyRef: 'metered_openrouter_bench', moneyGated: true }, // clean API, NEVER CLI
+    { door: 'claude-code', model: 'balanced' }, // Sonnet-4.6 reserve
+  ],
+  // Open-ended writing (WRITE is the sole Opus-via-CLI-exempt lane — FD4).
+  WRITE: [
+    { door: 'codex-cli', model: 'gpt-5.4-mini' },
+    { door: 'groq-api', model: 'gpt-oss-120B', keyRef: 'metered_groq_bench', moneyGated: true, injectionSafe: false },
+    { door: 'claude-code', model: 'fast' }, // Haiku-4.5
+    { door: 'claude-code', model: 'capable' }, // Opus-4.8 quality lane — allowed on WRITE (FD4)
+  ],
+};
+
+/**
+ * FD-LABEL / FD4.1 — the explicit per-door registry mapping a benchmark LABEL to a
+ * concrete model id. This is the boundary A1 deliberately deferred: A1 clamps to the
+ * `balanced` tier TOKEN; A2 pins the reserve to a CONCRETE id. The `claude-code`
+ * `balanced` reserve pins to the versioned manifest id `claude-sonnet-4-6` (FD4 place
+ * 1 — a tier label could resolve differently under a future CLI alias/remap; the
+ * pinned concrete id can't). A tier hint NOT present here (`fast`, `capable`) is left
+ * as-is and resolves downstream through the existing per-adapter tier map.
+ */
+export const ROUTING_LABEL_TO_MODEL_ID: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  'gemini-api': { 'flash-lite': 'gemini-3.1-flash-lite' },
+  'openrouter-api': { 'opus-4.8': 'anthropic/claude-opus-4-8', 'gpt-5.5': 'openai/gpt-5.5' },
+  'claude-code': { balanced: 'claude-sonnet-4-6' },
+  'codex-cli': { 'gpt-5.5': 'gpt-5.5', 'gpt-5.4-mini': 'gpt-5.4-mini' },
+  'pi-cli': { 'gpt-5.5': 'gpt-5.5' },
+  'groq-api': { 'gpt-oss-120B': 'openai/gpt-oss-120b' },
+};
+
+/**
+ * The SINGLE sanctioned `claude-code` reserve model id for a bounded/gating
+ * (FAST/SORT/JUDGE) chain (FD4 place 1). The allowlist clamp permits ONLY this id on
+ * the claude-code door in those chains — deny-by-default — and clamps any other
+ * claude-code selection down to it. Pinned to the concrete manifest id (NOT the
+ * `balanced` tier label). Kept in sync with
+ * scripts/model-registry-freshness.manifest.json (role `balanced-anthropic`).
+ */
+export const CLAUDE_CODE_RESERVE_MODEL_ID = ROUTING_LABEL_TO_MODEL_ID['claude-code'].balanced;
+
+/**
+ * FD6 — the critical-gate components (nature-B JUDGE safety gates + `MessageSentinel`,
+ * a nature-A / R2-critical gate). Load-bearing for the resolver's empty-set branch: a
+ * critical gate with no available door FAILS CLOSED (throw), never `no-route`. A gate
+ * must carry a real nature entry (never a `chainExempt` filler — FD4 Adv5).
+ */
+export const NATURE_ROUTING_CRITICAL_GATES: ReadonlySet<string> = new Set([
+  'MessagingToneGate',
+  'CompletionEvaluator',
+  'ExternalOperationGate',
+  'LLMSanitizer',
+  'CoherenceReviewer',
+  'UnjustifiedStopGate',
+  'SessionWatchdog',
+  'StallTriageNurse',
+  'ProjectDriftChecker',
+  'MessageSentinel', // nature A, R2-critical
+]);

package/upgrades/1.3.772.md

@@ -0,0 +1,63 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Shipped the dark/dryRun mechanism for Nature-Axis Routing (S4 Increment A2.1) — the internal LLM
+router can now, in principle, choose which model and which access door a background check runs on
+based on the KIND of task it is (a quick sort vs a careful judgment vs open-ended writing), instead
+of only its category. This increment lands the pure resolver + its safety enforcement, wired dark:
+DARK on the fleet, and LIVE-in-dryRun on a development agent (it computes and logs the route it WOULD
+pick, then still does exactly today's thing — it never re-routes yet).
+
+The resolver is a small, side-effect-free fold with four honest outcomes: a resolved route; fall
+through to today's routing (for a component with no nature mapping); no route, use your own heuristic
+(for a low-stakes sorter when every door is down); or a distinct fail-closed error (for a safety gate
+when every door is down — a gate must fail shut, never open). It also finishes the concrete-id pinning
+A1 deferred (FD4.1): the sanctioned Claude reserve now pins to the concrete model id claude-sonnet-4-6,
+and a deny-by-default allowlist clamp keeps a bounded or judgment call on the Claude door pinned to that
+one reserve id — the measured-banned Opus-via-the-Claude-CLI route can never open, even if someone
+hand-edits a chain. Open-ended writing is exempt, since that is where Opus-via-CLI is legitimately best.
+
+The load-bearing safety property is asserted by a named test: when the feature is unset or off, the
+router is bit-for-bit identical to today. A1's always-on clamp is untouched — the new clamp is a
+separate, nature-routing-scoped function.
+
+Deferred and tracked (not dropped): the actual re-routing (enforcing mode), the injection map, the
+build-time lint and live-config validator (FD4 places 1-2; place 3, the runtime clamp, ships here),
+the durable audit log and dashboard read surface, the critical-gate drift notice, and the Fable-to-Opus
+migration. The paid metered doors and the money/PIN go-live are Increment B — deferred and PIN-gated.
+
+## What to Tell Your User
+
+Nothing proactive — this is an internal, turned-off-by-default plumbing change with no user-facing
+surface. If a user ever asks why a background check might one day run on a different model than the one
+they talk to, the plain answer is: the agent measured which model is best at each kind of internal
+check, and this lets it eventually pick the right one for each job — but it is currently just watching
+and learning what it would choose, not changing anything, and turning it fully on is a separate,
+deliberate step the operator takes. Nothing they do changes today, and no setting is required.
+
+## Summary of New Capabilities
+
+- A nature-aware route resolver picks a model and access door by task kind — shipped dark on the fleet,
+  live in dryRun-observe mode on a development agent.
+- A deny-by-default allowlist keeps every bounded or judgment call on the Claude door pinned to the one
+  sanctioned Sonnet reserve id, so the measured-banned Opus-via-CLI route cannot open.
+- The sanctioned reserve is now pinned to a concrete model id, not a tier nickname that could drift.
+- A new config block, seeded dark on update, with the enable flag omitted so it rides the development-
+  agent gate. When off, routing is byte-identical to today.
+
+## Evidence
+
+- tests/unit/nature-routing-resolver.test.ts — 29 cases: the FD3 tighten rule (both sides of every
+  boundary), the four resolveRoute outcomes, the FD4.1 concrete-id pin, the FD4 allowlist clamp
+  (accepts the reserve id, rejects every other Claude id, WRITE exempt), the proof the new clamp is a
+  SEPARATE function from A1's, and the named byte-identical-when-off assertion plus dryRun-observes-but-
+  does-not-re-route.
+- tests/unit/migrate-nature-routing-dark.test.ts — 4 cases: the dark seed omits enabled, never clobbers
+  a configured block, no-ops without a sessions block, and is idempotent.
+- Regression: la4-degrade-path-clamp (13) + intelligence-router (17) + opus-claude-cli-gating-guardrail
+  (14) + llm-routing-nature-ratchet (6) stay green; tsc --noEmit clean.
+- Spec: docs/specs/nature-axis-routing.md — FD3, FD4/FD4.1, FD9 (the A1/A2 increment split).

package/upgrades/1.3.773.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Completes two of the three enforcement places for the FD4 "harness-door ban" in the (still-dark) nature-axis router (spec: docs/specs/nature-axis-routing.md). The third place — the always-on runtime clamp — already shipped in A1 (#1386) and A2.1 (#1387).
+
+- **Build-time lint** (scripts/lint-nature-chains.mjs, wired into `npm run lint`): fails the build if any FAST/SORT/JUDGE chain position resolves to a non-reserve model on the claude-code harness door, if the one permitted claude-code position is an unpinned tier label instead of the pinned concrete reserve id, or if any chain (including WRITE) resolves to a Fable model. Deny-by-default allowlist; the reserve id and label map are derived from src/data/llmBenchCoverage.ts, so nothing is hard-coded.
+- **Resolve-time + config-load validator** (validateNatureRoutingChains, a pure predicate in src/core/IntelligenceRouter.ts): the same rule run on live config. It rejects a banned chain both when config is loaded (mergeNatureRoutingChains) and when a route is resolved (resolveRoute), falling back to the built-in defaults and warning once — so an operator config edit can never open the banned route.
+
+Dev-gated / dark: both new checks only run when sessions.natureRouting is enabled; when it is unset/off the resolve path is byte-identical to before (asserted in tests). This is enforcement hardening only — NOT the metered-door Increment B, and NOT the go-live flip.
+
+## What to Tell Your User
+
+This is internal safety plumbing for how I pick which model answers my own background checks — there is nothing for you to turn on or change, and nothing about our conversations changes. In plain terms: I added two guards that make it structurally impossible for one of my quick safety checks to be routed to an expensive model in a way that a bench found makes it easier to fool. One guard runs when my code is built; the other runs if the routing feature is ever switched on. The routing feature itself is still off by default, so today this is invisible — it just means that when it does get turned on, the unsafe route is already sealed shut in two more places.
+
+## Summary of New Capabilities
+
+- **FD4 harness-door ban — build-lint**: a new build check refuses any routing chain that would send a bounded safety check to a non-reserve model on the Claude CLI, or emit a Fable model.
+- **FD4 harness-door ban — runtime validator**: a live config/resolve-time guard rejects a banned routing chain and falls back to the safe built-in defaults, so a config edit can never re-open the banned route.
+
+## Evidence
+
+- scripts/lint-nature-chains.mjs runs clean over the real chain map; full `npm run lint` is green.
+- tests/unit/llm-routing-nature-ratchet.test.ts and tests/unit/nature-routing-resolver.test.ts (54 tests) green, covering positive/negative lint cases, config-load and resolve-time rejection, the build-lint/validator drift guard, and byte-identical-when-off with a banned override present.

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/nature-axis-routing-fd4-lints.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — FD4 harness-door ban: enforcement lints (build-lint + resolve-time/config-load validator)
+
+**Version / slug:** `nature-axis-routing-fd4-lints`
+**Date:** `2026-07-04`
+**Author:** `echo (build hand, 24h autonomous run, topic 29723)`
+**Second-pass reviewer:** `not required (Tier 1 — deterministic, dark/dev-gated, byte-identical when off)`
+
+## Summary of the change
+
+Completes the FD4 "harness-door ban" from `docs/specs/nature-axis-routing.md` by adding the two enforcement places that were still prose (the third place — the always-on runtime clamp — already shipped in A1 #1386 / A2.1 #1387). Files touched: `src/core/IntelligenceRouter.ts` (pure validator predicate `validateNatureRoutingChains`/`validateChainPosition`/`isNatureRoutingChainsValid` + wiring into `mergeNatureRoutingChains` config-load and `resolveRoute` resolve-time + a deduped rejection warning), `scripts/lint-nature-chains.mjs` (new build-lint), `package.json` (wire the lint into `npm run lint` + a `lint:nature-chains` alias), and two unit test files (`tests/unit/llm-routing-nature-ratchet.test.ts`, `tests/unit/nature-routing-resolver.test.ts`). The change interacts with the nature-axis routing decision surface only; it adds NO new routing behavior when the feature is off.
+
+## Decision-point inventory
+
+- `FD4 harness-door ban (compile-time place)` — add — the build-lint `lint-nature-chains.mjs` fails the build on a banned authored chain position.
+- `FD4.3 resolve-time / config-load validator` — add — the pure predicate that rejects a banned live chain → built-in defaults + warn-once, consulted in `resolveRoute` and `mergeNatureRoutingChains`.
+- `FD4 place-3 runtime clamp (clampToReserveOnCleanDoor / clampClaudeCliSwapModel)` — pass-through — unchanged; the new validator is belt-and-suspenders ahead of it.
+- `sessions.natureRouting enable/dryRun gate` — pass-through — the whole nature block (and therefore the new validator) still runs ONLY when enabled.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The build-lint could in principle reject a legitimate authored chain. It does not: the registry-pinned `balanced` label on claude-code (which resolves to the concrete reserve id) is accepted in FAST/SORT/JUDGE, the literal concrete reserve id is accepted, WRITE's `capable`/`fast` (Opus/Haiku) are accepted, and clean non-claude-code doors (incl. the openrouter Opus API door) are accepted. Verified: the real authored v3 defaults pass with zero violations (positive ratchet test). The runtime validator only rejects a chain that violates the static ban, and it falls back to the built-in defaults rather than failing the call, so a rejected operator override degrades to the safe default, never to a hard denial.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The lint's model-id resolution is scoped to `ROUTING_LABEL_TO_MODEL_ID` + a literal Fable substring scan — it does not follow a claude-code *tier label* through the downstream per-adapter tier map (e.g. `frameworkDefaultModels.claude-code`). That is deliberate: the claude-code FAST/SORT/JUDGE allowlist forces the pinned reserve id regardless, and WRITE tier resolution is the FD8 companion config concern (a tracked, restart-gated remainder), not this slice. The FD4.2 R-rule lints (R3–R8: doc-tree Claude-ban, Flash-Lite pin, injection-exposed JUDGE bans) are NOT built here — they depend on an injection-exposure map that does not yet exist; tracked as a remainder.
+
+## 3. Level-of-abstraction fit
+
+The validator is a pure, side-effect-free predicate over the static chain data (mirrors `validateChainPosition`), placed beside the existing FD4 functions in `IntelligenceRouter.ts`. The build-lint follows the house pattern (`lint-routing-registry-freshness.js` / `lint-no-opus-claude-cli-gating.js`): read source text pre-compile, export a pure function, exit 1 on violation. Correct altitude — no new engine, no new config language.
+
+## 4. Signal vs authority compliance
+
+The build-lint is a CI gate (a build ratchet — its natural authority is to fail the build on a real violation; the authored defaults are clean so it passes today). The resolve-time/config-load validator does exercise authority — it REJECTS a banned chain → built-in defaults — but this is a safety clamp on a MODEL-ROUTING decision, not a principal/operator authority decision: it never blocks a user message, never grants or credits anyone, and only ever narrows toward the sanctioned-safe default (the same safe direction as the existing runtime clamp). It emits a deduped warn-once so the rejection is never silent. No principal identity is read or asserted anywhere.
+
+## 5. Interactions
+
+Interacts with `resolveRoute` (adds a validation step before the availability walk) and `mergeNatureRoutingChains` (rejects a banned override chain at load). Both run only under `natureRouting.enabled`. Existing resolver tests (which pass valid default chains / valid overrides) are unaffected — validation returns empty and the positions are unchanged. The place-3 clamp still runs downstream; the two layers coexist as designed (three-place enforcement). The A1 `clampClaudeCliSwapModel` degrade-path clamp is untouched (its byte-identical-when-off behavior is preserved).
+
+## 6. External surfaces
+
+No external surface. No new HTTP route, no CLI command, no MCP tool, no Telegram/Slack path, no network egress. The build-lint reads a local source file; the validator reads in-memory config already loaded by the router.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator-facing surface added or changed. The warn-once rejection message names the offending chain + the human-readable violation detail (which position, which rule, the sanctioned reserve id) so an operator who mis-edits a chain via `PATCH /config` sees exactly why it was rejected. No raw secrets, tokens, or file paths are emitted.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+No cross-machine state. The validator is a pure function over per-call config; the build-lint is a repo build gate. The chain config is read live per call on each machine independently (existing `resolveConfig()` behavior). No replication, no shared ledger, no lease interaction. A per-machine operator override that is banned is rejected identically and independently on each machine.
+
+## 8. Rollback cost
+
+Low and clean. Revert the PR: the build-lint line drops out of `npm run lint`, the validator functions are removed, and `resolveRoute`/`mergeNatureRoutingChains` return to passing chains through unvalidated (the place-3 runtime clamp still guarantees safety). No migration, no persisted state, no config schema change, no data-format change. Because the validator only runs when `natureRouting.enabled`, a rollback is invisible to every fleet agent (feature dark).
+
+## Conclusion
+
+A deterministic, dark/dev-gated, byte-identical-when-off hardening slice that closes two of the three FD4 enforcement places. No block/allow surface on user traffic, no external surface, no multi-machine state, trivial rollback. Tier 1.
+
+## Second-pass review (if required)
+
+Not required — Tier 1 (deterministic enforcement lints; byte-identical when off; no operator/user-facing surface). Full `npm run lint` green and both affected test files green (54 tests) at authoring time.
+
+## Evidence pointers
+
+- `scripts/lint-nature-chains.mjs` runs clean over the real chain map (`lint-nature-chains: OK`).
+- `tests/unit/llm-routing-nature-ratchet.test.ts` — positive (real chains pass) + negative (Opus / tier-label / Fable fail) + drift guard (lint predicate agrees with the TS validator).
+- `tests/unit/nature-routing-resolver.test.ts` — validator both-sides, config-load rejection, resolve-time rejection, and byte-identical-when-off with a banned override present.
+
+## Class-Closure Declaration (display-only mirror)
+
+This closes the compile-time + resolve-time/config-load places of the FD4 ban as a class over the whole chain map (all four chains, every position), not a single spot fix. Tracked remainders (out of this slice by design): the FD4.2 R-rule lints (need the injection-exposure map), the full FD6 aggregated attention-item on rejection (warn-once here), and the FD8 `frameworkDefaultModels` companion config change (restart-gated).

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.