docs: plan post-release follow-up program (#541)

* docs: plan post-release follow-up program

* docs: make Changesets v3 migration atomic

Author: blove

docs/superpowers/plans/2026-08-30-post-release-followups.md

@@ -0,0 +1,118 @@
+# Post-release Follow-ups Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Resolve the approved dependency, correctness, and performance follow-ups as independently verified green-on-merge changes.
+
+**Architecture:** Dependency updates remain isolated by compatibility boundary; the release Action follows the CLI migration. The sole new product fix defines scroll authority at the React/controller seam. Already-shipped issue work is verified against current main before issue closure.
+
+**Tech Stack:** Node 24.19.0, pnpm 10.12.1, TypeScript 6, React 18-19, Vitest, Playwright, Changesets, GitHub Actions.
+
+**Spec:** `docs/superpowers/specs/2026-08-30-post-release-followups-design.md`
+
+---
+
+### Task 1: Commit and merge the follow-up design
+
+**Files:**
+- Create: `docs/superpowers/specs/2026-08-30-post-release-followups-design.md`
+- Create: `docs/superpowers/plans/2026-08-30-post-release-followups.md`
+
+- [ ] Run `pnpm prettier --check docs/superpowers/specs/2026-08-30-post-release-followups-design.md docs/superpowers/plans/2026-08-30-post-release-followups.md`.
+- [ ] Review the two documents against the GitHub issue and PR state.
+- [ ] Commit, push, open a documentation PR, wait for required checks, and squash-merge.
+
+### Task 2: Repair and merge dependency group PR #538
+
+**Files:**
+- Modify: `status/milestones/2026-08-15-s2-comparative-rebaseline.json`
+- Existing PR files: `package.json`, `pnpm-lock.yaml`, `apps/bench/package.json`, `apps/website/package.json`
+- Test: `scripts/__tests__/bench-comparator-provenance.test.mjs`
+
+- [ ] Refresh the PR branch from current `main` without force-pushing unrelated history.
+- [ ] Reproduce the provenance failure with `node --test scripts/__tests__/bench-comparator-provenance.test.mjs`.
+- [ ] Add an `adapterVersions.superseded` block naming MUI Data Grid, MUI Material, TanStack Table, and TanStack Virtual version drift; leave recorded versions unchanged.
+- [ ] Re-run the provenance test and inspect the complete PR diff.
+- [ ] Run `pnpm install --frozen-lockfile --ignore-scripts --ignore-pnpmfile`, `pnpm security:audit`, `pnpm test`, `pnpm typecheck`, `pnpm lint`, `pnpm format`, `pnpm build`, `pnpm api:check`, `pnpm consumer:check`, `pnpm react:compat`, and `pnpm lint:packaging`.
+- [ ] Push, wait for every required check, and squash-merge PR #538.
+
+### Task 3: Combine Changesets CLI 3 and Action 2 in PR #474
+
+**Files:**
+- Existing PR files: `package.json`, `pnpm-lock.yaml`
+- Modify: `.github/workflows/release.yml`
+- Inspect: `.changeset/config.json`, `scripts/publish-configured-packages.mjs`, `scripts/publish-preflight.mjs`
+- Test: `scripts/__tests__/publish-public-packages.test.mjs`, `scripts/__tests__/publish-preflight.test.mjs`, `scripts/__tests__/security-audit-workflow-contract.test.mjs`, `scripts/__tests__/node-toolchain-contract.test.mjs`
+
+- [ ] Read the official CLI 3 and Action 2 migration notes and compare them to the repository configuration, workflow, and custom publish wrapper.
+- [ ] Refresh the PR branch from current `main`.
+- [ ] Write failing workflow-contract assertions for `version-script`, `publish-script`, `pr-title`, `commit-message`, `github-token`, `pr-number`, and output-file propagation.
+- [ ] Migrate the Action in the same PR as the CLI. Keep npm token variables absent and the OIDC preconditions fail-closed.
+- [ ] Run the focused workflow/publish/preflight tests and safe CLI commands (`changeset status`, config parsing, and a disposable versioning fixture if needed).
+- [ ] Run the full verification matrix from Task 2.
+- [ ] Push the combined migration, wait for green checks, and squash-merge PR #474.
+- [ ] Close PR #476 as superseded by the verified atomic migration.
+
+### Task 4: Resolve fuzzysort 4 PR #472
+
+**Files:**
+- Existing PR files: `apps/website/package.json`, `pnpm-lock.yaml`
+- Modify/Test: website search modules and their existing tests discovered with `rg -n "fuzzysort" apps/website`
+
+- [ ] Read the official fuzzysort 4 migration notes.
+- [ ] Refresh the PR branch and run existing focused search tests to establish the failure or compatibility baseline.
+- [ ] Add a regression for every behavior affected by the v4 API change before changing production code.
+- [ ] Implement the minimal migration, verify red-green, then run website, typecheck, build, smoke, and full repository gates.
+- [ ] Push, wait for green checks, and squash-merge PR #472.
+
+### Task 5: Resolve jest-dom 7 PR #475
+
+**Files:**
+- Existing PR files: `package.json`, `pnpm-lock.yaml`
+- Inspect: every Vitest setup file and `tsconfig` matcher-type entry returned by `rg -n "jest-dom" .`
+
+- [ ] Read the official jest-dom 7 migration notes and engine requirements.
+- [ ] Refresh the PR branch and run representative React, UI, bench, and website DOM suites.
+- [ ] Add a focused type/runtime regression before any setup migration required by v7.
+- [ ] Run all DOM suites plus the full repository gates.
+- [ ] Push, wait for green checks, and squash-merge PR #475.
+
+### Task 6: Fix scroll authority issue #524
+
+**Files:**
+- Modify: `packages/react/src/pretable-model.ts`
+- Test: create `packages/react/src/__tests__/scroll-authority.test.tsx` or extend the narrowest existing controller-seam test after investigation
+- Inspect: `packages/renderer-dom/src/row-layout-controller.ts`, `packages/react/src/pretable-surface.tsx`
+
+- [ ] Trace user scroll, grid viewport, controller viewport, anchor restore, and status-change data flow on current `main`.
+- [ ] Write a React integration regression that reproduces stale viewport re-feed after an anchor-adjusting publish; confirm it fails for the #524 reason.
+- [ ] Make status-only controller publications unable to reassert stale DOM scroll while preserving legitimate viewport feeds.
+- [ ] Confirm the regression passes, mutation-check by restoring the old dependency/behavior, then restore the fix and run React plus renderer focused suites.
+- [ ] Run full repository gates and Chromium/WebKit smoke tests.
+- [ ] Push a dedicated PR, wait for green checks, squash-merge, and close #524 through the PR.
+
+### Task 7: Verify and close #491
+
+**Files:**
+- Existing test: `packages/renderer-dom/src/__tests__/indexed-renderer.test.ts`
+
+- [ ] Run the focused journal-anchor test on current `main`.
+- [ ] Confirm PR #508's merge commit is an ancestor of current `main` and inspect the exact anchor ladder.
+- [ ] Comment with the test evidence and close #491 as completed.
+
+### Task 8: Re-measure and close #452
+
+**Files:**
+- Generated/committed measurement only if the bench workflow requires it: `status/runsets/*`, `status/milestones/*`
+
+- [ ] Check the machine for a quiet measurement window.
+- [ ] Run Chromium S2 hypothesis sort, filter-metadata, and filter-text for Pretable and TanStack with at least three repeats in the same runset.
+- [ ] Compare interaction latency and correctness metrics to the original issue and PR #479/#487 evidence.
+- [ ] If the gap remains closed, comment exact results and close #452; if not, keep it open and write a new evidence-based implementation plan before changing code.
+
+### Task 9: Final main and production audit
+
+- [ ] Pull latest `main` into a fresh verification worktree.
+- [ ] Run security audit, full tests, typecheck, lint, format, build, API, packaging, packed consumers, React compatibility, and Chromium/WebKit smoke.
+- [ ] Verify npm package dist-tags and the latest main CI, CodeQL, Scorecard, release, and production-deploy checks.
+- [ ] Review open PRs/issues for superseded dependency branches or newly exposed blockers and report the final handoff.

docs/superpowers/specs/2026-08-30-post-release-followups-design.md

@@ -0,0 +1,100 @@
+# Post-release follow-ups design
+
+Date: 2026-08-30
+
+## Goal
+
+Finish the open maintenance and correctness work after the `0.11.0` release
+without combining unrelated risk into one merge. Every lane starts from the
+then-current `main`, carries its own evidence, and merges only after required
+checks pass.
+
+## Reassessment against current main
+
+The released package architecture is already on `main`. Since the original
+handoff, PR #539 also merged, so follow-up branches must start at or after
+`ac1cbb41` rather than the release commit.
+
+Two open issues describe work that has already shipped:
+
+- #491 was fixed by PR #508. The journal path now uses the same exact-ref then
+  old-neighbour anchor ladder as the replacement path, and the renderer test
+  pins the previously divergent scroll result.
+- #452 was addressed by PR #479 for sort and PR #487 for filters. Their
+  same-run measurements show sort interactions at or better than TanStack and
+  filter interaction latency in the 15-18 ms band. Those issues need fresh
+  verification and closure, not another speculative optimization.
+
+#524 remains an unresolved ownership seam. A controller publish may compute an
+anchored `scrollTop`, after which React's viewport-feed layout effect can run
+because controller status changed and reapply the DOM/grid snapshot's older
+pixel offset. The fix must define authority at a publish boundary rather than
+paper over one replace scenario.
+
+## Delivery lanes
+
+### 1. Minor and patch dependency group (#538)
+
+Refresh the Dependabot branch onto current `main`. Preserve historical
+benchmark truth: do not edit recorded comparator versions. The existing S2
+milestone is already superseded for pinning asymmetry, so add an explicit
+`adapterVersions.superseded` record naming the four comparator version moves
+and stating that its numbers describe the older releases. Run the full repo,
+packaging, audit, and browser checks before merge.
+
+### 2. Atomic Changesets v3 migration (#474 + #476)
+
+Changesets' official migration contract requires CLI 3 and Action 2 to move
+together: Action v1 is the CLI 2 maintenance line, and Action v2 validates CLI 3. Extend PR #474 into the atomic migration and close #476 as superseded only
+after #474 merges. Prove the repository config parses, status/version commands
+work on a disposable branch state, publish preflight still fails closed, and
+the release workflow contract remains green. Migrate the renamed Action
+inputs/outputs and explicit `github-token` input in the same commit series.
+
+### 3. Other major updates (#472, #475, #476)
+
+Each major gets dedicated compatibility evidence:
+
+- fuzzysort 4: verify the documented API change against every website call
+  site and preserve search ranking/result behavior with focused tests.
+- jest-dom 7: verify the Vitest setup, matcher types, Node floor, and all DOM
+  suites.
+- PR #476 is resolved by the atomic Changesets migration above, not by a second
+  release-workflow merge.
+
+### 4. Scroll authority (#524)
+
+The engine owns scroll position while committing an anchored row-layout
+publish. The DOM owns new scroll intent only when an actual viewport event or
+imperative viewport command changes the grid snapshot. A controller status
+transition alone must not manufacture new DOM intent.
+
+Implement this at the React/controller seam. First add a regression that makes
+the controller publish an anchor-adjusted `scrollTop` while the grid snapshot
+still holds the old value, then proves a status-only rerender cannot overwrite
+the anchored value. Keep legitimate height, width, overscan, column, and user
+scroll feeds intact. Verify with controller-level and React integration tests.
+
+### 5. Closure audits (#491 and #452)
+
+For #491, run the focused journal-anchor mutation test on current `main`, link
+PR #508, and close the issue.
+
+For #452, run the current Chromium S2 sort, filter-metadata, and filter-text
+matrix for Pretable and TanStack in one environment. Record the fresh runset
+or an issue comment with exact command, revisions, and results. Close only if
+the current measurements still establish that the originally reported
+interaction-latency gap is gone; otherwise reopen implementation scope from
+the evidence.
+
+## Verification and merge policy
+
+Each lane is a separate PR or an update to the existing Dependabot PR. Before
+merge: focused tests, full `pnpm test`, typecheck, lint, formatting, build,
+packaging checks, packed consumers, React compatibility, and security audit as
+applicable. Browser-sensitive changes additionally run Chromium and WebKit
+smoke/bench coverage. Merge only when required GitHub checks are green, then
+pull the new `main` before beginning the next lane.
+
+No benchmark record is rewritten to claim an unperformed measurement. No
+major upgrade is accepted solely because installation succeeds.