strangler-fig-method

name	strangler-fig-method
description	Use to REPLACE part of an existing brownfield system incrementally — behind a routing facade, one slice at a time, verified by contract equivalence against a green safety net — rather than restructuring it in place. Loaded internally by brownfield-refactorer when the human chooses replacement over Mikado in-place restructuring.
disable-model-invocation	true

Strangler Fig Method

Replaces a component by growing a new implementation alongside the old one, behind a facade that routes traffic, slice by slice, until the old implementation has no callers left and can be deleted. Unlike Mikado (restructure what exists), this method REPLACES it — appropriate when the existing code is too coupled to restructure safely, or when the target is a different stack/design entirely.

Precondition. Same as Mikado: a green safety net (characterize-with-contracts / brownfield-harness-builder) must exist first. Here the safety net does double duty — it is replayed against BOTH the old and the new implementation; a slice only cuts over when the new implementation is contract-equivalent to the old one on every test in the harness.

Procedure

1. Establish the facade

Introduce (or confirm an existing) routing seam in front of the component being replaced — a gateway route, a feature-flagged branch, or a proxy layer — such that traffic can be switched per-slice between OLD and NEW without touching callers. If no seam exists, this is the first prerequisite: build the facade itself as slice zero, verified by the harness against the OLD implementation only (no NEW yet — this slice just proves the facade is transparent).

2. Slice the surface

Partition the component's contract (the same contract discovered/reconstructed by characterize-with-contracts) into independently-cutover-able slices. Default granularity for v1: one slice per route/endpoint — smaller slices mean smaller blast radius per cutover and finer rollback granularity than a whole-component slice.

3. Build one slice's NEW implementation

Implement the NEW version of one slice. Run the SAME characterization tests for that slice's contract against the NEW implementation (not just the old). This is the contract-equivalence check — Microcks/contract tests are the perfect fit here because they assert against the SAME OPEN_API_SCHEMA, regardless of which implementation answers.

4. Cutover gate (S4 — non-negotiable)

A slice cuts over ONLY when:

• The slice's characterization tests pass against NEW with the same assertions used against OLD (contract-equivalent — same status codes, same shapes; deliberate behavior CHANGES must be called out explicitly to the human as a decision, never silently absorbed as "equivalent").
• The full harness (all other slices, still routed to whichever implementation currently serves them) remains green.

If the gate fails: do not cut over. Record the mismatch as a blocker (see terminal signals below) and keep routing that slice to OLD.

5. Repeat, then strangle

Repeat steps 3-4 for each slice. Once every slice routes to NEW and the facade shows zero traffic to OLD (verify via routing logs/metrics if available, or via a final "OLD is unreachable" static check), the OLD implementation and the facade's OLD branch are dead code, removable as a final slice of their own.

Plan persistence (the durable artifact)

Persist the slice plan to .copilot-tracking/skraft-plans/{projectSlug}/refactoring/{YYYY-MM-DD}/ strangler-<slug>.md as a table, one row per slice:

Slice	Contract surface	Status	Cutover verdict	Notes
S1	POST /orders	done (NEW live)	PASS (equivalent)	—
S2	GET /orders/:id	in-progress	CONCERNS	pagination shape differs — flagged to human
S3	DELETE /orders/:id	not-started	—	—

One writer on this file per run (brownfield-refactorer); reload before dispatching each slice worker, not from recall.

Driving slices to completion (per-slice worker contract)

Each slice is dispatched to refactoring-worker as a fresh, isolated unit. The dispatch packet MUST include: the current slice plan table, the specific slice to implement (contract surface + current status), the cutover acceptance criteria from step 4 verbatim, and the explicit instruction to flag (never silently resolve) any behavior difference between OLD and NEW.

Terminal signals (worker -> orchestrator)

• ADVANCE — this slice cut over cleanly; more slices remain.
• EXPAND — this slice was too large to cut over as one unit; it was split into smaller slices (new rows added to the plan); no cutover happened for this dispatch.
• DONE — all slices are on NEW, OLD is confirmed unreachable, and the OLD implementation + facade branch have been removed.
• BLOCKED — a contract-equivalence mismatch needs a human decision (is the behavior difference intentional? acceptable? a bug in NEW?), or the facade itself cannot route cleanly.

Common failure modes (reject these)

• Silently absorbing a behavior difference as "close enough" — any NEW-vs-OLD difference is a human decision, not an implementation detail to smooth over.
• Cutting over a slice without replaying the FULL harness — a slice can look correct in isolation while breaking a cross-slice interaction still routed to OLD.
• Skipping the facade-transparency check (slice zero) — cutting traffic before proving the facade itself is invisible makes every later slice's signal unreliable.
• Deleting OLD before confirming zero traffic — always verify unreachability before removal; a forgotten caller still pointed at OLD becomes a silent outage.