549a9a0004
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m0s
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.
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.
|