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

# Feature Specification: Private AI Execution & Policy Foundation

**Feature Branch**: `248-private-ai-policy-foundation`  
**Created**: 2026-04-27  
**Status**: Implemented  
**Input**: User description: "Promote the roadmap-fit candidate Private AI Execution & Policy Foundation as a narrow, implementation-ready slice that introduces a governed central AI execution boundary for approved use cases, workspace policy modes, provider-class gating, and audit-ready decision metadata, while stopping before customer-facing AI features, direct external provider calls with tenant data, or a broad multi-provider marketplace."

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: TenantPilot now has roadmap pressure to add AI-assisted support and operator workflows, but the repo still has no app-level AI execution seam, no workspace-owned AI policy truth, and no central place to classify which AI inputs are ever allowed to leave a bounded trust boundary.
- **Today's failure**: If AI work starts feature-by-feature, it will likely appear as local provider calls, local prompt assembly, and local allow/block logic that bypass workspace policy, provider trust boundaries, operational controls, and audit-ready decision metadata. That would create privacy drift, provider coupling, and rework before the first real customer-facing AI workflow even lands.
- **User-visible improvement**: Workspace operators can set an explicit workspace AI posture on the existing workspace settings surface, platform operators can pause all AI execution through the existing operational-controls path, and future AI-assisted internal workflows get one auditable allow-or-block decision before any model execution begins.
- **Smallest enterprise-capable version**: Add one concrete governed AI execution boundary, one code-owned approved use-case catalog locked to two internal-only future consumers (`product_knowledge.answer_draft` and `support_diagnostics.summary_draft`), one workspace AI policy section with the modes `disabled` and `private_only`, one bounded provider-class and data-classification contract, one reused operational-control key for emergency stop, and one audit metadata shape on the existing audit infrastructure.
- **Explicit non-goals**: No customer-facing AI surface, no chatbot, no customer communication drafting, no autonomous remediation, no human-approval workflow, no broad provider marketplace, no provider credential-management UI, no usage budgeting, no result cache/store, no prompt/template CMS, no queueing/OperationRun layer for AI, and no external public-provider execution with tenant or customer data.
- **Permanent complexity imported**: One workspace-owned AI policy truth inside the existing settings stack, one bounded AI use-case catalog, one bounded provider-class catalog, one bounded AI data-classification family, one concrete execution-decision service, one operational-control catalog entry, new audit action IDs and metadata fields, and focused unit plus feature guard coverage.
- **Why now**: This is the next roadmap-fit foundation after Specs 242-247 and the provider-vocabulary hardening lane. It directly reduces the current risk that private AI arrives through ungoverned local feature calls before the product has safe workspace isolation, provider gating, and audit semantics.
- **Why not local**: A local AI helper per surface would duplicate policy checks, duplicate data-classification choices, and teach parallel provider semantics across product knowledge, diagnostics, and later customer workflows. The trust boundary needs to exist once before those consumers start shipping.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New axes, new meta-infrastructure, and foundation-sounding scope. Defense: the slice is tightly limited to two approved use cases, two policy modes, one existing admin settings surface, one existing system control surface, no new table, no result persistence, and no customer-visible AI workflow.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace, platform
- **Primary Routes**:
  - `/admin/settings/workspace` on the existing workspace settings page for workspace-owned AI policy
  - `/system/ops/controls` on the existing system operational-controls page for a platform emergency stop of AI execution
  - No new tenant/admin AI output route, customer-facing AI page, or system AI console is introduced in v1
- **Data Ownership**:
  - Workspace AI policy truth is workspace-owned and stored through the existing workspace settings mechanism rather than a new AI table
  - Approved AI use cases, provider classes, and AI data classifications remain code-owned repository truth
  - AI execution decisions and policy mutations are recorded on the existing audit infrastructure; no AI result ledger, cache store, or prompt history table is introduced in this slice
  - Tenant-scoped AI requests may carry workspace and tenant identifiers for authorization and audit context, but tenant/customer content remains derived input only and is not persisted as a new AI-owned record family
- **RBAC**:
  - Workspace AI policy visibility and mutation stay on the existing workspace settings authorization path and reuse the current workspace settings capabilities
  - Platform pause/resume of AI execution stays on the existing system panel and requires `PlatformCapabilities::ACCESS_SYSTEM_PANEL` plus `PlatformCapabilities::OPS_CONTROLS_MANAGE`
  - The governed AI execution boundary accepts requests only after the caller has already resolved workspace and optional tenant entitlement on the host surface; it does not create a new cross-plane shortcut from `/system` into tenant data
  - This slice introduces no new customer-facing or operator-facing `run AI` capability string because it intentionally stops before any new AI action surface is exposed

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: N/A - this slice does not add a canonical cross-tenant AI list or detail route
- **Explicit entitlement checks preventing cross-tenant leakage**: AI decision evaluation never runs before the host surface has already resolved workspace and tenant entitlement. A non-member or wrong-scope actor receives the existing 404 semantics before any AI policy or data-classification detail is revealed.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: workspace settings, operational safety controls, audit logging, future support-diagnostic and product-knowledge source reuse
- **Systems touched**: existing workspace settings persistence and audit flow, `App\Support\OperationalControls\OperationalControlEvaluator`, `App\Filament\System\Pages\Ops\Controls`, `App\Support\ProductKnowledge\ContextualHelpResolver`, existing support-diagnostic bundle builders, and `App\Support\Audit\AuditActionId`
- **Existing pattern(s) to extend**: workspace settings update/reset audit path, operational-controls evaluation path, platform system-panel capability enforcement, and stable audit action ID conventions
- **Shared contract / presenter / builder / renderer to reuse**: `SettingsResolver`, `SettingsWriter`, `WorkspaceAuditLogger`, `AuditRecorder`, `OperationalControlEvaluator`, `AuditActionId`, `ContextualHelpResolver`, and the existing support-diagnostic summary pipeline
- **Why the existing shared path is sufficient or insufficient**: the existing settings, ops-controls, and audit paths are already sufficient for policy storage, emergency stop, and audit ownership. They are insufficient for AI itself because no central execution boundary or AI-specific allow/block decision contract exists yet.
- **Allowed deviation and why**: none. The first slice must not introduce page-local AI policy checks, page-local provider labels, or page-local audit payloads.
- **Consistency impact**: the same vocabulary for `AI policy mode`, `provider class`, `data classification`, `approved use case`, `blocked reason`, and `private-only` must appear consistently across workspace settings, system controls, audit prose, and all future AI decision callers.
- **Review focus**: reviewers must block any direct provider call, raw feature-level AI helper, or local data-classification rule that bypasses the central AI execution boundary, the workspace AI policy, or the reused operational-control decision.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: no
- **Shared OperationRun UX contract/layer reused**: N/A - this slice intentionally stops before queueing, background AI work, or customer/operator-facing AI runs
- **Delegated start/completion UX behaviors**: N/A
- **Local surface-owned behavior that remains**: N/A
- **Queued DB-notification policy**: N/A
- **Terminal notification path**: N/A
- **Exception required?**: none

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: platform-core
- **Seams affected**: AI use-case keys, workspace AI policy vocabulary, provider-class gating, data-classification gating, and the governed execution decision contract
- **Neutral platform terms preserved or introduced**: `AI use case`, `provider class`, `workspace AI policy`, `data classification`, `execution decision`, `source family`, and `private-only`
- **Provider-specific semantics retained and why**: none in v1. The slice intentionally classifies trust boundaries by provider class rather than naming vendors, endpoints, SDKs, or model marketplaces.
- **Why this does not deepen provider coupling accidentally**: the spec keeps provider truth at the class level (`local_private` versus `external_public`) and forbids feature code from depending on vendor-specific semantics or credentials in this foundation slice.
- **Follow-up path**: later provider expansion belongs in follow-up specs, primarily `AI Usage Budgeting, Context & Result Governance` and then `AI-Assisted Customer Operations`, rather than inside this foundation slice

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Workspace settings AI policy section | yes | Native Filament + existing singleton settings page | settings, status messaging, helper text | page, settings section, resolved policy summary | no | Extends the existing workspace settings page instead of creating a separate AI admin surface |
| System ops controls AI execution control card | yes | Native Filament + existing operational-controls page | operational safety controls, audit-backed state messaging | page, card/action state, confirmation modal | no | Reuses the current control-center pattern for a single new AI execution kill switch |
| Customer-facing or tenant-facing AI output surfaces | no | N/A | none | none | no | `N/A - explicitly out of scope for v1` |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Workspace settings AI policy section | Primary Decision Surface | Workspace owner or manager decides whether the workspace allows no AI use at all or only private-only AI for approved internal use cases | current policy mode, plain-language effect, approved use cases, allowed provider classes, and blocked data classes | audit attribution, source-family notes, and future-consumer explanation | Primary because this is the one workspace-owned product decision that changes later AI allow/block behavior | Follows configuration-first governance instead of hidden feature flags | Replaces founder memory or code comments with one explicit workspace truth |
| System ops controls AI execution control card | Primary Decision Surface | Platform operator decides whether all new AI execution must be paused during an incident or rollout concern | global control state, reason, expiry, and effect on new AI starts | audit history and affected-use-case summary | Primary because it is the runtime safety stop for the whole AI boundary, not a secondary diagnostic | Follows incident and rollout operations workflow | Removes the need for deploy-time or environment-level emergency stop behavior |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Workspace settings AI policy section | operator-MSP | policy mode, approved use cases, allowed provider classes, blocked data classes, and plain-language effect | last changed attribution and policy-source notes | none | `Save` | vendor-specific credentials, raw prompt examples, raw diagnostic inputs, and future budgeting fields stay out of scope | The same policy vocabulary is reused by the execution boundary and audit prose instead of being restated differently on future surfaces |
| System ops controls AI execution control card | support-platform, operator-platform | control state, reason, expiry, and whether new AI execution is paused | audit history and affected-use-case count | none | `Pause AI execution` or `Resume AI execution` | no prompt content, no provider payload preview, and no workspace content samples appear on the control surface | The control surface owns only runtime stop/start truth; workspace policy detail stays on workspace settings |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Workspace settings AI policy section | Config / Settings / Singleton | Workspace configuration section | Save or reset the workspace AI policy | In-page settings section on the existing singleton route | forbidden | Helper text and policy explanation stay inside the section | none | `/admin/settings/workspace` | `/admin/settings/workspace` | Active workspace context | Workspace AI policy | Whether AI is disabled or private-only, and what that means | existing singleton-settings exception remains valid |
| System ops controls AI execution control card | Utility / System | Operational safety control center | Pause or resume AI execution | Same-page card actions and confirmation modal | forbidden | Audit/history detail remains secondary inside the page | pause/resume stays on the card with confirmation | `/system/ops/controls` | `/system/ops/controls` | Platform-global control scope | AI execution control | Whether new AI execution is allowed right now and why | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Workspace settings AI policy section | Workspace owner or manager | Decide whether the workspace allows private-only AI for approved internal use cases | Singleton settings page | What AI posture applies to this workspace right now? | policy mode, approved use cases, allowed provider classes, blocked data classes, and plain-language effect | last changed attribution and source-family notes | AI policy mode, provider trust boundary, allowed data scope | TenantPilot only | Save, Reset policy | none |
| System ops controls AI execution control card | Platform operator | Decide whether all new AI execution must be paused or resumed | System control center | Should any new AI execution proceed right now? | global control state, reason, expiry, and effect on new starts | audit history and affected use-case summary | global runtime safety state | TenantPilot only | Pause AI execution, Resume AI execution | Pause AI execution, Resume AI execution |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes - workspace-owned AI policy becomes current-release product truth
- **New persisted entity/table/artifact?**: no - workspace AI policy reuses existing workspace settings persistence and audit paths
- **New abstraction?**: yes - one concrete governed AI execution boundary and one bounded use-case catalog
- **New enum/state/reason family?**: yes - AI policy modes, provider classes, data classifications, and execution decision reasons
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: TenantPilot needs a safe way to add AI later without letting support, diagnostics, or customer workflows bypass workspace isolation, private-only trust posture, and auditability.
- **Existing structure is insufficient because**: there is currently no app-level AI seam at all. Existing settings, ops controls, and audit paths can store policy and stop work, but they cannot classify AI input, bind use cases to approved data, or force all future AI callers through one decision.
- **Narrowest correct implementation**: keep persistence inside existing workspace settings, reuse existing system ops controls for the emergency stop, lock the use-case catalog to two internal-only future consumers, classify only the first-slice provider/data families, and write audit metadata to the existing audit log instead of building a second AI record system.
- **Ownership cost**: ongoing review of use-case keys, provider-class vocabulary, data classifications, audit metadata shape, and one architecture guard against direct provider calls
- **Alternative intentionally rejected**: direct feature-level AI helpers were rejected as unsafe; a broad provider registry or marketplace was rejected as speculative; a result ledger, cache, or budgeting system was rejected because the first slice does not yet need those truths.
- **Release truth**: current-release truth that deliberately prepares later AI features without shipping them yet

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit, Feature
- **Validation lane(s)**: fast-feedback, confidence
- **Why this classification and these lanes are sufficient**: unit coverage proves the approved use-case catalog, workspace AI policy resolution, provider-class and data-classification gating, operational-control precedence, and audit-metadata shaping. Focused feature coverage proves the existing workspace settings and system controls surfaces, plus one architecture guard that blocked requests never reach a direct provider call path.
- **New or expanded test families**: focused AI policy and execution-decision unit coverage, workspace settings feature coverage, operational-control integration feature coverage, and one architecture guard that blocks direct AI provider calls outside the governed boundary
- **Fixture / helper cost impact**: low-to-moderate. Reuse existing workspace, membership, settings, platform-user, and system control fixtures. Avoid browser harnesses, provider-emulator suites, or any seeded AI result history.
- **Heavy-family visibility / justification**: none
- **Special surface test profile**: standard-native-filament
- **Standard-native relief or required special coverage**: ordinary Filament feature coverage is sufficient for workspace settings and system ops controls. The central AI execution boundary also needs direct service-level tests proving that blocked requests produce no provider call and no raw audit payload.
- **Reviewer handoff**: reviewers must confirm that `ai.execution` uses the existing operational-control path, workspace policy changes reuse the existing settings audit path, unregistered use cases or blocked data classes never reach provider resolution, and no result store, queue, or customer-facing AI surface slipped into the slice.
- **Budget / baseline / trend impact**: low increase in narrow unit and feature coverage only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=WorkspaceAiPolicy`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=GovernedAiExecution`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=AiExecutionArchitectureGuard`

## First-Slice Approved AI Use Case Inventory *(implementation lock-in for v1)*

The first slice is locked to the following approved use cases. Adding a third use case requires an explicit spec update.

| Use Case Key | Intended Future Consumer | Allowed Provider Class(es) | Allowed Data Classification(s) | Visibility | Tenant Context Permitted | Explicitly Excluded Inputs |
|---|---|---|---|---|---|---|
| `product_knowledge.answer_draft` | Product knowledge and contextual help from `ContextualHelpResolver` and related code-owned knowledge sources | `local_private` | `product_knowledge`, `operational_metadata` | internal-only draft | no | tenant policy JSON, raw provider payloads, customer-confidential notes, personal data |
| `support_diagnostics.summary_draft` | Support diagnostics using a redacted summary derived from existing support-diagnostic bundle builders | `local_private` | `redacted_support_summary` | internal-only draft | yes | raw diagnostic bundle sections, raw provider payloads, customer-confidential notes, personal data |

## First-Slice AI Data Classification Contract *(implementation lock-in for v1)*

| Data Classification | Meaning In This Slice | V1 Consequence |
|---|---|---|
| `product_knowledge` | Code-owned glossary, contextual-help, and product documentation source content with no tenant/customer payload | Allowed only for approved use cases on `local_private` |
| `operational_metadata` | Minimal non-secret metadata such as safe surface family, route family, or internal workflow context that does not contain tenant/customer content | Allowed only when the approved use case explicitly opts in |
| `redacted_support_summary` | Sanitized support-diagnostic summary content derived from existing product truth without raw provider payloads or customer-confidential detail | Allowed only for `support_diagnostics.summary_draft` on `local_private` |
| `personal_data` | End-user or operator personal data | Blocked for all AI execution in v1 |
| `customer_confidential` | Tenant/customer-confidential narrative, sensitive configuration detail, or customer-owned context that is not reduced to the approved redacted summary | Blocked for all AI execution in v1 |
| `raw_provider_payload` | Raw provider payloads, raw policy JSON, raw Graph/API responses, or equivalent source material | Blocked for all AI execution in v1 |

## Scope Boundaries *(required for this slice)*

### In Scope

- One concrete governed AI execution boundary that all future AI callers must use
- One code-owned approved-use-case catalog locked to `product_knowledge.answer_draft` and `support_diagnostics.summary_draft`
- One workspace-owned AI policy section on the existing workspace settings page with the modes `disabled` and `private_only`
- One bounded provider-class contract with `local_private` and `external_public`, where `external_public` exists only as a blocked trust class in v1
- One bounded AI data-classification contract as defined above
- One reused operational-control key `ai.execution` on the existing system ops controls surface
- AI decision audit metadata written to the existing audit infrastructure with no prompt/output persistence
- Architecture guardrails that prevent direct provider calls outside the governed boundary

### Non-Goals

- Customer-facing AI features, tenant-facing AI summaries, or support-response drafting surfaces
- Broad provider marketplace, vendor credential management, or multi-provider routing UI
- Token or cost budgeting, credits, rate limits, or queue priority rules
- Result cache, prompt store, output history, or reusable AI artifact persistence
- Autonomous remediation, legal/customer communications, or human-approval workflow for AI outputs
- External public-provider execution with tenant/customer data
- Queueing, retries, or `OperationRun` semantics for AI execution in this slice

## Assumptions

- The existing workspace settings persistence and audit path are sufficient for storing one workspace AI policy mode without introducing a new table.
- The operational-controls foundation from the existing controls page can safely absorb one additional control key for AI execution.
- `ContextualHelpResolver` and support-diagnostic builders can provide code-owned or redacted source inputs without requiring raw provider payloads to cross the AI boundary.
- The first slice remains internal-only and draft-only, so no customer-visible AI wording, approval queue, or outbound communication contract is needed yet.

## Risks

- If the support-diagnostic pipeline cannot produce a clearly redacted summary without raw provider payloads or customer-confidential detail, `support_diagnostics.summary_draft` may need a tighter pre-step before implementation proceeds.
- If the operational-controls slice is unavailable or materially different at implementation time, the `ai.execution` emergency stop may need sequencing adjustment before this feature can land safely.
- A later implementer could still try to add a vendor-specific provider seam or prompt history while wiring the first private model. The architecture guard must stay explicit so the slice does not widen silently.
- A workspace policy surface without an enforced central execution boundary would create false confidence. The execution guard and architecture guard are both mandatory for safe implementation.

## Follow-up Candidates

- AI Usage Budgeting, Context & Result Governance
- AI-Assisted Customer Operations
- Decision-pack or review-workspace AI draft assistance after explicit human-approval and evidence-governance rules exist

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Set workspace AI posture once (Priority: P1)

As a workspace owner or manager, I want to choose whether the workspace disables AI entirely or allows only private-only AI for approved internal use cases so the product has one explicit trust posture before any AI feature is added.

**Why this priority**: The foundation is not safe unless workspace-owned AI posture is explicit, auditable, and visible before later AI use cases appear.

**Independent Test**: Open the existing workspace settings page, change the AI policy between `disabled` and `private_only`, and verify that the resolved policy explanation updates and is attributable without touching application code or environment flags.

**Acceptance Scenarios**:

1. **Given** a workspace manager opens workspace settings, **When** they save the AI policy mode as `private_only`, **Then** the page shows that only approved private-only use cases may proceed and the change is attributable through the existing workspace settings audit path.
2. **Given** the same workspace changes the mode back to `disabled`, **When** the page reloads, **Then** the page shows that no AI execution is allowed for the workspace and future approved use cases would block before execution.

---

### User Story 2 - Block unsafe AI requests before any provider call (Priority: P1)

As the product owner responsible for later AI-assisted operator workflows, I want every in-scope AI request to pass through one governed allow-or-block decision so unapproved use cases, external-public trust classes, or disallowed data classes never reach a provider call.

**Why this priority**: This is the core safety outcome of the foundation. If requests can still bypass the boundary, the slice fails even if the settings UI exists.

**Independent Test**: Exercise the governed AI boundary with the two approved use cases and several blocked combinations, and verify that allowed requests only accept the approved private input shape while blocked requests never resolve a provider call.

**Acceptance Scenarios**:

1. **Given** a workspace is set to `private_only` and a request uses `support_diagnostics.summary_draft` with `redacted_support_summary`, **When** the governed AI boundary evaluates the request for `local_private`, **Then** it allows the request and records an audit-ready decision without persisting prompt or output text.
2. **Given** the same workspace and use case, **When** a request declares `external_public` as the provider class, **Then** the boundary blocks the request before any provider resolution or outbound call occurs.
3. **Given** any workspace AI mode other than `disabled`, **When** a request includes `raw_provider_payload`, `customer_confidential`, or `personal_data`, **Then** the boundary blocks the request before execution even if the requested provider class is `local_private`.
4. **Given** a request uses an unregistered AI use case key or lacks workspace context, **When** the boundary evaluates it, **Then** the request is rejected and no AI provider call is attempted.

---

### User Story 3 - Pause all AI execution centrally during an incident (Priority: P2)

As a platform operator, I want to pause all new AI execution from the existing system ops controls surface so rollout problems or privacy concerns can be contained without a deployment.

**Why this priority**: Reusing the operational-controls pattern is the smallest safe incident stop for a cross-cutting AI boundary.

**Independent Test**: Pause `ai.execution` from the existing controls page, send an otherwise valid AI request through the governed boundary, and verify that it blocks with the operational-control reason until the control is resumed.

**Acceptance Scenarios**:

1. **Given** `ai.execution` is paused from `/system/ops/controls`, **When** an otherwise valid approved AI request is evaluated, **Then** the request is blocked before execution and the block reason identifies the active operational control.
2. **Given** the same control is resumed, **When** the same approved request is retried, **Then** the request follows normal workspace policy and data-classification evaluation again.

### Edge Cases

- A request may arrive without workspace context or with tenant context from an unauthorized actor; the host authorization boundary must fail first so the AI layer does not leak tenant or policy detail.
- A support-diagnostic request may contain mixed safe and unsafe source material; if the source cannot be reduced to `redacted_support_summary`, the entire AI request is blocked.
- A workspace may be set to `private_only` while the platform-level `ai.execution` control is paused; the pause control wins and blocks all new starts.
- An AI request may be accepted just before `ai.execution` is paused; the control governs new starts only and does not retroactively mutate any in-flight private execution.
- A later feature may try to introduce a third use case or a new data classification in the same implementation PR; that is out of scope unless the active spec is updated explicitly.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no Microsoft Graph contract change, no tenant-changing provider write, and no new queued workflow family. It creates a governed decision boundary that must run before any future AI provider execution, while reusing the existing workspace settings, operational-controls, and audit infrastructure.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The slice introduces new AI-specific vocabulary and one new execution boundary because the current-release product now needs a safe first truth for AI policy, provider trust class, and allowed data before broader AI features land. It stays narrow by avoiding new tables, queues, result persistence, or provider-marketplace abstractions.

**Constitution alignment (XCUT-001):** This slice is cross-cutting across workspace settings, operational controls, audit logging, product-knowledge input, and support-diagnostic input. It must reuse the existing settings and ops-controls paths rather than creating page-local AI settings or emergency-stop logic.

**Constitution alignment (PROV-001):** AI provider trust is classified through neutral provider classes, not vendor-specific names. Provider-specific semantics and provider credential management remain out of scope.

**Constitution alignment (TEST-GOV-001):** Proof stays in focused unit and feature lanes. The feature must add one explicit architecture guard proving that AI provider access cannot be called directly outside the governed boundary.

**Constitution alignment (OPS-UX):** This slice does not create or reuse an `OperationRun`. If a later AI feature becomes queued or operationally relevant, that behavior belongs in a follow-up spec and must adopt the canonical Ops-UX contract then.

**Constitution alignment (RBAC-UX):** The slice spans workspace `/admin` settings and platform `/system` operational controls. Wrong-plane or non-member access remains 404. Existing workspace settings authorization stays authoritative for policy mutation. Existing system-panel capability enforcement stays authoritative for the emergency stop. The governed AI boundary must not become an authorization bypass for tenant-scoped content.

**Constitution alignment (BADGE-001):** If policy mode or control state is shown with a badge or status chip, the rendering must reuse existing settings/control status semantics rather than introduce page-local AI color language.

**Constitution alignment (UI-FIL-001):** The only operator-facing surfaces in scope are existing Filament pages. The feature must use native sections, helper text, callouts, actions, and control cards rather than a custom AI admin shell.

**Constitution alignment (UI-NAMING-001):** Primary operator-facing labels must stay implementation-light and product-truthful: `Workspace AI policy`, `Disabled`, `Private only`, `Approved AI use cases`, `Blocked data classes`, and `AI execution`. Terms such as vendor names, SDK names, or low-level model endpoint jargon stay out of primary labels.

**Constitution alignment (DECIDE-001):** Workspace settings and system ops controls are the only decision surfaces in scope. No new decision inbox, AI draft viewer, or evidence-heavy AI result page is introduced.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** The feature must preserve the existing singleton settings and control-center page patterns. It may not add redundant inspect actions, shadow routes, or mixed action groups for AI management in this first slice.

**Constitution alignment (ACTSURF-001 - action hierarchy):** Workspace policy mutation stays on the workspace settings page. Platform-wide pause/resume stays on the existing controls page. No other visible AI mutation action is introduced.

**Constitution alignment (OPSURF-001):** Default-visible content must stay operator-first: whether AI is disabled or private-only for a workspace, and whether all new AI execution is paused globally. No raw prompt content, model internals, or tenant payload excerpts belong on the default surfaces.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** One decision layer is justified because direct reads from raw settings or local feature flags would still force each future AI surface to duplicate provider-class, data-classification, and policy logic. Tests must target business outcomes such as allowed versus blocked execution and clean audit payloads instead of cosmetic rendering alone.

**Constitution alignment (Filament Action Surfaces):** The action-surface contract remains satisfied. Workspace settings keep a single in-page save model. System ops controls keep confirmation-protected state-change actions on the same surface. No redundant inspect action or empty action group is introduced.

**Constitution alignment (UX-001 - Layout & Information Architecture):** The workspace AI policy stays inside the existing settings layout with sectioned content and plain-language guidance. The system AI execution stop stays inside the existing controls page. No new custom layout family is introduced.

### Functional Requirements

- **FR-248-001 Approved use-case catalog**: The system MUST define a code-owned AI use-case catalog locked to exactly two first-slice keys: `product_knowledge.answer_draft` and `support_diagnostics.summary_draft`.
- **FR-248-002 Use-case declaration contract**: Each first-slice use case MUST declare its allowed provider class, allowed data classifications, source family, visibility (`internal-only draft`), and whether tenant context is permitted.
- **FR-248-003 Workspace AI policy truth**: The system MUST store workspace AI posture through the existing workspace settings mechanism and audit policy changes through the existing workspace settings audit path.
- **FR-248-004 First-slice policy modes**: The first slice MUST support exactly two workspace AI policy modes: `disabled` and `private_only`.
- **FR-248-005 Provider-class contract**: The system MUST define a bounded provider-class contract containing `local_private` and `external_public`, where `external_public` exists only as a blocked trust class in v1.
- **FR-248-006 Data-classification contract**: The system MUST classify AI inputs using the first-slice data classifications defined in this spec and MUST block `personal_data`, `customer_confidential`, and `raw_provider_payload` for all AI execution in v1.
- **FR-248-007 Central execution boundary**: The system MUST route every future AI execution request through one governed execution boundary that requires a registered use case key, actor context, workspace context, requested provider class, declared data classification, and source family before execution is attempted.
- **FR-248-008 Block precedence**: After the host surface has already resolved authorization and scope entitlement, the governed boundary MUST evaluate `ai.execution` operational control, workspace AI policy mode, use-case registration, provider-class allowance, and data-classification allowance before resolving any AI provider call.
- **FR-248-009 Operational-control reuse**: The feature MUST reuse the existing operational-controls pattern through a new in-scope control key `ai.execution` on `/system/ops/controls` rather than introducing a second AI-specific emergency stop mechanism.
- **FR-248-010 Approved source inputs only**: `product_knowledge.answer_draft` MUST consume only code-owned product-knowledge sources, and `support_diagnostics.summary_draft` MUST consume only redacted support-diagnostic summary content. Raw provider payloads, raw policy JSON, and customer-confidential notes are out of scope.
- **FR-248-011 Audit metadata shape**: The system MUST write stable AI-related audit entries for workspace policy changes and AI execution decisions, including at minimum use case key, provider class, workspace AI policy mode, data classification, decision outcome, decision reason, workspace scope, tenant scope when present, source family, and an optional context fingerprint; audit entries MUST NOT store raw prompt text, raw source payloads, or full output text.
- **FR-248-012 No direct provider calls**: Feature code MUST NOT call AI providers directly. A guard test or equivalent architecture check MUST fail if AI provider access appears outside the central governed boundary.
- **FR-248-013 Workspace settings UX**: The existing workspace settings page MUST show the selected AI policy mode, plain-language effect, approved use cases, allowed provider classes, and blocked data classes without introducing vendor-specific admin UI.
- **FR-248-014 Pause semantics**: When `ai.execution` is paused, all new AI execution requests MUST block before provider resolution, while in-flight work already accepted before the pause MAY complete unchanged.
- **FR-248-015 No hidden scope growth**: The first slice MUST NOT introduce customer-facing AI output surfaces, external public-provider execution with tenant/customer data, AI result persistence, cost budgeting, queue/retry behavior, or a provider marketplace.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Workspace settings AI policy section | `app/Filament/Pages/Settings/WorkspaceSettings.php` | `Save` | N/A - singleton settings page | none | none | N/A | N/A | `Save`; optional `Reset policy` if the page already supports per-setting reset interactions | yes | Reuses the existing workspace settings mutation and audit path; no new AI execution action appears here |
| System ops controls AI execution control card | `app/Filament/System/Pages/Ops/Controls.php` | `Pause AI execution`, `Resume AI execution`, `View history` | Same-page control card or confirmation modal | none | none | none | same-page actions only | `Review impact`, `Save changes`, `Cancel` inside the existing control modal flow | yes | Reuses `PlatformCapabilities::OPS_CONTROLS_MANAGE` and the existing operational-controls action pattern; no new system AI console is introduced |

### Key Entities *(include if feature involves data)*

- **Workspace AI Policy**: The workspace-owned policy truth that resolves whether AI is `disabled` or `private_only` for the workspace.
- **Approved AI Use Case Definition**: The code-owned catalog entry that defines one allowed AI purpose, its allowed provider class, allowed data classifications, source family, and visibility.
- **AI Execution Request**: The derived request envelope passed into the governed boundary containing actor, workspace, optional tenant, use case key, provider class, data classification, and source provenance.
- **AI Execution Decision**: The allow-or-block result returned by the governed boundary, including policy mode, matched operational-control state, decision reason, and audit-ready metadata.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-248-001**: In validation scenarios, 100% of in-scope AI requests with an unregistered use case, blocked provider class, blocked data classification, missing workspace context, or active `ai.execution` control are stopped before any provider resolution or outbound call occurs.
- **SC-248-002**: Workspace owners can set and review the workspace AI policy on the existing workspace settings page in under 2 minutes without editing environment variables or code.
- **SC-248-003**: In validation coverage, 0 external-public AI executions occur for tenant/customer data in the first slice.
- **SC-248-004**: The two approved first-slice AI use cases resolve through the same governed decision vocabulary and audit metadata shape, with no direct provider call sites outside the central boundary in guard coverage.