ahmido
12ea7f9924
Implemented the output contract and readiness semantics for review packs. Also added spec 348. Includes changes to ChooseEnvironment, CustomerReviewWorkspace, GenerateReviewPackJob and related blade views. Added comprehensive tests. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #419
144 lines
12 KiB
Markdown
144 lines
12 KiB
Markdown
# Tasks: Spec 347 - Review Pack Output Contract & Readiness Semantics
|
|
|
|
**Input**: Design documents from `/specs/347-review-pack-output-contract-readiness-semantics/`
|
|
**Prerequisites**: `spec.md`, `plan.md`, `repo-truth-map.md`, and the three contract documents under `contracts/`
|
|
|
|
**Tests**: Required. This is a runtime output-contract and customer-safe trust-surface change on existing review-pack and Customer Review Workspace paths.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is explicit and narrow: Feature for ZIP/workspace contract, Browser for first-screen trust proof.
|
|
- [x] New or changed tests stay in the smallest honest family, and the browser addition is explicit.
|
|
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
|
|
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
|
|
- [x] The declared surface profile (`global-context-shell` + customer-safe strategic review surface + artifact contract) is explicit.
|
|
- [x] Any unreachable state is documented in the active spec package rather than faked.
|
|
|
|
## Phase 1: Preparation And Repo Truth
|
|
|
|
**Purpose**: Confirm current output truth and keep the runtime implementation bounded to the existing review-derived export and workspace surfaces.
|
|
|
|
- [x] T001 Re-read `specs/347-review-pack-output-contract-readiness-semantics/spec.md`, `plan.md`, `repo-truth-map.md`, and all three contract docs before runtime changes.
|
|
- [x] T002 Re-read related historical context only: Specs 109, 308, 312, 337, 342, 343, 344, and active Spec 346. Do not modify their artifacts.
|
|
- [x] T003 Re-verify current runtime truth in:
|
|
- `apps/platform/app/Jobs/GenerateReviewPackJob.php`
|
|
- `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`
|
|
- `apps/platform/app/Services/ReviewPackService.php`
|
|
- `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
|
|
- `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
|
|
- `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`
|
|
- [x] T004 Keep `specs/347-review-pack-output-contract-readiness-semantics/repo-truth-map.md` updated if implementation-time code differs from the prepared truth.
|
|
- [x] T005 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, or Filament asset change is required.
|
|
- [x] T006 Confirm Filament v5 / Livewire v4.0+ compliance and avoid legacy Filament or Livewire APIs.
|
|
- [x] T007 Confirm panel provider registration remains `apps/platform/bootstrap/providers.php`.
|
|
- [x] T008 Confirm no new global-search behavior is introduced for review/evidence/review-pack resources.
|
|
|
|
## Phase 2: Finalize Contract Docs
|
|
|
|
**Purpose**: Lock the implementation against one explicit contract instead of allowing page-local drift.
|
|
|
|
- [x] T009 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/review-pack-output-contract.md`.
|
|
- [x] T010 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/readiness-semantics.md`.
|
|
- [x] T011 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/customer-safe-output-boundary.md`.
|
|
- [x] T012 Record repo-truth deviations from the user draft explicitly:
|
|
- section-detail files currently live under `sections/`
|
|
- current delivery contract is `auditor_ready_executive_export.v1`
|
|
- current UI audit page report is `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`
|
|
- [x] T013 Confirm the contract keeps semantics derived-only and does not introduce a new persisted readiness family.
|
|
|
|
## Phase 3: Tests First
|
|
|
|
**Purpose**: Lock required file/field/label semantics before runtime refactor.
|
|
|
|
- [x] T014 Add `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php`.
|
|
- [x] T015 Add `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php`.
|
|
- [x] T016 Add `apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php`.
|
|
- [x] T017 Add `apps/platform/tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php`.
|
|
- [x] T018 Add assertions for required root files: `executive-summary.md`, `metadata.json`, `summary.json`, `sections.json`.
|
|
- [x] T019 Add assertions for required metadata fields: bundle contract, artifact family, review-pack id, released-review state, evidence-basis state, entrypoint, appendix, options, and redaction integrity.
|
|
- [x] T020 Add assertions for required summary/readiness fields, including review status, review completeness, evidence resolution, section state counts, publish blockers, delivery bundle, and any contract-backed readiness flag inputs.
|
|
- [x] T021 Add assertions that a section marked `missing` may still have a section-detail file and that the semantics are explicit.
|
|
- [x] T022 Add assertions that the workspace does not show unqualified `Ready to share` when evidence, section, export, or customer-safe readiness is incomplete.
|
|
- [x] T023 Add assertions that `include_pii=true` or equivalent repo-backed PII truth results in an operator-visible review warning before sharing.
|
|
- [x] T024 Add assertions that executive summary output contains limitations and non-certification disclosure when contract-backed limitations exist.
|
|
- [x] T025 Reuse or extend existing tests such as `EnvironmentReviewDerivedReviewPackTest.php`, `EnvironmentReviewExecutivePackTest.php`, `ReviewPackDownloadTest.php`, `Spec342CustomerReviewWorkspaceConsumptionTest.php`, `Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php`, and `CustomerReviewSurfaceLocalizationTest.php` only where more proportional than duplicating all setup.
|
|
|
|
## Phase 4: Derived Output-Readiness Mapper
|
|
|
|
**Purpose**: Replace scattered heuristics with one bounded derived contract.
|
|
|
|
- [x] T026 Choose the narrowest implementation home for derived output readiness:
|
|
- page-local helper inside `CustomerReviewWorkspace`
|
|
- or one bounded support-layer mapper shared with review-pack output generation/tests
|
|
- [x] T027 Derive a contract that exposes label, reason, impact, primary action, evidence basis state, section completeness summary, PII/redaction visibility, and customer-safe/internal-only/limitations state.
|
|
- [x] T028 Reuse current review summary, review-pack summary, and existing `delivery_bundle` / `evidence_resolution` data before adding any new payload keys.
|
|
- [x] T029 Keep any added payload keys narrow and review-pack-output-specific; do not create a generic governance output engine.
|
|
|
|
## Phase 5: Review-Derived ZIP Contract Hardening
|
|
|
|
**Purpose**: Keep the current generator shape while removing contract ambiguity.
|
|
|
|
- [x] T030 Update `apps/platform/app/Jobs/GenerateReviewPackJob.php` so review-derived ZIP generation always emits the required root files and required contract fields.
|
|
- [x] T031 Preserve the current review-derived contract constant in `apps/platform/app/Services/ReviewPackService.php` unless a repo-justified version bump is necessary.
|
|
- [x] T032 Decide and implement the canonical section-detail contract:
|
|
- add `section_key`, `required`, and `sort_order` to each `sections/*.json` file, or
|
|
- explicitly keep `sections.json` as the canonical section index and document the thinner subordinate detail-file shape
|
|
- [x] T033 Ensure `metadata.json` and `summary.json` expose consistent review, evidence, section, and bundle semantics.
|
|
- [x] T034 Ensure file-to-section consistency is testable: every detail file corresponds to a `sections.json` entry and does not silently drift in key/title/state.
|
|
- [x] T035 Keep review-pack download safety unchanged; do not weaken signed-route, capability, expiry, or file-existence checks in `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`.
|
|
|
|
## Phase 6: Executive Summary And Disclosure Hardening
|
|
|
|
**Purpose**: Make the human entrypoint honest without leaking internal detail.
|
|
|
|
- [x] T036 Update review-derived executive-summary generation in `apps/platform/app/Jobs/GenerateReviewPackJob.php` to add a dedicated `## Limitations` block when evidence completeness, section completeness, export readiness, or PII/customer-safe boundary limits sharing.
|
|
- [x] T037 Keep or strengthen the existing non-certification disclosure in the executive summary.
|
|
- [x] T038 Explicitly explain in the executive summary when section files are present but the corresponding section completeness is `missing`.
|
|
- [x] T039 Keep internal-only/raw/support detail out of the markdown entrypoint.
|
|
|
|
## Phase 7: Customer Review Workspace Remap
|
|
|
|
**Purpose**: Make the first screen reflect the same contract as the ZIP.
|
|
|
|
- [x] T040 Update `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` to use qualified output-readiness labels when the package contract is incomplete.
|
|
- [x] T041 Update `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` so the first screen surfaces evidence basis state, section completeness summary, PII/redaction visibility, and limitations-aware next action.
|
|
- [x] T042 Qualify download labels and affordances on the workspace surface based on repo-backed state, for example internal-only or limitations-bearing package wording where justified by the contract.
|
|
- [x] T043 Keep exactly one dominant next action in the decision card.
|
|
- [x] T044 Keep diagnostics collapsed and secondary.
|
|
- [x] T045 Avoid broader Customer Review Workspace redesign outside bounded readiness/disclosure hardening.
|
|
|
|
## Phase 8: Copy, Audit, And Browser Proof
|
|
|
|
**Purpose**: Align user-facing wording and proof artifacts with the hardened contract.
|
|
|
|
- [x] T046 Update only the required output-readiness and disclosure keys in:
|
|
- `apps/platform/lang/en/localization.php`
|
|
- `apps/platform/lang/de/localization.php`
|
|
- [x] T047 Update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` with the output contract/readiness mapping, limitations behavior, and deferred follow-ups.
|
|
- [x] T048 Keep the existing page-report identity and do not invent `ui-009-*` unless runtime review proves the current report cannot absorb the output-contract scope.
|
|
- [x] T049 Capture browser screenshots under `specs/347-review-pack-output-contract-readiness-semantics/artifacts/screenshots/`.
|
|
|
|
## Phase 9: Validation
|
|
|
|
**Purpose**: Prove the contract and preserve current safety.
|
|
|
|
- [x] T050 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php --compact`.
|
|
- [x] T051 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact`.
|
|
- [x] T052 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact`.
|
|
- [x] T053 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack`.
|
|
- [x] T054 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace`.
|
|
- [x] T055 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`.
|
|
- [x] T056 Run `git diff --check`.
|
|
- [x] T057 Report any unrelated broader-suite failures honestly if they remain out of scope.
|
|
|
|
## Non-Goals Checklist
|
|
|
|
- [x] NT001 Do not rebuild Review Pack generation from scratch.
|
|
- [x] NT002 Do not add a new persisted readiness entity, table, or status family.
|
|
- [x] NT003 Do not add a portal, PSA/ITSM handoff, or broader artifact-lifecycle framework.
|
|
- [x] NT004 Do not redesign Governance Inbox or broadly redesign Customer Review Workspace.
|
|
- [x] NT005 Do not add legal/compliance approval, certification, or attestation semantics.
|
|
- [x] NT006 Do not weaken signed-download safety.
|
|
- [x] NT007 Do not invent a legacy-compatible root-level section-file layout if repo truth remains `sections/*.json`.
|
|
- [x] NT008 Do not expand this slice into Review Pack Resource detail/header productization unless a minimal contradiction fix is proven unavoidable.
|