release(flow): v3.25.1 — adoption-hop baseline merge-preserve

Hotfix: the v3.25.0 U3/W2 module-size-baseline.txt + policy-state
merge-preserve now runs on the FIRST upgrade adopting v3.25.x.

Post-ship Codex adversarial review found the merge was skipped on the
adoption hop: upgrade.sh sourced the merge lib from the local
(pre-upgrade) tree before hooks/ refresh, and bootstrap-upgrade.sh
didn't stage hooks/local/lib/ -> the new merge code wasn't on disk when
the merge had to run -> project baseline rows clobbered on adoption.

Fix (49f335c/b562166/5324358/28fe2ea, bundled with this release commit):
- P1 bootstrap-upgrade.sh stages hooks/local/lib/ before handoff
- P2 upgrade.sh sources merge lib from authoritative target tree
  ($SOURCE_CLONE) + local fallback + re-source before Step 1a + loud
  no-skip warning
- P3 README routes pre-v3.25 installs through bootstrap-upgrade.sh
- P4 RED-then-GREEN adoption-hop integration test (13 cases) in run-tests

LOCKED merge rule unchanged (only how/when the lib is sourced). FR-07
clean: no FR rows / deploy-policy semantics / ratchet-governance.yml.
ACCEPTED-RISK: old installed upgrade.sh run directly can't run
target-version merge code; mitigated by bootstrap routing.

Verified: preflight 0/0; run-tests 92/92; check-module-size --all 0;
mirror 0 drift; recovery-sim 31/31 (state/audit/recovery-sim-v3.25.1-2026-06-15.log);
plugin==VERSION==3.25.1; GEMINI synced. Credit: post-ship Codex review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Pavel Sher

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "fusebase-flow",
   "description": "The framework client-facing teams use to build internal and client apps with AI. Two agents (Product Owner + AI Developer) run a disciplined spec-to-deploy lifecycle, packaged with FuseBase Apps domain skills. Closes the gaps that break real AI app development: drift, context rot, scope creep, unreliable hand-offs.",
-  "version": "3.25.0",
+  "version": "3.25.1",
   "author": {
     "name": "FuseBase (Nimbus Web Inc.)"
   },

.claude/agents/ai-developer.md

@@ -12,9 +12,9 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 Choose the role from the handoff filename:
 
-> **AI Developer:** "Operating as AI Developer under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for AI Developer."
+> **AI Developer:** "Operating as AI Developer under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for AI Developer."
 
-> **Deploy phase:** "Operating as Deploy phase under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Deploy phase."
+> **Deploy phase:** "Operating as Deploy phase under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Deploy phase."
 
 **Lightweight lane (FR-21).** When the handoff is a **change-note** (or an implement handoff marked `change_tier: lightweight`), attest as AI Developer and add: "Running the Lightweight Lane (FR-21): one change-note, one build→verify→deploy pass, plain operator go-ahead; safety floor (live proof, explicit go-ahead, FR-07, rollback, one commit) kept; I will STOP and promote to Full if this turns non-trivial." Then follow `workflows/lightweight-lane.md` — no stop-at-gate handoff to a second session, deploy on a plain go-ahead (no DP.6 / DP.1). See `flow-skills/lightweight-lane/SKILL.md`.
 

.claude/agents/product-owner.md

@@ -10,7 +10,7 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 ## Self-attestation (first response of every invocation)
 
-> "Operating as Product Owner under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Product Owner, and additionally the Architect (escalation) section when this ticket triggers escalation criteria."
+> "Operating as Product Owner under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Product Owner, and additionally the Architect (escalation) section when this ticket triggers escalation criteria."
 
 ## State announcement (every output)
 

.codex/agents/ai-developer.md

@@ -12,9 +12,9 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 Choose the role from the handoff filename:
 
-> **AI Developer:** "Operating as AI Developer under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for AI Developer."
+> **AI Developer:** "Operating as AI Developer under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for AI Developer."
 
-> **Deploy phase:** "Operating as Deploy phase under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Deploy phase."
+> **Deploy phase:** "Operating as Deploy phase under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Deploy phase."
 
 **Lightweight lane (FR-21).** When the handoff is a **change-note** (or an implement handoff marked `change_tier: lightweight`), attest as AI Developer and add: "Running the Lightweight Lane (FR-21): one change-note, one build→verify→deploy pass, plain operator go-ahead; safety floor (live proof, explicit go-ahead, FR-07, rollback, one commit) kept; I will STOP and promote to Full if this turns non-trivial." Then follow `workflows/lightweight-lane.md` — no stop-at-gate handoff to a second session, deploy on a plain go-ahead (no DP.6 / DP.1). See `flow-skills/lightweight-lane/SKILL.md`.
 

.codex/agents/product-owner.md

@@ -10,7 +10,7 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 ## Self-attestation (first response of every invocation)
 
-> "Operating as Product Owner under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Product Owner, and additionally the Architect (escalation) section when this ticket triggers escalation criteria."
+> "Operating as Product Owner under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for Product Owner, and additionally the Architect (escalation) section when this ticket triggers escalation criteria."
 
 ## State announcement (every output)
 

.cursor/rules/fusebase-flow-always.mdc

@@ -10,7 +10,7 @@ Read `FLOW_RULES.md` (stop at `## Amendment log` — dated history, never load i
 
 ## Self-attestation (first response of every session)
 
-State: "Operating as {Product Owner | AI Developer | Architect (escalated) | Deploy phase} under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
+State: "Operating as {Product Owner | AI Developer | Architect (escalated) | Deploy phase} under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
 
 ## State announcement (every output)
 

.github/copilot-instructions.md

@@ -1,13 +1,13 @@
 # GitHub Copilot / VS Code — Fusebase Flow repository instructions
 
-This repo runs **Fusebase Flow v3.25.0**. Read these files before any other action:
+This repo runs **Fusebase Flow v3.25.1**. Read these files before any other action:
 
 - `AGENTS.md` — portable always-on baseline (rules vs skills vs workflows vs hooks vs policies)
 - `FLOW_RULES.md` — full always-on rules (FR-01..FR-26) with enforcement-surface map (stop at `## Amendment log` — dated history, never load it)
 
 ## Self-attestation (first response of every session)
 
-> "Operating as {Product Owner | AI Developer | Architect (escalation) | Deploy phase} under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
+> "Operating as {Product Owner | AI Developer | Architect (escalation) | Deploy phase} under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
 
 ## State announcement (every output)
 

AGENTS.md

@@ -157,7 +157,7 @@ Fusebase Flow ships:
 
 **Self-attestation (every session's first response):**
 
-> "Operating as {role} under Fusebase Flow v3.25.0. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
+> "Operating as {role} under Fusebase Flow v3.25.1. I will follow FR-01 through FR-26. I will apply Mode A on chat output and Mode B on every internal-artifact write. I will apply the role-discipline skill section for {role}."
 
 **Operator questions:** per FR-19, ask questions in chat text, not popup / clickable menu tools. Use short option tables or numbered lists so the operator can copy, forward, quote, and follow up.
 

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to Fusebase Flow. Format follows [Keep a Changelog](https://
 
 Public release versions ship as annotated git tags on `main`. Per-version detail lives in `docs/release-notes/v<version>.md`.
 
+## [3.25.1] — 2026-06-15
+
+### Fixed — adoption-hop baseline merge-preserve (the v3.25.0 U3/W2 merge now runs on the FIRST upgrade adopting v3.25.x)
+
+**Hotfix.** v3.25.0 shipped the U3/W2 `module-size-baseline.txt` + policy-state **merge-preserve** rule, but a **post-ship Codex adversarial review** found it was **skipped on the adoption hop** — the first upgrade that brings a project onto v3.25.x. Root cause: `upgrade.sh` sourced the merge lib from the **local** (pre-upgrade) tree before `hooks/` was refreshed, and `bootstrap-upgrade.sh` didn't stage `hooks/local/lib/`, so the new merge code wasn't on disk when the merge had to run → a project's own baseline rows were **clobbered on adoption**. Bounded to **how/when the lib is sourced** + bootstrap staging + routing docs + a new test; **the LOCKED merge rule itself is unchanged**.
+
+- **P1 — `bootstrap-upgrade.sh` stages `hooks/local/lib/`** so the new `upgrade.sh` finds its merge code before handoff. (`49f335c`)
+- **P2 — `upgrade.sh` sources the merge lib from the authoritative target tree** (`$SOURCE_CLONE/hooks/local/lib/`) with a local fallback, **re-sources before Step 1a**, and prints a **loud no-skip warning** if the lib can't load — a silent skip can never recur. (`b562166`)
+- **P3 — README routing:** pre-v3.25 installs go through `bootstrap-upgrade.sh` for the v3.25.x hop (the merge ships in the target version; a clobbered baseline is recoverable from the `.pre-upgrade` backup). (`5324358`)
+- **P4 — RED-then-GREEN adoption-hop integration test** `hooks/tests/test-bootstrap-baseline-hop.sh` (13 cases) wired into `run-tests`: pre-fix engine loses the row (RED), fixed engine preserves it (GREEN) + P1 staging preconditions. (`28fe2ea`)
+- **ACCEPTED-RISK:** an old already-installed `upgrade.sh` run directly (not via bootstrap) still can't run the target-version merge code; mitigated by the P3 bootstrap routing. Only residual Codex flagged.
+
+Verified: preflight 0/0 · run-tests **92/92 PASS** (79 + 13 new adoption-hop) · `check-module-size --all` exit 0 · mirror 31 skills / 0 drift (byte-identical) · sync `--dry-run` framework-scoped (consumer excluded) · plugin == VERSION == 3.25.1 · GEMINI synced v3.25.1 · **recovery-sim 31/31 exit 0** · FR-07 clean (version-string sweep only; LOCKED merge rule untouched — only lib sourcing). Credit: post-ship Codex adversarial review. Spec: `docs/specs/upgrade-baseline-bootstrap-hop/spec.md`. Detail: `docs/release-notes/v3.25.1.md`.
+
 ## [3.25.0] — 2026-06-15
 
 ### Changed — upgrade-tooling hardening (Windows perf, baseline/policy merge-preserve, sync allowlist, GEMINI sync, PARTIAL_UPGRADE)

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md - Claude Code adapter for Fusebase Flow
 
-This repo runs **Fusebase Flow v3.25.0**. The portable always-on baseline is in `AGENTS.md`. The full rule set is in `FLOW_RULES.md`. Read both before any other action (stop `FLOW_RULES.md` at `## Amendment log` — dated history, never load it).
+This repo runs **Fusebase Flow v3.25.1**. The portable always-on baseline is in `AGENTS.md`. The full rule set is in `FLOW_RULES.md`. Read both before any other action (stop `FLOW_RULES.md` at `## Amendment log` — dated history, never load it).
 
 ## Claude Code-specific notes