76 lines
6.4 KiB
Markdown
76 lines
6.4 KiB
Markdown
# 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. |