TML-2690: close out migrate-to-rollback-plannable (retro landings + project-dir cleanup)

[wmadden-electric]

What this is

Close-out for the migrate-to-rollback-plannable slice (TML-2690). The feature itself merged in #635 ("make rollback edges plannable and applyable via --to"); this PR lands the project's retro lessons in durable surfaces and removes the now-transient projects/migrate-to-rollback-plannable/ scaffold.

Project DoD verification

All acceptance criteria shipped and merged in #635:

AC	Status	Evidence
migrate keeps refusing to apply a non-existent path (refusal invariant preserved)	Met	#635 — migrate.ts still never invents an edge; --to only redirects the verification target
pathUnreachable (PN-RUN-3000) diagnostic reads as one plan-then-apply sequence	Met	#635 — cli-errors.ts errorPathUnreachable + migration-apply.ts buildPathNotFoundFailure.why
migration plan --to <ref> plans toward an arbitrary target (incl. rollback)	Met	#635 — migration-plan.ts --to wiring; plan-resolution.ts shared resolver
migrate --to <node> verifies/applies against the target bundle's end-contract.json (closes the DESTINATION_CONTRACT_MISMATCH dead-end)	Met	#635 — mirrors db update --to; e2e plan-to-rollback.e2e.test.ts
Slice-DoD: e2e reproduces the J5 case (plan --to <dir>^ then migrate --to <dir>^ round-trip, no contract-source edit)	Met	#635 — test/integration/test/cli-journeys/plan-to-rollback.e2e.test.ts

Round-2 aggregate consolidation (rewire onto ContractSpaceMember.contractAt) and the provenance fix (discriminated ContractAtResult) also merged in #635.

Mandatory final retro: complete (per invariant I10). Lessons landed durably in this PR:

• drive/calibration/failure-modes.md § F14 — consolidation onto a shared facet must carry provenance, not re-infer result-kind from the input; a behaviour-preserving rewire needs an intent pass despite green tests.
• drive/retro/findings.md (2026-05-30, gap) — process root: the two round-2 rewire dispatches were pushed on green tests without a reviewer pass, and the provenance regression slipped to CodeRabbit; green is the weakest signal on a logic-replacing rewire because the suite predates the divergent branch.

Migration / reference summary

• Long-lived files migrated: none. The user-facing docs (CLI README, docs/architecture docs/subsystems/7. Migration System.md) were updated inside TML-2690: make rollback edges plannable and applyable via --to #635; the project dir held only spec.md (transient shaping artefact) and retros.md (transient log — lessons landed above).
• Reference strip: no dangling projects/migrate-to-rollback-plannable/ path references existed. The two drive/ retro entries reference the project by name + ticket (migrate-to-rollback-plannable (TML-2690)) as a durable incident label, which survives close-out by design.

Known pre-existing item (not introduced here)

Nine @prisma-next/cli spawn-timeout flakes (500ms cap vs ~680ms cold start) pre-date this work and are unrelated — noted in the merged feature, no action in this PR.

Closes TML-2690.

Summary by CodeRabbit

• Documentation
  • Added a new calibration failure-mode (F15) describing a consolidation/rewire dispatch pattern that can misclassify provenance, with detection signals and mitigation steps (discriminators, discriminated unions, review intent).
  • Added a retrospective finding (2026-05-30) capturing an incident of provenance misclassification, its symptoms, and a procedural lesson to require reviewer/intent checks for rewires even when tests pass.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 1be18266-f245-4037-846b-523f820e2030

📥 Commits

Reviewing files that changed from the base of the PR and between 4975261 and 0238246.

⛔ Files ignored due to path filters (1)

• projects/migrate-to-rollback-plannable/spec.md is excluded by !projects/**

📒 Files selected for processing (2)

• drive/calibration/failure-modes.md
• drive/retro/findings.md

---

📝 Walkthrough

Walkthrough

This PR appends failure mode F15 to drive/calibration/failure-modes.md and a related 2026-05-30 drive-build-workflow retro finding to drive/retro/findings.md, documenting a provenance misclassification caused by consolidation/rewire dispatches and the governance gap that allowed it.

Changes

Incident Documentation

Layer / File(s)

Summary

F15 failure mode and corresponding retro finding drive/calibration/failure-modes.md, drive/retro/findings.md

Adds failure mode F15 describing consolidation/rewire misclassification where callers infer result kind from inputs instead of a facet-provided provenance discriminator (causing path-specific fields like sourceDir to be dropped). Adds a 2026-05-30 retro finding recording the dispatch governance gap (intermediate rewires D6/D7 pushed without reviewer pass, PR #635) and the lesson to require reviewer/intent passes for such rewires.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through diffs and found a subtle trail,
A flow that wore another's name and lost its tail.
Now F15 marks where provenance should be shown,
Review the rewires, so each path keeps its own.
🌿🧩

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: closing out a feature slice with retro findings and project cleanup, matching the documented objectives and changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2690-closeout

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}