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.