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

Feature Specification: Full Suite Green Signal Restoration

Feature Branch: 296-full-suite-green-signal-restoration
Created: 2026-05-11
Status: Draft
Input: User-provided Spec 296 prompt: restore the complete platform test suite as a trustworthy green CI signal after Specs 293, 294, and 295.

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

• Problem: The raw platform test suite is still red after targeted cutover and provider-verification stabilization work. Maintainers cannot trust a full-suite failure as a clear CI signal because stale expectations, missing workspace or panel context, browser drift, heavy-governance drift, RBAC assertion drift, and possible true runtime bugs are still mixed together.
• Today's failure: Spec 295 recorded a red raw suite (450 failed, 8 skipped, 4194 passed) and red lane splits. Without Spec 296, maintainers either ignore red full-suite output or risk "fixing" tests by restoring retired /admin/t/... or TenantPanel semantics, weakening RBAC, or hiding browser/heavy failures.
• User-visible improvement: Maintainers get a green full-suite signal, or a tightly controlled default-CI signal where every non-default failure is classified with explicit lane ownership and no hidden product/runtime bug.
• Smallest enterprise-capable version: A stabilization pass that inventories failures, protects the Spec 288/293/294 guard lanes first, fixes stale tests and proven small runtime bugs, documents every lane decision, and ends with the raw full suite green unless only justified browser/heavy/external cases remain outside the default lane.
• Explicit non-goals: No new product feature, no TenantPanelProvider reactivation, no /admin/t/... compatibility route, no broad runtime refactor, no new provider abstraction, no new migrations unless a hard runtime correctness bug proves one is unavoidable, no mass skips, and no screenshot baseline churn as a side effect.
• Permanent complexity imported: Spec-local failure inventory, fix log, lane decision log, and browser evidence log. No new runtime model, table, enum, provider registry, UI framework, or persisted truth is planned.
• Why now: Specs 293, 294, and 295 narrowed the suite failure space and proved the remaining raw-suite signal is still unusable. Full-suite trust is now the blocker before more feature work can rely on CI.
• Why not local: Individual test-file repairs cannot restore the suite as a signal unless each red group is classified, guard lanes are protected, browser/heavy decisions are documented, and the final validation proves default/full-suite behavior.
• Approval class: Core Enterprise.
• Red flags triggered: Broad surface area and suite-governance scope. Defense: the scope is repair/classification of existing tests and small proven bugs only; it adds spec-local artifacts, not runtime architecture.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Spec Scope Fields (mandatory)

• Scope: canonical-view test-suite-governance.
• Primary Routes: No new routes. Existing route families that may be validated or repaired in tests include /admin/workspaces/{workspace}/operations, /admin/workspaces/{workspace}/operations/{run}, /admin/workspaces/{workspace}/environments, and current admin-panel Filament resource routes.
• Data Ownership: No new application data ownership. Existing workspace-owned and tenant-owned records may be created in tests as fixtures only. Spec-local markdown artifacts are preparation/implementation evidence, not product truth.
• RBAC: Capability-first RBAC remains authoritative. Non-member workspace or managed-environment access remains deny-as-not-found (404). Established members missing capability remain 403. No role-string backdoor checks may be introduced.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Operation and monitoring assertions must preserve workspace context and tenant entitlement. Tenant-bound OperationRun rows may appear only when the actor is entitled to the referenced workspace and managed environment.
• Explicit entitlement checks preventing cross-tenant leakage: Tests that assert operation links, resource URLs, relation-manager actions, or browser navigation must seed or assert workspace membership, managed-environment access, and session workspace context explicitly.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): test lane reporting, failure classification, operation links, Filament resource URLs, browser evidence, action visibility, RBAC assertions.
• Systems touched: scripts/platform-test-lane, apps/platform/tests/Support/TestLaneManifest.php, apps/platform/tests/Pest.php, App\Support\OperationRunLinks, existing Filament resources/pages, existing policies, existing browser smoke tests, and spec-local artifacts.
• Existing pattern(s) to extend: Spec 295 lane reporting/failure classification; Spec 293 cutover failure classification; Spec 294 provider-verification classification; existing OperationRunLinks; existing WorkspaceContext; existing setAdminPanelContext().
• Shared contract / presenter / builder / renderer to reuse: OperationRunLinks, WorkspaceContext::SESSION_KEY, Filament panel: 'admin' URL generation, existing Pest groups and TestLaneManifest lanes.
• Why the existing shared path is sufficient or insufficient: Existing shared paths are sufficient for route, panel, lane, and OperationRun link truth. Failures should be repaired by using them correctly or by fixing narrow bugs in those owners if proven.
• Allowed deviation and why: None by default. Wrong-lane or environment/browser-only decisions may be documented in lane-decisions.md only after proof.
• Consistency impact: Raw suite, lane splits, failure inventory, fix log, browser evidence, and final validation must tell the same story about what is green, what was fixed, and what was intentionally classified outside the default suite.
• Review focus: Confirm no restored legacy routes, no hidden skips, no security weakening, no unclassified red group, and no screenshot baseline churn without documented evidence.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes, as a protected contract in tests; no new UX behavior is planned.
• Shared OperationRun UX contract/layer reused: App\Support\OperationRunLinks and current monitoring/operation pages.
• Delegated start/completion UX behaviors: Existing canonical operation URLs and Open operation/View operation labels remain delegated to shared helpers.
• Local surface-owned behavior that remains: Test fixtures and expectations only.
• Queued DB-notification policy: N/A - no new queued notification behavior.
• Terminal notification path: N/A - no new terminal notification behavior.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes, as a protected guardrail.
• Boundary classification: mixed. Provider runtime remains provider-owned; platform-core route, lane, RBAC, and OperationRun contracts remain platform-core.
• Seams affected: ProviderConnections tests, Verification tests, provider operation start semantics, provider capability assertions, provider-neutral copy assertions, lane classification artifacts.
• Neutral platform terms preserved or introduced: provider connection, managed environment, workspace, operation, capability, verification, evidence.
• Provider-specific semantics retained and why: Microsoft-specific semantics may remain only inside provider-owned test fixtures or provider-specific assertions. They must not become platform-core route, RBAC, or operation truth.
• Why this does not deepen provider coupling accidentally: The spec forbids broad provider abstraction and limits provider changes to rebaseline/fix work proven by existing provider-boundary tests.
• Follow-up path: Document-in-feature for contained rebaselines; follow-up-spec only for structural provider-boundary drift not safe to repair within the stabilization loop.

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Test and fixture repairs	no direct product surface change	N/A	test lanes, route helpers, panel context	test context only	no	Existing surfaces may be asserted but not redesigned.
Small proven runtime bug fix	only if a true bug is proven	Existing native/shared path must remain	affected existing owner only	existing page/resource/helper	no by default	Any broader surface change requires spec/plan update before continuing.
Browser screenshot evidence	no unless baseline update is explicitly approved by evidence	N/A	browser lane	screenshot artifact only	possible documented exception	Evidence screenshots are not committed unless browser-evidence.md explains why the new baseline is correct.

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

No new operator-facing surface is planned. If implementation proves a runtime UI bug, the changed existing surface must preserve its current decision role and update this spec before any broader UI change.

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

N/A - no new customer, operator, or support disclosure surface is planned. Existing browser or Filament tests must preserve current customer/operator/support boundaries.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

N/A - no new list, detail, queue, audit, config, or report surface is planned. Existing Filament resources/pages may only receive narrow correctness fixes if a test proves current runtime is wrong.

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

N/A - no new operator-facing page or workflow is planned.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no product source of truth. Spec-local artifacts are implementation evidence only.
• New persisted entity/table/artifact?: no persisted application entity. New markdown artifacts are required spec-local evidence.
• New abstraction?: no.
• New enum/state/reason family?: no runtime state. Failure classifications are spec-local and bounded to this stabilization effort.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: maintainers cannot trust the full test suite or default CI signal.
• Existing structure is insufficient because: Spec 295 classified the suite red but intentionally did not repair product/test failures; the raw suite remains unusable until the remaining groups are fixed or explicitly re-laned.
• Narrowest correct implementation: classify first, fix smallest proven root-cause clusters, document every lane decision, and validate full suite or controlled default CI.
• Ownership cost: implementation-time maintenance of four spec-local evidence files plus test/lane validation notes.
• Alternative intentionally rejected: pausing feature work while accepting a red full suite; mass skipping; restoring legacy tenant routes; or creating a new permanent CI framework.
• Release truth: current-release cleanup and quality gate restoration.

Compatibility posture

This feature assumes the repo's pre-production lean doctrine. Legacy aliases, compatibility routes, dual-write logic, historical fixtures, and /admin/t/... compatibility paths are forbidden unless a separate approved spec amends the cutover truth.

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

• Test purpose / classification: Feature, Heavy-Governance, Browser, and full-suite validation. Unit only where a small helper/guard owner is directly fixed.
• Validation lane(s): raw full suite, fast-feedback, confidence, heavy-governance, browser, Spec 288 guard lane, Spec 293 cutover lane, Spec 294 ProviderConnections/Verification lane.
• Why this classification and these lanes are sufficient: The goal is the complete suite signal. Guard lanes must remain green because they protect cutover, provider boundary, browser-lane isolation, CI classification, and no-role-string RBAC truth.
• New or expanded test families: none by default. Existing tests may be rebaselined, repaired, removed as obsolete, or moved only with documented lane decisions.
• Fixture / helper cost impact: Minimal by default. Workspace, managed-environment, capability, provider, and browser fixtures must be explicit and used only where the assertion requires them.
• Heavy-family visibility / justification: Heavy-governance and browser failures are explicit in this spec because Spec 295 identified them as red. No hidden promotion into fast-feedback is allowed.
• Special surface test profile: standard-native-filament, surface-guard, browser, and monitoring-state-page only for existing tests that already prove those contracts.
• Standard-native relief or required special coverage: Use ordinary Feature/Livewire/Filament tests for stale expectations; use browser lane only for real browser/layout/screenshot behavior.
• Reviewer handoff: Reviewers must confirm Livewire v4/Filament v5 compliance, provider registration remains in apps/platform/bootstrap/providers.php, global search rules are unchanged or explicitly verified, destructive actions keep confirmation and authorization, assets strategy is unchanged unless documented, and tests cover pages/actions/widgets via Livewire where applicable.
• Budget / baseline / trend impact: Full suite and lane runtimes may change; any material runtime or lane movement must be documented in lane-decisions.md or fix-log.md.
• Escalation needed: document-in-feature for contained wrong-lane or obsolete-test decisions; follow-up-spec for any remaining non-green structural class.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.
• Planned validation commands:

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

Plus the Spec 288 and Spec 293 lanes listed in the acceptance criteria below, and browser lane if any browser file or screenshot baseline is touched.

User Scenarios & Testing (mandatory)

User Story 1 - Inventory The Red Suite Before Repairs (Priority: P1)

As a test maintainer, I want the raw full suite and fallback lanes captured before fixes so I can distinguish root causes from incidental output noise.

Why this priority: Fixes without a failure inventory risk hiding product bugs or reintroducing retired compatibility behavior.

Independent Test: failure-inventory.md contains every observed group from the baseline and each row has owner area, classification, fix type, validation command, and final status.

Acceptance Scenarios:

1. Given the raw full suite is red, When the baseline command is run, Then the pass/fail/skipped counts and first observed command are recorded.
2. Given raw output is too broad or truncated, When lane splits are run, Then each lane outcome is recorded and grouped into root-cause clusters.

---

User Story 2 - Protect Guard Lanes Before Broad Repairs (Priority: P1)

As a platform quality owner, I want the Spec 288, Spec 293, and Spec 294 guard lanes green before broader suite repairs so critical workspace, cutover, provider, and RBAC contracts do not regress.

Why this priority: A green full suite is not trustworthy if it weakens isolation, provider boundaries, or cutover truth.

Independent Test: The guard lane commands pass or any red group is fixed before lower-priority suite debt.

Acceptance Scenarios:

1. Given a guard lane fails, When the implementation loop starts, Then that guard lane is repaired before unrelated confidence/heavy/browser work.
2. Given a fix could make a guard pass by restoring /admin/t/..., When reviewed, Then the fix is rejected and reworked to current workspace-first truth.

---

User Story 3 - Fix Root-Cause Clusters Without Legacy Regression (Priority: P1)

As a maintainer, I want root-cause clusters repaired in priority order so stale tests, route drift, panel context drift, RBAC assertion drift, provider-boundary drift, browser drift, and heavy-governance drift are handled deliberately.

Why this priority: The failure groups from Spec 295 share root causes; repairing them one by one without cluster discipline wastes time and can create contradictory baselines.

Independent Test: Each root-cause cluster has at least one focused reproduction command, a documented classification, a minimal fix, a focused validation command, and a lane/full-suite revalidation step.

Acceptance Scenarios:

1. Given a test expects /admin/operations without workspace, When repaired, Then it uses the workspace-aware route or canonical OperationRunLinks helper.
2. Given a Filament resource URL is generated without panel context, When repaired, Then the test uses admin panel context or explicit panel: 'admin'.
3. Given an RBAC expectation differs between hidden, disabled, forbidden, not found, and redirect, When repaired, Then the owning policy/page/action is read before deciding whether the test or runtime is wrong.

---

User Story 4 - Make Browser And Lane Decisions Explicit (Priority: P2)

As a reviewer, I want browser evidence and lane decisions documented so browser-only, heavy-only, obsolete, wrong-lane, and default-suite tests are not mixed or skipped without proof.

Why this priority: Full-suite restoration must not be achieved by silent skips or by committing screenshot baselines as incidental evidence.

Independent Test: lane-decisions.md and browser-evidence.md explain every moved/skipped/browser baseline decision and confirm no product bug is hidden.

Acceptance Scenarios:

1. Given a browser screenshot is generated by a failing smoke test, When it is used only as evidence, Then it is copied to /tmp/tenantpilot-296-browser-evidence and not committed.
2. Given a test is skipped or moved out of the default suite, When reviewed, Then lane-decisions.md explains the lane, reason, and proof that no real product bug is hidden.

---

User Story 5 - Publish A Final Green Or Controlled Default Signal (Priority: P1)

As a CI owner, I want the final result to state whether the raw full suite is green or whether default CI is controlled-green with every remaining class explicitly outside default scope.

Why this priority: The end state must be operationally useful, not merely a partial lane success.

Independent Test: Final validation commands pass and the final response reports full-suite status, guard lane status, provider/verification status, browser status, Pint, git diff --check, changed file classes, screenshots, root causes fixed, rebaselined tests, moved/skipped tests, residual errors, cutover status, and CI-signal status.

Acceptance Scenarios:

1. Given all tests are in the raw suite, When ./vendor/bin/sail artisan test --compact is run, Then it passes.
2. Given only browser/heavy/external-runtime cases remain outside default, When default CI is claimed green, Then every exception is documented, lane-owned, and not a hidden runtime bug.

Edge Cases

• Raw full-suite output is too long or truncated: use lane splits and JUnit/report artifacts, but do not skip raw-suite validation at the end unless a documented stop condition exists.
• A stale test can be made green by restoring /admin/t/...: forbidden; update the test to retired-route behavior or current workspace route truth.
• A Filament action assertion fails because an action is disabled instead of hidden: read the resource/page/policy before deciding whether the current UX contract is hidden, disabled, 403, 404, redirect, or absent.
• A browser screenshot changes because the page is broken: fix runtime or test expectation; do not commit the baseline as evidence.
• A test appears obsolete or duplicate: document the reason, owning lane, and product contract before removing or skipping.
• A narrow runtime bug requires a code fix: update spec/plan if the fix broadens beyond local correctness.

Requirements (mandatory)

• FR-296-001: Implementation MUST begin with git branch --show-current, git status --short, and git diff --stat, and MUST stop if unrelated uncommitted changes are present.
• FR-296-002: Implementation MUST read .specify/memory/constitution.md plus Specs 293, 294, and 295 failure-classification/task artifacts before repairs.
• FR-296-003: Implementation MUST run or intentionally document the baseline result for cd apps/platform && ./vendor/bin/sail artisan test --compact.
• FR-296-004: If raw output is not classifiable, implementation MUST run the existing lane splits: fast-feedback, confidence, heavy-governance, and browser.
• FR-296-005: failure-inventory.md MUST include test file, test name, failure summary, first observed command, owner area, classification, fix type, fixed now, follow-up required, validation command, and final status.
• FR-296-006: Failure classifications MUST use only the pinned classification values in failure-inventory.md unless spec/plan/tasks are updated first.
• FR-296-007: Spec 288 guard lane MUST be green before lower-priority suite repair continues, unless the guard lane failure is itself the in-progress root-cause owner.
• FR-296-008: Spec 293 cutover regression lane MUST be green before lower-priority suite repair continues, unless the cutover lane failure is itself the in-progress root-cause owner.
• FR-296-009: Spec 294 ProviderConnections/Verification lane MUST be green before lower-priority suite repair continues, unless the provider lane failure is itself the in-progress root-cause owner.
• FR-296-010: Runtime MUST NOT restore TenantPanelProvider product truth, /admin/t/... compatibility routes, or /admin/operations tenantless fallback assumptions.
• FR-296-011: Operation route fixes MUST preserve workspace-aware admin.operations.index and admin.operations.view URLs and prefer OperationRunLinks where it is the canonical helper.
• FR-296-012: Filament resource/page URL fixes in tests MUST use current admin-panel context or explicit panel: 'admin' when required.
• FR-296-013: RBAC fixes MUST preserve capability-first authorization, deny-as-not-found for non-members, 403 for established members missing capability, and no role-string checks.
• FR-296-014: Destructive actions touched by runtime or test fixes MUST continue to execute via ->action(...), require confirmation, and enforce authorization server-side.
• FR-296-015: Provider-boundary fixes MUST keep provider-specific semantics bounded and MUST re-run tests/Feature/ProviderConnections tests/Feature/Verification after any provider-related change.
• FR-296-016: Browser failures MUST be documented in browser-evidence.md; screenshot baselines MUST NOT be committed unless the file and rationale are explicitly documented.
• FR-296-017: Lane moves, skips, obsolete-test decisions, and wrong-lane decisions MUST be documented in lane-decisions.md with proof that no product/runtime bug is hidden.
• FR-296-018: fix-log.md MUST record every changed file, why it changed, whether it is test or runtime, which product contract it protects, and which validation ran.
• FR-296-019: Final validation MUST include raw full suite, Spec 288 guard lane, Spec 293 cutover lane, Spec 294 provider/verification lane, Pint dirty formatting, and git diff --check.
• FR-296-020: If raw full suite is not green, the final state MUST meet controlled default CI criteria: default CI lane green, all remaining non-green cases classified outside default, no hidden runtime bug, and no unclassified red group.

Success Criteria (mandatory)

• SC-296-001: Preferred outcome: cd apps/platform && ./vendor/bin/sail artisan test --compact exits green.
• SC-296-002: Spec 288 guard lane exits green.
• SC-296-003: Spec 293 cutover regression lane exits green.
• SC-296-004: Spec 294 ProviderConnections/Verification lane exits green.
• SC-296-005: ./vendor/bin/sail bin pint --dirty --format agent exits green after PHP changes, and git diff --check exits green.
• SC-296-006: failure-inventory.md, fix-log.md, lane-decisions.md, and browser-evidence.md are complete and internally consistent with final validation output.
• SC-296-007: No runtime change weakens workspace isolation, tenant isolation, capability-first RBAC, provider boundaries, OperationRun execution truth, or Filament v5/Livewire v4 assumptions.
• SC-296-008: No screenshot baseline is committed without documented browser evidence and rationale.
• SC-296-009: No skipped, deleted, moved, or wrong-lane test lacks a documented reason.
• SC-296-010: Final response explicitly states whether the full suite is green and whether the suite is again a trustworthy CI signal.

Required Validation Commands

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

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

./vendor/bin/sail artisan test --compact \
  tests/Feature/Guards/Spec288NoLegacyRouteAndHelperGuardTest.php \
  tests/Feature/Guards/Spec288ProviderCoreAndRoleAuthorityGuardTest.php \
  tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php \
  tests/Feature/Guards/ProviderBoundaryPlatformCoreGuardTest.php \
  tests/Feature/ProviderConnections/LegacyRedirectTest.php \
  tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php \
  tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php \
  tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php \
  tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php \
  tests/Feature/Guards/BrowserLaneIsolationTest.php \
  tests/Feature/Guards/CiLaneFailureClassificationContractTest.php \
  tests/Feature/Guards/CiHeavyBrowserWorkflowContractTest.php \
  tests/Unit/Auth/NoRoleStringChecksTest.php

./vendor/bin/sail artisan test --compact \
  tests/Feature/Filament/PanelNavigationSegregationTest.php \
  tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php \
  tests/Feature/OpsUx/CanonicalViewRunLinksTest.php \
  tests/Feature/OpsUx/OperateHubShellTest.php \
  tests/Feature/OpsUx/FailureSanitizationTest.php \
  tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php \
  tests/Feature/RequiredPermissions/RequiredPermissionsLegacyRouteTest.php \
  tests/Feature/Guards/ActionSurfaceContractTest.php \
  tests/Feature/ProviderConnections/NavigationPlacementTest.php \
  tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php

./vendor/bin/sail bin pint --dirty --format agent
git diff --check

If browser files or screenshots are affected:

./scripts/platform-test-lane browser

Assumptions

• Specs 293, 294, and 295 are present in the current branch and represent the repo truth for prior stabilization work.
• Laravel Sail is the preferred local test runtime.
• Filament remains v5 and Livewire remains v4; provider registration remains in apps/platform/bootstrap/providers.php.
• Current workspace-first route truth is canonical; retired tenant-panel route shapes are not a compatibility target.
• The full suite may be long-running; lane splits may be used for classification, but final full-suite proof remains preferred.

Risks

• The raw full suite may expose more groups than Spec 295 observed.
• Browser failures may include both true product bugs and screenshot evidence churn.
• A small-looking RBAC assertion drift may be a security bug and must be investigated before rebaseline.
• Fixing many stale tests can accidentally widen fixture setup or move heavy work into fast lanes.
• Controlled default CI could be misused as a partial-green claim; this spec requires every exception to be explicit.

Open Questions

None blocking preparation. During implementation, every new red group must be added to failure-inventory.md before repair.