TenantAtlas/specs/296-full-suite-green-signal-restoration/plan.md

Implementation Plan: Full Suite Green Signal Restoration

Branch: 296-full-suite-green-signal-restoration | Date: 2026-05-11 | Spec: spec.md
Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/296-full-suite-green-signal-restoration/spec.md

Summary

Spec 296 restores the platform test suite as a trustworthy CI signal. The implementation starts with a raw full-suite baseline, falls back to existing lane splits when raw output is too broad, protects the Spec 288/293/294 guard lanes first, repairs root-cause clusters in priority order, documents every fix and lane decision, and ends with the raw full suite green unless only controlled, justified browser/heavy/external-runtime cases remain outside the default suite.

This plan is preparation only. It does not implement application code.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail 1.52.0
Storage: PostgreSQL through Laravel/Sail for tests; no new storage planned
Testing: Pest via ./vendor/bin/sail artisan test --compact; browser lane via existing ./scripts/platform-test-lane browser
Validation Lanes: raw full suite, fast-feedback, confidence, heavy-governance, browser, Spec 288 guard lane, Spec 293 cutover lane, Spec 294 ProviderConnections/Verification lane
Target Platform: Laravel Sail local test runtime; Gitea-compatible CI signal
Project Type: Laravel web application under apps/platform plus repository-level lane scripts
Performance Goals: Restore trust in existing suite/lane output without adding hidden heavy defaults; document any material lane runtime or budget drift
Constraints: No TenantPanelProvider reactivation, no /admin/t/... compatibility routes, no broad runtime refactor, no security/RBAC weakening, no mass skips, no incidental screenshot baseline commits
Scale/Scope: Existing test suite and lane manifests only; no new product surface

UI / Surface Guardrail Plan

• Guardrail scope: workflow/test-suite guardrail change; no planned operator-facing surface change.
• Native vs custom classification summary: N/A for planned work. Any proven UI runtime fix must preserve existing Filament-native/shared patterns.
• Shared-family relevance: test lanes, browser evidence, action-surface tests, operation links, Filament resource URL generation.
• State layers in scope: test context, session workspace context, Filament panel context, route parameters, screenshot artifacts.
• Audience modes in scope: N/A for planned changes; existing surfaces must preserve operator/customer/support disclosure boundaries.
• Decision/diagnostic/raw hierarchy plan: Use existing surfaces; no new hierarchy.
• Raw/support gating plan: Preserve existing capability/policy gating.
• One-primary-action / duplicate-truth control: Preserve existing action-surface contracts; do not add UI actions to make tests pass.
• Handling modes by drift class or surface: stale-test-expectation and route/panel context drift are repairable in tests; true-runtime-bug is repairable only in the owning local seam; browser/environment/wrong-lane requires documented lane decision.
• Repository-signal treatment: review-mandatory for guard lanes, browser screenshots, skips, obsolete tests, wrong-lane moves, and any RBAC/security drift.
• Special surface test profiles: standard-native-filament, surface-guard, monitoring-state-page, browser.
• Required tests or manual smoke: focused Pest reruns for touched files, affected lane reruns, final full suite, browser lane when browser files are touched.
• Exception path and spread control: Any lane move or skip must be listed in lane-decisions.md; any screenshot baseline update must be listed in browser-evidence.md.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: apps/platform/tests/Pest.php, apps/platform/tests/Support/TestLaneManifest.php, scripts/platform-test-lane, scripts/platform-test-report, scripts/platform-test-artifacts, App\Support\OperationRunLinks, App\Support\Workspaces\WorkspaceContext, existing Filament resources/pages/policies/tests.
• Shared abstractions reused: OperationRunLinks, WorkspaceContext::SESSION_KEY, setAdminPanelContext(), Filament panel: 'admin' URL generation, TestLaneManifest lane definitions, existing Pest groups.
• New abstraction introduced? why?: none.
• Why the existing abstraction was sufficient or insufficient: Existing helpers encode current product truth. Spec 296 should fix tests that bypass them or narrow owner bugs where the helper/runtime is proven wrong.
• Bounded deviation / spread control: none by default; document any wrong-lane or environment-only decision in spec-local artifacts.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes as an assertion surface, not as a new UX behavior.
• Central contract reused: App\Support\OperationRunLinks, OperationRun policies, Monitoring/Operations pages.
• Delegated UX behaviors: operation index/view URL generation and Open operation labels remain in shared helpers.
• Surface-owned behavior kept local: test data setup and focused assertions.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes as a guardrail and possible test/runtime repair seam.
• Provider-owned seams: ProviderConnections resource behavior, provider operation start gate, verification/health check fixtures, provider credential/capability fixtures.
• Platform-core seams: workspace route parameters, OperationRun links, lane classification, RBAC semantics, managed-environment access, provider-neutral labels at shared boundaries.
• Neutral platform terms / contracts preserved: provider, connection, workspace, managed environment, operation, capability, verification.
• Retained provider-specific semantics and why: Microsoft-specific fixture content may remain inside Microsoft-provider tests only.
• Bounded extraction or follow-up path: document-in-feature for contained provider test rebaselines; follow-up-spec for structural provider-boundary drift.

Constitution Check

GATE: Must pass before Phase 0 baseline. Re-check after final validation.

• Inventory-first: no new inventory or snapshot truth.
• Read/write separation: no new product writes. Existing destructive/mutating actions touched by tests must keep preview/confirmation/audit/authorization contracts.
• Graph contract path: no new Graph calls. Provider/verification fixes must not bypass existing contracts.
• Deterministic capabilities: capability-first tests and registries must remain authoritative; no role-string checks.
• RBAC-UX: /admin and /system planes remain separate; non-member workspace/tenant access remains 404; established member missing capability remains 403; UI visibility remains non-security.
• Workspace isolation: workspace context is explicit in route generation, session setup, operation links, and resource tests.
• Tenant isolation: managed-environment access remains entitlement-scoped.
• Run observability: OperationRun remains execution truth; operation links use canonical workspace-aware URLs.
• Test governance: every changed test or lane decision must record purpose, lane, fixture cost, heavy/browser visibility, validation command, and escalation decision.
• Proportionality: spec-local evidence artifacts are narrow and temporary; no runtime structure is introduced.
• No premature abstraction: no new factories, registries, presenters, lane framework, or provider abstraction.
• Persisted truth: no new application persistence.
• Behavioral state: no new runtime state/status/reason family.
• Shared pattern first: reuse OperationRunLinks, WorkspaceContext, TestLaneManifest, and existing Filament test helpers.
• Provider boundary: do not spread Microsoft-specific language or semantics into platform core.
• Filament-native UI: any touched Filament page/resource must remain v5-compatible with Livewire v4; no ad-hoc UI redesign.
• Filament UI Action Surface Contract: destructive actions require ->requiresConfirmation() and server-side authorization; action-surface tests must not be rebaselined blindly.
• Deployment/ops: no runtime asset registration is planned. If any Filament asset registration is unexpectedly changed, deploy notes must include cd apps/platform && php artisan filament:assets.

Test Governance Check

• Test purpose / classification by changed surface: Feature for route/RBAC/panel tests; Heavy-Governance for surface/discovery/action breadth; Browser for real browser/screenshot behavior; Unit only for narrow helper guards.
• Affected validation lanes: raw full suite, fast-feedback, confidence, heavy-governance, browser, Spec 288, Spec 293, Spec 294.
• Why this lane mix is the narrowest sufficient proof: The full suite is the target signal; guard lanes prove critical invariants; focused files prove local fixes before broad reruns.
• Narrowest proving command(s): focused ./vendor/bin/sail artisan test --compact <file> first, then affected lane, then final full suite and required guard lanes.
• Fixture / helper / factory / seed / context cost risks: workspace/session/provider fixtures may grow if copied carelessly; all expensive setup must stay explicit and local.
• Expensive defaults or shared helper growth introduced?: no planned shared default changes.
• Heavy-family additions, promotions, or visibility changes: none by default. Any move/skip is documented in lane-decisions.md.
• Surface-class relief / special coverage rule: standard-native relief for unchanged Filament surfaces; dedicated browser lane for screenshots/layout.
• Closing validation and reviewer handoff: run final commands in spec.md and confirm all artifacts agree with command output.
• Budget / baseline / trend follow-up: document any material lane runtime drift; do not relax budgets without evidence.
• Review-stop questions: Did a fix restore legacy routes? Did it weaken RBAC? Did it hide a browser/runtime bug behind a skip? Did it commit screenshots without rationale? Did it add heavy defaults?
• Escalation path: document-in-feature for contained lane/screenshot decisions; follow-up-spec for structural remaining red class; reject-or-split for hidden product scope.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.
• Why no dedicated follow-up spec is needed: The goal is specifically to close the follow-up created by Spec 295. Remaining structural non-green classes must not be hidden; they become explicit follow-up specs only if controlled default CI is used.

Project Structure

Documentation (this feature)

specs/296-full-suite-green-signal-restoration/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── tasks.md
├── failure-inventory.md
├── fix-log.md
├── lane-decisions.md
├── browser-evidence.md
└── checklists/
    └── requirements.md

Source Code (repository root)

Expected touched surfaces during implementation are tests and small owner files only if proven:

apps/platform/tests/
├── Feature/
├── Browser/
├── Unit/
└── Pest.php

apps/platform/app/
├── Support/
├── Policies/
└── Filament/

apps/platform/routes/web.php
scripts/
├── platform-test-lane
├── platform-test-report
└── platform-test-artifacts

Structure Decision: Use existing Laravel app, existing Pest tests, existing Spec Kit artifacts, and existing lane scripts. No new base directory or application dependency is planned.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Broad test-suite stabilization scope	Spec 295 proved the remaining full-suite failures span route, panel, RBAC, provider, browser, and heavy lanes	A narrow single-file fix would not restore the full-suite CI signal or classify remaining default-suite exceptions
Additional spec-local evidence artifacts	The user explicitly requires failure inventory, fix log, lane decisions, and browser evidence to prevent hidden skips and screenshot churn	A single tasks.md checklist would not preserve root-cause and lane-decision accountability during a long repair loop

Phase 0: Safety Gate

1. Run:

git branch --show-current
git status --short
git diff --stat

2. Confirm branch is 296-full-suite-green-signal-restoration.
3. Stop if unrelated uncommitted changes exist.
4. Read:

.specify/memory/constitution.md
specs/293-post-cutover-suite-stabilization/failure-classification.md
specs/294-provider-verification-runtime-semantics/failure-classification.md
specs/295-full-suite-ci-baseline/failure-classification.md
specs/295-full-suite-ci-baseline/tasks.md

Phase 1: Baseline Snapshot

Run:

cd apps/platform
./vendor/bin/sail artisan test --compact

If raw output is too long or not classifiable, run:

./scripts/platform-test-lane fast-feedback
./scripts/platform-test-lane confidence
./scripts/platform-test-lane heavy-governance
./scripts/platform-test-lane browser

Populate failure-inventory.md before any repair.

Phase 2: Guard Lanes First

Run and repair red groups before lower-priority work:

• Spec 288 guard lane from spec.md
• Spec 293 cutover regression lane from spec.md
• Spec 294 ProviderConnections/Verification lane:

cd apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification

Phase 3: Root-Cause Cluster Order

Repair in this order:

1. Legacy Cutover Test Debt
2. Workspace Route / Operation URL Drift
3. Filament Panel Context / Resource URL Drift
4. RBAC / Capability / Authorization Drift
5. Provider Boundary / Provider Operation Restdrift
6. Browser Lane Failures
7. Heavy Governance / Summary Count / Relation Manager UI Drift

For each cluster: reproduce one focused failure, read owner code, classify, fix minimally, rerun focused file, rerun affected lane, update failure-inventory.md and fix-log.md.

Phase 4: Lane And Browser Decisions

• Keep default suite tests in default unless a test is proven browser/heavy/external-runtime-only.
• Document moved/skipped/obsolete tests in lane-decisions.md.
• Copy browser evidence to /tmp/tenantpilot-296-browser-evidence.
• Do not commit screenshot baselines unless browser-evidence.md explicitly says why the new baseline is correct.

Phase 5: Full Suite Green Loop

Run:

cd apps/platform
./vendor/bin/sail artisan test --compact

If red, add new groups to failure-inventory.md, repair the smallest next root cause, and repeat.

Phase 6: Final Validation

Required:

cd apps/platform
./vendor/bin/sail artisan test --compact
./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification
./vendor/bin/sail bin pint --dirty --format agent
git diff --check

Also run the Spec 288 and Spec 293 command blocks from spec.md. Run browser lane if browser files or screenshots changed.

Filament v5 / Livewire v4 Review Contract

• Livewire v4.0+ compliance: required; installed version is Livewire 4.1.4.
• Provider registration location: Laravel 12 panel providers stay in apps/platform/bootstrap/providers.php; do not register panel providers in bootstrap/app.php.
• Global search: no planned resource additions. For any touched globally searchable resource, verify it has an Edit or View page, or global search is disabled.
• Destructive actions: any touched destructive action must still use ->action(...), ->requiresConfirmation(), and server-side authorization.
• Asset strategy: no asset registration is planned. If registered assets change, deployment must include cd apps/platform && php artisan filament:assets; otherwise N/A.
• Testing plan: Livewire/Filament pages, resources, relation managers, and actions are tested through existing Livewire/Pest patterns, not by mounting static resource classes.

Rollout Considerations

• No env vars planned.
• No migrations planned.
• No queue/cron changes planned.
• No storage volume changes planned, except transient browser evidence under /tmp.
• CI/Gitea impact is limited to restored default/full-suite signal and any documented lane classification update.

Stop Conditions

• Unrelated dirty worktree before implementation.
• Guard lane red group that cannot be fixed without changing product scope.
• A required runtime fix expands beyond a local owner seam.
• A security/RBAC failure would require weakening authorization to pass.
• Browser or heavy failures remain but cannot be honestly classified into default/controlled lanes.