# Deterministic test-baseline repair and feature-branch restacking

Use this when a feature/release commit already contains incidental test-baseline fixes, but the baseline repairs must ship first as a separate PR.

## Objective

Produce two reviewable commits without rewriting or losing the original feature work:

```text
base
└── baseline-fix
    └── feature-v2
```

Keep the original feature commit reachable under its original branch plus an explicit local backup branch or tag until both replacement commits are verified.

## Procedure

1. **Freeze the original feature commit.** Verify its SHA and parent, then create an unambiguous backup ref. Do not amend, reset, or delete the original ref.
2. **Reproduce on the exact base SHA.** Create a separate worktree/branch directly from the requested base and run the full suite before editing. Never infer the base failure count from a dirty or already-modified feature worktree: incidental fixes there can hide inherited failures.
3. **Repair only baseline tests.** Prefer controlled clocks, explicit fixture reference dates, public contracts such as OpenAPI/TestClient behavior, and expectations derived from synthetic fixture components. Do not change production formulas merely to satisfy stale expectations.
4. **Prove the baseline commit is test-only.** Inspect its changed path set and full diff. Run focused failures, then the full suite, compile, changed-file lint, repository/secret safety, and diff checks. Commit only when green.
5. **Create a new feature branch from the baseline commit.** Do not rebase or mutate the preserved original branch.
6. **Transfer without auto-committing.** Apply the original feature commit with `git cherry-pick -n <original>` or an equivalent three-way patch. Resolve conflicts by retaining baseline-owned test repairs and feature-owned product/contract changes. If a conflicted no-commit cherry-pick is used, stage resolutions and `git cherry-pick --quit` before final verification/commit.
7. **Correct audit documentation.** Record the exact base failure count and explain any earlier lower count only from observed worktree/command evidence.
8. **Prove no incidental repair was duplicated.** Compare the baseline and feature-v2 patches. Shared files can be legitimate when different contracts live together; prove hunk ownership rather than claiming path-level disjointness. Assert baseline-specific signatures/hunks are present in the baseline patch and absent from the feature-v2 patch.
9. **Prove feature preservation.** Compare the original feature changed-path set with feature-v2 relative to the baseline. For non-conflict files, compare blob hashes. Review every intentional exception (audit docs, conflict integrations, changed-file lint cleanup).
10. **Run full feature gates again.** Focused contracts, full backend suite, complete frontend tests/typecheck/build, compile, changed-file lint, safety scan, diff check, and full primary-agent diff review. Verify all worktrees clean and all parent relationships exact after local commits.

## Pitfalls

- A full suite run in the feature worktree is not evidence of the untouched base failure count.
- Do not cherry-pick the whole feature commit into the baseline branch.
- Do not report two PRs as non-overlapping merely because their purposes differ; inspect shared files and prove the specific baseline repair hunks are absent from feature-v2.
- Legacy safety scanners may inspect ignored test/lint caches. On the baseline branch, clean only ignored caches before the final scan and report that limitation; do not broaden a test-only baseline PR into a scanner rewrite.
- If changed-file lint is the gate, preflight it before the one-shot full suite so mechanical cleanup does not invalidate already-recorded suite evidence.