TenantAtlas/specs/234-dead-transitional-residue/spec.md

Feature Specification: Dead Transitional Residue Cleanup

Feature Branch: 234-dead-transitional-residue
Created: 2026-04-23
Status: Draft
Input: User description: "Dead Transitional Residue Cleanup"

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

• Problem: The repo still carries dead transitional residue around tenant truth and baseline profile status language. Deprecated baseline profile status aliases and retired tenant app-status support artifacts still survive in support code, fixtures, and tests even though the current product no longer treats them as active truth.
• Today's failure: Contributors and regressions can still conserve or reintroduce dead semantics because the repo keeps them available as if they were valid current-release language. That weakens earlier tenant-truth cleanup and makes follow-up cleanup strands harder to land cleanly.
• User-visible improvement: Existing tenant and baseline profile surfaces keep the same current truth, but retired app-status and deprecated status-alias semantics stop leaking back through defaults, badges, fixtures, and tests.
• Smallest enterprise-capable version: Remove dead baseline profile status aliases and tenant app-status residue from active runtime support code, factories, seeds, fixtures, and tests after verifying no productive dependency still exists. Do not redesign tenant readiness, baseline semantics, or storage.
• Explicit non-goals: No new readiness model, no new status family, no schema redesign, no provider-connection cleanup beyond the dead tenant app-status residue, no onboarding fallback cleanup, and no canonical operation-type convergence work.
• Permanent complexity imported: None. The feature reduces permanent complexity by removing dead symbols, dead badge semantics, and fixture conservatism while keeping focused regression coverage.
• Why now: This is the first step in the active repository cleanup strand. Leaving dead residue in place makes the next cleanup slices and source-of-truth work riskier because they must keep fighting old semantics that should already be gone.
• Why not local: Deleting only one constant or one test would leave the same dead semantics alive in other seams such as badge registration, factories, browser fixtures, or seed data. The problem is distributed residue, not one stray reference.
• Approval class: Cleanup
• Red flags triggered: One mild red flag: the cleanup spans model, badge, fixture, seed, and test seams. Defense: those seams all conserve the same retired semantics, so one bounded cleanup spec is smaller and safer than several micro-specs.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 2 | Produktnähe: 1 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace + tenant
• Primary Routes:
  • /admin/tenants
  • /admin/tenants/{tenant}
  • /admin/baseline-profiles
  • /admin/baseline-profiles/{profile}
  • /admin/baseline-profiles/{profile}/edit
• Data Ownership:
  • tenants remain the tenant-owned source of lifecycle, provider, and RBAC truth. This feature does not add, remove, or reinterpret tenant lifecycle semantics.
  • baseline_profiles remain the workspace-owned source of baseline profile truth. This feature does not change profile lifecycle behavior; it removes deprecated alias language around that existing truth.
  • No new persisted truth, mirror field, or cleanup ledger is introduced.
• RBAC:
  • Workspace membership remains required for the affected admin resources.
  • Tenant isolation and current capability checks remain unchanged.
  • This feature does not broaden visibility, alter 404 versus 403 semantics, or add new authorization paths.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

N/A - no shared interaction family touched.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no operator-facing surface change. Existing tenant and baseline profile surfaces must keep their current behavior while dead supporting residue is removed.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: No.
• New persisted entity/table/artifact?: No.
• New abstraction?: No.
• New enum/state/reason family?: No.
• New cross-domain UI framework/taxonomy?: No.
• Current operator problem: Dead residue keeps retired semantics available, which makes it easier for tests, fixtures, and future changes to treat them as current truth again.
• Existing structure is insufficient because: The existing structure is the problem; it still contains aliases and support artifacts that no longer represent active product language.
• Narrowest correct implementation: Remove only the dead residue that has no active runtime contract and update the focused regressions that still conserve it.
• Ownership cost: One bounded cleanup pass across affected support code, fixtures, and tests, followed by lower long-term cognitive and maintenance cost.
• Alternative intentionally rejected: Leaving deprecated aliases and legacy support artifacts in place "just in case" was rejected because this is a pre-production repo and the residue already causes semantic drift.
• Release truth: Current-release truth cleanup.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: The proof burden is that existing tenant and baseline profile behaviors still work after dead residue is removed, and that dead semantics no longer survive in active support paths. Focused feature coverage with one small badge-regression slice is sufficient.
• New or expanded test families: Update the existing tenant-truth cleanup regressions, tenant lifecycle domain-separation regressions, baseline profile behavior regressions, and badge catalog regressions. Add a narrow baseline-status cleanup regression only if an existing file cannot express the assertion cleanly.
• Fixture / helper cost impact: Lower overall. Factories, seeds, and browser fixtures should stop carrying dead app-status defaults unless a still-active boundary proves they are needed.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament
• Standard-native relief or required special coverage: Ordinary feature coverage is sufficient. The cleanup must also prove that central badge registration and default fixtures do not conserve retired semantics.
• Reviewer handoff: Reviewers must confirm that no active runtime dependency still needs the removed residue, that tenant and baseline profile behavior remains unchanged for current truth, and that dead semantics are removed rather than rewrapped in a compatibility shim.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantTruthCleanupSpec179Test.php tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineProfileArchiveActionTest.php tests/Feature/Filament/BaselineProfileListFiltersTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/TenantBadgesTest.php tests/Unit/Badges/BadgeCatalogTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

User Scenarios & Testing (mandatory)

User Story 1 - Keep tenant truth free of retired app-status semantics (Priority: P1)

As an operator, I can continue to use tenant surfaces without retired app-status semantics resurfacing through defaults, badges, or seeded examples, so the current lifecycle, provider, and RBAC truth stays trustworthy.

Why this priority: Tenant truth cleanup already happened on primary surfaces. The highest-value part of this cleanup is making sure dead supporting residue cannot silently undo that work.

Independent Test: Can be fully tested by exercising the existing tenant list and tenant detail regressions with records that still contain legacy app-status values and proving that current tenant truth stays unchanged.

Acceptance Scenarios:

1. Given a tenant record still stores a legacy app-status value, When the operator opens the existing tenant list or tenant detail surface, Then that legacy value does not regain current-status meaning.
2. Given seeded or factory-created tenant examples are used in current tenant-truth regressions, When those regressions run after cleanup, Then they no longer depend on app-status defaults to make the surfaces work.
3. Given lifecycle, provider, and RBAC truth already coexist on a tenant surface, When the cleanup is complete, Then those active truths remain separate and unchanged.

---

User Story 2 - Use one baseline profile status language (Priority: P1)

As a maintainer, I can reason about baseline profile state through one canonical status contract, so draft, active, and archived behavior is not split between live status truth and deprecated aliases.

Why this priority: The deprecated baseline profile aliases are explicitly dead residue. Removing them is the cleanest proof that the repo now has one active baseline profile status language.

Independent Test: Can be fully tested by running existing baseline profile archive, list/filter, and view/edit continuity regressions after the deprecated alias language is removed and confirming that current baseline profile behavior stays intact.

Acceptance Scenarios:

1. Given baseline profiles still move through draft, active, and archived behavior today, When existing baseline profile regressions run after cleanup, Then the behavior still works without deprecated status aliases.
2. Given a contributor updates baseline profile logic or tests, When they read current profile status semantics, Then only the canonical status contract is available as active language.
3. Given an operator opens or saves an existing baseline profile through the current view and edit surfaces, When the cleanup is complete, Then those surfaces continue to render and persist through the canonical status contract without depending on deprecated aliases.

---

Cross-Cutting Verification - Prove the residue is fully retired (Release Gate)

As a reviewer, I can verify the cleanup in one focused pass, so the repo does not keep half-dead semantics alive in support code, fixtures, or tests.

Why this priority: Cleanup value is only real if the dead semantics are actually gone rather than merely hidden in one layer.

Release Gate: This verification runs after User Story 1 and User Story 2 are complete and confirms that the touched runtime and test paths no longer expose the retired semantics as active language.

Note: This is not an independently shippable MVP slice; it is the feature-level closeout check that proves the cleanup is complete.

Acceptance Scenarios:

1. Given the cleanup branch, When the reviewer runs the focused validation commands, Then current tenant and baseline profile behaviors still pass without the retired residue.
2. Given a touched support path, fixture, or test previously conserved dead semantics, When the cleanup is reviewed, Then that path is either removed, rewritten to current truth, or explicitly deferred as a follow-up rather than silently preserved.

Edge Cases

• A legacy storage field may still exist historically or in migrations even when it no longer has any active runtime meaning.
• A browser fixture or seeder may still populate a retired value for historical realism; this spec must remove mandatory dependency on that value without changing unrelated fixture intent.
• Some tests may use literal status values rather than deprecated aliases; the cleanup must distinguish current canonical value usage from dead alias usage.
• Central badge registration may still contain dormant legacy entries even when no current surface consumes them; dormant entries count as cleanup scope if they no longer support active truth.
• Baseline profile archive, list, view, and edit behavior must continue to work because the active status contract already exists independently of the deprecated aliases.

Requirements (mandatory)

Constitution alignment (required): This feature adds no Microsoft Graph calls, no long-running work, and no new write workflow. It is a bounded runtime and test cleanup over existing tenant and baseline profile truth.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces no new persistence, abstraction, state family, or semantic layer. It removes dead structure that no longer represents current-release truth.

Constitution alignment (XCUT-001): Not applicable. The feature does not add or modify a shared operator interaction family.

Constitution alignment (TEST-GOV-001): Focused feature and badge-regression coverage is the narrowest sufficient proof because the business risk is dead semantics surviving in active support paths, not a new workflow or surface family.

Constitution alignment (RBAC-UX): No authorization behavior changes. Existing workspace membership, tenant isolation, and capability enforcement remain authoritative.

Constitution alignment (BADGE-001): Centralized badge semantics remain authoritative. If the retired tenant app-status badge domain has no active consumer, it must be removed centrally rather than replaced with any page-local or test-local mapping.

Constitution alignment (UI-FIL-001): No new Filament screen, action surface, or custom markup is introduced. Existing tenant and baseline profile surfaces must continue to rely on their current native presentation.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature removes dead interpretation residue rather than adding another semantic layer. Tests must prove current business truth survives while the residue disappears.

Functional Requirements

• FR-234-001: The system MUST remove deprecated baseline profile status aliases from active runtime language once the cleanup proves no productive dependency remains.
• FR-234-002: The system MUST treat the canonical baseline profile status contract as the only active source of draft, active, and archived profile semantics.
• FR-234-003: The system MUST remove retired tenant app-status support residue from active badge registration, factory defaults, browser fixtures, seeds, and tests when those paths no longer serve a current runtime contract.
• FR-234-004: Existing tenant list and tenant detail behavior MUST remain unchanged for current lifecycle, provider, and RBAC truth after the retired residue is removed.
• FR-234-005: Existing baseline profile list, view, edit, and archive behavior MUST remain unchanged for current profile status truth after deprecated aliases are removed.
• FR-234-006: Every removed residue item MUST be checked for hidden runtime, UI, filter, cast, policy, or API dependency before deletion.
• FR-234-007: If a hidden dependency is found, the dependency MUST be documented and moved to a follow-up cleanup decision rather than preserving the residue as silent compatibility lore.
• FR-234-008: The feature MUST NOT introduce compatibility aliases, fallback readers, migration shims, or new legacy fixtures to preserve removed residue.
• FR-234-009: The feature MUST NOT introduce a new readiness model, new status family, new cleanup ledger, or any other replacement semantic layer.
• FR-234-010: Historical storage or migration remnants MAY remain only as historical artifacts and MUST NOT regain default-visible operator meaning.
• FR-234-011: Focused regression coverage MUST prove both tenant-truth continuity and baseline-profile continuity after the cleanup.
• FR-234-012: The feature MUST stay bounded to dead transitional residue cleanup and MUST NOT absorb onboarding fallback retirement, provider-connection legacy cleanup, or canonical operation-type convergence.

Key Entities (include if feature involves data)

• Canonical baseline profile status: The active status language that already governs baseline profile lifecycle behavior.
• Deprecated baseline profile status aliases: Retired alias constants that mirror current profile statuses but no longer represent active repo truth.
• Tenant app-status residue: Retired support artifacts around a legacy tenant-level status signal that current tenant surfaces no longer treat as authoritative.
• Residual support artifacts: Factories, fixtures, seeds, tests, and badge registrations that can conserve dead semantics even when primary product surfaces no longer use them.

Success Criteria (mandatory)

Measurable Outcomes

• SC-234-001: In acceptance review, no targeted tenant surface or supporting default path reintroduces tenant app-status as current truth.
• SC-234-002: 100% of targeted tenant-truth regressions pass after the retired tenant app-status residue is removed.
• SC-234-003: 100% of targeted baseline profile regressions pass after the deprecated baseline profile status aliases are removed.
• SC-234-004: The cleanup ships without adding any new persistence, status family, compatibility shim, or replacement semantic layer.

Assumptions

• The current baseline profile status contract is already sufficient for existing profile behavior.
• Existing tenant surfaces no longer require app-status to express current tenant truth.
• Historical migration files may retain old field names or values as history without counting as active runtime truth.

Non-Goals

• Dropping legacy database columns in this slice
• Redesigning tenant readiness, provider readiness, or baseline readiness semantics
• Performing onboarding fallback retirement
• Performing provider-connection legacy cleanup outside the dead tenant app-status residue
• Resolving the canonical operation-type source-of-truth conflict

Dependencies

• Existing tenant lifecycle, provider, and RBAC truth separation on current tenant surfaces
• Existing baseline profile behavior and current baseline profile status contract
• Existing focused regressions for tenant truth, baseline profile behavior, and central badge registration

Definition of Done

• Deprecated baseline profile status aliases are gone from active runtime language.
• Retired tenant app-status residue is gone from active badge registration, default fixtures, seeds, and tests unless an explicit still-active dependency is documented.
• Existing tenant and baseline profile behaviors remain unchanged for current truth.
• No new compatibility path or replacement status layer was introduced.
• Focused regression coverage passes.