TenantAtlas/specs/197-shared-detail-contract/quickstart.md

Quickstart: Shared Detail Micro-UI Contract

Goal

Validate that the same verification and normalized detail concepts now render through family-owned contracts across their covered hosts, without adding persistence, Graph calls, or a generic UI framework.

Prerequisites

1. Start Sail.
2. Ensure you have a tenant with at least one completed verification run and one onboarding session that can resume on the verify step.
3. Ensure you have policy and policy-version data that exercises both settings-catalog and standard-settings rendering.
4. Ensure you have at least one drift finding with an available normalized diff and one drift finding with missing version references.
5. Ensure the current user can open the covered hosts in tenant and workspace-safe contexts.

Implementation Validation Order

1. Run verification-family regression coverage

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantVerificationReportWidgetTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
./vendor/bin/sail artisan test --compact tests/Feature/MonitoringOperationsTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Spec085/DenyAsNotFoundSemanticsTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAccessTest.php
./vendor/bin/sail artisan test --compact --filter=SharedVerificationReportFamilyContract

Expected outcome:

• Operation detail, onboarding, and tenant widget all expose the same verification-family core.
• Verification rendering stays DB-only and does not dispatch outbound work.
• Onboarding-only assist and acknowledge actions remain available as bounded host variations.
• Workspace-context and tenant-context verification hosts keep deny-as-not-found and capability-safe behavior after the shared viewer refactor.

2. Run normalized detail-family regression coverage

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyVersionSettingsTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Filament/SettingsCatalogPolicyNormalizedDiffTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Filament/GroupPolicyConfigurationNormalizedDiffTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Drift/DriftFindingDiffUnavailableTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php
./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingRbacTest.php
./vendor/bin/sail artisan test --compact --filter=NormalizedDetailFamilyContract

Expected outcome:

• Policy and policy-version settings use the same family-owned wrapper with explicit subtype behavior.
• Policy-version diff and finding diff use the same normalized diff family semantics for available, unavailable, and zero-diff cases.
• No host still relies on a sibling top-level settings view or a host-only diff unavailable message for the same concept.
• Tenant-scoped policy, policy-version, and finding detail hosts preserve existing deny-as-not-found and capability semantics.

3. Run the fork guard and targeted parity checks

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
./vendor/bin/sail artisan test --compact tests/Feature/Guards/SharedDetailFamilyContractGuardTest.php
./vendor/bin/sail artisan test --compact --filter=FamilyContract

Expected outcome:

• Guard coverage blocks reintroduction of direct host forks.
• Parity tests prove the same family zones and the same unavailable-state semantics across hosts.

4. Format touched files

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
./vendor/bin/sail bin pint --dirty --format agent

Expected outcome:

• All touched PHP files conform to the repo’s Pint rules.

Manual Smoke Check

1. Open the operation run detail that shows a verification report and confirm you can immediately identify summary, issues, passed, and technical details zones.
2. Open the onboarding wizard verify step for the same or equivalent verification payload and confirm the same core verification surface appears, with onboarding-only assist or acknowledge behavior layered on top instead of a different tab model.
3. Open the tenant verification widget and confirm the completed-state core matches the other verification hosts while no-run and in-progress framing stays widget-specific.
4. Open a policy-version detail view and a policy detail view that both show normalized settings and confirm warnings, empty-state behavior, and subtype structure feel like one family.
5. Open a policy-version detail view that shows normalized diff and confirm summary, grouped sections, and availability messaging match the same shared diff-family contract used elsewhere.
6. Open a drift finding with missing referenced versions and confirm the diff area uses a family-consistent unavailable state.
7. Open a drift finding with an available normalized diff and confirm the grouped diff surface feels like the same family as policy-version diff, not a new host-specific micro-app.

Release Acceptance Recording

1. Update specs/197-shared-detail-contract/migration-note.md with the migrated hosts actually touched by the implementation.
2. Record the consciously allowed remaining variations that still differ by host.
3. Capture reviewer, review date, and pass or fail notes for SC-197-003 and SC-197-004 in the migration note.
4. Record any shell, monitoring-state, or other intentionally out-of-scope follow-ups in the migration note instead of expanding this feature silently.

Non-Goals For This Slice

• No database migration.
• No new public API.
• No new Graph call path or OperationRun lifecycle change.
• No new Filament asset registration or filament:assets deployment change.
• No shell, workspace context bar, or monitoring page-state refactor.