instar 1.3.705 → 1.3.706

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/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).