TenantAtlas/specs/431-exchange-powershell-invocation-operation-registration-gate/plan.md

# Implementation Plan: Exchange PowerShell Invocation Operation Registration and Execution Gate

**Branch**: `431-exchange-powershell-invocation-operation-registration-gate` | **Date**: 2026-07-05 | **Spec**: `specs/431-exchange-powershell-invocation-operation-registration-gate/spec.md`  
**Input**: Feature specification from `specs/431-exchange-powershell-invocation-operation-registration-gate/spec.md`

## Summary

Implement a narrow OperationRun/provider operation registration and fake-runner invocation gate for the three Exchange PowerShell contracts introduced by Spec 430: `transportRule`, `remoteDomain`, and `inboundConnector`. The implementation registers the canonical operation path, provider operation, provider capability, capability resolver mapping, safe summaries, sanitized failures, one invocation gate, a structured runner interface, and a fake runner. Production execution remains disabled/inert. No live Exchange calls, evidence, UI, migrations, jobs, scheduled capture, customer claims, or `tenant_id` are allowed.

## Technical Context

**Language/Version**: PHP 8.4 / Laravel 12  
**Primary Dependencies**: Filament v5 / Livewire v4 baseline remains unchanged; no UI code planned  
**Storage**: PostgreSQL via existing `operation_runs` table only; no migration  
**Testing**: Pest 4 focused unit and feature tests  
**Validation Lanes**: fast-feedback for unit/feature; selected regressions for Spec 430/426/427/417/419/420; browser N/A  
**Target Platform**: Laravel Sail local, Dokploy staging/production remains unaffected because production execution is disabled  
**Project Type**: Laravel monolith under `apps/platform`  
**Performance Goals**: No real provider work; fake-runner tests complete locally without network or shell execution  
**Constraints**: No raw provider output persistence, no PowerShell process, no Microsoft calls, no UI, no migrations  
**Scale/Scope**: Exactly three Exchange target types and one invocation operation

## Preflight Findings

- Current prep branch before Spec Kit execution: `platform-dev`.
- HEAD before Spec Kit execution: `9b58a569 feat: add Exchange PowerShell adapter contract slice 1 (#497)`.
- Initial dirty state before Spec Kit execution: clean.
- Spec Kit helper created branch: `431-exchange-powershell-invocation-operation-registration-gate`.
- Existing related packages: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`, `specs/430-exchange-powershell-adapter-contract-slice-1/`.
- Spec 430 implementation report proves the three command contracts and no OperationRun invocation/evidence/UI/migration.
- Existing OperationRun type for generic capture: `tenant_configuration.capture`; no Exchange PowerShell invocation type exists.
- Existing operation catalog has `tenant_configuration.capture`; no invocation entry exists.
- Existing provider operation registry has provider connection, inventory, compliance snapshot, restore, directory groups, and role definitions entries; no Exchange PowerShell invocation entry exists.
- Existing provider capability registry has provider connection, inventory, configuration, restore, directory groups, and role definitions capabilities; no Exchange PowerShell invocation capability exists.
- Existing summary keys are fixed in `OperationSummaryKeys::all()` and unknown keys are dropped by `SummaryCountsNormalizer`.
- Existing `ProviderOperationStartGate` stores `provider_connection_id` in OperationRun context and validates provider bindings/capabilities; implementation should reuse or compose with this path where practical.
- Existing actor capability registry includes `App\Support\Auth\Capabilities::PROVIDER_RUN`; Spec 431 reuses it instead of adding a new actor/RBAC capability.
- Existing provider credentials are represented through `ProviderConnection::credential`, `ProviderCredential`, `CredentialManager`, and `ProviderIdentityResolver`; Spec 431 must use that path and must not invent a credential reference store.
- Existing feature flags live under `tenantpilot.features.*`; Spec 431 uses `tenantpilot.features.exchange_powershell_invocation`, default `false`.

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
- **No-impact class, if applicable**: backend-only operation registration/gate.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: OperationRun and provider operation shared contracts only; no rendered UI shared family.
- **State layers in scope**: OperationRun lifecycle and summary/failure state only.
- **Audience modes in scope**: internal operator/reviewer only; no customer surface.
- **Decision/diagnostic/raw hierarchy plan**: No product view. Raw provider output is forbidden from persistence.
- **Raw/support gating plan**: Raw output not stored.
- **One-primary-action / duplicate-truth control**: N/A.
- **Handling modes by drift class or surface**: N/A.
- **Repository-signal treatment**: no rendered UI signal.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: `N/A - no rendered UI surface changed`.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: no rendered product surface changed.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **No-impact rationale**: The spec forbids routes, Filament pages, Livewire components, navigation, global search, and assets.
- **Navigation / Filament provider-panel handling**: no panel/provider registration changes.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical addition only; no compatibility aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures.
- **Page archetype and surface budget plan**: N/A.
- **Technical Annex and deep-link demotion plan**: N/A - no rendered product surface changed. OperationRun remains internal/audit truth.
- **Canonical status vocabulary plan**: N/A.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: N/A.
- **Visible complexity outcome target**: neutral.
- **Implementation report target**: `specs/431-exchange-powershell-invocation-operation-registration-gate/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: repo baseline remains Livewire v4; no Livewire runtime code planned.
- **Panel provider registration location**: no panel/provider change; Laravel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Filament resource/global search surface changed.
- **Destructive/high-impact action posture**: none added.
- **Asset strategy**: no assets; `filament:assets` is not required for this slice.
- **Testing plan**: no pages/widgets/relation managers/actions/browser tests because no rendered UI surface changes.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, assets, container, or Dokploy changes. Production execution remains disabled/inert.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: OperationRun type/catalog/lifecycle, provider operation registry, provider capability registry, capability resolver, summary normalization, failure sanitizer, provider operation start/gate path, Coverage v2 source contract resolver/contracts.
- **Shared abstractions reused**: `OperationRunService`, `OperationCatalog`, `ProviderOperationRegistry`, `ProviderCapabilityRegistry`, `OperationRunCapabilityResolver`, `OperationSummaryKeys`, `SummaryCountsNormalizer`, `RunFailureSanitizer`, `CoverageSourceContractResolver`, `ExchangePowerShellCommandContracts`.
- **New abstraction introduced? why?**: One invocation gate and one runner interface are allowed because provider/shell invocation must be centrally blocked, structured, and fake-testable before evidence work can safely use it.
- **Why the existing abstraction was sufficient or insufficient**: Existing registries and OperationRun lifecycle are sufficient foundations but lack this operation/capability/runner boundary.
- **Actor capability path**: Reuse `Capabilities::PROVIDER_RUN` for operation execution. If implementation proves that capability is too broad, stop and amend the spec before adding a new actor capability or role mapping.
- **Public gate boundary**: `ExchangePowerShellInvocationGate` is the sole public invocation entry point. It may call `ProviderOperationStartGate` internally for provider binding/capability/scope behavior; feature code and tests must not directly call the runner or provider start gate for this invocation.
- **Bounded deviation / spread control**: No parallel provider framework. If a production runner class is introduced, it must be inert and blocked by default.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes, backend OperationRun creation/lifecycle only.
- **Central contract reused**: `OperationRunService` for creation/transition; `OperationSummaryKeys` and `SummaryCountsNormalizer`; `RunFailureSanitizer`.
- **Delegated UX behaviors**: no toast, run link, artifact link, browser event, queued DB notification, or surface messaging.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: central lifecycle mechanism where applicable; no feature-local notification.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Exchange PowerShell command names, command contracts, response shape, command safety, fake-runner outcome vocabulary.
- **Platform-core seams**: OperationRun type/catalog, provider operation registry, provider capability registry, capability resolver, summary/failure sanitizer, provider connection context.
- **Neutral platform terms / contracts preserved**: operation, provider connection, capability, managed environment, workspace, source contract, summary counts, failure reason, runner mode.
- **Retained provider-specific semantics and why**: Exchange command names stay inside provider-owned contracts because Spec 431 is explicitly Exchange PowerShell only.
- **Bounded extraction or follow-up path**: document-in-feature; production runner hardening and evidence promotion remain separate specs.

## Constitution Check

- Inventory-first: no inventory or evidence truth is changed.
- Read/write separation: no restore/apply/mutation provider action; only read-only command contracts are fake-invoked.
- Graph contract path: no Microsoft Graph call path changed; no Graph call added.
- Deterministic capabilities: provider/actor capability mappings must be central and tested.
- Actor capability: the invocation operation maps to existing `Capabilities::PROVIDER_RUN`; no new actor capability is planned without a spec amendment.
- RBAC-UX: non-member workspace/environment scope is 404; member without capability is 403; readonly cannot invoke.
- Workspace isolation: workspace and managed environment are mandatory inputs.
- Tenant isolation: managed-environment entitlement is enforced before provider connection disclosure.
- Feature gate: logical key `tenant_configuration.exchange_powershell_invocation` is implemented via `tenantpilot.features.exchange_powershell_invocation` and defaults to false.
- Credential source: non-fake mode uses existing `ProviderConnection::credential` / `ProviderCredential` / `ProviderIdentityResolver` truth and blocks safely when no repo-supported credential reference exists.
- Run observability: invocation attempts are OperationRun-owned before fake runner execution.
- OperationRun start UX: no rendered start surface; lifecycle/summary/failure paths stay central.
- Ops-UX 3-surface feedback: no new UI feedback or notification policy.
- Ops-UX lifecycle: status/outcome transitions only through `OperationRunService`.
- Ops-UX summary counts: allowed keys only, flat numeric values only.
- Data minimization: OperationRun context stores safe identifiers and runner mode only; no raw output, credentials, tokens, transcripts, or payloads.
- Test governance: focused unit/feature tests with fake runners; no browser lane; no heavy shared fixtures by default.
- Proportionality: one operation/capability/gate/runner boundary justified by provider credential safety, RBAC, and operation truth.
- No premature abstraction: no generic PowerShell platform or multi-provider framework.
- Persisted truth: no new tables or persisted evidence truth.
- Behavioral state: blocker/failure codes must alter execution handling and sanitize operator diagnosis.
- Provider boundary: Exchange semantics remain provider-owned and do not become platform-core ownership truth.
- V1 explicitness / few layers: narrow explicit mapping and one gate preferred.
- Spec discipline / bloat check: proportionality review included in `spec.md`.
- Filament-native UI: N/A - no UI.
- Product Surface Contract: N/A - no rendered surface changed.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for registries/summary/failure/runner shape; Feature for OperationRun/gate/provider scope/no evidence/no UI/no tenant_id.
- **Affected validation lanes**: fast-feedback/confidence focused tests; selected regressions; browser N/A.
- **Why this lane mix is the narrowest sufficient proof**: The behavior is backend registry/gate/service behavior with fake runner and DB OperationRun assertions; no rendered UI or PostgreSQL-specific migration exists.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec431 --compact`
  - selected Spec 430/426/427/417/419/420 regression files or filters documented by implementation
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: Provider connection/workspace/managed-environment/actor setup required for feature tests; keep helper setup explicit and local.
- **Expensive defaults or shared helper growth introduced?**: no; fake runner should be local to Spec 431 tests unless later specs adopt it intentionally.
- **Heavy-family additions, promotions, or visibility changes**: none planned.
- **Surface-class relief / special coverage rule**: backend-only; browser `N/A - no rendered UI surface changed`.
- **Closing validation and reviewer handoff**: implementation report must list exact tests and pass/fail counts.
- **Budget / baseline / trend follow-up**: none unless implementation materially expands regression lanes.
- **Review-stop questions**: verify no shell execution, no Microsoft calls, no evidence, no raw output persistence, no UI, no migration, no `tenant_id`, no mini-platform.
- **Escalation path**: reject-or-split if implementation attempts live provider execution, evidence promotion, UI, migrations, or broader Exchange types.
- **Active feature PR close-out entry**: no rendered UI surface changed; no deployment impact.
- **Why no dedicated follow-up spec is needed**: Routine test upkeep stays inside Spec 431; production runner hardening/evidence promotion are already separate follow-up candidates.

## Project Structure

### Documentation (this feature)

```text
specs/431-exchange-powershell-invocation-operation-registration-gate/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- implementation-report.md
```

### Source Code (likely affected by later implementation)

```text
apps/platform/app/Support/OperationRunType.php
apps/platform/app/Support/OperationCatalog.php
apps/platform/app/Services/Providers/ProviderOperationRegistry.php
apps/platform/app/Services/Providers/ProviderOperationStartGate.php
apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityRegistry.php
apps/platform/app/Support/Operations/OperationRunCapabilityResolver.php
apps/platform/app/Support/Auth/Capabilities.php
apps/platform/app/Support/OpsUx/OperationSummaryKeys.php
apps/platform/app/Support/OpsUx/SummaryCountsNormalizer.php
apps/platform/app/Support/OpsUx/RunFailureSanitizer.php
apps/platform/app/Models/ProviderConnection.php
apps/platform/app/Models/ProviderCredential.php
apps/platform/app/Services/Providers/ProviderIdentityResolver.php
apps/platform/app/Services/Providers/CredentialManager.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandContracts.php
apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationGate.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandRunner.php
apps/platform/app/Services/TenantConfiguration/FakeExchangePowerShellCommandRunner.php
apps/platform/config/tenantpilot.php
apps/platform/tests/Unit/Support/TenantConfiguration/
apps/platform/tests/Feature/TenantConfiguration/
```

Forbidden source changes:

```text
apps/platform/routes/**
apps/platform/resources/views/**
apps/platform/app/Filament/**
apps/platform/app/Livewire/**
apps/platform/database/migrations/**
Exchange-specific evidence tables
jobs for live provider execution
provider clients that call Microsoft
```

## Implementation Phases

### Phase 0 - Preflight

- Capture branch, HEAD, dirty state.
- Reconfirm Spec 430 contract state and no pending checklist blocker.
- Reconfirm target types and command names.
- Reconfirm no migration, no UI, no evidence, no live execution, no `tenant_id`.

### Phase 1 - Operation and Provider Registration

- Add canonical OperationRun type.
- Add OperationCatalog entry and alias inventory entry only if required by repo pattern.
- Add ProviderOperationRegistry definition and Microsoft active binding or explicit internal binding.
- Add ProviderCapabilityRegistry capability.
- Add OperationRunCapabilityResolver execution mapping.

### Phase 2 - Summary and Failure Plumbing

- Reuse `total`, `processed`, `succeeded`, `failed`, `skipped`, and `items` unless implementation proves a new key is necessary.
- Extend failure normalization only with safe bounded mappings or known provider reason codes.
- Test known/unknown failures and redaction.

### Phase 3 - Invocation Gate

- Add single gate service.
- Compose with existing provider operation/capability/scope gates where practical.
- Require verified Spec 430 contracts, allowlisted commands, parameters, actor capability `Capabilities::PROVIDER_RUN`, provider scope, feature gate `tenantpilot.features.exchange_powershell_invocation`, runner mode, redaction policy, and existing provider credential/identity resolution unless fake-runner-only.
- Create OperationRun before fake runner execution.

### Phase 4 - Runner Boundary

- Add structured runner interface.
- Add fake runner and structured envelopes.
- Add disabled/inert production runner only if needed.
- Reject raw/mutation/arbitrary command paths.

### Phase 5 - No-Promotion Safety

- Prove no evidence rows, no coverage promotion, no compare/render/certification/restore/customer state, no customer output, no UI/routes/assets/global search, no migration, no `tenant_id`, no mini-platform.

### Phase 6 - Validation and Report

- Run focused Spec 431 tests.
- Run selected regressions.
- Run Pint and `git diff --check`.
- Complete implementation report with proportionality, proof, no-surface, and deployment close-out.

## Risk Controls

- Stop if implementation needs a migration.
- Stop if implementation needs live provider execution.
- Stop if a production runner would call PowerShell.
- Stop if evidence persistence is required.
- Stop if UI/routes/jobs/scheduled capture are introduced.
- Stop if new summary keys are emitted without registration/tests.
- Stop if provider/capability resolution cannot fail closed.
- Stop if `Capabilities::PROVIDER_RUN` proves too broad and a new actor capability would be required without a spec amendment.
- Stop if the feature gate cannot default disabled through `tenantpilot.features.exchange_powershell_invocation`.
- Stop if credential material would be persisted or logged.
- Stop if credential checks require a new credential persistence path.
- Stop if `tenant_id` is introduced.

## Preparation Analyze Result

Initial preparation self-review recorded this package as aligned with current repo truth and preparation-only boundaries. Follow-up `/speckit-analyze` remediation clarified actor capability, feature-gate path/default, credential-source truth, and the single public invocation gate boundary. No application code was modified. The repo does not expose executable `speckit.plan`, `speckit.tasks`, or `speckit.analyze` commands; this package was created with the available Spec Kit feature/plan scripts plus manual artifact authoring against the repository templates and prompts.