Plan: V4-Only Repository Cutover

Current Situation

The completed convergence implementation is 83d0311aadd7cc93a5f5393902fb0d97645eaefb on team/stefan/m7-m9-effect-v4-convergence in draft PR #87. It combines the accepted M7–M9 architecture work without merging or deploying any child PR. Historical T1/T2 detail remains on the IP-324 source notes and PR #83; this plan records the final convergence graph and proof on PR #87.

T1–T9 are complete. GitHub behavior-contract run 29849467229, job 88698354582, passed in 5m27s. Live Linear verification returned IP-317 through IP-346 as 30/30 Done. The final documentation-only closeout receives a later commit SHA and does not replace the implementation authority above.

Goal

Finish one Effect v4 repository cutover with no v3 or temporary compatibility path, then prove the shipped CLI, API, renderer, operator, and consumer surfaces before merge or release.

Constraints

• Keep one unmerged, undeployed convergence branch until every required gate passes.
• Preserve breadth-first dependency direction: public roots, peer services/repositories/adapters, leaves, cleanup, then aggregate product proof.
• Do not add a v3 alias, shim, dual runtime, feature flag, or staged compatibility path.
• Use IP-330 public behavior characterization as the oracle.
• A missing required gate blocks completion; it is not a waiver.
• The implementation SHA and later documentation-only SHA must remain distinct in closeout evidence.
• Never use the wiki sync wrapper as a validation shortcut. Validate the canonical routed wiki source directly with non-mutating Fumadocs, type-generation, typecheck, and build commands.

Branch/Base Intent

• Branch: team/stefan/m7-m9-effect-v4-convergence
• Base: team/stefan/refactor-cli-architecture
• PR: draft #87; keep it open, unmerged, and undeployed.
• Topology: PR #76 is the parent. PRs #77–#83 and #87 are sibling children of #76's branch. PR #87 does not imply that #77–#83 are in its history.
• Closeout owner: the root coordinator owns push, live PR verification, and the post-push stack sync --dry-run gate. A sync may run only if that preview preserves the fan-out and reports required changes.

Dependency Graph

T1 branch/dependency preflight and convergence provenance
  -> T2 public roots across peer workspaces
  -> T3a CLI/API services, repositories, and adapters
  -> T3b shared persistence/scaffold/UI services and adapters
  -> T4a CLI/API leaves
  -> T4b backoffice/web/wiki leaves
  -> T4c shared v4-only cleanup
  -> T5 strict static and public-output repository gate
  -> T6 packaged CLI/API/renderer/operator proof ─┐
  -> T7 fresh and existing consumer proof ───────┤
  -> T8 repeated deterministic gate and residue audit
  -> T9 final review, docs, Linear, PR, and post-push stack closeout

Task Graph

T1: Preflight and Convergence Provenance

• depends_on: []
• intent: Capture branch, dependency, rollback, and child-commit provenance before convergence. Preserve open draft child history; do not merge child PRs or deploy an intermediate state.
• oracle: The intended parent ancestry, exact child commits, pinned Effect catalog/lock state, and prior known-good rollback authority are recorded and recoverable.
• status: Inherited complete. Detailed historical evidence remains on PR #83/source notes; no stale worktree, rebase, or old-SHA procedure is prescribed for PR #87.

T2: Establish Public Roots Breadth-First

• depends_on: [T1]
• intent: Establish deliberate public roots and dependency direction across CLI, API, shared packages, and consuming apps before completing any leaf vertically.
• oracle: Public-root characterization, focused types, dependency direction, and generated-contract semantics match the accepted IP-330 outcomes.
• status: Inherited complete from the converged M7–M9 work. Detailed task evidence remains on the source notes.

T3a: Converge CLI/API Services, Repositories, and Adapters

• depends_on: [T2]
• intent: Move CLI/API services, repositories, adapters, typed failures, configuration boundaries, and app-owned runtime/client seams to Effect v4.
• oracle: Public operations cross the owning v4 boundary, preserve the IP-330 output classification, and pass focused/full CLI/API tests plus packaged API provenance.
• status: Complete on PR #87. The final full CLI suite passes 67 files and 743 tests; API tests, types, build, and packaged runtime proof pass.

T3b: Converge Shared Services and Adapters

• depends_on: [T2]
• intent: Move persistence, scaffold, UI, auth, contract, configuration, and environment peers through their public v4 seams without reversing dependency direction.
• oracle: Shared package tests/types and real adapter contracts pass; public exports and serialized/generated outputs retain their accepted semantic or byte-locked forms.
• status: Complete locally on PR #87.

T4a: Complete CLI/API Leaves

• depends_on: [T3a, T3b]
• intent: Finish CLI/API actions and handlers under v4 with no compatibility route.
• oracle: CLI/API tests, types, checks, builds, public-output fixtures, and packaged runtime behavior pass through their public seams.
• status: Complete locally on PR #87.

T4b: Complete Backoffice/Web/Wiki Leaves

• depends_on: [T3a, T3b]
• intent: Finish renderer, route, and operator/browser consumers without source-only substitutes.
• oracle: Backoffice Playwright passes 8/8, wiki behavior passes 6/6, direct wiki generation/types/build pass, and renderer/catalog output remains characterized.
• status: Complete locally on PR #87.

T4c: Remove V3, Temporary Paths, and Generated Drift

• depends_on: [T3a, T3b]
• intent: Remove v3 imports/dependencies, aliases, shims, dual paths, temporary migration scaffolding, and stale generated state while retaining truthful package authority.
• oracle: bun run validate:effect-v4 passes 94/94 with 1,434 assertions; the CLI tarball ships only react-devtools-core as a runtime dependency while Effect/internal workspaces remain development/build dependencies; managed byte contracts pass.
• status: Complete locally on PR #87. The Effect validator passed twice after the final repairs.

T5: Pass the Strict Repository and Public-Output Gate

• depends_on: [T4a, T4b, T4c]
• intent: Run the same aggregate architecture and behavior oracles used by repository closeout, including workspace tests, types, lint/format, and builds.
• oracle: Effect gate 94/94; root behavior suite 4/4; root test Turbo wave 15/15; root check 12/12; all build surfaces pass, using direct non-mutating wiki build plus the four non-wiki Turbo build tasks.
• status: Complete locally on PR #87.

T6: Prove Packaged CLI, API, Renderer, and Operator Behavior

• depends_on: [T5]
• intent: Exercise the shipped npm tarball and packaged API rather than source-only substitutes, then validate renderer/catalog, browser/operator, wiki, and cleanup seams.
• oracle: bun run validate:packaged-product installs the actual npm tarball and exercises both hi and hint; CLI public-output/renderer is 60/60; packaged API provenance and fail-closed authority pass; backoffice browser is 8/8; wiki is 6/6; package-surface and residue checks pass.
• status: Complete locally on PR #87.

T7: Prove Fresh and Existing Consumer Repositories

• depends_on: [T5]
• intent: Use the packaged CLI in isolated fresh and existing repositories. Cover hi init, hi scaffold, hi check, and hi update, including managed/unmanaged ownership and user-change preservation.
• oracle: bun run validate:consumer-repositories installs the actual npm tarball offline; packaged hi/hint prove fresh init, repeated scaffold, drift/check, conflict-preserving and idempotent update, a final clean check, exact managed provenance/hashes, unchanged consumer bytes, exact bundled gitignore alias bytes, and removal of the run-owned temporary root.
• status: Complete locally on PR #87. Fresh init verified 199 managed files and 191 non-project-authored hashes; repeated scaffold verified 235 and 228; existing check/update preserved both managed conflict bytes and unmanaged user bytes and reached a clean fixed point.

T8: Repeat the Complete Gate and Prove Cleanup

• depends_on: [T6, T7]
• intent: Repeat the complete static, packaged, and consumer gate with unique provenance and compare normalized output while auditing owned processes, files, repositories, and service state.
• oracle: Repeated runs are deterministic and leave no run-owned residue on success or failure.
• status: Complete locally. The replacement bun run validate:cutover-repeat matrix exited 0 at HEAD 5e1637f939818e43b69a8a5262c3de012e54518c, bound to dirty-patch SHA-256 633b1614c0081cd52d7dda086cb241c2fd62f279c2b9d4fe26914e7695faf806 (56,308 tracked bytes; 6 untracked paths). Both complete runs matched at 739c91c0ae08234d6cd7611ffbfda8eed19aa14b1f4355b349d12a546162fe0d; both stress runs matched at dbbed7e6af71a7a1bdf63b9444045743503343e5f86770a4f15cce1c78fd7bac. The observational archive digest was cc49bfd06a303ee9f6cf4c5a1a991404c1641de0567c3df77b7032f381d1361; the authoritative 664-entry installed tree was 991c96fbcf2e7a0d2b26733704e53944783523e61c47b3fa2319eba48f7f2cb9; the four generated wiki modules matched at fd36d0636ae488eaa5acb37823cf0f4bf6846e0f16452d387312a847be2fe422. All complete, stress, expected-failure, and session cleanup path/process/service sets were empty.

T9: Final Review, Docs, Linear, PR, and Stack Closeout

• depends_on: [T8]
• intent: Complete findings-first review, reconcile durable docs and Linear evidence, push the reviewed branch, and prove the post-push PR/stack topology without merging or deploying it.
• oracle: No blocking review findings; every acceptance item has evidence; Linear and PR #87 reflect the actual state; the post-push stack gate preserves the intended fan-out.
• status: Complete. Findings-first review returned no actionable findings. Implementation SHA 83d0311aadd7cc93a5f5393902fb0d97645eaefb was pushed; the exact root gate passed 15/15 and the CLI passed 743/743. GitHub run 29849467229, job 88698354582, passed. Post-push stack status and stack sync --dry-run preserved the exact fan-out and reported current, so no sync ran. IP-345, IP-346, then IP-324 were moved to Done; a live refetch proved IP-317 through IP-346 are 30/30 Done. PR #87 remains draft, open, unmerged, and undeployed.

Validation Oracles

Stop Conditions

Delivery is complete. Keep PR #87 draft, open, unmerged, and undeployed for maintainer review. Any merge, release, deployment, retarget, or future convergence branch is a separate explicit decision.