instar 1.3.705 → 1.3.707

package/upgrades/1.3.706.md

@@ -0,0 +1,80 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The guard-posture inventory (`GET /guards`) can now express that a DARK feature
+is load-bearing — that a critical path depends on it — instead of treating it as
+an ordinary optional dark feature that sits quiet while the path it should guard
+runs unguarded. This is the guard-layer arm of the ratified "A Dark Feature Guards
+Nothing" standard, and it closes the gap the 2026-07-01 silent-loss postmortem
+named (operator message delivery depended on dark guards, and nothing surfaced it).
+
+A guard declared `loadBearing` in the manifest now carries a `criticalPath` label
+on every row, and when it sits silently unguarded it is classified one of three
+ways:
+- `loadBearingGap` — LOUD. A critical path is unguarded. It alerts on its OWN
+  attention episode track (`guard-posture-loadbearing:ep-N`), so a long-lived gap
+  can never mask an acute load-shed on another guard.
+- `loadBearingSoaking` — a dry-run guard graduating within a bounded, code-constant
+  soak window. Surfaced on `/guards` only, no alert; it LAPSES to a loud gap if it
+  stalls past the window.
+- `loadBearingAccepted` — an owned, PIN-authenticated operator acceptance is on
+  record. Full suppression + a visible accepted-risk row.
+
+New route (dashboard-PIN-gated, `owner` + `reason` both required):
+`POST`/`DELETE /guards/:key/accept-fallback`. The initial curated load-bearing set
+is small and conservative: the durable inbound-message queue and the stranded-topic
+sentinel, both on the operator-message-delivery critical path.
+
+The classifier stays observe-only — it never gates, blocks, or disables anything,
+and `/guards` is byte-identical for a consumer that ignores the new fields. Rollback
+lever for the alert: `monitoring.guardPostureProbe.alertLoadBearingGaps` (the
+classification stays either way).
+
+## What to Tell Your User
+
+I can now tell you when a critical safety system is turned off but something
+important actually depends on it — instead of it quietly staying dark. If that
+happens I will flag it clearly and give you three ways to resolve it: turn the
+guard on, let it finish a short grace period while it is being rolled out, or have
+you formally accept the risk (which I record with your name and reason so it is a
+real decision, not a shrug). Accepting a risk needs your dashboard PIN — I cannot
+do it on your behalf. If you ever ask "why is a critical guard flagged as a gap?",
+that is this feature at work.
+
+## Summary of New Capabilities
+
+- `GET /guards` rows gain `loadBearing`, `criticalPath`, `loadBearingGap`,
+  `loadBearingSoaking`, `loadBearingAccepted`, and `acceptedFallbackReason`; the
+  summary and the capacity heartbeat gain `loadBearingGapKeys`,
+  `loadBearingSoakingKeys`, and `loadBearingAcceptedKeys`.
+- `POST /guards/:key/accept-fallback` (dashboard-PIN-gated; `owner` + `reason`
+  required) records an owned per-machine acceptance; `DELETE` revokes it and
+  reopens the gap.
+- The GuardPostureProbe raises a load-bearing gap on its own bounded, per-episode
+  attention topic, separate from the acute load-shed track (no masking).
+- Per-machine by design: accepting a risk on one machine never silences a peer's
+  gap; a peer's critical-path label is looked up from the local, fleet-uniform
+  manifest.
+
+## Evidence
+
+Before: on an agent where a load-bearing feature ships dark (e.g. the inbound-message
+queue with `enabled:false`), `GET /guards` reported it identically to any optional
+dark feature — an `off:dark-default` row with no signal that a critical path depended
+on it, so nothing ever surfaced the exposure (the postmortem's silent-loss shape).
+
+After (verified over the real HTTP route + real disk in the Tier-3 e2e): the same
+dark guard's `/guards` row now carries `loadBearing:true`, a `criticalPath` string,
+and `loadBearingGap:true`, and the summary lists it under `loadBearingGapKeys`.
+`POST /guards/:key/accept-fallback` with a valid PIN + owner + reason flips the row to
+`loadBearingAccepted` (gap cleared, reason visible); `DELETE` reopens the gap, and both
+survive a fresh-server "reboot" reading the same durable per-machine record. The
+masking regression drives the REAL `createAttentionItem` funnel and asserts an acute
+off-runtime-divergent guard surfaces while a load-bearing-gap episode has been open —
+and an inert-lever test proves the funnel dedups by item id, so the separate episode
+track (not a healthKey change) is what carries the fix. `npx tsc --noEmit` clean and
+`npm run lint` exit 0.

package/upgrades/1.3.707.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Thirteen background LLM call sites that were quietly running on the default
+framework (Claude) now route off-Claude with their peers. The framework router
+picks a provider by a component's category; these thirteen were absent from the
+category map, so they resolved to `other` and fell back to Claude — burning
+Anthropic quota while near-identical siblings routed to the cheaper, less
+rate-limited off-Claude providers.
+
+They were the pinned `WIRING_EXCLUSIONS` backlog explicitly deferred from the
+token-audit PR ("each needs its own deliberate routing decision"). This is that
+decision: each is registered by function — `InputClassifier`,
+`SessionSummarySentinel`, `TelegramAdapter` (sentinel; `TelegramAdapter` also fixes
+an asymmetry versus the already-registered `SlackAdapter` alert-suppression judge);
+`ResumeValidator` (gate); and `Usher`, `TopicIntentExtractor`, `PreCompactionFlush`,
+`TreeSynthesis`, `LLMConflictResolver`, `openConversationBrief`, `a2a-checkin`,
+`correction-learning`, `mentor-stage-b` (reflector).
+
+`WIRING_EXCLUSIONS` now holds only the five components that route via an explicit
+`attribution.category` and are correctly map-unregistered. The existing wiring
+ratchet remains the drift guard against future recurrence. Additive and fully
+reversible; no new logic, no new decision authority.
+
+## What to Tell Your User
+
+Thirteen of my small background AI helpers — the ones that classify messages,
+summarize sessions, extract facts before compaction, and similar housekeeping —
+were quietly running on Claude instead of the cheaper providers the rest of my
+background checks use. That was burning Claude subscription quota (the scarce,
+rate-limited resource) on work that never needed it. They now route off Claude
+like their peers, so more of your Claude quota stays available for the
+conversations and heavy work where it matters. Nothing changes in what these
+helpers do — only which provider quietly runs them.
+
+## Summary of New Capabilities
+
+None — no new API routes, config keys, or user-facing behavior. This is a
+routing-map completion: 13 existing internal LLM call sites now resolve to their
+proper category (`sentinel`/`gate`/`reflector`) so the existing
+Provider-Fallback Default Policy routes them off Claude. Operators can still
+override any of them per-agent via `sessions.componentFrameworks.overrides`.
+
+## Evidence
+
+Before: `GET /intelligence/routing` on a live agent showed these 13 components
+absent from the known-components registry, and `categoryForComponent()` in the
+deployed dist resolved each to `'other'` → the agent default framework (Claude).
+Verified against the deployed code during the 2026-07-01 LLM Routing Registry
+audit (docs/LLM-ROUTING-REGISTRY.md), not just the source branch — each of the
+13 calls `.evaluate()` with an `attribution.component` that had no map entry and
+no explicit `attribution.category`, while siblings like `SlackAdapter` (mapped)
+routed off-Claude.
+
+After: `categoryForComponent('InputClassifier')` → `'sentinel'` (and likewise
+for all 13; `'TelegramAdapter'` now matches the already-mapped `SlackAdapter`).
+The wiring ratchet (`tests/unit/llm-attribution-ratchet.test.ts`) proves both
+directions over the real source tree: every literal `attribution.component` in
+`src/` resolves to a registered category or a pinned explicit-category
+exception, and every remaining exception genuinely resolves to `'other'`. The
+router, integration, and e2e routing suites are green unchanged.

package/upgrades/side-effects/g3-dark-but-load-bearing-guards.md

@@ -0,0 +1,143 @@
+# Side-Effects Review — G3 Dark-but-Load-Bearing Guard Classification
+
+**Version / slug:** `g3-dark-but-load-bearing-guards`
+**Date:** `2026-07-01`
+**Author:** Echo (autonomous)
+**Spec:** `docs/specs/g3-dark-but-load-bearing-guards.md` (review-convergence 2026-07-02, 6 iterations, cross-model codex GPT-5.5; approved:true)
+**Parent principle:** A Dark Feature Guards Nothing (STANDARDS-REGISTRY.md, ratified 2026-07-01 PR #1316)
+**Second-pass reviewer:** not-required (Tier 2; observe-only classifier + one PIN-gated suppress route; no new gating/blocking decision, byte-identical `/guards` for a consumer ignoring the new fields)
+
+## Summary of the change
+
+The `/guards` inventory could not express "this dark feature is load-bearing" — a
+feature that ships DARK but that a CRITICAL PATH depends on was indistinguishable
+from a genuinely-optional dark feature. It sat quiet while the path it should guard
+ran unguarded (the 2026-07-01 silent-loss postmortem's case study: operator message
+delivery depended on dark guards, and nothing surfaced it).
+
+G3 adds an optional `loadBearing`/`criticalPath`/`soakWindowDays`/`declaredLoadBearingAt`
+manifest declaration and classifies a load-bearing guard in a silent-unguarded posture
+into ONE of three states — `loadBearingGap` (loud, its OWN attention channel),
+`loadBearingSoaking` (graduate arm, no attention item), `loadBearingAccepted` (owned,
+PIN-authenticated operator acceptance). `criticalPath` travels on EVERY anomaly of a
+load-bearing guard. Pure classifier, observe-only — it never gates.
+
+### Files added
+- `src/monitoring/guardAcceptedFallbacks.ts` — ALL disk I/O for the per-machine
+  operator-accept store (`state/guard-accepted-fallbacks.json`, keyed
+  `<machineId>:<guardKey>`). Keeps the classifier PURE: the caller reads/scopes
+  once and threads the map in. Missing/corrupt file ⇒ empty map (safe direction).
+- Tests: `tests/unit/monitoring/guard-posture-loadbearing.test.ts`,
+  `tests/unit/monitoring/guard-posture-probe-loadbearing.test.ts`,
+  `tests/integration/guards-accept-fallback-route.test.ts`,
+  `tests/e2e/guards-loadbearing-lifecycle.test.ts`,
+  `tests/unit/PostUpdateMigrator-guardLoadBearingSection.test.ts`.
+
+### Files modified
+- `src/monitoring/guardManifest.ts` — 4 optional fields; the two NEW manifest lints
+  (`validateGuardManifest`); the curated initial load-bearing set (inboundQueue +
+  strandedTopicSentinel, both operator-message-delivery critical-path, 30-day soak
+  window declared 2026-07-01).
+- `src/monitoring/guardPostureView.ts` — the SIX new row fields + three-state
+  precedence (accepted → soaking-within-window → gap) on a threaded `now`; both
+  `deriveGuardRow` and `buildGuardInventory` stay PURE (accept map threaded via
+  `DeriveInput`/`opts`); `ROW_FIELD_ALLOWLIST` extended with all six by name; summary
+  + heartbeat gain the three key-lists.
+- `src/monitoring/probes/GuardPostureProbe.ts` — the SEPARATE `load-bearing-gap`
+  episode track (own `openEpisodeId`/`episodeEmitted`/anomalies + item-id namespace
+  `guard-posture-loadbearing:ep-N`); acute close condition tests `currentAcute` (not
+  the shared set); `load-bearing-gap` class pushed in both evaluate paths; criticalPath
+  on all load-bearing anomalies; `alertLoadBearingGaps` sub-flag (default-on).
+- `src/core/types.ts` — the 3 optional key-list fields on `GuardPostureSummary`.
+- `src/server/routes.ts` — GET /guards threads the accept map + now; the PIN-gated
+  `POST`/`DELETE /guards/:key/accept-fallback` route (owner+reason required).
+- `src/commands/server.ts` — all 3 `buildGuardInventory` call sites thread the accept
+  map + now (route, probe `getLocalPosture`, heartbeat `selfGuardPosture`); the probe's
+  `alertLoadBearingGaps` sub-flag resolved from config (default true).
+- `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` — Agent Awareness +
+  Migration Parity (content-sniffed on `loadBearingGap`).
+- `src/data/state-coherence-registry.json` — the new `guard-accepted-fallbacks`
+  store category + a `resolution`-class retention policy.
+
+## Decision-point inventory
+
+- **Added — one PIN-gated route** (`POST/DELETE /guards/:key/accept-fallback`): the
+  ONLY new decision surface. It SUPPRESSES a safety SIGNAL for a named operator; it
+  never allows/blocks an action. Gated by `checkMandatePin` (Know Your Principal — a
+  Bearer token cannot accept a safety risk); `owner` AND `reason` both REQUIRED (400
+  otherwise); a non-load-bearing key is 404.
+- **Added — classifier flags**: `deriveGuardRow` sets orthogonal FLAGS; the nine
+  `GuardEffectiveState` values + the normative precedence table are UNCHANGED. No new
+  effective state, so the nine-state contract cannot regress.
+- **Added — probe anomaly class** `load-bearing-gap` on its OWN episode track.
+  Observe-only: the probe only ever calls the attention funnel; never gates.
+- No agent-to-user message-flow gate is added.
+
+## Roll-up across the seven review dimensions
+
+1. **Over-block**: none. The classifier adds flags; `/guards` is byte-identical for a
+   consumer ignoring the new fields. The accept route only suppresses a signal — it
+   loosens nothing and blocks nothing. The alert has a rollback sub-flag
+   (`alertLoadBearingGaps:false`) that keeps the classification.
+2. **Under-block**: none. No gate was loosened. A load-bearing dark guard is now MORE
+   visible, not less. Soaking only defers the alert within a bounded, code-constant
+   window; a typo'd `declaredLoadBearingAt` falls to the LOUD gap (safe direction).
+3. **Masking**: the round-3/round-4 fix. `load-bearing-gap` is a designed long-lived
+   anomaly; running it on a SEPARATE episode track (its own item-id namespace) means a
+   week-open gap can never hold the acute track's episode open. The regression test
+   drives the REAL `createAttentionItem` funnel and asserts an acute off-runtime-divergent
+   surfaces while the lb episode is open; the inert-lever test proves the funnel dedups
+   by ID, so a healthKey-only split would leave masking intact.
+4. **Multi-machine**: classification is per-machine (an accept on machine A never
+   silences a peer's gap — proven by test). Manifest fields are fleet-uniform constants;
+   a peer's criticalPath is looked up from the local manifest. The heartbeat carries the
+   three key-lists (Array.isArray-guarded for an un-upgraded peer). The 3rd-site fix: the
+   heartbeat compute threads the local accept map, so an accepted guard never ships to
+   peers as a false gap.
+5. **Purity / I/O layering**: `deriveGuardRow` AND `buildGuardInventory` gain no `fs`.
+   The caller reads the accept file ONCE per inventory build and threads the scoped map;
+   the new `guardAcceptedFallbacks.ts` module owns all disk I/O. One accept-file read per
+   inventory build, never per guard.
+6. **Bounded Notification Surface**: each track surfaces as ONE bounded, coalesced,
+   per-episode class-level forum topic (two class-level topics max, never per-guard).
+   Soaking pushes NO attention item.
+7. **Migration Parity / Agent Awareness**: the manifest ships as code (reaches existing
+   agents automatically); the CLAUDE.md vocabulary + accept route reach existing agents
+   via a content-sniffed `migrateClaudeMd` addendum; new agents get it in `generateClaudeMd`.
+   Migration idempotency + parity covered by a dedicated test.
+
+## Rollout / rollback
+
+Classification + route + separate-track wiring ship ALWAYS-ON as pure observability
+(additive, never gating). The probe ALERT on `load-bearing-gap` rides the existing
+GuardPostureProbe enablement + the `monitoring.guardPostureProbe.alertLoadBearingGaps`
+sub-flag (default-on; soak windows are code constants). Rollback = set the sub-flag
+false; `/guards` keeps the classification. The accept store is a per-machine JSON file;
+DELETE scopes to the operator record only, never the manifest soak constant.
+
+## Test evidence
+
+`npx tsc --noEmit` clean; full `npm run lint` exit 0. New tests green: 21 unit
+(classification/lints/allowlist/key-lists/purity), 9 probe-track unit (separate track,
+masking regression against the real funnel, inert-lever guard, soaking-silent,
+criticalPath, heartbeat array-guard, per-machine independence, alert rollback), 7
+integration (PIN gate, owner-required, accept clears gap, DELETE-revoke survives reboot),
+3 e2e (feature-alive: six fields + accept route mounted). Existing guard/posture suites
+(monitoring 260, guard integration+e2e 51, server+migrator 27, parity+discoverability 170)
+all pass.
+
+## Post-review fixes (2026-07-02)
+
+- Rebased onto JKHeadley/main after PR #1317 (silent-loss fix) merged. #1317's
+  rejected-enumeration + wiring gate on `routes.ts`/`server.ts`/`types.ts` and G3's
+  additive edits compose cleanly (adjacent, non-overlapping edits; tsc + `npm run lint`
+  clean post-rebase; the guard/posture suite re-run green).
+- CI's full sharded suite caught two mechanical guard-tracking failures the loaded-box
+  local run (exit 144) missed. Neither weakens a guard:
+  1. `no-silent-fallbacks` (492 > baseline 491): `readAcceptedFallbacks`'s
+     missing/corrupt-file catch in `guardAcceptedFallbacks.ts` is annotated
+     `@silent-fallback-ok` — an empty map is the SAFE direction (no phantom accept can
+     suppress a real load-bearing gap). Threshold NOT bumped; count back to 491.
+  2. `feature-delivery-completeness`: the migrator's new `loadBearingGap` content-sniff
+     section is registered in `legacyMigratorSections` (migrator-only behavioral
+     awareness, also emitted inline by `generateClaudeMd` so a fresh init self-matches).

package/upgrades/side-effects/llm-routing-register-uncategorized-components.md

@@ -0,0 +1,100 @@
+# Side-Effects Review — Register 13 uncategorized LLM components
+
+**Version / slug:** `llm-routing-register-uncategorized-components`
+**Date:** `2026-07-01`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds 13 previously-unregistered LLM call-site component names to `COMPONENT_CATEGORY`
+in `src/core/componentCategories.ts`, each tagged `sentinel` / `gate` / `reflector`
+by function, so the framework router resolves them to a real category instead of
+`other` (which falls back to the agent default framework, Claude). Correspondingly
+removes those 13 names from the `WIRING_EXCLUSIONS` pinned backlog in
+`tests/unit/llm-attribution-ratchet.test.ts`, leaving only the 5 components that
+route via an explicit `attribution.category` (so they correctly stay map-unregistered).
+Files touched: `src/core/componentCategories.ts`, `tests/unit/llm-attribution-ratchet.test.ts`.
+The change interacts with one decision point — the router's category resolution
+(`categoryForComponent`) — but only feeds it more data; it adds no branching logic.
+
+## Decision-point inventory
+
+- `categoryForComponent` (src/core/componentCategories.ts) — **pass-through** — unchanged
+  function; this change only adds rows to the map it reads. No control-flow edit.
+- `IntelligenceRouter.resolveFramework` (per-component framework routing) — **pass-through** —
+  consumes the category; unchanged. The 13 components now resolve to their category's
+  configured framework instead of the default, which is the intended effect.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. This is a routing-map data change,
+not a gate. It changes WHICH provider runs a call, never WHETHER the call is allowed.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. The change cannot make any gate
+more permissive; gate *authority* is untouched. (The one `gate`-category addition,
+ResumeValidator, keeps its existing behavior; only its provider changes.)
+
+---
+
+## 3. Wrong-provider / routing correctness
+
+**Could a component now route to a provider that can't serve it correctly?**
+
+Low risk. All 13 join categories (`sentinel`/`gate`/`reflector`) that the
+Provider-Fallback Default Policy already routes off-Claude for dozens of live
+components — the target providers (codex-cli → pi-cli → gemini-cli, Claude last)
+are production-exercised. A rate-limited or missing framework degrades via the
+existing per-framework circuit breaker + fallback chain (unchanged). No component
+routes to a provider class not already in use for its category.
+
+The one behavioral nuance: components that make *nuanced/critical* judgments
+(e.g. LLMConflictResolver resolving divergent multi-machine state) now run on a
+non-Claude reasoning-capable model (gpt-5.5 via codex) rather than Claude. This is
+aligned with the operator directive to prefer subsidized non-Claude subscriptions,
+and gpt-5.5 is reasoning-capable. A later nature-based routing pass (operator-reviewed)
+will refine per-task model tiers; this change does not lock that in.
+
+---
+
+## 4. Reversibility / rollback
+
+Fully reversible: remove the 13 rows from `COMPONENT_CATEGORY` (and restore them to
+`WIRING_EXCLUSIONS`) and routing returns to the prior state. No migration, no state
+schema change, no persisted data. An operator can also override any single component
+per-agent via `sessions.componentFrameworks.overrides` without touching this map.
+
+---
+
+## 5. Blast radius
+
+Fleet-wide once shipped (it's a core map), but strictly additive and category-consistent.
+No new code paths execute; the router simply finds a category where it previously found
+none. Existing tests cover it: the wiring ratchet (`llm-attribution-ratchet.test.ts`)
+proves every live `.evaluate()` component now resolves, `intelligence-router.test.ts` and
+the integration/e2e routing suites remain green. Signal-vs-authority: N/A — no detector
+and no authority is added or modified; this is a data-map completion.
+
+---
+
+## 6. Test coverage
+
+- `tests/unit/llm-attribution-ratchet.test.ts` — the drift guard; asserts every literal
+  `attribution.component` in `src/` resolves to a registered category or a pinned
+  (explicit-category) exception, AND that every pinned exception still resolves to `other`.
+  Both sides green after the change.
+- `tests/unit/intelligence-router.test.ts`, `tests/unit/standards-coverage-component-category.test.ts`,
+  `tests/integration/intelligence-routing-routes.test.ts`,
+  `tests/integration/provider-fallback-default-routing.test.ts` — all green.
+- No NEW test added: the existing ratchet already IS the structural guard for this
+  invariant (adding a duplicate would be noise).