TenantAtlas/specs/308-decision-register-summary-review-pack/plan.md

# Implementation Plan: Decision Register Customer-Safe Summary & Review-Pack Inclusion

**Branch**: `308-decision-register-summary-review-pack` | **Date**: 2026-05-15 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/specs/308-decision-register-summary-review-pack/spec.md`

## Summary

Add a bounded customer-safe Decision Register summary to existing released-review governance-package truth and review-derived Review Pack exports. The implementation should extend current Environment Review and Review Pack composition paths, not create a new decision store, export subsystem, customer approval workflow, or OperationRun lifecycle.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail
**Storage**: PostgreSQL; existing JSONB fields on `environment_reviews.summary`, `review_packs.summary`, and generated files on the existing `exports` disk
**Testing**: Pest 4 feature tests and optional bounded browser smoke
**Validation Lanes**: confidence; browser only if rendered UI changes
**Target Platform**: Laravel Sail locally; Dokploy container deployment for staging/production
**Project Type**: single Laravel app under `apps/platform`
**Performance Goals**: Derived summary composition remains ordinary review/pack work; no new query-heavy global scan
**Constraints**: no migrations expected; no new assets; no new operation type; no customer-safe raw diagnostic leakage
**Scale/Scope**: one managed-environment released-review and review-pack flow at a time

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed customer-safe review/package surfaces and exported artifact content.
- **Native vs custom classification summary**: native/shared existing Filament surfaces plus existing export files.
- **Shared-family relevance**: customer review consumption, governance-package summary, Review Pack artifact truth, evidence/report disclosure, Decision Register context.
- **State layers in scope**: page, detail, artifact content; no shell change.
- **Audience modes in scope**: customer/read-only and operator-MSP.
- **Decision/diagnostic/raw hierarchy plan**: customer-safe decision summary first, existing detail/sections second, raw/support diagnostics absent from default customer paths.
- **Raw/support gating plan**: no raw OperationRun URLs, fingerprints, platform reason families, or provider payloads in customer-safe summary/export.
- **One-primary-action / duplicate-truth control**: preserve existing `Open review`, `Download governance package`, and `Download` actions; summary content must not add peer operator-only actions.
- **Handling modes by drift class or surface**: review-mandatory for customer-safe copy/export changes; report-only for unchanged Decision Register page.
- **Repository-signal treatment**: review-mandatory because this touches customer-safe review consumption and exported artifacts.
- **Special surface test profiles**: shared-detail-family plus standard-native-filament.
- **Required tests or manual smoke**: focused feature tests; existing bounded browser smoke if rendered customer workspace/review detail changes.
- **Exception path and spread control**: none planned.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: `EnvironmentReviewComposer`, `EnvironmentReviewSectionFactory`, `CustomerReviewWorkspace`, `EnvironmentReviewResource`, `ReviewPackService`, `GenerateReviewPackJob`, `ReviewPackResource`, review/review-pack tests.
- **Shared abstractions reused**: existing `governance_package` summary, existing `auditor_ready_executive_export.v1` delivery contract, existing `ReviewPackService::generateFromReview()`, existing `executive-summary.md` generation, existing BADGE-001 rendering if UI labels need badges.
- **New abstraction introduced? why?**: none planned. Private methods in existing classes are acceptable if needed to keep summary derivation readable.
- **Why the existing abstraction was sufficient or insufficient**: Existing review and pack composition paths already own customer-safe summary and export truth; they lack explicit Decision Register follow-through proof. Existing operator register builder is intentionally too operator-focused for direct customer export.
- **Bounded deviation / spread control**: no public framework or new artifact family. Any new summary keys stay nested under existing review/pack summary payloads.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no new start/completion/link UX. Existing review-pack generation run behavior remains.
- **Central contract reused**: existing `ReviewPackService`, `GenerateReviewPackJob`, `OperationRunService`, and existing `OperationRunLinks` usage where already present.
- **Delegated UX behaviors**: existing Review Pack generation / run feedback only.
- **Surface-owned behavior kept local**: customer-safe copy may mention evidence/package availability, not run diagnostics.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: existing Review Pack terminal handling remains.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no.
- **Provider-owned seams**: none.
- **Platform-core seams**: review/governance-package summary and review-pack export artifact content.
- **Neutral platform terms / contracts preserved**: governance decision, accepted risk, evidence basis, review, review pack, managed environment, workspace.
- **Retained provider-specific semantics and why**: existing finding/evidence titles may include provider context; this feature does not add provider coupling.
- **Bounded extraction or follow-up path**: none.

## Constitution Check

- Inventory-first: PASS. The feature uses existing evidence/review snapshot truth; it does not query Graph or change inventory behavior.
- Read/write separation: PASS. Customer-safe summary is derived/read-only. Existing review-pack generation remains the only write path and already uses confirmation/authorization semantics where applicable.
- Graph contract path: PASS. No Graph calls or contracts are touched.
- Deterministic capabilities: PASS. Existing review/review-pack capabilities remain.
- RBAC-UX: PASS. Existing workspace/environment membership and review/review-pack policy behavior remain server-side boundaries.
- Workspace isolation: PASS. Summary derivation must scope to the released review workspace.
- Tenant/environment isolation: PASS. Summary derivation must scope to the managed environment under review.
- Run observability: PASS. Existing Review Pack `OperationRun` remains; no new run type or local run UX.
- TEST-GOV-001: PASS with focused feature coverage and optional bounded browser smoke.
- PROP-001 / BLOAT-001: PASS. No new table, enum family, service framework, or export family.
- PERSIST-001: PASS. Existing review and review-pack artifacts receive derived content; no new persisted truth.
- STATE-001: PASS. No new lifecycle/status family.
- UI-SEM-001: PASS. Customer-safe copy stays a derived summary, not a UI framework.
- XCUT-001: PASS. Reuses existing review and review-pack shared paths.
- PROV-001: PASS. No provider seam changes.
- UI-FIL-001: PASS. Existing Filament-native surfaces stay native/shared-primitives first; no ad-hoc CSS or new assets expected.
- DECIDE-AUD-001 / OPSURF-001: PASS. Customer-safe summary excludes raw/support/debug content by default.

## Test Governance Check

- **Test purpose / classification by changed surface**: Feature tests for review summary composition, review-pack ZIP content, customer workspace/review-pack access, redaction, and isolation. Browser smoke only if rendered UI changes.
- **Affected validation lanes**: confidence; browser optional/bounded.
- **Why this lane mix is the narrowest sufficient proof**: Export content can be verified by reading generated ZIP entries; rendered summary and access boundaries can be verified through existing feature tests. A broad suite or new browser family is not justified.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/EnvironmentReview/EnvironmentReviewCreationTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` if rendered UI changes
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: use existing helpers such as `composeEnvironmentReviewForTest()` and review-pack factories; avoid widening defaults.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: standard-native-filament plus shared-detail-family review/export checks.
- **Closing validation and reviewer handoff**: verify summary content, redaction, no raw diagnostics, no cross-scope leakage, unchanged destructive action confirmation, and unchanged asset strategy.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: Are customer-safe summaries derived from the correct source? Are hidden records excluded? Is raw diagnostic detail absent? Did tests stay focused?
- **Escalation path**: none.
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: This is a bounded productization pass over existing review/pack paths; broader localization, packaging cadence, and artifact lifecycle remain separate candidates.

## Project Structure

### Documentation (this feature)

```text
specs/308-decision-register-summary-review-pack/
|-- spec.md
|-- plan.md
|-- tasks.md
`-- checklists/
    `-- requirements.md
```

### Source Code (likely affected later)

```text
apps/platform/app/Services/EnvironmentReviews/
|-- EnvironmentReviewComposer.php
`-- EnvironmentReviewSectionFactory.php

apps/platform/app/Jobs/
`-- GenerateReviewPackJob.php

apps/platform/app/Services/
`-- ReviewPackService.php

apps/platform/app/Filament/Pages/Reviews/
`-- CustomerReviewWorkspace.php

apps/platform/app/Filament/Resources/
|-- EnvironmentReviewResource.php
`-- ReviewPackResource.php

apps/platform/tests/Feature/EnvironmentReview/
apps/platform/tests/Feature/ReviewPack/
apps/platform/tests/Feature/Reviews/
apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
```

**Structure Decision**: Single Laravel/Filament application under `apps/platform`. Later implementation should modify only existing review, review-pack, and focused test surfaces unless repo inspection proves a smaller private helper is necessary.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| None planned | N/A | N/A |

## Technical Approach

1. Inspect current `EnvironmentReviewComposer::governancePackageSummary()` and `GenerateReviewPackJob::buildExecutiveEntrypoint()` behavior.
2. Add or refine a customer-safe decision-summary shape under existing `EnvironmentReview.summary['governance_package']`.
3. Keep existing `governance_decisions` entries aligned with accepted-risk / exception decision truth and add explicit count/empty/unavailable semantics if missing.
4. Ensure `GenerateReviewPackJob` includes the same summary in `summary.json` and readable markdown in `executive-summary.md`.
5. Update existing customer workspace/review detail presentation only if current surfaces do not expose the summary clearly.
6. Preserve redaction through existing `redactReportPayload()` behavior and add assertions for `include_pii=false`.
7. Add focused tests for positive, none, incomplete, cross-scope, and redaction scenarios.

## Data / Model Implications

- No migration expected.
- No new model expected.
- No new enum/status family expected.
- Existing JSONB summary fields may receive additive keys:
  - `governance_package.decision_summary`
  - or a clarified `governance_package.governance_decisions` shape
- Existing ZIP entries remain preferred:
  - `summary.json`
  - `executive-summary.md`
  - `sections.json`

If implementation finds a new table, new artifact file family, or new public contract is necessary, stop and update the spec/plan before coding further.

## UI / Filament Implications

- Filament v5.2.1 and Livewire v4.1.4 remain the target.
- No panel provider changes; Laravel 12 provider registration remains in `bootstrap/providers.php`.
- No new globally searchable resource.
- No new destructive actions.
- Existing Review Pack destructive-like actions such as expire/regenerate must keep `->requiresConfirmation()` and existing authorization.
- No new assets; deployment `filament:assets` unchanged.
- If UI changes are needed, prefer existing Filament sections/infolists/table entries and shared badge primitives.

## Livewire Implications

- Existing Filament/Livewire pages may render updated summary content.
- No new Livewire component is expected.
- Avoid server-driven reactivity changes unless current page state already requires it.

## RBAC / Policy Implications

- Reuse current review and review-pack policies/capabilities.
- No new capability constant expected.
- Customer-safe content must derive only after workspace and managed-environment scope are established.
- Non-member/not-entitled remains `404`; member missing capability remains existing `403`.
- Tests must cover at least one hidden/cross-scope omission path.

## Audit / Logging / Evidence Implications

- No new audit action ID expected.
- Existing review pack request/export/download audit and telemetry remain.
- No secrets, raw JSON, fingerprints, internal reason ownership, or OperationRun URLs in customer-safe default content.
- Existing `ReviewPack`, `EnvironmentReview`, `EvidenceSnapshot`, and `OperationRun` links remain traceability for operators.

## Rollout Considerations

- No migration.
- No new env vars.
- Queue workers already process review-pack jobs; no new worker class expected beyond current job changes.
- Staging validation should generate at least one review-derived pack with decisions requiring awareness and one with no decisions.
- Production/Dokploy deploy impact is ordinary app code plus queue restart if job code changes.

## Risk Controls

- Keep customer-safe summary derived and additive.
- Keep operator Decision Register unchanged unless a test proves a small source alignment issue.
- Reject raw OperationRun/proof URL exposure in customer-safe summary.
- Preserve non-certification disclosure in `executive-summary.md`.
- Keep tests focused on current review, pack, and customer workspace families.

## Implementation Phases

### Phase 1 - Discovery and Failing Tests

Confirm current summary/export behavior, then add focused tests for missing customer-safe decision summary, export inclusion, redaction, and cross-scope omission.

### Phase 2 - Summary Composition

Extend existing Environment Review governance-package summary with bounded customer-safe decision summary content.

### Phase 3 - Review Pack Inclusion

Ensure review-derived Review Pack `summary.json` and `executive-summary.md` include matching customer-safe decision summary content.

### Phase 4 - Customer Surface Presentation

Expose the summary on existing customer-safe review surfaces only where needed and only through native/shared Filament patterns.

### Phase 5 - Validation and Close-Out

Run focused Pest commands, optional bounded browser smoke, Pint dirty, and `git diff --check`. Record no new assets, no migrations, and no application implementation outside scope.

## Spec Readiness Gate

- `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist.
- Scope is bounded to existing Decision Register context, Environment Review summary, Customer Review Workspace/review detail, and review-derived Review Pack export.
- No open question blocks implementation.
- No new persisted entity, new status family, new public framework, new OperationRun type, or new asset bundle is planned.
- RBAC, isolation, auditability, OperationRun semantics, evidence/result truth, customer-safe disclosure, and test governance are addressed.

## Implementation Close-Out

- **Implementation status**: Completed for Spec 308.
- **Changed application files**:
  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`
  - `apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php`
  - `apps/platform/app/Jobs/GenerateReviewPackJob.php`
  - `apps/platform/resources/views/filament/infolists/entries/environment-review-summary.blade.php`
  - `apps/platform/lang/en/localization.php`
  - `apps/platform/lang/de/localization.php`
- **Changed tests**:
  - `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php`
  - `apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php`
- **No-migration status**: No database migration, new model, new enum/status family, new persisted decision source, or new Review Pack status was introduced.
- **No-asset status**: No frontend asset registration was added; existing deployment `filament:assets` expectations are unchanged.
- **OperationRun / audit status**: No new OperationRun type, run-link surface, or audit action ID was added. Existing review-pack generation/download traceability remains unchanged.
- **Validation results**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/EnvironmentReview/EnvironmentReviewCreationTest.php` - passed, 5 tests / 68 assertions.
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php` - passed, 22 tests / 142 assertions.
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php` - passed, 12 tests / 77 assertions.
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` - passed, 1 test / 46 assertions.
  - Additional regression lane: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/EnvironmentReview/EnvironmentReviewComposerTest.php tests/Feature/Evidence/ExceptionValidityEvidenceIntegrationTest.php tests/Feature/ReviewPack/ReviewPackValidRiskAcceptanceTest.php` - passed, 6 tests / 27 assertions.
  - Additional RBAC/download lane: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackRbacTest.php` - passed, 20 tests / 49 assertions.
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - passed.
  - `git diff --check` - passed.
- **Browser smoke result**: Required because rendered customer review detail UI changed. Existing bounded customer workspace browser smoke passed.
- **Post-implementation analysis**: No confirmed in-scope findings remain after the first implementation/fix iteration.
- **Remaining gaps**: None inside Spec 308 scope. Localization adoption, artifact lifecycle/retention, governance-service packaging cadence, and AI-assisted review drafting remain separate follow-up candidates and were not implemented.