ahmido
9b46c0e435
Implemented the output resolution guidance for the customer review workspace and internal views. Added ReviewPackOutputResolutionGuidance, updated CustomerReviewWorkspace and EnvironmentReviewResource, and added related blade views and tests. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #420
83 lines
7.0 KiB
Markdown
83 lines
7.0 KiB
Markdown
# Spec 349 - Repo Truth Map
|
|
|
|
Status: implemented
|
|
Created: 2026-06-03
|
|
Scope: Customer Review Workspace output resolution guidance and Environment Review detail output-guidance separation
|
|
|
|
This map records the repo-backed truth that Spec 349 is allowed to harden. It must be updated if runtime inspection during implementation reveals a narrower or broader bounded truth boundary.
|
|
|
|
## Implementation Update
|
|
|
|
- Shared derived guidance now lives in `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php`.
|
|
- Workspace top-card rendering consumes that shared mapping in `CustomerReviewWorkspace.php` and `customer-review-workspace.blade.php`.
|
|
- Environment Review detail consumes the same mapping through `EnvironmentReviewResource::outputGuidanceState()` and `filament/infolists/entries/review-pack-output-guidance.blade.php`.
|
|
|
|
## Classification Vocabulary
|
|
|
|
- `repo-verified`: directly observed in runtime code, tests, routes, or completed adjacent specs
|
|
- `derived from existing truth`: can be computed safely from current models or payloads
|
|
- `gap`: no current operator-guidance contract exists even though raw truth exists
|
|
- `deferred`: intentionally out of scope for Spec 349
|
|
|
|
## Current Output-Readiness Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| `ReviewPackOutputReadiness` exists | repo-verified | `apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php` | Reuse as the raw readiness source |
|
|
| Current readiness states are `customer_safe_ready`, `published_with_limitations`, `internal_review_package_available`, `export_not_ready` | repo-verified | same class constants | Reuse; any extra display state must remain derived-only |
|
|
| Current limitation codes include `export_not_ready`, evidence-basis codes, `required_sections_incomplete`, `publish_blockers_present`, `contains_pii`, and `disclosure_missing` | repo-verified | same class | Reuse as source for grouped guidance |
|
|
| Current readiness already exposes `primary_reason`, `primary_action`, `limitations`, and `section_summary` | repo-verified | same class return payload | Prefer reuse before adding new fields |
|
|
| Current readiness is derived-only and not persisted | repo-verified | same class plus current data model | Preserve; no new persisted truth |
|
|
|
|
## Current Customer Review Workspace Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| Strategic decision card already exists | repo-verified | `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` | Keep as the first decision surface |
|
|
| Workspace already derives label, reason, impact, primary action, and secondary action from readiness truth | repo-verified | `workspaceReadinessLabel()`, `workspaceReadinessReason()`, `workspaceReadinessImpact()`, `workspaceReadinessActions()` in `CustomerReviewWorkspace.php` | Consolidate into calmer grouped guidance |
|
|
| Effective state already folds finding follow-up and accepted-risk follow-up into `published_with_limitations` | repo-verified | `effectiveWorkspaceReadinessState()` | Preserve honest customer-safe logic |
|
|
| Workspace already has proof/detail panels and diagnostics sections | repo-verified | Blade view + page payload methods | Keep proof secondary; do not redesign the page broadly |
|
|
| Workspace does not yet expose a compact grouped limitation list tied to one dominant blocker | gap | current decision card and proof panel structure | Primary gap to close |
|
|
| Workspace does not yet expose a dedicated technical-details disclosure contract for output guidance | gap | current payload/view structure | Add bounded disclosure only |
|
|
|
|
## Current Environment Review Detail Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| Detail surface is Filament infolist-driven | repo-verified | `EnvironmentReviewResource::infolist()` | Do not invent a custom detail page unless repo truth later forces it |
|
|
| Customer-workspace mode narrows header actions on review detail | repo-verified | `ViewEnvironmentReview::getHeaderActions()` | Preserve current access/handoff behavior |
|
|
| Detail surface already shows artifact truth, review fields, executive posture, and sections | repo-verified | `EnvironmentReviewResource::infolist()` | Reorder or refine only as needed for clearer status separation |
|
|
| Detail surface does not yet expose an explicit "review status vs output readiness vs sharing/publication state" summary | gap | current infolist sections and labels | Primary gap to close |
|
|
|
|
## Current Route And Scope Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| Workspace route is `/admin/reviews/workspace` | repo-verified | route list | Keep unchanged |
|
|
| Environment Review detail route is workspace/environment scoped | repo-verified | route list for `environment-reviews/{record}` | Keep unchanged |
|
|
| Review Pack routes are workspace/environment scoped plus one signed download route | repo-verified | route list for `review-packs` and `admin/review-packs/{reviewPack}/download` | Keep unchanged |
|
|
| Evidence overview and detail routes already exist | repo-verified | route list for `/admin/evidence/overview` and scoped evidence detail | Reuse for guidance links where needed |
|
|
| Workspace surface uses explicit `environment_id` query filtering | repo-verified | `CustomerReviewWorkspace::environmentFilterUrl()` and current tests | Preserve; no hidden shell-state fallback |
|
|
|
|
## Current Documentation Truth
|
|
|
|
| Data point | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| Durable workspace page report exists as `ui-006-customer-review-workspace.md` | repo-verified | docs audit file | Update this report |
|
|
| No `ui-009-review-pack-output-contract.md` exists | repo-verified | docs audit inventory; `ui-009` is Provider Connections | Record this user-draft conflict explicitly; do not invent or overwrite `ui-009` |
|
|
|
|
## Current Test Truth
|
|
|
|
| Test surface | Classification | Repo evidence | Spec 349 handling |
|
|
|---|---|---|---|
|
|
| Output-readiness contract and workspace wording already have Spec 347 coverage | repo-verified | `Spec347ReviewPackOutputContractTest.php`, `Spec347ReviewPackReadinessSemanticsTest.php`, `Spec347CustomerReviewWorkspaceOutputReadinessTest.php` | Reuse as regression base |
|
|
| Customer Review Workspace already has broader page and pack-access tests | repo-verified | `CustomerReviewWorkspacePageTest.php`, `CustomerReviewWorkspacePackAccessTest.php` | Extend or reuse proportionally |
|
|
| Environment Review detail already has UI contract coverage | repo-verified | `EnvironmentReviewUiContractTest.php` | Extend or reuse proportionally |
|
|
|
|
## Primary Repo-Truth Gaps To Close
|
|
|
|
1. No grouped output-resolution guidance object exists yet over the raw readiness truth.
|
|
2. No one-primary-blocker + one-primary-action contract is enforced across workspace and detail surfaces.
|
|
3. Review detail does not yet distinguish review publication/completeness from output-readiness/sharing truth clearly enough.
|
|
4. The user-draft audit-doc target conflicts with existing repo numbering and must be corrected explicitly.
|