TenantAtlas/specs/087-legacy-runs-removal/spec.md

# Feature Specification: Legacy Runs Removal

**Feature Branch**: `087-legacy-runs-removal`  
**Created**: 2026-02-12  
**Status**: Draft  
**Input**: User description: "Spec 087 — Legacy Runs Removal (RIGOROS)"

## Clarifications

### Session 2026-02-12

- Q: Should we backfill legacy run history into the canonical run system before dropping legacy tables? → A: No backfill (accept losing pre-existing legacy run history)
- Q: Should backup schedule retention/purge produce canonical run records? → A: Yes — retention and purge each produce their own canonical runs
- Q: Which canonical run_type contract should be enforced? → A: Use the explicit list: inventory_sync, drift_generate_findings, entra_group_sync, backup_schedule_run, backup_schedule_retention, backup_schedule_purge
- Q: For canonical run URLs, should access be 404 for non-members and 403 for members missing capability? → A: Yes — non-member/not entitled → 404; member missing capability → 403
- Q: How broad should the “NoLegacyRuns” architecture guard scan be? → A: Scan app/, database/, resources/, and routes/ (exclude specs/ and references/)

## Redirect Scope

This spec’s “no redirects” requirement applies to legacy *run* pages and legacy run UI surfaces.

The existing convenience route that redirects the tenant-scoped operations index to the canonical operations index (for example: `/admin/t/{tenant}/operations` → `/admin/operations`) is not considered a legacy run page.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Single canonical run history (Priority: P1)

As a workspace member, I can see and open run history for inventory sync, Entra group sync, and backup schedules in a single, consistent place, without having to navigate multiple legacy run screens.

**Why this priority**: Removes duplicated tracking and inconsistent UX, and reduces confusion about which “run” is authoritative.

**Independent Test**: Trigger each run type once and verify it appears in the canonical Operations run list and can be opened via the canonical run detail view.

**Acceptance Scenarios**:

1. **Given** a workspace member with permission to view operations, **When** a new inventory sync run starts and finishes, **Then** a corresponding canonical run exists and is viewable via the canonical Operations UI.
2. **Given** a workspace member with permission to view operations, **When** a new Entra group sync run starts and finishes, **Then** a corresponding canonical run exists and is viewable via the canonical Operations UI.
3. **Given** a workspace member with permission to view operations, **When** a backup schedule run starts and finishes, **Then** a corresponding canonical run exists and is viewable via the canonical Operations UI.

---

### User Story 2 - Legacy run UI is intentionally gone (Priority: P1)

As a workspace member, I cannot access legacy run pages anymore. Old links intentionally fail, so there is no ambiguity about where runs are viewed.

**Why this priority**: Prevents “run sprawl” and ensures there is exactly one canonical run UI.

**Independent Test**: Attempt to access any known legacy run route and verify it is not available.

**Acceptance Scenarios**:

1. **Given** a user (any role), **When** they attempt to access a legacy run URL, **Then** the application responds as not found.
2. **Given** the application navigation, **When** a user browses the admin UI, **Then** no legacy run resources appear in navigation.

---

### User Story 3 - Drift references canonical runs (Priority: P1)

As a workspace member using drift-related features, I see baseline/current references tied to canonical runs, and drift logic does not depend on a legacy run store.

**Why this priority**: Drift currently has structural coupling to a legacy run concept; removing it reduces risk and complexity.

**Independent Test**: Create drift findings that reference baseline/current runs and confirm the references use canonical runs (or are empty if historical data cannot be mapped).

**Acceptance Scenarios**:

1. **Given** drift findings created after this feature ships, **When** a user views baseline/current references, **Then** the references point to canonical runs.
2. **Given** historical drift findings where no safe mapping exists, **When** a user views baseline/current references, **Then** the UI remains functional and references are empty rather than erroring.

---

### Edge Cases

- Historical runs exist with details that were only stored in legacy run records, and this history will not be backfilled into canonical runs.
- A user is a non-member of the workspace and attempts to view a run.
- A user is a workspace member but lacks the capability to view operations.
- A scheduled backup run is skipped/cancelled and still needs a canonical run record with a clear final outcome.
- Retention/purge runs remove old data; the user expects runs to remain auditable and consistent.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature changes long-running work and run tracking. It MUST ensure run observability via the canonical run system, consistent identity, and workspace-scoped visibility.

**Constitution alignment (RBAC-UX):** This feature changes run visibility and removes legacy pages. It MUST explicitly define not-found vs forbidden behavior and enforce authorization server-side.

**Constitution alignment (BADGE-001):** Any run status-like badges MUST be derived from canonical run status/outcome to keep semantics centralized.

**Constitution alignment (Filament Action Surfaces):** This feature removes legacy run resources and updates run links to point to the canonical operations views.

### Functional Requirements

- **FR-001**: The system MUST treat the canonical run system as the single source of truth for all run tracking and display.
- **FR-002**: The system MUST NOT create or update legacy run records for inventory sync, Entra group sync, or backup schedule runs.
- **FR-003**: The system MUST remove all legacy run UI surfaces (resources/pages/relation managers/badges) so that runs are only accessible from the canonical Operations UI.
- **FR-004**: Requests to legacy run pages MUST behave as not found (no redirects).
- **FR-005**: Drift-related entities MUST reference canonical runs for baseline/current/last-seen run linkage.
- **FR-006**: Backup schedule retention/purge workflows MUST operate without relying on legacy run stores.
- **FR-007**: Entra group sync run history and links MUST reference canonical runs only.
- **FR-008**: The system MUST enforce workspace-first access rules for canonical run list and detail views:
  - non-member or not entitled to the workspace scope → not found (404)
  - member but missing capability → forbidden (403)
- **FR-009**: Automated architecture checks MUST prevent reintroduction of legacy run concepts by failing CI if legacy tokens are found anywhere in: `app/`, `database/`, `resources/`, `routes/`.
- **FR-010**: The system MUST NOT backfill historical legacy run records into the canonical run system; only new runs are guaranteed to be represented as canonical runs.
- **FR-011**: Backup schedule retention and purge executions MUST each create their own canonical run records, observable in the canonical Operations UI.
- **FR-012**: The system MUST standardize and enforce the canonical `run_type` identifiers for runs created by this feature:
  - `inventory_sync`
  - `drift_generate_findings`
  - `entra_group_sync`
  - `backup_schedule_run`
  - `backup_schedule_retention`
  - `backup_schedule_purge`

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Operations run list | Admin UI | None | Filtered list + open run | View | None | None | N/A | N/A | Yes (via canonical runs) | All run types converge here |
| Operations run detail | Admin UI | None | N/A | N/A | None | None | None | N/A | Yes (via canonical runs) | Single canonical view for run details |
| Backup schedule detail | Admin UI | None | Links to canonical runs | View | None | None | N/A | N/A | Yes | Legacy run tab removed |

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

- **Operation Run**: A canonical record representing a long-running operation, including type, status, timestamps, context, and summary.
- **Drift Finding**: A drift detection result that may reference baseline and current runs.
- **Inventory Item**: An inventory record that may reference the last run in which it was observed.
- **Backup Schedule**: A recurring configuration that triggers backup operations and may trigger retention/purge operations.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% of new inventory sync, Entra group sync, and backup schedule executions produce exactly one canonical run record that is visible in the canonical Operations run list.
- **SC-002**: Legacy run pages are not accessible (attempts to access legacy run URLs result in not found).
- **SC-003**: Drift creation and drift UI flows do not depend on legacy run stores; baseline/current references resolve to canonical runs when mappings exist.
- **SC-004**: The automated architecture guard blocks reintroduction of legacy run concepts and fails the build when legacy tokens reappear.
- **SC-005**: Backup schedule retention/purge workflows complete successfully without legacy run stores and are observable through canonical runs.
- **SC-006**: Each retention and each purge execution produces a canonical run record (independent from the associated backup schedule run).

## Assumptions

- Historical legacy-only run details do not need to be preserved; pre-existing legacy run history may be lost after legacy tables are removed.
- The canonical Operations UI already exists and is the single supported run viewer.

## Dependencies

- Workspace-scoped run access rules remain enforced consistently across list and detail views.