# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: minor -->

## What Changed

**A stored preference that gets violated now becomes a learning signal (dark).** This extends the Correction & Preference Learning Sentinel. A learned preference — for example, "don't defer work to a fresh session" or "never ask the user to edit files" — can now carry an optional self-violation pattern. When the agent emits an outbound message that contradicts such a preference, that is recorded as a self-violation in the correction ledger, which reinforces the preference's recurrence so it surfaces more prominently the next session.

It is signal-only: the detector observes the finalized outbound message and records — it can never block, delay, or rewrite a message. It is fail-open (any detector error silently no-ops and delivery is unaffected) and dark (gated behind both the master correction-learning flag and a new self-violation sub-flag). A preference without a self-violation pattern is never checked, so existing preference files are fully backward compatible.

## What to Tell Your User

The correction-learning system can now notice when the agent's own outgoing message contradicts a preference it has already learned about how you like to work, and quietly use that as a signal to remember the preference more strongly next time. It only ever observes and records — it never blocks, delays, or changes a message — and it stays off until explicitly turned on.

## Summary of New Capabilities

- New `src/monitoring/SelfViolationDetector.ts` — pure, deterministic `detectSelfViolation`; precision-biased (a lone weak keyword never fires), never throws.
- `PreferencesManager` preference records gain an optional `violationPattern` (regex or keyword grammar); fully backward compatible.
- Observe-only outbound hook in `checkOutboundMessage` records self-violations to the `CorrectionLedger`; structurally independent of the tone-gate verdict and of the message itself.
- New `monitoring.correctionLearning.selfViolationSignal` config flag (default false).

## Evidence

- `SelfViolationDetector` unit (17), self-violation wiring-integrity (5, asserts the outbound message passes through byte-for-byte unchanged and the detector fail-opens), integration (5), and E2E lifecycle (3) — all passed.
- `npm run build` / `npm run lint` / `docs-coverage` clean.
