instar 1.3.136 → 1.3.138

package/upgrades/1.3.135.md

@@ -1,53 +1,97 @@
 # Upgrade Guide — vNEXT
 
-<!-- bump: patch -->
+<!-- bump: minor -->
 
 ## What Changed
 
-**Background pollers now back off when the agent is idle — trimming wasted work
-from the always-on CPU floor.**
+**The Correction & Preference Learning Sentinel now has a human read surface — a
+calm "Preferences" dashboard tab — plus the scalability and closed-loop hardening
+that lets it run unattended.** This is Slice 2 of the feature; it still ships dark
+and is still signal-only (it never blocks, rewrites, or delays a message).
 
-Each instar agent runs a couple dozen timer-driven background monitors. On an idle
-agent (no active sessions) most still wake on a fixed cadence and do work — log
-scans, session captures, ledger rollups — for no reason. Across many always-on
-agents on one machine, that fixed-cadence churn is a real slice of baseline CPU.
+The new **Preferences tab** in the dashboard shows, in plain language, the
+preferences the agent has picked up about how you like to work (the same block the
+session-start hook injects on every boot) and the recent corrections it has
+distilled, each with a short scrubbed summary and its status. The exact words you
+used are never stored or shown — only a neutral summary. When the feature is off,
+the tab shows a friendly "not turned on yet" state instead of an error.
 
-This adds a reusable `IdleAwareCadence` primitive: a self-rescheduling timer that
-runs short while active and long while idle, re-checking the idle state on every
-cycle so it snaps back to full speed the moment work resumes. The first poller to
-adopt it is the token-usage scanner (`TokenLedgerPoller`): when no session is
-running there are no new tokens to attribute, so it backs off from every 60s to
-every 5 minutes. The mechanism is built so the other pollers — and, later, a full
-agent-sleep mode — can adopt it incrementally.
+Under the hood, the loop is now bounded so it can run on a schedule without ever
+running away:
 
-This is the first slice of Level 1 (idle footprint) of the Responsible Resource
-Usage standard. (instar can't hibernate the MCP servers Claude Code spawns, so the
-in-scope win is making instar's own pollers cheaper when idle.)
+- The recurrence analyzer routes at most a handful of learnings per run; the rest
+  stay open and route on the next run, so a backlog can never flood the agent in
+  one pass.
+- When auto-feedback is on, infra-gap proposals are sent one at a time with a delay
+  between them and stop on the first rate-limit response, so a converged batch
+  never trips the feedback route's limit or silently drops a learning.
+- The drift canary that watches for changing phrasing gets its own small daily LLM
+  budget, separate from the main one, so it can never starve the main path.
+- The correction ledger gained a composite index backing its restart-proof
+  distinct-calendar-days count.
+- The closed-loop verify step now runs on the infra-gap path too: if the same
+  friction recurs after a feedback proposal it reopens; if it goes quiet, the
+  result is marked inconclusive rather than verified — because an infrastructure
+  fix is the upstream project's to ship, so the agent never claims a result it
+  cannot prove it caused.
+
+The corrections list also gained pagination — a since lower-bound and a keyset
+cursor — so a large ledger can be walked page by page.
 
 ## What to Tell Your User
 
-Nothing to configure. When an agent is just sitting idle, its background checkers
-now run less often instead of waking up on a fast timer for no reason — so each
-agent uses a little less CPU when nothing is happening, and speeds right back up
-the moment you give it work. It is conservative by design: it only changes how
-often these checkers run, never what they do, and if it is ever unsure whether the
-agent is idle it stays on the fast schedule.
+There is a new Preferences tab in your dashboard. It is the calm, plain-language
+place to see what the agent has learned about how you like to work, and the recent
+moments it noticed you correcting it. The exact words you used are never kept —
+only a short, scrubbed summary. It is read-only and never changes or blocks a
+message; these are signals the agent applies by default, and a real instruction or
+a safety rule always wins. The whole feature still ships turned off by default, so
+until someone enables it the tab simply shows a friendly note that it is not turned
+on yet. When the user asks what the agent has learned about them, point them to the
+Preferences tab rather than reading raw output.
 
 ## Summary of New Capabilities
 
-- New `IdleAwareCadence` (`src/monitoring/IdleAwareCadence.ts`) — reusable
-  active/idle self-rescheduling timer; `isIdle()` throw degrades to active;
-  `tick()` throw never breaks the loop; `currentIntervalMs()` for observability.
-- `TokenLedgerPoller` gains optional `isIdle` + `idleIntervalMs` (default 5 min);
-  without them it keeps the prior fixed cadence exactly.
-- `AgentServer` wires the token poller's idle signal to "no running sessions."
+- New dashboard "Preferences" tab (`dashboard/preferences-learning.js` + the tab
+  wiring in `dashboard/index.html`) — the human read surface for learned
+  preferences + scrubbed corrections; pure renderers + a visibility-gated polling
+  controller; textContent-only DOM writes so raw text can never reach the DOM;
+  friendly disabled state in plain prose. Backed by the existing
+  `/preferences/session-context` + `/corrections` endpoints (no new server route).
+- `GET /corrections` pagination — `?since=<ISO>` lower-bound alongside the
+  `?before=<ISO>` keyset cursor and `?limit`.
+- `CorrectionLoopDriver` hardening — a per-tick add ceiling (`maxRoutesPerTick`,
+  default 5) with overflow carried to the next run; batched, rate-limit-aware
+  loopback feedback (`feedbackPostDelayMs`, default 7000; stops on 429, carries
+  the rest); and an infra-gap closed-loop verify (reopen-on-recurrence with the
+  14-day window; silence → inconclusive). `POST /corrections/analyze` now reports
+  `routed.overflow` + `routed.rateLimited`.
+- `CorrectionLedger` composite index `idx_corr_dedupe_day` backing the distinct-
+  calendar-days recurrence count.
+- New config `monitoring.correctionLearning.driftCanaryDailyCents` (5),
+  `maxRoutesPerTick` (5), `feedbackPostDelayMs` (7000) — auto-migrated to existing
+  agents via ConfigDefaults deep-merge. The drift canary gets its own dedicated
+  LlmQueue sub-budget so it cannot starve the main 25-cent distill cap.
 
 ## Evidence
 
-- `tests/unit/IdleAwareCadence.test.ts` — active interval, idle backoff,
-  active→idle re-evaluation, `isIdle`-throw⇒active, `tick`-throw-survives, `stop()`,
-  `currentIntervalMs`.
-- `tests/unit/token-ledger-poller-idle.test.ts` — the poller backs off while idle,
-  runs full cadence while active, and keeps the fixed cadence without `isIdle`.
-- `tests/unit/token-ledger.test.ts` + `TokenLedgerPoller-codex.test.ts` green
-  (backward-compatible). `npm run lint` clean.
+- `tests/unit/CorrectionLoopDriver.test.ts` (15) — per-tick ceiling caps + carries
+  overflow; a second run routes the carried-over overflow; a 429 stops the batch
+  and the remaining infra-gap records stay open; legacy-boolean feedback still
+  honored; infra-gap recurrence → reopened (14-day window); infra-gap silence →
+  inconclusive (never verified).
+- `tests/unit/CorrectionLedger.test.ts` (13) — `idx_corr_dedupe_day` is created and
+  `distinctCounts` still computes correct day counts with the composite index.
+- `tests/unit/preferences-learning-render.test.ts` (20, jsdom) — every renderer +
+  the polling controller against a real DOM; the disabled state; a record carrying
+  an unexpected raw `learning` field is never rendered.
+- `tests/integration/corrections-routes.test.ts` (12) — `?since` lower-bounds
+  detected_at; the `?before` keyset cursor walks the full set without overlap; a
+  malformed `?since`/`?before` is tolerated (never a 500).
+- `tests/e2e/preferences-learning-tab-lifecycle.test.ts` (5) — the tab is alive on
+  the production route path (200 enabled / 503 disabled); the SHIPPED controller
+  renders the learned preference + scrubbed correction from a live server; the raw
+  `learning` text never reaches the DOM; the disabled state shows no config-key
+  string and no monospace element.
+- `node scripts/docs-coverage.mjs --check` — exit 0 (class 55% / route 55% floors
+  held).

package/upgrades/1.3.137.md

@@ -0,0 +1,97 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**The Correction & Preference Learning Sentinel now has a human read surface — a
+calm "Preferences" dashboard tab — plus the scalability and closed-loop hardening
+that lets it run unattended.** This is Slice 2 of the feature; it still ships dark
+and is still signal-only (it never blocks, rewrites, or delays a message).
+
+The new **Preferences tab** in the dashboard shows, in plain language, the
+preferences the agent has picked up about how you like to work (the same block the
+session-start hook injects on every boot) and the recent corrections it has
+distilled, each with a short scrubbed summary and its status. The exact words you
+used are never stored or shown — only a neutral summary. When the feature is off,
+the tab shows a friendly "not turned on yet" state instead of an error.
+
+Under the hood, the loop is now bounded so it can run on a schedule without ever
+running away:
+
+- The recurrence analyzer routes at most a handful of learnings per run; the rest
+  stay open and route on the next run, so a backlog can never flood the agent in
+  one pass.
+- When auto-feedback is on, infra-gap proposals are sent one at a time with a delay
+  between them and stop on the first rate-limit response, so a converged batch
+  never trips the feedback route's limit or silently drops a learning.
+- The drift canary that watches for changing phrasing gets its own small daily LLM
+  budget, separate from the main one, so it can never starve the main path.
+- The correction ledger gained a composite index backing its restart-proof
+  distinct-calendar-days count.
+- The closed-loop verify step now runs on the infra-gap path too: if the same
+  friction recurs after a feedback proposal it reopens; if it goes quiet, the
+  result is marked inconclusive rather than verified — because an infrastructure
+  fix is the upstream project's to ship, so the agent never claims a result it
+  cannot prove it caused.
+
+The corrections list also gained pagination — a since lower-bound and a keyset
+cursor — so a large ledger can be walked page by page.
+
+## What to Tell Your User
+
+There is a new Preferences tab in your dashboard. It is the calm, plain-language
+place to see what the agent has learned about how you like to work, and the recent
+moments it noticed you correcting it. The exact words you used are never kept —
+only a short, scrubbed summary. It is read-only and never changes or blocks a
+message; these are signals the agent applies by default, and a real instruction or
+a safety rule always wins. The whole feature still ships turned off by default, so
+until someone enables it the tab simply shows a friendly note that it is not turned
+on yet. When the user asks what the agent has learned about them, point them to the
+Preferences tab rather than reading raw output.
+
+## Summary of New Capabilities
+
+- New dashboard "Preferences" tab (`dashboard/preferences-learning.js` + the tab
+  wiring in `dashboard/index.html`) — the human read surface for learned
+  preferences + scrubbed corrections; pure renderers + a visibility-gated polling
+  controller; textContent-only DOM writes so raw text can never reach the DOM;
+  friendly disabled state in plain prose. Backed by the existing
+  `/preferences/session-context` + `/corrections` endpoints (no new server route).
+- `GET /corrections` pagination — `?since=<ISO>` lower-bound alongside the
+  `?before=<ISO>` keyset cursor and `?limit`.
+- `CorrectionLoopDriver` hardening — a per-tick add ceiling (`maxRoutesPerTick`,
+  default 5) with overflow carried to the next run; batched, rate-limit-aware
+  loopback feedback (`feedbackPostDelayMs`, default 7000; stops on 429, carries
+  the rest); and an infra-gap closed-loop verify (reopen-on-recurrence with the
+  14-day window; silence → inconclusive). `POST /corrections/analyze` now reports
+  `routed.overflow` + `routed.rateLimited`.
+- `CorrectionLedger` composite index `idx_corr_dedupe_day` backing the distinct-
+  calendar-days recurrence count.
+- New config `monitoring.correctionLearning.driftCanaryDailyCents` (5),
+  `maxRoutesPerTick` (5), `feedbackPostDelayMs` (7000) — auto-migrated to existing
+  agents via ConfigDefaults deep-merge. The drift canary gets its own dedicated
+  LlmQueue sub-budget so it cannot starve the main 25-cent distill cap.
+
+## Evidence
+
+- `tests/unit/CorrectionLoopDriver.test.ts` (15) — per-tick ceiling caps + carries
+  overflow; a second run routes the carried-over overflow; a 429 stops the batch
+  and the remaining infra-gap records stay open; legacy-boolean feedback still
+  honored; infra-gap recurrence → reopened (14-day window); infra-gap silence →
+  inconclusive (never verified).
+- `tests/unit/CorrectionLedger.test.ts` (13) — `idx_corr_dedupe_day` is created and
+  `distinctCounts` still computes correct day counts with the composite index.
+- `tests/unit/preferences-learning-render.test.ts` (20, jsdom) — every renderer +
+  the polling controller against a real DOM; the disabled state; a record carrying
+  an unexpected raw `learning` field is never rendered.
+- `tests/integration/corrections-routes.test.ts` (12) — `?since` lower-bounds
+  detected_at; the `?before` keyset cursor walks the full set without overlap; a
+  malformed `?since`/`?before` is tolerated (never a 500).
+- `tests/e2e/preferences-learning-tab-lifecycle.test.ts` (5) — the tab is alive on
+  the production route path (200 enabled / 503 disabled); the SHIPPED controller
+  renders the learned preference + scrubbed correction from a live server; the raw
+  `learning` text never reaches the DOM; the disabled state shows no config-key
+  string and no monospace element.
+- `node scripts/docs-coverage.mjs --check` — exit 0 (class 55% / route 55% floors
+  held).

package/upgrades/1.3.138.md

@@ -0,0 +1,58 @@
+---
+review-convergence: complete
+approved: true
+approved-by: echo (standing 12h deploy mandate, topic 13435; Justin directive to track all codex onboarding issues for next-framework onboarding)
+---
+
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed — a durable write path for the framework-onboarding issue ledger
+
+The Framework-Onboarding Mentor System keeps a bucket-tagged ledger of issues found while
+onboarding a non-Claude agent framework (Codex now; Cursor/Aider/Gemini next). Until now it
+was fed by ONE source — the automated mentor tick's own forensics — so issues discovered the
+other way (an engineer auditing and fixing the code) never reached it. The generalizable
+buckets that feed the next-framework playbook stayed empty of exactly the deepest lessons.
+
+This adds `POST /framework-issues/observe` — a small authenticated write path over the
+ledger's already-validated `recordObservation` (+ an optional status transition, so an
+already-fixed issue can be backfilled in one call). New framework strings are intentionally
+allowed (onboarding the next framework introduces one); the write is idempotent on `dedupKey`.
+A reusable importer script (`scripts/framework-issue-backfill/`) bulk-loads a findings JSON.
+
+## Summary of New Capabilities
+
+- `POST /framework-issues/observe` records an engineering-discovered framework issue:
+  `{ framework, bucket, severity?, title, dedupKey, evidence?, observedVersion?, status?,
+  fixedInVersion?, wontFixReason?, bucketPrimary?, signature?, relatedSpec? }`. bucket /
+  severity / status enums are validated by the ledger (400 on bad input). Idempotent on
+  `dedupKey`. Returns `{ issueId, created, recurrenceCount, issue }`.
+- The two generalizable buckets (`framework-limitation`, `instar-integration-gap`) feed the
+  existing `/framework-issues/playbook?targetFramework=X` for the next framework onboarded.
+- Agents learn the write path via CLAUDE.md (template registry row + migrator section), with a
+  proactive trigger: log a framework-compat issue the moment you fix or won't-fix it.
+
+## What to Tell Your User
+
+When you are onboarding a non-Claude agent and you find a compatibility issue by fixing the
+code, you can now record it in the durable onboarding ledger, not just the ones the automated
+mentor loop happens to trip over. Those records carry forward as a playbook for the next
+framework you bring onto Instar. Nothing to configure.
+
+## Evidence
+
+- New route in src/server/routes.ts (thin wrapper over the existing recordObservation +
+  updateIssue; both already enum-validate and throw, surfaced as HTTP 400).
+- Tier-2 integration: tests/integration/framework-issues-routes.test.ts — records a new issue,
+  backfills an already-fixed issue in one call, idempotent re-record, allows a new framework
+  string, 400 on missing field / invalid bucket / wont-fix-without-reason (23 tests pass).
+- Tier-3 E2E: tests/e2e/framework-issue-ledger-lifecycle.test.ts — the write route is alive on
+  the production init path (POST returns 200 not 503; the finding surfaces through the live GET).
+- Agent Awareness + Migration Parity: templates.ts registry row + a content-sniffed,
+  idempotent migrateClaudeMd paragraph for existing agents (feature-delivery-completeness
+  allowlist updated; 235 PostUpdateMigrator tests pass).
+- tsc --noEmit clean; npm run lint clean.
+- Spec: docs/specs/framework-issue-observe-write-path.md (+ .eli16.md).
+- Side-effects: upgrades/side-effects/framework-issue-observe-write-path.md.

package/upgrades/side-effects/correction-preference-learning-sentinel-slice2.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Correction & Preference Learning Sentinel, Slice 2
+
+**Version / slug:** `correction-preference-learning-sentinel-slice2`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (signal-only, ships dark; read-only dashboard surface; see §7)
+
+## Summary of the change
+
+Slice 2 adds the human read surface and the scalability/closed-loop hardening on top of the shipped Slice 1a/1b loop:
+
+- **Dashboard "Preferences" tab** — a calm, plain-language read-only surface (`dashboard/preferences-learning.js` + tab wiring in `dashboard/index.html`) mirroring the Process Health tab precedent. It shows the active learned preferences (from `/preferences/session-context`) and the recent scrubbed corrections (from `/corrections`). No new server route — it consumes the two existing Slice-1a/1b endpoints.
+- **`/corrections` `?since` pagination** — a lower-bound (`detected_at >= since`) alongside the existing `?before` keyset cursor + `?limit`.
+- **`CorrectionLoopDriver` hardening** — a per-tick add ceiling (`maxRoutesPerTick`, default 5; overflow stays `open`, re-routes next run), batched + rate-limit-aware loopback feedback (`feedbackPostDelayMs`, default 7000; stops on the first 429 and carries the rest), and the infra-gap closed-loop verify (reopen-on-recurrence with the 14-day window; silence → inconclusive, never verified).
+- **`CorrectionLedger` composite index** `idx_corr_dedupe_day` backing the distinct-calendar-days recurrence count.
+- **Drift-canary sub-budget** — a dedicated `LlmQueue` instance with its own small daily cap (`driftCanaryDailyCents`, default 5) so the canary can never starve the main 25¢ distill cap.
+
+The loop is still **SIGNAL-ONLY** (it never blocks or rewrites an outbound message) and still ships **dark** behind `monitoring.correctionLearning.enabled`. The new dashboard tab is read-only.
+
+**Files touched:**
+- `dashboard/preferences-learning.js` (new — pure renderers + polling controller), `dashboard/index.html` (tab button + panel + registry entry + lazy-load wiring).
+- `src/monitoring/CorrectionLedger.ts` (composite index + `listOccurrenceIndexes()`), `src/monitoring/CorrectionLoopDriver.ts` (per-tick ceiling, batched/429-retry, infra-gap verify + audit).
+- `src/server/routes.ts` (`?since`; structured `feedbackLoopbackPost`; `maxRoutesPerTick`/`feedbackPostDelayMs`/audit wiring; `routed.overflow`/`rateLimited` response), `src/commands/server.ts` (drift-canary sub-budget LlmQueue).
+- `src/core/types.ts` + `src/config/ConfigDefaults.ts` (`driftCanaryDailyCents`, `maxRoutesPerTick`, `feedbackPostDelayMs` + defaults).
+- `src/server/CapabilityIndex.ts` (`?since` + dashboard tab), `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` (dashboard tab awareness + idempotent backfill), `src/data/builtin-manifest.json` (regenerated by build).
+- `site/src/content/docs/features/correction-preference-learning.md` (Preferences tab + API + Scalability bounds + infra-gap verify).
+- `tests/unit/CorrectionLedger.test.ts`, `tests/unit/CorrectionLoopDriver.test.ts`, `tests/unit/preferences-learning-render.test.ts` (new), `tests/integration/corrections-routes.test.ts`, `tests/e2e/preferences-learning-tab-lifecycle.test.ts` (new).
+- `upgrades/NEXT.md`, this side-effects artifact.
+
+## Decision-point inventory
+
+- **Dashboard tab** — *read-only render*. Pure data→DOM with `sanitizeForDisplay` + textContent-only writes. No authority; cannot mutate anything.
+- **Per-tick add ceiling** — *bounded throughput, code-determined*. Caps routed records/run; overflow stays `open` and re-routes next run. Cannot drop a learning.
+- **429-retry batch control** — *carry, not drop*. A rate-limited feedback POST leaves the record `open` for the next run. Cannot silently lose a learning.
+- **Drift-canary sub-budget** — *resource isolation*. A separate `LlmQueue` instance; cannot affect routing or authority.
+- **Infra-gap verify verdict** — *signal*. Silence → `inconclusive` (never a self-attributed "verified"); recurrence → reopen (capped). No authority change.
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The dashboard tab is read-only; the driver still never blocks a message, tool call, or user. The per-tick ceiling bounds throughput but never blocks a learning — overflow is carried, not dropped.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The closest analog is a learning deferred to the next run by the per-tick ceiling or a 429; in both cases the record stays `open` and re-routes — it is delayed, never lost, never an unsafe action.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The dashboard tab is a self-contained browser-native ESM module + index.html wiring, mirroring the Process Health tab precedent exactly (lazy dynamic-import, registry entry with onActivate/onDeactivate, reused `ph-*` calm-type CSS, `sanitizeForDisplay` + textContent-only safety). The driver/ledger/config changes sit in the same `src/monitoring/` + `src/config/` modules as the rest of the loop. No new server route was added — the tab consumes the existing Slice-1a/1b endpoints (the discoverability-lint allowlist is unchanged).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] **No — every output is a signal consumed by an existing smart gate or a human, or a read-only render.** The dashboard tab is read-only. The driver's authority surface is unchanged from Slice 1b: `CorrectionLoopDeps` still carries exactly `addAction`, `createInitiative`, `feedbackLoopbackPost`, `recordPreference`, `attentionRoute` — Slice 2 adds only bounding parameters (`maxRoutesPerTick`, `feedbackPostDelayMs`, `sleep`, `audit`) and a richer return type on `feedbackLoopbackPost` (`{posted, rateLimited}`), none of which add a mutation capability. The existing by-construction authority test still holds (no proposal-mint, no memory-write field). The infra-gap verify verdict is signal-only and deliberately refuses to self-attribute a "verified" the agent cannot prove.
+
+## 5. Interactions
+
+- **Shadowing:** the dashboard tab registry entry chains after Process Health; it has its own panel ids (`pl*`) so it cannot shadow the Process Health tab (`ph*`). The lazy-load controller is independent.
+- **Double-fire:** the per-tick ceiling + the analyzer's `status:'open'` filter mean a record routes once; a record left as overflow stays `open` and is re-evaluated next run (idempotent — the second-run test pins it routes the carried-over overflow exactly once). The 429 path leaves the record `open` (never marked `acted-on`), so it re-routes next run without duplicating.
+- **Races:** the driver is single-threaded per `route()` call. The composite index does not change `distinctCounts` results (a test pins identical day counts) — it only speeds the query. The drift-canary `LlmQueue` is a separate instance; it cannot race the main distill queue's cap.
+- **Feedback loops:** the batched feedback POSTs serialize with a delay and stop on the first 429, so the loop cannot hammer its own `/feedback` route. The dashboard tab polls read-only (`/preferences/session-context` + `/corrections`) on a 60s cadence, visibility-gated and abort-safe — it cannot re-enter the capture path.
+- **Startup ordering:** the drift-canary sub-budget LlmQueue is constructed inside the existing capture-loop boot block, only when `driftCanary` is on (it ships dark, so normally null). The dashboard files ship with the package and are served by `express.static` — no boot wiring.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none. No change to the cross-agent (Rising Tide) path beyond the batched/429 serialization, which only makes the agent a politer client of its own `/feedback` route.
+- **Other users of the install base:** purely additive and dark. Existing agents that don't flip `monitoring.correctionLearning.enabled` see byte-identical behavior. The new config keys (`driftCanaryDailyCents`, `maxRoutesPerTick`, `feedbackPostDelayMs`) backfill via ConfigDefaults deep-merge with safe defaults. The dashboard tab appears on the next update (package-served) but renders the friendly disabled state until the flag is on.
+- **External systems:** the drift-canary sub-budget provisions an additional small daily LLM spend cap (default 5¢, only when the canary is enabled — dark by default). No new egress beyond what Slice 1b disclosed; the canary is not yet wired to fire (its budget is provisioned ahead of the sampler).
+- **Persistent state:** new composite index in the existing `correction-ledger.db` (no new file; created idempotently via `CREATE INDEX IF NOT EXISTS`). The driver's audit hook appends route/verify decisions to the existing `<stateDir>/logs/correction-learning-audit.jsonl` (metadata only, `origin: correction-loop`). No new persistent state.
+- **Timing:** the per-tick ceiling and the inter-POST delay are bounded and only apply during the off-hot-path weekly analyzer run. The dashboard polling is read-only and visibility-gated.
+
+## 7. Rollback cost
+
+- **Code:** flip `monitoring.correctionLearning.enabled` back to false (or revert the commits). With the flag off, the `/corrections` + `/preferences/session-context` routes 503, the dashboard tab renders the disabled state, and the driver is not wired.
+- **Persistent state:** the composite index is harmless when the feature is off (read by nothing). The audit JSONL stays on disk, read by nothing. No new state file to remove.
+- **Dashboard:** the tab is package-served; reverting the `dashboard/` changes removes it. There is no per-agent dashboard migration to undo.
+- **Agent state repair:** none required.
+- **User visibility during rollback:** none — the feature is dark by default and the tab shows the disabled state.
+
+Total rollback time: under 1 minute (flip one config flag, or revert the commits).
+
+## Conclusion
+
+Read-only dashboard surface + bounding parameters + an index + a sub-budget — no new blocking authority, no new mutation capability, no new egress beyond the (dark) canary budget. The per-tick ceiling and 429-retry carry learnings rather than dropping them; the infra-gap verify refuses to self-attribute a "verified". The dashboard tab mirrors the established Process Health precedent (sanitize + textContent-only) so raw text can never reach the DOM. Signal-only, dark-by-default, and fully bounded.

package/upgrades/side-effects/framework-issue-observe-write-path.md

@@ -0,0 +1,44 @@
+# Side-effects artifact — framework-issue ledger write path (POST /framework-issues/observe)
+
+## 1. What files/state does this change touch at runtime?
+Only the existing `framework-issue-ledger.db` SQLite file (under `<stateDir>/server-data/`),
+via the ledger's existing `recordObservation` + `updateIssue` methods (WAL, busy_timeout
+already configured). No new files, tables, or schema. No config keys added.
+
+## 2. Does it gate, block, or constrain any agent/session/message?
+No. The ledger is observability-only and this is a write surface for it. It never gates a
+job, blocks a message, kills a session, or influences any decision path. Purely additive
+record-keeping.
+
+## 3. What happens on bad/malicious input?
+Required fields missing → 400. Invalid bucket/severity/status enum → the ledger's
+`assertEnum` throws → 400. `status:'wont-fix'` without a reason → ledger throws (§13.7) → 400.
+Free-text fields are length-bounded + secret-scanned by the ledger's existing
+`sanitizeFreeText`/`scanForSecret` (unchanged). No SQL injection surface (parameterized
+statements inside the ledger). Bearer-auth required (same middleware as all non-/health routes).
+
+## 4. Migration parity — do existing agents get it?
+The route ships in code (no migration needed for the endpoint itself — it rides the existing
+`ctx.frameworkIssueLedger` wiring that GET routes already use). Agent awareness IS migrated:
+templates.ts registry row (new agents) + an idempotent, content-sniffed migrateClaudeMd
+paragraph (existing agents) guarded on `framework-issues/observe`. Re-running the migration is
+safe (content-sniff). The feature-delivery-completeness allowlist was updated so CI tracks it.
+
+## 5. Could it spam / flood / burn resources?
+No. A write is one SQLite upsert. There is no loop, no polling, no LLM call, no message send,
+no spawn. Idempotent on dedupKey, so repeated imports collapse. No notification is emitted.
+
+## 6. Rollback / off-switch?
+The route is dormant when the ledger is unavailable (returns 503 — same as the GET routes).
+Reverting the PR removes the route with zero residual state (any recorded rows remain valid
+ledger data and are harmless; they can be left or pruned). No flags, no dark-launch needed —
+the surface is inert until called.
+
+## 7. Concurrency / multi-process safety?
+The ledger uses WAL + busy_timeout=5000 (existing). The server is the in-process writer; the
+backfill importer writes THROUGH the server's HTTP route (not a second DB handle), so there is
+a single writer. The one-shot importer is run manually, not on a schedule. No new concurrency.
+
+## Blast radius
+Minimal. New additive HTTP route + one CLAUDE.md awareness paragraph + a one-shot importer
+script + tests. No change to any existing route, gate, sentinel, schema, or decision path.