TenantAtlas/specs/248-private-ai-policy-foundation/quickstart.md

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.