feat(config): governed v8 defaults-flip frame — conservative preset, migration, rollback, inventory (#2504)

docs/architecture.md

@@ -1922,7 +1922,12 @@ Three modes control background-first rollout:
 
 ### Per-Capability Feature Flags
 
-All v6.7 automation features are gated behind explicit feature flags (all default `false`):
+Every automation capability is gated behind its own feature flag, individually
+defaulted: read-only capabilities (`plan_sync`, `evidence_auto_summaries`,
+`decision_drift_detection`) default on; anything that writes or auto-runs
+(`phase_preflight`, `config_doctor_on_startup`, `config_doctor_autofix`)
+defaults off. Governed default changes are inventoried with production
+evidence and per-flip kill switches in `docs/defaults-governance.md` (#2504).
 
 | Feature Flag | Description | Security |
 |--------------|-------------|----------|

docs/configuration.md

@@ -76,6 +76,7 @@ Generated from `PluginConfigSchema` (`src/config/schema.ts`) - do not edit insid
 | --- | ---- | ------- | ----------- |
 | `$schema` | string | — | JSON Schema URL for editor validation/autocomplete of this file (issue #1663). Ignored at runtime; malformed values are ignored too. |
 | `config_format_version` | integer | 1 | Config format version for the migration table. Increment when fields are deprecated. Distinct from knowledge.schema_version. |
+| `preset` | enum(default \| conservative) | — | Defaults profile: "default" applies the governed v8 defaults; "conservative" restores the pre-flip (v7) defaults for every flipped surface (#2504). |
 | `agents` | record<string, object> | — | Per-agent overrides keyed by agent name for the default swarm (e.g. "architect", "coder"). Multi-swarm setups configure agents under swarms.<id>.agents instead. |
 | `default_agent` | string | — | Agent set as the primary mode. Omitted: every generated *_architect is primary. Exact generated name (e.g. "local_architect"): only that agent. Base role name (e.g. "coder"): every generated agent with that base role. Unknown strings warn once and fall back to architect primaries. |
 | `auto_select_architect` | boolean \| string | — | Auto-select the swarm architect for new sessions instead of OpenCode built-ins. Omitted or false: manual selection (omitted behaves as false). true: enable auto-select and disable built-in build/plan agents. "<architect_name>" (e.g. "mega_architect"): enable targeting one architect in multi-swarm setups. |
@@ -369,6 +370,24 @@ Empty or whitespace-only values are treated as omitted.
 
 > Why this matters: in v7.3.x the schema applied an implicit `.default("architect")`. In a multi-swarm config there is no agent literally named `architect` — they are all prefixed — so every architect was demoted to subagent and OpenCode showed only the native `build`/`plan` agents. The omitted-vs-explicit distinction is now load-bearing; do not re-introduce a schema default.
 
+## `preset` — defaults profile for the governed v8 flips (issue #2504)
+
+`preset` (top-level, optional `"default" | "conservative"`) selects the default
+posture for every surface whose default changed under the governed v8
+defaults-flip frame:
+
+| Value | Effect |
+|---|---|
+| _(omitted)_ or `"default"` | The governed v8 defaults apply. Today that means new plans default to parallel-first execution for provably file-disjoint work (since v7.132.0), and `auto_review` flips to advisory-on at the first 8.x release (burn-in pinned; see the `auto_review` section). |
+| `"conservative"` | Restores the pre-flip (v7) defaults for every flipped surface: `auto_review.enabled: false` and serial new plans. |
+
+The preset is applied as the lowest-precedence layer in config resolution, so
+an explicit value for any affected key always wins over it. Evidence
+citations, per-flip kill switches, and rollback for every governed default
+change live in `docs/defaults-governance.md`; `/swarm config doctor` surfaces
+pending default changes and `/swarm config doctor --fix` acknowledges them
+(stamps `config_format_version: 3`).
+
 ## `auto_select_architect` — auto-select swarm architect on launch
 
 `auto_select_architect` (top-level, optional `boolean | string`) controls whether OpenCode's built-in `build` and `plan` agents are disabled so the swarm architect is automatically selected as the active agent on launch.

docs/defaults-governance.md

@@ -0,0 +1,154 @@
+# Defaults Governance — the governed v8 defaults-flip inventory
+
+> Owner: issue #2504 (Workstream F PR 12 of 21), consolidating source EPIC #1677.
+> Frame: every v8 default flip must cite production evidence; migration and
+> rollback are documented and tested; a conservative preset restores the
+> pre-flip (v7) defaults exactly.
+
+This document is the inventory required by #2504: one entry per governed
+default change, each with its evidence citations, one-line kill switch, and
+rollback, plus the dispositions for the three previously-unowned K3 UX
+candidates and the explicitly non-flipped families.
+
+**Release-frame honesty:** the supported-host qualification matrix (#2586) is
+still open. The enabled-feature evidence it has published so far (e.g. the R10
+dispatch-protection integer/wall-clock budgets) was produced on Windows only,
+and its own contract states one platform's fixture does not certify another.
+Nothing in this inventory claims Windows/macOS/Linux or Node/Bun qualification
+beyond what each cited source actually ran. The default-path completion
+evidence from #2585 was produced on a real OpenCode host across three live
+runs; see that issue for scope.
+
+## Flip inventory
+
+### 1. `auto_review.enabled` — FLIPPED (v8 release-gated)
+
+- **v7 default:** `false` (opt-in). **v8 default:** `true` (advisory mode) —
+  resolves automatically on the first 8.x release when the config does not set
+  the key explicitly.
+- **Mechanism:** `AUTO_REVIEW_V8_BURN_IN_DECISION` (approved, pins
+  `docs/benchmarks/auto-review-v8-cost-baseline.json` at SHA-256
+  `b4e981d4…84ce`) + `autoReviewEnabledByRelease` (package major ≥ 8 gate) in
+  `src/config/schema.ts`.
+- **Production evidence:** #2585 live-host proof (PR #2691: three live
+  OpenCode-host runs at one revision with a machine verifier; frozen fixtures
+  at `tests/fixtures/pr-review/frozen-limits.json`); #2586 partial
+  supported-host evidence (Windows-only R10 cells); published quality
+  decisions #2490 (memory-recall regression gate + held-out corpus), #2491
+  (review-routing vocabulary, shipped v7.166.4), #2503 (HarnessOpt capstone
+  manifest contract). Cost baseline:
+  `docs/benchmarks/auto-review-v8-cost-baseline.json` (30 canonical-main
+  diffs; min 1,380 / p50 2,438 / p95 50,480 / max 88,121 input tokens;
+  800-token output budget; `v8_default_per_phase: "1 reviewer + 0
+  validator"`).
+- **Kill switch (one line):** `"auto_review": { "enabled": false }`.
+- **Rollback:** set the kill switch above (explicit user values always win),
+  or set `"preset": "conservative"` to restore every v7 default at once. Whole-
+  config rollback: `/swarm config doctor --fix` backs up to
+  `.swarm/config-backup-<timestamp>.json` and `/swarm config doctor` documents
+  the restore path.
+
+### 2. `execution_profile.parallelization_enabled` (new plans) — FLIPPED (v7.132.0)
+
+- **v7 pre-flip default:** `false` (serial). **Current default:** `true` for
+  NEW plans only (v7.132.0, #1674 via PR #1966), with the delegation gate
+  enforcing serial automatically whenever the pending tasks are not provably
+  file-disjoint. Existing plans are unchanged on upgrade; the plan schema
+  default itself stays `false`.
+- **Production evidence:** #1674 / PR #1966 (`docs/releases/v7.132.0.md`) —
+  gate-enforced serial fallback plus the `plan_conflict_check` advisory tool
+  and durable merge-back recovery shipped in the same release.
+- **Kill switch (one line):** `execution_profile.parallelization_enabled:
+  false` on the plan (per-plan), or `"preset": "conservative"` to make NEW
+  plans serial again.
+- **Rollback:** as above; conservative preset coverage tested in
+  `tests/unit/config/conservative-preset.test.ts`.
+
+## K3 UX candidate dispositions
+
+- **`auto_select_architect` posture (K3 UX-3) — NO schema flip.** F1 (#2493)
+  ships the designed posture: the installer writes `auto_select_architect:
+  true` for FRESH installs only (`src/cli/index.ts`), the schema default stays
+  omitted/`false`, and a one-time advisory fires when a session starts on a
+  non-architect agent. Flipping the schema default would silently disable the
+  host's built-in build/plan agents for every existing user who never set the
+  key — a behavior change with no exit evidence, and against F1's "never fight
+  the user configuration silently" invariant. Disposition: keep the
+  install-layer activation exactly as shipped.
+- **Always-visible startup health banner (K3 UX-6) — DEFERRED, no flip.** No
+  exit evidence exists for an always-visible banner. Recurring cost: every
+  chat-visible line must ride a user-role guidance carrier
+  (`src/hooks/system-guidance-carrier.ts`) because the pinned host discards
+  `role: 'system'` entries in `messages.transform` (AGENTS.md invariant 10),
+  and carrier content is counted against the bounded injection/turn budget
+  (#2107, "Unify context pressure, injection budgets, and summary
+  continuity"). Existing health surfaces (startup config doctor when enabled,
+  model preflight warnings, `/swarm doctor`, the automation-status artifact)
+  remain the supported channels. A future banner needs its own evidence-gated
+  flip entry here.
+- **Free-tier model default resolution against the live catalog (K3 UX-7) — NO
+  default change.** The asked-for behavior already ships: `DEFAULT_MODELS` /
+  `DEFAULT_AGENT_CONFIGS` pin free-tier models with multi-level fallback chains
+  (`src/config/constants.ts`), and `runModelPreflight`
+  (`src/services/model-preflight.ts`) resolves every enabled agent's effective
+  model against the live provider catalog at startup (fail-open) and inside
+  `/swarm doctor`, warning on unresolved selections. There is no proposed
+  model default change to govern.
+
+## Non-goals (not flipped without their own exit evidence)
+
+Per #2504: "Do not default-enable experimental resilience, autonomy, remote
+export, training capture, or sandbox behavior without their own exit
+evidence."
+
+- **Experimental resilience:** `pr_review_resilience.enabled` stays `false`
+  (staged canary/fanout; no exit evidence).
+- **Autonomy:** `full_auto.enabled` stays `false`; `automation.mode` stays
+  `"manual"`.
+- **Remote export:** `observability.export.enabled` stays `false` (local
+  operation is fully independent of the exporter).
+- **Training capture:** consent-gated via `/swarm dataset` commands; no config
+  default to flip.
+- **Sandbox:** `guardrails.sandbox_macos_enabled` stays optional/absent (the
+  SBPL profile is explicitly not re-verified against a real macOS host from
+  this repository's dev environments); sandbox mode stays `advisory`.
+
+### Also not flipped (disqualifying evidence)
+
+- `parallelization.enabled` (config-level): dark foundation — no production
+  code path branches on it yet (`src/config/schema.ts`).
+- `memory.*` / `context_map.enabled`: #2490 shipped a memory-recall regression
+  gate, but its own release (`docs/releases/v7.148.0.md`) records that the
+  graph-memory acceptance criteria were not met — no burn-in evidence to
+  promote (#1677 allows these flips "only if their burn-in evidence is
+  published").
+- `architectural_supervision.enabled`: no published evidence.
+
+## Conservative preset
+
+`"preset": "conservative"` (top-level config key, #2504) restores the pre-flip
+v7 defaults for every flipped surface: `auto_review.enabled: false` and serial
+new plans. It is applied as the lowest-precedence layer in config resolution,
+so an explicit user key always wins over the preset. `"preset": "default"` or
+an absent preset applies the governed v8 defaults. See
+`docs/configuration.md` (`preset`) and `tests/unit/config/conservative-preset.test.ts`.
+
+## Migration, warnings, and acknowledgment
+
+`/swarm config doctor` surfaces pending v8 default changes as `defaults-flip`
+findings (info severity) while `config_format_version < 3`, naming the change,
+the kill switch, and the conservative preset. Running
+`/swarm config doctor --fix` acknowledges them by stamping
+`config_format_version: 3` (idempotent; passive scans never write). The
+Compatibility Matrix (behavior by config vintage and preset) lives in
+`docs/installation.md`.
+
+## Cost-delta statement
+
+At the v8 default posture the advisory auto-review adds one reviewer dispatch
+and no validator per phase (`v8_default_per_phase` in the pinned cost
+baseline: min 1,380 / p50 2,438 / p95 50,480 / max 88,121 input tokens per
+diff, 800-token output budget). Parallel-first new plans run concurrent coders
+only for provably file-disjoint work, bounded by the plan's
+`max_concurrent_tasks`. Users who need the v7 cost profile set
+`"preset": "conservative"`.

docs/design-rationale.md

@@ -26,14 +26,20 @@ Swarm adds the discipline that LLMs lack.
 - Conflict resolution hell
 - Non-reproducible results
 
-**Swarm's approach**: One agent at a time. Always.
+**Swarm's approach**: serial by default — with one governed exception. Since
+v7.132.0 (#1674, PR #1966) new plans default to parallel-first execution for
+PROVABLY file-disjoint task groups only; the delegation gate enforces the
+serial fallback automatically whenever scopes overlap or are unknown. The
+conservative preset (`preset: "conservative"`, #2504) restores fully serial
+new plans. Concurrency is earned by proof, not assumed.
 
 ```
 WRONG:  Agent1 ──┐
         Agent2 ──┼── Merge conflicts, inconsistencies
         Agent3 ──┘
 
 RIGHT:  Agent1 → Agent2 → Agent3 → Consistent result
+        (or: provably file-disjoint agents in parallel, gate-enforced)
 ```
 
 Slower? Yes. Working code? Also yes.
@@ -294,20 +300,23 @@ Architect respects dependencies. Won't start 2.2 until 2.1 is complete.
   "automation": {
     "mode": "manual",  // Default: conservative, full control
     "capabilities": {
-      "plan_sync": false,
+      "plan_sync": true,
       "phase_preflight": false,
       "config_doctor_on_startup": false,
       "config_doctor_autofix": false,
-      "evidence_auto_summaries": false,
-      "decision_drift_detection": false
+      "evidence_auto_summaries": true,
+      "decision_drift_detection": true
     }
   }
 }
 ```
 
+(The `capabilities` values above are the actual schema defaults — read-only
+capabilities default on; anything that writes or auto-runs defaults off.)
+
 **Why this works:**
 - **Progressive rollout:** Start with `manual`, enable features as needed
-- **Explicit opt-in:** Every automation feature has a feature flag (all default false)
+- **Per-capability flags:** every automation capability has its own feature flag, individually defaulted (read-only capabilities default on; anything that writes or auto-runs — `phase_preflight`, `config_doctor_on_startup`, `config_doctor_autofix` — defaults off). Governed default changes are inventoried with evidence and kill switches in `docs/defaults-governance.md` (#2504).
 - **Fail-safe defaults:** Nothing auto-runs unless explicitly enabled
 - **User control:** Architect chooses when to enable automation
 - **Reversible:** Disable mode or specific capabilities anytime

docs/installation.md

@@ -795,10 +795,10 @@ Pick auto once you've tested the individual capabilities and want full throughpu
 
 ### Feature Flag Safety
 
-Every automation capability is default-off:
+Every automation capability has its own feature flag, individually defaulted
+(read-only capabilities on; write/auto-run capabilities off):
 
-- Start with `mode: "manual"` and all capabilities `false`
-- Enable features as you test them
+- Start with `mode: "manual"` and enable capabilities as you test them
 - Never enable everything at once
 - Revert to manual mode if something goes wrong
 
@@ -809,6 +809,23 @@ Every automation capability is default-off:
 - Creates encrypted backups in `.swarm/` before applying fixes
 - Supports restore via `/swarm config doctor --restore <backup-id>`
 
+### Compatibility Matrix
+
+Governed default posture by config vintage and preset (#2504; full inventory
+with evidence citations at `docs/defaults-governance.md`):
+
+| Config | `auto_review` default | New plans | Kill switch / restore |
+|---|---|---|---|
+| v7 config, no preset (7.x releases) | `false` (opt-in) | Parallel-first for provably file-disjoint groups (since v7.132.0), gate-enforced serial fallback | `auto_review.enabled: false`; per-plan `execution_profile.parallelization_enabled: false` |
+| v7 config, no preset (first 8.x release) | `true` (advisory) — flips automatically | Same as above | Same kill switches; `/swarm config doctor --fix` acknowledges and stamps `config_format_version: 3` |
+| `preset: "conservative"` | `false` (v7 posture restored) | Serial (v7 posture restored) | Explicit keys always win over the preset |
+| `preset: "default"` | Same as the no-preset rows | Same as the no-preset rows | Same kill switches |
+| Fresh install | Installer writes `auto_select_architect: true` (first-run activation, #2493); `auto_review` follows the release rows above | Same as no-preset | The schema default for `auto_select_architect` stays off — no silent change for existing users |
+
+Explicit user values always win over both the preset and any flipped default.
+Existing plans are never rewritten on upgrade; only NEW plans pick up the
+parallel-first default.
+
 ### GUI Visibility
 
 When automation is enabled, Swarm writes status to `.swarm/automation-status.json`: