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.