ahmido
3a9402998a
Added `BaselineReadinessGate`, resolution propagation, and disclosure semantics logic per Spec 385. Integrates baseline unreadiness into Customer Review Workspace and Review Packs to prevent report generation when identity bindings are unresolved. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #456
162 lines
14 KiB
Markdown
162 lines
14 KiB
Markdown
# Tasks: Spec 385 - Evidence and Review Readiness Integration v1
|
|
|
|
**Input**: Design documents from `/specs/385-evidence-review-readiness/`
|
|
**Prerequisites**: `spec.md`, `plan.md`
|
|
**Tests**: Required. This is a runtime and customer/operator-facing readiness change.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
|
- [x] New or changed tests stay in the smallest honest family, and any browser addition is explicit.
|
|
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
|
|
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
|
|
- [x] The declared surface test profile or `standard-native-filament` relief is explicit.
|
|
- [x] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.
|
|
|
|
## Phase 1: Preparation and Guardrails
|
|
|
|
**Purpose**: Confirm dependency truth and prevent scope bleed before implementation.
|
|
|
|
- [x] T001 Verify completed-spec guardrail for `specs/381-provider-resource-identity-binding/`, `specs/382-baseline-matching-canonicalization/`, `specs/383-baseline-result-semantics/`, and `specs/384-baseline-subject-resolution-ui/`; do not modify those packages.
|
|
- [x] T002 Inspect current Spec 383 semantic payload keys in `apps/platform/app/Support/Baselines/CompareSemantics/` and current compare OperationRun context shape before adding any mapper.
|
|
- [x] T003 Inspect current Spec 384 binding decision modes in `apps/platform/app/Models/ProviderResourceBinding.php` and `apps/platform/app/Support/Resources/ProviderResourceResolutionMode.php` before mapping decisions into readiness.
|
|
- [x] T004 Confirm no new migration, table, queue, scheduler, route, panel provider, capability family, provider call, workflow engine, or report/PDF runtime scope is needed; update spec/plan before implementation if this is false.
|
|
- [x] T005 Record the implementation close-out target as `Evidence and Review Readiness Integration` for guardrail, exception, smoke, and deployment notes.
|
|
|
|
---
|
|
|
|
## Phase 2: Baseline Readiness Mapping Tests (Blocking)
|
|
|
|
**Purpose**: Define false-green and false-red behavior before runtime changes.
|
|
|
|
- [x] T006 Add unit tests for the baseline readiness derivation under `apps/platform/tests/Unit/Support/Baselines/` or the nearest existing baseline semantics test family.
|
|
- [x] T007 Cover trusted no-drift mapping to complete/verified readiness with source compare proof.
|
|
- [x] T008 Cover trusted drift mapping to complete-with-findings and prove drift does not block publication by itself.
|
|
- [x] T009 Cover unresolved required identity mapping to action-required/publication blocker with a Baseline Subject Resolution next-action target.
|
|
- [x] T010 Cover missing local evidence mapping as evidence missing/refresh guidance, not provider drift.
|
|
- [x] T011 Cover missing provider resource with trusted identity as a governance issue/finding, not local-evidence missing.
|
|
- [x] T012 Cover unsupported required coverage as blocker unless accepted or allowed by profile.
|
|
- [x] T013 Cover inventory-only/foundation-only coverage as limitation, never verified no drift.
|
|
- [x] T014 Cover accepted limitation as limitation, not verified no drift.
|
|
- [x] T015 Cover excluded non-governed subject as excluded from governed claims, not compliant/pass.
|
|
- [x] T016 Cover compare failed, stale source, and zero findings without trusted compare as not customer-ready, including the expected downstream reason/limitation code when existing Review Pack states are reused.
|
|
|
|
**Checkpoint**: Tests in this phase should fail before runtime mapping is implemented.
|
|
|
|
---
|
|
|
|
## Phase 3: Baseline Readiness Derivation
|
|
|
|
**Purpose**: Build or extend the narrow shared interpretation layer.
|
|
|
|
- [x] T017 Implement or extend a bounded baseline readiness derivation using existing Spec 383 compare semantics and active `provider_resource_bindings`; prefer existing helpers before creating `apps/platform/app/Support/Baselines/Readiness/`.
|
|
- [x] T018 Ensure the derivation returns safe counts for verified subjects, drift subjects, blocked subjects, limitation subjects, missing-evidence subjects, unsupported subjects, accepted limitations, excluded subjects, stale subjects, and failed subjects.
|
|
- [x] T019 Ensure the derivation records safe source references such as source OperationRun ID, baseline compare ID if available, and evidence snapshot ID where applicable without raw provider payloads.
|
|
- [x] T020 Ensure customer-safe fields never include raw provider IDs, canonical subject keys, binding internals, database IDs, internal enum names, or raw OperationRun JSON.
|
|
- [x] T021 Ensure any new derived state/constants replace ambiguity rather than adding duplicate truth; update spec/plan first if a new public state family becomes necessary.
|
|
|
|
---
|
|
|
|
## Phase 4: Evidence Snapshot Integration (US1)
|
|
|
|
**Purpose**: Make Evidence Snapshot baseline completeness consume the readiness derivation.
|
|
|
|
- [x] T022 [US1] Update `apps/platform/app/Services/Evidence/Sources/BaselineDriftPostureSource.php` to use the baseline readiness derivation instead of relying only on drift finding count or OperationRun outcome.
|
|
- [x] T023 [US1] Update baseline evidence summary/fingerprint payloads with safe readiness counts, source IDs, and measured/freshness timestamps.
|
|
- [x] T024 [US1] Update `apps/platform/app/Services/Evidence/EvidenceCompletenessEvaluator.php` only if existing completeness aggregation cannot preserve blocker/limitation detail through existing item payloads.
|
|
- [x] T025 [US1] Add or update feature tests in `apps/platform/tests/Feature/Evidence/BaselineDriftPostureSourceTest.php` for trusted clean, trusted drift, unresolved identity, missing evidence, accepted limitation, exclusion, stale, and failed cases.
|
|
- [x] T026 [US1] Add regression coverage proving old display-name or old reason-code readiness interpretation is not authoritative.
|
|
|
|
---
|
|
|
|
## Phase 5: Environment Review Integration (US2)
|
|
|
|
**Purpose**: Turn baseline evidence detail into precise review readiness and blockers.
|
|
|
|
- [x] T027 [US2] Update `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewReadinessGate.php` so required baseline blockers and stale/missing evidence create specific review blockers.
|
|
- [x] T028 [US2] Update `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php` or section factory code so baseline limitation and blocker details appear in review summaries/sections without duplicating truth.
|
|
- [x] T029 [US2] Add guidance mapping for unresolved identity, missing evidence, compare failed, unsupported required scope, accepted limitation, and trusted drift findings.
|
|
- [x] T030 [US2] Ensure guidance links to existing destinations only: Baseline Subject Resolution, evidence basis, source operation, or existing compare rerun path.
|
|
- [x] T031 [US2] Add or update tests under `apps/platform/tests/Feature/EnvironmentReview/` covering publication blocked, published with limitations, trusted findings allowed, missing evidence refresh guidance, and internal-only behavior.
|
|
- [x] T032 [US2] Ensure review readiness does not create workflow/task/approval records or new durable blocker entities.
|
|
|
|
---
|
|
|
|
## Phase 6: Review Pack Readiness and Disclosure Integration (US3)
|
|
|
|
**Purpose**: Align Review Pack output readiness, guidance, and customer-safe disclosure.
|
|
|
|
- [x] T033 [US3] Update `apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php` to consume baseline readiness details through existing review/evidence inputs, representing stale and failed baseline readiness through existing states plus explicit reason/limitation codes unless spec/plan are updated first.
|
|
- [x] T034 [US3] Update `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php` so primary reason, limitation summary, qualified download label, and primary/secondary actions reflect baseline blockers, limitations, stale sources, and failed/unproven compare states.
|
|
- [x] T035 [US3] Update `apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php` so customer-facing profiles disclose allowed baseline limitations and block or warn when customer-safe claims are unsupported.
|
|
- [x] T036 [US3] Update rendered Review Pack or Customer Review Workspace consumers only where necessary to display customer-ready, published-with-limitations, internal-only, and blocked/export-not-ready states consistently.
|
|
- [x] T037 [US3] Add or update tests under `apps/platform/tests/Feature/ReviewPack/` for customer-safe ready, published-with-limitations, internal-only, blocked/export-not-ready, stale-source, failed/unproven-compare, and safe limitation wording.
|
|
- [x] T038 [US3] Add or update customer-safe output tests proving raw provider IDs, canonical subject keys, binding internals, internal enum names, database IDs, and raw OperationRun JSON are absent.
|
|
- [x] T039 [US3] Add or update report profile/disclosure unit tests under `apps/platform/tests/Unit/Support/ReviewPacks/` for allowed/disallowed limitation disclosure.
|
|
|
|
---
|
|
|
|
## Phase 7: Internal Proof and Diagnostics (US4)
|
|
|
|
**Purpose**: Preserve useful internal proof while keeping customer-safe output clean.
|
|
|
|
- [x] T040 [US4] Ensure internal/support profile output can include safe source IDs, reason counts, and technical diagnostics where existing profile rules allow.
|
|
- [x] T041 [US4] Ensure customer-safe profile output omits internal proof fields by default.
|
|
- [x] T042 [US4] Add tests that compare internal and customer-safe profile output from the same baseline readiness state.
|
|
- [x] T043 [US4] Ensure any source OperationRun links use existing `OperationRunLinks` or established route helpers and do not compose local OperationRun start UX.
|
|
|
|
---
|
|
|
|
## Phase 8: UI/Productization Coverage
|
|
|
|
**Purpose**: Satisfy UI-COV-001 for changed reachable surfaces.
|
|
|
|
- [x] T044 Review affected rendered surfaces and decide whether each page report needs an update or a checked no-new-route/no-archetype note.
|
|
- [x] T045 Update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` if Customer Review Workspace readiness presentation changes.
|
|
- [x] T046 Update `docs/ui-ux-enterprise-audit/page-reports/ui-011-reviews.md` if Environment Review readiness presentation changes.
|
|
- [x] T047 Update `docs/ui-ux-enterprise-audit/page-reports/ui-042-review-pack-detail.md` if Review Pack detail/output readiness presentation changes.
|
|
- [x] T048 Update `docs/ui-ux-enterprise-audit/page-reports/ui-046-evidence-snapshot-detail.md` if Evidence Snapshot baseline readiness presentation changes.
|
|
- [x] T049 Add screenshot/browser-smoke artifact paths to implementation close-out for changed customer-facing readiness rendering, or update spec/plan/tasks first if implementation proves no rendered presentation changed.
|
|
- [x] T050 Confirm `route-inventory.md` and `design-coverage-matrix.md` do not need changes unless implementation changes route inventory, navigation, or surface classification.
|
|
- [x] T051 Verify the spec's `UI Action Matrix` still matches the implementation; update it before merge if any visible action, action placement, bulk action, dangerous-action behavior, or inspect/open model changes.
|
|
|
|
---
|
|
|
|
## Phase 9: Filament, RBAC, and Security Regression Checks
|
|
|
|
**Purpose**: Keep existing surfaces tenant-safe and Filament v5 compliant.
|
|
|
|
- [x] T052 Confirm Livewire v4.0+ compliance and no Livewire v3 APIs were introduced.
|
|
- [x] T053 Confirm panel provider registration remains unchanged in `apps/platform/bootstrap/providers.php` and no new panel provider was added.
|
|
- [x] T054 Confirm no new globally searchable resource was added; if any existing Resource global-search code changes, verify View/Edit page and tenant-safe search rules.
|
|
- [x] T055 Confirm no new destructive/high-impact action was added; if an existing action is touched, verify `->action(...)`, confirmation where applicable, server-side authorization, audit, notification, and tests.
|
|
- [x] T056 Confirm existing workspace/environment entitlement checks prevent cross-tenant leakage for evidence, review, pack, stored report, operation, and subject-resolution links.
|
|
- [x] T057 Confirm no Graph/provider calls occur during UI render or readiness derivation.
|
|
- [x] T058 Confirm no secrets, raw credential payloads, raw provider payloads, or raw Graph errors are logged or rendered.
|
|
|
|
---
|
|
|
|
## Phase 10: Validation
|
|
|
|
**Purpose**: Prove the implementation and record residual risk.
|
|
|
|
- [x] T059 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Unit/Evidence tests/Unit/Support/ReviewPacks`.
|
|
- [x] T060 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/BaselineDriftPostureSourceTest.php tests/Feature/EnvironmentReview tests/Feature/ReviewPack`.
|
|
- [x] T061 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php` and any new Spec 385 Filament tests.
|
|
- [x] T062 Run browser smoke with `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php` or a new focused Spec 385 smoke covering changed rendered customer readiness.
|
|
- [x] T063 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
|
|
- [x] T064 Run `git diff --check`.
|
|
- [x] T065 Document implementation close-out with Livewire v4 compliance, provider registration location, global search status, destructive/high-impact action handling, asset strategy, tests run, browser smoke result, and deployment impact.
|
|
|
|
---
|
|
|
|
## Explicit Non-Goals
|
|
|
|
- [x] NT001 Do not modify completed Specs 381-384 except as read-only context.
|
|
- [x] NT002 Do not add matching pipeline logic or compare result semantics beyond consuming Spec 383.
|
|
- [x] NT003 Do not add or redesign Baseline Subject Resolution UI.
|
|
- [x] NT004 Do not add a generic workflow engine, approval workflow, task table, or broad Governance Inbox.
|
|
- [x] NT005 Do not add Management Report/PDF runtime validation or renderer changes.
|
|
- [x] NT006 Do not add legacy compare/evidence/review payload compatibility readers.
|
|
- [x] NT007 Do not create a new persisted readiness table/entity without updating spec/plan/tasks first.
|