ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/347-review-pack-output-contract-readiness-semantics/repo-truth-map.md
ahmido 12ea7f9924 feat: review pack output contract and readiness semantics (spec 347/348) (#419) 
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
2026-06-02 23:17:08 +00:00

117 lines
10 KiB
Markdown
Raw Blame History

# Spec 347 - Repo Truth Map
Status: prepared
Created: 2026-06-02
Scope: Review Pack output contract and Customer Review Workspace readiness semantics
This map records the repo-backed truth that Spec 347 is allowed to harden. It must be updated if runtime inspection during implementation reveals a narrower or broader truth boundary.
## Classification Vocabulary
- `repo-verified`: directly observed in runtime code, tests, routes, or current spec history
- `derived from existing truth`: can be computed safely from current models or payloads
- `foundation-real`: existing foundation exists, but final contract semantics are still open
- `not available`: no repo-backed truth exists today
- `deferred`: intentionally out of scope for Spec 347
## Current Review-Derived ZIP Shape
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Review-derived ZIP exists | repo-verified | `apps/platform/app/Jobs/GenerateReviewPackJob.php`, `apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php` | Keep as baseline; do not rewrite the generator |
| Required root files | repo-verified | `metadata.json`, `summary.json`, `sections.json`, `executive-summary.md` created in `buildReviewDerivedFileMap()` | Treat as required contract root files |
| Section-detail files live under `sections/` | repo-verified | `buildReviewDerivedFileMap()` writes `sections/%02d-%s.json` | Preserve repo truth; document deviation from user draft |
| Delivery contract constant | repo-verified | `App\Services\ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT` = `auditor_ready_executive_export.v1` | Preserve unless a narrow version bump is justified |
| Executive entrypoint filename | repo-verified | `ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME` | Preserve |
## Current Metadata / Summary Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| `metadata.json.delivery_bundle.entrypoint` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.delivery_bundle.appendix` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.delivery_bundle.artifact_family` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.delivery_bundle.review_pack_id` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.delivery_bundle.released_review.*` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.delivery_bundle.evidence_basis.*` | repo-verified | `deliveryBundleMetadata()` | Keep required |
| `metadata.json.options.include_pii` / `include_operations` | repo-verified | `buildReviewDerivedFileMap()` | Keep required |
| `metadata.json.redaction_integrity.protected_values_hidden` | repo-verified | `buildReviewDerivedFileMap()` | Keep required |
| `summary.json.review_status` / `review_completeness_state` | repo-verified | review-derived summary payload in `buildReviewDerivedFileMap()` | Keep required |
| `summary.json.section_state_counts` | repo-verified in review summary, not guaranteed in pack summary | `EnvironmentReviewComposer` writes it into `EnvironmentReview.summary`; `summary.json` currently merges the review summary | Verify and keep explicit |
| `summary.json.has_ready_export` | repo-verified in `EnvironmentReview.summary`; not guaranteed as a contract input in all consumers | `EnvironmentReviewComposer` seeds false; `GenerateReviewPackJob` sets true on successful generation | Keep explicit and consume honestly |
| `summary.json.delivery_bundle` | repo-verified | review-derived summary payload | Keep required |
## Current Section Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| `sections.json` contains `section_key`, `title`, `sort_order`, `required`, `completeness_state`, `summary_payload`, `render_payload` | repo-verified | `buildReviewDerivedFileMap()` | Treat as canonical section index |
| Section-detail files include only `title`, `completeness_state`, `summary_payload`, `render_payload` | repo-verified | `buildReviewDerivedFileMap()` | Gap: detail files do not currently repeat key/required/order |
| Section files are generated even when section completeness is `missing` | derived from existing truth | every included section gets a detail file regardless of completeness state | Define and test this semantics explicitly |
| Section-file absence meaning | not available as explicit contract | no current doc/test explains absence semantics | Add contract documentation and focused tests |
## Current Review / Evidence / Export Readiness Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Review publication state | repo-verified | `EnvironmentReview.status`, `published_at` | Keep as distinct from export readiness |
| Review completeness state | repo-verified | `EnvironmentReview.completeness_state` | Keep distinct from evidence/export/customer-safe readiness |
| Evidence completeness state | repo-verified | `EvidenceSnapshot.completeness_state`, `summary.evidence_basis`, `summary.evidence_resolution` | Keep distinct |
| Review summary `publish_blockers` | repo-verified | `EnvironmentReviewComposer` | Keep distinct |
| Review summary `has_ready_export` | repo-verified | `EnvironmentReviewComposer` + `GenerateReviewPackJob` | Use as explicit signal, not implied magic |
| Review Pack artifact readiness | repo-verified | `ReviewPack.status`, `file_path`, `file_disk`, `expires_at`, signed download route | Keep distinct from customer-safe sharing |
| Customer-safe readiness | foundation-real | current workspace heuristics in `CustomerReviewWorkspace::reviewReadinessForTenant()` | Replace heuristic-only phrasing with contract-backed mapping |
| Internal-only / limitations-bearing label | not available as explicit contract | no current dedicated state label exists | Add derived contract only |
| PII visibility in package metadata | repo-verified | `metadata.json.options.include_pii` | Surface in UI/readiness mapping |
| PII visibility in workspace UI | not available | current workspace does not surface it | Gap to address |
## Current Customer Review Workspace Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Strategic first-screen decision card exists | repo-verified | `customer-review-workspace.blade.php`, Spec 342 tests | Keep as first decision surface |
| Current primary labels: `Ready to share`, `Shareable with follow-up`, `Follow-up required before sharing` | repo-verified | `CustomerReviewWorkspace::reviewReadinessForTenant()` and localization keys | Candidate wording to harden |
| Package availability states: `available`, `evidence_incomplete`, `not_available`, `preparing`, `expired`, `unavailable` | repo-verified | `CustomerReviewWorkspace::governancePackageAvailability()` | Reuse where possible; map more explicitly to output contract |
| Readiness does not explicitly consume `include_pii` | repo-verified absence | no PII branch in workspace readiness methods | Gap to address |
| Readiness does not explicitly consume a section completeness summary | repo-verified absence | section counts not surfaced on the decision card | Gap to address |
| Diagnostics remain collapsed | repo-verified | current Blade/tests | Preserve |
## Current Executive Summary Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Non-certification disclosure exists | repo-verified | `buildExecutiveEntrypoint()` | Preserve |
| Dedicated limitations section does not exist | repo-verified absence | executive summary currently has Executive story / Evidence basis / Key findings / Accepted risks / Governance decisions / Next actions / Non-certification disclosure / Structured auditor appendix | Add explicit limitations block when needed |
| Executive summary does not explicitly explain section-file-present + section-missing semantics | repo-verified absence | no such wording in `buildExecutiveEntrypoint()` | Gap to address |
## Current Download Safety Truth
| Data point | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Signed route required | repo-verified | `ReviewPackDownloadController`, `ReviewPackDownloadTest` | Preserve unchanged |
| Capability required | repo-verified | `Capabilities::REVIEW_PACK_VIEW` check | Preserve unchanged |
| Ready status required | repo-verified | controller check | Preserve unchanged |
| Expiry required | repo-verified | controller check | Preserve unchanged |
| File existence required | repo-verified | controller check | Preserve unchanged |
| Audit event on download | repo-verified | controller audit log | Preserve unchanged |
## Existing Proof Tests
| Test surface | Classification | Repo evidence | Spec 347 handling |
|---|---|---|---|
| Review-derived ZIP contract basics | repo-verified | `apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php` | Extend or complement |
| Review-derived executive entrypoint and section-order contract | repo-verified | `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php` | Re-run and extend where Spec 347 changes the executive entrypoint or delivery-bundle semantics |
| Download safety | repo-verified | `apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` | Preserve and re-run |
| Review Pack generation | repo-verified | `apps/platform/tests/Feature/ReviewPack/ReviewPackGenerationTest.php` | Reuse helpers |
| Customer Review Workspace false-claim prevention | repo-verified | `apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php` | Extend or complement |
| Customer Review Workspace smoke | repo-verified | `apps/platform/tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php` | Use as pattern or overlap regression |
| Customer Review Workspace localization contract | repo-verified | `apps/platform/tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php` | Re-run when readiness vocabulary changes |
## Primary Repo-Truth Gaps To Close
1. No explicit documented contract for section-detail files vs `sections.json`.
2. No explicit dedicated limitations block in the executive summary.
3. No first-class output-readiness contract that aligns ZIP payloads with workspace wording.
4. No explicit PII/redaction visibility on the workspace first screen.
5. Existing ready/share labels are stronger than the currently explicit bundle contract.
Reference in New Issue View Git Blame Copy Permalink