# ADR-S5: Compatibility and Incremental Migration

**Status**: Adopted (agent-recorded design decision) — pending named
architecture ratification **Date**: 2026-07-24 **Authors**: V1 Domain
Workbenches extraction audit (Phase S)

> Records how Tara adopts the shared workbench-kit **without a flag day**
> (`V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md` §S0.10). Built on §S0.10.a
> (`tara-migration-surface.json`), the §S0.2 extraction matrix (the migration
> slices), the §S0.7 extension model (the seams), and §S0.8 (the store
> boundary). Machine-checked model:
> `evidence/v1-workbenches/migration-plan.json`.

## Context

§S0.10.a registered Tara's surface: 209 public imports, **70 routes, 1 durable
store, 1 domain-lib consumer** (`@oshun/bff`). The migration must not break any
of these while the kit is introduced.

## S0.10.b — Coexistence architecture (additive seams)

| Seam                | Mechanism                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| adapter             | each kit contract is fed by a Tara-supplied domain adapter (§S0.7 `ImportAdapter`/`PublishAdapter`/`ScoreProvider`); the kit never names a Tara concept |
| alias               | re-export the kit contract under Tara's existing symbol names so current importers keep compiling (additive, no rename)                                 |
| version-negotiation | kit capability discovery (§S0.7.d) lets a partially-migrated host detect which contracts are kit-backed vs Tara-inline                                  |
| no-breaking-change  | every seam is additive; `@oshun/tara-workbench` keeps serving all **70 routes** throughout — there is no flag day                                       |

## S0.10.c — Migration slices (independently verifiable capabilities)

The slices are the **13 neutral interaction contracts** the §S0.2 matrix
extracted — not a package-wide replacement. Ordered by risk:

- **Tier 1 — proven-reuse-first:** `EvidenceGroundingPanel`, `SourceLibrary`
  (Veritas is the near 2nd consumer → clears the §S0.11 threshold first).
- **Tier 2 — lowest-coupling neutral:** the 0-meditation-signal contracts
  (`AssignmentPanel`, `CommentThread`, `PipelineFunnel`, `ReviewDecisionPanel`).
- **Tier 3 — mixed-split:** the remaining contracts that need their domain
  adapter wired (`GateRunnerPanel`, `CatalogBrowser`, `SchedulingCalendar`,
  `BundlePublisher`, `SourceInspector`, `TaxonomyEditor`,
  `AgentAutonomyBudget`).

Full ordered list (1..13) in `migration-plan.json` `.slices`.

## S0.10.d — Slice transition contract

Per slice: **enable** (feature-flag the kit-backed contract; Tara inline stays
default) → **verify** (the slice's existing tests pass against the kit) →
**coexist** (both render identically; flip the flag) → **remove** (delete the
Tara inline copy only once the kit contract clears §S0.11).

**No dual-read/write reconciliation is needed:** each slice is a UI-contract
extraction over the **same** Tara BFF + durable store (§S0.8 keeps the store
Tara-owned) — there is no second copy of the data to reconcile.

## S0.10.e — Mixed-version journey plan

A partially-migrated user sees **no difference**:

- **70 routes unchanged**, **1 durable store unchanged**.
- the `/studio/tara-workbench/*` deep-link namespace is Tara-owned (§S0.9 IA)
  and does not change — deep links resolve identically.
- the migration swaps a **component implementation**, not a route/store/URL; the
  §S0.2 seam is the interaction contract, so behavior is preserved.

## S0.10.f — Retirement plan

Milestone-gated, not calendar-fixed (so it cannot slip a flag day):

| Milestone | Condition                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| T0        | first slice (`EvidenceGroundingPanel`/`SourceLibrary`) gains its Veritas 2nd consumer → clears §S0.11 → first deletion eligible |
| T1        | neutral-candidate slices migrated + verified behind the flag                                                                    |
| T2        | mixed-split slices migrated once their domain adapters are wired                                                                |
| T3        | all migrated slices past §S0.11 → Tara inline copies deleted; contract period ends                                              |

- **Contract period:** each slice keeps its inline copy until its kit contract
  clears §S0.11 (≥2 real consumers).
- **Legacy consumer:** the single `@oshun/bff` consumer re-points per slice.
- **Deletion gate:** §S0.11 — delete only at ≥2 consumers **and** passing tests.
- **Absolute dates** are set at named ratification (governance).

## Consequences

- No flag day: `@oshun/tara-workbench` serves every route until each slice is
  independently proven and retired.
- The §S0.11 deletion threshold is the single retirement gate, tying this ADR to
  ADR-S1/S0.11.
- Named ratification remains a human step; the slice order, seams, and gate are
  coherence-gated in CI against the §S0.2/§S0.8/§S0.10.a evidence.

## References

- `V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md` §S0.10
- `evidence/v1-workbenches/tara-migration-surface.json` (§S0.10.a),
  `component-extraction-matrix.json` (§S0.2)
- `evidence/v1-workbenches/migration-plan.json` (this plan, machine-checked)
- `docs/adr/ADR-S1-*.md` … `ADR-S4-*.md`