ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

spec(263): auditor-pack executive export - automated PR (#319)

Browse Source 
Automated PR: commit workspace changes for spec 263 (auditor-pack executive export). Created by Copilot automation.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #319
This commit is contained in:
ahmido 2026-05-02 10:02:07 +00:00
parent 8f1ceb70ec
commit b05d5c52d4
17 changed files with 1337 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
apps/platform/app/Jobs/GenerateReviewPackJob.php
View File

@ -199,13 +199,16 @@ private function executeReviewDerivedGeneration(
$options = $reviewPack->options ?? [];
$includePii = (bool) ($options['include_pii'] ?? true);
$includeOperations = (bool) ($options['include_operations'] ?? true);
$generatedAt = now();
$fileMap = $this->buildReviewDerivedFileMap(
reviewPack: $reviewPack,
review: $review,
tenant: $tenant,
snapshot: $snapshot,
includePii: $includePii,
includeOperations: $includeOperations,
generatedAt: $generatedAt,
);
$tempFile = tempnam(sys_get_temp_dir(), 'review-pack-');
@ -219,7 +222,7 @@ private function executeReviewDerivedGeneration(
'review-packs/%s/review-%d-%s.zip',
$tenant->external_id,
(int) $review->getKey(),
now()->format('Y-m-d-His'),
$generatedAt->format('Y-m-d-His'),
);
Storage::disk('exports')->put($filePath, file_get_contents($tempFile));
@ -241,6 +244,7 @@ private function executeReviewDerivedGeneration(
'operation_count' => $includeOperations ? (int) ($reviewSummary['operation_count'] ?? 0) : 0,
'highlights' => is_array($reviewSummary['highlights'] ?? null) ? $reviewSummary['highlights'] : [],
'publish_blockers' => is_array($reviewSummary['publish_blockers'] ?? null) ? $reviewSummary['publish_blockers'] : [],
'delivery_bundle' => $this->deliveryBundleSummary($review),
'evidence_resolution' => [
'outcome' => 'resolved',
'snapshot_id' => (int) $snapshot->getKey(),
@ -258,8 +262,8 @@ private function executeReviewDerivedGeneration(
'file_size' => $fileSize,
'file_path' => $filePath,
'file_disk' => 'exports',
'generated_at' => now(),
'expires_at' => now()->addDays($retentionDays),
'generated_at' => $generatedAt,
'expires_at' => $generatedAt->copy()->addDays($retentionDays),
'summary' => $summary,
]);
@ -582,13 +586,21 @@ private function assembleZip(string $tempFile, array $fileMap): void
* @return array<string, string>
*/
private function buildReviewDerivedFileMap(
ReviewPack $reviewPack,
TenantReview $review,
Tenant $tenant,
EvidenceSnapshot $snapshot,
bool $includePii,
bool $includeOperations,
\Carbon\CarbonInterface $generatedAt,
): array {
$reviewSummary = is_array($review->summary) ? $review->summary : [];
$deliveryMetadata = $this->deliveryBundleMetadata(
reviewPack: $reviewPack,
review: $review,
snapshot: $snapshot,
generatedAt: $generatedAt,
);
$sections = $review->sections
->filter(fn (mixed $section): bool => $includeOperations || $section->section_key !== 'operations_health')
@ -599,7 +611,8 @@ private function buildReviewDerivedFileMap(
'version' => '1.0',
'tenant_id' => $tenant->external_id,
'tenant_name' => $includePii ? $tenant->name : '[REDACTED]',
'generated_at' => now()->toIso8601String(),
'generated_at' => $generatedAt->toIso8601String(),
'delivery_bundle' => $deliveryMetadata,
'tenant_review' => [
'id' => (int) $review->getKey(),
'status' => (string) $review->status,
@ -622,11 +635,17 @@ private function buildReviewDerivedFileMap(
'note' => RedactionIntegrity::protectedValueNote(),
],
], JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR),
'summary.json' => json_encode($this->redactReportPayload(array_merge([
'tenant_review_id' => (int) $review->getKey(),
'review_status' => (string) $review->status,
'review_completeness_state' => (string) $review->completeness_state,
], $reviewSummary), $includePii), JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR),
'summary.json' => json_encode($this->redactReportPayload(array_merge(
[
'tenant_review_id' => (int) $review->getKey(),
'review_status' => (string) $review->status,
'review_completeness_state' => (string) $review->completeness_state,
],
$reviewSummary,
[
'delivery_bundle' => $this->deliveryBundleSummary($review),
],
), $includePii), JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR),
'sections.json' => json_encode($sections->map(function ($section) use ($includePii): array {
$summaryPayload = is_array($section->summary_payload) ? $section->summary_payload : [];
$renderPayload = is_array($section->render_payload) ? $section->render_payload : [];
@ -641,6 +660,14 @@ private function buildReviewDerivedFileMap(
'render_payload' => $this->redactReportPayload($renderPayload, $includePii),
];
})->all(), JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR),
ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME => $this->buildExecutiveEntrypoint(
review: $review,
tenant: $tenant,
snapshot: $snapshot,
reviewSummary: $reviewSummary,
includePii: $includePii,
generatedAt: $generatedAt,
),
];
foreach ($sections as $section) {
@ -659,6 +686,195 @@ private function buildReviewDerivedFileMap(
return $files;
}
/**
* @return array<string, mixed>
*/
private function deliveryBundleSummary(TenantReview $review): array
{
return [
'contract' => ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT,
'executive_entrypoint_file' => ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME,
'appendix_files' => ['metadata.json', 'summary.json', 'sections.json'],
'interpretation_version' => $review->controlInterpretationVersion(),
];
}
/**
* @return array<string, mixed>
*/
private function deliveryBundleMetadata(
ReviewPack $reviewPack,
TenantReview $review,
EvidenceSnapshot $snapshot,
\Carbon\CarbonInterface $generatedAt,
): array {
return [
'contract' => ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT,
'artifact_family' => 'review_pack',
'review_pack_id' => (int) $reviewPack->getKey(),
'generated_at' => $generatedAt->toIso8601String(),
'released_review' => [
'id' => (int) $review->getKey(),
'status' => (string) $review->status,
'completeness_state' => (string) $review->completeness_state,
'published_at' => $review->published_at?->toIso8601String(),
],
'interpretation_version' => $review->controlInterpretationVersion(),
'evidence_basis' => [
'snapshot_id' => (int) $snapshot->getKey(),
'snapshot_fingerprint' => (string) $snapshot->fingerprint,
'completeness_state' => (string) $snapshot->completeness_state,
'generated_at' => $snapshot->generated_at?->toIso8601String(),
],
'entrypoint' => [
'file' => ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME,
'role' => 'executive_entrypoint',
'audience' => 'executive',
'format' => 'text/markdown',
],
'appendix' => [
[
'file' => 'metadata.json',
'role' => 'bundle_metadata',
'description' => 'Structured delivery metadata and artifact role map.',
],
[
'file' => 'summary.json',
'role' => 'review_summary_appendix',
'description' => 'Structured released-review summary truth.',
],
[
'file' => 'sections.json',
'role' => 'section_detail_appendix',
'description' => 'Structured released-review section detail.',
],
],
];
}
/**
* @param array<string, mixed> $reviewSummary
*/
private function buildExecutiveEntrypoint(
TenantReview $review,
Tenant $tenant,
EvidenceSnapshot $snapshot,
array $reviewSummary,
bool $includePii,
\Carbon\CarbonInterface $generatedAt,
): string {
$package = is_array($reviewSummary['governance_package'] ?? null)
? $this->redactReportPayload($reviewSummary['governance_package'], $includePii)
: [];
$controlInterpretation = is_array($reviewSummary['control_interpretation'] ?? null)
? $reviewSummary['control_interpretation']
: [];
$nonCertificationDisclosure = $this->plainText(
$controlInterpretation['non_certification_disclosure'] ?? null,
'TenantPilot interprets available evidence for review readiness. This is not a certification, legal attestation, or compliance guarantee.',
);
$tenantName = $includePii ? $tenant->name : '[REDACTED]';
$topFindings = is_array($package['top_findings'] ?? null) ? $package['top_findings'] : [];
$acceptedRisks = is_array($package['accepted_risks'] ?? null) ? $package['accepted_risks'] : [];
$governanceDecisions = is_array($package['governance_decisions'] ?? null) ? $package['governance_decisions'] : [];
$nextActions = is_array($reviewSummary['recommended_next_actions'] ?? null) ? $reviewSummary['recommended_next_actions'] : [];
$lines = [
'# Executive summary',
'',
'Tenant: '.$this->plainText($tenantName, '[REDACTED]'),
'Released review: #'.((int) $review->getKey()),
'Review status: '.$this->plainText($review->status, 'unknown'),
'Generated at: '.$generatedAt->toIso8601String(),
'',
'## Executive story',
'',
$this->plainText($package['executive_summary'] ?? null, 'No executive summary is available for this released review.'),
'',
'## Evidence basis',
'',
$this->plainText(
$package['evidence_basis_summary'] ?? null,
sprintf('Anchored to evidence snapshot #%d with %s completeness.', (int) $snapshot->getKey(), (string) $snapshot->completeness_state),
),
'',
'## Key findings',
'',
...$this->entryBullets($topFindings, 'No key findings are listed for this released review.'),
'',
'## Accepted risks',
'',
...$this->entryBullets($acceptedRisks, 'No accepted risks are listed for this released review.'),
'',
'## Governance decisions requiring awareness',
'',
...$this->entryBullets($governanceDecisions, 'No governance decisions require awareness in this released review.'),
'',
'## Next actions',
'',
...$this->textBullets($nextActions, 'No next action is listed for this released review.'),
'',
'## Non-certification disclosure',
'',
$nonCertificationDisclosure,
'',
'## Structured auditor appendix',
'',
'This executive entrypoint is the first file to read. The structured auditor appendix remains available in metadata.json, summary.json, and sections.json.',
'',
];
return implode("\n", $lines);
}
/**
* @param array<int, mixed> $entries
* @return list<string>
*/
private function entryBullets(array $entries, string $emptyText): array
{
if ($entries === []) {
return ['- '.$emptyText];
}
return collect($entries)
->filter(static fn (mixed $entry): bool => is_array($entry))
->map(function (array $entry): string {
$title = $this->plainText($entry['title'] ?? null, 'Entry');
$summary = $this->plainText($entry['summary'] ?? null, '');
return $summary === '' ? '- '.$title : '- '.$title.' - '.$summary;
})
->values()
->all();
}
/**
* @param array<int, mixed> $entries
* @return list<string>
*/
private function textBullets(array $entries, string $emptyText): array
{
$bullets = collect($entries)
->filter(static fn (mixed $entry): bool => is_string($entry) && trim($entry) !== '')
->map(fn (string $entry): string => '- '.$this->plainText($entry, ''))
->values()
->all();
return $bullets === [] ? ['- '.$emptyText] : $bullets;
}
private function plainText(mixed $value, string $fallback): string
{
if (! is_scalar($value) && $value !== null) {
return $fallback;
}
$text = preg_replace('/\s+/', ' ', trim((string) $value));
return is_string($text) && $text !== '' ? $text : $fallback;
}
private function markFailed(ReviewPack $reviewPack, OperationRun $operationRun, OperationRunService $operationRunService, string $reasonCode, string $errorMessage): void
{
$reviewPack->update([

10
apps/platform/app/Services/ReviewPackService.php
View File

@ -26,6 +26,10 @@
class ReviewPackService
{
public const string REVIEW_DERIVED_DELIVERY_CONTRACT = 'auditor_ready_executive_export.v1';
public const string EXECUTIVE_ENTRYPOINT_FILENAME = 'executive-summary.md';
public function __construct(
private OperationRunService $operationRunService,
private EvidenceSnapshotResolver $snapshotResolver,
@ -193,6 +197,11 @@ public function generateFromReview(TenantReview $review, User $user, array $opti
'review_status' => (string) $review->status,
'review_completeness_state' => (string) $review->completeness_state,
'section_count' => $review->sections->count(),
'delivery_bundle' => [
'contract' => self::REVIEW_DERIVED_DELIVERY_CONTRACT,
'executive_entrypoint_file' => self::EXECUTIVE_ENTRYPOINT_FILENAME,
'appendix_files' => ['metadata.json', 'summary.json', 'sections.json'],
],
'finding_outcomes' => is_array($review->summary['finding_outcomes'] ?? null)
? $review->summary['finding_outcomes']
: [],
@ -376,6 +385,7 @@ public function computeFingerprintForReview(TenantReview $review, array $options
'tenant_review_id' => (int) $review->getKey(),
'review_fingerprint' => (string) $review->fingerprint,
'review_status' => (string) $review->status,
'delivery_contract' => self::REVIEW_DERIVED_DELIVERY_CONTRACT,
'include_pii' => (bool) ($options['include_pii'] ?? true),
'include_operations' => (bool) ($options['include_operations'] ?? true),
];

8
apps/platform/lang/de/localization.php
View File

@ -130,8 +130,8 @@
'customer_reviews' => 'Kundenreviews',
'customer_review_workspace' => 'Kundenreview-Workspace',
'customer_safe_review_workspace' => 'Kundensicherer Governance-Paket-Index',
'customer_workspace_intro' => 'Prüfen Sie für jeden berechtigten Tenant den aktuellen Status des Governance-Pakets und öffnen Sie bei Bedarf die kundensichere Detailansicht.',
'customer_workspace_canonical_note' => 'Jede Zeile ist ein Einstieg in die Detailansicht: Dort sehen Sie Paketstatus, Nachweise, aktuelle Risiken und den nächsten kundensicheren Schritt.',
'customer_workspace_intro' => 'Prüfen Sie für jeden berechtigten Tenant den executive-fähigen Status des Governance-Pakets und öffnen Sie bei Bedarf die kundensichere Detailansicht.',
'customer_workspace_canonical_note' => 'Jede Zeile ist ein Einstieg in die Detailansicht: Dort sehen Sie Paketstatus, Executive-Einstieg, Nachweise, aktuelle Risiken und den nächsten kundensicheren Schritt.',
'customer_workspace_mapping_version' => 'Die Control-Readiness-Interpretation verwendet :version für diesen Workspace.',
'customer_workspace_non_certification_disclosure' => 'Dieser Workspace fasst die aktuelle Review- und Nachweislage für die Service-Auslieferung zusammen. Er ersetzt weder ein formales Auditurteil noch eine Zertifizierung oder rechtliche Attestierung.',
'reviews' => 'Reviews',
@ -173,6 +173,10 @@
'governance_package' => 'Governance-Paket',
'governance_decisions' => 'Governance-Entscheidungen',
'governance_package_delivery_note' => 'Dieses Governance-Paket wird über das aktuelle Export-Review-Pack des veröffentlichten Reviews ausgeliefert.',
'executive_entrypoint' => 'Executive-Einstieg',
'executive_entrypoint_description' => 'Beginnen Sie im heruntergeladenen Paket mit executive-summary.md.',
'auditor_appendix' => 'Strukturierter Auditor-Anhang',
'auditor_appendix_description' => 'metadata.json, summary.json und sections.json bleiben als sekundärer strukturierter Anhang enthalten.',
'governance_package_available' => 'Governance-Paket verfügbar',
'governance_package_available_description' => 'Das aktuelle Export-Review-Pack ist aus diesem veröffentlichten Review für die Stakeholder-Auslieferung bereit.',
'governance_package_partial' => 'Governance-Paket partiell',

8
apps/platform/lang/en/localization.php
View File

@ -130,8 +130,8 @@
'customer_reviews' => 'Customer reviews',
'customer_review_workspace' => 'Customer Review Workspace',
'customer_safe_review_workspace' => 'Customer-safe governance package index',
'customer_workspace_intro' => 'Review the current governance package status for each entitled tenant and open the customer-safe detail when follow-up is needed.',
'customer_workspace_canonical_note' => 'Each row is an index entry: open the review detail to inspect package status, supporting evidence, current risks, and the next customer-safe action.',
'customer_workspace_intro' => 'Review the executive-ready governance package status for each entitled tenant and open the customer-safe detail when follow-up is needed.',
'customer_workspace_canonical_note' => 'Each row is an index entry: open the review detail to inspect package status, the executive entrypoint, supporting evidence, current risks, and the next customer-safe action.',
'customer_workspace_mapping_version' => 'Control readiness interpretation uses :version for this workspace.',
'customer_workspace_non_certification_disclosure' => 'This workspace summarizes current review evidence for service delivery. It does not replace a formal audit opinion, certification, or legal attestation.',
'reviews' => 'Reviews',
@ -173,6 +173,10 @@
'governance_package' => 'Governance package',
'governance_decisions' => 'Governance decisions',
'governance_package_delivery_note' => 'This governance package is delivered through the current export review pack for the released review.',
'executive_entrypoint' => 'Executive entrypoint',
'executive_entrypoint_description' => 'Start with executive-summary.md in the downloaded package.',
'auditor_appendix' => 'Structured auditor appendix',
'auditor_appendix_description' => 'metadata.json, summary.json, and sections.json remain included as the secondary structured appendix.',
'governance_package_available' => 'Governance package available',
'governance_package_available_description' => 'The current export review pack is ready for stakeholder delivery from this released review.',
'governance_package_partial' => 'Governance package partial',

10
apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php
View File

@ -126,12 +126,22 @@
<div class="mt-1 text-sm font-medium text-gray-900 dark:text-gray-100">{{ __('localization.review.download_governance_package') }}</div>
</div>
<div class="rounded-md border border-gray-100 bg-gray-50 px-3 py-2 dark:border-gray-800 dark:bg-gray-950/60">
<div class="text-[11px] font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">{{ __('localization.review.executive_entrypoint') }}</div>
<div class="mt-1 text-sm text-gray-900 dark:text-gray-100">{{ __('localization.review.executive_entrypoint_description') }}</div>
</div>
@if ($packageNextStep !== null)
<div class="rounded-md border border-primary-100 bg-primary-50 px-3 py-2 dark:border-primary-900/40 dark:bg-primary-950/30">
<div class="text-[11px] font-semibold uppercase tracking-wide text-primary-700 dark:text-primary-200">{{ __('localization.review.next_step') }}</div>
<div class="mt-1 text-sm text-primary-900 dark:text-primary-100">{{ $packageNextStep }}</div>
</div>
@endif
<div class="rounded-md border border-gray-100 bg-gray-50 px-3 py-2 dark:border-gray-800 dark:bg-gray-950/60">
<div class="text-[11px] font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">{{ __('localization.review.auditor_appendix') }}</div>
<div class="mt-1 text-sm text-gray-700 dark:text-gray-300">{{ __('localization.review.auditor_appendix_description') }}</div>
</div>
</div>
@if (filled($governancePackage['executive_summary'] ?? null))

3
apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
View File

@ -88,6 +88,7 @@
->assertSee('Governance package')
->assertSee('Status')
->assertSee('Evidence')
->assertSee('Review the executive-ready governance package status')
->assertSee('This workspace summarizes current review evidence for service delivery. It does not replace a formal audit opinion, certification, or legal attestation.')
->assertSee('Partial')
->assertSee('Review required')
@ -109,6 +110,8 @@
->assertSee('Released governance record')
->assertSee('Review status')
->assertSee('Primary action')
->assertSee('Executive entrypoint')
->assertSee('Structured auditor appendix')
->assertSee('Assessment basis')
->assertDontSee('Control readiness interpretation')
->assertDontSee('Compliance evidence mapping v1')

15
apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php
View File

@ -28,7 +28,7 @@
app()->call([$job, 'handle']);
$pack->refresh();
$review->refresh();
$review->refresh()->load('evidenceSnapshot');
expect($pack->tenant_review_id)->toBe((int) $review->getKey())
->and($pack->status)->toBe(ReviewPackStatus::Ready->value)
@ -47,11 +47,22 @@
$metadata = json_decode((string) $zip->getFromName('metadata.json'), true, 512, JSON_THROW_ON_ERROR);
$summary = json_decode((string) $zip->getFromName('summary.json'), true, 512, JSON_THROW_ON_ERROR);
$sections = json_decode((string) $zip->getFromName('sections.json'), true, 512, JSON_THROW_ON_ERROR);
$executiveEntrypoint = (string) $zip->getFromName(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME);
expect(data_get($metadata, 'tenant_name'))->toBe('[REDACTED]')
->and(data_get($metadata, 'delivery_bundle.entrypoint.file'))->toBe(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME)
->and(data_get($metadata, 'delivery_bundle.entrypoint.role'))->toBe('executive_entrypoint')
->and(data_get($metadata, 'delivery_bundle.appendix.0.file'))->toBe('metadata.json')
->and(data_get($metadata, 'delivery_bundle.appendix.1.file'))->toBe('summary.json')
->and(data_get($metadata, 'delivery_bundle.appendix.2.file'))->toBe('sections.json')
->and(data_get($metadata, 'options.include_operations'))->toBeFalse()
->and(data_get($summary, 'delivery_bundle.executive_entrypoint_file'))->toBe(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME)
->and(data_get($summary, 'tenant_review_id'))->toBe((int) $review->getKey())
->and(collect($sections)->pluck('section_key')->all())->not->toContain('operations_health');
->and(collect($sections)->pluck('section_key')->all())->not->toContain('operations_health')
->and($executiveEntrypoint)->toContain('Tenant: [REDACTED]')
->and($executiveEntrypoint)->toContain('This executive entrypoint is the first file to read')
->and($executiveEntrypoint)->not->toContain((string) $review->fingerprint)
->and($executiveEntrypoint)->not->toContain((string) $review->evidenceSnapshot?->fingerprint);
$zip->close();
unlink($tempFile);

3
apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php
View File

@ -92,7 +92,8 @@
->assertCanSeeTableRecords([$tenantA->fresh(), $tenantB->fresh()])
->assertCanNotSeeTableRecords([$tenantDenied->fresh()])
->assertSee(TenantReviewResource::tenantScopedUrl('view', ['record' => $latestPublishedReview->fresh()], $tenantA), false)
->assertSee('Review the current governance package status for each entitled tenant and open the customer-safe detail when follow-up is needed.')
->assertSee('Review the executive-ready governance package status for each entitled tenant and open the customer-safe detail when follow-up is needed.')
->assertSee('Each row is an index entry: open the review detail to inspect package status, the executive entrypoint, supporting evidence, current risks, and the next customer-safe action.')
->assertSee('This workspace summarizes current review evidence for service delivery. It does not replace a formal audit opinion, certification, or legal attestation.')
->assertSee('Governance package')
->assertSee('Status')

28
apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php
View File

@ -38,7 +38,7 @@
app()->call([$job, 'handle']);
$pack->refresh();
$review->refresh()->load('sections');
$review->refresh()->load(['sections', 'evidenceSnapshot']);
$zipContent = Storage::disk('exports')->get((string) $pack->file_path);
$tempFile = tempnam(sys_get_temp_dir(), 'tenant-review-pack-');
@ -47,13 +47,37 @@
$zip = new ZipArchive;
$zip->open($tempFile);
$metadata = json_decode((string) $zip->getFromName('metadata.json'), true, 512, JSON_THROW_ON_ERROR);
$summary = json_decode((string) $zip->getFromName('summary.json'), true, 512, JSON_THROW_ON_ERROR);
$sections = json_decode((string) $zip->getFromName('sections.json'), true, 512, JSON_THROW_ON_ERROR);
$executiveEntrypoint = (string) $zip->getFromName(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME);
$filenames = collect(range(0, $zip->numFiles - 1))
->map(fn (int $index): string => (string) $zip->getNameIndex($index))
->values()
->all();
expect(array_column($sections, 'section_key'))
->toBe($review->sections->pluck('section_key')->values()->all())
->and($summary['highlights'] ?? null)->toBe($review->summary['highlights'] ?? [])
->and($summary['recommended_next_actions'] ?? null)->toBe($review->summary['recommended_next_actions'] ?? []);
->and($summary['recommended_next_actions'] ?? null)->toBe($review->summary['recommended_next_actions'] ?? [])
->and($summary['delivery_bundle']['contract'] ?? null)->toBe(ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT)
->and($summary['delivery_bundle']['executive_entrypoint_file'] ?? null)->toBe(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME)
->and($metadata['delivery_bundle']['contract'] ?? null)->toBe(ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT)
->and($metadata['delivery_bundle']['review_pack_id'] ?? null)->toBe((int) $pack->getKey())
->and($metadata['delivery_bundle']['released_review']['id'] ?? null)->toBe((int) $review->getKey())
->and($metadata['delivery_bundle']['interpretation_version'] ?? null)->toBe($review->controlInterpretationVersion())
->and($metadata['delivery_bundle']['entrypoint']['file'] ?? null)->toBe(ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME)
->and(collect($metadata['delivery_bundle']['appendix'] ?? [])->pluck('file')->all())->toBe(['metadata.json', 'summary.json', 'sections.json'])
->and($filenames)->toContain('metadata.json', 'summary.json', 'sections.json', ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME)
->and(collect($filenames)->filter(fn (string $filename): bool => str_starts_with($filename, 'executive-'))->values()->all())->toBe([ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME])
->and($executiveEntrypoint)->toContain('# Executive summary')
->and($executiveEntrypoint)->toContain('## Executive story')
->and($executiveEntrypoint)->toContain('## Structured auditor appendix')
->and($executiveEntrypoint)->toContain('metadata.json, summary.json, and sections.json')
->and($executiveEntrypoint)->not->toContain((string) $review->fingerprint)
->and($executiveEntrypoint)->not->toContain((string) $review->evidenceSnapshot?->fingerprint)
->and($executiveEntrypoint)->not->toContain('Reason owner')
->and($executiveEntrypoint)->not->toContain('Platform reason family');
$zip->close();
unlink($tempFile);

4
apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php
View File

@ -98,6 +98,10 @@
->assertSee('Last review')
->assertSee('Primary action')
->assertSee('Download governance package')
->assertSee('Executive entrypoint')
->assertSee('Start with executive-summary.md in the downloaded package.')
->assertSee('Structured auditor appendix')
->assertSee('metadata.json, summary.json, and sections.json remain included as the secondary structured appendix.')
->assertSee('Anchored to evidence snapshot #')
->assertSee('Assessment basis')
->assertSee('Evidence basis')

255
docs/product/implementation-ledger.md
View File

@ -1,39 +1,37 @@
# TenantPilot Implementation Ledger
> **Status:** Active
> **Last reviewed:** 2026-05-01
> **Last reviewed:** 2026-05-02
> **Use for:** Repo-based implementation status and product-surface maturity assessment
> **Do not use for:** Roadmap priority, spec priority, or proof that tests were executed in the current branch
> **Scoped maintenance:** 2026-05-01 full repo-based maturity refresh against current `specs/` truth and repo anchors, especially refreshed Spec 043 and Specs 251-260 plus the implemented compare/preflight, governance-package, compliance-interpretation, commercial-lifecycle, and external-support-handoff slices.
> **Scoped maintenance:** 2026-05-02 ledger drift correction and alignment with `docs/product/roadmap.md` plus `docs/product/spec-candidates.md` after the repo-truth review of roadmap drift, manual-promotion backlog, and implementation maturity.
## Purpose
Dieses Dokument beschreibt den aktuellen repo-basierten Implementierungsstand von TenantPilot. Es ergaenzt `roadmap.md` und `spec-candidates.md`, ersetzt sie aber nicht.
Dieses Dokument beschreibt den aktuellen repo-basierten Implementierungsstand von TenantPilot. Es ergaenzt `docs/product/roadmap.md` und `docs/product/spec-candidates.md`, ersetzt sie aber nicht.
Bewertungsregeln fuer dieses Ledger:
- Repo-basiert only: Aussagen zaehlen nur, wenn Code, Datenmodell, Workflow, UI-Adoption oder Test-Artefakte im Repo belastbar darauf hinweisen.
- Keine Roadmap- oder Spec-Absicht ohne Repo-Evidence.
- Produkt-Posture wird nur mit `foundation-only`, `implemented but not productized`, `fast sellable`, `sellable` oder `not implemented` beschrieben.
- `sellable` wird nur dort verwendet, wo UI, Workflow, Datenmodell, RBAC/Audit und passende Test-Artefakte plausibel zusammenpassen.
- Backend-only bleibt `foundation-only`.
- UI-only gilt nicht als fertig.
- `fast sellable` bedeutet: repo-real und kunden- oder operatornah genug, aber die letzte produktisierte Delivery-, Packaging- oder Self-Serve-Schicht fehlt noch.
- `implemented but not productized` bedeutet: reale Oberflaechen oder Workflows existieren, aber sie sind noch nicht als ruhige, wiederholbare Produkt-Slice zusammengezogen.
- `foundation-only` bleibt fuer Enablement-, Control-, Policy- oder technische Tragschichten reserviert.
- Wenn Tests unten als vorhanden markiert sind, bedeutet das: passende Test-Dateien existieren im Repo. Sie wurden fuer dieses Ledger nicht ausgefuehrt.
## Current Product Position
TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry und Safety Controls. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating sowie eine kanonische cross-tenant compare preview mit promotion preflight. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution und ein breiterer decision workboard/action layer, wiederholbare Billing-/Trial-/Demo-Operations sowie eine AI-governed execution foundation.
TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry, Safety Controls und eine repo-reale governed AI policy foundation. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating sowie eine kanonische cross-tenant compare preview mit promotion preflight. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution, ein bounded governance decision pack and approval workflow, wiederholbare Billing-/Subscription-Truth, eine klarere Stored-Reports-Surface und der erste governed AI runtime consumer ueber der bereits repo-realen AI policy foundation.
## Status Model
- `planned`: nur in Roadmap oder Kandidatenliste, ohne belastbare Repo-Evidence
- `specified`: als Spec oder Draft angelegt, aber nicht repo-verifiziert umgesetzt
- `implemented_partial`: Teilumsetzung vorhanden, aber noch nicht als fertig bewertbar
- `implemented_backend`: belastbare Backend- oder Modelllogik vorhanden, aber keine ausreichende UI-Adoption
- `implemented_ui`: sichtbare UI vorhanden, aber Workflow- oder Backend-Proof ist noch zu schwach
- `implemented_verified`: Code, Modell, Workflow und Test-Artefakte sind plausibel vorhanden
- `adopted`: implementiert und bereits in zentrale Produktoberflaechen oder Kernablaeufe uebernommen
- `deferred`: bewusst verschoben
- `obsolete`: durch neuere Repo-Realitaet oder andere Implementierung ueberholt
- `foundation-only`: belastbare technische, policy- oder control-layer foundation ohne hinreichende Produktisierung
- `implemented but not productized`: reale Oberflaeche oder Workflow vorhanden, aber noch keine ruhige wiederholbare Produktschicht
- `fast sellable`: repo-real, kunden- oder operatornah und nah an wiederholbarer Delivery, aber letzte Produktisierungsluecken bleiben
- `sellable`: belastbare UI-, Workflow-, RBAC/Audit- und Test-Spur mit wiederholbarem Produktversprechen
- `not implemented`: noch kein belastbarer repo-real Slice fuer das eigentliche Ziel
Evidence-Level im Dokument:
@ -44,68 +42,69 @@ ## Status Model
## Roadmap Coverage Summary
| Roadmap Area | Status | Evidence Level | UI Ready | Tested | Sellable | Notes |
| Roadmap Area | Product posture | Evidence Level | UI Ready | Tested | Sellable | Notes |
|---|---|---:|---|---|---|---|
| R1 Golden Master Governance | adopted | strong | yes | repo tests, not run | yes | Baselines, Drift, Findings und OperationRun-Truth sind breit im Produkt verankert. |
| R2 Tenant Reviews, Evidence & Control Foundation | adopted | strong | yes | repo tests, not run | almost | Reviews, Evidence, Review Packs, Customer Review Workspace, governance-package delivery, compliance interpretation overlays und Control-/Exception-Layer greifen als reale Governance-Surface zusammen, aber die finale customer-safe self-serve productization bleibt offen. |
| Alert escalation + notification routing | implemented_verified | strong | partial | repo tests, not run | yes | Alert-Regeln, Dispatch, Cooldown und Quiet Hours sind real. |
| Governance & Architecture Hardening | implemented_partial | strong | partial | repo tests, not run | foundation-only | Viele Hardening-Slices sind bereits im Code, die Lane bleibt aber aktiv. |
| UI & Product Maturity Polish | implemented_partial | strong | partial | partial repo tests, not run | no | Empty States, Navigation, Localization und read-only Review-Polish sind real, aber kein geschlossenes Theme-Completion-Signal. |
| Secret & Security Hardening | implemented_verified | strong | yes | repo tests, not run | almost | Provider-Verifikation, Permission-Diagnostics und Redaction sind belastbar. |
| Baseline Drift Engine (Cutover) | adopted | strong | yes | repo tests, not run | yes | Compare- und Drift-Workflow wirken als produktive Kernfunktion. |
| R1.9 Platform Localization v1 | implemented_verified | strong | yes | repo tests, not run | foundation-only | Locale-Resolver, Override/Praeferenz, Workspace-Default, Fallback und lokalisierte Notifications sind repo-real. |
| Product Scalability & Self-Service Foundation | implemented_partial | strong | yes | repo tests, not run | almost | Onboarding, Support, Help, Entitlements, commercial lifecycle state handling und bounded support-desk handoff sind repo-real; Billing-, Trial- und Demo-Automation bleiben offen. |
| R2.0 Canonical Control Catalog Foundation | implemented_verified | strong | partial | repo tests, not run | foundation-only | Bereits implementiert und in Evidence/Reviews referenziert, aber kein eigenstaendiger Kundennutzen-Surface. |
| R2 Completion: customer review, support, help | implemented_partial | strong | yes | repo tests, not run | almost | Customer Review Workspace, released-review detail handoff, governance-package delivery, Support Diagnostics/Requests und Help-Katalog sind repo-real, aber die finale customer-safe productization ist noch nicht vollstaendig. |
| Compliance Evidence Mapping v1 | implemented_partial | strong | yes | repo tests, not run | foundation-only | Canonical control interpretation is rendered in tenant reviews and the customer review workspace, but broader framework coverage and auditor-facing mapping remain open. |
| Governance-as-a-Service Packaging v1 | implemented_partial | strong | yes | repo tests, not run | foundation-only | Governance package status, download messaging und current review-pack reuse sind repo-real, aber standalone recurring delivery workflows und breitere management packaging remain open. |
| Findings Workflow v2 / Execution Layer | adopted | strong | yes | repo tests, not run | almost | Triage, Ownership, My Work, Intake, Governance Inbox, Exceptions und Alerts/Hygiene sind real; Cross-Tenant-Decisioning bleibt spaeter. |
| Provider-missing policy visibility follow-up | specified | weak | no | no | no | Spec 261 ist als schmaler policy-only Follow-up vorbereitet; die breitere Lifecycle-Taxonomie bleibt strategisch und unimplementiert. |
| Platform Operations Maturity | implemented_partial | strong | yes | repo tests, not run | almost | System Panel, Control Tower und Ops Controls sind real; CSV/Raw Drilldowns bleiben offen. |
| Product Usage, Customer Health & Operational Controls | adopted | strong | yes | repo tests, not run | almost | Diese Mid-term-Lane ist im Repo bereits substanziell vorhanden. |
| Private AI Execution Governance Foundation | planned | none | no | no | no | Keine belastbare AI-Governance-Foundation im Repo. |
| MSP Portfolio & Operations | implemented_partial | strong | yes | repo tests, not run | foundation-only | Portfolio-Triage, canonical compare preview, preflight audit and launch continuity are repo-real; actual promotion execution and the broader decision workboard remain open. |
| Human-in-the-Loop Autonomous Governance | planned | none | no | no | no | Kein repo-verifizierter Decision-Pack- oder Approval-Workflow jenseits des jetzigen Exception-/Review-Layers. |
| Drift & Change Governance | implemented_partial | strong | yes | repo tests, not run | almost | Drift review, accepted-risk governance, exception validity und Governance-Inbox-Surfaces sind repo-real; portfolio-weite Eskalation bleibt offen. |
| Standardization & Policy Quality | planned | none | no | no | no | Keine starke Repo-Evidence fuer eine Intune-Linting- oder Policy-Quality-Oberflaeche. |
| PSA / Ticketing Handoff | implemented_verified | strong | yes | repo tests, not run | almost | Support Requests now include bounded external create/link handoff on the current tenant and operation-run contexts; broader multi-provider ITSM expansion remains separate work. |
| R1 Golden Master Governance | sellable | strong | yes | repo tests, not run | yes | Baselines, Drift, Findings und OperationRun-Truth sind breit im Produkt verankert. |
| R2 Tenant Reviews, Evidence & Control Foundation | fast sellable | strong | yes | repo tests, not run | yes | Reviews, Evidence, Review Packs, Customer Review Workspace, governance-package delivery, compliance interpretation overlays und Control-/Exception-Layer greifen als reale Governance-Surface zusammen; die letzte customer-safe self-serve productization bleibt offen. |
| Alert escalation + notification routing | sellable | strong | partial | repo tests, not run | yes | Alert-Regeln, Dispatch, Cooldown und Quiet Hours sind real. |
| Governance & Architecture Hardening | foundation-only | strong | partial | repo tests, not run | no | Viele Hardening-Slices sind bereits im Code, die Lane bleibt als platform seam work aktiv. |
| UI & Product Maturity Polish | implemented but not productized | strong | partial | partial repo tests, not run | no | Empty States, Navigation, Localization und read-only Review-Polish sind real, aber kein geschlossenes Theme-Completion-Signal. |
| Secret & Security Hardening | fast sellable | strong | yes | repo tests, not run | yes | Provider-Verifikation, Permission-Diagnostics und Redaction sind belastbar. |
| Baseline Drift Engine (Cutover) | sellable | strong | yes | repo tests, not run | yes | Compare- und Drift-Workflow wirken als produktive Kernfunktion. |
| R1.9 Platform Localization v1 | foundation-only | strong | yes | repo tests, not run | no | Locale-Resolver, Override/Praeferenz, Workspace-Default, Fallback und lokalisierte Notifications sind repo-real; `specs/252-platform-localization-v1/spec.md` ist die historische Foundation. |
| Product Scalability & Self-Service Foundation | fast sellable | strong | yes | repo tests, not run | yes | Onboarding, Support, Help, Entitlements, commercial lifecycle state handling und bounded support-desk handoff sind repo-real; Billing-, Trial- und Demo-Truth bleiben offen. |
| R2.0 Canonical Control Catalog Foundation | foundation-only | strong | partial | repo tests, not run | no | Bereits implementiert und in Evidence/Reviews referenziert, aber kein eigenstaendiger Kundennutzen-Surface. |
| R2 Completion: customer review, support, help | fast sellable | strong | yes | repo tests, not run | yes | Customer Review Workspace, released-review detail handoff, governance-package delivery, Support Diagnostics/Requests und Help-Katalog sind repo-real, aber die finale customer-safe productization ist noch nicht vollstaendig. |
| Compliance Evidence Mapping v1 | implemented but not productized | strong | yes | repo tests, not run | no | Canonical control interpretation is rendered in tenant reviews and the customer review workspace, but broader framework coverage and auditor-facing mapping remain open. |
| Governance-as-a-Service Packaging v1 | implemented but not productized | strong | yes | repo tests, not run | no | Governance package status, download messaging und current review-pack reuse sind repo-real, aber recurring delivery workflows und breitere management packaging remain open. |
| Findings Workflow v2 / Execution Layer | fast sellable | strong | yes | repo tests, not run | yes | Triage, Ownership, My Work, Intake, Governance Inbox, Exceptions und Alerts/Hygiene sind real; Cross-Tenant-Decisioning bleibt spaeter. |
| Provider-missing policy visibility follow-up | not implemented | weak | no | no | no | `specs/261-provider-missing-policy-visibility/spec.md` bleibt ein schmaler policy-only Follow-up; die breitere Lifecycle-Taxonomie ist getrennt. |
| Platform Operations Maturity | implemented but not productized | strong | yes | repo tests, not run | no | System Panel, Control Tower und Ops Controls sind real; CSV/Raw Drilldowns bleiben offen. |
| Product Usage, Customer Health & Operational Controls | implemented but not productized | strong | yes | repo tests, not run | no | Diese Mid-term-Lane ist im Repo bereits substanziell vorhanden, bleibt aber vor allem operatorseitige Produktisierung. |
| Private AI Execution Governance Foundation | foundation-only | strong | partial | repo tests, not run | no | `specs/248-private-ai-policy-foundation/spec.md` ist repo-real in Policy, Boundary, Settings und Ops Controls; der erste Runtime-Consumer fehlt noch. |
| MSP Portfolio & Operations | implemented but not productized | strong | yes | repo tests, not run | no | Portfolio-Triage, canonical compare preview, preflight audit and launch continuity are repo-real; actual promotion execution and the broader decision workboard remain open. |
| Human-in-the-Loop Autonomous Governance | not implemented | weak | no | no | no | Kein repo-verifizierter Decision-Pack- oder Approval-Workflow jenseits des jetzigen Exception-/Review-Layers. |
| Drift & Change Governance | fast sellable | strong | yes | repo tests, not run | yes | Drift review, accepted-risk governance, exception validity und Governance-Inbox-Surfaces sind repo-real; portfolio-weite Eskalation bleibt offen. |
| Standardization & Policy Quality | not implemented | none | no | no | no | Keine starke Repo-Evidence fuer eine Intune-Linting- oder Policy-Quality-Oberflaeche. |
| PSA / Ticketing Handoff | implemented but not productized | strong | yes | repo tests, not run | no | Support Requests include bounded external create/link handoff on the current tenant and operation-run contexts; broader multi-provider ITSM expansion remains separate work. |
## Implemented Capabilities
| Capability | Status | Backend | UI | Tests | RBAC/Audit | Sellable | Evidence |
| Capability | Product posture | Backend | UI | Tests | RBAC/Audit | Sellable | Evidence |
|---|---|---|---|---|---|---|---|
| OperationRun truth layer | implemented_verified | yes | partial | repo tests, not run | yes | foundation-only | `app/Models/OperationRun.php`; `tests/Feature/System/*`; `tests/Feature/ReviewPack/*` |
| Baseline profiles, snapshots and compare | implemented_verified | yes | yes | repo tests, not run | yes | yes | `app/Models/BaselineProfile.php`; `app/Models/BaselineSnapshot.php`; `app/Services/Baselines/BaselineCompareService.php` |
| Drift findings and governance pressure | adopted | yes | yes | repo tests, not run | yes | yes | `app/Models/Finding.php`; `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`; `tests/Feature/Findings/*` |
| Findings inboxes and governance inbox | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Filament/Pages/Findings/MyFindingsInbox.php`; `app/Filament/Pages/Findings/FindingsIntakeQueue.php`; `app/Filament/Pages/Governance/GovernanceInbox.php`; `tests/Feature/Findings/MyWorkInboxTest.php`; `tests/Feature/Governance/*` |
| Finding exceptions and risk acceptance workflow | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Models/FindingException.php`; `app/Services/Findings/FindingExceptionService.php`; `app/Filament/Resources/FindingExceptionResource.php`; `tests/Feature/Findings/FindingExceptionWorkflowTest.php` |
| Restore workflow with safety gates | implemented_verified | yes | yes | repo tests, not run | yes | yes | `app/Models/OperationRun.php`; restore gates and tests in `tests/Feature/Restore/*` |
| Evidence snapshots | implemented_verified | yes | yes | repo tests, not run | yes | foundation-only | `app/Models/EvidenceSnapshot.php`; `app/Services/Evidence/EvidenceSnapshotService.php`; `tests/Feature/Evidence/*` |
| Tenant reviews | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Models/TenantReview.php`; `app/Services/TenantReviews/TenantReviewService.php`; `tests/Feature/TenantReview/*` |
| Review pack generation and export | implemented_verified | yes | yes | repo tests, not run | yes | yes | `app/Models/ReviewPack.php`; `app/Services/ReviewPackService.php`; `tests/Feature/ReviewPack/*` |
| Customer review workspace | implemented_partial | yes | yes | repo tests, not run | yes | almost | `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `tests/Feature/Reviews/*`; `tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` |
| Governance package delivery surface | implemented_partial | yes | yes | repo tests, not run | yes | almost | `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `app/Filament/Resources/TenantReviewResource.php`; `tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`; `tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php` |
| Compliance evidence mapping overlay | implemented_partial | yes | yes | repo tests, not run | partial | foundation-only | `app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php`; `app/Services/TenantReviews/TenantReviewSectionFactory.php`; `tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php` |
| Alerts and notification routing | implemented_verified | yes | partial | repo tests, not run | yes | yes | `app/Services/Alerts/AlertDispatchService.php`; `tests/Feature/*Alert*` |
| Provider health, onboarding readiness and required permissions | adopted | yes | yes | repo tests, not run | yes | almost | `app/Jobs/ProviderConnectionHealthCheckJob.php`; `app/Services/Onboarding/OnboardingLifecycleService.php`; `app/Filament/Pages/TenantRequiredPermissions.php` |
| Permission posture reporting | implemented_verified | yes | yes | repo tests, not run | yes | yes | `app/Services/PermissionPosture/PermissionPostureFindingGenerator.php`; `tests/Feature/PermissionPosture/*` |
| Entra admin roles reporting | implemented_verified | yes | yes | repo tests, not run | yes | yes | `app/Services/EntraAdminRoles/EntraAdminRolesReportService.php`; `tests/Feature/EntraAdminRoles/*` |
| Stored reports substrate | implemented_verified | yes | partial | repo tests, not run | partial | foundation-only | `app/Models/StoredReport.php`; `tests/Feature/PermissionPosture/StoredReportModelTest.php`; `tests/Feature/EntraAdminRoles/StoredReportFingerprintTest.php` |
| Support diagnostics | adopted | yes | yes | repo tests, not run | yes | almost | `app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php`; `app/Filament/Pages/TenantDashboard.php`; `tests/Feature/SupportDiagnostics/*` |
| In-app support requests | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Models/SupportRequest.php`; `app/Support/SupportRequests/*`; `tests/Feature/SupportRequests/*` |
| External support-desk handoff | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Support/SupportRequests/ExternalSupportDeskHandoffService.php`; `app/Support/SupportRequests/SupportRequestSubmissionService.php`; `tests/Unit/Support/SupportRequests/ExternalSupportDeskHandoffServiceTest.php` |
| Product knowledge and contextual help | implemented_partial | yes | yes | repo tests, not run | partial | almost | `app/Support/ProductKnowledge/ContextualHelpCatalog.php`; `tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php` |
| Localization foundation | implemented_verified | yes | yes | repo tests, not run | partial | foundation-only | `app/Services/Localization/LocaleResolver.php`; `app/Http/Controllers/LocalizationController.php`; `tests/Feature/Localization/*` |
| Product telemetry | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Models/ProductUsageEvent.php`; `app/Filament/System/Widgets/ProductTelemetryKpis.php`; `tests/Feature/System/ProductTelemetry/*` |
| Customer health scoring | implemented_verified | yes | yes | repo tests, not run | partial | almost | `app/Filament/System/Widgets/CustomerHealthKpis.php`; `app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php`; `tests/Feature/System/CustomerHealth/*` |
| Operational controls | implemented_verified | yes | yes | repo tests, not run | yes | almost | `app/Models/OperationalControlActivation.php`; `app/Support/OperationalControls/*`; `tests/Feature/System/OpsControls/*` |
| Workspace entitlements | implemented_verified | yes | yes | repo tests, not run | yes | foundation-only | `app/Services/Entitlements/WorkspaceEntitlementResolver.php`; `tests/Feature/Filament/Settings/WorkspaceEntitlementsSettingsPageTest.php` |
| Commercial lifecycle state handling | implemented_verified | yes | yes | repo tests, not run | yes | foundation-only | `app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php`; `app/Filament/System/Pages/Directory/ViewWorkspace.php`; `tests/Feature/System/ViewWorkspaceEntitlementsTest.php`; `tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php` |
| Capability-first RBAC | adopted | yes | yes | repo tests, not run | yes | foundation-only | `app/Services/Auth/CapabilityResolver.php`; `app/Services/Auth/RoleCapabilityMap.php`; many `tests/Feature/Rbac/*` |
| Audit log foundation | adopted | yes | yes | repo tests, not run | yes | foundation-only | `app/Models/AuditLog.php`; `app/Services/Audit/WorkspaceAuditLogger.php`; many audit-focused feature tests |
| Canonical control catalog | implemented_verified | yes | partial | repo tests, not run | partial | foundation-only | `app/Support/Governance/Controls/CanonicalControlCatalog.php`; `config/canonical_controls.php`; `tests/Unit/Governance/*` |
| Portfolio triage continuity | implemented_verified | yes | yes | repo tests, not run | yes | foundation-only | `app/Services/PortfolioTriage/TenantTriageReviewService.php`; `app/Support/PortfolioTriage/*`; `tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php` |
| Cross-tenant compare preview and promotion preflight | implemented_verified | yes | yes | repo tests, not run | yes | foundation-only | `app/Filament/Pages/CrossTenantComparePage.php`; `app/Support/PortfolioCompare/CrossTenantComparePreviewBuilder.php`; `app/Support/PortfolioCompare/CrossTenantPromotionPreflight.php`; `tests/Feature/PortfolioCompare/*`; `tests/Unit/Support/PortfolioCompare/*` |
| OperationRun truth layer | foundation-only | yes | partial | repo tests, not run | yes | no | `app/Models/OperationRun.php`; `tests/Feature/System/*`; `tests/Feature/ReviewPack/*` |
| Baseline profiles, snapshots and compare | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/BaselineProfile.php`; `app/Models/BaselineSnapshot.php`; `app/Services/Baselines/BaselineCompareService.php` |
| Drift findings and governance pressure | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/Finding.php`; `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`; `tests/Feature/Findings/*` |
| Findings inboxes and governance inbox | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Filament/Pages/Findings/MyFindingsInbox.php`; `app/Filament/Pages/Findings/FindingsIntakeQueue.php`; `app/Filament/Pages/Governance/GovernanceInbox.php`; `tests/Feature/Findings/MyWorkInboxTest.php`; `tests/Feature/Governance/*` |
| Finding exceptions and risk acceptance workflow | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/FindingException.php`; `app/Services/Findings/FindingExceptionService.php`; `app/Filament/Resources/FindingExceptionResource.php`; `tests/Feature/Findings/FindingExceptionWorkflowTest.php` |
| Restore workflow with safety gates | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/OperationRun.php`; restore gates and tests in `tests/Feature/Restore/*` |
| Evidence snapshots | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/EvidenceSnapshot.php`; `app/Services/Evidence/EvidenceSnapshotService.php`; `tests/Feature/Evidence/*` |
| Tenant reviews | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/TenantReview.php`; `app/Services/TenantReviews/TenantReviewService.php`; `tests/Feature/TenantReview/*` |
| Review pack generation and export | implemented but not productized | yes | yes | repo tests, not run | yes | no | `specs/109-review-pack-export/spec.md`; `app/Models/ReviewPack.php`; `app/Services/ReviewPackService.php`; `tests/Feature/ReviewPack/*` |
| Customer review workspace | fast sellable | yes | yes | repo tests, not run | yes | yes | `specs/258-customer-review-productization/spec.md`; `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `tests/Feature/Reviews/*`; `tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` |
| Governance package delivery surface | implemented but not productized | yes | yes | repo tests, not run | yes | no | `specs/260-governance-service-packaging/spec.md`; `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `app/Filament/Resources/TenantReviewResource.php`; `tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`; `tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php` |
| Compliance evidence mapping overlay | implemented but not productized | yes | yes | repo tests, not run | partial | no | `specs/259-compliance-evidence-mapping/spec.md`; `app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php`; `app/Services/TenantReviews/TenantReviewSectionFactory.php`; `tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php` |
| Alerts and notification routing | sellable | yes | partial | repo tests, not run | yes | yes | `app/Services/Alerts/AlertDispatchService.php`; `tests/Feature/*Alert*` |
| Provider health, onboarding readiness and required permissions | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Jobs/ProviderConnectionHealthCheckJob.php`; `app/Services/Onboarding/OnboardingLifecycleService.php`; `app/Filament/Pages/TenantRequiredPermissions.php` |
| Permission posture reporting | sellable | yes | yes | repo tests, not run | yes | yes | `app/Services/PermissionPosture/PermissionPostureFindingGenerator.php`; `tests/Feature/PermissionPosture/*` |
| Entra admin roles reporting | sellable | yes | yes | repo tests, not run | yes | yes | `app/Services/EntraAdminRoles/EntraAdminRolesReportService.php`; `tests/Feature/EntraAdminRoles/*` |
| Stored reports substrate | foundation-only | yes | partial | repo tests, not run | partial | no | `app/Models/StoredReport.php`; `tests/Feature/PermissionPosture/StoredReportModelTest.php`; `tests/Feature/EntraAdminRoles/StoredReportFingerprintTest.php` |
| Support diagnostics | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php`; `app/Filament/Pages/TenantDashboard.php`; `tests/Feature/SupportDiagnostics/*` |
| In-app support requests | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/SupportRequest.php`; `app/Support/SupportRequests/*`; `tests/Feature/SupportRequests/*` |
| External support-desk handoff | implemented but not productized | yes | yes | repo tests, not run | yes | no | `app/Support/SupportRequests/ExternalSupportDeskHandoffService.php`; `app/Support/SupportRequests/SupportRequestSubmissionService.php`; `tests/Unit/Support/SupportRequests/ExternalSupportDeskHandoffServiceTest.php` |
| Product knowledge and contextual help | implemented but not productized | yes | yes | repo tests, not run | partial | no | `app/Support/ProductKnowledge/ContextualHelpCatalog.php`; `tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php` |
| Localization foundation | foundation-only | yes | yes | repo tests, not run | partial | no | `specs/252-platform-localization-v1/spec.md`; `app/Services/Localization/LocaleResolver.php`; `app/Http/Controllers/LocalizationController.php`; `tests/Feature/Localization/*` |
| Product telemetry | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/ProductUsageEvent.php`; `app/Filament/System/Widgets/ProductTelemetryKpis.php`; `tests/Feature/System/ProductTelemetry/*` |
| Customer health scoring | foundation-only | yes | yes | repo tests, not run | partial | no | `app/Filament/System/Widgets/CustomerHealthKpis.php`; `app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php`; `tests/Feature/System/CustomerHealth/*` |
| Operational controls | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/OperationalControlActivation.php`; `app/Support/OperationalControls/*`; `tests/Feature/System/OpsControls/*` |
| Governed AI policy foundation | foundation-only | yes | partial | repo tests, not run | yes | no | `specs/248-private-ai-policy-foundation/spec.md`; `app/Support/Ai/AiUseCaseCatalog.php`; `app/Support/Ai/GovernedAiExecutionBoundary.php`; `app/Support/Ai/AiDecisionAuditMetadataFactory.php`; `app/Filament/Pages/Settings/WorkspaceSettings.php`; `tests/Unit/Support/Ai/*`; `tests/Feature/SettingsFoundation/WorkspaceAiPolicySettingsTest.php`; `tests/Feature/System/OpsControls/AiExecutionOperationalControlTest.php` |
| Workspace entitlements | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/Entitlements/WorkspaceEntitlementResolver.php`; `tests/Feature/Filament/Settings/WorkspaceEntitlementsSettingsPageTest.php` |
| Commercial lifecycle state handling | foundation-only | yes | yes | repo tests, not run | yes | no | `specs/251-commercial-entitlements-billing-state/spec.md`; `app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php`; `app/Filament/System/Pages/Directory/ViewWorkspace.php`; `tests/Feature/System/ViewWorkspaceEntitlementsTest.php`; `tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php` |
| Capability-first RBAC | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/Auth/CapabilityResolver.php`; `app/Services/Auth/RoleCapabilityMap.php`; many `tests/Feature/Rbac/*` |
| Audit log foundation | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/AuditLog.php`; `app/Services/Audit/WorkspaceAuditLogger.php`; many audit-focused feature tests |
| Canonical control catalog | foundation-only | yes | partial | repo tests, not run | partial | no | `app/Support/Governance/Controls/CanonicalControlCatalog.php`; `config/canonical_controls.php`; `tests/Unit/Governance/*` |
| Portfolio triage continuity | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/PortfolioTriage/TenantTriageReviewService.php`; `app/Support/PortfolioTriage/*`; `tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php` |
| Cross-tenant compare preview and promotion preflight | fast sellable | yes | yes | repo tests, not run | yes | yes | `specs/043-cross-tenant-compare-and-promotion/spec.md`; `app/Filament/Pages/CrossTenantComparePage.php`; `app/Support/PortfolioCompare/CrossTenantComparePreviewBuilder.php`; `app/Support/PortfolioCompare/CrossTenantPromotionPreflight.php`; `tests/Feature/PortfolioCompare/*`; `tests/Unit/Support/PortfolioCompare/*` |
## Foundation-Only Capabilities
@ -117,36 +116,44 @@ ## Foundation-Only Capabilities
- Stored reports substrate: wichtig fuer Reports, Evidence und Diagnostics, aber kein eigenstaendiges Produktversprechen.
- Evidence snapshot substrate: tragende technische Basis fuer Reviews und Exports.
- Localization foundation: resolved locale precedence, Workspace-Default, User-Praeferenz/Override und Notification-Formatting sind real, aber Enablement statt eigener Produkt-Surface.
- Governed AI policy foundation: Use-Case-Katalog, Boundary, Audit-Metadata, Workspace-Policy-Surface und Ops-Control-Integration sind repo-real, aber noch ohne ersten Runtime-Consumer.
- Operational control registry and evaluator: starke Safety-Control-Foundation, primar operatorseitig.
- Customer health scoring: reale interne SaaS-Operations-Layer, aber noch keine eigenstaendige Kundenoberflaeche.
- Product telemetry und customer health scoring: reale operatorseitige SaaS-Operations-Layer, aber noch keine eigenstaendige sellable Oberflaeche.
- Portfolio triage continuity: sinnvoller Multi-Tenant-Unterbau, aber noch kein vollstaendiges Portfolio-Produkt.
## Partial Capabilities
## Fast-Sellable Or Not-Yet-Productized Capabilities
- Customer-facing review consumption: Tenant Reviews, Evidence Snapshots, Review Packs, the Customer Review Workspace, the customer-safe released-review detail mode, governance-package delivery cues, compliance interpretation overlays, and commercial-lifecycle-aware access states are repo-real; broader lifecycle/governance taxonomy work remains separate.
- Findings Workflow v2: Triage, Assignment, My Work, Intake, Governance Inbox, Exceptions, notifications, and the three queue-facing cleanup/hardening follow-through packages are now repo-backed; later cross-tenant action layers remain separate work.
- Product scalability and self-service: Onboarding, Support, Help, Entitlements, commercial lifecycle state handling, and external support-desk handoff are repo-real; broader trial/demo and commercialization layers still remain.
- Product scalability and self-service: Onboarding, Support, Help, Entitlements, commercial lifecycle state handling, and external support-desk handoff are repo-real; broader trial/demo and billing-subscription truth still remain.
- MSP portfolio operations: Portfolio-Triage plus cross-tenant compare preview and promotion preflight are repo-real; actual promotion execution and broader portfolio action orchestration remain open.
- Platform operations maturity: Control Tower und Ops Controls sind stark, aber einige geplante operatorseitige Drilldowns/Exports fehlen noch.
- Product knowledge rollout: Help-Katalog und Resolver sind real, aber noch nicht breit genug adoptiert fuer "fertig".
## Planned But Not Implemented
## Not Implemented
- Private AI Execution Governance Foundation
- Auditor Pack Delivery & Executive Export v1
- Cross-Tenant Promotion Execution v1
- Governance Decision Pack & Approval Workflow v1
- Customer-Facing Localization Adoption v1
- Billing & Subscription Truth Layer v1
- Stored Reports Surface v1
- Workspace & Tenant Closure Lifecycle v1
- First Governed AI Runtime Consumer v1
- Human-in-the-Loop Autonomous Governance
- Standardization & Policy Quality / Intune Linting
- Provider-Missing Policy Visibility & Restore Continuity v1 (Spec 261, specified only)
- Provider-Missing Policy Visibility & Restore Continuity v1 (`specs/261-provider-missing-policy-visibility/spec.md`, spec-backed prep only)
- Broader compliance frameworks and auditor-facing mapping beyond the current evidence overlay
## Release Readiness
| Release / Theme | Readiness | Notes |
|---|---|---|
| R1 Golden Master Governance | implemented | Die zentrale Governance- und Execution-Layer ist repo-verifiziert und breit adoptiert. |
| R2 Tenant Reviews & Evidence Packs | implemented | Reviews, Evidence Snapshots, Review Packs, Customer Review Workspace, released-review detail handoff, governance-package delivery, compliance interpretation overlays und Exception-/Accepted-Risk-Workflow sind repo-real; die finale customer-safe Productization bleibt als sellability follow-up offen. |
| R3 MSP Portfolio OS | partial | Portfolio-Triage sowie canonical compare preview/preflight sind da, aber actual promotion execution und portfolio-weite Action-Layer fehlen weiter. |
| Compliance Evidence Mapping v1 | partial | Compliance interpretation overlays sind repo-real in Tenant Reviews und Customer Review Workspace, aber breitere Framework-Abdeckung und auditor-facing mapping fehlen weiter. |
| Governance-as-a-Service Packaging v1 | partial | Governance package status, delivery messaging und current review-pack reuse sind repo-real; eine wiederholbare management-taugliche Packaging-Workflow-Layer ist nicht vollstaendig. |
| R1 Golden Master Governance | sellable | Die zentrale Governance- und Execution-Layer ist repo-verifiziert und breit adoptiert. |
| R2 Tenant Reviews & Evidence Packs | fast sellable | Reviews, Evidence Snapshots, Review Packs, Customer Review Workspace, released-review detail handoff, governance-package delivery, compliance interpretation overlays und Exception-/Accepted-Risk-Workflow sind repo-real; die finale customer-safe Productization bleibt als sellability follow-up offen. |
| R3 MSP Portfolio OS | implemented but not productized | Portfolio-Triage sowie canonical compare preview/preflight sind da, aber actual promotion execution und portfolio-weite Action-Layer fehlen weiter. |
| Compliance Evidence Mapping v1 | implemented but not productized | Compliance interpretation overlays sind repo-real in Tenant Reviews und Customer Review Workspace, aber breitere Framework-Abdeckung und auditor-facing mapping fehlen weiter. |
| Governance-as-a-Service Packaging v1 | implemented but not productized | Governance package status, delivery messaging und current review-pack reuse sind repo-real; eine wiederholbare management-taugliche Packaging-Workflow-Layer ist nicht vollstaendig. |
## Commercial Readiness
@ -160,7 +167,7 @@ ### Demo-ready
- Support diagnostics
- Permission posture and Entra admin roles reporting
### Almost sellable
### Fast sellable
- Review-driven governance workflow rund um Tenant Reviews, Customer Review Workspace, governance-package delivery, compliance interpretation overlays, accepted risks und Review Packs, aber noch nicht als vollstaendig productisierte customer-safe consumption experience
- Baseline drift and restore governance
@ -169,6 +176,14 @@ ### Almost sellable
- Support requests with contextual diagnostics and bounded external create/link handoff
- Provider readiness and permission posture reporting
### Implemented but not productized
- Review pack generation and export als wiederholbare auditor-/executive-ready delivery layer
- Broader compliance evidence mapping surface
- Standalone governance-as-a-service packaging workflow
- Cross-tenant compare preview and promotion preflight without execution
- Product knowledge and contextual help rollout
### Foundation-only
- OperationRun truth layer
@ -179,54 +194,55 @@ ### Foundation-only
- Stored reports substrate
- Evidence snapshot substrate
- Localization foundation
- Governed AI policy foundation
- Product telemetry
- Customer health scoring
- Operational controls
- Portfolio triage continuity
### Not sellable yet
### Not implemented
- Portfolio-wide promotion execution and decision workboard
- Broader compliance evidence mapping surface
- Standalone governance-as-a-service packaging workflow
- Private AI Execution Governance Foundation
- Auditor-ready executive export / auditor pack delivery
- Portfolio-wide promotion execution and governance decision-pack workflow
- Billing and subscription truth layer
- Stored reports product surface
- Customer-facing localization adoption
- Workspace and tenant closure lifecycle runtime follow-through
- First governed AI runtime consumer
## Open Gaps & Blockers
Queue audit note: the former queue-facing gap rows for customer review productization, governance convergence, the findings cleanup trio, compare/preflight, commercial lifecycle maturity, compliance evidence mapping, governance packaging, and external support-desk handoff were narrowed or removed here on 2026-05-01 because refreshed Spec 043 and Specs 251-260 now provide prepared or implemented packages for those bounded slices.
Queue audit note: no safe automatic next-best-prep target remains active. The remaining open lanes are now tracked as explicit manual promotions in `docs/product/spec-candidates.md` instead of being re-opened through automatic queue logic.
| Gap | Type | Impact | Roadmap Area | Recommended Spec |
|---|---|---|---|---|
| No safe automatic next-best-prep target is currently active | Planning blocker | `spec-candidates.md` had drifted behind current `specs/` truth, so automatic next-spec selection would have reopened already prepared or completed packages | Product planning / queue hygiene | none - require explicit promotion of the next candidate |
| Customer-safe review productization is not fully complete | Productization blocker | Customer review workspace, released-review details, governance-package delivery, compliance overlays, and lifecycle-aware access are repo-real, but the final calmer self-serve customer-safe polish is still incomplete | R2 review consumption | explicit follow-through only if re-promoted; do not reopen completed specs automatically |
| Portfolio promotion execution and the broader decision workboard remain absent | Product blocker | Compare preview and preflight are repo-real, but no execution path, persisted drafts, queueing, or wider portfolio action orchestration exists | MSP Portfolio & Operations | explicit new candidate or follow-up; do not reopen Spec 043 automatically |
| Provider-missing policy visibility follow-up remains specified only | Product blocker | Spec 261 exists as a bounded policy-only correction, but implementation has not landed and the broader lifecycle taxonomy stays deferred | Lifecycle governance / provider truth | Spec 261 if pressure becomes immediate |
| Workspace, Tenant & Managed Object Lifecycle Governance v1 remains deferred by design | Strategic blocker | The lifecycle taxonomy is still intentionally broader than the bounded slices that just landed and should not be auto-selected without an explicit roadmap decision | Lifecycle governance / enterprise trust | deferred strategic candidate only |
| AI governance foundation is absent | Architecture blocker | Future AI features would risk trust and policy drift if added directly | Private AI Execution Governance | P3 Private AI Execution Governance Foundation |
| Roadmap understates current repo truth | Documentation blocker | Prioritization can drift because strategy docs still lag compare/preflight, governance-package delivery, compliance overlays, commercial lifecycle handling, and support handoff slices | Product planning / roadmap maintenance | none - docs alignment |
| Test files were not executed for this ledger update | Testing blocker | This document relies on code plus test presence, not live runtime validation | all areas | none - run targeted suites |
| No safe automatic next-best-prep target is currently active | Planning boundary | `docs/product/spec-candidates.md` now keeps the active queue empty, so the next slice must be promoted deliberately instead of selected automatically | Product planning / queue hygiene | none - require explicit manual promotion |
| Auditor-ready executive export is still missing | Productization blocker | Review truth remains short of auditor-/executive-ready delivery without dedicated packaging | R2 review delivery | `Auditor Pack Delivery & Executive Export v1` |
| Cross-tenant promotion execution is still missing | Product blocker | Compare preview and preflight are repo-real, but the actual portfolio action remains absent | MSP Portfolio & Operations | `Cross-Tenant Promotion Execution v1` |
| Governance decision pack and approval workflow is still missing | Product blocker | Decision-based operating still lacks a bounded approval-ready action package with audit trail | Decision-based operating | `Governance Decision Pack & Approval Workflow v1` |
| Customer-facing localization adoption is incomplete | Productization blocker | Locale groundwork is repo-real, but customer-safe adoption remains incomplete | Localization / review productization | `Customer-Facing Localization Adoption v1` |
| Billing and subscription truth is missing | Commercial blocker | Entitlements and lifecycle state handling stop short of a durable billing/subscription truth layer | Commercial readiness | `Billing & Subscription Truth Layer v1` |
| Stored reports still lack a clear product surface | Product blocker | Retained evidence and review artifacts remain harder to consume than they should be | Reports / evidence consumption | `Stored Reports Surface v1` |
| Workspace and tenant closure follow-through is not started | Strategic blocker | The taxonomy exists, but closure/runtime semantics are not yet productized | Lifecycle governance / enterprise trust | `Workspace & Tenant Closure Lifecycle v1` |
| First governed AI runtime consumer is missing | Architecture blocker | The policy foundation exists, but there is no bounded runtime consumer proving the model end-to-end | Governed AI follow-through | `First Governed AI Runtime Consumer v1` |
## Recommended Next Specs
## Recommended Manual Promotions
- `No safe automatic next-best-prep target`: queue hygiene work is complete; do not reopen Specs 043 or 251-260 through another automatic selection pass.
- `Spec 261 execution decision`: if provider-missing pressure is immediate, execute the already-prepared policy-only follow-up instead of drafting a broader lifecycle patch.
- `Workspace, Tenant & Managed Object Lifecycle Governance v1`: still the main deferred strategic candidate, but only after an explicit roadmap/product decision promotes it into the active queue.
- `P3 Private AI Execution Governance Foundation`: should exist before feature-level AI adoption, not after it.
- `Auditor Pack Delivery & Executive Export v1` -> anchored by `specs/109-review-pack-export/spec.md`, `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/258-customer-review-productization/spec.md`, `specs/259-compliance-evidence-mapping/spec.md`, and `specs/260-governance-service-packaging/spec.md`
- `Cross-Tenant Promotion Execution v1` -> anchored by `specs/043-cross-tenant-compare-and-promotion/spec.md`
- `Governance Decision Pack & Approval Workflow v1` -> anchored by `specs/257-governance-decision-convergence/spec.md` and `docs/product/roadmap.md`
- `Customer-Facing Localization Adoption v1` -> anchored by `specs/252-platform-localization-v1/spec.md`, `specs/258-customer-review-productization/spec.md`, and `specs/260-governance-service-packaging/spec.md`
- `Billing & Subscription Truth Layer v1` -> anchored by `specs/247-plans-entitlements-billing-readiness/spec.md` and `specs/251-commercial-entitlements-billing-state/spec.md`
- `Stored Reports Surface v1` -> anchored by `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/260-governance-service-packaging/spec.md`, and `docs/product/implementation-ledger.md`
- `Workspace & Tenant Closure Lifecycle v1` -> anchored by `specs/262-lifecycle-governance-taxonomy/spec.md`
- `First Governed AI Runtime Consumer v1` -> anchored by `specs/248-private-ai-policy-foundation/spec.md`
## Roadmap Drift Notes
- `roadmap.md` understates current R2 implementation depth, but the ledger had overstated sellability. Customer Review Workspace, published review handoff, review-pack downloads und der Finding-Exception-/Risk-Acceptance-Workflow sind repo-real; the remaining gap is customer-safe productization, not review-foundation absence.
- `roadmap.md` understates findings workflow maturity. My Findings, Intake, Governance Inbox und Exception Queue existieren bereits im Repo.
- `roadmap.md` understates localization maturity. Locale resolution order, Workspace-Default, User-Praeferenz, lokalisierte Notifications und Fallback-Tests sind implementiert.
- `roadmap.md` understates the current R2 control foundation. Canonical controls, stored reports, permission posture and Entra admin roles are already repo-real, not just near-term ideas.
- `roadmap.md` understates product supportability. Support diagnostics, in-app support requests and contextual help already exist in the repo.
- `roadmap.md` understates operational maturity. Product telemetry, customer health and operational controls are already implemented and wired into the system panel.
- `roadmap.md` understates commercial foundations. Workspace entitlements, commercial lifecycle state handling, plan profiles and enforcement points already exist, even though full billing-state maturity does not.
- `roadmap.md` understates MSP portfolio preparation. Cross-tenant compare preview, promotion preflight, audit logging and launch continuity are already repo-real.
- `roadmap.md` understates governance-package delivery and compliance interpretation. The customer review workspace and released-review detail now expose governance-package status/download cues plus current evidence interpretation overlays.
- `roadmap.md` understates bounded external support handoff. Support requests now support current-scope external create/link handoff without introducing a separate support queue product.
- Queue-facing drift had become larger than roadmap drift alone: this ledger and `spec-candidates.md` were still naming already prepared or completed slices as open candidates even though refreshed Spec 043 and Specs 251-260 now carry prep or implementation-close-out evidence.
- The main drift pattern is still underestimation, but customer-review sellability now needs a more precise reading: the missing piece is no longer basic review read-only access, but the final customer-safe productization layer over an already real surface.
- `docs/product/roadmap.md` and `docs/product/spec-candidates.md` were corrected on 2026-05-02 to reflect manual-promotion-only backlog handling and repo-real follow-through on compare/preflight, governance-package delivery, compliance overlays, commercial lifecycle handling, support handoff, and AI foundation.
- The remaining documentation risk is no longer queue drift alone; it is overstating sellability on still-open follow-through slices such as auditor-ready export, promotion execution, governance decision packs, billing/subscription truth, stored reports surface, and the first governed AI runtime consumer.
- This ledger therefore treats review-driven governance and portfolio preparation as `fast sellable` or `implemented but not productized`, not `sellable`, until those explicit manual-promotion slices land.
- Tests referenced here remain repo-present only. They were not executed for this ledger update.
## Evidence Sources
@ -281,6 +297,9 @@ ## Evidence Sources
- `apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php`
- `apps/platform/app/Services/Entitlements/WorkspaceEntitlementResolver.php`
- `apps/platform/app/Services/PortfolioTriage/TenantTriageReviewService.php`
- `apps/platform/app/Support/Ai/AiUseCaseCatalog.php`
- `apps/platform/app/Support/Ai/GovernedAiExecutionBoundary.php`
- `apps/platform/app/Support/Ai/AiDecisionAuditMetadataFactory.php`
- `apps/platform/app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php`
- `apps/platform/app/Support/PortfolioCompare/CrossTenantComparePreviewBuilder.php`
- `apps/platform/app/Support/PortfolioCompare/CrossTenantPromotionPreflight.php`
@ -288,6 +307,7 @@ ## Evidence Sources
- `apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php`
- `apps/platform/app/Services/Audit/WorkspaceAuditLogger.php`
- `apps/platform/app/Services/Auth/CapabilityResolver.php`
- `apps/platform/app/Filament/Pages/Settings/WorkspaceSettings.php`
- `apps/platform/app/Services/Localization/LocaleResolver.php`
Wichtige Test-Anker im Repo:
@ -304,12 +324,15 @@ ## Evidence Sources
- `apps/platform/tests/Feature/System/CustomerHealth/*`
- `apps/platform/tests/Feature/System/ProductTelemetry/*`
- `apps/platform/tests/Feature/System/OpsControls/*`
- `apps/platform/tests/Feature/System/OpsControls/AiExecutionOperationalControlTest.php`
- `apps/platform/tests/Feature/SettingsFoundation/WorkspaceAiPolicySettingsTest.php`
- `apps/platform/tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php`
- `apps/platform/tests/Unit/Governance/*`
- `apps/platform/tests/Unit/Support/Ai/*`
- `apps/platform/tests/Unit/Support/PortfolioCompare/*`
- `apps/platform/tests/Unit/Support/SupportRequests/ExternalSupportDeskHandoffServiceTest.php`
- `apps/platform/tests/Unit/Entitlements/*`
## Last Updated
2026-05-01 on branch `platform-dev` (full repo-based maturity refresh against current specs and repo anchors)
2026-05-02 on branch `platform-dev` (ledger drift correction and alignment with `docs/product/roadmap.md` plus `docs/product/spec-candidates.md` after the manual-promotion split)

87
docs/product/roadmap.md
View File

@ -1,15 +1,15 @@
# Product Roadmap
> **Status:** Active
> **Last reviewed:** 2026-04-30
> **Last reviewed:** 2026-05-02
> **Use for:** Current product roadmap, release themes, and prioritization context
> **Do not use for:** Implementation truth, spec completion status, or delivery guarantees without repo verification
> **Scoped maintenance:** 2026-05-01 lifecycle/provider-missing wording alignment only; no full roadmap re-review was performed.
> **Scoped maintenance:** 2026-05-02 repo-based roadmap drift correction and queue/backlog alignment after the audit-derived product-truth review.
>
> Strategic thematic blocks and release trajectory.
> This is the "big picture" — not individual specs.
>
> Queue boundary: the active candidate queue lives in `spec-candidates.md`; older audit-derived candidate packages are historical inputs only.
> Queue boundary: the active candidate queue lives in `docs/product/spec-candidates.md`; the promotable candidate backlog there is manual promotion only, not auto-prep; older audit-derived candidate packages remain historical inputs only.
---
@ -28,18 +28,23 @@ ## Current Productization & Moat Priorities
| Order | Theme | Repo truth | Product posture | Why now | Candidate posture |
|---|---|---|---|---|---|
| 1 | Customer Review Workspace Productization v1 | Reviews, Evidence Snapshots, Review Packs, Customer Review Workspace, and accepted-risk foundations are repo-real | fast sellable | clearest sellability blocker between current repo truth and a customer-safe governance-of-record surface | active P0 candidate |
| 2 | Risk Acceptance & Accountability productization | Exception / risk-acceptance workflow is repo-verified, but customer-safe accountability presentation is not fully productized | fast sellable | strong MSP and German midmarket moat around documented decisions, expiry, reviewability, and audit trail | fold into Customer Review Workspace Productization and review/reporting follow-through, not a new greenfield foundation |
| 3 | Governance Decision Surface Convergence | Governance Inbox, My Findings, Intake, and Exception Queue are repo-real, but convergence is not | almost | reduces admin-tool sprawl and turns multiple queue surfaces into calmer decision work | active P1 candidate |
| 4 | Compliance Evidence Mapping v1 | Canonical controls, evidence, stored reports, reviews, and findings foundations are repo-real; customer-safe compliance mapping is not | foundation-only | strong governance moat for compliance-oriented MSP and Mittelstand reviews without certification claims | active P2 candidate |
| 5 | Governance-as-a-Service Packaging v1 | Review packs, exports, evidence, and accepted-risk foundations are repo-real; recurring executive/MSP packaging is not | foundation-only | turns governance truth into a repeatable MSP deliverable instead of one-off manual reporting | active P2 candidate |
| 6 | Cross-Tenant Compare & Promotion v1 | Portfolio triage exists; compare and promotion are not repo-proven | not implemented | strongest MSP multiplier after customer-safe review and decision workflows are calmer | active P1 candidate |
| 7 | Private AI Execution Governance Foundation | Spec 248 exists, but no repo-real governed AI execution layer is proven | only spec / not implemented | strategic moat later, but not ahead of current productization and portfolio-action gaps | keep as later strategic lane, not near-term blocker |
| 1 | Auditor Pack Delivery & Executive Export v1 | Review-pack export, evidence, tenant review, customer review productization, compliance mapping, and governance packaging foundations are already spec-backed and partially repo-real | fast sellable | clearest remaining step between repo-real governance truth and auditor-/executive-ready delivery | manual promotion only, not auto-prep |
| 2 | Customer Review Workspace Productization v1 | Reviews, Evidence Snapshots, Review Packs, Customer Review Workspace, and accepted-risk foundations are repo-real | fast sellable | clearest customer-safe governance-of-record surface gap | spec-backed follow-through, not active queue |
| 3 | Governance Decision Surface Convergence | Governance Inbox, My Findings, Intake, and Exception Queue are repo-real, but convergence remains incomplete | implemented but not productized | reduces admin-tool sprawl and turns multiple queue surfaces into calmer decision work | spec-backed follow-through, not active queue |
| 4 | Compliance Evidence Mapping v1 | Canonical controls, evidence, stored reports, reviews, and findings foundations are repo-real; customer-safe compliance mapping follow-through remains | implemented but not productized | strong governance moat for compliance-oriented MSP and Mittelstand reviews without certification claims | spec-backed follow-through, not active queue |
| 5 | Governance-as-a-Service Packaging v1 | Review packs, exports, evidence, and accepted-risk foundations are repo-real; recurring executive/MSP packaging follow-through remains | implemented but not productized | turns governance truth into a repeatable MSP deliverable instead of one-off manual reporting | spec-backed follow-through, not active queue |
| 6 | Cross-Tenant Promotion Execution v1 | Cross-tenant compare preview and promotion preflight are repo-real; execution is not | not implemented | strongest MSP multiplier after review and packaging lanes are calmer | manual promotion only, not auto-prep |
| 7 | Governance Decision Pack & Approval Workflow v1 | Decision convergence and decision-based operating framing are strong enough for a bounded human-in-the-loop slice, but the workflow itself is not implemented | not implemented | next narrow decision workflow without autonomous remediation | manual promotion only, not auto-prep |
| 8 | Customer-Facing Localization Adoption v1 | Locale foundation is repo-real; customer-facing adoption, glossary completion, and regression hardening remain | implemented but not productized | turns existing localization groundwork into customer-safe polish | manual promotion only, not auto-prep |
| 9 | Billing & Subscription Truth Layer v1 | Plans, entitlements, and commercial lifecycle are repo-real; billing/subscription truth is not | not implemented | closes the remaining commercial truth gap | manual promotion only, not auto-prep |
| 10 | Stored Reports Surface v1 | Stored-report substrate is repo-real through evidence and review foundations; product surface remains incomplete | foundation-only | makes retained governance artifacts usable without manual digging | manual promotion only, not auto-prep |
| 11 | First Governed AI Runtime Consumer v1 | Governed AI policy foundation is repo-real; no first governed runtime consumer is proven | not implemented | bounded post-foundation AI adoption after higher-priority sellability gaps | manual promotion only, not auto-prep |
Explicit anti-sprawl boundaries for this priority set:
- Do not reopen risk acceptance as a broad new foundation theme; reuse the existing exception/risk-acceptance workflow and productize its customer-safe accountability trail.
- Do not reopen private AI as a fresh roadmap idea; the foundation already exists at spec level and should remain behind current customer-facing and MSP-facing sellability gaps.
- Do not reopen private AI as a fresh roadmap idea; the foundation already exists in `specs/248-private-ai-policy-foundation/spec.md`, and the open roadmap question is only when to promote the first governed runtime consumer.
- Do not treat the promotable candidate backlog in `docs/product/spec-candidates.md` as an automatic prep queue; those items require explicit product decisions.
- Do not prioritize Tenant Trust Score / public governance profile, insurance connectors, Copilot shadow-IT governance, local-first/on-prem proxy, or a standalone Betriebsrat mode before customer-safe review consumption, decision convergence, compliance mapping, governance packaging, and compare/promotion are materially clearer.
---
@ -92,7 +97,7 @@ ### R1.9 Platform Localization v1 (DE/EN)
- Search/Sort/Filter auf kritischen Listen für locale-sensitives Verhalten prüfen
- QA/Foundation: Missing-Key Detection, Locale Regression Tests, Pseudolocalization Smoke Tests für kritische Flows
**Queue status**: no standalone active candidate right now; remaining localization work should be folded into customer-facing productization and UI-maturity follow-through unless a narrower repo-real gap emerges.
**Queue status**: no standalone active candidate right now; the historical foundation package is `specs/252-platform-localization-v1/spec.md`, and the remaining follow-through is `Customer-Facing Localization Adoption v1` in `docs/product/spec-candidates.md` as manual promotion only, not auto-prep.
### Product Scalability & Self-Service Foundation
Self-service and supportability foundation that keeps TenantPilot operable as a low-headcount, AI-assisted SaaS instead of drifting into manual onboarding, manual support, and founder-dependent customer operations.
@ -107,7 +112,7 @@ ### Product Scalability & Self-Service Foundation
- Customer-facing transparency hooks: product surfaces should be designed so customer read-only views, review workspaces, support requests, and review-pack downloads can reuse the same underlying entities instead of becoming parallel one-off features
- Private AI readiness hooks: support, review, diagnostic, and decision surfaces should be designed so later AI assistance can use governed context builders, data classification, usage budgets, local/private model policies, cache fingerprints, and human approval gates instead of direct feature-level AI calls
**Active specs**: — (not yet specced)
**Repo reality**: this is no longer an unspecced greenfield foundation. Onboarding, diagnostics, support requests, contextual help, entitlements, telemetry, customer health, and operational controls are already spec-backed or repo-real; the remaining roadmap gap is broader customer/self-service productization plus the narrower `Billing & Subscription Truth Layer v1` follow-up tracked in `docs/product/spec-candidates.md`.
---
@ -137,11 +142,12 @@ ### R1.x Foundation Hardening — Governance Platform Anti-Drift
- No AWS/GCP/SaaS connector implementation in this slice; this is anti-drift foundation work only
### R2 Completion — Evidence & Exception Workflows
- Review pack export (Spec 109 — done)
- Review pack export (`specs/109-review-pack-export/spec.md` — repo-real follow-through)
- Exception/risk-acceptance workflow for Findings → Spec 154 (repo-real foundation; the next product gap is accountability-trail productization in customer-safe review, expiry/re-review visibility, and management-ready reporting)
- Formal evidence/review-pack entity foundation → Spec 153 (evidence snapshots, draft) + Spec 155 (tenant review layer / review packs, draft)
- Formal evidence/review-pack entity foundation -> `specs/153-evidence-domain-foundation/spec.md` + `specs/155-tenant-review-layer/spec.md`
- Workspace-level PII override for review packs → deferred from 109
- Customer Review Workspace Productization v1 → sharpen customer-facing review consumption: baseline status, latest reviews, findings, accepted risks, evidence/review-pack downloads, customer-safe redaction, calmer access states, and no admin/remediation actions
- Customer Review Workspace Productization v1 -> `specs/258-customer-review-productization/spec.md` and the adjacent follow-through in `specs/259-compliance-evidence-mapping/spec.md` + `specs/260-governance-service-packaging/spec.md`
- Auditor Pack Delivery & Executive Export v1 -> manual-promotion follow-up that builds on `specs/109-review-pack-export/spec.md`, `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/258-customer-review-productization/spec.md`, `specs/259-compliance-evidence-mapping/spec.md`, and `specs/260-governance-service-packaging/spec.md` rather than reopening them as active queue work.
- Support Diagnostic Pack → connect tenant/review/finding/report/operation contexts into a reusable support bundle before support demand scales
- In-App Support Request with Context → attach the relevant diagnostic pack and ticket reference to support workflows without creating a separate support data model
- Product Knowledge & Contextual Help → reuse canonical glossary, outcome/reason semantics, and report/finding terminology as the product-help source layer
@ -168,13 +174,13 @@ ### Workspace, Tenant & Managed Object Lifecycle Governance
- Retention / compliance lifecycle: retained, export requested, deletion requested, deletion scheduled, legal hold / retention hold, purge due, purged
- Restoreability lifecycle: restorable, metadata only, blocked by dependency, not restorable, expired by retention
**Roadmap posture**: Strategic P2 enterprise-trust candidate, not immediate implementation. This should not block Customer Review Workspace Productization, Governance Decision Surface Convergence, or Cross-Tenant Compare & Promotion.
**Roadmap posture**: The taxonomy-first foundation is now captured in `specs/262-lifecycle-governance-taxonomy/spec.md`. The narrower runtime follow-through is `Workspace & Tenant Closure Lifecycle v1` in `docs/product/spec-candidates.md`, and it remains manual promotion only, not auto-prep.
**Important boundary**: Do not implement a narrow policy-only ghost lifecycle patch, Laravel `SoftDeletes` rollout, workspace deletion flow, tenant deletion flow, purge engine, or retention framework before this lifecycle taxonomy is agreed.
**Approved narrow exception**: Spec 261 (`provider-missing-policy-visibility`) now captures the bounded policy-only provider-missing truth correction. Keep future lifecycle, deletion, retention, and purge work taxonomy-first; do not generalize Spec 261 into the broader lifecycle model.
**Spec candidate**: `Workspace, Tenant & Managed Object Lifecycle Governance v1` in `docs/product/spec-candidates.md`.
**Spec-backed foundation**: `specs/262-lifecycle-governance-taxonomy/spec.md` is the agreed taxonomy-first package. Keep closure/runtime follow-through separate from the taxonomy and promote it only through `Workspace & Tenant Closure Lifecycle v1` in `docs/product/spec-candidates.md`.
### Platform Operations Maturity
- CSV export for filtered run metadata (deferred from Spec 114)
@ -228,6 +234,7 @@ ### Product Usage, Customer Health & Operational Controls
### Private AI Execution Governance Foundation
Strategic AI platform foundation for using AI inside TenantPilot without hard-coding public cloud AI calls, leaking tenant data, losing cost control, or forcing later rewrites.
**Repo reality**: `specs/248-private-ai-policy-foundation/spec.md` already captures the governed AI foundation. The open roadmap gap is no longer whether a foundation should exist, but when to promote the first governed runtime consumer.
**Goal**: Make AI local/private-first, explicitly governed, budgeted, cacheable, auditable, and human-approved. External public AI providers are disabled by default and only usable through workspace-level opt-in, data classification, redaction, usage limits, and approval gates.
**Why it matters**: TenantPilot sells governance, compliance readiness, evidence, and tenant trust. AI cannot be bolted on through direct feature-level API calls. The platform needs a reusable execution boundary so support summaries, finding explanations, review packs, decision packs, and customer communications can use AI later without rebuilding privacy, cost, provider, approval, and audit controls each time.
**Depends on**: Product Knowledge & Contextual Help, Support Diagnostic Pack, Decision Pack Contract & Approval Workflow, Product Usage & Adoption Telemetry, Plans / Entitlements & Billing Readiness, Operational Controls & Feature Flags, Security Trust Pack Light, audit log foundation, and workspace/RBAC isolation.
@ -364,7 +371,7 @@ ## Long-term
### Tenant-to-Tenant / Staging→Prod Promotion
Compare/diff between tenants, mapping UI (groups, scope tags, filters, named locations, app refs), promotion plan (preview → dry-run → cutover → verify).
**Source**: 0800-future-features, Spec 043 draft.
**Source**: 0800-future-features and `specs/043-cross-tenant-compare-and-promotion/spec.md`.
### Recovery Confidence ("Killer Feature")
Automated restore tests in test tenants, recovery readiness report, preflight score.
@ -388,12 +395,14 @@ ## Infrastructure & Platform Debt
| No shared lifecycle taxonomy for workspace, tenant, managed-object, retention, export, purge, and restoreability states | Local fixes such as ghost-policy handling, workspace deactivation, tenant removal, retention, or purge can create inconsistent deletion semantics and audit gaps | Covered by Workspace, Tenant & Managed Object Lifecycle Governance candidate |
| No structured support diagnostic bundle yet | Support cases require manual context gathering across tenants, runs, findings, providers, and reports | Covered by Product Scalability & Self-Service Foundation |
| No formal security trust pack yet | Enterprise sales and customer security reviews require repeated manual explanations | Covered by Solo-Founder SaaS Automation & Operating Readiness |
| No product usage/adoption telemetry yet | Founder cannot see onboarding drop-off, feature adoption, trial health, or support-triggering surfaces without manual investigation | Covered by Additional Solo-Founder Scale Guardrails |
| No customer health score yet | Churn, inactive customers, stale reviews, unhealthy provider connections, and unresolved high-risk findings may be noticed too late | Covered by Additional Solo-Founder Scale Guardrails |
| No explicit operational controls / feature flags lane | Incidents or risky features may require code changes or manual database intervention instead of safe operator controls | Covered by Additional Solo-Founder Scale Guardrails |
| No private AI execution foundation yet | Future AI features may call model providers directly, leak tenant context, become hard to audit, or require rewrites to support local/private models | Covered by Private AI Execution Governance Foundation |
| No AI usage budgeting / cost governance yet | AI-assisted summaries, decision packs, reviews, and support workflows may create uncontrolled compute/API costs and queue pressure | Covered by Private AI Execution Governance Foundation |
| No AI data classification / context-builder boundary yet | Raw provider payloads, personal data, or customer-confidential tenant context could be over-shared with models instead of sanitized purpose-specific context | Covered by Private AI Execution Governance Foundation |
| Auditor-ready executive export is not yet productized | Review truth still stops short of auditor-/executive-ready delivery without additional packaging | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Cross-tenant promotion execution is missing | Compare preview and preflight stop short of the actual portfolio action | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Governance decision pack and approval workflow is missing | Decision-based operating still lacks a bounded approval-ready action package with explicit audit trail | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Customer-facing localization adoption is incomplete | Repo-real locale groundwork is not yet fully productized across customer-safe governance surfaces | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Billing and subscription truth is missing | Commercial readiness still stops short of a durable billing/subscription truth layer | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Stored reports still lack a clear product surface | Retained evidence and review artifacts remain harder to consume than they should be | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| Workspace and tenant closure follow-through is not started | The taxonomy exists, but closure/runtime semantics are not yet productized | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| First governed AI runtime consumer is missing | The governed AI foundation exists, but no bounded runtime consumer proves the model end-to-end | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` |
| No no-customization governance yet | Customer-specific requests can silently turn the product into consulting work and create hidden maintenance obligations | Covered by Additional Solo-Founder Scale Guardrails |
| No business-continuity / founder-backup plan yet | Solo-founder operations create continuity risk for incidents, illness, vacation, access recovery, and customer trust | Covered by Additional Solo-Founder Scale Guardrails |
| No `.env.example` in repo | Onboarding friction | Open |
@ -406,31 +415,27 @@ ## Infrastructure & Platform Debt
---
## Priority Ranking (from Product Brainstorming)
## Priority Ranking (Current Manual Promotion Order)
1. Product Scalability & Self-Service Foundation
2. Product Usage, Customer Health & Operational Controls
3. Private AI Execution Governance Foundation
4. Decision-Based Operating / Governance Inbox
5. MSP Portfolio + Alerting
6. Drift + Approval Workflows
7. Evidence / Review Packs + Customer Review Workspace
8. Standardization / Linting
9. Promotion DEV→PROD
10. Recovery Confidence
11. Solo-Founder SaaS Automation & Operating Readiness
12. Additional Solo-Founder Scale Guardrails
1. Auditor Pack Delivery & Executive Export v1
2. Cross-Tenant Promotion Execution v1
3. Governance Decision Pack & Approval Workflow v1
4. Customer-Facing Localization Adoption v1
5. Billing & Subscription Truth Layer v1
6. Stored Reports Surface v1
7. Workspace & Tenant Closure Lifecycle v1
8. First Governed AI Runtime Consumer v1
---
## How to use this file
- **Big product and operating themes** live here.
- **Concrete spec candidates** → see [spec-candidates.md](spec-candidates.md)
- **Concrete spec candidates** → see `docs/product/spec-candidates.md`
- **Lifecycle / deletion / retention work must be taxonomy-first**: do not promote narrow ghost-policy, workspace deletion, tenant deletion, purge, or retention specs until the shared Workspace, Tenant & Managed Object Lifecycle Governance candidate defines the platform semantics.
- **Company automation / solo-founder operating items** live here as strategic tracks first; only product-impacting or repeatable engineering work should become spec candidates.
- **Solo-founder guardrails** should remain visible even when they are not immediate product specs, because they define what must become measurable, controllable, delegable, or documented before customer volume grows.
- **Governance positioning is Microsoft-first, provider-extensible**: roadmap language should keep the initial product scope focused on Microsoft tenant governance while avoiding unnecessary Microsoft-only coupling in platform-level abstractions.
- **AI positioning is local/private-first and provider-adapter-based**: roadmap language should avoid direct feature-level public AI calls and instead route AI through use-case registries, data classification, context builders, policy gates, budget gates, provider adapters, audit trails, and human approval workflows.
- **Small discoveries from implementation** → see [discoveries.md](discoveries.md)
- **Product principles** → see [principles.md](principles.md)
- **Small discoveries from implementation** → see `docs/product/discoveries.md`
- **Product principles** → see `docs/product/principles.md`

88
docs/product/spec-candidates.md
View File

@ -53,6 +53,94 @@ ## Active Candidate Queue
The historical record for `Workspace, Tenant & Managed Object Lifecycle Governance v1` remains below because it was promoted intentionally, not automatically, into Spec 262 and must not re-enter the active auto-prep queue.
## Promotable Candidate Backlog
**Boundary**: manual promotion only, not auto-prep. These items are intentionally outside `next-best-prep` and require an explicit product decision before any future spec refresh or follow-up work.
### Auditor Pack Delivery & Executive Export v1
- **Priority**: 1
- **Repo truth**: review-pack export, evidence, tenant review, customer review productization, compliance mapping, and governance packaging foundations are already spec-backed.
- **Why promotable now**: this is the clearest remaining step between repo-real governance truth and auditor-/executive-ready delivery.
- **Why manual promotion only**: this is a bounded packaging and export decision, not an automatic next-best-prep foundation gap.
- **Anchors**:
- `specs/109-review-pack-export/spec.md`
- `specs/153-evidence-domain-foundation/spec.md`
- `specs/155-tenant-review-layer/spec.md`
- `specs/258-customer-review-productization/spec.md`
- `specs/259-compliance-evidence-mapping/spec.md`
- `specs/260-governance-service-packaging/spec.md`
### Cross-Tenant Promotion Execution v1
- **Priority**: 2
- **Repo truth**: cross-tenant compare preview and promotion preflight are already prepared, but execution is still the missing product action.
- **Why promotable now**: this is the next MSP-multiplier after customer-safe review and packaging follow-through.
- **Why manual promotion only**: the repo already has the compare/preflight preparation package, so only the narrower execution slice should be promoted deliberately.
- **Anchors**:
- `specs/043-cross-tenant-compare-and-promotion/spec.md`
### Governance Decision Pack & Approval Workflow v1
- **Priority**: 3
- **Repo truth**: governance convergence is spec-backed, but the bounded human-in-the-loop decision-pack workflow is still a distinct follow-up gap.
- **Why promotable now**: it is the next decision-based operating slice after convergence, without expanding into autonomous remediation.
- **Why manual promotion only**: this must stay an explicit product choice because the v1 scope is intentionally narrow: decision pack, reason, impact, evidence, recommended action, approve, reject, snooze, assign, audit trail, optional OperationRun link, no autonomous remediation in v1.
- **Anchors**:
- `specs/257-governance-decision-convergence/spec.md`
- `docs/product/roadmap.md`
### Customer-Facing Localization Adoption v1
- **Priority**: 4
- **Repo truth**: the localization foundation is already spec-backed; the open gap is customer-facing adoption, glossary completion, and productized surface coverage.
- **Why promotable now**: localization is now a productization follow-through task, not a greenfield foundation.
- **Why manual promotion only**: the broad foundation is already covered, so only a narrower adoption slice should be promoted deliberately.
- **Anchors**:
- `specs/252-platform-localization-v1/spec.md`
- `specs/258-customer-review-productization/spec.md`
- `specs/260-governance-service-packaging/spec.md`
### Billing & Subscription Truth Layer v1
- **Priority**: 5
- **Repo truth**: plans, entitlements, and commercial lifecycle maturity are already spec-backed, but the billing/subscription truth layer is still missing.
- **Why promotable now**: this is the remaining commercial truth gap after entitlements and lifecycle groundwork.
- **Why manual promotion only**: the broad readiness work is already covered, so this should not be reintroduced as an automatic foundation candidate.
- **Anchors**:
- `specs/247-plans-entitlements-billing-readiness/spec.md`
- `specs/251-commercial-entitlements-billing-state/spec.md`
### Stored Reports Surface v1
- **Priority**: 6
- **Repo truth**: the stored-reports substrate is already grounded by evidence and review foundations, but the product surface remains incomplete.
- **Why promotable now**: this is the cleanest path from retained governance artifacts to a customer- and operator-usable surface.
- **Why manual promotion only**: this is a focused product-surface follow-up, not an unprepared foundation gap.
- **Anchors**:
- `specs/153-evidence-domain-foundation/spec.md`
- `specs/155-tenant-review-layer/spec.md`
- `specs/260-governance-service-packaging/spec.md`
- `docs/product/implementation-ledger.md`
### Workspace & Tenant Closure Lifecycle v1
- **Priority**: 7
- **Repo truth**: lifecycle taxonomy is already explicitly captured as a spec-backed foundation, but closure/runtime follow-through is still open.
- **Why promotable now**: it is the next bounded runtime slice after the taxonomy-first package.
- **Why manual promotion only**: it must remain a deliberate follow-up and not collapse back into an automatic reopening of the broader taxonomy work.
- **Anchors**:
- `specs/262-lifecycle-governance-taxonomy/spec.md`
### First Governed AI Runtime Consumer v1
- **Priority**: 8
- **Repo truth**: the private AI governance foundation is already spec-backed, but there is still no first real governed runtime consumer.
- **Why promotable now**: it is the clearest bounded follow-up once higher-priority sellability, promotion, and commercial-truth gaps are addressed.
- **Why manual promotion only**: the foundation already exists, so the next move must be an explicit runtime-use-case decision rather than a repeated foundation-prep cycle.
- **Anchors**:
- `specs/248-private-ai-policy-foundation/spec.md`
## Deferred / Existing Drafts Outside the Current Queue
These items are still useful, but they are not the next best open specs from the current repo state.

52
specs/263-auditor-pack-executive-export/checklists/requirements.md Normal file
View File

@ -0,0 +1,52 @@
# Specification Quality Checklist: Auditor Pack Delivery & Executive Export v1
**Purpose**: Validate specification completeness and repo fit before implementation
**Created**: 2026-05-02
**Feature**: [spec.md](../spec.md)
## Content Quality
- [x] The spec stays on one bounded follow-up over the current `ReviewPack` family instead of inventing a second package domain.
- [x] The spec is product- and behavior-oriented and does not read like an implementation diff.
- [x] The spec explicitly names the current repo-real foundations it builds on: review-pack export, customer review workspace, compliance interpretation, and governance-package delivery.
- [x] Mandatory repo sections for scope, RBAC, disclosure, testing, and proportionality are completed.
## Requirement Completeness
- [x] No `[NEEDS CLARIFICATION]` markers remain.
- [x] Requirements are testable and bounded to one released-review delivery contract.
- [x] The spec explains what remains in scope versus what is intentionally deferred.
- [x] Acceptance scenarios cover export initiation, read-only delivery, and tenant-safe audit or entitlement behavior.
- [x] Edge cases cover missing packs, expired packs, partial evidence, and blocked commercial lifecycle states.
## Candidate Selection Gate
- [x] The selected candidate exists in `docs/product/spec-candidates.md` and `docs/product/roadmap.md`.
- [x] No existing spec package already covers `Auditor Pack Delivery & Executive Export v1` as its own bounded slice.
- [x] Related anchor specs were checked for completion or close-out signals and treated as context only: `109`, `153`, `155`, `258`, `259`, and `260`, with current repo code and tests used as implementation-truth validation for the delta.
- [x] The chosen slice is smaller and higher-priority than the deferred alternatives from the manual-promotion backlog.
## Feature Readiness
- [x] The slice is an explicit delta follow-up over already prepared customer-safe review/package work and stays on one current `ReviewPack` bundle instead of reopening those inherited surfaces wholesale.
- [x] The spec explicitly reuses the current `ReviewPackGenerate` and signed download seams.
- [x] The spec forbids new panel/provider changes, new global-search scope, and new asset strategy.
- [x] The spec keeps one dominant action per current operator/customer surface and does not reopen broader packaging, branding, or recurring-delivery scope.
## Test Governance
- [x] Planned validation stays bounded to existing `TenantReview`, `Reviews`, and `ReviewPack` feature families plus the current customer-review browser smoke.
- [x] No new heavy-governance or new browser family is introduced.
- [x] The runtime proof commands stay consistent across spec, plan, and tasks, while Pint remains standard implementation hygiene.
## Notes
- Reviewed against `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, `docs/product/implementation-ledger.md`, `specs/109-review-pack-export/spec.md`, `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/258-customer-review-productization/spec.md`, `specs/259-compliance-evidence-mapping/spec.md`, `specs/260-governance-service-packaging/spec.md`, current review/review-pack code and tests under `apps/platform`, and `.specify/memory/constitution.md` on 2026-05-02.
- No application implementation was performed while preparing this package.
## Review Outcome
- **Outcome class**: `acceptable-special-case`
- **Outcome**: `keep`
- **Reason**: The spec promotes the highest-priority manual backlog item, now records itself as a delta follow-up over the already prepared review/package foundations, stays on one current artifact family, and narrows the sellability gap to one externally deliverable bundle.
- **Workflow result**: Ready for implementation.

215
specs/263-auditor-pack-executive-export/plan.md Normal file
View File

@ -0,0 +1,215 @@
# Implementation Plan: Auditor Pack Delivery & Executive Export v1
**Branch**: `263-auditor-pack-executive-export` | **Date**: 2026-05-02 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/263-auditor-pack-executive-export/spec.md`
## Summary
This is an explicit delta follow-up over Specs 258-260 and the current review-package code path. The existing customer-safe workspace/detail delivery semantics, current operator export initiation, current signed download route, and current governance-package availability states are inherited. The implementation scope is only to make the existing current bundle externally deliverable by adding one human-readable executive entrypoint inside that bundle, making appendix roles explicit, and applying the minimal wording changes needed to explain that new bundle contract. The implementation must stay on current released-review, review-pack, evidence, and interpretation truth with no new artifact family, no new panel, and no new recurring-delivery workflow.
## Inherited Baseline / Explicit Delta
### Inherited baseline
- `CustomerReviewWorkspace` already owns the calm workspace delivery-selection surface.
- released-review detail already owns the customer-safe governance-package summary and signed download action.
- published operator review detail already owns `export_executive_pack` and current `ReviewPackGenerate` initiation.
- the current review-derived ZIP baseline already contains `metadata.json`, `summary.json`, and `sections.json`.
### Explicit delta in this plan
- preserve the existing ZIP baseline entries and add one executive-first entrypoint file
- extend delivery metadata so the preserved ZIP entries are explicitly framed as the structured appendix
- update only the wording on the inherited workspace/detail surfaces that is required to describe the new bundle contract
## Technical Context
**Language/Version**: PHP 8.4, Laravel 12, Filament v5, Livewire v4
**Primary Dependencies**: Filament admin surfaces, current `ReviewPackService`, `GenerateReviewPackJob`, `ReviewPackDownloadController`, `TenantReviewComposer`, `ArtifactTruthPresenter`
**Storage**: PostgreSQL plus private `exports` disk for the existing `ReviewPack` ZIP artifact
**Testing**: Pest feature tests plus one bounded browser smoke
**Validation Lanes**: `confidence`, `browser`
**Target Platform**: Existing Laravel admin runtime under `apps/platform`
**Project Type**: Laravel monolith with Filament admin surfaces
**Performance Goals**: No new provider calls, no second generation flow, and no additional queue family beyond the current `ReviewPackGenerate` run
**Constraints**: No new persisted delivery domain, no new panel/provider/assets, no raw internal diagnostics in the executive entrypoint, preserve current `404`/`403` semantics, preserve current signed download path
**Scale/Scope**: One released review at a time, one current export bundle per released review
## UI / Surface Guardrail Plan
- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament surfaces plus one bounded export entrypoint rendered from existing product truth
- **Shared-family relevance**: review-pack delivery, governance-package wording, detail-summary disclosure, download actions
- **State layers in scope**: page, detail, disclosure state
- **Audience modes in scope**: operator-MSP, customer-admin, customer-read-only, auditor-read-only
- **Decision/diagnostic/raw hierarchy plan**: decision-first delivery readiness and executive summary first, diagnostics second, raw/support detail last
- **Raw/support gating plan**: raw provider payloads, fingerprints, and internal reason semantics stay hidden from the executive entrypoint and customer-safe default surfaces
- **One-primary-action / duplicate-truth control**: workspace rows keep `Open review` only; released-review detail keeps one dominant safe download action; operator detail keeps the existing export initiation action
- **Handling modes by drift class or surface**: `report-only` for unchanged operator-only pack detail surfaces; `review-mandatory` for any change that would add a second delivery action or a second package domain
- **Repository-signal treatment**: `review-mandatory`
- **Special surface test profiles**: `shared-detail-family`
- **Required tests or manual smoke**: focused feature coverage plus the existing bounded browser smoke for `CustomerReviewWorkspace`
- **Exception path and spread control**: none; any proposal for a new artifact family, new panel, or PDF engine is a scope split, not an in-feature exception
- **Active feature PR close-out entry**: Smoke Coverage
## Shared Pattern & System Fit
- **Cross-cutting feature marker**: yes
- **Systems touched**: `CustomerReviewWorkspace`, `TenantReviewResource`, `ViewTenantReview`, `ReviewPackService`, `GenerateReviewPackJob`, `ReviewPackDownloadController`, `TenantReviewComposer`, `TenantReviewSectionFactory`, `ArtifactTruthPresenter`, localization files, and current audit IDs
- **Shared abstractions reused**: `ReviewPackService`, current `ReviewPackGenerate` `OperationRun` contract, current signed download controller, `ArtifactTruthPresenter`, `TenantReviewComposer`, `TenantReviewSectionFactory`, and `WorkspaceAuditLogger`
- **New abstraction introduced? why?**: none required by default. If implementation needs one helper to assemble delivery metadata or executive-export markup, it must stay local to current review-pack generation and not become a new export framework.
- **Why the existing abstraction was sufficient or insufficient**: current seams already solve entitlement, review anchoring, and bundle generation. They are only missing an explicit stakeholder-ready entrypoint and explicit appendix framing.
- **Bounded deviation / spread control**: none
## OperationRun UX Impact
- **Touches OperationRun start/completion/link UX?**: yes
- **Central contract reused**: existing `ReviewPackGenerate` start UX and terminal notification flow
- **Delegated UX behaviors**: queued toast, dedupe-or-reuse handling, current run completion semantics, and current signed download follow-up stay delegated to existing review-pack infrastructure
- **Surface-owned behavior kept local**: internal published review detail decides when the export action is offered; customer-safe released-review detail remains download-only
- **Queued DB-notification policy**: unchanged from the current review-pack contract
- **Terminal notification path**: unchanged
- **Exception path**: none
## Provider Boundary & Portability Fit
- **Shared provider/platform boundary touched?**: no
- **Provider-owned seams**: existing provider-specific report names remain appendix-only and secondary
- **Platform-core seams**: delivery wording, evidence-basis wording, and customer-safe summary semantics remain platform-owned
- **Neutral platform terms / contracts preserved**: governance package, released review, evidence basis, delivery readiness, accepted risks, governance decisions
- **Retained provider-specific semantics and why**: provider-specific report or evidence names can remain in the appendix because the appendix is secondary and evidence-oriented, not the primary executive narrative
- **Bounded extraction or follow-up path**: none
## Constitution Check
*GATE: Must pass before implementation begins and again before merge.*
- Inventory-first: unchanged; all delivery content stays derived from current review, evidence snapshot, stored reports, and current review-pack truth
- Read/write separation: write path remains only the current review-pack generation flow; customer-safe delivery remains read-only
- Graph contract path: no Graph calls are added
- Deterministic capabilities: current review and review-pack capability derivation stays authoritative
- RBAC-UX: workspace membership and tenant/review entitlement remain `404` boundaries; current in-scope capability denials remain `403`
- Workspace isolation: unchanged
- Tenant isolation: unchanged
- Run observability: current `ReviewPackGenerate` `OperationRun` path remains the only generation run path; no new run type or queue family is introduced
- OperationRun start UX: existing shared review-pack start UX remains authoritative
- Ops-UX lifecycle and summary counts: unchanged
- Test governance: keep proof bounded to current review, review-pack, and customer-workspace test families plus one existing browser smoke
- Proportionality / persistence / bloat: no new table, new artifact family, or delivery workflow state is allowed
- Shared pattern first: current review-pack export and download paths must be extended instead of bypassed
- Provider boundary: unchanged
- V1 explicitness / few layers: prefer direct extension of current bundle generation and current UI disclosure
- Badge semantics: reuse the current governance-package availability and artifact-truth badge mapping
- Filament-native UI: keep current native Filament pages and detail surfaces; no new custom dashboard shell
- UI/UX surface taxonomy and decision-first operating model: workspace remains registry-first; released-review detail remains package-owning context
- Audience-aware disclosure: executive-ready summary first, appendix second, raw/internal detail hidden by default
- Action-surface discipline: workspace rows keep one open action, released-review detail keeps one dominant download action, operator detail keeps one dominant export action
## Test Governance Check
- **Test purpose / classification by changed surface**: Feature, Browser
- **Affected validation lanes**: `confidence`, `browser`
- **Why this lane mix is the narrowest sufficient proof**: the slice changes bundle contents, delivery wording, and existing actions on current review surfaces. Focused feature coverage plus the current browser smoke are sufficient without widening into heavy-governance or new browser families.
- **Narrowest proving command(s)**:
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php`
- **Fixture / helper / factory / seed / context cost risks**: reuse current released-review, evidence, and review-pack fixtures only; avoid new seeded report families or provider setup
- **Expensive defaults or shared helper growth introduced?**: no
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: `shared-detail-family`
- **Closing validation and reviewer handoff**: reviewers should confirm that one current `ReviewPack` bundle still drives the entire delivery path and that the browser smoke remains bounded to the existing workspace flow
- **Budget / baseline / trend follow-up**: none
- **Review-stop questions**: lane fit, bundle truth staying on current artifact family, raw-detail leakage, and accidental second-delivery-domain drift
- **Escalation path**: none
- **Active feature PR close-out entry**: Smoke Coverage
## Project Structure
### Documentation (this feature)
```text
specs/263-auditor-pack-executive-export/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
└── requirements.md
```
### Source Code (expected implementation surfaces)
```text
apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/app/Filament/Resources/TenantReviewResource.php
apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
apps/platform/app/Services/ReviewPackService.php
apps/platform/app/Jobs/GenerateReviewPackJob.php
apps/platform/app/Http/Controllers/ReviewPackDownloadController.php
apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
apps/platform/app/Services/TenantReviews/TenantReviewComposer.php
apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php
apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php
apps/platform/resources/views/review-packs/...
apps/platform/lang/en/localization.php
apps/platform/lang/de/localization.php
apps/platform/tests/Feature/Reviews/...
apps/platform/tests/Feature/TenantReview/...
apps/platform/tests/Feature/ReviewPack/...
apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
```
**Structure Decision**: keep the implementation inside the existing admin-plane review and review-pack surfaces. If a dedicated executive-export Blade template is needed, add it under `apps/platform/resources/views/review-packs/` and keep it local to current `ReviewPack` generation.
## Data / Migration Implications
- Prefer extending current bundle contents and current JSON metadata over schema changes.
- Preserve the current review-derived ZIP baseline entries `metadata.json`, `summary.json`, and `sections.json`; the new contract adds one executive-first entrypoint and explicit appendix-role metadata over that baseline.
- No new `ReviewPack` table columns, no new delivery table, and no new artifact registry should be required for v1.
- If implementation cannot express delivery metadata inside the current pack contents or current JSON summary surfaces, stop and split rather than widening persistence scope.
## Rollout Considerations
- Filament remains v5 on Livewire v4. No panel-provider change is required, and provider registration remains in `apps/platform/bootstrap/providers.php`.
- No global search change is required because the affected surfaces stay on existing pages and non-globally-searchable resources.
- No destructive action is added. Existing export generation and download paths remain the only user-triggered flows.
- No new asset registration is expected; any human-readable executive entrypoint should be rendered from existing server-side view capabilities and included in the current bundle.
## Risk Controls
- Reject any implementation that introduces a second delivery artifact family or a new export registry.
- Reject any implementation that adds PDF/report-engine infrastructure or recurring delivery automation in this slice.
- Reject any implementation that exposes raw provider payloads or internal reason ownership in the executive entrypoint.
- Keep customer-safe read-only download semantics and current operator-side export initiation separate.
## Implementation Phases
### Phase 0 - Confirm Current Delivery Truth
- Verify the current review-derived pack contents and metadata contract in `ReviewPackService`, `GenerateReviewPackJob`, and current review-pack tests.
- Verify the current customer-workspace and released-review detail delivery semantics in `CustomerReviewWorkspace`, `ViewTenantReview`, and their tests.
### Phase 1 - Extend The Current Bundle
- Add one human-readable executive entrypoint file to the current review-derived bundle.
- Extend bundle metadata so the executive entrypoint and appendix roles are explicit.
- Keep the current structured appendix files intact and secondary.
### Phase 2 - Align Surfaces With The Delivery Contract
- Update workspace and released-review detail copy so readiness, evidence basis, and delivery wording reflect the new bundle contract.
- Keep `Open review` and `Download governance package` as the dominant safe actions in their existing contexts.
### Phase 3 - Harden Audit, Permissions, And Download Continuity
- Reuse current audit events and signed download controller.
- Confirm export initiation and ready-pack download continue to follow current capability and entitlement rules.
### Phase 4 - Validate And Stop
- Run the planned `confidence` proof and the existing browser smoke.
- Verify no new run type, no new artifact family, no new panel/provider/assets, and no raw-detail leakage.
## Why This Plan Is Narrow Enough
The repo already has a generated review-pack artifact, an operator export action, a customer-safe download action, and shared governance-package meaning. This plan changes only the delivery contract of that existing artifact and the wording on the two existing review surfaces that expose it. Everything broader stays explicitly deferred.

308
specs/263-auditor-pack-executive-export/spec.md Normal file
View File

@ -0,0 +1,308 @@
# Feature Specification: Auditor Pack Delivery & Executive Export v1
**Feature Branch**: `263-auditor-pack-executive-export`
**Created**: 2026-05-02
**Status**: Ready for implementation
**Input**: User description: "Promote the top manual backlog item from `docs/product/spec-candidates.md` and `docs/product/roadmap.md` into a new Spec Kit package that turns current review-pack and governance-package truth into one auditor-ready and executive-readable delivery bundle without reopening the existing review, evidence, compliance-mapping, or governance-packaging foundations."
## Inherited Baseline / Explicit Delta
This package is an explicit delta follow-up over already prepared and partly repo-real foundations, especially `specs/109-review-pack-export/spec.md`, `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/258-customer-review-productization/spec.md`, `specs/259-compliance-evidence-mapping/spec.md`, and `specs/260-governance-service-packaging/spec.md`.
Inherited baseline for 263:
- current customer-safe workspace and released-review delivery semantics remain owned by Specs 258-260 and current code
- current operator-side `export_executive_pack` generation path remains owned by the existing review-pack export contract
- current signed review-pack download route remains the only download seam
- current governance-package availability states remain the baseline delivery-state model
New delta introduced by 263 only:
- add one explicit executive-first entrypoint inside the current review-derived pack
- add explicit bundle metadata clarifying which current files form the structured auditor appendix
- make only the minimal workspace/detail wording changes required to describe that new bundle contract
Everything broader stays inherited and out of scope unless it must change solely to explain the new bundle artifact.
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
- **Problem**: TenantPilot already has a review-derived export path (`export_executive_pack`), a ready or partial governance-package surface in the customer review workspace, current signed review-pack downloads, and shared compliance interpretation. What is still missing is one explicitly audience-ordered delivery artifact that an operator can hand to executives or auditors without manually explaining which parts of the current review pack are safe for whom.
- **Today's failure**: Published reviews can already produce or reuse a review-derived pack, but the exported artifact still reads like a product-internal review pack rather than an externally deliverable package. Operators still need ad-hoc guidance outside the product to explain the executive story, the evidence basis, and which files form the auditor appendix.
- **User-visible improvement**: An entitled actor can open one released review context and download one clearly packaged bundle whose default entrypoint is executive-readable while the structured appendix remains available for auditor follow-up inside the same delivery path.
- **Smallest enterprise-capable version**: Keep one released-review-bound `ReviewPack` artifact and the current signed download seam. Extend that existing bundle with one human-readable executive export entrypoint plus explicit delivery metadata that explains the included auditor appendix files. No new package domain, no new panel, no new scheduling, no new customer portal, and no second artifact family ship in v1.
- **Explicit non-goals**: No standalone `AuditorPack` model or table, no new report engine, no PDF renderer requirement, no campaign or recurring delivery workflow, no email delivery automation, no branding or white-label system, no multi-review or multi-tenant package batch, no new review publication workflow, and no raw provider-payload dump as the default human-readable export.
- **Permanent complexity imported**: One bounded delivery-bundle contract over the existing `ReviewPack` artifact, one export-ready summary template or equivalent presentation layer for the executive entrypoint, localized copy updates, and focused feature plus browser coverage. No new persisted workflow state is introduced.
- **Why now**: `docs/product/roadmap.md` and `docs/product/spec-candidates.md` both rank this as the highest-priority manual-promotion gap, and `docs/product/implementation-ledger.md` still marks auditor-ready executive delivery as the clearest remaining blocker between repo-real review truth and a repeatable sellable outcome.
- **Why not local**: A local copy tweak on the customer review workspace or a one-off download rename would not turn the current artifact into a credible external deliverable. A larger portal or reporting engine would overshoot the repo's current need.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New delivery vocabulary and export-bundle expectations over an existing artifact family. Defense: the slice stays fully derived from `TenantReview`, `ReviewPack`, `EvidenceSnapshot`, and shared interpretation truth; it does not add new persistence, new workflow state, or a second export subsystem.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve
## Spec Scope Fields *(mandatory)*
- **Scope**: canonical-view
- **Primary Routes**:
- existing workspace customer review registry at `/admin/reviews/workspace`
- existing tenant-scoped released review detail route under `TenantReviewResource`
- existing signed review-pack download route used by the current governance-package download path
- existing operator-side published review detail export action on `ViewTenantReview`
- **Data Ownership**:
- `TenantReview`, `ReviewPack`, `EvidenceSnapshot`, `StoredReport`, `Finding`, `FindingException`, `FindingExceptionDecision`, and `AuditLog` remain the only persisted truth used by this slice
- the delivered auditor-ready bundle remains one `ReviewPack` artifact tied to one released review; no new `AuditorPack`, `ExecutiveExport`, or delivery-campaign persistence family is introduced
- v1 should prefer extending bundle contents and current `metadata.json` / `summary` data over adding new database columns; if implementation cannot stay inside existing artifact and JSON surfaces, it must stop and split scope
- **RBAC**:
- workspace membership remains the first isolation boundary and stays `404` for non-members or out-of-scope tenant or review targets
- operator-side export initiation on published review detail continues to require the current review-manage capability path used by `export_executive_pack`
- read-only delivery download continues to reuse current released-review and review-pack visibility rules on the customer-safe detail route and signed download endpoint
- in-scope capability denials remain `403` only where the current review or review-pack contract already does so; this slice must not invent a new capability family for auditor or executive delivery
- the slice remains read-only for the customer-safe flow and does not introduce destructive actions
For canonical-view specs, the spec MUST define:
- **Default filter behavior when tenant-context is active**: `CustomerReviewWorkspace` keeps the current tenant-prefilter launch behavior. When launched from a tenant-context surface, the workspace prefilters to that tenant and opens the latest released review as the delivery context.
- **Explicit entitlement checks preventing cross-tenant leakage**: package availability, executive-export readiness, and review-pack access signals remain derived only for entitled tenants and released reviews. Inaccessible targets are omitted from aggregate lists and direct targeting resolves as not found.
## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*
- **Cross-cutting feature?**: yes
- **Interaction class(es)**: download actions, delivery-status messaging, management-summary disclosure, review-pack delivery framing, navigation entry points, and audit-backed export/download flows
- **Systems touched**: `CustomerReviewWorkspace`, `TenantReviewResource`, `ViewTenantReview`, `ReviewPackService`, `ReviewPackDownloadController`, `GenerateReviewPackJob`, `TenantReviewComposer`, `TenantReviewSectionFactory`, `ArtifactTruthPresenter`, localization files, and existing audit infrastructure
- **Existing pattern(s) to extend**: current `export_executive_pack` generation path, current `download_current_review_pack` customer-safe action, current governance-package availability states, current signed download route, and the existing released-review detail summary contract
- **Shared contract / presenter / builder / renderer to reuse**: `ReviewPackService`, `ArtifactTruthPresenter`, `TenantReviewComposer`, `TenantReviewSectionFactory`, `ReviewPackDownloadController`, `WorkspaceAuditLogger`, and the current review-pack action and resource seams
- **Why the existing shared path is sufficient or insufficient**: the existing path is already sufficient for review anchoring, entitlement enforcement, current package readiness states, and signed download handling. It is insufficient only because the bundle itself still lacks an explicit executive entrypoint and explicit explanation of which files form the auditor appendix.
- **Allowed deviation and why**: none. The slice must extend the current review-pack family and current released-review surfaces instead of introducing a second package domain or a new export framework.
- **Consistency impact**: `Governance package`, `Export executive pack`, delivery availability labels, evidence-basis wording, and non-certification disclosure must stay aligned across workspace rows, released review detail, exported bundle metadata, and signed download copy.
- **Review focus**: reviewers must block any second artifact family, any direct raw-report export that bypasses released-review truth, any portal-specific duplication of package status, or any scope growth into recurring delivery automation.
## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*
- **Touches OperationRun start/completion/link UX?**: yes
- **Shared OperationRun UX contract/layer reused**: the existing `ReviewPackGenerate` start and completion flow reused by `TenantReviewResource::executeExport()` remains the only run path
- **Delegated start/completion UX behaviors**: queued toast, already-available pack reuse, active-run dedupe messaging, existing terminal `OperationRunCompleted` delivery, and current signed-download follow-up stay on the shared review-pack export path
- **Local surface-owned behavior that remains**: the internal published review detail continues to decide when `export_executive_pack` is visible or primary; the customer-safe released-review detail continues to expose download only when a ready pack already exists
- **Queued DB-notification policy**: unchanged from the current review-pack export contract
- **Terminal notification path**: unchanged; the current `OperationRunCompleted` path remains authoritative
- **Exception required?**: none
## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*
N/A - no shared provider/platform seam is widened. Provider-specific report names and evidence details remain secondary appendix content and do not become the primary delivery language.
## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Customer Review Workspace page | yes | Native Filament page plus shared review-package primitives | delivery availability, package wording, navigation entry points | page, table, disclosure state | no | Existing row action remains `Open review`; delivery state stays informational on the workspace surface |
| Released review detail in customer-workspace mode | yes | Native Filament detail surface plus shared summary and artifact-truth primitives | delivery summary, package entrypoint, appendix disclosure | detail sections, disclosure state | no | Existing `Download governance package` remains the dominant safe action |
| Published review detail in operator mode | yes | Native Filament detail surface | export initiation, queued/reused package messaging | header actions, detail context | no | Existing `export_executive_pack` initiation path remains the only generation entrypoint |
## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*
| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | Primary Decision Surface | Operator decides which released review is ready for external delivery | released review state, package readiness, evidence-basis presence, and current next step | released review detail and appendix context after explicit open | Primary because it remains the calm workspace selection surface for customer-safe delivery | Keeps delivery anchored to the existing review-consumption workflow | Removes the need to inspect operator-only review-pack pages before the first decision |
| Released review detail in customer-workspace mode | Secondary Context | Operator or entitled reader confirms what the delivered bundle means and downloads it | executive-ready summary, evidence basis, package readiness, and the dominant download action | appendix semantics, deeper proof links, and review lineage after explicit drilldown | Secondary because the review has already been selected on the workspace surface | Keeps delivery centered on one released review | Avoids duplicate summaries across workspace and detail surfaces |
| Published review detail in operator mode | Secondary Context | Operator decides whether to generate or reuse the current export bundle | current review status, export readiness, and queued/reused package outcome | review-pack detail or run detail only after explicit follow-up | Secondary because this is the operator-only generation context, not the customer-safe delivery registry | Preserves the current operator workflow while clarifying the final bundle purpose | Prevents the operator from bouncing between review detail and review-pack resource just to know what will be delivered |
## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*
| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | operator-MSP, customer-admin, auditor-read-only, customer-read-only | delivery availability, released review state, executive-ready teaser, and evidence-basis presence | none beyond current review state and next-step copy | raw appendix files, provider payloads, fingerprints, and operator-only diagnostics stay off the list surface | `Open review` | raw/support detail stays off the workspace page by default | workspace rows say only whether delivery is ready; detail owns the actual delivery summary |
| Released review detail in customer-workspace mode | operator-MSP, customer-admin, auditor-read-only, customer-read-only | executive summary, evidence basis, top findings, accepted risks, governance decisions requiring awareness, and current delivery readiness | review lineage, interpretation freshness, and artifact availability descriptions in secondary sections only | raw provider payloads, fingerprints, internal reason ownership, and platform reason families stay hidden or gated | `Download governance package` | appendix file structure and operator-only proof links remain secondary | the delivery summary appears once in the governance-package block; later sections add evidence rather than restating the same outcome |
| Published review detail in operator mode | operator-MSP | export readiness, existing package state, and bundle purpose | run details and review-pack detail remain secondary | raw appendix files remain on the pack resource, not the primary review detail block | `Export executive pack` | customer-facing download copy stays off operator-only generation states until a pack is ready | generation context explains bundle purpose once and defers proof to the pack detail or download |
## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*
| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | List / Table / Read-only workspace report | Read-only registry report | Open the released review that is ready for delivery | full-row open via the existing `Open review` link | required | no peer download action on the list surface | none | `/admin/reviews/workspace` | existing tenant review detail route | workspace context, tenant prefilter, released review state, delivery availability | Customer review | whether a released review is delivery-ready | none |
| Released review detail in customer-workspace mode | Detail / Report / Management export | Read-only detail report | Download the current governance package | sectioned detail with one dominant safe header action | forbidden | appendix descriptions and proof links remain secondary in-body | none | `/admin/reviews/workspace` | existing tenant review detail route | workspace, tenant, release state, evidence basis, delivery availability | Governance package | what the exported bundle means and whether it is ready | none |
| Published review detail in operator mode | Detail / Report / Export initiation | Operator export surface | Start or reuse the review-derived export bundle | sectioned detail page with one primary export action | forbidden | review-pack detail or run links remain secondary | none | existing tenant review collection route | existing tenant review detail route | tenant context, review status, export readiness | Executive pack export | whether an export can start or be reused now | none |
## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*
| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | MSP operator or entitled reviewer | Decide which released review is ready for stakeholder delivery | Read-only workspace review overview | Which released review can I safely deliver right now? | released review state, delivery availability, evidence-basis presence, and next step | none beyond secondary review detail | release state, delivery readiness, evidence sufficiency | none | Open review | none |
| Released review detail in customer-workspace mode | MSP operator, customer admin, auditor with read access | Understand the delivery package and download it | Read-only detail report | What will this delivery bundle say, and is it ready? | executive summary, evidence basis, top findings, accepted risks, governance decisions, and delivery status | appendix structure, deeper evidence links, and lineage | delivery readiness, evidence sufficiency, released review status | none | Download governance package | none |
| Published review detail in operator mode | MSP operator | Generate or reuse the review-derived delivery bundle | Detail/export initiation surface | Can I prepare the current delivery bundle now, or is one already available? | review status, export readiness, and package reuse status | run detail and review-pack detail after explicit follow-up | review status, generation readiness, package availability | current `ReviewPackGenerate` run only | Export executive pack | none |
## Proportionality Review *(mandatory when structural complexity is introduced)*
- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no new persisted family; the existing `ReviewPack` artifact remains the delivery artifact
- **New abstraction?**: no new cross-domain abstraction by default; any implementation helper must stay local to current review-pack generation and delivery seams
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: the repo can already generate a review-derived export and show a customer-safe governance-package summary, but it still cannot hand over one clearly audience-ordered delivery artifact without manual explanation.
- **Existing structure is insufficient because**: the current bundle is machine-oriented and the current UI summary is in-app only. Neither alone gives a stakeholder-ready delivery contract.
- **Narrowest correct implementation**: extend the existing review-derived `ReviewPack` bundle and current signed download path with one human-readable executive entrypoint and explicit delivery metadata instead of creating a second package family.
- **Ownership cost**: maintain one additional exported entrypoint, one bundle metadata contract, a small amount of localized copy, and focused delivery tests.
- **Alternative intentionally rejected**: a standalone `AuditorPack` domain, a PDF/reporting engine, or recurring delivery automation were rejected as broader than current-release truth requires.
- **Release truth**: current-release sellability follow-through, not future-release delivery automation.
### Compatibility posture
This feature assumes a pre-production environment.
Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.
Canonical extension of the current `ReviewPack` bundle is preferred over adding a new delivery artifact family.
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: confidence, browser
- **Why this classification and these lanes are sufficient**: focused feature tests prove bundle contents, current export reuse, signed-download continuity, customer-safe disclosure, and entitlement boundaries on the current review and review-pack surfaces. One bounded browser smoke remains justified because the customer-facing detail copy and dominant action are user-visible delivery surfaces.
- **New or expanded test families**: extend existing `apps/platform/tests/Feature/TenantReview/`, `apps/platform/tests/Feature/Reviews/`, and `apps/platform/tests/Feature/ReviewPack/` families plus the existing `apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php`
- **Fixture / helper cost impact**: low to moderate; reuse current released-review, evidence-snapshot, review-pack, and entitlement fixtures. No provider-sync, no new queue family, and no heavy-governance lane are needed.
- **Heavy-family visibility / justification**: none
- **Special surface test profile**: shared-detail-family
- **Standard-native relief or required special coverage**: customer-workspace list behavior keeps standard native coverage; the released-review detail and bundle contract need explicit shared-detail coverage plus the existing browser smoke
- **Reviewer handoff**: reviewers must confirm that the exported bundle stays on the current `ReviewPack` family, the executive entrypoint is human-readable and customer-safe, the appendix stays clearly secondary, the workspace surface keeps `Open review` as the only dominant row action, and no second delivery domain or new run type appears
- **Budget / baseline / trend impact**: low feature-local increase only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**:
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php`
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Deliver One Stakeholder-Ready Bundle From A Released Review (Priority: P1)
As an MSP operator, I want a published review to produce one delivery-ready package that I can hand to an executive or auditor without separately explaining which files matter.
**Why this priority**: This is the commercial core of the slice. Without one externally deliverable bundle, the feature remains an internal review surface only.
**Independent Test**: Trigger `export_executive_pack` for a published review, finish the existing review-pack generation job, download the resulting pack through the current signed download path, and verify that the bundle contains both the current structured appendix files and one human-readable executive entrypoint.
**Acceptance Scenarios**:
1. **Given** a published review with an eligible evidence basis, **When** an entitled operator runs `export_executive_pack`, **Then** the existing `ReviewPackGenerate` flow starts or reuses the current pack and the finished bundle contains one executive entrypoint plus the existing structured appendix files.
2. **Given** a ready current export pack for a released review, **When** an entitled reader opens the customer-safe released-review detail and chooses `Download governance package`, **Then** the same current pack is downloaded through the existing signed route rather than a second artifact family.
3. **Given** the current export pack already exists and is still valid, **When** an operator repeats the export action, **Then** the system reuses the existing pack instead of creating a second delivery artifact.
---
### User Story 2 - Read The Executive Story First And The Auditor Appendix Second (Priority: P1)
As an entitled reviewer, I want the delivered bundle and released-review detail to make the executive summary obvious first while keeping the structured appendix clearly secondary, so the package is usable without exposing internal diagnostics by default.
**Why this priority**: The product already exposes governance-package meaning in-app. The missing value is making that meaning the default entrypoint of the delivered bundle.
**Independent Test**: Open a released review in customer-workspace mode, confirm the default-visible package block is customer-safe and executive-readable, then inspect the downloaded pack to verify the executive entrypoint and appendix roles are explicit.
**Acceptance Scenarios**:
1. **Given** a released review in customer-workspace mode, **When** the detail page renders, **Then** it shows executive-ready summary, evidence basis, delivery readiness, and `Download governance package` without exposing fingerprints, raw payloads, internal reason ownership, or platform reason families by default.
2. **Given** the delivered bundle is opened, **When** the recipient inspects the archive, **Then** the executive entrypoint is obvious and the structured appendix files remain present but secondary.
3. **Given** delivery readiness is `partial`, `unavailable`, `expired`, or `blocked`, **When** the workspace row or detail page renders, **Then** the product explains that state truthfully without pretending a bundle is ready.
---
### User Story 3 - Keep Delivery Tenant-Safe, Auditable, And Bounded (Priority: P2)
As a platform owner, I want the new delivery bundle to stay on the current entitlement, audit, and review-pack seams so the sellability improvement does not create a second uncontrolled export surface.
**Why this priority**: The feature only improves trust if it stays on the current authorization and audit boundaries.
**Independent Test**: Verify non-members receive `404`, in-scope actors use the existing download/export capability paths, and export/download activity remains visible through the existing audit and `OperationRun` seams.
**Acceptance Scenarios**:
1. **Given** a non-member or an out-of-scope tenant or review target, **When** they attempt to open the workspace, released-review detail, or signed download route, **Then** the response remains deny-as-not-found.
2. **Given** an entitled read-only reviewer with access to the released review and current export pack, **When** they download the governance package, **Then** the bundle is accessible without exposing operator-only diagnostics in the default human-readable export.
3. **Given** an entitled operator exports a published review, **When** the bundle is created or reused, **Then** the current audit and `ReviewPackGenerate` observability signals remain intact and no new delivery workflow state is introduced.
### Edge Cases
- What happens when a released review exists but no ready current export pack exists yet? The customer-safe detail stays truthful about unavailability and does not fabricate a download link.
- What happens when the current export pack is expired? The workspace and detail surfaces show `expired`, and the reader must rely on the operator-side generation flow to prepare a new bundle.
- What happens when the released review is customer-safe but some supporting evidence remains partial or stale? The executive entrypoint must say so explicitly, and the bundle stays `partial` rather than falsely `available`.
- What happens when a workspace commercial lifecycle state blocks new export starts but an existing ready pack remains downloadable? The operator-side export action stays blocked while the current allowed download semantics remain intact.
## Requirements *(mandatory)*
**Constitution alignment:** This feature reuses the current `ReviewPackGenerate` `OperationRun` path and existing signed review-pack download route. It must not introduce a second export run type, a second artifact family, or any new write path outside current review-pack generation. UI visibility remains non-authoritative; current `404`/`403` semantics stay enforced server-side.
**Constitution alignment (PROP-001 / PERSIST-001 / BLOAT-001):** This feature must stay on the existing `ReviewPack` persistence family. If implementation requires a new table, new standalone package model, or new delivery workflow state, the scope fails readiness and must split.
**Constitution alignment (XCUT-001):** Delivery status messaging, download actions, and review-pack export reuse must extend the current review, review-pack, and artifact-truth paths rather than introducing a new package presenter stack or a parallel portal UX language.
### Functional Requirements
- **FR-001**: The existing review-derived `ReviewPack` bundle for a published review MUST become the auditor-ready delivery bundle for this slice; no second artifact family may be introduced.
- **FR-002**: Operator-side export initiation for published reviews MUST continue to reuse the current `export_executive_pack` action and current `ReviewPackGenerate` `OperationRun` semantics.
- **FR-003**: Customer-safe read-only download for a released review MUST continue to reuse the current signed review-pack download route reached from `download_current_review_pack`.
- **FR-004**: The delivered bundle MUST preserve the current review-derived ZIP baseline entries `metadata.json`, `summary.json`, and `sections.json`, and MUST add exactly one human-readable executive entrypoint file suitable for executive-first consumption.
- **FR-005**: The delivered bundle metadata MUST explicitly identify the released review context, the current export review pack identity, interpretation version, evidence basis, generation timestamps, and which file is the executive entrypoint versus the preserved appendix entries `metadata.json`, `summary.json`, and `sections.json`.
- **FR-006**: The executive entrypoint MUST be derived from current released-review truth and shared interpretation truth, including executive summary, key findings, accepted risks, governance decisions requiring awareness, evidence basis, and explicit non-certification disclosure.
- **FR-007**: The executive entrypoint MUST NOT expose raw provider payloads, fingerprints, internal reason ownership, platform reason families, or operator-only diagnostics by default.
- **FR-008**: `CustomerReviewWorkspace` and released-review detail MUST keep package availability states truthful (`available`, `partial`, `unavailable`, `expired`, `blocked`) and must not imply delivery readiness when the current pack or evidence basis is not sufficient.
- **FR-009**: The workspace surface MUST keep `Open review` as the only dominant row action. It may not add a peer download action or a second delivery-specific row action.
- **FR-010**: The customer-safe released-review detail MUST keep one dominant safe download action and must present the auditor appendix as secondary explanatory context rather than a competing primary action.
- **FR-011**: Existing export/download audit events and metadata MUST be reused or minimally extended. A new audit family specific to auditor packs is out of scope.
- **FR-012**: This slice MUST NOT add new panel providers, new globally searchable resources, or new asset registration. Existing Filament v5 / Livewire v4 admin surfaces remain the only UI path.
## Scope Boundaries
### In Scope
- one auditor-ready delivery contract over the current review-derived `ReviewPack` bundle
- one human-readable executive entrypoint added to that current bundle while preserving `metadata.json`, `summary.json`, and `sections.json`
- delivery metadata clarifying executive entrypoint versus the preserved appendix roles
- only the truthful package-readiness and delivery wording changes on `CustomerReviewWorkspace` and released-review detail that are required to explain the new bundle contract
- reuse of current operator-side export initiation and current customer-safe signed download path
- focused localization, entitlement, audit, and browser-smoke follow-through for that delivery bundle
### Non-Goals
- a new `AuditorPack` model, table, or standalone delivery registry
- a new report engine, template system, or PDF-generation requirement
- recurring delivery schedules, campaigns, email delivery, or workflow automation
- white-label branding, customer-specific theming, or MSP profile variants
- a portal, new panel, or external identity plane
- multi-review or multi-tenant package batching
- raw provider-payload export as the default executive output
- any new destructive action or approval workflow
## Acceptance Criteria
- A published review can still generate or reuse one current export pack, and that pack now exposes a clear executive entrypoint plus a clearly secondary structured appendix.
- `CustomerReviewWorkspace` remains a calm selection surface with `Open review` as the only dominant row action, while released-review detail remains the package-owning context.
- Customer-safe delivery copy stays derived from existing review and interpretation truth and hides internal operator-only diagnostics by default.
- Existing `ReviewPackGenerate` and signed-download seams remain authoritative; no second artifact family or new run type is introduced.
## Success Criteria
- An operator no longer needs external instructions to explain which file in the current bundle is the executive-first entrypoint.
- An entitled customer-safe reader can download the same current bundle from released-review detail without seeing raw internal diagnostics by default.
- Review-pack delivery becomes closer to auditor-/executive-ready packaging without reopening the already prepared customer-safe workspace/detail delivery semantics from Specs 258-260.
## Assumptions
- The current `ReviewPack` ZIP artifact remains the acceptable v1 delivery container.
- A human-readable executive entrypoint can be produced inside the current export flow without introducing a new rendering subsystem.
- Existing review, review-pack, evidence, and interpretation truth are sufficient for v1 delivery framing; missing or stale basis is handled through truthful readiness states rather than by generating new data.
## Risks
- The slice could drift into a second export domain if implementation treats auditor delivery as a new artifact family instead of extending the current `ReviewPack` bundle.
- Scope pressure could try to add PDF tooling, branding, or recurring delivery automation even though those are explicitly deferred.
- The executive entrypoint could accidentally mirror internal diagnostics unless the delivery copy stays on the existing customer-safe interpretation path.
## Candidate Selection Rationale
- **Selected candidate**: Auditor Pack Delivery & Executive Export v1
- **Source locations**:
- `docs/product/spec-candidates.md`
- `docs/product/roadmap.md`
- `docs/product/implementation-ledger.md`
- **Why selected**: The active queue is intentionally empty, and this is the top-ranked manual-promotion backlog item with no existing spec package. The repo already contains the prerequisite review-pack export, customer review workspace, compliance interpretation, and governance-package delivery foundations.
- **Why close alternatives were deferred**:
- `Cross-Tenant Promotion Execution v1` already has Spec 043 for compare preview and preflight; the remaining gap is a later portfolio-action slice.
- `Governance Decision Pack & Approval Workflow v1` depends on the broader decision-operating lane and is ranked behind auditor-ready delivery in current roadmap order.
- `Customer-Facing Localization Adoption v1`, `Billing & Subscription Truth Layer v1`, `Stored Reports Surface v1`, `Workspace & Tenant Closure Lifecycle v1`, and `First Governed AI Runtime Consumer v1` remain valid manual promotions, but none is ranked above auditor-ready delivery in the current repo-backed backlog.

184
specs/263-auditor-pack-executive-export/tasks.md Normal file
View File

@ -0,0 +1,184 @@
---
description: "Task list for Auditor Pack Delivery & Executive Export v1"
---
# Tasks: Auditor Pack Delivery & Executive Export v1
**Input**: Design documents from `specs/263-auditor-pack-executive-export/`
**Prerequisites**: `specs/263-auditor-pack-executive-export/spec.md`, `specs/263-auditor-pack-executive-export/plan.md`, `specs/263-auditor-pack-executive-export/checklists/requirements.md`
**Tests**: REQUIRED (Pest). Keep proof bounded to existing `Feature` families around `TenantReview`, `Reviews`, and `ReviewPack`, plus the current `CustomerReviewWorkspace` browser smoke only.
**Operations**: Reuse the existing `ReviewPackGenerate` `OperationRun` path and signed review-pack download route. No new run type, no new queue family, and no new export artifact family are allowed.
**RBAC**: Workspace or tenant non-members remain `404`; current in-scope review/export/download denials remain `403` where the existing review-pack contract already uses them. No new capability family may be introduced.
**Shared Pattern Reuse**: Reuse `CustomerReviewWorkspace`, `TenantReviewResource`, `ViewTenantReview`, `ReviewPackService`, `GenerateReviewPackJob`, `ReviewPackDownloadController`, `TenantReviewComposer`, `TenantReviewSectionFactory`, `ArtifactTruthPresenter`, current localization files, and current audit IDs. Do not create a new `AuditorPack` or reporting subsystem.
**Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`. No new panel, no new globally searchable resource, and no new asset strategy are allowed.
**Organization**: Tasks are grouped by user story so the bundle contract, the delivery disclosure, and the entitlement/audit boundaries stay independently implementable and testable. This package is a delta follow-up over Specs 258-260 and current code; broader customer-safe workspace/detail behavior is inherited unless a task explicitly changes it to explain the new bundle contract.
## Test Governance Checklist
- [x] Lane assignment stays `confidence` plus the existing bounded `browser` smoke and remains the narrowest sufficient proof.
- [x] New or changed tests stay in the existing `apps/platform/tests/Feature/TenantReview/`, `apps/platform/tests/Feature/Reviews/`, and `apps/platform/tests/Feature/ReviewPack/` families plus `apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php`.
- [x] Shared helpers, released-review fixtures, review-pack fixtures, and evidence fixtures stay cheap by default.
- [x] Planned validation commands cover bundle contents, disclosure, download continuity, and entitlement behavior without widening into unrelated lanes.
- [x] The declared surface test profile remains `shared-detail-family`.
- [x] Any drift toward a second artifact family, a PDF engine, or recurring delivery automation is handled as `reject-or-split` or `follow-up-spec`, not hidden inside this feature.
## Phase 1: Setup (Shared Context)
**Purpose**: Confirm the current review-pack bundle, delivery wording, and entitlement seams before any implementation change.
- [x] T001 Review `specs/263-auditor-pack-executive-export/spec.md`, `specs/263-auditor-pack-executive-export/plan.md`, `specs/263-auditor-pack-executive-export/checklists/requirements.md`, `specs/109-review-pack-export/spec.md`, `specs/153-evidence-domain-foundation/spec.md`, `specs/155-tenant-review-layer/spec.md`, `specs/258-customer-review-productization/spec.md`, `specs/259-compliance-evidence-mapping/spec.md`, and `specs/260-governance-service-packaging/spec.md` together so the slice stays on the current bundle and delivery foundations.
- [x] T002 [P] Confirm the current operator export initiation seam in `apps/platform/app/Filament/Resources/TenantReviewResource.php` and `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`.
- [x] T003 [P] Confirm the current bundle generation and download seams in `apps/platform/app/Services/ReviewPackService.php`, `apps/platform/app/Jobs/GenerateReviewPackJob.php`, and `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`.
- [x] T004 [P] Confirm the current customer-safe delivery surfaces in `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`, `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`, and `apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php`.
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Lock the bounded delivery contract before surface-level changes begin.
**Critical**: No user-story work should begin until this phase is complete.
- [x] T005 [P] Extend `apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php` and `apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php` to require one human-readable executive entrypoint plus explicit delivery metadata inside the current review-derived pack while preserving the current ZIP baseline entries `metadata.json`, `summary.json`, and `sections.json`.
- [x] T006 [P] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` to prove the feature still reuses the current `ReviewPackGenerate` path and the current signed download route rather than introducing a second artifact or download flow. Existing tests already covered this seam; the validation lane confirmed them unchanged.
- [x] T007 [P] Extend `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php`, `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php`, and `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php` to lock delivery-readiness wording, one dominant action per surface, and the absence of raw/internal detail in the customer-safe default path. New wording/default-disclosure assertions landed in `CustomerReviewWorkspacePageTest` and `TenantReviewExplanationSurfaceTest`; existing pack-access and UI-contract tests remained the action-hierarchy guard.
- [x] T008 Implement the bundle-contract change in `apps/platform/app/Services/ReviewPackService.php` and `apps/platform/app/Jobs/GenerateReviewPackJob.php`, keeping the current `ReviewPack` family and the ZIP baseline entries `metadata.json`, `summary.json`, and `sections.json` intact while adding one executive entrypoint and explicit delivery metadata.
- [x] T009 [P] Add or update the executive-entrypoint presentation layer under `apps/platform/resources/views/review-packs/` only if the current bundle generation cannot render the executive export cleanly from existing summary truth. Not needed: the current job renders a bounded Markdown entrypoint directly from existing review summary truth.
**Checkpoint**: The current bundle, current run path, and current customer-safe surfaces are all locked to the new delivery contract before broader wording changes begin.
---
## Phase 3: User Story 1 - Deliver One Stakeholder-Ready Bundle From A Released Review (Priority: P1)
**Goal**: A published review can generate or reuse one current export bundle that is ready to hand over externally.
**Independent Test**: Export a published review, complete the current generation job, and download the resulting current pack to verify that one executive entrypoint and the existing structured appendix coexist in the same bundle.
### Tests for User Story 1
- [x] T010 [P] [US1] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php` to assert that the current pack remains review-anchored and now exposes the executive entrypoint plus delivery metadata.
- [x] T011 [P] [US1] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php` to assert that export initiation still uses the existing `ReviewPackGenerate` path, dedupes correctly, and stays on the current operator-side action. Existing coverage already proved the unchanged run path and dedupe behavior.
- [x] T012 [P] [US1] Extend `apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` to verify the new bundle contents and signed-download continuity. New bundle assertions landed in `TenantReviewDerivedReviewPackTest`; existing download continuity coverage remained unchanged and passed.
### Implementation for User Story 1
- [x] T013 [US1] Update `apps/platform/app/Services/ReviewPackService.php` and `apps/platform/app/Jobs/GenerateReviewPackJob.php` so review-derived packs produce one executive entrypoint and explicit delivery metadata while preserving current appendix files and current `current_export_review_pack_id` behavior.
- [x] T014 [US1] Update `apps/platform/app/Filament/Resources/TenantReviewResource.php` and `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php` so published-review export continues to generate or reuse the current pack without introducing a second delivery action or a second artifact family. No code update was needed; repo truth already used the current action and run seam, and tests confirmed it.
- [x] T015 [US1] Update `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php` only as needed to carry the same current pack through the signed download path with delivery metadata intact. No controller update was needed; signed download continuity stayed on the existing pack file and passed validation.
**Checkpoint**: One released review can produce and deliver one stakeholder-ready current bundle without any second export system.
---
## Phase 4: User Story 2 - Show The Executive Story First And The Appendix Second (Priority: P1)
**Goal**: The in-app delivery surfaces and the exported bundle both make the executive narrative the default entrypoint while keeping appendix detail secondary.
**Independent Test**: Open a released review in customer-workspace mode and confirm that the default visible package block and the downloaded current bundle both present executive-first delivery framing without raw internal diagnostics.
### Tests for User Story 2
- [x] T016 [P] [US2] Extend `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php` and `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php` to cover only the delivery-readiness wording changes required by the new bundle contract, evidence-basis messaging, and the absence of peer download actions on the workspace list. New wording assertions landed in `CustomerReviewWorkspacePageTest`; existing pack-access tests remained the peer-action guard.
- [x] T017 [P] [US2] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php` and `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php` to cover executive-first default content, appendix-secondary wording, and hidden raw/internal detail by default. New disclosure assertions landed in `TenantReviewExplanationSurfaceTest`; existing UI-contract tests remained the one-action guard.
- [x] T018 [P] [US2] Extend `apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` to prove the released-review path still centers the customer-safe package summary and dominant download action after the wording changes.
### Implementation for User Story 2
- [x] T019 [US2] Update `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` and `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` only where needed so workspace rows keep delivery readiness informational and `Open review` remains the only dominant row action. No PHP/Blade structure change was needed on the workspace list; localized intro copy now frames executive-ready package status while existing row action tests guard `Open review`.
- [x] T020 [US2] Update `apps/platform/app/Services/TenantReviews/TenantReviewComposer.php`, `apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php`, and `apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php` only where needed so the released-review detail block explains executive-first delivery, evidence basis, and appendix-secondary meaning without reopening broader customer-safe package semantics already owned by Spec 260. Composer/factory already exposed the required truth; the detail entry now presents entrypoint and appendix wording.
- [x] T021 [US2] Update `apps/platform/lang/en/localization.php` and `apps/platform/lang/de/localization.php` so delivery-readiness, executive-entrypoint, appendix, and non-certification copy stay consistent across workspace, detail, and download paths.
**Checkpoint**: The delivery story is obvious and customer-safe before the bundle is opened, and the workspace/detail surfaces stay calm and non-duplicative.
---
## Phase 5: User Story 3 - Keep Delivery Tenant-Safe, Auditable, And Bounded (Priority: P2)
**Goal**: The sellability improvement remains on the current entitlement, audit, and observability seams.
**Independent Test**: Verify that export and download stay tenant-safe, audit-visible, and free of any second package domain or new delivery workflow state.
### Tests for User Story 3
- [x] T022 [P] [US3] Extend `apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` to confirm non-members remain `404` and current in-scope download permissions remain authoritative. Existing authorization/download coverage remained valid and passed.
- [x] T023 [P] [US3] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php` and `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php` to confirm operator export generation remains the only current initiation path and no competing customer-surface generation action appears. Existing UX-contract coverage remained valid and passed.
- [x] T024 [P] [US3] Extend `apps/platform/tests/Feature/TenantReview/TenantReviewAuditLogTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` to confirm current audit metadata still records export and download activity without a new audit family. Existing audit/download coverage remained valid and passed.
### Implementation for User Story 3
- [x] T025 [US3] Reuse or minimally extend current audit metadata in `apps/platform/app/Services/Audit/WorkspaceAuditLogger.php` and `apps/platform/app/Support/Audit/AuditActionId.php` only if the current export/download events need explicit delivery-role metadata. No audit-family or action-id change was needed; existing metadata remains authoritative.
- [x] T026 [US3] Review `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` and current delivery availability mapping so `available`, `partial`, `unavailable`, `expired`, and `blocked` remain truthful after the new bundle entrypoint is added.
- [x] T027 [US3] Confirm the implementation does not add a new panel, new global search entry, new asset registration, second artifact family, or recurring delivery workflow. If any of those become necessary, stop and split the scope.
**Checkpoint**: Delivery remains attributable, tenant-safe, and bounded to the current export/download seams.
---
## Phase 6: Polish & Cross-Cutting Validation
**Purpose**: Validate the bounded slice and stop without widening scope.
- [x] T028 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php` - passed, 41 tests / 326 assertions.
- [x] T029 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` - passed, 1 test / 42 assertions.
- [x] T030 [P] Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - passed.
- [x] T031 [P] Review touched code to confirm Filament stays on Livewire v4, provider registration remains unchanged in `apps/platform/bootstrap/providers.php`, no globally searchable resource contract changes, and no new asset strategy appears.
- [x] T032 [P] Review touched code to confirm the bundle stays on the current `ReviewPack` family and the current `ReviewPackGenerate` run path.
- [x] T033 [P] Record the final guardrail, smoke, and scope-boundary outcomes in the active feature close-out without reopening branding, PDF, scheduling, or second-artifact follow-up work. Outcome: no new panel, provider, global search, asset strategy, run type, artifact family, PDF/reporting engine, branding, scheduling, or second delivery workflow; browser smoke passed on the existing Customer Review Workspace handoff.
---
## Dependencies & Execution Order
### Phase Dependencies
- **Phase 1 (Setup)**: no dependencies; start immediately.
- **Phase 2 (Foundational)**: depends on Phase 1 and blocks all user stories.
- **Phase 3 (US1)**: depends on Phase 2 and establishes the current bundle contract.
- **Phase 4 (US2)**: depends on Phase 2 and should land with US1 so the new bundle contract and the in-app delivery language stay aligned.
- **Phase 5 (US3)**: depends on Phase 2 and hardens audit and entitlement behavior after the bundle contract exists.
- **Phase 6 (Polish)**: depends on all desired user stories being complete.
### User Story Dependencies
- **US1 (P1)**: independently testable after Phase 2 and delivers the core stakeholder-ready bundle.
- **US2 (P1)**: independently testable after Phase 2 and should ship with US1 so the delivered bundle and in-app delivery language do not drift apart.
- **US3 (P2)**: independently testable after Phase 2 and hardens the bounded delivery path.
### Within Each User Story
- Write the listed Pest coverage first and make it fail for the intended gap.
- Keep implementation inside the current review-pack, review, download, localization, and audit seams named above.
- Re-run the narrowest relevant validation command after each story checkpoint before moving on.
---
## Implementation Strategy
### Suggested MVP Scope
- MVP = **US1 + US2 together**. The feature is only useful when the current bundle becomes stakeholder-ready and the current in-app delivery surfaces explain it correctly.
### Incremental Delivery
1. Complete Phase 1 and Phase 2.
2. Deliver US1 and US2 together on the current `ReviewPack` family.
3. Add US3 to confirm audit and entitlement continuity.
4. Finish with the focused validation and drift-review tasks in Phase 6.
### Team Strategy
1. Settle the bundle contract first.
2. Parallelize failing tests within each story before runtime edits.
3. Serialize merges around `ViewTenantReview`, `CustomerReviewWorkspace`, and shared localization keys so delivery wording stays coherent.
---
## Deferred Follow-Ups / Non-Goals
- PDF tooling or richer print/export rendering
- recurring delivery or scheduled distribution
- branded or customer-specific delivery variants
- multi-review or multi-tenant delivery batches
- a second artifact family or a standalone auditor-portal surface