TenantAtlas/specs/092-legacy-purge-final/spec.md

# Feature Specification: Legacy Purge (Runs / Routes / UI / Test Shims)

**Feature Branch**: `092-legacy-purge-final`  
**Created**: 2026-02-14  
**Status**: Draft  
**Input**: User description: "Spec 092 — Legacy Purge: Runs / Routes / UI / Test-Shims vollständig entfernen"

## Clarifications

### Session 2026-02-14

- Q: For legacy tenant-scoped deep links that were previously served via redirect shims under `/admin/t/{tenant:external_id}/...` (e.g. `/admin/t/{tenant}/operations`), what response semantics do you want? → A: Always `404 Not Found`.
- Q: For guard tests scanning for legacy patterns, which paths should be excluded? → A: Exclude `database/migrations/**` + `references/**` + `docs/**`.
- Q: For Inventory entry after removing the redirect-only landing page, what should be the canonical target? → A: Inventory Items.
- Q: For Drift landing copy, what exact phrase should replace the legacy text “inventory sync runs”? → A: Use “operation runs”.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Operate without legacy concepts (Priority: P1)

As a platform maintainer, I can use the application without encountering legacy run concepts (URLs, labels, redirect-only pages, or test shims), so the system has a single canonical mental model.

**Why this priority**: Removing legacy remnants reduces refactor risk, prevents onboarding confusion, and eliminates hidden compatibility logic.

**Independent Test**: Navigate through Inventory, Drift, Operations/run history, and Provider Connections using the primary UI entry points; verify no legacy URLs or legacy wording appear and no compatibility shims are required.

**Acceptance Scenarios**:

1. **Given** a user navigates via the canonical UI navigation, **When** they open Inventory and Drift entry points, **Then** they land on canonical pages (not redirect-only landing pages) and see canonical operations terminology.
2. **Given** a user is in the admin UI, **When** the context/navigation chrome renders, **Then** it derives its state from the current workspace/tenant context only (not from legacy URL heuristics).

---

### User Story 2 - Legacy deep links fail fast (Priority: P2)

As a tenant admin with old bookmarks, I get a clear failure (not a redirect) when accessing legacy tenant-scoped admin paths, so the system enforces a single set of canonical URLs.

**Why this priority**: Removing redirects is an intentional breaking change; we want predictable behavior and to avoid ongoing maintenance of compatibility shims.

**Independent Test**: Attempt to access representative legacy tenant-scoped admin URLs and confirm they are not handled by the application.

**Acceptance Scenarios**:

1. **Given** an old bookmark to a legacy tenant-scoped admin path, **When** it is requested, **Then** the request returns `404 Not Found` and is not redirected by the application.

---

### User Story 3 - Prevent reintroduction (Priority: P3)

As a developer, I get fast feedback if I accidentally reintroduce removed legacy patterns (identifiers, parameters, route prefixes, or UI copy), so the cleanup remains permanent.

**Why this priority**: Cleanup work regresses easily during refactors; guard tests turn “tribal knowledge” into enforceable rules.

**Independent Test**: Introduce a known legacy identifier in a non-migration file and confirm automated guards fail reliably; remove it and confirm the suite is green again.

**Acceptance Scenarios**:

1. **Given** a change introduces a removed legacy identifier in non-migration code, **When** the automated guard suite runs, **Then** the build fails with an actionable message.

### Edge Cases

- Legacy tenant-scoped paths may still exist in browser history or external references; the application must not rely on redirects to function.
- Previously enqueued background work must continue to process safely during the compatibility window; removal of legacy job fields must not cause noisy runtime behavior.
- Automated legacy scans must explicitly exclude database migration history (migrations are immutable).
- Authorization semantics must not change as a side-effect of cleanup.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature does not introduce new external calls. It does change long-running/queued work APIs (background job payload shape), so it MUST be delivered using a staged rollout to avoid compatibility issues with previously queued payloads.

**Constitution alignment (RBAC-UX):** This feature does not change authorization rules. It removes legacy routes and UI heuristics; access semantics must remain consistent and must not introduce new information leaks.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable.

**Constitution alignment (BADGE-001):** Not applicable.

**Constitution alignment (Filament Action Surfaces):** This feature changes admin UI content and navigation/landing behavior but does not introduce new mutation actions. The Action Surface Contract remains satisfied by existing surfaces.

### Scope (bounded)

- In scope: removal of legacy run artifacts in code, routes, UI copy/heuristics, and tests; addition/extension of guard tests that prevent reintroduction.
- Out of scope: any changes to the canonical operations data model; any new features; any modifications to historical database migrations.

### Assumptions & Dependencies

- Release process supports two deployments/releases for the staged job payload change (compatibility window → final purge).
- Migration history is immutable and excluded from legacy-scanning guards.
- Release notes will communicate removal of legacy deep links.

### Functional Requirements

- **FR-001 (Dead notification removal)**: The unused legacy notification for “backup schedule run dispatched” MUST not exist in active code.
  - **Verification**: A repository-wide scan of non-migration code finds no references to the removed notification artifact.

- **FR-002 (Job API cleanup, staged)**: The backup schedule execution job MUST not require a legacy run identifier at dispatch sites.
  - **FR-002.A (Compatibility release)**: During a compatibility window, older queued payloads MUST still deserialize safely while new dispatches no longer include a dummy legacy run id.
  - **FR-002.B (Final purge)**: After the compatibility window, the legacy parameter/property MUST be removed entirely.
  - **Compatibility window definition**: The compatibility window MUST be considered complete only after Deploy A has been in production for at least 7 calendar days, and the operations team confirms there is no remaining backlog of previously queued backup schedule execution jobs.
  - **Verification**: After final purge, no non-migration code references the legacy run-id field, and dispatch sites do not include placeholder arguments.

- **FR-003 (Inventory landing removal)**: Inventory navigation MUST not rely on redirect-only landing pages or dead views.
  - **Verification**: Inventory entry points route directly to Inventory Items (canonical index), without using a redirect-only landing page.

- **FR-004 (Drift landing copy)**: Drift UI copy MUST not use legacy terminology such as “inventory sync runs”; it MUST use “operation runs”.
  - **Verification**: Drift landing content shows “operation runs” and no legacy phrase remains visible.

- **FR-005 (Legacy redirect routes removal)**: The application MUST not define redirect shims for removed legacy tenant-scoped admin endpoints (e.g. `/admin/t/{tenant:external_id}/operations`).
  - **Verification**: Routing definitions contain no legacy tenant-scoped redirect shims, and requests to the removed legacy endpoints return `404 Not Found`.
  - **Scope note**: At the time of writing, the only known legacy tenant-scoped redirect shim endpoint in `routes/**` is `/admin/t/{tenant:external_id}/operations`. If additional legacy redirect shim endpoints are discovered during implementation, they MUST be added to this spec and covered by tests.

- **FR-006 (Context chrome heuristic removal)**: Context/navigation chrome MUST not infer state from legacy URL patterns.
  - **Verification**: Context chrome behavior is correct without any legacy URL detection logic.

- **FR-007 (Test shim removal)**: Automated tests MUST not rely on legacy model shims or bootstrap hacks that simulate removed legacy domain concepts.
  - **Verification**: Test suite passes without any legacy shim files or bootstrapping.

- **FR-008 (Guard suite)**: Guard tests MUST fail if removed legacy identifiers/patterns are reintroduced outside migration history.
  - **Verification**: Guard suite reliably fails on reintroduction and passes when removed. Scans MUST exclude `database/migrations/**`, `references/**`, and `docs/**`.

- **FR-009 (Migration immutability)**: Database migrations MUST remain unchanged.
  - **Verification**: No migration files are modified as part of this feature.

### Legacy identifiers (verification-only glossary)

The following legacy identifiers/patterns are considered removed and are used only for verification/guarding (outside migrations):

- Notification artifact name: `BackupScheduleRunDispatchedNotification`
- Legacy shim model name: `InventorySyncRun`
- Legacy job field name: `backupScheduleRunId`
- Legacy tenant-scoped deep-link endpoint(s) served by redirect shims (current known set):
  - `/admin/t/{tenant:external_id}/operations`
- Non-legacy note: the tenant-plane prefix `/admin/t/{tenant:external_id}/...` is canonical by itself; only explicitly listed legacy deep-link shim endpoints are treated as removed.
- Legacy UI copy phrase: `inventory sync runs`

### Acceptance Criteria (Definition of Done)

- No active code (excluding database migration history) contains the removed legacy identifiers/patterns.
- No legacy redirect routes exist; legacy tenant-scoped deep links are not supported and return `404 Not Found`.
- Inventory entry points are canonical (no redirect-only landing UI).
- Drift landing copy uses canonical operations terminology.
- Test suite is green; guard tests prevent reintroduction.
- Guard scans explicitly exclude `database/migrations/**`, `references/**`, and `docs/**`.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Drift landing content | Drift entry UI | No change | No change | No change | No change | No change | No change | No change | No | Copy-only change; no action surface impact |
| Inventory navigation entry | Inventory entry UI | No change | No change | No change | No change | No change | No change | No change | No | Remove redirect-only landing behavior |
| Context/navigation chrome | Admin UI chrome | No change | No change | No change | No change | No change | No change | No change | No | Remove legacy URL detection; no actions affected |

### Key Entities *(include if feature involves data)*

- **Background job payloads**: Existing queued payloads may contain legacy fields; staged rollout must maintain compatibility until payloads are drained.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: A canonical navigation walkthrough (Inventory → Drift → Operations/run history → Provider connections) shows no legacy deep-link endpoints/redirect shims and no legacy run terminology.
- **SC-002**: The application defines zero legacy tenant-scoped redirect shim routes, and removed legacy deep links return `404 Not Found`.
- **SC-003**: The automated test suite passes; guard tests fail deterministically when any removed legacy identifier is reintroduced outside migration history.
- **SC-004**: The staged rollout completes with no emergency rollback due to queued job payload incompatibilities.