TenantAtlas/specs/205-compare-job-cleanup/spec.md

Feature Specification: Compare Job Legacy Drift Path Cleanup

Feature Branch: 205-compare-job-cleanup
Created: 2026-04-14
Status: Draft
Input: User description: "Compare Job Legacy Drift Path Cleanup"

• Type: Cleanup / closure hardening
• Priority: Medium
• Depends on: Spec 203 - Baseline Compare Engine Strategy Extraction
• Related to: Spec 202 - Governance Subject Taxonomy and Baseline Scope V2; Spec 204 - Platform Core Vocabulary Hardening
• Recommended timing: Immediate close-out before the next expansion-focused strand
• Blocks: No strategic work
• Does not block: Further platform work if completed as a short closure PR

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: The baseline compare orchestration unit still retains an obsolete pre-strategy drift computation block that no longer reflects how compare execution actually works.
• Today's failure: Contributors and reviewers must spend time proving which compare path is live, while architecture audits still see false monolithic coupling that has already been structurally replaced.
• User-visible improvement: No operator workflow changes, but the codebase becomes more trustworthy, easier to audit, and faster to maintain because the live compare architecture is no longer obscured by dead logic.
• Smallest enterprise-capable version: Remove the dead legacy drift block and its exclusively related helpers, clean direct fallout such as unused dependencies and misleading internal descriptions, and confirm that the current strategy-driven compare behavior remains unchanged.
• Explicit non-goals: No new abstraction, no naming sweep, no evidence-contract redesign, no schema change, no UI change, no new strategy, and no opportunistic follow-up refactor.
• Permanent complexity imported: None beyond minimal regression coverage or comment cleanup needed to lock in the deletion.
• Why now: Specs 202, 203, and 204 already established the current architecture. Leaving the old drift block behind keeps the pre-expansion foundation structurally dishonest even though the behavioral migration is complete.
• Why not local: A narrower action than deletion would still leave the same dead-path ambiguity in place, so the architectural trust gap would remain.
• Approval class: Cleanup
• Red flags triggered: Scope-creep risk if broader naming or architecture work is mixed into the cleanup.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 1 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace, tenant
• Primary Routes:
  • No new or changed routes
  • Existing verification anchors remain:
    • /admin/t/{tenant}/baseline-compare
    • /admin/operations
    • /admin/operations/{run}
• Data Ownership:
  • Existing tenant-owned compare runs, findings, summaries, and warnings remain authoritative.
  • No new persistence, ownership boundary, or data shape is introduced.
• RBAC:
  • Existing compare, monitoring, and tenant access rules remain unchanged.
  • No new membership rule, capability, or operator-facing action is introduced.
  • No destructive action behavior changes are included.

Assumptions & Dependencies

• Spec 203 already made strategy-driven compare execution the authoritative live path for the baseline compare orchestration unit.
• The retained legacy drift block is not part of the productive call graph and can be removed without functional redesign.
• Any test or inspection logic that still depends on deleted internal helper structure is considered stale and may be narrowed to current observable behavior.
• Successful completion depends on focused regression coverage for strategy dispatch, compare execution, finding lifecycle behavior, summary computation, gap handling, warning handling, and run completion.

User Scenarios & Testing (mandatory)

User Story 1 - Read the live compare architecture without dead-path noise (Priority: P1)

As a contributor reviewing baseline compare behavior, I want the orchestration unit to show only the active compare path so that I can understand current architecture without first disproving a retained legacy path.

Why this priority: This is the core value of the cleanup. If the dead path remains visible, the repository continues to teach the wrong architecture.

Independent Test: Inspect the orchestration unit after cleanup and confirm that only the active strategy-driven path remains while regression checks still pass.

Acceptance Scenarios:

1. Given the compare orchestration unit currently contains both live orchestration and retained legacy drift remnants, When a contributor reviews the file after cleanup, Then they can trace one active compare execution path without encountering a parallel legacy implementation.
2. Given a reviewer follows the productive compare call graph after cleanup, When they inspect the orchestration flow, Then the repository no longer suggests that the removed pre-strategy drift logic is still active.

---

User Story 2 - Preserve current compare behavior while removing dead code (Priority: P1)

As a product maintainer, I want the dead-code removal to leave compare behavior unchanged so that the cleanup can merge as a safe closure PR rather than another hidden refactor.

Why this priority: The cleanup is only valuable if it preserves the current compare lifecycle and does not force a second architecture review.

Independent Test: Run focused automated regression checks for the current compare flow and confirm that expected outcomes remain unchanged after the delete.

Acceptance Scenarios:

1. Given existing baseline compare regression coverage, When the cleanup lands, Then strategy selection, compare execution, finding generation, summary computation, gap handling, warning handling, recurrence behavior, and run completion remain green.
2. Given a compare run that already uses the current strategy infrastructure, When it executes after cleanup, Then it produces the same class of persisted results and operator-observable outcomes as before.

---

User Story 3 - Keep the review diff mechanically narrow (Priority: P2)

As a reviewer, I want the cleanup diff to stay limited to dead-path deletion and its direct fallout so that I can approve it quickly without re-reviewing unrelated architecture decisions.

Why this priority: The main delivery risk is not deletion itself, but that the cleanup grows into an opportunistic mixed refactor.

Independent Test: Inspect the resulting PR scope and confirm that it is limited to CompareBaselineToTenantJob, the focused compare guard and regression files that prove the delete is safe, and only direct blocker-driven follow-up in BaselineCompareService or IntuneCompareStrategy if the implementation explicitly justifies it.

Acceptance Scenarios:

1. Given nearby follow-up ideas exist, When the cleanup is implemented, Then the final diff touches CompareBaselineToTenantJob, the focused compare guard and regression files, and no other production file except a direct blocker-driven follow-up in BaselineCompareService or IntuneCompareStrategy.
2. Given adjacent imports, comments, or docblocks still imply the removed path exists, When the cleanup finishes, Then only those directly obsolete remnants are adjusted and no unrelated rename, schema, or UI work appears in the same PR.

Edge Cases

• A seemingly legacy helper still has an indirect productive call site or compatibility responsibility.
• A regression test or inspection helper still asserts deleted internal structure instead of current compare behavior.
• Summary, warning, or finding behavior depends on normalization that must remain preserved through the active path even after the dead block is removed.
• Internal comments or docblocks still describe a fallback or alternate drift path that no longer exists.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce a new external integration, new write pathway, or new long-running workflow. It removes dead internal compare logic from an existing execution unit and keeps existing tenant isolation, run observability, and audit behavior unchanged. Regression coverage must prove there is no behavior change.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The cleanup introduces no new persistence, abstraction, state family, or semantic layer. The narrowest correct implementation is deletion of the dead path and cleanup of its direct fallout.

Constitution alignment (OPS-UX): Existing run creation, lifecycle ownership, summary-count rules, and three-surface feedback behavior remain unchanged. Any touched regression coverage must continue to protect the current compare run lifecycle.

Constitution alignment (RBAC-UX): No authorization behavior changes are part of this feature. Existing workspace and tenant access rules, including current 404 and 403 behavior, remain untouched.

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

Constitution alignment (BADGE-001): Not applicable; no status or badge semantics change.

Constitution alignment (UI-FIL-001): Not applicable; no Filament or Blade surface changes are introduced.

Constitution alignment (UI-NAMING-001): Operator-facing labels remain unchanged. Only misleading internal comments or docblocks may be corrected.

Constitution alignment (DECIDE-001): No new or changed operator-facing decision surface is introduced.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): No surface or action changes are in scope.

Constitution alignment (ACTSURF-001 - action hierarchy): Not applicable; no header, row, or bulk action structure changes are introduced.

Constitution alignment (OPSURF-001): Not applicable; no operator-facing surface is added or materially refactored.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature removes redundant legacy logic instead of adding a new interpretation layer. Tests stay focused on behavior and architectural truth rather than thin indirection.

Constitution alignment (Filament Action Surfaces): Not applicable.

Constitution alignment (UX-001 - Layout & Information Architecture): Not applicable.

Functional Requirements

• FR-205-001 Single active compare path: The baseline compare orchestration unit MUST retain only the active strategy-driven compare execution path.
• FR-205-002 Legacy drift removal: The obsolete pre-strategy drift computation block retained in the orchestration unit MUST be removed.
• FR-205-003 Helper cleanup: Any helper method, local utility, or internal dependency used exclusively by the removed legacy path MUST also be removed.
• FR-205-004 Truthful dependency surface: After cleanup, imports, comments, and docblocks in the orchestration unit MUST reflect only currently active dependencies and behavior.
• FR-205-005 No behavioral reshaping: The cleanup MUST NOT change strategy selection, compare execution, finding generation, summary computation, gap handling, warning handling, recurrence behavior, reason handling, or run completion behavior.
• FR-205-006 No speculative follow-up work: The cleanup MUST NOT introduce new abstractions, naming generalizations, schema changes, UI changes, or unrelated refactors.
• FR-205-007 Regression proof: Automated regression coverage MUST demonstrate that the active strategy-driven compare path still executes correctly after the cleanup.
• FR-205-008 Call-graph safety: Before the cleanup is considered complete, the removed legacy path and its exclusive helpers MUST have no remaining productive call sites in the surrounding production code.

Non-Functional Requirements

• NFR-205-001 Reviewability: The resulting change set MUST be limited to CompareBaselineToTenantJob, the focused compare guard and regression files needed to prove delete safety, and only direct blocker-driven follow-up in BaselineCompareService or IntuneCompareStrategy when explicitly justified.
• NFR-205-002 Architectural honesty: After cleanup, an architecture review of the compare orchestration unit MUST find one authoritative compare execution path rather than a retained parallel legacy implementation.

Success Criteria (mandatory)

Measurable Outcomes

• SC-205-001: A contributor can inspect the compare orchestration unit and identify a single active compare execution path without needing to rule out a retained parallel legacy path.
• SC-205-002: Focused automated checks covering the current strategy-driven compare flow pass after the cleanup with no newly introduced failures.
• SC-205-003: Review of the cleanup diff shows touched files limited to CompareBaselineToTenantJob, the focused compare guard and regression files, and at most a direct blocker-driven follow-up in BaselineCompareService or IntuneCompareStrategy.
• SC-205-004: Post-cleanup architecture review no longer reports a retained pre-strategy drift computation block in the compare orchestration unit.