diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md new file mode 100644 index 00000000..d83c5afd --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md @@ -0,0 +1,163 @@ +# Adapter Strategy + +Spec 429 catalog status: documentation only. This file does not create adapters, clients, provider calls, tests, evidence, OperationRuns, UI, or runtime registry consumption. + +## Source Authority Rules + +Allowed source authority for future specs: + +- Official Microsoft documentation for source surface availability, authentication, authorization, and API/cmdlet behavior. +- Current repo contracts and tests for TenantPilot runtime truth. +- Existing Coverage v2 source-contract, identity, evidence, compare/render, Claim Guard, OperationRun, workspace/managed-environment/provider-connection, and redaction patterns. + +Forbidden source authority: + +- Guessed Microsoft Graph endpoints. +- Admin portal UI pages as runtime source contracts. +- PowerShell examples as proof that TenantPilot has runtime support. +- Registry aliases as evidence support. +- Historical completed specs as mutable artifacts. +- Display names as stable identity. +- `tenant_id` as platform-core ownership truth. +- Real shell execution in unit tests. + +## Adapter Pattern Matrix + +| Adapter pattern | Source surface class | Use when | Required future implementation constraints | Spec 429 decision | +| --- | --- | --- | --- | --- | +| `existing_graph_client_contract` | `graph_v1` | A repo Graph contract already exists and is production-safe. | Must go through `GraphClientInterface` and `config/graph_contracts.php`; no render-time Graph call; tests must prove scope, permissions, pagination, identity, redaction, and no customer overclaim. | Not used for current Exchange/Teams policy Cohort 1. | +| `new_graph_contract` | `graph_v1` or `graph_beta_experimental` | Official Graph source exists and policy/resource shape fits Coverage v2. | Add contract registry entry, permission review, pagination, allowed select/expand, schema hash, fake Graph tests, and beta/internal-only handling where needed. | Deferred for Teams inventory/app-installation style future work; not the first adapter path. | +| `new_exchange_admin_api_contract` | `exchange_online_admin_api` | The focused preview Admin API supports the target and preview/internal-only limitations are acceptable. | OAuth token path, Exchange RBAC role groups, POST-only endpoint handling, X-AnchorMailbox handling if required, paging/property selection, response-shape guard, preview no-certification rule, fake HTTP tests. | Candidate for `acceptedDomain` and `organizationConfig`; not a full Exchange replacement. | +| `new_exchange_powershell_adapter` | `exchange_online_powershell_rest` | Exchange source truth is only in Exchange Online PowerShell or the Admin API is too narrow/preview-limited. | App-only/certificate or managed identity feasibility, Exchange RBAC, command allowlist, no arbitrary script execution, fake command runner, module/runtime container decision, throttling/retry, structured errors, redaction, source metadata, OperationRun for real remote work. | Recommended first Spec 430 adapter pattern. | +| `new_teams_powershell_adapter` | `teams_powershell` | Teams policy/configuration source truth is in MicrosoftTeams PowerShell. | Application-based authentication, Teams RBAC roles, supported-cmdlet check, command allowlist, fake command runner, module/runtime container decision, throttling/retry, structured errors, redaction, source metadata, OperationRun for real remote work. | Recommended second slice after Exchange PowerShell proof, or reduced paired slice if Spec 430 must cover both workloads. | +| `new_security_compliance_adapter` | `security_compliance_powershell` | Purview/Security & Compliance policy source truth is explicitly in compliance PowerShell. | Separate security review, role/permission minimization, content-sensitive redaction, no customer claims until proven, fake command runner, OperationRun for remote work. | Deferred; not part of Exchange/Teams Cohort 1. | +| `defer_to_purview_adapter` | `security_compliance_powershell` | The target is primarily Purview/Defender/Compliance rather than Exchange/Teams. | Create a separate Purview/Security & Compliance source-surface strategy/spec. | Deferred. | +| `unsupported` | `unsupported_manual_only`, `unknown_requires_research`, `sharepoint_pnp_related` | Source is manual, unknown, portal-only, or belongs to another workload boundary. | Do not implement; document blocker. | Blocked/deferred. | + +## Graph Contract Concerns + +Future Graph-based Teams work must answer: + +- Is the resource available in Graph v1.0, or only beta? +- Does the resource represent durable configuration, or collaboration/content activity? +- Which Graph application/delegated permissions are required? +- Does the endpoint page, delta, select, expand, or filter? +- Which identity fields are stable across tenants and exports? +- Does the response include chat/message/file/recording/transcript/content or other forbidden data? +- Can the existing `GraphClientInterface` and `config/graph_contracts.php` model the endpoint without a new provider framework? +- How are empty, denied, unsupported, unavailable, throttled, and malformed responses distinguished? + +Spec 429 does not select a Graph-native policy path for Exchange/Teams Cohort 1 because current repo truth already removed unverified Graph endpoint claims for the first four Exchange/Teams target types. + +## Exchange Online Admin API Concerns + +The Exchange Online Admin API is a focused preview REST administrative surface. Future use must document: + +- Preview status and tenant availability. +- Supported endpoint and cmdlet subset. +- Unsupported scenarios and why the API does not replace Exchange Online PowerShell. +- OAuth flow: delegated `Exchange.ManageV2` or app-only `Exchange.ManageAsAppV2`. +- Exchange RBAC role groups and least-privilege custom role options. +- POST-only request model. +- Paging/property selection. +- X-AnchorMailbox/routing requirements where applicable. +- Response shape, empty result, denied result, unsupported result, unavailable result, and malformed result handling. +- Preview/internal-only claim posture: no certification or customer-ready claim from preview-only source proof. + +Spec 429 treats `acceptedDomain` and `organizationConfig` as Admin API candidates but does not make them runtime-supported. + +## Exchange PowerShell Adapter Concerns + +A future `new_exchange_powershell_adapter` must include: + +- Authentication: app-only certificate-based authentication or managed identity where supported by deployment topology. +- Tenant consent: required Office 365 Exchange Online application permissions and admin consent must be explicit. +- RBAC: least-privilege Exchange role group or custom role group, not broad Global Administrator by default. +- Execution environment: container image/module installation, PowerShell version, module version pinning/update policy, non-interactive execution, timeout handling, and process isolation. +- Command allowlist: only approved read cmdlets and approved parameters. +- No shell execution in unit tests: use a fake command runner with deterministic serialized outputs. +- Throttling and retries: classify throttled/transient failures separately from denied/unsupported/source-unavailable. +- Error normalization: sanitize command errors and map to stable reason codes. +- Response serialization: canonical JSON with sorted keys where appropriate, source version, command name, parameter hash, schema/hash metadata, and no raw terminal transcript by default. +- Redaction: remove or hide secrets, tokens, credentials, authorization headers, certificate/private-key material, raw provider responses, mail content, message content, header/body/subject patterns where unsafe, smart hosts when unsafe, and PII-heavy fields. +- OperationRun: real provider execution is remote/long-running and must be OperationRun-backed in a later runtime spec. + +Recommended first Exchange runtime proof: + +- `transportRule` +- `remoteDomain` +- one connector type, preferably `inboundConnector` first if a later spec confirms source output shape + +Do not include `sharedMailbox`, `managementRoleAssignment`, or compliance policies in the first Exchange adapter slice. + +## Teams PowerShell Adapter Concerns + +A future `new_teams_powershell_adapter` must include: + +- Authentication: application-based authentication with certificate or access-token flow, plus explicit Teams module version support. +- RBAC: Microsoft Entra roles and Teams admin roles assigned to the application/service principal; verify supported cmdlets and unsupported cmdlet list. +- Permissions: Graph permissions required by Teams PowerShell application authentication must be explicit, while avoiding unnecessary Skype and Teams Tenant Admin API configuration where Microsoft guidance warns against it. +- Execution environment: module installation, PowerShell runtime, container compatibility, non-interactive execution, timeout handling, and process isolation. +- Command allowlist: only approved read cmdlets and parameters. +- No shell execution in unit tests: use a fake command runner. +- Response serialization: canonical shape with source command, module version, policy ID/source ID, and schema/hash metadata. +- Error normalization: distinguish empty, denied, unsupported, source-unavailable, throttled, and malformed output. +- Redaction: never capture or default-render chat messages, file content, meeting recordings, transcripts, app secrets, app credentials, raw provider responses, or raw access tokens. +- OperationRun: real provider execution is remote/long-running and must be OperationRun-backed in a later runtime spec. + +Recommended first Teams runtime proof: + +- `appPermissionPolicy` +- `appSetupPolicy` +- `meetingPolicy` + +Do not include voice/phone-number policy, team/channel inventory, app-centric management migration, or SharePoint/OneDrive file governance in the first Teams adapter slice. + +## Security & Compliance / Purview Boundary + +Targets such as `dlpCompliancePolicy`, `labelPolicy`, `retentionCompliancePolicy`, `autoSensitivityLabelPolicy`, `protectionAlert`, and `complianceTag` are not Exchange/Teams Cohort 1. They need a separate Purview/Security & Compliance adapter strategy because they can involve: + +- compliance-specific roles and permissions, +- content-sensitive policy scopes, +- retention/legal/compliance meaning, +- Defender/Purview portal overlap, +- stronger redaction and customer-output controls. + +## Unsupported / Unknown Follow-Up Paths + +- Portal-only settings stay `unsupported` until official automation support is found. +- Unknown policy families stay `unknown_requires_research`. +- Teams files/storage governance belongs to SharePoint/OneDrive/PnP follow-up, not Teams policy capture. +- Microsoft cmdlets that perform operational actions rather than durable configuration reads are not target types. + +## First Spec 430 Implementation Slice + +Recommended first adapter pattern: `new_exchange_powershell_adapter`. + +Why this should come first: + +- It addresses the highest-value Exchange blocker (`transportRule`) that Spec 426/427 intentionally kept blocked. +- It proves the hardest shared constraints early: process isolation, command allowlist, fake command runner, redaction, stable source metadata, and response-shape distinction. +- It avoids depending on the preview Exchange Admin API for the first runtime proof. +- It creates a reusable but narrow command-runner pattern that the Teams PowerShell adapter can mirror only after Exchange proves the constraints. + +Spec 430 minimum scope should be: + +- Implement a read-only Exchange PowerShell adapter with no arbitrary command execution. +- Use a fake command runner in unit tests and no shell execution in unit tests. +- Capture only `transportRule`, `remoteDomain`, and one connector type if the official source shape is verified in the spec. +- Preserve workspace + managed environment + provider connection ownership. +- Create/reuse OperationRun for any real provider execution. +- Add RBAC/policy tests, provider-scope tests, redaction tests, blocked/denied/unavailable tests, and no-customer-claim tests. +- Keep UI/browser proof `N/A` unless rendered product surfaces change. + +Stop conditions for Spec 430: + +- PowerShell execution cannot be isolated safely in the container runtime. +- Least-privilege Exchange RBAC cannot be defined. +- The adapter cannot distinguish empty, denied, unsupported, unavailable, throttled, and malformed responses. +- Redaction cannot safely prevent mail/message/header/body content exposure. +- Implementation requires `tenant_id`, legacy shims, fallback readers, dual writes, or customer claims. +- Implementation needs broad Exchange/Teams/Purview/SharePoint mini-platform work. + +If both Exchange and Teams must ship in Spec 430, reduce the scope to two Exchange and two Teams types and explicitly document the extra fixture/runtime cost. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md new file mode 100644 index 00000000..1ad4daa1 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md @@ -0,0 +1,93 @@ +# Cohort Plan + +Spec 429 catalog status: documentation only. Cohort membership is implementation sequencing guidance for later specs, not runtime support or customer claim vocabulary. + +## Selection Principles + +- Include both Exchange and Teams in Cohort 1. +- Prefer tenant-level or policy-level configuration over per-user, per-mailbox, content, transcript, file, phone-number, or message surfaces. +- Prefer source surfaces with official Microsoft documentation and a plausible read-only adapter path. +- Preserve current repo truth: no Cohort 1 item is evidence-ready until a later runtime spec implements and tests a source adapter/contract. +- Keep Purview/Defender/SharePoint/OneDrive boundary items out of Cohort 1 unless a later spec explicitly shifts ownership. +- Do not select unknown, unsupported/manual-only, portal-only, beta-only certification blockers, or source-unclear types. + +## Cohort 1 Selected + +15 candidates are selected. This fits the 12-20 target guidance and includes both Exchange and Teams. + +| Order | Canonical type | Workload | Source surface class | Adapter pattern | Why selected | First blocker to clear | +| ---: | --- | --- | --- | --- | --- | --- | +| 1 | `transportRule` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | High-value mail-flow configuration; already has repo identity/redaction helper proof but no source adapter. | Implement safe Exchange PowerShell read adapter and prove no mail-content exposure. | +| 2 | `acceptedDomain` | Exchange | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | High-value domain posture; natural-key candidate and Admin API focused scenario. | Decide Admin API preview use vs PowerShell fallback; preserve blocked runtime state until proven. | +| 3 | `remoteDomain` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | External automatic reply/format/forwarding controls have governance value without mailbox-content capture. | Implement allowed `Get-RemoteDomain` style read path. | +| 4 | `organizationConfig` | Exchange | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | Tenant singleton baseline with high MSP value. | Limit to focused Admin API/PowerShell safe fields. | +| 5 | `mailboxPlan` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Configuration-oriented recipient boundary without per-mailbox explosion. | Prove least-privilege read path and source identity. | +| 6 | `inboundConnector` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Mail routing/security posture is customer-visible and operationally important. | Redact smart-host/domain/cert details appropriately. | +| 7 | `outboundConnector` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Complements inbound connector for mail-flow posture. | Redact routing and security metadata. | +| 8 | `sharingPolicy` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | External collaboration setting with meaningful review value. | Validate external-domain redaction and stable identity. | +| 9 | `appPermissionPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | High-value app governance; previously reviewed and blocked only by missing adapter. | Implement Teams PowerShell fake-runner proof and app-list redaction. | +| 10 | `appSetupPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | Pinning/install policy is high-value and pairs naturally with app permission posture. | Account for app-centric management migration state. | +| 11 | `meetingPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | High-risk meeting/recording/transcription governance; previously reviewed and blocked only by missing adapter. | Prove config-only capture and no recording/transcript/chat content. | +| 12 | `messagingPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | Core collaboration policy with high MSP review value. | Prove no message/chat content capture. | +| 13 | `teamsUpdateManagementPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | Moderate complexity and useful client governance posture. | Prove source shape and identity. | +| 14 | `teamsChannelsPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | Policy-level channel governance without channel content. | Keep separate from Graph channel inventory/content. | +| 15 | `externalAccessPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | External collaboration control is high value for customer/MSP review. | Redact external domains and cross-cloud metadata. | + +## Cohort 2 Candidates + +| Canonical type | Workload | Reason not Cohort 1 | +| --- | --- | --- | +| `transportConfig` | Exchange | Broad tenant singleton. Useful, but should follow adapter proof for rules/domains/connectors. | +| `sharedMailbox` | Exchange | Per-mailbox enumeration and PII risk; needs stricter scope/redaction review. | +| `managementRoleAssignment` | Exchange | Privileged RBAC data; requires dedicated security and audit review. | +| `tenantFederationConfiguration` | Teams | External/cross-tenant semantics overlap Entra and require additional boundary review. | +| `voiceRoute` | Teams | Voice licensing, PSTN, geography, and phone-number sensitivity make it too complex for first slice. | +| `teamsCallingPolicy` | Teams | Calling policy scope has license and emergency/voice complexity; should follow Teams policy adapter proof. | + +## Deferred Backlog + +| Canonical type | Boundary reason | +| --- | --- | +| `dlpCompliancePolicy` | Purview/Security & Compliance boundary; existing repo truth keeps it missing-contract blocked. | +| `labelPolicy` | Purview/Security & Compliance boundary. | +| `retentionCompliancePolicy` | Purview/Security & Compliance boundary and retention/customer-output sensitivity. | +| `teamsTeam` | Graph inventory/collaboration structure, not policy coverage; can explode into group/channel/file semantics. | +| `teamsChannel` | Graph channel inventory is content-adjacent and must not capture messages/files. | +| `teamsFileStorageIntegration` | SharePoint/OneDrive ownership boundary; needs separate source-surface catalog. | + +## Unsupported / Unknown + +| Category | Handling | +| --- | --- | +| Portal-only Teams or Exchange setting with no safe official automation source | `unsupported`; do not implement in Spec 430. | +| Unknown Teams/Exchange policy candidate | `unknown_requires_research`; keep blocked until official source docs and repo ownership are clear. | +| Microsoft cmdlet that performs operational action rather than durable configuration read | `unsupported_manual_only`; do not map as a target type. | + +## Recommended Spec 430 Scope + +The first runtime follow-up should not implement all 15 Cohort 1 candidates at once. + +Recommended first slice: + +1. Implement `new_exchange_powershell_adapter` as a read-only, command-allowlisted adapter with fake command-runner unit tests and no real shell execution in unit tests. +2. Use it for exactly `transportRule`, `remoteDomain`, and one connector type (`inboundConnector` or `outboundConnector`) to prove collection capture, identity, redaction, and blocked/permission-denied/source-unavailable distinctions. +3. Keep `acceptedDomain` and `organizationConfig` in the design as Admin API candidates, but do not depend on the preview Admin API for the first adapter proof unless the spec explicitly accepts preview/internal-only limits. +4. After Exchange adapter proof, implement a separate `new_teams_powershell_adapter` slice for `appPermissionPolicy`, `appSetupPolicy`, and `meetingPolicy`. + +If Spec 430 must cover both workloads in one PR, reduce the first Exchange and Teams sets to two types each and keep all other Cohort 1 items as documented follow-up. + +## No-Promotion Rule + +Cohort placement never changes: + +- coverage level +- evidence state +- support state +- claim state +- restore tier +- certification state +- customer output eligibility +- UI status +- OperationRun behavior + +Only a later runtime spec with tests may change those values. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md new file mode 100644 index 00000000..8629f592 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md @@ -0,0 +1,75 @@ +# Exchange Source Surface Catalog + +Spec 429 catalog status: documentation only. This file does not create runtime support, provider calls, evidence, OperationRuns, restore behavior, customer claims, UI, or app-side documentation lookup. + +## Source References + +Official Microsoft references reviewed for this catalog: + +- [Exchange Online PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell?view=exchange-ps) +- [App-only authentication for unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps) +- [Exchange PowerShell cmdlet module reference](https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/?view=exchange-ps) +- [Overview of the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-overview) +- [Authentication and authorization for the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-authentication) +- [Manage mail flow rules in Exchange Online](https://learn.microsoft.com/en-us/exchange/security-and-compliance/mail-flow-rules/manage-mail-flow-rules) +- [Manage accepted domains in Exchange Online](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/manage-accepted-domains/manage-accepted-domains) +- [Remote domains in Exchange Online](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/remote-domains/remote-domains) + +Repo references: + +- `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php` +- `apps/platform/app/Services/TenantConfiguration/SupportedScopeResolver.php` +- `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php` +- `apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php` +- `specs/419-m365-tcm-workload-registry-expansion/implementation-report.md` +- `specs/420-m365-generic-evidence-coverage-pack/implementation-report.md` +- `specs/422-exchange-teams-comparable-renderable-pack/implementation-report.md` +- `specs/426-exchange-teams-core-evidence-identity-readiness/implementation-report.md` +- `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md` +- `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md` + +## Current Repo Truth + +- `ResourceTypeRegistry` has registry-only Exchange planning rows for `transportRule`, `acceptedDomain`, `sharedMailbox`, `remoteDomain`, `mailboxPlan`, and `organizationConfig`. +- `SupportedScopeResolver` keeps Exchange planning scopes inactive and not customer-claimable. +- `CoverageSourceContractResolver` explicitly keeps `transportRule` and `acceptedDomain` blocked as `contract_blocked_repo_adapter_missing`; no provider call, evidence promotion, restore, certification, or customer claim is allowed. +- `CoverageIdentityStrategyRegistry` has stable candidate identity strategies for `transportRule` and `acceptedDomain`, but those strategies do not make source capture available. +- Spec 426 removed unverified Graph endpoint claims for Exchange/Teams first types. +- Spec 427 records the final source-contract state as blocked until a repo adapter/source contract exists. +- Spec 428 is prepared as fail-safe/no-op context; it is not implemented evidence. + +## Source Surface Classes + +| Source surface class | Exchange meaning | Adapter pattern | Current Spec 429 posture | +| --- | --- | --- | --- | +| `exchange_online_powershell_rest` | Exchange Online PowerShell module and REST-backed cmdlets. Broadest administrative surface for mail flow, domains, connectors, organization, sharing, mailbox plan, and related configuration. | `new_exchange_powershell_adapter` | Candidate for most Cohort 1 Exchange types. Requires app-only auth, least-privilege RBAC, command allowlist, fake command runner tests, throttling/error normalization, response serialization, and redaction. | +| `exchange_online_admin_api` | Preview REST-based administrative surface for a focused set of Exchange scenarios such as `OrganizationConfig` and `AcceptedDomain`. It is POST-only and is not a full Exchange Online PowerShell replacement. | `new_exchange_admin_api_contract` | Candidate only for accepted-domain and organization-config style reads when availability and RBAC can be proven. Preview status blocks certification/customer claims. | +| `security_compliance_powershell` | Purview/Security & Compliance PowerShell boundaries for retention, sensitivity, DLP, audit, and compliance artifacts. | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Boundary/deferred for Spec 429 Exchange catalog. Do not mix with Exchange Cohort 1 unless a later Purview spec justifies it. | +| `unsupported_manual_only` | Portal-only, unsafe, destructive, or operational-action surfaces. | `unsupported` | Excluded from Cohort 1. | +| `unknown_requires_research` | Source unclear or official docs do not support a safe capture decision. | `unsupported` until researched | Excluded from Cohort 1. | + +## Exchange Family Catalog + +| Family | Candidate target types | Source surface class | Adapter pattern | Expected object shape | Identity risk | Permission risk | Response shape risk | Redaction risk | Customer/MSP value | Cohort posture | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Mail flow and transport | `transportRule`, `transportConfig` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Mostly collections for rules plus tenant singleton/config objects. | Medium: rules have GUID-like identifiers, but display names and order are not stable identity. | High: mail-flow roles are sensitive and changes can affect message routing. | Medium: conditions/actions/exceptions are nested and order-sensitive. | High: rules can contain subject/body/header/disclaimer patterns. | High customer and MSP value because mail-flow rules are critical configuration. | `transportRule` is Cohort 1 selected; `transportConfig` is Cohort 2. | +| Domains and connectors | `acceptedDomain`, `remoteDomain`, `inboundConnector`, `outboundConnector` | `exchange_online_admin_api` for accepted-domain/org reads where safe; otherwise `exchange_online_powershell_rest`. | `new_exchange_admin_api_contract` or `new_exchange_powershell_adapter` | Collections keyed by domain/connector identifiers; connector objects include routing/security settings. | Low to medium: domain names can be natural keys; connector names are display-like and need source IDs. | Medium/high: domain and connector reads reveal mail routing posture. | Medium: connector shapes vary and may contain endpoint details. | Medium: connectors may include smart-host and organization routing data. | High value for migration, mail-flow, and MSP posture review. | `acceptedDomain`, `remoteDomain`, `inboundConnector`, and `outboundConnector` are Cohort 1 selected. | +| Organization configuration | `organizationConfig`, `transportConfig` | `exchange_online_admin_api` where the focused API covers it; otherwise `exchange_online_powershell_rest`. | `new_exchange_admin_api_contract` or `new_exchange_powershell_adapter` | Tenant singleton settings. | Low: singleton identity can derive from workspace + managed environment + provider connection + canonical type. | Medium/high: broad organization roles may be required. | Medium: singleton fields can be large and version-dependent. | Medium: org settings can contain domains and routing hints. | High value for baseline and drift review. | `organizationConfig` is Cohort 1 selected; broader config is Cohort 2. | +| Sharing and relationship configuration | `sharingPolicy`, `organizationRelationship`, `availabilityAddressSpace` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Collections with policy/relationship objects. | Medium: names are not enough; source IDs or stable composite keys needed. | Medium: external sharing configuration is sensitive. | Medium: external-org fields and federation state vary. | Medium: partner domain and relationship metadata need redaction discipline. | Medium/high value for external collaboration posture. | `sharingPolicy` is Cohort 1 selected; relationship variants are Cohort 2. | +| Protection and hygiene boundary | `antiPhishPolicy`, `antiSpamPolicy`, `safeLinksPolicy`, `malwareFilterPolicy` | `security_compliance_powershell` or Exchange-adjacent cmdlets depending on exact object. | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Collections of policy objects and rules. | Medium/high: policy and rule identity can be split. | High: Defender/Purview permissions may exceed Exchange least privilege. | High: policy/rule joins and portal behavior can be complex. | High: rule conditions may include domains, senders, subjects, or content patterns. | High value, but boundary risk is high. | Deferred to Purview/Defender boundary work. | +| Recipient and mailbox boundary | `sharedMailbox`, `mailboxPlan`, `mailboxFolderPermission`, `sendOnBehalfDelegation` | `exchange_online_powershell_rest`; Admin API only for focused mailbox/folder/delegation scenarios. | `new_exchange_powershell_adapter` or `new_exchange_admin_api_contract` | Collections or per-mailbox data; high cardinality risk for mailbox-scoped objects. | Medium/high: mailbox and permission identities need stable source IDs. | High: recipient/mailbox roles are broad and can expose user data. | High for per-mailbox enumeration and paging. | Critical for mailbox content-adjacent permissions and PII. | Mixed: mailbox plan high for governance; per-mailbox data needs stronger scope. | `mailboxPlan` is Cohort 1 selected; `sharedMailbox` and per-mailbox permissions are Cohort 2/deferred. | +| Role assignment and admin audit | `managementRoleAssignment`, `adminAuditLogConfig` | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Collections for assignments; singleton for audit config. | Medium: role assignment identity can be composite. | Critical: role/admin audit data is highly sensitive. | Medium/high: assignments may reference users/groups/service principals. | High: role assignments include principals and privileged admin metadata. | High operator value but high security review cost. | Cohort 2 or deferred until RBAC/audit redaction is separately reviewed. | +| Purview/Security & Compliance boundary | `labelPolicy`, `retentionCompliancePolicy`, `dlpCompliancePolicy`, `autoSensitivityLabelPolicy`, `protectionAlert`, `complianceTag` | `security_compliance_powershell` | `new_security_compliance_adapter` or `defer_to_purview_adapter` | Collections, sometimes policy/rule pairs. | Medium/high. | Critical: compliance roles and content-sensitive policy scope. | High: workloads and portals overlap. | Critical: compliance data can contain sensitive labels/rules. | High future value; not Exchange Cohort 1. | Deferred; requires a Purview/Security & Compliance adapter strategy. | + +## Exchange Cohort Guidance + +Cohort 1 should use Exchange Online PowerShell as the first practical Exchange source surface, with Exchange Admin API treated as a narrow optional path for `acceptedDomain` and `organizationConfig` if preview availability and RBAC are acceptable. Cohort 1 must still start blocked in runtime until Spec 430 implements an adapter and tests it with a fake command/API runner. It must not infer Graph availability from display aliases such as `mailFlowRule` or `acceptedDomains`. + +## Forbidden Source Authority Rules + +- Do not treat Microsoft Learn examples as runtime contracts. +- Do not create Graph contracts for Exchange target types unless official Graph availability and repo contract shape are proven in a later spec. +- Do not use Exchange Admin API as a full Exchange Online PowerShell replacement. +- Do not execute shell commands in unit tests. +- Do not store certificates, private keys, client secrets, access tokens, raw provider responses, mail content, or message content in catalog artifacts, audit metadata, OperationRun context, or default-visible output. +- Do not treat `tenant_id` as platform-core ownership truth; later runtime records must use workspace + managed environment + provider connection boundaries. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md new file mode 100644 index 00000000..2a58a0e0 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md @@ -0,0 +1,62 @@ +# Exchange/Teams Target Type Matrix + +Spec 429 catalog status: documentation only. The values in this matrix are not runtime enums, not persisted states, and not claim vocabulary. + +Allowed documentation-only values are exactly those listed in `spec.md` FR-429-009 through FR-429-013. + +## Matrix + +| Canonical type | Human label | Workload | Admin area | Source surface class | Adapter pattern | Source reference | Expected object shape | Singleton/collection | Identity candidate | Identity risk | Permission risk | Response shape risk | Redaction risk | Compare complexity | Render complexity | Customer value | MSP value | Cohort | Status | Blocker reason | Notes | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `transportRule` | Transport rule | Exchange | Mail flow | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange Online PowerShell; mail flow rules docs; repo Specs 426/427 | Rule with conditions, actions, exceptions, priority, mode/state | collection | `id`, `sourceId`, `Guid`, `RuleId` | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Current repo state remains `contract_blocked_repo_adapter_missing`. | Previously reviewed target; no Graph endpoint guessing allowed. | +| `acceptedDomain` | Accepted domain | Exchange | Domains | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | Exchange Admin API overview; accepted domains docs; repo Specs 420/426/427 | Domain object with domain type/default flag/state | collection | `id`, `sourceId`, `DomainName`, `domainName` | `low` | `medium` | `medium` | `medium` | `moderate` | `simple` | high | high | Cohort 1 | `cohort_1_selected` | Current repo state remains `contract_blocked_repo_adapter_missing`. | Admin API is preview and focused; PowerShell remains fallback candidate. | +| `remoteDomain` | Remote domain | Exchange | Domains | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Remote domains docs; Exchange PowerShell module | Remote-domain configuration controlling external message behavior | collection | `id`, `sourceId`, `DomainName`, `domainName` | `medium` | `medium` | `medium` | `medium` | `moderate` | `simple` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Valuable for external mail-flow posture; no runtime support now. | +| `organizationConfig` | Organization configuration | Exchange | Organization | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | Exchange Admin API overview; Exchange PowerShell module | Tenant singleton organization settings | singleton | workspace + managed environment + provider connection + canonical type | `low` | `high` | `medium` | `medium` | `moderate` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Admin API may cover a focused subset only; preview blocks claims. | +| `mailboxPlan` | Mailbox plan | Exchange | Recipient/mailbox boundary | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module; repo Spec 419 | Mailbox-plan configuration objects | collection | `id`, `sourceId`, plan GUID/name if source-backed | `medium` | `medium` | `medium` | `medium` | `moderate` | `simple` | medium | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Safer than per-mailbox enumeration because it is plan/config oriented. | +| `inboundConnector` | Inbound connector | Exchange | Connectors | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module; connector docs referenced by accepted-domain docs | Connector object with routing/security settings | collection | `id`, `sourceId`, connector GUID if available | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Smart hosts, domains, cert names, and TLS settings need redaction review. | +| `outboundConnector` | Outbound connector | Exchange | Connectors | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module; connector docs referenced by accepted-domain docs | Connector object with routing/security settings | collection | `id`, `sourceId`, connector GUID if available | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | High customer value but requires strict mail-routing redaction. | +| `sharingPolicy` | Sharing policy | Exchange | Sharing/relationships | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module | Policy object with domains/actions | collection | `id`, `sourceId`, policy GUID if available | `medium` | `medium` | `medium` | `medium` | `moderate` | `simple` | medium | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | External collaboration posture without mailbox-content capture. | +| `transportConfig` | Transport configuration | Exchange | Mail flow | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module | Tenant singleton transport settings | singleton | workspace + managed environment + provider connection + canonical type | `low` | `high` | `medium` | `medium` | `moderate` | `moderate` | high | high | Cohort 2 | `cohort_2_candidate` | Keep after rule/domain/connector adapter proof. | Broad tenant config; good second-wave candidate. | +| `sharedMailbox` | Shared mailbox | Exchange | Recipient/mailbox boundary | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module; repo Spec 419 | Mailbox collection | collection | `id`, `sourceId`, mailbox external ID | `medium` | `high` | `high` | `critical` | `very_complex` | `complex` | medium | medium | Cohort 2 | `cohort_2_candidate` | Per-mailbox enumeration and PII risk. | Do not include in first adapter slice. | +| `managementRoleAssignment` | Management role assignment | Exchange | RBAC/admin | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | Exchange PowerShell module | Role/principal assignment collection | collection | assignment ID or role+principal composite | `medium` | `critical` | `high` | `high` | `complex` | `moderate` | high | high | Cohort 2 | `cohort_2_candidate` | Privileged RBAC data requires separate security review. | High operator value but not first slice. | +| `dlpCompliancePolicy` | DLP compliance policy | Security and Compliance | Purview boundary | `security_compliance_powershell` | `defer_to_purview_adapter` | App-only auth docs; repo Specs 420/428 | Policy/rule collections | collection | source ID if Purview adapter exists | `high` | `critical` | `high` | `critical` | `very_complex` | `complex` | high | high | Deferred | `blocked_purview_boundary` | Purview/Security & Compliance boundary, not Exchange Cohort 1. | Current repo already blocks this as missing contract. | +| `labelPolicy` | Label policy | Security and Compliance | Purview boundary | `security_compliance_powershell` | `defer_to_purview_adapter` | Repo Spec 419; app-only auth docs | Policy/rule collections | collection | source ID if Purview adapter exists | `high` | `critical` | `high` | `critical` | `very_complex` | `complex` | high | high | Deferred | `blocked_purview_boundary` | Purview/Security & Compliance boundary. | Separate Purview catalog/adapter strategy required. | +| `retentionCompliancePolicy` | Retention compliance policy | Security and Compliance | Purview boundary | `security_compliance_powershell` | `defer_to_purview_adapter` | Repo Spec 419; app-only auth docs | Policy/rule collections | collection | source ID if Purview adapter exists | `high` | `critical` | `high` | `critical` | `very_complex` | `complex` | high | high | Deferred | `blocked_purview_boundary` | Retention/customer-output sensitivity requires separate Purview review. | Separate Purview catalog/adapter strategy required. | +| `appPermissionPolicy` | App permission policy | Teams | App governance | `teams_powershell` | `new_teams_powershell_adapter` | Teams app permission docs; Teams PowerShell module; repo Specs 420/426/427 | Policy object with app allow/block mode and app lists | collection | `id`, `sourceId`, `policyId` | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Current repo state remains `contract_blocked_repo_adapter_missing`. | App-centric management migration state must be recognized. | +| `appSetupPolicy` | App setup policy | Teams | App governance | `teams_powershell` | `new_teams_powershell_adapter` | Teams app setup docs; Teams PowerShell module; repo Spec 419 | Policy object with pinned/installed apps and upload controls | collection | `id`, `sourceId`, `policyId` | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Pinning respects app permission controls; render must avoid raw app IDs by default. | +| `meetingPolicy` | Meeting policy | Teams | Meetings/events | `teams_powershell` | `new_teams_powershell_adapter` | Teams settings/policies reference; Teams PowerShell module; repo Specs 426/427 | Policy object with meeting, lobby, recording, transcription settings | collection | `id`, `sourceId`, `policyId` | `medium` | `high` | `medium` | `critical` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Current repo state remains `contract_blocked_repo_adapter_missing`. | Must never capture recordings, transcripts, or chat content. | +| `messagingPolicy` | Messaging policy | Teams | Messaging/channels | `teams_powershell` | `new_teams_powershell_adapter` | Teams settings/policies reference; Teams PowerShell module; repo Spec 419 | Policy object controlling message/chat capabilities | collection | `id`, `sourceId`, `policyId` | `medium` | `medium` | `medium` | `high` | `moderate` | `simple` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Policy settings only; no message content. | +| `teamsUpdateManagementPolicy` | Teams update management policy | Teams | Client/update governance | `teams_powershell` | `new_teams_powershell_adapter` | Teams PowerShell module; repo Spec 419 | Policy object | collection | `id`, `sourceId`, `policyId` | `medium` | `medium` | `medium` | `medium` | `moderate` | `simple` | medium | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Moderate risk and good policy coverage value. | +| `teamsChannelsPolicy` | Teams channels policy | Teams | Messaging/channels | `teams_powershell` | `new_teams_powershell_adapter` | Teams PowerShell module; Teams settings/policies reference | Policy object for channels experience | collection | `id`, `sourceId`, `policyId` | `medium` | `medium` | `medium` | `medium` | `moderate` | `simple` | medium | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | Keep separate from Graph channel content/inventory. | +| `externalAccessPolicy` | External access policy | Teams | External/guest access | `teams_powershell` | `new_teams_powershell_adapter` | Guest/external access docs; Teams PowerShell module | Policy or tenant-level external communication settings | collection | `id`, `sourceId`, `policyId` | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 1 | `cohort_1_selected` | Missing repo adapter/source contract. | External domains and cross-cloud settings require redaction. | +| `tenantFederationConfiguration` | Tenant federation configuration | Teams | External/guest access | `teams_powershell` | `new_teams_powershell_adapter` | Guest/external access docs; Teams PowerShell module | Tenant singleton or small collection | singleton | workspace + managed environment + provider connection + canonical type | `medium` | `high` | `medium` | `high` | `complex` | `moderate` | high | high | Cohort 2 | `cohort_2_candidate` | Cross-tenant and external-domain semantics need separate review. | Defer behind first Teams policy adapter proof. | +| `voiceRoute` | Voice route | Teams | Calling/voice | `teams_powershell` | `new_teams_powershell_adapter` | Teams PowerShell module; repo Spec 419 | Voice route collection | collection | `id`, `sourceId`, route identity | `medium` | `high` | `high` | `medium` | `complex` | `moderate` | medium | high | Cohort 2 | `cohort_2_candidate` | Voice licensing/geography/phone-number complexity. | Registry-only planning row today. | +| `teamsCallingPolicy` | Teams calling policy | Teams | Calling/voice | `teams_powershell` | `new_teams_powershell_adapter` | Teams PowerShell module; Teams settings/policies reference | Calling policy collection | collection | `id`, `sourceId`, `policyId` | `medium` | `high` | `high` | `medium` | `complex` | `moderate` | medium | high | Cohort 2 | `cohort_2_candidate` | Calling policy scope has license and emergency/voice complexity. | Follow Teams policy adapter proof; not a first-slice target. | +| `teamsTeam` | Team inventory | Teams | Teams/groups | `graph_v1` | `new_graph_contract` | Microsoft Graph Teams overview | Team/group collection | collection | Graph team/group ID | `low` | `medium` | `medium` | `high` | `moderate` | `moderate` | medium | medium | Deferred | `deferred` | This is inventory/collaboration structure, not policy governance. | Files live in SharePoint; chat messages are forbidden. | +| `teamsChannel` | Channel inventory | Teams | Messaging/channels | `graph_v1` | `new_graph_contract` | Microsoft Graph Teams overview | Channel collection under teams | collection | Graph channel ID scoped to team ID | `medium` | `medium` | `high` | `critical` | `complex` | `moderate` | low | medium | Deferred | `deferred` | Channel content/files boundary is unsafe for Cohort 1. | Do not capture messages, files, tabs with secrets, or transcripts. | +| `teamsFileStorageIntegration` | Teams file/storage integration | Teams/SharePoint | Files/storage boundary | `sharepoint_pnp_related` | `unsupported` | Microsoft Graph Teams overview; Teams settings/policies reference | Cross-workload storage settings and file locations | collection | SharePoint/OneDrive source ID required | `high` | `critical` | `high` | `critical` | `very_complex` | `complex` | medium | medium | Deferred | `blocked_identity_unsafe` | Source truth belongs to SharePoint/OneDrive boundary. | Separate SharePoint/OneDrive source-surface catalog required. | +| `portalOnlyTeamsSetting` | Portal-only Teams setting | Teams | Unknown/manual | `unsupported_manual_only` | `unsupported` | Teams admin center references only | Unknown | singleton | unknown | `unknown` | `unknown` | `unknown` | `unknown` | `unknown` | `unknown` | low | low | Unsupported | `unsupported` | No official automation surface verified. | Placeholder category only; not a target for Spec 430. | +| `unknownTeamsPolicy` | Unknown Teams policy | Teams | Unknown | `unknown_requires_research` | `unsupported` | None verified | Unknown | collection | unknown | `unknown` | `unknown` | `unknown` | `unknown` | `unknown` | `unknown` | unknown | unknown | Unknown | `unknown_requires_research` | Needs official source research. | Must stay blocked rather than guessed. | + +## Summary Counts + +| Group | Count | +| --- | ---: | +| Cohort 1 selected | 15 | +| Cohort 2 candidate | 6 | +| Deferred | 6 | +| Unsupported | 1 | +| Unknown/research required | 1 | + +## Current Repo Blocker Preservation + +The matrix intentionally keeps the four previously reviewed target types blocked in runtime: + +| Type | Current repo blocker | +| --- | --- | +| `transportRule` | `contract_blocked_repo_adapter_missing` / `capture_blocked_missing_contract` | +| `acceptedDomain` | `contract_blocked_repo_adapter_missing` / `capture_blocked_missing_contract` | +| `appPermissionPolicy` | `contract_blocked_repo_adapter_missing` / `capture_blocked_missing_contract` | +| `meetingPolicy` | `contract_blocked_repo_adapter_missing` / `capture_blocked_missing_contract` | + +Selecting them for Cohort 1 means they are candidates for a later adapter implementation spec. It does not mean TenantPilot supports them now. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md new file mode 100644 index 00000000..568909d8 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md @@ -0,0 +1,74 @@ +# Teams Source Surface Catalog + +Spec 429 catalog status: documentation only. This file does not create runtime support, provider calls, evidence, OperationRuns, restore behavior, customer claims, UI, or app-side documentation lookup. + +## Source References + +Official Microsoft references reviewed for this catalog: + +- [MicrosoftTeams PowerShell module reference](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/?view=teams-ps) +- [Connect-MicrosoftTeams](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/connect-microsoftteams?view=teams-ps) +- [Application-based authentication in Teams PowerShell Module](https://learn.microsoft.com/en-us/microsoftteams/teams-powershell-application-authentication) +- [Use app permission policies to control user access to apps](https://learn.microsoft.com/en-us/microsoftteams/teams-app-permission-policies) +- [Use setup policies to manage, install and pin agents and apps for users](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies) +- [Teams settings and policies reference](https://learn.microsoft.com/en-us/microsoftteams/settings-policies-reference) +- [Use guest access and external access to collaborate with people outside your organization](https://learn.microsoft.com/en-us/microsoftteams/communicate-with-users-from-other-organizations) +- [Use the Microsoft Graph API to work with Microsoft Teams](https://learn.microsoft.com/en-us/graph/api/resources/teams-api-overview?view=graph-rest-1.0) + +Repo references: + +- `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php` +- `apps/platform/app/Services/TenantConfiguration/SupportedScopeResolver.php` +- `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php` +- `apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php` +- `specs/419-m365-tcm-workload-registry-expansion/implementation-report.md` +- `specs/420-m365-generic-evidence-coverage-pack/implementation-report.md` +- `specs/422-exchange-teams-comparable-renderable-pack/implementation-report.md` +- `specs/426-exchange-teams-core-evidence-identity-readiness/implementation-report.md` +- `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md` +- `specs/428-exchange-teams-content-backed-evidence-promotion/spec.md` + +## Current Repo Truth + +- `ResourceTypeRegistry` has registry-only Teams planning rows for `appPermissionPolicy`, `appSetupPolicy`, `meetingPolicy`, `messagingPolicy`, `teamsUpdateManagementPolicy`, and `voiceRoute`. +- `SupportedScopeResolver` keeps Teams planning scopes inactive and not customer-claimable. +- `CoverageSourceContractResolver` explicitly keeps `appPermissionPolicy` and `meetingPolicy` blocked as `contract_blocked_repo_adapter_missing`; no provider call, evidence promotion, restore, certification, or customer claim is allowed. +- `CoverageIdentityStrategyRegistry` has stable candidate identity strategies for `appPermissionPolicy` and `meetingPolicy`, but those strategies do not make source capture available. +- Spec 422 can compare/render selected Teams payload shapes only when content-backed evidence exists. It does not prove live capture. +- Spec 428 is prepared as fail-safe/no-op context; it is not implemented evidence. + +## Source Surface Classes + +| Source surface class | Teams meaning | Adapter pattern | Current Spec 429 posture | +| --- | --- | --- | --- | +| `teams_powershell` | MicrosoftTeams PowerShell module policy/configuration cmdlets. Application-based authentication is supported with caveats and documented unsupported cmdlets. | `new_teams_powershell_adapter` | Primary Teams policy source candidate. Requires app-based auth, Teams RBAC role assignment, command allowlist, fake command runner tests, response serialization, throttling/error handling, and redaction. | +| `graph_v1` | Microsoft Graph Teams resources for teams, channels, tabs, app installations, chats, online meetings, call records, and related collaboration resources. | `new_graph_contract` or `existing_graph_client_contract` | Useful for teams/channels/app-installation inventory, but not sufficient for all Teams policy governance. Any use must go through `GraphClientInterface` and `config/graph_contracts.php` in a later spec. | +| `graph_beta_experimental` | Microsoft Graph beta-only Teams resources. | `new_graph_contract` only after beta risk review | Excluded from certification/customer claims and Cohort 1 unless a later spec explicitly accepts internal-only beta capture. | +| `sharepoint_pnp_related` | Teams file governance and channel files where source truth lives in SharePoint/OneDrive. | `unsupported` for this spec; likely separate SharePoint/OneDrive/PnP strategy later | Deferred boundary. Do not present as Teams policy support. | +| `unsupported_manual_only` | Portal-only, operational, end-user content, or unsafe actions. | `unsupported` | Excluded from Cohort 1. | +| `unknown_requires_research` | Source unclear or official docs do not support a safe capture decision. | `unsupported` until researched | Excluded from Cohort 1. | + +## Teams Family Catalog + +| Family | Candidate target types | Source surface class | Adapter pattern | Expected object shape | Identity risk | Permission risk | Response shape risk | Redaction risk | Customer/MSP value | Cohort posture | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| App governance | `appPermissionPolicy`, `appSetupPolicy`, `teamsAppSettings`, app-centric management state | `teams_powershell` for policies; `graph_v1` may cover app catalog/installations but not all policy state. | `new_teams_powershell_adapter` plus later Graph contracts where proven. | Collections of policy objects, plus tenant singleton settings. | Medium: policy IDs/source IDs required; display names are not enough. | High: Teams administrator/application permissions and directory roles can be broad. | Medium/high: app-centric management can supersede legacy policy meaning. | High: app lists, app IDs, and catalog metadata need safe summaries. | High value for app governance and MSP reviews. | `appPermissionPolicy` and `appSetupPolicy` are Cohort 1 selected. App-centric management is Cohort 2/unknown until source clarity improves. | +| Meetings and events | `meetingPolicy`, `meetingConfiguration`, live events/town hall policies | `teams_powershell` | `new_teams_powershell_adapter` | Collections plus possible singleton tenant settings. | Medium: policy IDs/source IDs required. | High: meeting/recording/transcription controls are sensitive. | Medium: settings vary by feature availability and license. | Critical: recordings, transcripts, chat/message content must never be captured or rendered as config evidence. | High value for collaboration risk posture. | `meetingPolicy` is Cohort 1 selected; event-specific variants are Cohort 2. | +| Messaging and channels | `messagingPolicy`, `teamsChannelsPolicy`, `teamsClientConfiguration` | `teams_powershell`; Graph teams/channels APIs are inventory surfaces, not a replacement for policy capture. | `new_teams_powershell_adapter` or later `new_graph_contract` for team/channel inventory only. | Policy collections and tenant singleton settings. | Medium. | Medium/high: communication controls affect user collaboration. | Medium: policy settings can expand over time. | High: message content, chat content, attachments, and transcripts are forbidden evidence. | High for policy posture, lower for raw channel inventory. | `messagingPolicy` and `teamsChannelsPolicy` are Cohort 1 selected; team/channel inventory is deferred. | +| Calling and voice | `voiceRoute`, `onlineVoiceRoutingPolicy`, `teamsCallingPolicy`, `callParkPolicy`, phone-number configuration | `teams_powershell` | `new_teams_powershell_adapter` | Collections and tenant-level voice configuration. | Medium/high: voice routes and policies may use composite identity. | High: licensing, PSTN, phone-number, and emergency-calling permissions can be broad. | High: tenant readiness varies by license/geography. | Medium/high: phone-number and routing data can be sensitive. | Medium/high value, but complexity is high. | `voiceRoute` and calling policies are Cohort 2, not Cohort 1. | +| External and guest access | `externalAccessPolicy`, `tenantFederationConfiguration`, `guestMeetingConfiguration`, guest/external collaboration settings | `teams_powershell` and Microsoft 365/Entra boundary references. | `new_teams_powershell_adapter`; some pieces may require Entra or cross-workload follow-up. | Singleton plus policy collections. | Medium. | High: external collaboration posture is sensitive. | Medium: some controls overlap Entra cross-tenant access or Microsoft 365 admin center settings. | Medium/high: external domains and tenant identifiers need redaction discipline. | High customer and MSP value. | `externalAccessPolicy` is Cohort 1 selected; federation/guest variants are Cohort 2. | +| Files, storage, and integration boundary | Teams channel files, cloud storage providers, tabs, connectors, app installations | `graph_v1` for Teams entities; `sharepoint_pnp_related` for files; possible app catalog Graph surfaces. | `new_graph_contract`, `unsupported`, or future SharePoint/PnP adapter. | Teams/channel/app collections; files live in SharePoint. | Medium/high: Teams group/team/channel IDs are stable but file identity belongs elsewhere. | High: file/storage permissions cross workloads. | High: SharePoint/OneDrive ownership and paging are separate domains. | Critical: file contents and message attachments are forbidden. | Medium for inventory, high for future governance, but not safe Cohort 1. | Deferred to SharePoint/OneDrive or Teams Graph inventory spec. | + +## Teams Cohort Guidance + +Cohort 1 should focus on tenant and policy objects that Teams PowerShell can read without touching user content, file content, chat messages, meeting recordings, transcripts, or per-user explosion paths. Microsoft Graph should be used only for Teams entities where the official Graph resource is the actual source of truth and the later implementation goes through the existing Graph client contract path. + +## Forbidden Source Authority Rules + +- Do not treat Teams admin center UI instructions as runtime source contracts. +- Do not capture Teams chat, message, file, recording, transcript, or meeting content as configuration evidence. +- Do not use Graph Teams APIs to imply Teams policy coverage when the policy source is Teams PowerShell. +- Do not use app-centric management or unified app management wording as a claim until a later spec proves the source and migration semantics. +- Do not execute shell commands in unit tests. +- Do not store certificates, private keys, client secrets, access tokens, raw provider responses, chat content, meeting content, file content, or transcripts in catalog artifacts, audit metadata, OperationRun context, or default-visible output. +- Do not treat `tenant_id` as platform-core ownership truth; later runtime records must use workspace + managed environment + provider connection boundaries. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/checklists/requirements.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/checklists/requirements.md new file mode 100644 index 00000000..9b35ba60 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/checklists/requirements.md @@ -0,0 +1,138 @@ +# Requirements Checklist: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy + +**Purpose**: Validate catalog/strategy preparation completeness before implementation. +**Created**: 2026-07-04 +**Feature**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md` + +This checklist is a preparation gate only. The catalog implementation loop must re-review it after the catalog artifacts and implementation report exist; this preparation PASS is not catalog implementation completion. + +## Scope + +- [x] Catalog/strategy only. +- [x] No runtime adapter implementation. +- [x] No provider calls. +- [x] No evidence. +- [x] No OperationRun. +- [x] No compare/render promotion. +- [x] No certification. +- [x] No restore. +- [x] No customer claims. +- [x] No UI. +- [x] Spec 428 is treated as prepared fail-safe/no-op context, not implemented evidence. + +## Exchange Catalog + +- [x] Mail flow / transport catalog requirement defined. +- [x] Domains/connectors catalog requirement defined. +- [x] Organization configuration catalog requirement defined. +- [x] Sharing/relationship configuration catalog requirement defined. +- [x] Protection/hygiene boundary catalog requirement defined. +- [x] Mailbox/recipient boundary catalog requirement defined. +- [x] Purview/Security & Compliance boundary catalog requirement defined. + +## Teams Catalog + +- [x] App governance catalog requirement defined. +- [x] Meetings/events catalog requirement defined. +- [x] Messaging/channels catalog requirement defined. +- [x] Calling/voice catalog requirement defined. +- [x] External/guest access catalog requirement defined. +- [x] Files/storage/integration boundary catalog requirement defined. + +## Target Type Matrix + +- [x] Canonical type field required. +- [x] Workload field required. +- [x] Source surface class field required. +- [x] Adapter pattern field required. +- [x] Identity risk field required. +- [x] Permission risk field required. +- [x] Response shape risk field required. +- [x] Redaction risk field required. +- [x] Compare/render complexity fields required. +- [x] Customer/MSP value fields required. +- [x] Cohort/status fields required. +- [x] Documentation-only allowed values listed in the spec. + +## Cohort Plan + +- [x] Cohort 1 selection required. +- [x] Cohort 1 approximately 12-20 types or exception documented. +- [x] Cohort 2 required. +- [x] Deferred backlog required. +- [x] Unsupported/unknown backlog required. +- [x] Selection rationale required. + +## Adapter Strategy + +- [x] Graph-native path required. +- [x] Exchange Admin API path required. +- [x] Exchange PowerShell adapter path required. +- [x] Teams PowerShell adapter path required. +- [x] Security & Compliance boundary required. +- [x] Redaction/testability requirements required. +- [x] First Spec 430 implementation slice required. + +## No Runtime Impact + +- [x] No services. +- [x] No provider clients. +- [x] No migrations. +- [x] No routes/views/pages. +- [x] No jobs/commands. +- [x] No runtime registry consumption. +- [x] No `tenant_id`. +- [x] No tests unless optional static JSON validation is added later. + +## Claims + +- [x] No Exchange evidence claim. +- [x] No Teams evidence claim. +- [x] No M365 readiness claim. +- [x] No compare/render claim. +- [x] No certification claim. +- [x] No restore claim. +- [x] No customer-ready claim. + +## Validation + +- [x] `git diff --check` planned. +- [x] `git status --short` documentation planned. +- [x] Catalog artifact existence checks planned. +- [x] Implementation report completion planned. +- [x] Browser smoke marked N/A unless UI changed. + +## Preparation Quality + +- [x] No `[NEEDS CLARIFICATION]` markers remain. +- [x] Requirements are testable and unambiguous. +- [x] Success criteria are measurable. +- [x] Acceptance scenarios are defined. +- [x] Edge cases are identified. +- [x] Scope is clearly bounded. +- [x] Dependencies and assumptions identified. + +## Final Candidate Gate + +**Result**: PASS for preparation. + +PASS rationale: + +- The selected candidate is directly provided by the user and has no existing Spec 429 package. +- Related completed specs are read-only context. +- Spec 428 is not treated as implemented evidence. +- Spec/plan/tasks define catalog implementation without runtime work. +- No application implementation was performed during preparation. + +## Catalog Implementation Re-Review + +**Result**: PASS for docs/catalog implementation. + +PASS rationale: + +- Required catalog artifacts now exist under `catalog/`. +- `implementation-report.md` records the target summary, Cohort 1 matrix, adapter strategy matrix, no-runtime proof, no-promotion proof, Product Surface close-out, and validation commands. +- Cohort 1 includes both Exchange and Teams and stays within the 12-20 guidance. +- `transportRule`, `acceptedDomain`, `appPermissionPolicy`, and `meetingPolicy` remain documented as runtime-blocked by missing repo adapter/source contracts. +- No application runtime, UI, provider call, evidence, OperationRun, restore, certification, customer output, or `tenant_id` work was added. +- Browser proof remains `N/A - no rendered UI surface changed`. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md new file mode 100644 index 00000000..2366ee78 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md @@ -0,0 +1,150 @@ +# Implementation Report: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy + +## Preflight + +- **Active spec**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/` +- **Branch**: `429-exchange-teams-source-surface-catalog-adapter-strategy` +- **HEAD before implementation**: `a9818537 spec: add Exchange Teams content-backed evidence promotion (#495)` +- **Initial dirty state**: untracked active spec package only: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`. +- **Activated skills/gates**: + - `spec-kit-implementation-loop`: requested implementation loop. + - `.agent/workflows/spec-readiness-gate`: active Spec Kit implementation readiness check. +- **Hard-gate stop conditions checked**: no unrelated dirty files; no runtime/UI/provider/evidence/customer-output/OperationRun work required; no completed spec rewrite; no `tenant_id`, legacy adapter, fallback reader, dual write, runtime registry consumption, provider call, evidence promotion, compare/render promotion, certification, restore, report, Review Pack/PDF output, or customer claim required. + +## Completed-Spec Guardrail + +Specs 414, 415, 417, 419, 420, 422, 426, and 427 were used as read-only dependency context. No completed historical spec directory was edited. + +Spec 428 is a prepared fail-safe/no-op package and remains non-blocking for Spec 429 because this implementation is catalog/strategy only and does not consume evidence or promote capture. + +## Implementation Summary + +Created the static catalog package: + +- `catalog/exchange-source-surface-catalog.md` +- `catalog/teams-source-surface-catalog.md` +- `catalog/exchange-teams-target-type-matrix.md` +- `catalog/cohort-plan.md` +- `catalog/adapter-strategy.md` + +No application runtime files were changed. + +## Target Type Summary + +| Group | Count | Notes | +| --- | ---: | --- | +| Cohort 1 selected | 15 | Both Exchange and Teams represented; all remain runtime-blocked until a later adapter spec. | +| Cohort 2 candidate | 6 | Valuable but higher risk, broader, or better sequenced after adapter proof. | +| Deferred | 6 | Purview/Security & Compliance, Graph inventory, and SharePoint/OneDrive boundary work. | +| Unsupported | 1 | Portal/manual-only placeholder category. | +| Unknown/research required | 1 | Kept blocked instead of guessed. | + +## Cohort 1 Matrix + +| Canonical type | Workload | Source surface class | Adapter pattern | Current runtime claim | +| --- | --- | --- | --- | --- | +| `transportRule` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none; blocked by missing repo adapter/source contract | +| `acceptedDomain` | Exchange | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | none; blocked by missing repo adapter/source contract | +| `remoteDomain` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none | +| `organizationConfig` | Exchange | `exchange_online_admin_api` | `new_exchange_admin_api_contract` | none | +| `mailboxPlan` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none | +| `inboundConnector` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none | +| `outboundConnector` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none | +| `sharingPolicy` | Exchange | `exchange_online_powershell_rest` | `new_exchange_powershell_adapter` | none | +| `appPermissionPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none; blocked by missing repo adapter/source contract | +| `appSetupPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none | +| `meetingPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none; blocked by missing repo adapter/source contract | +| `messagingPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none | +| `teamsUpdateManagementPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none | +| `teamsChannelsPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none | +| `externalAccessPolicy` | Teams | `teams_powershell` | `new_teams_powershell_adapter` | none | + +## Adapter Strategy Matrix + +| Adapter pattern | Spec 429 decision | +| --- | --- | +| `new_exchange_powershell_adapter` | Recommended first Spec 430 runtime path. | +| `new_exchange_admin_api_contract` | Candidate for accepted-domain/organization-config scenarios only; preview status blocks claims. | +| `new_teams_powershell_adapter` | Recommended second slice or reduced paired slice after Exchange adapter proof. | +| `new_graph_contract` / `existing_graph_client_contract` | Deferred to Graph-native Teams inventory or app-installation work where official Graph source exists. | +| `new_security_compliance_adapter` / `defer_to_purview_adapter` | Deferred to Purview/Security & Compliance boundary strategy. | +| `unsupported` | Used for portal-only, unknown, and SharePoint/OneDrive boundary cases until separate source truth exists. | + +## No-Runtime Matrix + +| Guard | Result | +| --- | --- | +| No files outside Spec 429 package changed | Passed. Final staged/dirty state is limited to the active Spec 429 package. | +| No application services/provider clients changed | Passed. `git status --short -- apps/platform/app apps/platform/config apps/platform/database apps/platform/resources apps/platform/routes apps/platform/tests` returned no output. | +| No migrations/models/jobs/commands/policies/routes/views/tests changed | Passed. No `apps/platform/...` path has a diff. | +| No runtime config consumed by app changed | Passed. No runtime config path changed. | +| No provider calls, shell execution, direct HTTP, or docs lookup code added | Passed by diff review. | +| No TenantConfigurationResource or evidence rows created | Passed by scope; no runtime command executed. | +| No OperationRun, coverage-level, compare/render, certification, restore, report, Review Pack/PDF, customer output, or `tenant_id` change | Passed by diff review. | + +## No-Promotion Matrix + +| Claim category | Result | +| --- | --- | +| Exchange evidence-ready/content-backed | Not claimed. | +| Teams evidence-ready/content-backed | Not claimed. | +| Comparable/renderable Exchange/Teams readiness | Not claimed; Spec 422 remains evidence-gated context only. | +| Certified or restore-ready Exchange/Teams | Not claimed. | +| Customer-ready or full M365 readiness | Not claimed. | +| Runtime adapter support | Not claimed. | + +## Product Surface / Filament / Deployment Close-Out + +- Product Surface Impact: `N/A - no rendered product surface changed`. +- UI Surface Impact: no reachable UI surface impact. +- Browser proof: `N/A - no rendered UI surface changed`. +- Human Product Sanity: `N/A - no product surface changed`. +- Product Surface exceptions: none. +- Visible complexity outcome: neutral for runtime; catalog reduces future source-surface ambiguity. +- Livewire v4 compliance: unchanged; no Livewire code edited. +- Provider registration location: unchanged; Laravel providers remain under `apps/platform/bootstrap/providers.php`. +- Global search posture: unchanged; no Filament Resource/global search behavior changed. +- Destructive/high-impact actions: none added or changed. +- Asset strategy: no assets; no `filament:assets` deployment requirement introduced. +- Deployment impact: none. No env vars, migrations, queues, scheduler, storage, assets, provider credentials, or provider permissions changed. + +## Validation + +Passed: + +- `git diff --check` + - passed with no output. +- `git diff --name-only` + - initially returned no tracked diff because the active spec package was untracked. +- `git status --short` + - final remediation stages the active Spec 429 package so merge review includes it. +- `git ls-files --others --exclude-standard specs/429-exchange-teams-source-surface-catalog-adapter-strategy` + - initially listed only files under `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`. +- `git diff --cached --name-only` + - final remediation check lists only files under `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`. +- Static matrix consistency check + - passed: 29 main matrix rows, 22 required fields per row, Cohort 1 = 15, Cohort 2 = 6, Deferred = 6, Unsupported = 1, Unknown = 1. +- `if rg -n '[[:blank:]]+$' specs/429-exchange-teams-source-surface-catalog-adapter-strategy; then exit 1; else exit 0; fi` + - passed; no trailing whitespace found in the active package. +- `if git status --short -- apps/platform/app apps/platform/config apps/platform/database apps/platform/resources apps/platform/routes apps/platform/tests | rg '.'; then exit 1; else exit 0; fi` + - passed; no application runtime, UI, config, migration, route, resource, or test path changed. + +No JSON catalog was added, so `python3 -m json.tool ...` is not applicable. + +## Post-Implementation Analysis + +- Analysis/fix iterations: 2. +- Findings fixed: + - `spec.md` still said catalog implementation was pending after the catalog artifacts and report were created. Remediation: updated the spec status to `Implementation complete - docs/catalog ready for review`. + - Final manual review found the active package was untracked and the Cohort 2/Deferred summary did not match the target matrix. Remediation: staged the active Spec 429 package for merge review and added the missing matrix rows for `teamsCallingPolicy` and `retentionCompliancePolicy`. +- Spec Readiness Gate: passed. +- Implementation Scope Gate: passed. +- Test Gate: passed for docs/catalog validation. No Pest/runtime tests were added or required because no runtime behavior changed. +- Browser Smoke Test Gate: passed as not applicable because no rendered UI surface changed. +- Post-Implementation Analysis Gate: passed; no confirmed in-scope findings remain. +- Residual risks: future adapter implementation remains separate-spec work. Spec 430 must independently justify runtime adapters, RBAC, provider permissions, OperationRun semantics, redaction, tests, and any UI/browser proof. + +## Merge Readiness Notes + +- Merge Readiness Gate: passed for the docs/catalog scope. +- Ready for manual review/merge as a no-runtime Spec 429 package. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/plan.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/plan.md new file mode 100644 index 00000000..a87d67ee --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/plan.md @@ -0,0 +1,246 @@ +# Implementation Plan: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy + +**Branch**: `429-exchange-teams-source-surface-catalog-adapter-strategy` | **Date**: 2026-07-04 | **Spec**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md` +**Input**: Feature specification from `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md` + +## Summary + +Prepare a no-runtime Exchange/Teams source-surface catalog and adapter strategy. The implementation loop must create static Spec Kit catalog artifacts only, classify source surfaces and adapter patterns, choose a bounded Cohort 1, document blockers and deferred boundaries, and prove no runtime code, provider calls, evidence, OperationRuns, UI, or customer claims changed. + +## Technical Context + +**Language/Version**: PHP 8.4.15, Laravel 12 repo context; no runtime code planned +**Primary Dependencies**: Existing Spec Kit artifacts; Microsoft Learn official documentation; existing Coverage v2 repo truth +**Storage**: N/A - no database, migration, persisted runtime artifact, or runtime registry consumption +**Testing**: Static artifact validation only; no Pest tests unless implementation adds optional static JSON validation +**Validation Lanes**: docs/spec/catalog validation; no browser lane +**Target Platform**: Laravel monolith under `apps/platform`, read-only context only +**Project Type**: web application monorepo, docs/catalog-only feature +**Performance Goals**: N/A - no runtime path +**Constraints**: no runtime code, migrations, tests, provider calls, OperationRuns, UI, evidence, customer output, or claims +**Scale/Scope**: Exchange/Teams catalog and Cohort 1 strategy for later Spec 430 implementation + +## 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**: docs/spec/catalog-only. +- **Native vs custom classification summary**: N/A. +- **Shared-family relevance**: none at runtime. +- **State layers in scope**: none. +- **Audience modes in scope**: N/A. +- **Decision/diagnostic/raw hierarchy plan**: N/A for runtime; catalog artifacts must keep technical source details out of customer/readiness language. +- **Raw/support gating plan**: N/A for runtime. +- **One-primary-action / duplicate-truth control**: N/A. +- **Handling modes by drift class or surface**: hard-stop-candidate if implementation attempts runtime UI, route, navigation, report, Review Pack, PDF, evidence, OperationRun, restore, certification, or customer output work. +- **Repository-signal treatment**: completed Specs 422/426/427 are read-only evidence; Spec 428 is a prepared fail-safe/no-op dependency and non-blocking for catalog-only work. +- **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**: Guardrail / Exception / Smoke Coverage: `N/A - catalog/strategy only, no rendered UI surface changed`. +- **UI/Productization coverage decision**: No UI surface impact. +- **Coverage artifacts to update**: none. +- **No-impact rationale**: No routes, UI files, Filament resources/pages/widgets, navigation, reports, downloads, or customer surfaces change. +- **Navigation / Filament provider-panel handling**: no panel change. +- **Screenshot or page-report need**: no. + +## Product Surface Contract Plan + +- **Product Surface Contract reference**: N/A for runtime; spec records no rendered product surface changed. +- **No-legacy posture**: canonical documentation-only strategy; no compatibility exception. +- **Page archetype and surface budget plan**: N/A. +- **Technical Annex and deep-link demotion plan**: N/A at runtime; catalog artifacts must not create application-facing technical annexes. +- **Canonical status vocabulary plan**: N/A for UI. Documentation-only catalog statuses are not runtime vocabulary. +- **Product Surface exceptions**: none. +- **Browser verification plan**: `N/A - no rendered UI surface changed`. +- **Human Product Sanity plan**: N/A for runtime. +- **Visible complexity outcome target**: neutral runtime impact; future implementation should reduce source-surface ambiguity. +- **Implementation report target**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. + +## Filament / Livewire / Deployment Posture + +- **Livewire v4 compliance**: unchanged; no Livewire code. +- **Panel provider registration location**: no panel/provider change; Laravel providers remain under `apps/platform/bootstrap/providers.php`. +- **Global search posture**: unchanged; no Filament Resource changed. +- **Destructive/high-impact action posture**: none. +- **Asset strategy**: no assets; no new `filament:assets` requirement. +- **Testing plan**: no pages/widgets/relation managers/actions; static artifact validation only. +- **Deployment impact**: none - no env vars, migrations, queues, scheduler, storage, assets, provider credentials, or provider permissions. + +## Shared Pattern & System Fit + +- **Cross-cutting feature marker**: no runtime touch; planning context for future source/evidence systems. +- **Systems touched**: Spec artifacts only. Read-only source evidence includes `ResourceTypeRegistry`, `SupportedScopeResolver`, `CoverageSourceContractResolver`, `CoverageIdentityStrategyRegistry`, `ExchangeTeamsComparablePayloadNormalizer`, `ExchangeTeamsCoverageComparator`, `ExchangeTeamsRenderableSummaryBuilder`, `ClaimGuard`, and related Spec 419/420/422/426/427 reports/tests. +- **Shared abstractions reused**: none now. Future runtime specs must reuse existing Coverage v2 paths unless they record a bounded exception. +- **New abstraction introduced? why?**: none in runtime. Documentation-only classifications exist to prevent unsafe implementation drift. +- **Why the existing abstraction was sufficient or insufficient**: Existing Coverage v2 can block missing source contracts and protect claims, but it cannot choose Exchange/Teams adapter source surfaces without catalog work. +- **Bounded deviation / spread control**: Static catalog artifacts may introduce documentation-only source/adapter/status vocabulary. Later runtime work must re-justify any promotion into code. + +## OperationRun UX Impact + +- **Touches OperationRun start/completion/link UX?**: no. +- **Central contract reused**: N/A. +- **Delegated UX behaviors**: N/A. +- **Surface-owned behavior kept local**: none. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception path**: none. + +Future provider capture, PowerShell execution, or remote work must create/reuse OperationRun through the central service and start UX contract in a separate spec. + +## Provider Boundary & Portability Fit + +- **Shared provider/platform boundary touched?**: yes, documentation-only classification. +- **Provider-owned seams**: Exchange Online PowerShell, Teams PowerShell, Exchange Online Admin API, Microsoft Graph resource availability, Security & Compliance/Purview PowerShell, SharePoint/OneDrive/PnP boundary, Microsoft permission/RBAC names, provider-native identifiers, response shapes. +- **Platform-core seams**: Coverage v2 source-contract state, evidence truth, identity truth, claim guard, workspace/managed-environment/provider-connection ownership, no-customer-claim rules. +- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, target type, source surface, adapter pattern, evidence state, claim boundary, blocker, cohort. +- **Retained provider-specific semantics and why**: Microsoft source names are necessary for catalog accuracy but remain inside Spec Kit documentation until a later implementation spec. +- **Bounded extraction or follow-up path**: document-in-feature. Spec 430 is the first runtime follow-up and must not implement the whole catalog. + +## Constitution Check + +- Inventory-first: catalog only; no inventory, snapshot, backup, or evidence truth changes. +- Read/write separation: no write/change behavior. +- Graph contract path: no Graph calls and no graph contract additions; later Graph work must use `GraphClientInterface` and `config/graph_contracts.php`. +- Deterministic capabilities: no capability resolver changes. +- RBAC-UX: no route, policy, action, global search, or authorization change. +- Workspace isolation: no runtime query or ownership change. +- Tenant isolation: no tenant-plane read/write change. +- Run observability: no OperationRun; future remote/provider work must use OperationRun. +- OperationRun start UX: N/A. +- Ops-UX 3-surface feedback: N/A. +- OperationRun lifecycle: no status/outcome transition. +- Summary counts: no new counts. +- Data minimization: catalog must not store secrets, tokens, raw credential payloads, mail content, Teams content, or customer data. +- Test governance: docs/catalog-only validation; no runtime test family. +- Proportionality: documentation taxonomy is justified by blocked Exchange/Teams sequence and no runtime machinery is introduced. +- No premature abstraction: no runtime abstraction. +- Persisted truth: no new persistence. +- Behavioral state: no runtime status family. +- UI semantics: no UI. +- Shared pattern first: future runtime must reuse Coverage v2, OperationRun, Claim Guard, and product-surface paths. +- Provider boundary: provider-specific source details stay documentation-only and provider-owned. +- V1 explicitness / few layers: catalog before adapter; no framework. +- Spec discipline / bloat check: broad source-surface ambiguity is grouped into one coherent catalog spec rather than multiple micro-specs. +- Badge semantics: no badge changes. +- Filament-native UI: N/A. +- UI/Productization coverage: no UI surface impact is recorded. + +## Test Governance Check + +- **Test purpose / classification by changed surface**: N/A - no runtime behavior changed. +- **Affected validation lanes**: docs/spec/catalog static checks only. +- **Why this lane mix is the narrowest sufficient proof**: The implementation changes only Spec Kit documentation artifacts. +- **Narrowest proving command(s)**: + - `git status --short` + - `git diff --check` + - `git diff --name-only` + - optional if JSON catalog is added: `python3 -m json.tool specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-types.json > /dev/null` +- **Fixture / helper / factory / seed / context cost risks**: none. +- **Expensive defaults or shared helper growth introduced?**: no. +- **Heavy-family additions, promotions, or visibility changes**: none. +- **Surface-class relief / special coverage rule**: N/A. +- **Closing validation and reviewer handoff**: Confirm catalog artifacts exist, matrix fields are complete, and no files outside Spec 429 changed. +- **Budget / baseline / trend follow-up**: none. +- **Review-stop questions**: Did runtime code change? Did any provider call/adapter/evidence/OperationRun/UI/customer claim appear? Did catalog terms become runtime values? +- **Escalation path**: reject-or-split if runtime adapter work is attempted. +- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - catalog/strategy only, no rendered UI surface changed`. +- **Why no dedicated follow-up spec is needed**: This spec is the dedicated catalog/strategy follow-up. Runtime adapter implementation is separately deferred to Spec 430. + +## Project Structure + +### Documentation (this feature) + +```text +specs/429-exchange-teams-source-surface-catalog-adapter-strategy/ +|-- spec.md +|-- plan.md +|-- tasks.md +|-- checklists/ +| `-- requirements.md +|-- catalog/ +| |-- exchange-source-surface-catalog.md +| |-- teams-source-surface-catalog.md +| |-- exchange-teams-target-type-matrix.md +| |-- adapter-strategy.md +| `-- cohort-plan.md +`-- implementation-report.md +``` + +### Source Code + +No source code changes are planned or allowed. + +Relevant read-only evidence paths: + +```text +docs/product/spec-candidates.md +docs/product/roadmap.md +specs/420-m365-generic-evidence-coverage-pack/ +specs/422-exchange-teams-comparable-renderable-pack/ +specs/426-exchange-teams-core-evidence-identity-readiness/ +specs/427-exchange-teams-verified-source-contract-enablement/ +specs/428-exchange-teams-content-backed-evidence-promotion/ +apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php +apps/platform/app/Services/TenantConfiguration/SupportedScopeResolver.php +apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php +apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php +apps/platform/app/Services/TenantConfiguration/ExchangeTeamsComparablePayloadNormalizer.php +apps/platform/app/Services/TenantConfiguration/ExchangeTeamsCoverageComparator.php +apps/platform/app/Services/TenantConfiguration/ExchangeTeamsRenderableSummaryBuilder.php +``` + +**Structure Decision**: Spec-only/catalog package. Implementation must stay under the Spec 429 directory. + +## Complexity Tracking + +| Violation | Why Needed | Simpler Alternative Rejected Because | +| --- | --- | --- | +| Documentation-only source/adapter taxonomy | Prevents unsafe one-off Exchange/Teams adapter work after Specs 427/428 blocked the narrow path | Four direct adapters would repeat the endpoint-guessing and false-readiness risk | + +## Proportionality Review + +- **Current operator problem**: Future release reviewers need a credible Exchange/Teams adapter map before evidence or customer claims can progress. +- **Existing structure is insufficient because**: Existing Coverage v2 structures block missing contracts but do not decide source surfaces, adapter patterns, or implementation cohorts. +- **Narrowest correct implementation**: Static catalog and strategy documents, no runtime code. +- **Ownership cost created**: Catalog maintenance and later specs must keep cohort/source decisions in sync. +- **Alternative intentionally rejected**: One-off adapters, guessed Graph endpoints, broad provider framework, and customer-readiness claims. +- **Release truth**: Current-release prerequisite truth. + +## Implementation Phases + +### Phase 0 - Preflight + +- Capture branch, HEAD, dirty state, selected candidate, completed-spec guardrail, and Spec 428 non-blocking assumption. +- Confirm no runtime/UI/evidence/customer-claim work is planned. + +### Phase 1 - Source Reference Collection + +- Collect official Microsoft Learn references for Exchange Online PowerShell, Exchange Online Admin API, Teams PowerShell, Graph Teams overview, Teams app/meeting/messaging/external-access policies, Exchange mail-flow/domains/remote domains, and Security & Compliance boundaries. +- Collect repo source references from Coverage v2 services and completed specs. + +### Phase 2 - Exchange Catalog + +- Catalog Exchange mail flow/transport, domains/connectors, organization configuration, sharing/relationship configuration, protection/hygiene, recipient/mailbox, and Purview/Security & Compliance boundary families. +- Classify candidate target types by source surface, adapter pattern, risk, value, and blocker. + +### Phase 3 - Teams Catalog + +- Catalog Teams app governance, meetings/events, messaging/channels, calling/voice, external/guest access, and files/storage/integration boundary families. +- Classify candidate target types by source surface, adapter pattern, risk, value, and blocker. + +### Phase 4 - Target Type Matrix And Cohort Plan + +- Normalize target type names. +- Complete required matrix fields. +- Select Cohort 1, Cohort 2, deferred, unsupported, and unknown groups. + +### Phase 5 - Adapter Strategy + +- Define Graph-native, Exchange Admin API, Exchange PowerShell, Teams PowerShell, Security & Compliance, unsupported, and unknown paths. +- Identify the first Spec 430 implementation slice and review/test constraints. + +### Phase 6 - Validation And Report + +- Validate no runtime diff. +- Create implementation report with required matrices and no-claim/no-promotion proof. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md new file mode 100644 index 00000000..dd7b2092 --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md @@ -0,0 +1,370 @@ +# Feature Specification: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy + +**Feature Branch**: `429-exchange-teams-source-surface-catalog-adapter-strategy` +**Created**: 2026-07-04 +**Status**: Implementation complete - docs/catalog ready for review +**Input**: User-provided draft "Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy" + +## Preparation Selection Summary + +- **Selected candidate**: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy. +- **Source location**: User-provided attachment `/Users/ahmeddarrazi/.codex/attachments/922413a0-883b-4d66-8436-a335f510e9e5/pasted-text.txt`. +- **Why selected**: The automatic candidate queue in `docs/product/spec-candidates.md` currently has no safe auto-prep target, but the user directly provided a P0 Coverage v2 / Microsoft 365 candidate. Specs 426-428 show the next Exchange/Teams blocker is not a single missing Graph contract; it is the absence of a coherent source-surface and adapter strategy. +- **Roadmap relationship**: This belongs to the M365 Coverage v2 readiness sequence after Specs 414, 415, 417, 419, 420, 422, 426, 427, and the prepared Spec 428 fail-safe/no-op package. It supports a later Exchange/Teams adapter cohort implementation without claiming readiness now. +- **Close alternatives deferred**: Management-report runtime validation, governance-artifact lifecycle retention, provider-readiness productization, cross-domain indicator follow-through, system-panel browser fixture work, and first governed AI runtime consumer remain manual-promotion/backlog items. They do not supersede this direct P0 Exchange/Teams continuation. +- **Completed-spec guardrail result**: Specs 414, 415, 417, 419, 420, 422, 426, and 427 contain completed implementation reports, validation results, completed tasks, or browser/smoke evidence. They are read-only dependency context and must not be rewritten, normalized, reopened, or stripped of close-out history. Spec 428 exists as a prepared fail-safe/no-op package and is accepted as non-blocking for this catalog-only spec because Spec 429 does not consume evidence or promote capture. +- **Smallest viable implementation slice**: Create documentation/catalog artifacts only: source reference notes, Exchange catalog, Teams catalog, target type matrix, cohort plan, adapter strategy, requirements checklist, and no-runtime implementation report. Do not implement adapters, provider calls, evidence, OperationRuns, UI, customer output, compare/render promotion, certification, restore, or runtime registry consumption. +- **Candidate Selection Gate**: PASS. The candidate is directly provided, not already covered by an existing Spec 429 package, aligns with the current Exchange/Teams blocker, and is scoped as a docs/catalog-only strategy package. + +## Draft-To-Repo Deviations + +The draft assumes Spec 428 can be treated as a fail-safe/no-op close-out. Current repo truth says Spec 428 is prepared but not implementation-closed; it records the fail-safe/no-op path because Spec 427 left all four first target types blocked as `contract_blocked_repo_adapter_missing`. + +This spec proceeds only because it is catalog/strategy work and does not depend on runtime evidence from Spec 428. Any attempt to treat Spec 428 as implemented evidence, or to use Spec 429 to create evidence, must stop and move to a separate implementation spec after the source-adapter decision is ready. + +The historical sequence "429 compare/render promotion" from Specs 426/427 is superseded by this user-provided 429 catalog/strategy candidate. Compare/render promotion is deferred to later Spec 432 after adapter implementation and content-backed evidence exist. + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: Exchange/Teams Coverage v2 cannot progress safely while TenantPilot lacks a source-surface catalog and adapter strategy for the real Exchange Online, Teams, Security & Compliance, Graph, and Admin API boundaries. +- **Today's failure**: The previous narrow sequence tried to reason about four target types in isolation. Spec 427 proved those types remain blocked by missing repo adapters/source contracts, and Spec 428 correctly prepared a no-op instead of evidence promotion. Without Spec 429, future work may guess endpoints, implement one-off adapters, or overclaim M365 readiness. +- **User-visible improvement**: Release reviewers and later implementers get a clear map of which Exchange/Teams surfaces matter, which source surface can be trusted, which adapter pattern is required, which target types enter Cohort 1, and which claims remain blocked. +- **Smallest enterprise-capable version**: Documentation/catalog artifacts only: Exchange catalog, Teams catalog, target type matrix, Cohort 1/2/deferred plan, adapter strategy, and no-promotion proof. No runtime code. +- **Explicit non-goals**: No Exchange adapter, Teams adapter, Graph contract, PowerShell execution, Exchange Admin API client, provider permission change, provider call, runtime documentation lookup, evidence row, OperationRun, coverage-level promotion, compare/render, certification, customer report, Review Pack/PDF output, restore/apply flow, Exchange/Teams dashboard, new provider subsystem, `tenant_id`, legacy shim, or runtime registry consumption. +- **Permanent complexity imported**: Spec/catalog documentation vocabulary only. No runtime model, table, enum, service, adapter, provider client, UI concept, or persisted taxonomy is introduced by this spec. Later implementation specs must re-justify runtime complexity. +- **Why now**: Specs 426-428 prove fail-safe behavior but leave Exchange/Teams structurally blocked. The next safe action is to map source surfaces and adapter cohorts before any more runtime work. +- **Why not local**: A local fix for four types would repeat the problem. The blocker spans Exchange Online PowerShell, Teams PowerShell, Graph, Exchange Online Admin API, Purview/Security & Compliance, SharePoint/OneDrive boundaries, permissions, identity, redaction, and customer claims. +- **Approval class**: Core Enterprise. +- **Red flags triggered**: New documentation taxonomy and strategy vocabulary. Defense: it remains static Spec Kit documentation, is required to prevent false governance/customer claims, and explicitly defers all runtime machinery to later specs with proportionality review. +- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 11/12** +- **Decision**: approve as catalog/strategy-only preparation for later adapter implementation. + +## Spec Scope Fields *(mandatory)* + +- **Scope**: Workspace + managed-environment scoped Coverage v2 planning context; documentation/catalog only. +- **Primary Routes**: N/A - no route, page, navigation, panel, action, report, download, browser-rendered surface, or customer surface changes. +- **Data Ownership**: No runtime data changes. Catalog artifacts must preserve the current ownership language: workspace, managed environment, provider connection, provider-owned source metadata, and no platform-core `tenant_id`. +- **RBAC**: Existing RBAC remains unchanged. Later adapter implementation must define capability and authorization requirements before any capture or provider call. + +For canonical-view specs: + +- **Default filter behavior when tenant-context is active**: N/A - no canonical route or rendered query changes. +- **Explicit entitlement checks preventing cross-tenant leakage**: N/A for this spec. Later runtime capture must enforce workspace + managed-environment + provider-connection same-scope checks. + +## No Legacy / No Backward Compatibility Constraint *(mandatory)* + +TenantPilot is pre-production unless this spec explicitly records a compatibility exception. + +- **Compatibility posture**: canonical documentation-only strategy; no compatibility exception. +- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no. +- **Why clean replacement is safe now**: No runtime behavior changes. The spec explicitly forbids legacy adapters, fallback readers, dual writes, Coverage v1 bridges, `tenant_id` ownership truth, fake evidence fixtures, and customer-facing legacy claims. + +## UI Surface Impact *(mandatory - UI-COV-001)* + +Does this spec add, remove, rename, or materially change any reachable UI surface? + +- [x] No UI surface impact +- [ ] Existing page changed +- [ ] New page/route added +- [ ] Navigation changed +- [ ] Filament panel/provider surface changed +- [ ] New modal/drawer/wizard/action added +- [ ] New table/form/state added +- [ ] Customer-facing surface changed +- [ ] Dangerous action changed +- [ ] Status/evidence/review presentation changed +- [ ] Workspace/environment context presentation changed + +No-impact rationale: Spec 429 is a catalog and adapter strategy package. It must not edit runtime UI files, route files, Filament resources/pages/widgets, navigation, reports, downloads, customer outputs, or browser-rendered diagnostics. + +## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)* + +N/A - no reachable UI surface impact. Future specs that expose Exchange/Teams status, evidence, readiness, or adapter progress in rendered product surfaces must satisfy the Product Surface Contract before runtime UI edits. + +## Product Surface Impact *(mandatory for UI-affecting specs; otherwise write `N/A - no rendered product surface changed` plus rationale)* + +Reference: `docs/product/standards/product-surface-contract.md`. + +- **Product Surface Contract applies?**: no - no rendered product surface changes. +- **Page archetype**: N/A. +- **Primary user question**: N/A. +- **Primary action**: N/A. +- **Surface budget result**: N/A. +- **Technical Annex / deep-link demotion**: N/A for runtime. Catalog artifacts may discuss technical source surfaces, but no OperationRun, evidence, raw payload, ID, source key, detector, fingerprint, or log is rendered in the application. +- **Canonical status vocabulary**: N/A for UI. Documentation-only catalog status values are not runtime status vocabulary. +- **Visible complexity impact**: neutral in runtime; future implementation should decrease hidden Exchange/Teams ambiguity. +- **Product Surface exceptions**: none. + +## Browser Verification Plan *(mandatory)* + +- **Browser proof required?**: no. +- **No-browser rationale**: `N/A - no rendered UI surface changed`. +- **Focused path when required**: N/A. +- **Primary interaction to execute**: N/A. +- **Console, Livewire, Filament, network, and 500-error checks**: N/A. +- **Full-suite failure triage**: N/A. + +## Human Product Sanity Check *(mandatory)* + +- **Required?**: no. +- **No-human-sanity rationale**: N/A - no product surface changed. +- **Reviewer questions**: N/A for runtime. Manual artifact review should verify the catalog is actionable, does not imply readiness, and keeps source boundaries clear. +- **Planned result location**: future implementation report. + +## Product Surface Merge Gate Checklist *(mandatory)* + +- [x] No-legacy posture or approved exception recorded. +- [x] Product Surface Impact is completed or `N/A` is justified. +- [x] Browser proof is completed or `N/A - no rendered UI surface changed` is justified. +- [x] Human Product Sanity is completed or not applicable with rationale. +- [x] Product Surface exceptions are documented or `none`. +- [x] Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, no completed-spec rewrite assertion, and no application implementation. + +## 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?**: no runtime touch; yes as planning context for future source/evidence surfaces. +- **Interaction class(es)**: N/A for runtime. +- **Systems touched**: Spec artifacts only. Read-only references include Coverage v2 registry/source-contract/identity/claim guard truth and completed Exchange/Teams helper specs. +- **Existing pattern(s) to extend**: none in this spec. Future implementation must reuse Coverage v2 source-contract, generic capture/evidence, canonical identity, OperationRun, Claim Guard, and product-surface patterns. +- **Shared contract / presenter / builder / renderer to reuse**: N/A now; later specs must name exact repo classes before runtime work. +- **Why the existing shared path is sufficient or insufficient**: Existing Coverage v2 paths are sufficient for proof and claims, but insufficient for Exchange/Teams capture because no source adapters/contracts exist for the first target types. +- **Allowed deviation and why**: static catalog documentation only. +- **Consistency impact**: Later runtime work must not create a parallel Exchange/Teams product language, evidence path, or customer claim path. +- **Review focus**: Confirm the catalog maps future work back to existing shared paths rather than inventing an Exchange/Teams mini-platform. + +## 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. +- **Delegated start/completion UX behaviors**: N/A. +- **Local surface-owned behavior that remains**: none. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception required?**: none. + +Any future adapter/capture implementation that performs remote work must create/reuse canonical OperationRun semantics through existing shared paths before provider execution. + +## 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, as documentation-only classification. +- **Boundary classification**: mixed. Coverage v2 source-contract, evidence, identity, claim, scope, and customer-output gates are platform-core. Exchange Online, Teams, Security & Compliance, Graph, Admin API, PowerShell cmdlets, provider-native IDs, permission names, and response shapes are provider-owned source details. +- **Seams affected**: Spec/catalog artifacts only; no runtime seam changes. +- **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, target type, source surface, source contract candidate, adapter pattern, evidence state, claim boundary, blocker. +- **Provider-specific semantics retained and why**: Exchange/Teams family names, Microsoft cmdlet/API names, and Microsoft permission/RBAC terms are retained only as provider-owned source research needed to select future adapters. +- **Why this does not deepen provider coupling accidentally**: No provider-specific table, runtime registry, route, UI, OperationRun type, adapter, endpoint, permission, or customer claim is added. +- **Follow-up path**: document-in-feature now; Spec 430 must separately justify any runtime adapter and provider permission work. + +## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)* + +N/A - no operator-facing surface change. + +## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +- **New source of truth?**: no runtime source of truth. The future catalog artifacts are planning truth only. +- **New persisted entity/table/artifact?**: no runtime persisted entity/table. The implementation loop will create static Spec Kit catalog documents. +- **New abstraction?**: no runtime abstraction. +- **New enum/state/reason family?**: no runtime enum or persisted status family. Catalog status/source/adapter values are documentation-only vocabulary. +- **New cross-domain UI framework/taxonomy?**: no UI framework. Documentation-only target type taxonomy is introduced to prevent unsafe adapter work. +- **Current operator problem**: Release reviewers cannot safely approve the next Exchange/Teams adapter/evidence step without knowing which source surfaces are safe, valuable, and bounded. +- **Existing structure is insufficient because**: The existing Coverage v2 path blocks capture correctly, but it does not answer which Exchange/Teams source surface should be implemented first or how to avoid one-off adapter drift. +- **Narrowest correct implementation**: Static catalog and strategy artifacts, no runtime machinery. +- **Ownership cost**: Maintaining catalog artifacts and carrying source-boundary decisions into later specs. +- **Alternative intentionally rejected**: Implementing four adapters directly, guessing Graph endpoints, using PowerShell one-offs, broad Exchange/Teams mini-platforms, and customer-readiness claims. +- **Release truth**: Current-release prerequisite truth for future adapter implementation. + +### 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. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: docs/spec/catalog validation only; no runtime test family. +- **Validation lane(s)**: Spec Kit artifact validation plus static no-runtime checks. +- **Why this classification and these lanes are sufficient**: No application code, migrations, runtime config, UI, tests, provider calls, evidence, or OperationRuns are changed by the spec preparation. Later docs-only implementation should prove file existence and no-runtime diff. +- **New or expanded test families**: none. +- **Fixture / helper cost impact**: none. +- **Heavy-family visibility / justification**: none. +- **Special surface test profile**: N/A. +- **Standard-native relief or required special coverage**: `N/A - no rendered UI surface changed`. +- **Reviewer handoff**: Confirm changed files stay under the Spec 429 package, catalog artifacts are complete, and no app/runtime files are touched. +- **Budget / baseline / trend impact**: none. +- **Escalation needed**: none for prep; reject-or-split if runtime adapter work is attempted. +- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - catalog/strategy only, no rendered UI surface changed`. +- **Planned validation commands**: + - `git status --short` + - `git diff --check` + - `git diff --name-only` + - Optional if JSON catalog is added later: `python3 -m json.tool specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-types.json > /dev/null` + +## Source Reference Basis *(preparation notes)* + +The implementation loop must use official Microsoft documentation and repo truth only. Initial official source anchors: + +- [Exchange Online PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell?view=exchange-ps) +- [Exchange Online PowerShell app-only authentication](https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps) +- [Overview of the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-overview) +- [Authentication and authorization for the Exchange Online Admin API](https://learn.microsoft.com/en-us/exchange/reference/admin-api-authentication) +- [Exchange PowerShell cmdlet module reference](https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/?view=exchange-ps) +- [MicrosoftTeams PowerShell module reference](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/?view=teams-ps) +- [Teams app permission policies](https://learn.microsoft.com/en-us/microsoftteams/teams-app-permission-policies) +- [Teams app setup policies](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies) +- [Teams settings and policies reference](https://learn.microsoft.com/en-us/microsoftteams/settings-policies-reference) +- [Teams guest and external access](https://learn.microsoft.com/en-us/microsoftteams/communicate-with-users-from-other-organizations) +- [Exchange mail flow rules](https://learn.microsoft.com/en-us/exchange/security-and-compliance/mail-flow-rules/manage-mail-flow-rules) +- [Exchange accepted domains](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/manage-accepted-domains/manage-accepted-domains) +- [Exchange remote domains](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/remote-domains/remote-domains) +- [Microsoft Graph Teams overview](https://learn.microsoft.com/en-us/graph/api/resources/teams-api-overview?view=graph-rest-1.0) + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Catalog Source Surfaces Without Claims (Priority: P1) + +As a release reviewer, I need Exchange and Teams administration families cataloged by source surface and adapter pattern so I can approve a later implementation sequence without confusing cataloged surfaces with supported evidence. + +**Why this priority**: This is the core safety gate. Without it, later implementation may guess endpoints, over-select Cohort 1, or imply readiness. + +**Independent Test**: Verify `exchange-source-surface-catalog.md`, `teams-source-surface-catalog.md`, and `exchange-teams-target-type-matrix.md` exist, cite official/repo sources, classify source surfaces and adapter patterns, and state no runtime support is created. + +**Acceptance Scenarios**: + +1. **Given** the Spec 429 package, **When** a reviewer opens the catalog artifacts, **Then** Exchange and Teams families are mapped to source surface classes and adapter patterns without runtime claims. +2. **Given** a target type lacks source or permission clarity, **When** the matrix is reviewed, **Then** the row is deferred, blocked, unsupported, or unknown rather than selected for Cohort 1. + +--- + +### User Story 2 - Select a Bounded Core Cohort (Priority: P2) + +As a future implementer, I need Cohort 1, Cohort 2, and deferred/backlog decisions so Spec 430 can implement the narrowest valuable adapter slice. + +**Why this priority**: Adapter implementation must be small, reviewable, and product-relevant. + +**Independent Test**: Verify `cohort-plan.md` selects approximately 12-20 Cohort 1 candidates or documents a scoped exception, includes both Exchange and Teams, excludes Purview/Defender/SharePoint boundary items unless justified, and records selection rationale. + +**Acceptance Scenarios**: + +1. **Given** candidate target types from Exchange and Teams, **When** Cohort 1 is selected, **Then** each selected type has identifiable source surface, adapter pattern, risk, complexity, and customer/MSP value. +2. **Given** a valuable but high-risk target type, **When** the cohort plan is reviewed, **Then** the type is placed in Cohort 2 or deferred with an explicit reason. + +--- + +### User Story 3 - Produce an Actionable Adapter Strategy (Priority: P3) + +As a future adapter implementer, I need the adapter strategy to separate Graph-native, Exchange Admin API, Exchange PowerShell, Teams PowerShell, Security & Compliance, unsupported, and unknown paths. + +**Why this priority**: The first implementation spec after 429 must know which adapter path comes first and what security/product review it requires. + +**Independent Test**: Verify `adapter-strategy.md` identifies adapter patterns, first implementation sequence, authentication and permission concerns, execution environment concerns, redaction/testability requirements, and no-runtime constraints. + +**Acceptance Scenarios**: + +1. **Given** a candidate requiring Exchange Online PowerShell, **When** the adapter strategy is reviewed, **Then** it documents auth options, tenant consent, execution environment, module dependency, error normalization, redaction, throttling, and fake command-runner testability. +2. **Given** a candidate covered by the Exchange Online Admin API, **When** the strategy is reviewed, **Then** it records the preview/focused-scope limitation and does not treat the API as a full Exchange Online PowerShell replacement. + +### Edge Cases + +- Official Microsoft documentation shows a setting is portal-only or unstable. +- A target type overlaps Exchange and Purview/Defender boundaries. +- A Teams policy overlaps SharePoint/OneDrive file governance. +- A source exists only in Graph beta or preview API. +- A source shape is a singleton tenant setting rather than a collection. +- A source depends on per-user/per-mailbox enumeration and would explode Cohort 1 scope. +- A source requires broad admin roles or app-only permissions that are not least-privilege enough for SaaS capture. +- A Microsoft cmdlet represents an operational action rather than durable configuration. + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-429-001**: The implementation MUST create `catalog/exchange-source-surface-catalog.md`. +- **FR-429-002**: The implementation MUST create `catalog/teams-source-surface-catalog.md`. +- **FR-429-003**: The implementation MUST create `catalog/exchange-teams-target-type-matrix.md`. +- **FR-429-004**: The implementation MUST create `catalog/cohort-plan.md`. +- **FR-429-005**: The implementation MUST create `catalog/adapter-strategy.md`. +- **FR-429-006**: The Exchange catalog MUST cover mail flow/transport, domains/connectors, organization configuration, sharing/relationship configuration, protection/hygiene boundary, recipient/mailbox boundary, and Purview/Security & Compliance boundary. +- **FR-429-007**: The Teams catalog MUST cover app governance, meetings/events, messaging/channels, calling/voice, external/guest access, and files/storage/integration boundary. +- **FR-429-008**: Every target type matrix row MUST include canonical type, human label, workload, admin area, source surface class, adapter pattern, source reference, expected object shape, singleton/collection classification, identity candidate, identity risk, permission risk, response shape risk, redaction risk, compare complexity, render complexity, customer value, MSP value, cohort, status, blocker reason, and notes. +- **FR-429-009**: Source surface class values MUST be documentation-only and limited to `graph_v1`, `graph_beta_experimental`, `exchange_online_powershell_rest`, `exchange_online_admin_api`, `teams_powershell`, `security_compliance_powershell`, `sharepoint_pnp_related`, `unsupported_manual_only`, and `unknown_requires_research`. +- **FR-429-010**: Adapter pattern values MUST be documentation-only and limited to `existing_graph_client_contract`, `new_graph_contract`, `new_exchange_admin_api_contract`, `new_exchange_powershell_adapter`, `new_teams_powershell_adapter`, `new_security_compliance_adapter`, `defer_to_purview_adapter`, and `unsupported`. +- **FR-429-011**: Status values MUST be documentation-only and limited to `cohort_1_candidate`, `cohort_1_selected`, `cohort_2_candidate`, `deferred`, `blocked_missing_source`, `blocked_permission_unclear`, `blocked_identity_unsafe`, `blocked_response_shape_unsafe`, `blocked_product_value_low`, `blocked_purview_boundary`, `unsupported`, and `unknown_requires_research`. +- **FR-429-012**: Risk values MUST be documentation-only and limited to `low`, `medium`, `high`, `critical`, and `unknown`. +- **FR-429-013**: Complexity values MUST be documentation-only and limited to `simple`, `moderate`, `complex`, `very_complex`, and `unknown`. +- **FR-429-014**: Cohort 1 MUST include both Exchange and Teams candidates and SHOULD contain 12-20 target types unless the catalog documents why fewer are safer. +- **FR-429-015**: Cohort 1 MUST exclude unsupported/manual-only, unknown, beta-only certification blockers, portal-only, primarily Purview/Defender, and primarily SharePoint/OneDrive types unless a documented exception explains why they are still safe. +- **FR-429-016**: The adapter strategy MUST state which adapter pattern should be implemented first in Spec 430 and why. +- **FR-429-017**: The adapter strategy MUST document PowerShell adapter concerns: authentication options, certificate/application auth feasibility, tenant consent, execution environment, module dependencies, throttling/rate limits, error normalization, response serialization, redaction, fake command runner testability, and no shell execution in unit tests. +- **FR-429-018**: The adapter strategy MUST document Graph contract concerns when applicable: endpoint/resource availability, v1/beta status, permissions, pagination, identity fields, response shape, redaction, and `GraphClientInterface` compatibility. +- **FR-429-019**: The adapter strategy MUST document Exchange Online Admin API concerns when applicable: preview status, supported scenarios, unsupported scenarios, permissions/RBAC, POST-only behavior, response shape, and why it is not a full Exchange Online PowerShell replacement. +- **FR-429-020**: The catalog MUST treat Microsoft cmdlets as source evidence, not automatic TenantPilot target types. +- **FR-429-021**: The catalog MUST preserve the current repo truth that `transportRule`, `acceptedDomain`, `appPermissionPolicy`, and `meetingPolicy` remain blocked by missing repo adapter/source contract until a later implementation spec changes that truth. +- **FR-429-022**: The implementation report MUST include target type summary, Cohort 1, adapter strategy, and no-promotion matrices. +- **FR-429-023**: The implementation MUST NOT change files outside `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/` unless the spec is amended before work continues. +- **FR-429-024**: The implementation MUST NOT create or modify application runtime code, migrations, models, services, jobs, commands, policies, routes, views, Filament/Livewire UI, tests, provider clients, runtime config consumed by the app, database rows, evidence rows, or OperationRuns. +- **FR-429-025**: The implementation MUST NOT make or enable claims that Exchange/Teams are evidence-ready, content-backed, comparable, renderable, certified, restore-ready, customer-ready, full M365 ready, or pilot-ready. +- **FR-429-026**: The implementation MUST review and, if needed, update `checklists/requirements.md` after catalog artifacts and the implementation report are complete; the preparation PASS alone MUST NOT be treated as catalog implementation completion. + +### Key Entities *(include if feature involves data)* + +- **Catalog target type**: Documentation-only representation of a productized configuration resource candidate that may later become identifiable, captured, hashed, compared, rendered, claim-guarded, or certified. +- **Source surface class**: Documentation-only classification of where the source data appears to live: Graph, Exchange Online PowerShell, Exchange Online Admin API, Teams PowerShell, Security & Compliance PowerShell, SharePoint/PnP boundary, unsupported/manual, or unknown. +- **Adapter pattern**: Documentation-only classification of the future implementation pattern required to capture the target type safely. +- **Cohort**: Documentation-only grouping that controls implementation sequencing; it does not change runtime support. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-429-001**: A reviewer can identify Cohort 1 target types, source surfaces, adapter patterns, and major blocker reasons from the catalog artifacts without opening application source code. +- **SC-429-002**: Every Cohort 1 target type has non-empty source surface, adapter pattern, identity risk, permission risk, compare/render complexity, and customer/MSP value fields. +- **SC-429-003**: The adapter strategy names the first implementation spec path and separates Graph, Exchange Admin API, Exchange PowerShell, Teams PowerShell, Security & Compliance, unsupported, and unknown decisions. +- **SC-429-004**: Validation proves changed files are limited to the Spec 429 package and that no runtime/UI/evidence/OperationRun/customer-claim files changed. +- **SC-429-005**: No open question blocks starting Spec 430 as a docs-to-runtime adapter implementation spec. + +## Assumptions + +- Spec 428's prepared fail-safe/no-op status is non-blocking because Spec 429 is catalog-only and does not depend on evidence from Spec 428. +- Official Microsoft Learn pages and current repo source/test/spec truth are sufficient for source-surface classification. +- Catalog status/source/adapter values remain documentation vocabulary until a later spec explicitly promotes any value into runtime code with proportionality review. +- The first later implementation spec will be Spec 430 and will remain narrower than the full catalog. + +## Open Questions + +- None blocking for preparation. During implementation, official Microsoft source review may mark additional target types as unknown, unsupported, or deferred. + +## Risks + +| Risk | Severity | Mitigation | +| --- | ---: | --- | +| Catalog is mistaken for support/readiness | High | No-claim matrix and explicit no-runtime wording in every artifact | +| Cohort 1 becomes too broad | High | 12-20 target guidance, risk/value scoring, deferred backlog | +| Graph availability is overestimated | High | Official source reference required; beta/preview paths blocked from certification | +| PowerShell adapter complexity is underestimated | High | Separate adapter strategy and Spec 430 implementation gate | +| Purview/Defender/SharePoint boundaries blur | High | Boundary classification in catalog and deferred backlog | +| Runtime implementation sneaks in | High | Tasks and validation forbid app/runtime file changes | +| `tenant_id` returns | High | No-runtime/no-tenant-id proof in implementation report | + +## Follow-up Spec Candidates + +- Spec 430 - Exchange/Teams Adapter Cohort 1 Implementation. +- Spec 431 - Exchange/Teams Content-Backed Evidence Promotion. +- Spec 432 - Exchange/Teams Comparable / Renderable Promotion. +- Spec 433 - Exchange/Teams Certified Core Compare Pack. +- Spec 434 - M365 Customer Output & Claim Guard. +- Spec 435 - M365 Pilot Readiness Gate. +- Purview/Security & Compliance adapter strategy if catalog boundaries show enough current-release value. +- SharePoint/OneDrive file governance source-surface catalog if Teams file/storage boundaries require it. diff --git a/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/tasks.md b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/tasks.md new file mode 100644 index 00000000..0922e71c --- /dev/null +++ b/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/tasks.md @@ -0,0 +1,145 @@ +# Tasks: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy + +**Input**: Design documents from `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/` +**Prerequisites**: `spec.md`, `plan.md`, `checklists/requirements.md` +**Implementation Mode**: catalog/strategy only. Do not edit application runtime code. + +## Test Governance Checklist + +- [x] Lane assignment is named as docs/spec/catalog validation only. +- [x] New or changed tests are not added unless optional static JSON validation is introduced. +- [x] Shared helpers, factories, seeds, fixtures, and context defaults remain unchanged. +- [x] Planned validation commands cover the no-runtime catalog closure without pulling in unrelated lane cost. +- [x] Browser proof is explicitly `N/A - no rendered UI surface changed`. +- [x] Human Product Sanity and Product Surface implementation-report close-out are `N/A - no rendered UI surface changed`. +- [x] Any future runtime adapter, capture, evidence, or UI work is escalated to Spec 430 or later. + +## Phase 1: Preflight + +**Goal**: Prove the work starts from safe repo state and completed specs stay read-only. + +- [x] T001 Capture current branch, HEAD, and `git status --short` in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. +- [x] T002 Confirm completed Specs 414, 415, 417, 419, 420, 422, 426, and 427 are read-only context and are not edited. +- [x] T003 Confirm Spec 428 is a prepared fail-safe/no-op package and record why it is non-blocking for this catalog-only spec. +- [x] T004 Confirm the active implementation diff is limited to `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`. +- [x] T005 Confirm no files under `apps/platform/app/`, `apps/platform/config/`, `apps/platform/database/`, `apps/platform/resources/`, `apps/platform/routes/`, or `apps/platform/tests/` are changed. +- [x] T006 Confirm no runtime adapter, provider call, evidence, OperationRun, UI, report, Review Pack/PDF output, restore/apply, certification, customer claim, or `tenant_id` work is planned. + +## Phase 2: Catalog Artifact Setup + +**Goal**: Create the static catalog artifact surface for the documentation-only implementation. + +- [x] T007 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/`. +- [x] T008 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T009 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T010 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md`. +- [x] T011 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md`. +- [x] T012 Create `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. + +## Phase 3: Source Reference Collection + +**Goal**: Ground catalog decisions in official Microsoft documentation and current repo truth. + +- [x] T013 [P] Record official Exchange Online PowerShell, app-only auth, cmdlet module, and Exchange Online Admin API references in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T014 [P] Record official Teams PowerShell, Teams policy, external/guest access, and Microsoft Graph Teams overview references in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T015 [P] Record repo source evidence from `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php`, `SupportedScopeResolver.php`, `CoverageSourceContractResolver.php`, and completed Specs 419, 420, 422, 426, 427, and 428 in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md`. +- [x] T016 [P] Record source authority rules and forbidden source-authority rules in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. + +## Phase 4: Exchange Source Surface Catalog + +**Goal**: Catalog Exchange administration/configuration families without implementing adapters. + +- [x] T017 [US1] Catalog mail flow and transport families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T018 [US1] Catalog domains and connector families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T019 [US1] Catalog organization, sharing, relationship, role assignment, mailbox plan, address book, and admin audit families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T020 [US1] Catalog protection/hygiene families and classify Defender/Purview boundaries in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T021 [US1] Catalog recipient/mailbox boundary families and document per-mailbox explosion risk in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-source-surface-catalog.md`. +- [x] T022 [US1] For each Exchange family, record source surface class, adapter pattern, expected object shape, identity risk, permission risk, response-shape risk, redaction risk, customer/MSP value, and blocker reason in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md`. + +## Phase 5: Teams Source Surface Catalog + +**Goal**: Catalog Teams policy/configuration families without implementing adapters. + +- [x] T023 [US1] Catalog app governance families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T024 [US1] Catalog meetings/events families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T025 [US1] Catalog messaging/channels families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T026 [US1] Catalog calling/voice families and license/complexity risks in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T027 [US1] Catalog external/guest access families in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T028 [US1] Catalog files/storage/integration boundaries and classify SharePoint/OneDrive overlap in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/teams-source-surface-catalog.md`. +- [x] T029 [US1] For each Teams family, record source surface class, adapter pattern, expected object shape, identity risk, permission risk, response-shape risk, redaction risk, customer/MSP value, and blocker reason in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md`. + +## Phase 6: Target Type Matrix And Cohorts + +**Goal**: Make later implementation bounded and reviewable. + +- [x] T030 [US2] Ensure every row in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-type-matrix.md` includes all fields required by FR-429-008. +- [x] T031 [US2] Validate documentation-only source surface, adapter pattern, status, risk, and complexity values against FR-429-009 through FR-429-013. +- [x] T032 [US2] Select Cohort 1 in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md` with both Exchange and Teams represented and roughly 12-20 candidates unless a narrower exception is documented. +- [x] T033 [US2] Define Cohort 2 in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md` with reasons each type is not Cohort 1. +- [x] T034 [US2] Define deferred, unsupported, and unknown backlogs in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/cohort-plan.md`. +- [x] T035 [US2] Add target type summary and Cohort 1 matrices to `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. + +## Phase 7: Adapter Strategy + +**Goal**: Turn catalog findings into an actionable Spec 430 implementation path. + +- [x] T036 [US3] Document Graph-native contract path, Graph v1/beta handling, permissions, pagination, identity fields, response shape, redaction, and `GraphClientInterface` compatibility in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T037 [US3] Document Exchange Online Admin API path, preview/focused-scope limitation, permissions/RBAC, POST-only behavior, response shape, and non-replacement boundary in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T038 [US3] Document Exchange PowerShell adapter path, app-only/certificate auth feasibility, tenant consent, execution environment, module dependencies, throttling, error normalization, response serialization, redaction, and fake command-runner testability in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T039 [US3] Document Teams PowerShell adapter path, policy/cmdlet boundaries, permission risks, execution environment, response serialization, redaction, and fake command-runner testability in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T040 [US3] Document Security & Compliance/Purview, Defender, SharePoint/OneDrive, unsupported/manual, and unknown follow-up paths in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T041 [US3] Define the first Spec 430 implementation slice, non-goals, stop conditions, and validation strategy in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/adapter-strategy.md`. +- [x] T042 [US3] Add adapter strategy matrix to `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. + +## Phase 8: No Runtime / No Claim Proof + +**Goal**: Prove the catalog did not become runtime support or product readiness. + +- [x] T043 Confirm no application services, provider clients, migrations, models, jobs, commands, policies, routes, views, Filament/Livewire UI, tests, or runtime config consumed by the app changed. +- [x] T044 Confirm no runtime provider call, PowerShell execution, application-side documentation lookup, application-side direct HTTP request, provider SDK bypass, or Microsoft source-fetch code was added. +- [x] T045 Confirm no `TenantConfigurationResource`, `TenantConfigurationResourceEvidence`, OperationRun, coverage-level, compare/render, certification, restore, report, Review Pack, PDF, customer output, or `tenant_id` change was added. +- [x] T046 Confirm no claim was added for Exchange evidence readiness, Teams evidence readiness, content-backed Exchange/Teams, comparable/renderable Exchange/Teams, certification, full M365 readiness, customer-ready proof, or restore readiness. +- [x] T047 Add no-promotion and no-runtime matrices to `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. + +## Phase 9: Validation And Checklist + +**Goal**: Close the docs/catalog implementation with reviewable proof. + +- [x] T048 Run `git diff --check`. +- [x] T049 Run `git diff --name-only` and confirm changed files are limited to `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/`. +- [x] T050 Run `git status --short` and record final dirty state in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. +- [x] T051 If `catalog/exchange-teams-target-types.json` is added, run `python3 -m json.tool specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-types.json > /dev/null`. N/A - no JSON catalog was added. +- [x] T052 Review and, if needed, update `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/checklists/requirements.md` after catalog artifacts and the implementation report are complete; record if no checklist changes are needed. +- [x] T053 Record browser status as `N/A - no rendered UI surface changed` in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. +- [x] T054 Record Livewire v4 unchanged, provider registration unchanged under `apps/platform/bootstrap/providers.php`, global search unchanged, destructive/high-impact actions none, asset strategy none, deployment impact none, visible complexity neutral, and no completed-spec rewrite proof in `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`. + +## Dependencies & Execution Order + +- Phase 1 must complete before any catalog artifact work. +- Phase 2 creates files required by Phases 3-7. +- Phase 3 source collection must precede final catalog classifications. +- Exchange and Teams catalog work in Phases 4 and 5 can run in parallel after Phase 3. +- Phase 6 depends on enough catalog rows to select Cohort 1 and Cohort 2. +- Phase 7 depends on target classifications and cohort decisions. +- Phases 8 and 9 close after catalog and adapter strategy are complete. + +## Parallel Opportunities +- T013-T016 can run in parallel after catalog files exist. +- Exchange family tasks T017-T021 can run in parallel if merge coordination is explicit. +- Teams family tasks T023-T028 can run in parallel if merge coordination is explicit. +- No application-code task is parallelizable because no application-code task is allowed. + +## Stop Conditions + +Stop and amend or replace this spec if any of the following becomes true: + +- runtime adapters, provider clients, provider calls, or PowerShell execution are required; +- application code, migrations, routes, views, tests, jobs, commands, policies, or runtime config need to change; +- evidence rows, OperationRuns, coverage-level promotion, compare/render, certification, restore, reports, Review Pack/PDF output, or customer claims are required; +- catalog terms need to become runtime enums/statuses/registries; +- `tenant_id`, legacy compatibility, fallback readers, dual writes, or Coverage v1 bridges appear; +- official source research cannot support a safe Cohort 1 decision. + +## Recommended MVP Scope + +Complete Phases 1-9 as a single docs/catalog package. Do not split before Cohort 1 and adapter strategy exist, because the value of Spec 429 is the combined map that makes Spec 430 safe.