# Quickstart — Private AI Execution & Policy Foundation ## Preconditions - Docker is running. - `apps/platform` dependencies are installed. - This slice stays inside the existing Laravel / Filament runtime and does not introduce a second AI service. ## Intended Implementation Order 1. Add `ai.policy_mode` to the existing settings registry and workspace settings page. 2. Add `ai.execution` to the existing operational-control catalog and controls page. 3. Add a narrow `app/Support/Ai/` namespace containing the use-case catalog, request/decision value objects, and the governed decision boundary only. 4. Reuse the existing audit pipeline for workspace policy mutation and AI decision logging. 5. Add the no-direct-provider architecture guard and the focused unit/feature tests. ## Targeted Validation Commands (after implementation) - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Ai/AiUseCaseCatalogTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Ai/AiDecisionAuditMetadataTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Ai/GovernedAiExecutionBoundaryTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceAiPolicySettingsTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceSettingsViewOnlyTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceSettingsNonMemberNotFoundTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceSettingsAuditTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/OpsControls/AiExecutionOperationalControlTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/OpsControls/OperationalControlManagementTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OperationalControls/OperationalControlAuthorizationSemanticsTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoDirectAiProviderBypassTest.php` - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` ## Manual Smoke (after implementation) 1. Sign in to `/admin`, select a workspace, and open `/admin/settings/workspace`. 2. As a workspace manager, switch the AI policy between `Disabled` and `Private only` and confirm the page shows the allowed use cases, provider classes, and blocked data classes in plain language. 3. Sign in to `/system` as a platform operator with `platform.access_system_panel` and `platform.ops.controls.manage`, then open `/system/ops/controls`. 4. Pause `AI execution`, confirm the global reason/expiry flow, and verify that the control state is visible before resuming it. 5. Exercise the governed AI boundary through focused tests or a narrow internal stub caller only; no customer-facing AI route or UI is part of v1. ## Implementation Outcome (2026-04-27) - `TEST-GOV-001`: PASS. - Focused validation stayed in Pest `Unit` plus `Feature` lanes with one architecture guard only. - Executed validation summary: - AI boundary unit lane: 8 tests, 83 assertions passed. - AI execution controls feature lane: 1 test, 34 assertions passed. - Operational controls regression lane: 11 tests, 167 assertions passed. - Workspace settings lane: 20 tests, 267 assertions passed. - Platform authorization semantics lane: 6 tests, 26 assertions passed. - No-direct-provider guard lane: 1 test, 1 assertion passed. - Approved source-input lane: 2 tests, 30 assertions passed. - Adjacent product-knowledge/support-diagnostics regression lane: 14 tests, 107 assertions passed. - Final targeted feature validation rollup: 42 tests, 530 assertions passed. - Pint: `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` passed. - Catalog lock and tenant-context declaration: - `product_knowledge.answer_draft`: `tenant_context_permitted = false` - `support_diagnostics.summary_draft`: `tenant_context_permitted = true` - Browser smoke completed: 1. `/admin/settings/workspace`: saved `Workspace AI policy = Private only` and confirmed the effective summary updated on the real page. 2. `/system/ops/controls`: paused and resumed `AI execution` through the confirmation flow and confirmed both state changes plus success notifications. - Environment note: the integrated browser's `localhost` system-panel session became stale during smoke work, so the system-panel step completed on `127.0.0.1` with a fresh host-scoped session. Route health and product behavior were otherwise unchanged. - Deferred to follow-up specs only: - external-public or broader provider execution - result persistence, caching, or prompt/output history - budgeting, credits, or cost controls - queued AI work or `OperationRun` semantics - customer-facing AI surfaces or approval workflows ## Notes - Filament v5 already runs on Livewire v4 in this repo. - Panel providers remain registered through `bootstrap/providers.php`; this slice does not add or move providers. - No new globally searchable AI resource is part of v1, so global search behavior stays unchanged. - `Pause AI execution` and `Resume AI execution` are the only destructive-like actions in scope and must stay confirmation-protected. - No new registered assets are expected. If implementation later registers a Filament asset anyway, deployment still needs the normal `cd apps/platform && php artisan filament:assets` step.