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](/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/296-full-suite-green-signal-restoration/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)

```text
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:

```text
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:

```bash
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:

```text
.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:

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

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

```bash
./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:

```bash
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:

```bash
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:

```bash
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.