docs(upgrade-tooling-hardening): flip spec DONE + deploy hash 6a8961f; record task SHAs; file U6 follow-up backlog (v3.25.0)

- spec.md DRAFT->DONE, deploy hash 6a8961f, tag v3.25.0
- task SHAs Ua..Uf + Ua-fix + Ug remediation recorded
- new backlog ticket docs/backlog/adapter-overlay-refresh-parity (U6 overlay-refresh parity follow-up)
- backlog index: upgrade-tooling-hardening done (v3.25.0) + adapter-overlay-refresh-parity parked

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

Author: Pavel Sher

docs/backlog/adapter-overlay-refresh-parity/README.md

@@ -0,0 +1,33 @@
+# Backlog ticket — adapter-overlay-refresh-parity
+
+**Status:** parked (filed 2026-06-15 as the U6 follow-up deferred from `upgrade-tooling-hardening`, shipped v3.25.0)
+**Source friction:** TWO independent consumer upgrade reports (paperclip+hermes-v1 I5, WorkHub Managed W3) — `v3.21.1 → v3.23.1` on Windows/Git-Bash.
+**Predecessor:** `docs/specs/upgrade-tooling-hardening/spec.md` (v3.25.0). That release shipped U5 (the GEMINI **version-string** regex fix — un-stuck the `Fusebase Flow Local v2.1` drift) but **deferred U6**: a full marker-anchored **overlay-refresh** path for the secondary adapters, because it needs a marker-strategy design of its own (per the Codex RESCOPE verdict).
+
+## Pain
+
+`AGENTS.md` and `CLAUDE.md` get a **marker-anchored overlay refresh** on upgrade (the `FLOW:PRESERVE` blocks survive, project rules are preserved, only the Flow-owned overlay region is rewritten). The secondary adapters — **`GEMINI.md`, `.github/copilot-instructions.md`, `.cursor/rules/*.mdc`** — have **no equivalent refresh path**:
+
+- They only receive the **version-string sweep** (U5), not a content overlay refresh. So when the Flow overlay content evolves (new FR rows, new skills, changed attestation, new state-announcement format), these adapters silently fall behind the canonical AGENTS/CLAUDE overlay.
+- This is exactly how GEMINI drifted to a stale header in the first place — version-only sync masks deeper content drift. Fixing the version string (U5) does not fix the missing-overlay-region problem.
+- A consumer who relies on Gemini/Antigravity, Copilot, or Cursor as their primary surface gets a progressively staler Flow overlay with each upgrade, with no signal.
+
+## Why it was deferred (not folded into v3.25.0)
+
+Unlike AGENTS/CLAUDE (which already carry begin/end overlay markers), the secondary adapters have **no marker convention**. Designing one requires deciding, per adapter:
+- where the Flow-owned region begins/ends without clobbering IDE-specific or project-specific content,
+- how `FLOW:PRESERVE`-equivalent project carve-outs work in each file format (`.md`, `.mdc`, copilot-instructions),
+- how the refresh interacts with the U4 sync allowlist and the health-check `PARTIAL_UPGRADE` derived-fact comparison (so a stale secondary adapter becomes a *detectable* fact, not silent drift).
+
+## Rough acceptance (to be specified)
+
+- A **marker-anchored overlay-refresh path** for GEMINI / copilot / cursor adapters, parallel to AGENTS/CLAUDE: rewrites only the Flow-owned overlay region, preserves project + IDE-specific content (a `FLOW:PRESERVE`-equivalent).
+- `upgrade.sh` / `post-fusebase-update.sh --refresh-overlays` refreshes these adapters' overlay regions, not just their version strings.
+- The health-check derived-fact comparison flags a **secondary adapter whose overlay region is stale** (extends the v3.24.0/v3.25.0 `PARTIAL_UPGRADE` engine beyond version/FR/skill-count to overlay-region content).
+- The U4 sync allowlist + under-reach guard continue to hold (no consumer-doc reach; no framework file omitted).
+- No regression to the AGENTS/CLAUDE overlay refresh or the byte-exact copy / mirror contracts.
+
+## Notes
+
+- Builds directly on v3.25.0: the U4 executable allowlist + the U7 `PARTIAL_UPGRADE` derived-fact engine are the foundation; this ticket extends them from version-string parity to **overlay-content parity**.
+- Reactive-shipping context: same two consumer reports that drove `upgrade-tooling-hardening`. U5 (version) shipped; U6 (overlay) is the remaining half.

docs/backlog/index.md

@@ -6,3 +6,5 @@
 | architect-sub-agent | parked | Dedicated 3rd sub-agent for deep cross-cutting investigation, keeping the PO lean |
 | role-path-hook-enforcement | parked | `pre_tool_use` role × path gate — PO "no app code" as a structural guarantee (FR-25 plumbing precedent) |
 | health-check-fast-timeout | done (v3.24.0) | Bound the health-check's unbounded git-fetch + sub-script invocations so it never appears to hang (timeouts + partial verdict + `--fast` mode) |
+| upgrade-tooling-hardening | done (v3.25.0) | Harden the refresh/upgrade scripts from two consumer reports — Windows perf (batched spawns), EOF-newline preserve, baseline/policy merge-preserve, sync allowlist + under-reach guard, GEMINI version sync, `PARTIAL_UPGRADE` |
+| adapter-overlay-refresh-parity | parked | U6 follow-up — marker-anchored overlay-refresh path for GEMINI/copilot/cursor (parity with AGENTS/CLAUDE), so secondary adapters get the Flow overlay content refreshed, not just the version string |

docs/specs/upgrade-tooling-hardening/spec.md

@@ -1,9 +1,9 @@
 # Spec — upgrade-tooling-hardening
 
-**Status:** LOCKED (Codex adversarial design review 2026-06-15 folded — verdict RESCOPE; HIGH cluster ships first, U6 follow-up). Ready for implementation.
+**Status:** DONE — shipped v3.25.0 (2026-06-15). Codex adversarial design review (RESCOPE) folded; HIGH cluster shipped, U6 deferred to follow-up backlog ticket `docs/backlog/adapter-overlay-refresh-parity/`.
 **Created:** 2026-06-15
 **Baseline:** FuseBase Flow v3.24.0
-**Deploy hash:** N/A — framework/tooling change
+**Deploy hash:** `6a8961fb603988c0fbfd460fc16a0b65e2c88f85` (release commit, tag `v3.25.0`)
 **Source:** TWO independent consumer upgrade reports (v3.21.1→v3.23.1, both Windows/Git-Bash):
 - `paperclip+hermes-v1/docs/fusebase-flow-proposals/2026-06-15-upgrade-3.21.1-to-3.23.1-friction-report.md` (I1–I9) + proven patch `2026-06-14-windows-hash-spawn-batch-cost.md`
 - WorkHub Managed report (W1–W5), commit `2504584`.
@@ -61,14 +61,21 @@ Byte-exact content copy; marker-anchored AGENTS/CLAUDE overlay refresh (preserve
 - **AC8** `.gitattributes` LF pins (U11); progress output present (U9); Windows docs (U8); `.pre-*` retention prunes dotfile-prefixed (U10, if shipped).
 - **AC9** Standard gate: preflight 0/0; run-tests PASS (+ new fixtures); recovery-sim PASS (exercises both refresh scripts — strongest guard); health HEALTHY; mirror drift 0; plugin valid; `internal/`+`repo-polish` untracked; FR-25 all modules < ceiling.
 
-## Tasks (rough)
-- **Ua** mirror-skills.sh batch, bounded copy, ARG_MAX-safe (U1) + progress (U9).
-- **Ub** sync-version-strings.sh: prefilter + portable newline-preserving rewrite (U1/U2) + executable allowlist `SYNC_ROOTS` (U4) + progress.
-- **Uc** upgrade.sh: module-size-baseline + policy-state merge-preserve (U3) per the LOCKED rule; trap recovery message (U7); `.pre-*` retention (U10); offer-remove `.fusebase-flow-source/` (U12 doc).
-- **Ud** GEMINI regex (U5); `.gitattributes` (U11); Windows env detection + docs (U8); health-check `PARTIAL_UPGRADE` signal (U7).
-- **Ue** Tests: AC2 newline fixtures, AC3 baseline-preserve regression, AC4 under-reach guard + consumer-doc-not-synced, AC7 policy-state preserve.
-- **Uf** Docs + CHANGELOG + release notes + version bump; mirror.
-- Gate → deploy.
+## Tasks (shipped — SHAs)
+| Task | What | Commit SHA |
+|---|---|---|
+| **Ua** | mirror-skills.sh batch, bounded copy, ARG_MAX-safe (U1) + progress (U9) | `b6f31a1` |
+| **Ub** | sync-version-strings.sh: prefilter + portable newline-preserving rewrite (U1/U2) + executable allowlist `SYNC_ROOTS` (U4) + Local regex (U5) + progress | `37c6706` |
+| **Uc** | upgrade.sh: module-size-baseline + policy-state merge-preserve (U3) per LOCKED rule; trap recovery (U7); `.pre-*` retention (U10); progress (U9) | `8ef5d95` |
+| **Ud** | GEMINI regex (U5); `.gitattributes` (U11); Windows env docs (U8); health-check `PARTIAL_UPGRADE` signal (U7) | `382a05e` |
+| **Ue** | Tests: AC2 newline / AC3 baseline-merge / AC4 under-reach guard + consumer-doc-not-synced / AC7 policy-state | `dc47042` |
+| **Ua-fix** | mirror-skills.sh — survive a plain (non-git) dir run (recovery-sim regression) | `0b2b32d` |
+| **Ug-A2** | AC3 baseline-merge — shell-redirection fixture + loud setup asserts (round-2 remediation) | `8c401bd` |
+| **Ug-B1** | merge-baseline — document canonicalization (preservation is row-per-path) | `b86d9eb` |
+| **Ug-B2** | mirror-skills — temp hash cache via mktemp under TMPDIR + EXIT trap | `899a698` |
+| **Uf** | Version bump + sync sweep + release notes + CHANGELOG (the release commit) | `6a8961f` |
+
+Gate → deploy: preflight 0/0 · run-tests 79/79 · check-module-size --all 0 · mirror 0 drift · recovery-sim 31/31 (captured) · probes G-M..G-Q PASS. Tag `v3.25.0`. Codex round-2 confirm SHIP, no findings.
 
 ## Notes
 - Mostly `mirror-skills.sh`, `sync-version-strings.sh`, `upgrade.sh` + GEMINI + `.gitattributes` + health-check (PARTIAL_UPGRADE) + docs. FR-25: watch sizes; extract along seams.