# Upgrade Guide — vNEXT

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

## What Changed

Retired the catch-all `deliberate-fleet-default` category from the dev-feature
dark-gate classification and added a concrete `action-bearing` category. Every
"off even on a development agent" feature must now name a real reason it would be
unsafe or non-runnable there — it kills/deletes, spends money, takes an external
action, or needs per-deployment config — and the vague "off by policy" bucket is
gone. The CI lint (`scripts/lint-dev-agent-dark-gate.js`) rejects the retired
category and now fails loud if an exclusion entry escapes category validation (the
backtick-reason silent-skip hole), via a count-match guard in
`scripts/lib/dark-gate-attribution.js`.

Reclassified the 11 features that were in the retired bucket. Each candidate for
going live on a development agent was re-grounded against its actual code (D4): 4
verified safe and moved to `DEV_GATED_FEATURES` (`parallelWorkSentinel`,
`failureLearning`, `releaseReadiness`, `bootHealthBeacon`) — their `enabled` flag
is now omitted from `ConfigDefaults` so the developmentAgent gate resolves them
live-on-dev / dark-on-fleet, and their construction sites route through
`resolveDevAgentGate`. The other 3 candidates were held back as honest exclusions
because their code contradicted "observe-only": `correctionLearning` (cost-bearing
— per-message LLM spend), `apprenticeshipCycleSla` and `geminiCapacityEscalation`
(action-bearing — auto-post Telegram alerts). `greenPrAutoMerge` + `a2aCheckIn` are
recategorized action-bearing; `mentor` + `mentee` optional-integration.

Added a one-shot, dev-agent-only `PostUpdateMigrator.migrateDevGateTeethStrip` that
strips a stale persisted `enabled: false` for the 4 newly-dev-gated flags so an
existing development agent actually picks up the change (without it the add-missing
config merge would leave the stale value and the features would stay dark — the
cartographer trap).

## What to Tell Your User

Nothing changes for you on a normal install — every one of these features stays off
until you turn it on, exactly as before. On a development agent (the dogfooding
machine), four watch-only helpers now switch on automatically after the update: a
parallel-work overlap watcher, a failure-learning recorder, a release-readiness
watcher, and a boot health responder. They only observe and record — none of them
sends you a message, spends money, or changes anything. Three other helpers that
were candidates to turn on were deliberately kept off because they would have spent
money or sent you alerts; you can still switch any of those on yourself if you want
them.

## Summary of New Capabilities

- A development agent now runs four verified watch-only observers live (parallel-work
  overlap, failure-learning, release-readiness, boot health) so they get dogfooded
  before the fleet ever sees them.
- The dark-feature classification now requires a concrete, honest reason for any
  feature parked "off even on dev" — enforced in CI — so a safe feature can no longer
  be hidden behind a vague "off by policy" label.

## Evidence

- Spec + 6-round convergence report with a real cross-model (GPT-tier) external pass:
  `docs/specs/DEV-AGENT-DARK-GATE-TEETH-SPEC.md`,
  `docs/specs/reports/dev-agent-dark-gate-teeth-convergence.md`.
- Tests (all green): `tests/unit/lint-dev-agent-dark-gate.test.ts` (retired category
  rejected, `action-bearing` accepted, count-match guard, hand-verified drift canary),
  `tests/unit/devGatedFeatures-wiring.test.ts` (the 4 new entries resolve live-on-dev /
  dark-on-fleet through the real `ConfigDefaults`),
  `tests/unit/PostUpdateMigrator-devGateTeethStrip.test.ts` (migration both sides +
  idempotency + the 3 held untouched), `tests/integration/dev-gate-teeth-rollout.test.ts`
  (full migration → defaults → resolver pipeline + the two-switch drift guard).
- D4 code-grounding evidence (file:line per feature) is recorded in the spec's
  "D4 grounding result" section.
