ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c737fd65a0
TenantAtlas/specs/403-evidence-anchor-currentness-runtime-closure/plan.md
Ahmed Darrazi c737fd65a0
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m5s
Details
feat: add evidence anchor runtime closure contract proofs
2026-06-23 17:11:38 +02:00

21 KiB
Raw Blame History

Implementation Plan: Spec 403 - Evidence Anchor & Currentness Runtime Closure

Branch: 403-evidence-anchor-currentness-runtime-closure | Date: 2026-06-23 | Spec: specs/403-evidence-anchor-currentness-runtime-closure/spec.md Input: Feature specification from specs/403-evidence-anchor-currentness-runtime-closure/spec.md

Summary

Spec 403 closes the remaining evidence-anchor and currentness product-contract gap before TenantPilot expands management-report or customer-output claims. The implementation must inventory existing evidence/currentness claims, build an Evidence/Currentness Coverage Matrix, add focused tests and browser proof, and apply only minimal runtime fixes where a claim is false, unsafe, unscoped, or unproven.

Do not start by creating a new proof framework. Use the matrix to decide whether existing EvidenceAnchorResolver, EvidenceAnchorResult, Spec 388 proof-currentness support, policies, and shared presenters already express the required truth. Extend existing paths only when the matrix proves a concrete gap.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Laravel Sail, Pest 4.3.1, PHPUnit 12.5.4 Storage: PostgreSQL; no schema changes allowed by default Testing: Pest Unit/Feature/Filament/Browser tests Validation Lanes: confidence for Feature/Filament proof; browser for representative rendered evidence/currentness proof; optional heavy-governance only if a matrix guard is implemented Target Platform: TenantPilot Laravel monolith under apps/platform Project Type: Laravel + Filament application Performance Goals: No Graph/provider calls during render; no broad full-suite/browser expansion; no material test-runtime cost without report note Constraints: No new product surfaces, routes, navigation, persisted truth, new status vocabulary, report runtime, provider integration, migration, asset registration, or broad runtime audit Scale/Scope: Existing evidence/currentness surfaces in admin/customer/review/report/restore/baseline/finding/operation flows

Preparation Context

  • Dirty state before preparation: clean on platform-dev at c5db3ea4 feat: add resource policy authorization proof matrix (#473).
  • Spec Kit script used: .specify/scripts/bash/create-new-feature.sh --json --number 403 --short-name evidence-anchor-currentness-runtime-closure "..."
  • Generated branch/path: 403-evidence-anchor-currentness-runtime-closure, specs/403-evidence-anchor-currentness-runtime-closure/.
  • Candidate source: direct user-provided Spec 403 draft, promoted after Spec 402's PASS close-out and recommendation.
  • Active auto-prep queue: docs/product/spec-candidates.md reports no safe automatic next-best-prep target, so this is a manual operator-promoted candidate.
  • Completed-spec guardrail: Specs 388, 393, 400, 401, and 402 are read-only context. Do not rewrite their close-out, validation, completed tasks, implementation reports, or browser evidence.

Existing Repository Surfaces

Evidence and currentness foundations

  • apps/platform/app/Services/Evidence/EvidenceAnchorResolver.php
  • apps/platform/app/Services/Evidence/EvidenceAnchorResult.php
  • apps/platform/app/Services/Evidence/EvidenceSnapshotResolver.php
  • apps/platform/app/Services/Evidence/EvidenceSnapshotService.php
  • apps/platform/app/Support/Evidence/EvidenceSnapshotStatus.php
  • apps/platform/app/Support/Evidence/EvidenceCompletenessState.php
  • apps/platform/app/Models/EvidenceSnapshot.php
  • apps/platform/app/Models/EvidenceSnapshotItem.php

Existing rendered/admin/customer surfaces to inventory

  • apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
  • apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
  • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
  • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
  • apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ResolveReviewPublication.php
  • apps/platform/resources/views/filament/resources/environment-review-resource/pages/resolve-review-publication.blade.php
  • apps/platform/app/Filament/Resources/ReviewPackResource.php
  • apps/platform/app/Filament/Resources/StoredReportResource.php
  • apps/platform/app/Filament/Resources/RestoreRunResource.php and restore presenter/proof Blade views
  • apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
  • apps/platform/app/Filament/Resources/BaselineSnapshotResource.php
  • apps/platform/app/Filament/Resources/BaselineProfileResource.php
  • apps/platform/app/Filament/Resources/FindingResource.php
  • apps/platform/app/Filament/Resources/FindingExceptionResource.php
  • Monitoring/Operations and OperationRun detail/link helpers where proof links are emitted

Existing proof and output semantics

  • Spec 388 proof-currentness classes under apps/platform/app/Support/ReviewPublicationResolution/.
  • Spec 393 evidence anchor resolver/result behavior.
  • Review/report output builders and services discovered by implementation, including management-report payload builders where they are already repo-real.
  • Restore readiness/safety support and baseline evidence providers.
  • Existing policies for evidence, reviews, review packs, OperationRuns, findings, and restore/baseline resources.

UI / Surface Guardrail Plan

  • Guardrail scope: existing rendered evidence/currentness/status/proof presentation may be corrected; no new surfaces.
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces: exact touched surfaces named in implementation report after matrix inventory.
  • No-impact class, if applicable: N/A because rendered evidence/status presentation may change.
  • Native vs custom classification summary: native Filament resources/pages plus existing Blade views and shared helpers.
  • Shared-family relevance: evidence/report viewers, status messaging, action links, OperationRun proof links, customer-safe output, readiness/proof labels.
  • State layers in scope: page, detail, table row, report output, proof link, wizard/detail proof section, route/query context.
  • Audience modes in scope: customer/read-only, operator-MSP, support-platform where existing surfaces permit support/raw evidence.
  • Decision/diagnostic/raw hierarchy plan: default product surfaces show product proof state; technical proof remains secondary/internal; support/raw remains capability-gated.
  • Raw/support gating plan: preserve or tighten existing authorization. No raw evidence links in customer-safe default views.
  • One-primary-action / duplicate-truth control: no new primary actions; technical links remain secondary.
  • Handling modes by drift class or surface: hard-stop for P0 false/leaking claims; review-mandatory for P1 missing proof; document-in-feature for bounded implementation choices; follow-up-spec for structural product decisions.
  • Repository-signal treatment: review-mandatory for arbitrary latest evidence selectors, direct evidence routes in customer-safe output, OperationRun link leakage, current/released copy conflicts, stale/failed/partial proof overclaims, and cross-scope links.
  • Special surface test profiles: shared-detail-family, monitoring-state-page, customer-safe report surface, restore wizard/detail, baseline decision surface.
  • Required tests or manual smoke: Unit/Feature/Filament tests plus focused browser smoke.
  • Exception path and spread control: any Product Surface exception must be in the implementation report with page, violated rule/budget, reason, and follow-up.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
  • UI/Productization coverage decision: existing-surface evidence/currentness hardening only; route-inventory/design-matrix review or update is required if runtime UI files or reachable evidence/status semantics change.
  • Coverage artifacts to update: review/update docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md for touched existing surfaces if runtime UI files or reachable evidence/status semantics change. If existing entries already cover the final archetype/depth/safety state, record that review result in the implementation report.
  • Navigation / Filament provider-panel handling: no panel provider or navigation change. Providers remain in apps/platform/bootstrap/providers.php.
  • Screenshot or page-report need: no page-report set; focused browser proof is sufficient.

Product Surface Contract Plan

  • Product Surface Contract reference: docs/product/standards/product-surface-contract.md
  • No-legacy posture: canonical current evidence/currentness behavior, no compatibility exception.
  • Page archetype and surface budget plan: existing archetypes only; no added default OperationRun/raw evidence/source-key links.
  • Technical Annex and deep-link demotion plan: OperationRun, evidence IDs, source keys, detectors, fingerprints, raw payloads, and technical logs remain secondary/internal.
  • Canonical status vocabulary plan: map internal evidence states to existing canonical product states; do not introduce new top-level product states.
  • Product Surface exceptions: none planned.
  • UI coverage registry plan: runtime UI changes require route-inventory/design-coverage-matrix review or update for touched existing surfaces before close-out.
  • Browser verification plan: focused paths for admin evidence, customer-safe output, released evidence, stale/missing/failed state, unauthorized/cross-scope denial, and OperationRun proof link visibility/blocking.
  • Human Product Sanity plan: 5-15 minute review of touched customer-safe/readiness/evidence surfaces after implementation.
  • Visible complexity outcome target: neutral or decreased.
  • Implementation report target: specs/403-evidence-anchor-currentness-runtime-closure/implementation-report.md.

Filament / Livewire / Deployment Posture

  • Livewire v4 compliance: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire v3 APIs allowed.
  • Panel provider registration location: unchanged; Laravel 12 panel providers are registered in apps/platform/bootstrap/providers.php.
  • Global search posture: no resource global-search participation is added or changed by default. If evidence/report resources are touched, confirm View/Edit pages and $recordTitleAttribute or global-search disabled posture.
  • Destructive/high-impact action posture: no new destructive/high-impact action is planned. Existing restore/report/review actions keep ->action(...), confirmation, authorization, audit, and tests where already required.
  • Asset strategy: no new assets. filament:assets is not newly required unless implementation unexpectedly registers assets, which is out of scope by default.
  • Testing plan: focused Unit/Feature/Filament tests for evidence/currentness truth, RBAC/scope, customer-safe boundary, OperationRun proof links, current/released semantics, plus focused browser smoke.
  • Deployment impact: no env vars, migrations, queues, scheduler, storage, assets, routes, panels, or navigation changes expected. Deployment notes should record no infrastructure impact unless implementation discovers otherwise and spec/plan are updated first.

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes.
  • Systems touched: evidence anchor resolution, review/report output, OperationRun proof links, baseline/restore proof surfaces, customer-safe views, existing badges/presenters.
  • Shared abstractions reused: EvidenceAnchorResolver, EvidenceAnchorResult, EvidenceSnapshotStatus, EvidenceCompletenessState, Spec 388 proof-currentness support, OperationRunLinks, policies, and existing ArtifactTruth/Badge paths.
  • New abstraction introduced? why?: none planned.
  • Why the existing abstraction was sufficient or insufficient: existing paths are the correct current repo truth; this spec tests and corrects usage. If insufficient, update spec/plan before adding structure.
  • Bounded deviation / spread control: local label/link corrections are allowed for confirmed false claims; recurring semantics become follow-up spec rather than new framework inside Spec 403.

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: proof/link visibility only; no new start/completion behavior.
  • Central contract reused: existing OperationRun UX/link/policy helpers.
  • Delegated UX behaviors: unchanged.
  • Surface-owned behavior kept local: existing proof display only.
  • Queued DB-notification policy: unchanged.
  • Terminal notification path: unchanged.
  • Exception path: none planned.

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: possibly where provider freshness/permissions affect evidence claims.
  • Provider-owned seams: provider connection/readiness/permission diagnostic detail.
  • Platform-core seams: evidence proof, current/released status, customer-safe output, OperationRun proof, workspace/environment scope.
  • Neutral platform terms / contracts preserved: workspace, managed environment, provider, evidence, proof, review, report, operation, current, released, historical, customer-safe.
  • Retained provider-specific semantics and why: Microsoft/Graph/Entra terms remain in existing provider-owned diagnostics only.
  • Bounded extraction or follow-up path: provider productization remains separate if needed.

Constitution Check

  • Inventory-first: PASS planned. The matrix starts from observed repo/runtime evidence, not speculative product concepts.
  • Read/write separation: PASS planned. No new write flow; existing restore/report/review actions retain safety gates.
  • Graph contract path: PASS planned. No new Graph calls; UI render remains DB-only.
  • Deterministic capabilities: PASS planned. Existing capability/policy paths remain authoritative.
  • RBAC-UX: PASS planned. Scope and authorization for evidence/OperationRun links are explicit; non-members remain deny-as-not-found.
  • Workspace isolation: PASS planned. Cross-workspace proof denial tests are required.
  • Tenant/managed-environment isolation: PASS planned. Evidence and proof references must match workspace and managed environment.
  • Run observability: PASS planned. Existing OperationRun proof only; no new run type.
  • OperationRun start UX: PASS planned. No new local start UX.
  • Ops-UX lifecycle: PASS planned. No new status/outcome transitions.
  • Data minimization: PASS planned. No secrets/raw provider payloads in customer output, tests, reports, or logs.
  • Test governance: PASS planned. Confidence/browser lanes explicit; heavy-governance not hidden.
  • Proportionality: PASS planned. No new persisted truth or broad framework by default.
  • No premature abstraction: PASS planned. Extend existing paths only after matrix proof.
  • Persisted truth: PASS. No new persistence.
  • Behavioral state: PASS. No new state family.
  • UI semantics: PASS. No new UI taxonomy.
  • Shared pattern first: PASS. Existing evidence/proof helpers reused.
  • Provider boundary: PASS. Provider-specific semantics stay bounded.
  • V1 explicitness / few layers: PASS. Targeted tests and fixes only.
  • Spec discipline / bloat check: PASS. One coherent closure spec instead of many micro-specs.
  • Filament-native UI: PASS planned. Existing Filament surfaces remain native/shared-first.
  • UI/Productization coverage: PASS planned. Existing-surface presentation hardening only.
  • Product Surface Contract Gate: PASS planned. Browser proof, human sanity, no-legacy, and implementation-report fields are explicit.

Test Governance Check

  • Test purpose / classification by changed surface: Unit for resolver/state mapping; Feature/Filament for evidence/report/review/restore/baseline scope and display; Browser for focused rendered proof; Heavy-Governance only if a matrix/discovery guard is added explicitly.
  • Affected validation lanes: confidence, browser, optional heavy-governance.
  • Why this lane mix is the narrowest sufficient proof: evidence/currentness truth is business behavior plus rendered product wording; full browser audit is unnecessary and out of scope.
  • Narrowest proving command(s):
    • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec403
    • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php --compact
    • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php --compact
    • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php --compact
    • targeted restore/baseline/finding/report tests changed by implementation
    • focused Spec 403 browser smoke
    • git diff --check
    • formatter for changed PHP files
  • Fixture / helper / factory / seed / context cost risks: evidence/review/report/OperationRun/restore/baseline fixtures can become expensive. Keep new helpers opt-in and named for Spec 403 proof.
  • 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: standard-native Filament relief for unchanged resource mechanics; special coverage for customer-safe, monitoring-state, and proof-link surfaces.
  • Closing validation and reviewer handoff: implementation report records command results, browser proof, human sanity, residual findings, and next action.
  • Budget / baseline / trend follow-up: none expected; document if test runtime grows materially.
  • Review-stop questions: Did every critical false-claim risk get a test? Did any customer-safe view expose raw proof? Did any current/released label conflict? Did any OperationRun link bypass authorization? Did any new abstraction slip in without updated proportionality review?
  • Escalation path: document-in-feature for bounded residuals; follow-up-spec for structural product decisions; reject-or-split for broad audit/report/lifecycle creep.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
  • Why no dedicated follow-up spec is needed: Spec 403 is the bounded closure package; only unresolved P0/P1 findings need remediation before Spec 404.

Project Structure

Documentation (this feature)

specs/403-evidence-anchor-currentness-runtime-closure/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- implementation-report.md     # created during implementation

Source Code (repository root)

Implementation may inspect and, only if confirmed by matrix/tests, minimally edit:

apps/platform/app/Services/Evidence/
apps/platform/app/Support/Evidence/
apps/platform/app/Support/ReviewPublicationResolution/
apps/platform/app/Support/OpsUx/
apps/platform/app/Support/Operations/
apps/platform/app/Filament/Pages/Monitoring/
apps/platform/app/Filament/Pages/Reviews/
apps/platform/app/Filament/Resources/
apps/platform/app/Filament/Resources/*/Pages/
apps/platform/resources/views/filament/
apps/platform/app/Http/Controllers/
apps/platform/routes/                  # inspect-only for existing route authorization/scoping; route edits require spec/plan update
apps/platform/tests/

Explicitly Out Of Scope

database/migrations/
composer.json
package.json
apps/platform/config/
new routes/pages/navigation
new panel providers
new report/PDF runtime
new evidence providers
new governance lifecycle runtime

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
None planned N/A N/A

Proportionality Review

  • Current operator problem: evidence-backed claims can mislead operators or customers if current/released/stale/missing/failed/partial/internal/customer-safe meanings drift.
  • Existing structure is insufficient because: unknown until matrix/test inventory. Current assumption is existing structures are sufficient and need targeted usage/hardening.
  • Narrowest correct implementation: matrix, tests, minimal existing-path fixes, focused browser proof.
  • Ownership cost created: focused tests, implementation report, and any small helper extension.
  • Alternative intentionally rejected: new evidence taxonomy, new proof framework, new currentness enum family, new customer output category, full browser audit, management-report runtime changes.
  • Release truth: current-release product trust closure.

Implementation Phases

  1. Preparation and dirty-state baseline.
  2. Repo truth inventory and Evidence/Currentness Coverage Matrix.
  3. Gap classification and severity.
  4. Tests first for current evidence, released/customer-safe evidence, OperationRun proof, and cross-scope denial.
  5. Minimal runtime closure using existing helpers and surfaces.
  6. Focused browser proof and human product sanity.
  7. Implementation report, validation commands, residual findings, and recommended next action.

Risk Controls

  • Stop and update spec/plan before adding persistence, new routes, new product states, broad helper frameworks, provider integrations, report/PDF runtime, or lifecycle semantics.
  • Stop and classify as product-decision required if existing contracts do not define customer-safe proof behavior.
  • Do not claim browser proof unless focused browser tests actually run.
  • Do not rewrite completed historical specs.
  • Do not claim Spec 404 readiness unless Spec 403 final result allows it.