TenantAtlas/specs/388-resolution-proof-currentness-contract-v1/plan.md

# Implementation Plan: Spec 388 - Resolution Proof & Currentness Contract v1

**Branch**: `388-resolution-proof-currentness-contract-v1` | **Date**: 2026-06-19 | **Spec**: `specs/388-resolution-proof-currentness-contract-v1/spec.md`
**Input**: Feature specification from `/specs/388-resolution-proof-currentness-contract-v1/spec.md`

## Summary

Harden the existing Spec 386/387 Review Publication Resolution workflow with a bounded proof/currentness contract. Replace or extend the current shallow proof resolver output so step planning and proof disclosure can distinguish current, stale, superseded, missing, running, failed, inaccessible, and usable proof. Keep source truth in existing domain objects, avoid new persistence by default, and do not create a generic proof registry or broad adapter framework.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1
**Storage**: PostgreSQL via Sail; no schema migration approved by default
**Testing**: Pest 4 unit, feature, Filament/Livewire, optional focused browser smoke
**Validation Lanes**: fast-feedback + confidence; browser if rendered proof states materially change; PostgreSQL only if schema changes after spec update
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: web application / Filament admin panel
**Performance Goals**: deterministic local DB evaluation; no Graph/provider calls during UI render; avoid N+1 proof lookup
**Constraints**: no generic workflow engine, no global proof adapter registry, no new proof source-of-truth table, no auto-publish, no customer proof explorer, no new panel/provider/route family
**Scale/Scope**: one existing subject-owned Review Publication Resolution workflow and related proof display

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed state/proof presentation on existing surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `App\Filament\Resources\EnvironmentReviewResource\Pages\ResolveReviewPublication`
  - `apps/platform/resources/views/filament/resources/environment-review-resource/pages/resolve-review-publication.blade.php`
  - existing Environment Review detail only if it consumes proof summary changes
  - existing Customer Review Workspace negative no-leakage tests only
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: existing Filament page + existing Blade disclosure + native Filament badges/actions.
- **Shared-family relevance**: proof/status messaging, OperationRun links, artifact links, readiness labels, customer-safe disclosure.
- **State layers in scope**: page, proof disclosure, current step state.
- **Audience modes in scope**: operator-MSP, manager, readonly inspector, support-platform; customer/read-only only for no-leakage regression.
- **Decision/diagnostic/raw hierarchy plan**: decision-first proof label and next action; diagnostics in collapsed technical proof; raw/support payloads absent.
- **Raw/support gating plan**: no raw provider/report/evidence content; safe reason code and safe summary only.
- **One-primary-action / duplicate-truth control**: proof state informs the one current step action; technical proof links stay secondary.
- **Handling modes by drift class or surface**: review-mandatory for proof-state display and no-leakage; report-only for UI audit files unless rendered structure materially changes.
- **Repository-signal treatment**: UI-101 and Spec 387 screenshot evidence are context; update only if visible state/copy structure changes.
- **Special surface test profiles**: workflow-detail surface with proof-state smoke; standard-native-filament relief for unchanged action placement.
- **Required tests or manual smoke**: proof state mapping, stale/superseded display, readonly limited proof, customer no-leakage.
- **Exception path and spread control**: no generic proof UI framework; local/bounded mapper only.
- **Active feature PR close-out entry**: Proof Currentness / No Generic Registry / Smoke Coverage.
- **UI/Productization coverage decision**: update `docs/ui-ux-enterprise-audit/page-reports/ui-101-review-publication-resolution.md` only when visible structure/copy changes; otherwise record no-new-route/no-archetype rationale.
- **Coverage artifacts to update**: likely none or UI-101 only; route inventory/design matrix should not change.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no provider registration or panel path changes; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: yes only for representative changed proof states; Feature/Livewire evidence may substitute for hard-to-fixture states with an artifact note.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, bounded to one workflow.
- **Systems touched**:
  - `App\Support\ReviewPublicationResolution\ReviewPublicationProofResolver`
  - `ReviewPublicationReadinessEvaluator`
  - `ReviewPublicationStepPlanner`
  - `ReviewPublicationResolutionService`
  - `ResolveReviewPublication`
  - `ReviewPublicationResolutionCase` / `ReviewPublicationResolutionStep`
  - existing OperationRun link/actionability/reconciliation classes as context only
  - `EvidenceSnapshot`, `StoredReport`, `EnvironmentReview`, `ReviewPack`
- **Shared abstractions reused**:
  - existing review-publication resolver/evaluator/planner/service
  - existing readiness fingerprint from Spec 386
  - existing OperationRun UX/link helpers
  - existing policies, `UiEnforcement`, and Filament components
- **New abstraction introduced? why?**: yes, bounded proof evaluation DTO/value-object and enum/value set are expected because current arrays cannot encode currentness/usability/visibility safely.
- **Why the existing abstraction was sufficient or insufficient**: existing workflow ownership is sufficient; existing proof array fields are insufficient to prevent stale, superseded, inaccessible, or diagnostics-only proof from driving completion.
- **Bounded deviation / spread control**: keep new classes under existing `App\Support\ReviewPublicationResolution` or a clearly review-publication-owned child namespace. Do not introduce global `ProofRegistry`, `GlobalProofAdapterRegistry`, `WorkflowProofEngine`, or broad `Support/ResolutionProof` package without updating spec/plan/tasks first.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes for classification/display only; no new start/completion behavior.
- **Central contract reused**: existing OperationRun service lifecycle, OperationRun links, Spec 386 step execution behavior, and terminal notification path.
- **Delegated UX behaviors**: queued toast, run link, artifact link, run-enqueued event, dedupe messaging, terminal notification, and safe URL resolution remain delegated to existing paths.
- **Surface-owned behavior kept local**: deciding whether an existing run is current, superseded, failed, running, diagnostics-only, or not enough without artifact proof.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes, platform proof vocabulary over provider-backed artifacts.
- **Provider-owned seams**: raw Microsoft/Graph identifiers, provider payloads, provider-specific report internals, credential/permission mechanics.
- **Platform-core seams**: proof, artifact, operation, currentness, usability, visibility, safe summary, readiness fingerprint.
- **Neutral platform terms / contracts preserved**: proof, currentness, artifact, operation, subject, action, workspace, managed environment, safe summary.
- **Retained provider-specific semantics and why**: required report keys such as permission posture and Entra admin roles remain existing review requirements but stay out of customer-safe proof mechanics.
- **Bounded extraction or follow-up path**: follow-up-spec only when Restore, Provider, Governance Inbox, or Report Delivery has a real proof/currentness consumer.

## Constitution Check

- Inventory-first: no inventory truth changes.
- Read/write separation: no external write path is added; existing step actions keep Spec 386/387 confirmation, authorization, audit, and tests.
- Graph contract path: no Graph calls added; proof evaluation consumes existing DB-backed artifacts.
- Deterministic capabilities: proof visibility uses existing policies/capabilities; no raw capability strings unless existing pattern requires.
- RBAC-UX: workspace/environment access remains deny-as-not-found; missing capability remains safe limited/forbidden state.
- Workspace isolation: proof candidates must resolve through workspace scope before use/display.
- Tenant isolation: managed-environment proof must match environment-scoped subject/action.
- Run observability: OperationRun remains execution truth; no new operation type or lifecycle transition.
- OperationRun start UX: no local queued toast/link/event/start-state composition.
- Ops-UX lifecycle: no direct `OperationRun.status` / `OperationRun.outcome` mutation outside existing services.
- Data minimization: no raw provider payload, raw report content, full evidence JSON, token, secret, or raw exception in proof summary/audit/UI.
- Test governance: Unit/Feature/Filament coverage first; browser only for representative UI state smoke.
- Proportionality: new proof DTO/enums are justified by false-blocker/false-confidence risk in current workflow; no new persistence by default.
- No premature abstraction: no registry or broad adapter framework; review-publication-owned classes only.
- Persisted truth: existing domain objects and resolution steps remain truth; proof evaluation is derived.
- Behavioral state: new proof states affect step completion, actionability, visibility, audit metadata, or operator next action.
- UI semantics: proof labels are direct mappings from normalized proof result to existing UI; no cross-domain presentation framework.
- Shared pattern first: existing resolver/evaluator/planner/page and OperationRun helpers are extended.
- Provider boundary: provider-specific details stay internal/diagnostic and are sanitized.
- V1 explicitness / few layers: small explicit value objects/helpers; no generalized platform package.
- Badge semantics: existing Filament/shared badge semantics; no ad-hoc independent color system.
- Filament-native UI: existing Filament page and Blade disclosure remain; no new custom UI system.
- UI/Productization coverage: existing UI-101 coverage reused/updated proportionally.
- Filament v5 / Livewire v4: implementation must remain Livewire 4.1.4 compatible and avoid Livewire v3 APIs.
- Panel provider registration: no panel provider changes; Laravel 12 providers remain in `apps/platform/bootstrap/providers.php`.
- Global search: no Resource is added; no proof evaluation global search surface is introduced.
- Destructive/high-impact actions: no new action approved. Existing step/cancel actions remain `->action(...)`, `->requiresConfirmation()`, authorized, audited, and tested.
- Asset strategy: no registered Filament assets expected; no `filament:assets` deploy change unless implementation unexpectedly registers assets and updates this plan first.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for pure proof evaluation and fingerprint helpers; Feature for planner/service/currentness/RBAC/customer leakage; Filament/Livewire for proof-state display and action state; Browser for representative visible proof-state smoke if UI changes.
- **Affected validation lanes**: fast-feedback, confidence, optional browser.
- **Why this lane mix is the narrowest sufficient proof**: the risk is deterministic evaluation and safe workflow display over existing DB-backed records, not new provider execution or broad surface discovery.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReviewPublicationResolution tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec388ReviewPublicationProofCurrentnessSmokeTest.php` if a browser file is added
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: reuse existing Spec 386/387 fixtures and `apps/platform/tests/Pest.php`; avoid global setup defaults or broad provider context.
- **Expensive defaults or shared helper growth introduced?**: no by default.
- **Heavy-family additions, promotions, or visibility changes**: none planned.
- **Surface-class relief / special coverage rule**: workflow-detail surface; browser optional for representative proof states; no full UI audit/browser matrix.
- **Closing validation and reviewer handoff**: verify proof states affect behavior, no generic framework/persistence, no customer leakage, no raw payloads, and no local OperationRun lifecycle rewrites.
- **Budget / baseline / trend follow-up**: none expected; document-in-feature if browser fixture scope grows materially.
- **Review-stop questions**: Did stale proof fail closed? Did newer current artifact supersede old failure? Did successful run require artifact proof? Did visibility enforce RBAC? Did customer output stay clean?
- **Escalation path**: document-in-feature for bounded fixture gaps; follow-up-spec for cross-domain proof consumers.
- **Active feature PR close-out entry**: Proof Currentness / No Generic Registry / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: this is the dedicated review-publication proof-currentness hardening slice; broader adapters are explicitly deferred.

## Project Structure

### Documentation (this feature)

```text
specs/388-resolution-proof-currentness-contract-v1/
+-- checklists/
|   +-- requirements.md
+-- plan.md
+-- spec.md
+-- tasks.md
```

### Source Code (repository root)

```text
apps/platform/app/Support/ReviewPublicationResolution/
+-- ReviewPublicationProofResolver.php
+-- ReviewPublicationReadinessEvaluator.php
+-- ReviewPublicationStepPlanner.php
+-- ReviewPublicationResolutionService.php
+-- ReviewPublicationResolutionStepAuthorizer.php
+-- ReviewPublicationResolutionStepKey.php
+-- ReviewPublicationResolutionStepStatus.php
+-- ResolutionProofEvaluation.php
+-- ResolutionProofReference.php
+-- ResolutionProofStatus.php
+-- ResolutionProofCurrentness.php
+-- ResolutionProofUsability.php
+-- ResolutionProofVisibility.php

apps/platform/app/Models/
+-- ReviewPublicationResolutionCase.php
+-- ReviewPublicationResolutionStep.php
+-- EnvironmentReview.php
+-- EvidenceSnapshot.php
+-- StoredReport.php
+-- ReviewPack.php
+-- OperationRun.php

apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/
+-- ResolveReviewPublication.php
+-- ViewEnvironmentReview.php

apps/platform/resources/views/filament/resources/environment-review-resource/pages/
+-- resolve-review-publication.blade.php

apps/platform/tests/Unit/Support/ReviewPublicationResolution/
+-- ResolutionProofEvaluationTest.php
+-- ReviewPublicationProofResolverTest.php

apps/platform/tests/Feature/EnvironmentReview/
+-- Spec386ReviewPublicationResolutionWorkflowTest.php
+-- Spec387ReviewPublicationResolutionDecisionUxTest.php
+-- Spec388ReviewPublicationProofCurrentnessTest.php

apps/platform/tests/Browser/
+-- Spec388ReviewPublicationProofCurrentnessSmokeTest.php (only if browser coverage is added)

docs/ui-ux-enterprise-audit/page-reports/
+-- ui-101-review-publication-resolution.md (only if visible structure/copy materially changes)
```

**Structure Decision**: Use existing Laravel/Filament app structure and existing `App\Support\ReviewPublicationResolution` ownership. Do not create a new base package, registry, global adapter system, Resource, navigation entry, panel provider, or standalone readiness fingerprint abstraction. Fingerprint work extends the existing readiness evaluator/helper behavior from Spec 386 unless spec/plan/tasks are updated first.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| New proof state/value set | Current workflow needs distinct current/stale/superseded/visibility/usability behavior to avoid false completion/blockers | Existing `proof_status` string cannot govern currentness, actor visibility, or artifact-backed completion safely |
| New DTO/value object | Step planner/page/audit need one safe shape rather than ad hoc arrays | Adding labels to current arrays would keep logic duplicated and untestable |

## Proportionality Review

- **Current operator problem**: stale failed runs, stale artifacts, inaccessible proof, and successful runs without artifacts can mislead resolution workflow decisions.
- **Existing structure is insufficient because**: `ReviewPublicationProofResolver::proofFor()` returns only `proof_type`, `proof_id`, `proof_status`, and `operation_run_id`; it cannot represent currentness, supersession, usability, or actor-safe visibility.
- **Narrowest correct implementation**: evaluate only Review Publication Resolution step proof and use existing readiness fingerprint/artifact records.
- **Ownership cost created**: maintain enum/value mapping, safe-summary rules, resolver tests, and UI/audit mapping.
- **Alternative intentionally rejected**: local UI-only wording changes; they would not prevent incorrect step completion or false blockers.
- **Release truth**: current-release trust hardening for an implemented workflow.

## Domain / Model Implications

- Existing models remain source truth.
- Proof evaluation is derived; do not add a table.
- Existing `review_publication_resolution_steps` proof fields may continue storing safe references. If implementation proves `proof_currentness`, `proof_usability`, or `proof_evaluated_at` must be persisted, update spec/plan/tasks first and add a reversible PostgreSQL-safe migration.
- Prefer safe timestamps/fingerprints already present on EnvironmentReview, EvidenceSnapshot, StoredReport, ReviewPack, and readiness payloads.

## UI / Filament Implications

- Existing `ResolveReviewPublication` stays the decision surface.
- Technical proof remains collapsed/secondary by default.
- Customer-facing surfaces display only safe availability states.
- No new Resource, global search, navigation, panel provider, or assets.
- Livewire v4.0+ compliance is mandatory; no Livewire v3 references or APIs.

## Audit / Observability Implications

- Proof evaluation itself should not audit on every render.
- Audit proof metadata only when a proof state is persisted, linked, superseded, rejected for step completion, or used for step completion through existing case/step transitions.
- Audit metadata must use normalized fields and safe summaries only.
- Add or update focused test assertions for proof-driven transition audit metadata when safe proof fields are attached, including proof status/currentness/usability/visibility/reason fields and exclusion of raw payloads or unsafe details.
- OperationRun remains execution truth; this spec does not change operation lifecycle transitions.

## Data / Migration Implications

- Default: no migration.
- If a migration becomes necessary, it must be reversible, PostgreSQL-safe, and limited to existing review-publication resolution tables.
- No raw payload columns, no generic polymorphic proof table, and no cross-domain proof persistence.

## Implementation Phases

1. Confirm repo truth and existing proof/currentness inputs in Spec 386/387 implementation.
2. Add failing tests for proof evaluation states and step-planner outcomes.
3. Introduce bounded proof evaluation DTO/enums or equivalent values under existing review-publication ownership.
4. Update proof resolver and step planner/service to consume currentness/usability/visibility.
5. Update proof disclosure UI only where needed.
6. Add RBAC/customer non-leakage tests and representative browser evidence if visible proof states change.
7. Run focused validation and record close-out.

## Risk Controls

- Stop and update spec/plan/tasks before adding persistence, a generic namespace, a registry, or cross-domain adapter behavior.
- Treat unknown currentness as not usable.
- Treat cross-workspace/environment proof as not accessible/not usable.
- Require artifact proof for artifact-backed steps even when runs succeed.
- Keep relationship-backed proof resolution bounded through explicit queries or eager-loading; do not add per-step unbounded query behavior.
- Keep raw/support detail absent from customer-safe and default operator UI.
- Use existing policies/capabilities, not UI visibility alone.