# Spec Candidates

> Concrete future specs waiting for prioritization.
> Each entry has enough structure to become a real spec when the time comes.
>
> **Flow**: Inbox → Qualified → Planned → Spec created → moved to `Promoted to Spec`

**Last reviewed**: 2026-03-28 (added request-scoped performance foundation candidates for derived state, governance aggregates, and workspace access context)

---

## Inbox

> Ungefiltert. Kurze Notiz reicht. Wöchentlich sichten.

- Dashboard trend visualizations (sparklines, compliance gauge, drift-over-time chart)
- Dashboard "Needs Attention" should be visually louder (alert color, icon, severity weighting)
- Dashboard enterprise polish: severity-weighted drift table, actionable alert buttons, progressive disclosure (demoted from Qualified — needs bounded scope before re-qualifying)
- Operations table should show duration + affected policy count
- Density control / comfortable view toggle for admin tables
- Inventory landing page may be redundant — consider pure navigation section
- Settings change history → explainable change tracking
- Workspace chooser v2: search, sort, favorites, pins, environment badges, last activity
- Workspace-level PII override for review packs (deferred from Spec 109 — controls whether PII is included/redacted in tenant review pack exports at workspace scope)
- CSV export for filtered run metadata (deferred from Spec 114 — allow operators to export filtered operation run lists from the system console as CSV)
- Raw error/context drilldowns for system console (deferred from Spec 114 — in-product drilldown into raw error payloads and execution context for failed/stuck runs in the system console)

---

## Promoted to Spec

> Historical ledger for candidates that are no longer open. Keep them here so prioritization stays clean without losing decision history.

- Queued Execution Reauthorization and Scope Continuity → Spec 149 (`queued-execution-reauthorization`)
- Livewire Context Locking and Trusted-State Reduction → Spec 152 (`livewire-context-locking`)
- Evidence Domain Foundation → Spec 153 (`evidence-domain-foundation`)
- Operator Outcome Taxonomy and Cross-Domain State Separation → Spec 156 (`operator-outcome-taxonomy`)
- Operator Reason Code Translation and Humanization Contract → Spec 157 (`reason-code-translation`)
- Governance Artifact Truthful Outcomes & Fidelity Semantics → Spec 158 (`artifact-truth-semantics`)

---

## Qualified

> Problem + Nutzen klar. Scope noch offen. Braucht noch Priorisierung.

### Request-Scoped Derived State and Resolver Memoization
- **Type**: foundation
- **Source**: cross-cutting Filament render-path performance analysis 2026-03-28 — repeated derived-state resolution across `ArtifactTruthPresenter`, `OperationUxPresenter`, and `RelatedNavigationResolver`
- **Problem**: TenantPilot's presenter / resolver layer is architecturally correct but render-path chatty. The same derived truth, guidance, or related-navigation state is recomputed multiple times per record, per surface, and per request: list row badges, descriptions, tooltips, visibility checks, detail entries, and widgets ask for the same deterministic answer through separate closures. This is broader than one local N+1 query; it is a repeated-cost shape that now spans baseline, evidence, review, operation, and navigation surfaces.
- **Why it matters**: If each page is locally optimized in isolation, the underlying cost pattern remains and spreads into tenant reviews, review packs, evidence surfaces, baseline snapshots, and future portfolio/MSP views. The product needs a shared contract for deterministic request-local reuse, not another generation of ad hoc static caches and page-specific memoization helpers.
- **Proposed direction**:
  - Introduce a canonical request-scoped derived-state store for deterministic presenter / resolver outputs
  - Define explicit keying rules around presenter family, record type, record identity, variant / surface mode, and any relevant view-policy context
  - Route `ArtifactTruthPresenter::for*()` paths, `OperationUxPresenter` surface guidance paths, and `RelatedNavigationResolver` primary/detail-entry paths through the shared store
  - Separate raw domain state, derived surface state, and navigation/context state so memoization boundaries are explicit instead of accidental
  - Provide a row-safe consumption pattern for Filament tables so label / tooltip / description / visible / url closures share the same derived state instead of recomputing it independently
  - Define an explicit freshness rule for mutating action flows so request-local reuse never masks state that must be recomputed within the same action request
- **Scope boundaries**:
  - **In scope**: request-scoped memoization contract, derived-state store infrastructure, keying contract, presenter/resolver adoption for at least Artifact Truth, Operation UX, and Related Navigation, and Filament list/detail/widget guardrails for row-safe consumption
  - **Out of scope**: Redis or cross-request caching, aggressive query redesign, semantic changes to truth/guidance/navigation rules, widget redesign, and one-off page caches that bypass the shared contract
- **Acceptance points**:
  - The same artifact truth for the same scope is fully derived at most once per request
  - The same operation guidance for the same run/surface scope is fully derived at most once per request
  - The same related primary/detail navigation entry for the same record is fully resolved at most once per request
  - At least three currently affected surface families adopt the same shared contract
  - Existing truth / guidance / navigation semantics stay unchanged from the operator's perspective
  - Regression tests prove request-local reuse and mutation-path freshness
- **Risks / open questions**:
  - Incorrect cache keys could cause invalid reuse across surfaces or variants
  - Static ad hoc caches would hide the problem rather than solve it
  - Mutation flows need an explicit invalidation or fresh-recompute rule where state can legitimately change mid-request
- **Suggested order**: first. This is the shared performance foundation the two follow-up candidates build on.
- **Priority**: high

### Tenant Governance Aggregate Contract
- **Type**: foundation
- **Source**: tenant governance surface overlap analysis 2026-03-28 — shared summary state duplicated across Baseline Compare Landing, Needs Attention, Coverage Banner, Compare Now, and related tenant-governance cards
- **Problem**: TenantPilot currently recomposes overlapping tenant-governance summaries on multiple surfaces in parallel instead of treating them as one tenant-scoped aggregate. Baseline compare freshness, compare outcome, open finding counts, overdue findings, expiring governance, lapsed governance, and related drift/coverage signals are recalculated or re-queried per widget/page, leaving ownership fragmented and making each new governance card more expensive than it needs to be.
- **Why it matters**: Release 1 and 2 continue expanding governance, review, evidence, and dashboard surfaces. If these tenant-level summaries keep growing surface-by-surface, new widgets will multiply redundant count queries, presentation-specific helper code, and semantic drift around what exactly qualifies as an attention count or governance posture.
- **Proposed direction**:
  - Promote the current baseline/governance summary path into an explicit tenant-scoped aggregate contract, either by hardening `BaselineCompareStats` into that role or by introducing a clearly named `TenantGovernanceAggregate`
  - Define one shared tenant summary that covers compare freshness, compare outcome, confidence/coverage/suppression where relevant, open findings summary, overdue findings, expiring/lapsed governance counts, and compare-related drift posture
  - Make dashboard widgets and attention cards consume the aggregate and keep only presentation mapping local to the surface
  - Prohibit parallel count queries for states that are already part of the shared aggregate contract
  - Ensure repeated reads of the same tenant aggregate on one page are request-scoped and reusable instead of recomputed per widget
- **Scope boundaries**:
  - **In scope**: tenant-scoped governance aggregate contract, shared ownership of attention counts, dashboard/landing/banner/card consumption for the same aggregate family, and request-local reuse across those surfaces
  - **Out of scope**: cross-tenant portfolio aggregation, cross-request persistence caching, new drift semantics, new findings workflow semantics, full dashboard redesign, and broader evidence/review aggregation beyond the current tenant-governance summary family
- **Acceptance points**:
  - At least three tenant-governance widgets/pages consume the same aggregate contract
  - No widget re-queries overdue, lapsed, or expiring counts that are already part of the shared aggregate
  - Dashboard, landing, and banner surfaces present semantically consistent values for the same tenant state
  - Request-local reuse for the tenant aggregate is demonstrably testable
  - No visible business-semantics regression is introduced while consolidating the summary source
- **Risks / open questions**:
  - An overly broad aggregate could become a single oversized payload instead of a crisp contract
  - If attention semantics are not clearly separated from presentation mapping, widgets will continue to smuggle business logic back into the UI layer
  - If `BaselineCompareStats` stays helper-shaped rather than becoming an explicit contract, ownership ambiguity will persist even after partial consolidation
- **Suggested order**: second, ideally immediately after or alongside the request-scoped derived-state foundation.
- **Priority**: high

### Workspace Access Context and Navigation Cost Hardening
- **Type**: hardening
- **Source**: admin/workspace access-path analysis 2026-03-28 — repeated current-workspace, membership, navigation-visibility, and policy-adjacent access resolution across admin requests
- **Problem**: TenantPilot already has request-local caching in some capability resolvers, but the wider workspace/admin access path still pays a repeated request tax. Current workspace resolution, workspace membership lookups, navigation visibility checks, page access checks, and policy-adjacent access helpers can rebuild overlapping context multiple times before the actual screen content has even rendered. The issue is not one slow page; it is a hidden cost shape spread across many admin requests.
- **Why it matters**: As admin, monitoring, review, evidence, and future portfolio/workspace surfaces grow, this hidden context tax will compound across almost every workspace-scoped request. Left unbounded, it also increases the risk of access logic drifting into scattered local helpers instead of one explicit request-level contract.
- **Proposed direction**:
  - Introduce an explicit request-scoped workspace access context that carries the current workspace ID/model, the membership decision, and any capability-access snapshot needed for repeated checks
  - Harden `currentWorkspace()` or equivalent paths so the active workspace model is request-stable instead of repeatedly reloaded
  - Make navigation visibility, resource visibility, page access helpers, and similar admin-panel checks consume the shared access context rather than rebuilding workspace/membership state locally
  - Reuse the same context in policy-side or policy-adjacent workspace access decisions where repeated lookup is currently common
  - Keep cross-panel workspace-aware transitions aligned with the same context contract rather than introducing special-case handoff helpers
- **Scope boundaries**:
  - **In scope**: request-scoped workspace access context, current-workspace reuse, membership reuse, navigation/page-access context reuse, and migration of at least a subset of admin-sensitive helpers to the shared path
  - **Out of scope**: RBAC redesign, capability-semantic changes, navigation IA restructuring, tenant-panel RBAC rewrite, or product-model changes to workspace-first behavior
- **Acceptance points**:
  - The current workspace is not separately loaded multiple times within the same request path
  - Repeated workspace-scoped access checks reuse the same membership/access context instead of rebuilding it
  - At least two admin-sensitive request paths are migrated to the shared access context
  - Navigation visibility uses request-wide reusable workspace context rather than repeated local lookups
  - Access semantics remain unchanged while the request-path cost is hardened
- **Risks / open questions**:
  - A wrong or overly broad shared context could create subtle access bugs
  - The boundary between session-persisted workspace choice and request-scoped access context must stay explicit
  - Over-centralization could hide legitimate special cases if exceptions are not consciously modeled
- **Suggested order**: third, after the derived-state and tenant-aggregate foundation work has clarified the shared request-scoped patterns.
- **Priority**: medium

### Tenant Draft Discard Lifecycle and Orphaned Draft Visibility
- **Type**: hardening
- **Source**: domain architecture analysis 2026-03-16 — tenant lifecycle vs onboarding workflow lifecycle review
- **Problem**: TenantPilot correctly separates durable tenant lifecycle (`draft`, `onboarding`, `active`, `archived`) from onboarding workflow lifecycle (`draft` → `completed` / `cancelled`), but there is no end-of-life path for abandoned draft tenants. When all onboarding sessions for a tenant are cancelled, the tenant reverts to `draft` and remains visible indefinitely without a semantically correct cleanup action. Archive/restore do not apply (draft tenants have no operational data worth preserving), and force delete requires archive first (which is semantically wrong for a provisional record). Operators cannot remove orphaned drafts.
- **Why it matters**: Without a discard path, abandoned draft tenants accumulate as orphaned rows in the tenant list. This creates operator confusion (draft vs. archived vs. active ambiguity), data hygiene issues, and forces operators to either ignore stale records or misuse lifecycle actions that don't fit the domain semantics. The gap also makes tenant list UX harder to trust for enterprise operators managing many tenants.
- **Proposed direction**:
  - Introduce a canonical **draft discardability contract** (central service/policy, not scattered UI visibility logic) that determines whether a draft tenant may be safely removed, considering linked onboarding sessions, downstream artifacts, and operational traces
  - Add a **discard draft** destructive action for tenant records in `draft` status with no resumable onboarding sessions, gated by the discardability contract, capability authorization (`tenant.delete` or a dedicated `tenant.discard_draft`), and confirmation modal
  - Add an **orphaned draft indicator** to the tenant list/detail views — visual distinction between a resumable draft (has active session) and an abandoned draft (all sessions terminal or none exist)
  - Emit a **distinct audit event** (`tenant.draft_discarded`) separate from `tenant.force_deleted`, capturing workspace context, tenant identifiers, linked session state, and acting user
  - Preserve and reinforce the existing domain separation: `archive/restore/force_delete` remain reserved for durable tenant lifecycle; `cancel/delete` remain reserved for onboarding workflow lifecycle; `discard` is the new end-of-life action for provisional drafts
- **Key domain rules**:
  - `archive` = preserve durable tenant for compliance while removing from active use
  - `restore` = reactivate an archived durable tenant
  - `force delete` = permanently destroy an already archived durable tenant
  - `discard draft` = permanently remove a provisional tenant that never became a durable operational entity
  - Draft tenants must NOT become archivable or restorable
- **Safety preconditions for discard**: tenant is in `draft` status, not trashed, no resumable onboarding sessions exist, no accumulated operational data (no policies, backups, operation runs beyond onboarding)
- **Out of scope**: automatic cleanup without operator confirmation, retention policy for cancelled onboarding sessions, changes to the 4-state tenant lifecycle enum, changes to the 7-state onboarding session lifecycle enum
- **Dependencies**: Spec 140 (onboarding lifecycle checkpoints — already shipped), Spec 143 (tenant lifecycle operability context semantics)
- **Related specs**: Spec 138 (draft identity), Spec 140 (lifecycle checkpoints), Spec 143 (lifecycle operability semantics)
- **Priority**: medium

### Baseline Capture Truthful Outcomes and Upstream Guardrails
- **Type**: hardening
- **Source**: product/domain analysis 2026-03-21 — baseline capture no-op success case (Operation Run #112), follow-up to 2026-03-08 discovery "Drift engine hard-fail when no Inventory Sync exists"
- **Problem**: Baseline Capture can currently finish as `Completed / Succeeded` even when no credible baseline was produced. In the observed case, the run accepted a completed-but-blocked upstream Inventory Sync, resolved `subjects_total = 0`, captured `items_captured = 0`, reused an empty snapshot, and still presented a successful baseline capture. The current contract treats all-zero capture as a benign empty result instead of a prerequisite or trust-semantics problem.
- **Why it matters**: This is a governance credibility issue, not just a debugging bug. A green "Baseline capture succeeded" state implies that TenantPilot established or refreshed a trustworthy baseline artifact. When the actual result is "no usable inventory basis" or "no in-scope subjects", operators, auditors, and MSP reviewers are misled. False-green run outcomes weaken operations transparency, baseline trust, and the product's auditability story.
- **Proposed direction**:
  - **Precondition guardrails for `baseline.capture`**: require a *usable* upstream inventory basis, not merely the existence of the latest `OperationRun` with `status = completed`. `outcome` and coverage usability must be part of the decision.
  - **Stricter upstream source selection**: Baseline Capture should select the latest *credible* Inventory Sync, not simply the latest completed one. `blocked` and `failed` inventory runs must not be accepted as baseline inputs.
  - **Truthful outcome semantics**: define stable terminal behavior for no-data and bad-upstream cases:
    - no inventory exists → `blocked`
    - latest inventory run is `blocked` → `blocked`
    - latest inventory run is `failed` → `blocked`
    - inventory is valid, but zero relevant subjects resolve → `partially_succeeded`
    - success is reserved for captures that produce a usable baseline result
  - **Stable reason-code contract**: add baseline-capture-specific reason codes for blocked/no-data outcomes so operator messaging, audit logs, and run detail pages are deterministic instead of heuristic.
  - **Empty snapshot semantics**: an empty snapshot must not be silently treated as a credible active baseline. If zero-subject capture remains representable for audit/history reasons, it must be visibly marked as a no-data artifact and must not auto-promote to `active_snapshot_id` by default.
  - **Operator-facing run UX**: the Operation Run detail page should lead with a primary message such as `No baseline was captured`, `Latest inventory sync was blocked`, `Run tenant sync first`, or `No subjects were in scope`, instead of allowing an all-zero run to read as neutral or successful. Raw JSON/context remains secondary.
  - **All-zero count visibility rule**: `0 / 0 / 0 / 0` counts must not read as semantically blank. If a run completes with all-zero counts, the surface must explain *why*.
- **Key domain decisions to encode**:
  - `baseline.capture` must not accept a fachlich unbrauchbarer upstream inventory run
  - `status = completed` alone is insufficient for capture eligibility
  - `subjects_total = 0` must not render as a full success state
  - empty or reused empty snapshots are not inherently trustworthy baseline artifacts
- **Scope boundaries**:
  - **In scope**: baseline capture runtime preconditions, inventory-run eligibility for capture, capture outcome mapping, baseline-capture reason codes, empty-snapshot promotion rules, operation-run detail messaging for baseline capture, focused start-surface preflight/copy if needed
  - **Out of scope**: full redesign of the entire `OperationRun` platform, broad rewrite of inventory coverage semantics, generalized platform-wide no-data heuristics for every operation type, drift-engine compare semantics (except where this candidate explicitly borrows its warning/reason-code pattern), roadmap-wide operations naming or badge redesign
- **Strategic importance**: This is a small-scope but high-trust hardening item. It protects one of TenantPilot's core governance promises: that a baseline artifact is meaningful, reviewable, and safe to reason about. It also strengthens MSP/operator confidence that Monitoring surfaces are operationally truthful, not cosmetically green.
- **Roadmap fit**: Aligns with **Active / Near-term — Governance & Architecture Hardening** (canonical run-view trust semantics) and acts as follow-through on **Baseline Drift Engine (Cutover)** by tightening the capture side of baseline truth, not just the compare side.
- **Acceptance points**:
  - A capture run without a credible inventory basis cannot finish as `succeeded`
  - A capture run with valid inventory but zero in-scope subjects ends as `partially_succeeded` with explicit reason code
  - Operation Run detail for baseline capture exposes primary cause + next action before raw context payloads
  - Existing tests that encode "empty capture succeeds" are replaced with truthful-outcome coverage
  - Empty snapshots are not silently promoted as active baselines unless explicitly allowed and visibly marked by the spec
- **Risks / open questions**:
  - Whether zero-item snapshots should still be persisted as audit traces or suppressed entirely needs one explicit product decision; recommendation is "persist only if visibly marked and not auto-promoted"
  - There is already a broader inconsistency in `blocked` / `failed` / `skipped` semantics across some operation families (notably Inventory Sync job vs service path). This candidate should mention that risk but remain tightly scoped to Baseline Capture truthfulness.
  - If product wants stale successful inventory fallback instead of strict "latest credible only", that needs an explicit rule rather than hidden fallback behavior.
- **Dependencies**: Baseline drift engine stable (Specs 116–119), inventory coverage context, canonical operation-run presentation work (Specs 054, 114, 144), audit log foundation (Spec 134), tenant operability and execution legitimacy direction (Specs 148, 149)
- **Related specs / candidates**: Spec 101 (baseline governance), Specs 116–119 (baseline drift engine), Spec 144 (canonical operation viewer context decoupling), Spec 149 (queued execution reauthorization), `discoveries.md` entry "Drift engine hard-fail when no Inventory Sync exists"

### Provider-Backed Action Preflight and Dispatch Gate Unification
- **Type**: hardening
- **Source**: prerequisite-handling architecture analysis, provider dispatch gate architecture review, semantic clarity audit 2026-03-21
- **Problem**: TenantPilot has two generations of provider-backed action dispatch patterns that produce inconsistent operator experiences for the same class of problem (missing prerequisites, blocked execution, concurrency collision):
  - **Gen 2 pattern** (correct, ~3 job types): `ProviderInventorySyncJob`, `ProviderConnectionHealthCheckJob`, `ProviderComplianceSnapshotJob` receive an explicit `providerConnectionId`, pass through `ProviderOperationStartGate` at dispatch time, and produce structured `ProviderOperationStartResult` envelopes with 4 clear states (`started`, `deduped`, `scope_busy`, `blocked`) plus structured reason codes and next-steps. Operators learn about blocked conditions **before** the job is queued.
  - **Gen 1 pattern** (inconsistent, ~20 services + their jobs): `ExecuteRestoreRunJob`, `EntraGroupSyncJob`, `SyncRoleDefinitionsJob`, policy sync jobs, and approximately 17 other services resolve connections implicitly at runtime via `MicrosoftGraphOptionsResolver::resolveForTenant()` or internal `resolveProviderConnection()` methods. These services bypass the gate entirely — prerequisites are not checked before dispatch. Blocked conditions are discovered asynchronously during job execution, producing runtime exceptions (`ProviderConfigurationRequiredException`, `RuntimeException`, `InvalidArgumentException`) that surface to operators as after-the-fact failed runs rather than preventable preflight blocks.
  - **Operator impact**: the same class of problem (missing provider connection, expired consent, invalid credentials, scope busy) produces two different operator experiences depending on which action triggered it. Gen 2 actions produce a clear "blocked" result with reason code and next-step guidance at the moment the operator clicks the button. Gen 1 actions silently queue, then fail asynchronously — the operator discovers the problem only when checking the operation run later, with a raw error message instead of structured guidance.
  - **Concurrency and deduplication gaps**: the `ProviderOperationStartGate` handles scope_busy / deduplication for Gen 2 operations, but Gen 1 operations have no equivalent deduplication — multiple restore or sync jobs for the same tenant/scope can be queued simultaneously, competing for the same provider connection without coordination.
  - **Notification inconsistency**: Gen 2 blocked results produce immediate toast/notification via `ProviderOperationStartResult` rendering in Filament actions. Gen 1 failures produce terminal `OperationRunCompleted` notifications with sanitized but still technical failure messages. The operator receives different feedback patterns for equivalent problems.
- **Why it matters now**: As TenantPilot adds more provider domains (Entra roles, enterprise apps, SharePoint sharing), more operation types (baseline capture, drift detection, evidence generation), and more governance workflows (restore, review, compliance snapshot), every new provider-backed action that follows the Gen 1 implicit pattern reproduces the same operator experience gap. The Gen 2 pattern is proven, architecturally correct, and already handles the hard problems (connection locking, stale run detection, structured reason codes). The gap is not design — it is incomplete adoption. Additionally, the "Provider Connection Resolution Normalization" candidate addresses the backend plumbing problem (explicit connection ID passing), but does not address the operator-facing preflight/dispatch gate UX pattern. This candidate addresses the operator experience layer: ensuring that all provider-backed actions follow one canonical start path and that operators receive consistent, structured, before-dispatch feedback about prerequisites.
- **Proposed direction**:
  - **Canonical dispatch entry point for all provider-backed actions**: all operator-triggered provider-backed actions (sync, backup, restore, health check, compliance snapshot, baseline capture, evidence generation, and future provider operations) must pass through a canonical preflight/dispatch gate before queuing. The existing `ProviderOperationStartGate` is the reference implementation; this candidate extends its scope to cover all provider-backed operation types, not just the current 3.
  - **Structured preflight result presentation contract**: define a shared Filament action result-rendering pattern for `ProviderOperationStartResult` states (`started`, `deduped`, `scope_busy`, `blocked`) so that every provider-backed action button produces the same UX feedback pattern. Currently, each Gen 2 consumer renders gate results with local if/else blocks — this should be a shared presenter or action mixin.
  - **Pre-queue prerequisite detection**: blocked conditions (missing connection, expired consent, invalid credentials, tenant not operable, scope busy, missing required permissions) must be detected and surfaced to the operator **before** the job is dispatched to the queue. Operators should never discover a preventable prerequisite failure only after checking a terminal `OperationRun` record.
  - **Dispatch-time connection locking for all operation types**: extend the `FOR UPDATE` row-locking pattern from Gen 2 to all provider-backed operations, preventing concurrent conflicting operations on the same provider connection.
  - **Deduplication/scope-busy enforcement for all operation types**: extend scope_busy/dedup detection to Gen 1 operations (restore, group sync, role sync, etc.) that currently lack it. Operators should receive "An operation of this type is already running for this tenant" feedback at click time, not discover it through a failed run.
  - **Unified next-steps for all blocked states**: extend the `ProviderNextStepsRegistry` pattern (or its successor from the Reason Code Translation candidate) to cover all provider-backed operation blocked states, not just provider connection codes. Every "blocked" gate result includes cause-specific next-action guidance.
  - **Operator notification alignment**: terminal notifications for provider-backed operations must follow the same structured pattern regardless of which generation of plumbing dispatched them. The notification should include: translated reason code (per Reason Code Translation contract), structured next-action guidance, and a link to the relevant resolution surface.
- **Key decisions to encode**:
  - `ProviderOperationStartGate` (or its evolved successor) is the single canonical dispatch entry point — no provider-backed action bypasses it
  - Pre-queue prerequisite detection is a product guarantee for all provider operations — async-only failure discovery is an anti-pattern
  - Scope-busy / deduplication is mandatory for all provider operations, not just Gen 2
  - The gate result presentation is a shared UI contract, not a per-action local rendering decision
- **Scope boundaries**:
  - **In scope**: extending `ProviderOperationStartGate` scope to all provider-backed operation types, shared gate result presenter for Filament actions, pre-queue prerequisite detection for Gen 1 operations, scope-busy/dedup extension, next-steps enrichment for all gate blocked states, notification alignment for gate results, dispatch-time connection locking extension
  - **Out of scope**: backend connection resolution refactoring (tracked separately as "Provider Connection Resolution Normalization" — that candidate handles explicit `providerConnectionId` passing; this candidate handles the operator-facing gate/preflight layer), provider connection UX label changes (tracked as "Provider Connection UX Clarity"), legacy credential cleanup (tracked as "Provider Connection Legacy Cleanup"), adding new provider domains (domain expansion specs own that), operation naming vocabulary (tracked separately), reason code translation contract definition (tracked as "Operator Reason Code Translation" — this candidate consumes translated labels)
- **Affected workflow families / surfaces**: All provider-backed Filament actions across TenantResource, ProviderConnectionResource, onboarding wizard, and future governance action surfaces. Approximately 20 services currently using Gen 1 implicit resolution. Notification templates for provider-backed operation terminal states. System console triage views for provider-related failures.
- **Why this should be one coherent candidate rather than per-action fixes**: The Gen 1 pattern is used by ~20 services. Fixing each service independently would produce 20 local preflight implementations with inconsistent result rendering, different dedup logic, and incompatible notification patterns. The value is the unified contract: one gate, one result envelope, one presenter, one notification pattern. Per-action fixes cannot deliver this convergence.
- **Dependencies**: Provider Connection Resolution Normalization (soft dependency — gate unification is more coherent when all services receive explicit connection IDs, but the gate itself can be extended before full backend normalization is complete since `ProviderConnectionResolver::resolveDefault()` already exists). Operator Reason Code Translation (for translated blocked-reason labels in gate results). Operator Outcome Taxonomy (for consistent outcome vocabulary in gate result presentation).
- **Related specs / candidates**: Provider Connection Resolution Normalization (backend plumbing), Provider Connection UX Clarity (UX labels), Provider Connection Legacy Cleanup (post-normalization cleanup), Queued Execution Reauthorization (execution-time revalidation — complementary to dispatch-time gating), Baseline Capture Truthful Outcomes (consumes gate results for baseline-specific preconditions), Operator Presentation & Lifecycle Action Hardening (rendering conventions for gate results)
- **Strategic sequencing**: Recommended as the adjacent hardening lane after the shared taxonomy and translation work are in place, while governance-surface adoption proceeds through Spec 158 and the governance compression follow-up. It benefits from the vocabulary defined by the Outcome Taxonomy and the humanized labels from Reason Code Translation, but much of the backend extension of `ProviderOperationStartGate` scope can proceed independently and in parallel with governance-surface work.
- **Priority**: high

### Governance Operator Outcome Compression
- **Type**: hardening
- **Source**: product follow-up recommendation 2026-03-23; direct continuation of Spec 158 (`artifact-truth-semantics`)
- **Vehicle**: new standalone candidate
- **Problem**: Spec 158 establishes the correct internal truth model for governance artifacts, but several governance-facing list and summary surfaces still risk exposing too many internal semantic axes as first-class UI language. On baseline, evidence, review, and pack surfaces the product can still read as academically correct but operator-heavy: multiple adjacent status badges, architecture-derived labels, and equal treatment of existence, readiness, freshness, completeness, and publication semantics. Normal operators are forced to synthesize the answer to three simple workflow questions themselves: Is this artifact usable, why not, and what should I do next?
- **Why it matters**: This is the cockpit follow-up to Spec 158's engine work. Without it, TenantPilot preserves semantic correctness internally but leaks too much of that structure directly into governance UX. The result is lower scanability, weaker operator confidence, and a real risk that baseline, evidence, review, and pack domains each evolve their own local status dialect despite sharing the same truth foundation. Shipping this follow-up before broader governance expansion stabilizes operator language where MSP admins actually work.
- **Proposed direction**:
  - Introduce a **compressed operator outcome layer** for governance artifacts that consumes the existing `ArtifactTruthEnvelope`, outcome taxonomy, and reason translation contracts without discarding any internal truth dimensions
  - Define rendering rules that classify each truth dimension as **primary operator view**, **secondary explanatory detail**, or **diagnostics only**
  - Make list and overview rows answer three questions first: **primary state**, **short reason**, **next action**
  - Normalize visible operator language so internal architectural terms such as `artifact truth`, `missing_input`, `metadata_only`, or `publication truth` do not dominate primary workflow surfaces
  - Clarify where **publication readiness** is the primary business statement versus where it is only one secondary dimension, especially for tenant reviews and review packs
  - Keep diagnostics available on detail and run-detail pages, but demote raw reason structures, fidelity sub-axes, JSON context, and renderer/support facts behind the primary operator explanation
- **Primary adoption surfaces**:
  - Baseline snapshot lists and detail pages
  - Evidence snapshot lists and detail pages
  - Evidence overview
  - Tenant review lists and detail pages
  - Review register
  - Review pack lists and detail pages
  - Shared governance detail templates and artifact-truth presenter surfaces
  - Artifact-oriented run-detail pages only where the run is explaining baseline, evidence, review, or review-pack truth
- **Scope boundaries**:
  - **In scope**: visible operator labels, list-column hierarchy, detail-page information hierarchy, mapping from artifact-truth envelopes to compressed operator states, explicit separation between default operator view and diagnostic detail, review/pack publication-readiness primacy rules, governance run-detail explanation hierarchy
  - **Out of scope**: full operations-list redesign, broad visual polish, color or spacing retuning as the primary goal, new semantic foundation axes, broad findings or workspace overview rewrites, compliance/audit PDF output changes, alert routing or notification copy rewrites, domain-model refactors that change the underlying truth representation
- **Core product principles to encode**:
  - One primary operator statement per artifact on scan surfaces
  - No truth loss: internal artifact truth, reason structures, APIs, audit context, and JSON diagnostics remain intact and available
  - Diagnostics are second-layer, not the default operator language
  - Context-specific business language beats architecture-first vocabulary on primary governance surfaces
  - Lists are scan surfaces, not diagnosis surfaces
- **Candidate requirements**:
  - **R1 Composite operator outcome**: governance artifacts expose a compressed operator-facing outcome derived from the existing truth and reason model
  - **R2 Primary / secondary / diagnostic rendering rules**: the system defines which semantic dimensions may appear in each rendering tier
  - **R3 List-surface simplification**: governance lists stop defaulting to multi-column badge explosions for separate semantic axes
  - **R4 Detail-surface hierarchy**: details lead with outcome, explanation, and next action before diagnostics
  - **R5 Operator language normalization**: internal architecture terms are translated or removed from primary governance UI
  - **R6 Review / pack publication clarity**: review and pack surfaces explicitly state when publishability is the main business decision and when it is not
  - **R7 No truth loss**: APIs, audit, diagnostics, and raw context remain available even when the primary presentation is compressed
- **Acceptance points**:
  - Governance lists no longer present multiple equal-weight semantic badge columns as the default mental model
  - `artifact truth` and sibling architecture-first labels stop dominating primary operator surfaces
  - Governance detail pages clearly separate primary state, explanatory reason, next action, and diagnostics
  - Review and pack surfaces clearly answer whether the artifact is ready to publish or share
  - Baseline and evidence surfaces clearly answer whether the artifact is trustworthy and usable
  - Governance run-detail pages make the dominant problem and next action understandable without reading raw JSON
  - The internal truth model remains fully usable for diagnostics, audit, and downstream APIs
- **Dependencies**: Spec 156 (operator-outcome-taxonomy), Spec 157 (reason-code-translation), Spec 158 (artifact-truth-semantics), shared governance detail templates, review-layer and evidence-domain adoption surfaces already in flight
- **Related specs / candidates**: Spec 153 (evidence-domain-foundation), Spec 155 (tenant-review-layer), Spec 158 (artifact-truth-semantics), Baseline Snapshot Fidelity Semantics candidate, Compliance Readiness & Executive Review Packs candidate
- **Strategic sequencing**: Recommended immediately after Spec 158 and before any major additional governance-surface expansion. This is the adoption layer that turns the truth semantics foundation into an operator-tolerable cockpit instead of a direct dump of internal semantic richness.
- **Priority**: high

### Humanized Diagnostic Summaries for Governance Operations
- **Type**: hardening
- **Source**: operator-facing governance run-detail gap analysis 2026-03-23; follow-up to Specs 156, 157, and 158
- **Vehicle**: new standalone candidate
- **Problem**: Governance run-detail pages now have the right outcome, reason, and artifact-truth semantics, but the operator explanation often still lives in raw JSON. A run can read as `Completed with follow-up`, `Partial`, `Blocked`, or `Missing input` while the important meaning stays hidden: how much was affected, which cause dominates, whether retry or resume helps, and whether the resulting artifact is actually trustworthy.
- **Why it matters**: This is the missing middle layer between Spec 158's truth engine and the operator's actual decision. Without it, TenantPilot stays semantically correct but too technical on one of its highest-trust governance surfaces. Raw JSON remains part of normal troubleshooting when it should be optional.
- **Proposed direction**:
  - Add a humanized diagnostic summary layer on governance run-detail pages between semantic verdicts and raw JSON
  - Lead with impact, dominant cause, artifact trustworthiness, and next action instead of forcing operators to infer those from badges plus raw context
  - Render a compact dominant-cause breakdown for multi-cause degraded runs, including counts or relative scale where useful
  - Separate processing-success counters from artifact usability so technically correct metrics do not read as false-green artifact success
  - Upgrade generic `Inspect diagnostics` guidance into cause-aware next steps such as retry later, resume capture, refresh policy inventory, verify missing policies, review ambiguous matches, or fix access or scope configuration
  - Keep raw JSON and low-level context fully available, but explicitly secondary
- **Primary adoption surfaces**:
  - Canonical Monitoring run-detail pages for governance operation types
  - Shared tenantless canonical run viewers and run-detail templates
  - Governance run detail reached from baseline capture, baseline compare, evidence refresh or snapshot generation, tenant review generation, and review-pack generation
- **Scope boundaries**:
  - **In scope**: run-detail explanation hierarchy, humanized impact summaries, dominant-cause breakdowns, clearer processing-versus-artifact terminology, reusable guidance pattern for governance run families
  - **Out of scope**: full Operations redesign, broad list or dashboard overhaul, new persistence models for summaries, removal of raw JSON, new truth axes beyond the existing outcome or artifact-truth model, generalized rewrite of all governance artifact detail pages
- **Acceptance points**:
  - A normal operator can understand the dominant problem and next step on a governance run-detail page without opening raw JSON
  - Runs with technically successful processing but degraded artifacts explicitly explain why those truths diverge
  - Multi-cause degraded runs show the dominant causes and their scale instead of only one flattened abstract state
  - Guidance distinguishes retryable or resumable situations from structural prerequisite problems when the data supports that distinction
  - Raw JSON remains present for audit and debugging but is clearly secondary in the page hierarchy
- **Dependencies**: Spec 156 (operator-outcome-taxonomy), Spec 157 (reason-code-translation), Spec 158 (artifact-truth-semantics), canonical operation viewer work, shared governance detail templates
- **Related specs / candidates**: Spec 144 (canonical operation viewer context decoupling), Spec 153 (evidence-domain-foundation), Spec 155 (tenant-review-layer), Spec 158 (artifact-truth-semantics), Governance Operator Outcome Compression candidate
- **Strategic sequencing**: Best treated as the run-detail explainability companion to Governance Operator Outcome Compression. Compression improves governance artifact scan surfaces; this candidate makes governance run detail self-explanatory once an operator drills in.
- **Priority**: high

### Operator Explanation Layer for Degraded / Partial / Suppressed Results
- **Type**: cross-cutting UX / domain semantics / operator clarity
- **Source**: product analysis 2026-03-23; direct follow-up to Spec 156 (`operator-outcome-taxonomy`)
- **Vehicle**: new standalone candidate
- **Problem**: Spec 156 improves status, outcome, and run vocabulary, but pure outcome taxonomy does not resolve a deeper operator-readability gap: the product stores truth across multiple semantic dimensions (execution, evaluation, reliability, coverage, recommended action) that are currently presented side by side without separation or explanation. Several governance and operational surfaces — Baseline Compare, Baseline Capture, Operation Run detail, Tenant Reviews, evidence-dependent results — show technically correct but operatorisch schwer lesbare combinations such as `Run finished` + `Counts 0` + `Why no findings: evidence_capture_incomplete`. These force operators to synthesize whether: the run was technically successful, the result is trustworthy, findings were genuinely absent, data was missing, assignments were ambiguous, or follow-up is required. The product preserves truth better than it explains truth. Distinct truth dimensions collapse into shared reading surfaces — count blocks that look like complete results when they show only a subset, `0 findings` that reads as reassurance when evaluation was incomplete, reason codes that serve as primary operator explanation when they are diagnostic material. Enterprise operators need the UI to make without JSON and without implicit product knowledge clear: what happened, how reliable the result is, and what to do next.
- **Why it matters**: This is the missing interpretation layer between the outcome taxonomy foundation (Spec 156) and the operator's actual decision. Without it, the product remains formally correct but interpretively weak on its highest-trust governance surfaces. Concrete consequences: operators read `0 findings` as all-clear when evaluation was constrained by evidence gaps; support and debug cost stays high because run-detail pages require JSON or expert knowledge; reason codes leak into operator surfaces as primary explanation; semantic inconsistencies multiply with each new governance/evidence/review feature; enterprise readiness suffers despite strong internal modelling. The gap is systemic — not a single-surface fix — because the same class of problem (execution succeeded, but result is degraded/partial/suppressed) recurs across baselines, reviews, evidence, monitoring, and future governance domains.
- **Proposed direction**:
  - **R1 — Multi-dimensional outcome model in the UI**: operator surfaces must separate result communication into at least five distinguishable axes: execution status, evaluation result, reliability/confidence/trustworthiness, coverage/completeness, recommended action. Not every page needs all five equally prominent, but the UI model must keep them distinct instead of collapsing them into a single badge or count block.
  - **R2 — Primary operator explanation over raw reason codes**: every relevant reason code or reason cluster gets an operator-readable title, clear meaning description, impact explanation, and next-step guidance. Technical reason codes remain stored and diagnostically usable but stop being the primary explanation. Example: not `evidence_capture_incomplete` as the headline, but "Vergleich unvollständig bewertet — 16 Evidence-Lücken verhinderten vollständige Bewertung."
  - **R3 — Semantically unambiguous counts**: count blocks must not imply completeness when they represent only a subset. The spec defines which counts are execution counts, which are evaluation-output counts, which are data-quality/completeness counts, and how suppressed/incomplete/degraded states surface. `0 findings` when evidence gaps exist must not read as reassurance.
  - **R4 — "Why no findings / no results / no report" explanation patterns**: a shared pattern for explaining absent output, distinguishing between genuinely no issues found, no results producible due to missing inputs, results suppressed due to unreliable evidence, prerequisite failure, viewer/rendering limitation, pending calculation, and intentionally unpublished.
  - **R5 — Reliability/confidence visibility**: compare-, review-, and evidence-dependent results must show whether the result is trustworthy, limited in trustworthiness, incomplete, diagnostically usable but not decision-grade, or not usable. Terms like fidelity, coverage, partial, meta, full, degraded get a defined reading direction instead of appearing loosely side by side.
  - **R6 — Semantically derived next-step guidance**: the next-step surface must distinguish between no action needed, observe, re-run, fix prerequisite, update inventory/sync, check evidence gaps, manually validate, and escalate — derived from cause and severity, not a generic fallback phrase.
  - **R7 — Diagnostics available but not dominant**: technical raw data, run context, and reason codes remain accessible for debugging but the default reading path leads with meaning and action: what happened → how reliable → why it looks this way → what to do → then technical details.
  - **R8 — Shared explanation patterns, not page-by-page special logic**: define reusable cross-domain explanation patterns: completed but degraded, completed but incomplete, no output because suppressed, no output because insufficient evidence, partial result with fallback, output exists but not publication-ready, viewer limitation vs source limitation, prerequisite missing vs execution failed.
  - **R9 — Baseline Compare as reference case**: Baseline Compare is the golden path for this spec. The case where compare finishes technically, driftResults = 0, counts = 0, evidence gaps exist, and "why no findings" is currently reason-code-heavy must become immediately understandable without additional product knowledge.
  - **R10 — No contradiction between top-level state and detail interpretation**: top-level states (run finished, completed with follow-up, succeeded, partially succeeded) must not conflict with the underlying result surfaces. Technically successful but fachlich limited results must read as a consistent composite.
- **Primary adoption surfaces**:
  - Operation Run detail pages
  - Baseline Capture
  - Baseline Compare
  - Baseline Snapshot / Compare truth surfaces
  - Tenant Reviews / review generation states
  - Evidence-dependent result surfaces
  - Run summaries, state banners, next-step texts, count summaries
  - Reason code presentation / translation layer
  - Count semantics for runs with suppressed / incomplete / degraded results
- **Optional extension surfaces**: restore/backup operation outcomes, prerequisite/readiness/missing-input explanation surfaces, alerts that rely on degraded semantics
- **UX/semantics principles**:
  - Truth first, but operator-first wording — truth is not softened but expressed in readable operator language
  - No false reassurance — `0 findings` or `no errors` must not read as all-clear when evaluation was constrained
  - Separate execution from confidence — a technically successful run can still produce a limited-confidence result
  - Default path before diagnostics — the normal reading flow answers meaning and action first, then technical detail
  - Consistent semantics across domains — the same kind of state must not be named or explained differently in baselines, reviews, and evidence
- **Scope boundaries**:
  - **In scope**: explanation dimension definitions, outcome-to-operator-message mapping, shared explanation pattern library, reference implementation for Baseline Compare / Operation Run detail / Baseline Capture, count semantics rules, reliability visibility rules, next-step guidance patterns, reason code presentation hierarchy
  - **Out of scope**: queue/retry/job-runtime model redesign, large-scale raw data model restructuring (existing run-context data should suffice), purely visual polishing without semantic improvement, reason code elimination (they remain for diagnostics), complete redesign of every product page, compliance/governance domain logic changes
- **Phased delivery**:
  - Phase 1 — Semantics model: define explanation dimensions, outcome vs reliability vs coverage vs action separation, reason-code-to-operator-message mapping, shared explanation pattern library
  - Phase 2 — Reference implementation: Operation Run detail page, Baseline Compare, Baseline Capture
  - Phase 3 — Extension: Tenant Reviews, evidence/report surfaces, further degraded/prerequisite-heavy flows
- **Success criteria**:
  - An operator can understand degraded/suppressed results without JSON: what was executed, whether results were produced, how reliable they are, why nothing was generated, and what to do next
  - Baseline Compare with 0 findings + evidence gaps shows no implicit all-clear
  - Reason codes remain technically usable but no longer serve as sole primary explanation
  - Count surfaces are semantically unambiguous, distinguishing output counts from completeness/reliability signals
  - At least one shared explanation pattern is reused across domains rather than landing as one-off page logic
- **Dependencies**: Spec 156 (operator-outcome-taxonomy — shared vocabulary foundation), Spec 157 (reason-code-translation — humanized code labels), Spec 158 (artifact-truth-semantics — governance artifact truth model), Spec 159 (baseline-snapshot-truth — baseline truth surfaces)
- **Related specs / candidates**: Governance Operator Outcome Compression (governance-artifact list/scan compression — complementary, narrower scope), Humanized Diagnostic Summaries for Governance Operations (governance run-detail explainability — complementary, narrower scope), Baseline Capture Truthful Outcomes (capture-specific precondition and outcome hardening), OperationRun Humanization & Diagnostics Boundary (run-detail operator-first hierarchy)
- **Strategic importance**: This is not UI polish but an enterprise-readability and governance-trust layer. As the roadmap expands toward baseline governance, findings workflow, exceptions/risk acceptance, stored reports, tenant reviews, evidence packs, and MSP portfolio views, the cost of not having a systematic explanation layer increases with every new feature. The longer this is deferred, the more governance surfaces ship with locally invented explanation patterns that diverge instead of converging. This candidate is strategically anschlussfähig rather than locally reactive.
- **Priority**: high

> **Operator Truth Initiative — Sequencing Note**
>
> The operator-truth work now has two connected lanes: a shared truth-foundation lane and a governance-surface compression lane. Together they address the systemic gap between backend truth richness and operator-facing truth quality without forcing operators to parse raw internal semantics.
>
> **Recommended order:**
> 1. **Operator Outcome Taxonomy and Cross-Domain State Separation** — defines the shared vocabulary, state-axis separation rules, and color-severity conventions that all other operator-facing work references. This is the smallest deliverable (a reference document + restructuring guidelines) but the highest-leverage decision. Without it, the other candidates will invent local vocabularies that diverge.
> 2. **Operator Reason Code Translation and Humanization Contract** — defines the translation bridge from internal codes to operator-facing labels using the Outcome Taxonomy's vocabulary. Can begin in parallel with the taxonomy using pragmatic interim labels, but final convergence depends on the taxonomy.
> 3. **Governance Artifact Truthful Outcomes & Fidelity Semantics** — establishes the full internal truth model for governance artifacts, keeping existence, usability, freshness, completeness, publication readiness, and actionability distinct.
> 4. **Operator Explanation Layer for Degraded / Partial / Suppressed Results** — defines the cross-cutting interpretation layer that turns internal truth dimensions into operator-readable explanation: multi-dimensional outcome separation (execution, evaluation, reliability, coverage, action), shared explanation patterns for degraded/partial/suppressed states, count semantics rules, "why no findings" patterns, and reliability visibility. Consumes the taxonomy, translation, and artifact-truth foundations; provides the shared explanation pattern library that compression and humanized summaries adopt on their respective surfaces. Baseline Compare is the golden-path reference implementation.
> 5. **Governance Operator Outcome Compression** — applies the foundation and explanation layer to governance workflow surfaces so lists and details answer the operator's primary question first, while preserving diagnostics as second-layer detail.
> 6. **Humanized Diagnostic Summaries for Governance Operations** — the run-detail explainability companion to compression; makes governance run detail self-explanatory using the explanation patterns established in step 4.
> 7. **Provider-Backed Action Preflight and Dispatch Gate Unification** — extends the proven Gen 2 gate pattern to all provider-backed operations and establishes a shared result presenter. Benefits from the shared vocabulary work but remains a parallel hardening lane rather than a governance-surface adoption slice.
>
> **Why this order rather than the inverse:** The semantic-clarity audit classified the taxonomy problem as P0 (60% of warning badges are false alarms — actively damages operator trust). Reason code translation creates the shared human-facing language. Spec 158 establishes the correct internal truth engine for governance artifacts. The Operator Explanation Layer then defines the cross-cutting interpretation patterns that all downstream surfaces need — the systemwide rules for how degraded, partial, suppressed, and incomplete results are separated, explained, and acted upon. Compression and humanized summaries are adoption slices that apply those patterns to specific surface families (governance artifact lists and governance run details respectively). Gate unification remains highly valuable but is a neighboring hardening lane.
>
> **Why these are not one spec:** Each candidate has a different implementation surface, different stakeholders, and different shippability boundary. The taxonomy is a cross-cutting decision document. Reason code translation touches reason-code artifacts and notification builders. Spec 158 defines the richer artifact truth engine. The Operator Explanation Layer defines the shared interpretation semantics and explanation patterns. Governance operator outcome compression is a UI-information-architecture adoption slice across governance artifact surfaces. Humanized diagnostic summaries are an adoption slice for governance run-detail pages. Gate unification touches provider dispatch and notification plumbing across ~20 services. Merging them would create an unshippable monolith. Keeping them sequenced preserves independent delivery while still converging on one operator language.

### Operation Run Active-State Visibility & Stale Escalation
- **Type**: hardening
- **Source**: product/operator visibility analysis 2026-03-24; operation-run lifecycle and stale-state communication review
- **Vehicle**: new standalone candidate
- **Problem**: TenantPilot already has the core lifecycle foundations for `OperationRun` records: canonical run modelling, workspace-level run viewing, per-type lifecycle policies, freshness and stale detection, overdue-run reconciliation, terminal notifications, and tenant-local active-run hints. The gap is no longer primarily lifecycle logic. The gap is that the same lifecycle truth is not communicated with enough consistency and urgency across the operator surfaces that matter. A run can be past its expected lifecycle or likely stuck while still looking like normal active work on tenant-local cards or dashboard attention surfaces. Operators then have to drill into the canonical run viewer to learn that the run is no longer healthy, which weakens monitoring trust and makes hanging work look deceptively normal.
- **Why it matters**: This is an observability and operator-trust problem in a core platform layer, not visual polish. If `queued` or `running` remains visually neutral after lifecycle expectations have been exceeded, operators receive false reassurance, support burden rises, queue or worker issues are discovered later, and the product trains users that active-state surfaces are not trustworthy without manual drill-down. As TenantPilot pushes more governance, review, drift, and evidence workflows through `OperationRun`, stale active work must never read as healthy progress anywhere in the product.
- **Proposed direction**:
  - Reuse the existing lifecycle, freshness, and reconciliation truth to define one **cross-surface active-state presentation contract** that distinguishes at least: `active / normal`, `active / past expected lifecycle`, `stale / likely stuck`, and `terminal / no longer active`
  - Upgrade **tenant-local active-run and progress cards** so stale or past-lifecycle runs are visibly and linguistically different from healthy active work instead of reading as neutral `Queued • 1d` or `Running • 45m`
  - Upgrade **tenant dashboard and attention surfaces** so they distinguish between healthy activity, activity that needs attention, and activity that is likely stale or hanging
  - Upgrade the **workspace operations list / monitoring views** so problematic active runs become scanable at row level instead of being discoverable only through subtle secondary text or by opening each run
  - Preserve the **workspace-level canonical run viewer** as the authoritative diagnostic surface, while ensuring compact and summary surfaces do not contradict it
  - Apply a **same meaning, different density** rule: tenant cards, dashboard signals, list rows, and run detail may vary in information density, but not in lifecycle meaning or operator implication
- **Core product principles**:
  - Execution lifecycle, freshness, and operator attention are related but not identical dimensions
  - Compact surfaces may compress information, but must not downplay stale or hanging work
  - The workspace-level run viewer remains canonical; this candidate improves visibility, not source-of-truth ownership
  - Stale or past-lifecycle work must not look like healthy progress anywhere
- **Candidate requirements**:
  - **R1 Cross-surface lifecycle visibility**: all relevant active-run surfaces can distinguish at least normal active, past-lifecycle active, stale/likely stuck, and terminal states
  - **R2 Tenant active-run escalation**: tenant-local active-run and progress cards visibly and linguistically escalate stale or past-lifecycle work
  - **R3 Dashboard attention separation**: dashboard and attention surfaces distinguish healthy activity from concerning active work
  - **R4 Operations-list scanability**: the workspace operations list makes problematic active runs quickly identifiable without requiring row-by-row interpretation or drill-in
  - **R5 Canonical viewer preservation**: the workspace-level run viewer remains the detailed and authoritative truth surface
  - **R6 No hidden contradiction**: a run that is clearly stale or lifecycle-problematic on the detail page must not appear as ordinary active work on tenant or monitoring surfaces
  - **R7 Existing lifecycle logic reuse**: the candidate reuses current freshness, lifecycle, and reconciliation semantics instead of introducing parallel UI-only heuristics
  - **R8 No new backend lifecycle semantics unless necessary**: new status values or model-level lifecycle semantics are out unless the current semantics cannot carry the presentation contract cleanly
- **Scope boundaries**:
  - **In scope**: tenant-local active-run cards, tenant dashboard activity and attention surfaces, workspace operations list and monitoring surfaces, shared lifecycle presentation contract for active-state visibility, copy and visual semantics needed to distinguish healthy active work from stale active work
  - **Out of scope**: retry, cancel, force-fail, or reconcile-now operator actions; queue or worker architecture changes; new scheduler or timeout engines; new notification channels; a full operations-hub redesign; cross-workspace fleet monitoring; introducing new `OperationRun` status values unless existing semantics are proven insufficient
- **Acceptance points**:
  - An active run outside its lifecycle expectation is visibly distinct from healthy active work on tenant-local progress cards
  - Tenant dashboard and attention surfaces clearly represent the difference between healthy activity and active work that needs attention
  - The workspace operations list makes stale or problematic active runs quickly scanable
  - No surface shows a run as stale/problematic while another still presents it as normal active work
  - The canonical workspace-level run viewer remains the most detailed lifecycle and diagnosis surface
  - Existing lifecycle and freshness logic is reused rather than duplicated into local UI-only state rules
  - No retry, cancel, or force-fail intervention actions are introduced by this candidate
  - Fresh active runs do not regress into false escalation
  - Tenant and workspace scoping remain correct; no cross-tenant leakage appears in cards or monitoring views
  - Regression coverage includes fresh and stale active runs across tenant and workspace surfaces
- **Suggested test matrix**:
  - queued run within expected lifecycle
  - queued run well past expected lifecycle
  - running run within expected lifecycle
  - running run well past expected lifecycle
  - run becomes terminal while an operator navigates between tenant and run-detail surfaces
  - stale state on detail surface remains semantically stale on tenant and monitoring surfaces
  - fresh active runs do not escalate falsely
  - tenant-scoped surfaces never show another tenant's runs
  - operations list clearly surfaces problematic active runs for fast scan
- **Dependencies**: existing operation-run lifecycle policy and stale detection foundations, canonical run viewer work, tenant-local active-run surfaces, operations monitoring list surfaces
- **Related specs / candidates**: Spec 114 (system console / operations monitoring foundations), Spec 144 (canonical operation viewer context decoupling), Spec 149 (queued execution reauthorization and lifecycle continuity), Operator Explanation Layer for Degraded / Partial / Suppressed Results (adjacent but broader interpretation layer), Provider-Backed Action Preflight and Dispatch Gate Unification (neighboring operational hardening lane)
- **Strategic sequencing**: Best treated before any broader operator intervention-actions spec. First make stale or hanging work visibly truthful across all existing surfaces; only then add retry / force-fail / reconcile-now UX on top of a coherent active-state language.
- **Priority**: high

### Baseline Snapshot Fidelity Semantics
- **Type**: hardening
- **Source**: semantic clarity & operator-language audit 2026-03-21
- **Vehicle**: new standalone candidate
- **Problem**: Baseline snapshots currently conflate renderer maturity, capture depth, metadata-only capture modes, and real API/capture failures into operator-facing fidelity and gap badges. `FidelityState`, `GapSummary`, and related baseline snapshot presentation surfaces make standard-renderer or summary-only situations read like governance warnings. The result is a high-volume false-warning pattern on one of the product's most frequently scanned detail surfaces.
- **Why it matters**: This is the single highest-volume false-warning source identified in the audit. If baseline surfaces keep teaching operators that yellow means "the product used a standard renderer" instead of "you should investigate a governance problem," every later baseline warning becomes less credible.
- **Proposed direction**: Create a bounded baseline-specific follow-up that consumes the Operator Outcome Taxonomy and separates snapshot-internal fidelity semantics from diagnostic renderer metadata. Split gap causes into product limitation vs capture-mode choice vs actual capture problem, move product-support facts to diagnostics, and replace vague snapshot labels such as "Captured with gaps" with truthful operator language tied to the correct axis.
- **Dependencies**: Operator Outcome Taxonomy and Cross-Domain State Separation, Structured Snapshot Rendering (Spec 130)
- **Priority**: high

### Baseline Compare Scope Guardrails & Ambiguity Guidance
- **Type**: hardening
- **Source**: product/operator-trust analysis 2026-03-24 — baseline compare ambiguity and scope communication review
- **Vehicle**: new standalone candidate
- **Problem**: Baseline Compare currently produces confusing results when the baseline snapshot contains generic Microsoft/Intune default objects or subjects with non-unique display names. Not-uniquely-matchable subjects are surfaced as "duplicates" in the UI, implying operator error even when the root cause is provider-side generic naming. Separate truth dimensions — identity confidence (could subjects be matched uniquely?), evidence fidelity (how deep was the compare?), and result trust (how reliable is the overall outcome?) — are collapsed into ambiguous operator signals such as `No Drift Detected` + `Limited confidence` + `Fidelity: Meta` without explaining whether the issue is baseline scope, generic names, limited compare capability, or actual tenant drift.
- **Why it matters**: Operators reading compare results cannot distinguish between "everything is fine" and "we couldn't compare reliably." False reassurance (`No Drift Detected` at limited confidence) and false blame ("rename your duplicates" when subjects are provider-managed defaults) erode trust in the product's core governance promise. MSP operators managing baselines for multiple tenants need clear signals about what they can rely on and what requires scope curation — not academic-sounding fidelity labels next to misleading all-clear verdicts.
- **Product decision**: Baseline Compare in V1 is designed for uniquely identifiable, intentionally curated governance policies — not for arbitrary tenant-wide default/enrollment/generic standard objects. When compare subjects cannot be reliably matched due to generic names or weak identity, TenantPilot treats this primarily as a scope/suitability problem of the current baseline content and a transparency/guidance topic in the product — not as an occasion for building a large identity classification engine.
- **Proposed direction**:
  - **Compare wording correction**: replace pausal "rename your duplicates" messaging with neutral, scope-aware language explaining that some subjects cannot be matched uniquely by the current compare strategy, that this can happen with generic or provider-managed display names, and that the visible result is therefore only partially reliable
  - **Scope guidance on compare surfaces**: make explicit that Baseline Compare is for curated governance-scope policies, not for every tenant content. Baseline/capture surfaces must frame Golden Master as a deliberate governance scope, not an unfiltered tenant full-extract
  - **Actionable next-step guidance**: when ambiguity is detected, direct operators to review baseline profile scope, remove non-uniquely-identifiable subjects from governance scope, and re-run compare after scope cleanup — not to pauschal rename everything
  - **Meta-fidelity and limited-confidence separation**: separate identity-matchability, evidence/compare-depth, and overall result trustworthiness in the communication so operators can tell which dimension is limited and why
  - **Conservative framing for problematic V1 domains**: for known generically-named compare domains, allow conservative copy such as "not ideal for baseline compare," "limited compare confidence," "review scope before relying on result" — without introducing deep system-managed default detection
  - **Evidence/snapshot surface consistency**: terms like `Missing input`, `Not collected yet`, `Limited confidence` must not read as runtime errors when the actual issue is scope suitability
- **Scope boundaries**:
  - **In scope**: compare result warning copy, limited-confidence explanation, next-step guidance, baseline profile/capture scope framing, conservative guardrail copy for problematic domains, evidence/snapshot surface term consistency
  - **Out of scope**: comprehensive Microsoft default policy detection, new global identity strategy engine, object-class-based system-managed vs user-managed classification, new deep fidelity matrix for all policy types, automatic exclusion or repair of problematic baseline items, compare engine architecture redesign
- **UX direction**:
  - **Bad (current)**: "32 policies share the same display name" / "Please rename the duplicates" / `No Drift Detected` despite `Limited confidence`
  - **Good (target)**: neutral, honest, operator-actionable — e.g. "Some policies in the current baseline scope cannot be matched uniquely by the current compare strategy. This often happens with generic or provider-managed display names. Review your baseline scope and keep only uniquely identifiable governance policies before relying on this result."
- **Acceptance criteria**:
  - AC1: ambiguous-match UI no longer pauschal blames operators for duplicates without explaining scope/generic-name context
  - AC2: limited-trust compare results are visually and linguistically distinguishable from fully reliable results; operators can tell the result is technically complete but content-wise only partially reliable
  - AC3: primary V1 guidance directs operators to baseline-scope review/cleanup and re-compare — not to pauschal rename or assume tenant misconfiguration
  - AC4: baseline/compare surfaces convey that Golden Master is a curated governance scope
  - AC5: `No Drift Detected` at `Limited confidence` is understandable as not-fully-trustworthy, not as definitive all-clear
- **Tests / validation**:
  - Warning text for ambiguous matches uses neutral scope/matchability wording
  - Next-step guidance points to baseline scope review, not pauschal rename
  - `Limited confidence` + `No Drift Detected` is not presented as unambiguous all-clear
  - Baseline/compare surfaces include governance-scope hint
  - Known compare gaps do not produce misleading "user named everything wrong" messaging
  - Existing compare status/outcome logic remains intact
  - No new provider-specific special classification logic required for consistent UI
- **Risks**:
  - R1: pure copy changes alone might address the symptom too weakly → mitigation: include scope/guidance framing, not just single-sentence edits
  - R2: too much guidance without technical guardrails might let operators keep building bad baselines → mitigation: conservative framing and later evolution via real usage data
  - R3: team reads this spec as a starting point for large identity architecture → mitigation: non-goals are explicitly and strictly scoped
- **Roadmap fit**: Aligns directly with Release 1 — Golden Master Governance (R1.1 BaselineProfile, R1.3 baseline.compare, R1.4 Drift UI: Soll vs Ist). Improves V1 sellability without domain-model expansion: less confusing drift communication, clearer Golden Master story, no false operator blame, better trust basis for compare results.
- **Dependencies**: Baseline drift engine stable (Specs 116–119), Baseline Snapshot Fidelity Semantics candidate (complementary — snapshot-level fidelity clarity), Operator Explanation Layer candidate (consumes explanation patterns), Governance Operator Outcome Compression candidate (complementary — governance artifact presentation)
- **Related specs / candidates**: Specs 116–119 (baseline drift engine), Spec 101 (baseline governance), Baseline Capture Truthful Outcomes candidate, Baseline Snapshot Fidelity Semantics candidate, Operator Explanation Layer candidate, Governance Operator Outcome Compression candidate
- **Recommendation**: Treat before any large matching/identity extension. Small enough for V1, reduces real operator confusion, protects against scope creep, and sharpens the product message: TenantPilot compares curated governance baselines — not blindly every generic tenant default content.
- **Priority**: high

### Restore Lifecycle Semantic Clarity
- **Type**: hardening
- **Source**: semantic clarity & operator-language audit 2026-03-21
- **Vehicle**: new standalone candidate
- **Problem**: Restore flows currently overload run-level status, item-level result status, preview decision state, and manual follow-up guidance into a vocabulary that is too ambiguous for a safety-critical workflow. "Partial" means different things at different levels, preview and apply states are visually too close, and blocked/manual-required states do not consistently tell operators what happened or what to do next.
- **Why it matters**: Restore is one of the few product areas where semantic ambiguity can directly lead to the wrong remediation action. Operators need to know whether a tenant is in a consistent state, which items were skipped intentionally versus prevented by prerequisites, and whether the next step is retry, manual completion, or no action.
- **Proposed direction**: Define a restore-specific semantic cleanup that consumes the taxonomy and rationalizes run lifecycle, item results, preview decisions, and next-action language without changing restore execution mechanics. The candidate should reduce ambiguous states, quantify mixed outcomes, and move raw technical detail behind secondary diagnostics.
- **Dependencies**: Operator Outcome Taxonomy and Cross-Domain State Separation, restore-run and restore-preview surfaces already delivered through the restore spec family
- **Priority**: high

### Inventory, Provider & Operability Semantics
- **Type**: hardening
- **Source**: semantic clarity & operator-language audit 2026-03-21
- **Vehicle**: new standalone candidate
- **Problem**: Inventory KPI badges, provider connection status labels, sync/prerequisite messages, verification outcomes, and onboarding helper messages all reuse warning language for product/platform readiness facts that are not the same as governance problems. "Metadata only," "Needs attention," "Blocked," degraded provider health, and onboarding prerequisite messages currently collapse prerequisite state, stale verification state, and product support tier into one operator-facing severity bucket.
- **Why it matters**: These surfaces shape daily operator trust and first-run product impression. If inventory and onboarding surfaces treat every prerequisite or product-tier distinction like a warning, operators either ignore the guidance or cannot tell what actually needs intervention.
- **Proposed direction**: Create a single operability-semantic candidate that consumes the taxonomy and normalizes how inventory capture mode, provider health/prerequisites, verification results, and onboarding next-step messaging are presented. The candidate should make prerequisite state and recovery guidance explicit while demoting pure product-maturity facts to neutral/diagnostic treatment.
- **Dependencies**: Operator Outcome Taxonomy and Cross-Domain State Separation, provider connection vocabulary/cutover work, onboarding and verification spec family
- **Priority**: medium

### Tenant Operational Readiness & Status Truth Hierarchy
- **Type**: hardening
- **Source**: product/operator-trust analysis 2026-03-24 — tenant-facing status presentation and source-of-truth hierarchy review
- **Vehicle**: new standalone candidate
- **Problem**: Tenant-facing surfaces expose multiple parallel status domains — lifecycle, legacy app status, provider connection state, provider health, verification report availability, RBAC readiness, and recent run evidence — without a clear hierarchy. Some domains are valid but poorly explained; at least one (`Tenant.app_status`) is legacy/orphaned truth still presented as if authoritative. The combined presentation does not answer the operator's actual question: "Can I trust this tenant right now, and is any action required?" Instead, operators must mentally reconcile six semi-related status fragments with no clear precedence, creating three distinct risks: legacy truth leakage (dead fields displayed as current truth), state collision without hierarchy (valid domains answering different questions but appearing to compete), and support/trust burden (operators asking why a tenant is "active" yet also "unknown," or provider is "connected" but health is "unknown," even when operational evidence proves usability).
- **Why it matters**: TenantPilot is moving further into governance, evidence, reviews, drift, and portfolio visibility. As the product becomes more compliance- and operations-centric, source-of-truth quality on core tenant surfaces becomes more important, not less. If left unresolved: support load scales with tenant count, MSP operators learn to distrust or ignore status surfaces, future governance views inherit ambiguous foundations, and headline truth across baselines, evidence, findings, and reviews remains semantically inconsistent. For an enterprise governance platform, this is a product-truth and operator-confidence issue, not just a wording problem.
- **Core insight**: Not every status belongs at the same level. The product currently exposes multiple truths belonging to different semantic layers:
  - **Layer 1 — Headline operator truth**: "Can I work with this tenant, and is action required?"
  - **Layer 2 — Domain truth**: lifecycle, provider consent/access, verification, RBAC, recent operational evidence
  - **Layer 3 — Diagnostic truth**: low-level or specialized states useful for investigation, not competing with headline summary
  - **Layer 4 — Legacy/orphaned truth**: stale, weakly maintained, deprecated, or no longer authoritative fields
- **Proposed direction**:
  - **Headline readiness model**: define a single tenant-facing readiness summary answering whether the tenant is usable and whether action is needed. Concise operator-facing states such as: Ready, Ready with follow-up, Limited, Action required, Not ready.
  - **Source-of-truth hierarchy**: every tenant-facing status shown on primary surfaces classified as authoritative, derived, diagnostic, or legacy. Authoritative sources: lifecycle, canonical provider consent/access state, canonical verification state, RBAC readiness, recent operational evidence as supporting evidence.
  - **Domain breakdown beneath headline**: each supporting domain exists in a clearly subordinate role — lifecycle, provider access/consent, verification state, RBAC readiness, recent operational evidence.
  - **Action semantics clarity**: primary surfaces must distinguish between no action needed, recommended follow-up, required action, and informational only.
  - **Verification semantics**: UI must distinguish between never verified, verification unavailable, verification stale, verification failed, and verified but follow-up recommended. These must not collapse into ambiguous "unknown" messaging.
  - **Provider truth clarity**: provider access state must clearly differentiate access configured/consented, access verified, access usable but not freshly verified, access blocked or failed.
  - **RBAC semantics clarity**: RBAC readiness must clearly state whether write actions are blocked, without implying that all tenant operations are unavailable when read-only operations still function.
  - **Operational evidence handling**: recent successful operations may contribute supporting confidence, but must not silently overwrite or replace distinct provider verification truth.
  - **Legacy truth removal/demotion**: fields that are legacy, orphaned, or too weak to serve as source of truth must not remain prominent on tenant overview surfaces. Explicit disposition for orphaned fields like `Tenant.app_status`.
  - **Reusable semantics model**: the resulting truth hierarchy and readiness model must be reusable across tenant list/detail and future higher-level governance surfaces.
- **Functional requirements**:
  - FR1 — Single tenant-facing readiness summary answering operability and action-needed
  - FR2 — Every primary-surface status classified as authoritative, derived, diagnostic, or legacy
  - FR3 — Legacy/orphaned fields not displayed as current operational truth on primary surfaces
  - FR4 — No peer-level contradiction on primary surfaces
  - FR5 — Verification semantics explicitly distinguishing not yet verified / unavailable / stale / failed / verified with follow-up
  - FR6 — Provider access state clearly differentiating configured, verified, usable-but-not-fresh, blocked
  - FR7 — RBAC readiness clarifying write-block vs full-block
  - FR8 — Operational evidence supportive but not substitutive for verification truth
  - FR9 — Actionability clarity on primary surfaces
  - FR10 — Reusable semantics for future governance surfaces
- **UX/product rules**:
  - Same question, one answer: if several states contribute to the same operator decision, present one synthesized answer first
  - Summary before diagnostics: operator summary belongs first, domain detail underneath or behind expansion
  - "Unknown" is not enough: must not substitute for not checked, no report stored, stale result, legacy field, or unavailable artifact
  - Evidence is supportive, not substitutive: successful operations reinforce confidence but do not replace explicit verification
  - Lifecycle is not health: active does not mean provider access is verified or write operations are ready
  - Health is not onboarding history: historical onboarding verification is not automatically current operational truth
- **Likely surfaces affected**:
  - Primary: tenant detail/overview page, tenant list presentation, tenant widgets/cards related to verification and recent operations, provider-related status presentation within tenant views, helper text/badge semantics on primary tenant surfaces
  - Secondary follow-up: provider connection detail pages, onboarding completion/follow-up states, future portfolio rollup views
- **Scope boundaries**:
  - **In scope**: truth hierarchy definition, headline readiness model, tenant detail/overview presentation rules, provider state presentation rules on tenant surfaces, verification semantics on tenant surfaces, RBAC relationship to readiness, role of recent operational evidence, legacy truth cleanup on primary tenant surfaces
  - **Out of scope**: redesigning OperationRun result semantics in general, revisiting every badge/helper in the product, evidence/reporting semantics outside tenant readiness, changing onboarding lifecycle requirements unless directly necessary for truth consistency, provider architecture overhaul, full data-model cleanup beyond what is needed to remove legacy truth from primary surfaces, full badge taxonomy standardization everywhere, color palette / visual design overhaul, findings severity or workflow semantics, broad IA/navigation redesign, portfolio-level rollup semantics beyond stating compatibility goals
- **Acceptance criteria**:
  - AC1: Primary tenant surfaces present a single operator-facing readiness truth rather than several equal-weight raw statuses
  - AC2: Lifecycle, provider access, verification, RBAC, and operational evidence shown with explicit semantic roles and no ambiguous precedence
  - AC3: Legacy/orphaned status fields no longer presented as live operational truth on primary surfaces
  - AC4: System clearly differentiates not yet verified / verification unavailable / stale / failed
  - AC5: Operator can tell within seconds whether tenant is usable / usable with follow-up / limited / blocked / in need of action
  - AC6: Recent successful operations reinforce confidence where appropriate but do not silently overwrite explicit verification truth
  - AC7: Primary tenant status communication suitable for MSP/enterprise use without requiring tribal knowledge to interpret contradictions
- **Boundary with Tenant App Status False-Truth Removal**: That candidate is a quick, bounded removal of the single most obvious legacy truth field (`Tenant.app_status`). This candidate defines the broader truth hierarchy and presentation model that decides how all tenant status domains interrelate. The false-truth removal is a subset action that can proceed independently as a quick win; this candidate provides the architectural direction that prevents future truth leakage.
- **Boundary with Provider Connection Status Vocabulary Cutover**: Provider vocabulary cutover owns the `ProviderConnection` model-level status field cleanup (canonical enum sources replacing legacy varchar fields). This candidate owns how provider truth appears on tenant-level surfaces in relation to other readiness domains. The vocabulary cutover provides cleaner provider truth; this candidate defines where and how that truth is presented alongside lifecycle, verification, RBAC, and evidence.
- **Boundary with Inventory, Provider & Operability Semantics**: That candidate normalizes how inventory capture mode, provider health/prerequisites, and verification results are presented on their own surfaces. This candidate defines the tenant-level integration layer that synthesizes those domain truths into a single headline readiness answer. Complementary: domain-level semantic cleanup feeds into the readiness model.
- **Boundary with Operator Explanation Layer**: The explanation layer defines cross-cutting interpretation patterns for degraded/partial/suppressed results. This candidate defines the tenant-specific readiness truth hierarchy. The explanation layer may inform how degraded readiness states are explained, but the readiness model itself is tenant-domain-specific.
- **Boundary with Governance Operator Outcome Compression**: Governance compression improves governance artifact scan surfaces. This candidate improves tenant operational readiness surfaces. Both reduce operator cognitive load but on different product domains.
- **Dependencies**: Operator Outcome Taxonomy and Cross-Domain State Separation (shared vocabulary foundation), Tenant App Status False-Truth Removal (quick win that removes the most obvious legacy truth — can proceed independently before or during this spec), Provider Connection Status Vocabulary Cutover (cleaner provider truth sources — soft dependency), existing tenant lifecycle semantics (Spec 143)
- **Related specs / candidates**: Spec 143 (tenant lifecycle operability context semantics), Tenant App Status False-Truth Removal, Provider Connection Status Vocabulary Cutover, Provider Connection UX Clarity, Inventory Provider & Operability Semantics, Operator Outcome Taxonomy (Spec 156), Operation Run Active-State Visibility & Stale Escalation
- **Strategic sequencing**: Best tackled after the Operator Outcome Taxonomy provides shared vocabulary and after Tenant App Status False-Truth Removal removes the most obvious legacy truth as a quick win. Should land before major portfolio, MSP rollup, or compliance readiness surfaces are built, since those surfaces will inherit the tenant readiness model as a foundational input.
- **Priority**: high

### Exception / Risk-Acceptance Workflow for Findings
- **Type**: feature
- **Source**: HANDOVER gap analysis, Spec 111 follow-up
- **Problem**: Finding has a `risk_accepted` status value but no formal exception lifecycle. Today, accepting risk is a status transition — there is no dedicated entity to record who accepted the risk, why, under what conditions, or when the acceptance expires. No approval workflow, no expiry/renewal semantics, no structured justification. Auditors cannot answer "who accepted this risk, what was the justification, and is it still valid?"
- **Why it matters**: Enterprise compliance frameworks (ISO 27001, SOC 2, CIS) require documented, time-bounded risk acceptance with clear ownership. A bare status flag does not meet this bar. Without a formal exception lifecycle, risk acceptance becomes invisible to audit trails and impossible to govern at scale.
- **Proposed direction**: First-class `RiskException` (or `FindingException`) entity linked to Finding, with: justification text, owner (actor), `accepted_at`, `expires_at`, renewal/reminder semantics, optional linkage to verification checks or related findings. Approval flow with capability-gated acceptance. Audit trail for creation, renewal, expiry, and revocation. Findings in `risk_accepted` state without a valid exception should surface as governance warnings.
- **Dependencies**: Findings workflow (Spec 111) complete, audit log foundation (Spec 134)
- **Priority**: high

### Compliance Readiness & Executive Review Packs
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, R2 theme completion, product positioning for German midmarket / MSP governance
- **Vehicle note**: Tenant review and publication-readiness semantics should extend existing Spec 155 (`tenant-review-layer`), not become a separate candidate. This candidate remains about broader management/stakeholder-facing readiness outputs beyond the current review-layer spec.
- **Problem**: TenantPilot is building a strong evidence/data foundation (Evidence Domain Foundation candidate, StoredReports, review pack export via Spec 109, findings, baselines), but there is no product-level capability that assembles this data into management-ready, customer-facing, or auditor-oriented readiness views. Enterprise customers, MSP account managers, and CISOs need structured governance outputs for recurring tenant reviews, audit preparation, and compliance conversations — not raw artifact collections or manual export assembly. The gap is not data availability; it is the absence of a dedicated readiness presentation and packaging layer that turns existing governance evidence into actionable, consumable deliverables.
- **Why it matters**: This is a core product differentiator and revenue-relevant capability for the MSP and German midmarket audience. Without it, TenantPilot remains an operator tool — powerful but invisible to the stakeholders who sign off on governance, approve budgets, and evaluate vendor value. Structured readiness outputs (lightweight BSI/NIS2/CIS-oriented views, executive summaries, customer review packs) make TenantPilot sellable as a governance review platform, not just a backup and configuration tool. This directly strengthens the MSP sales story for quarterly reviews, security health checks, and audit preparation.
- **Proposed direction**:
  - A dedicated readiness/review presentation layer that consumes evidence domain artifacts, findings summaries, baseline/drift posture, permission posture signals, and operational health data
  - Management-ready output surfaces: executive summary views, customer-facing review dashboards, structured compliance readiness pages oriented toward frameworks such as BSI Grundschutz, NIS2, and CIS — in a lightweight, non-certification sense (governance evidence, not formal compliance claims)
  - Exportable review packs that combine multiple evidence dimensions into a single coherent deliverable (PDF or structured export) for external stakeholders
  - Tenant-scoped and workspace-scoped views — individual tenant reviews as well as portfolio-level readiness summaries
  - Clear separation from the Evidence Domain Foundation: evidence foundation owns curation, completeness tracking, and artifact storage; compliance readiness owns presentation, assembly, and stakeholder-facing output
  - Readiness views should be composable: an operator selects which dimensions to include in a review pack (e.g. baseline posture + findings summary + permission evidence + operational health) rather than a monolithic fixed report
- **Explicit non-goals**: Not a formal certification engine — TenantPilot does not certify compliance or issue attestations. Not a legal or compliance advice system. Not a replacement for the Evidence Domain Foundation (which owns the data layer). Not a generic BI dashboard or data warehouse initiative. Not a PDF-only export task — the primary value is the structured readiness view, with export as a secondary delivery mechanism. Not a reimplementation of review pack export (Spec 109 handles CSV/ZIP). Not a customer-facing analytics suite.
- **Boundary with Evidence Domain Foundation**: Evidence Domain Foundation = curation, completeness tracking, artifact storage, immutable snapshots. Compliance Readiness = presentation, assembly, framework-oriented views, stakeholder-facing outputs. Evidence Foundation is a prerequisite; Compliance Readiness is a consumer.
- **Dependencies**: Evidence Domain Foundation (data layer), review pack export (Spec 109), findings workflow (Spec 111), baseline/drift engine (Specs 116–119), permission posture (Specs 104/105), audit log foundation (Spec 134)
- **Priority**: medium (high strategic value, but depends on evidence foundation maturity)

### Enterprise App / Service Principal Governance
- **Type**: feature
- **Source**: platform domain coverage planning, governance gap analysis
- **Problem**: TenantPilot covers tenant configuration and governance workflows, but lacks a first-class governance surface for enterprise applications and service principals. Operators cannot easily answer which app identities exist, which ones hold privileged permissions, which credentials are nearing expiry, and where renewal/review workflows are needed.
- **Why it matters**: Enterprise apps and service principals are a major governance and security pain point in Microsoft cloud environments. Expiring secrets/certificates, over-privileged app permissions, and unclear ownership create real audit, operational, and risk-management gaps. This is highly relevant for MSP reviews, customer reporting, and exception workflows.
- **Proposed direction**: Add a governance-oriented domain surface for enterprise applications and service principals, starting with inventory, privileged-permission visibility, expiring credential visibility, ownership/review metadata, alerting hooks, and exception/renewal workflow support. Keep the scope centered on governance and reviewability rather than trying to model all enterprise app administration.
- **Dependencies**: Evidence/reporting direction, alerting foundations, RBAC/capability model, domain coverage strategy
- **Priority**: high

### SharePoint Tenant-Level Sharing Governance
- **Type**: feature
- **Source**: platform domain coverage planning, audit/compliance positioning
- **Problem**: TenantPilot currently focuses on device and identity governance domains, but does not yet cover one of the most audit-relevant Microsoft 365 data-governance control surfaces: tenant-level SharePoint and OneDrive external sharing settings. Operators lack a governance view for high-risk sharing posture at tenant scope.
- **Why it matters**: Tenant-level sharing controls are central to data exposure, external collaboration, and audit readiness. For many customers, especially compliance-oriented SMB and midmarket environments, these settings are part of the core governance story and should not remain outside the platform's planned coverage.
- **Proposed direction**: Introduce a bounded governance surface for tenant-level SharePoint and OneDrive sharing/access settings, focused on inventory, reviewability, explainability, and later alignment with evidence/reporting workflows. Start at tenant-level controls rather than attempting full site-level administration or a broad SharePoint management surface.
- **Dependencies**: Domain coverage strategy, Microsoft 365 policy-domain expansion, reporting/evidence direction
- **Priority**: medium

### Entra Role Governance
- **Type**: feature
- **Source**: platform domain coverage planning, identity governance expansion
- **Problem**: TenantPilot does not yet provide a first-class governance surface for Microsoft Entra roles. Built-in roles, custom role definitions, and role assignments are highly relevant for identity governance, but today they are not planned as a dedicated product capability.
- **Why it matters**: Role governance is a central part of tenant security posture, privileged access control, and audit readiness. Customers need visibility into how administrative authority is defined and assigned, especially as Entra role usage grows beyond default out-of-the-box roles.
- **Proposed direction**: Add a first-class Entra role governance capability focused on role definitions and assignments as governable objects. Start with inventory, visibility, and review-oriented explainability. Preserve the possibility of future attestation/review workflows without making them mandatory in V1.
- **Dependencies**: Identity governance expansion, RBAC/capability model, reporting/evidence direction
- **Priority**: medium

### Security Posture Signals Foundation
- **Type**: feature
- **Source**: platform domain coverage planning, compliance/readiness reporting direction
- **Problem**: TenantPilot's evidence and reporting direction is strong, but high-value security posture signals such as Defender Vulnerability Management exposure data and backup assurance signals are not yet represented as a bounded product capability. This leaves a gap between governance findings and the operational evidence customers want in recurring reviews.
- **Why it matters**: Customers and MSP operators increasingly want proof that security operations are functioning, not just that configurations exist. Exposure trends, vulnerability posture, and backup success/failure signals are highly valuable inputs for executive reviews, customer reporting, and audit preparation.
- **Proposed direction**: Establish a bounded evidence/signal foundation for ingesting, historizing, correlating, and reporting on selected posture signals, starting with Defender Vulnerability Management and backup success/failure/protection-state signals. Keep this clearly in the evidence domain, not the policy domain.
- **Dependencies**: StoredReports/Evidence direction, signal ingestion foundations, reporting/export maturity
- **Priority**: medium

### Security Suite Layer — Posture Score, Blast Radius, High-Risk Opt-In Controls
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming, roadmap "Security Suite Layer" long-term theme
- **Problem**: TenantPilot's security-related capabilities are growing — findings, baselines, drift detection, permission posture — but they remain siloed as individual data outputs. The Security Posture Signals Foundation candidate addresses lower-level signal ingestion and evidence collection, but there is no product layer that aggregates, interprets, and prioritizes these signals into actionable security posture surfaces for operators. An MSP operator managing twenty tenants cannot currently answer: which tenants have the weakest security posture? Which single misconfiguration has the widest blast radius across users and devices? Which high-risk settings are intentionally enabled vs. accidentally exposed? The gap is not signal availability — it is the absence of a higher-level interpretation and prioritization layer that turns raw posture data into operator-facing security value.
- **Why it matters**: Raw signals and individual findings are necessary but insufficient. Operators, CISOs, and MSP account managers need aggregated, prioritized, and contextualized security views that surface the most consequential risks first. Without this, security-relevant data is scattered across findings tables, drift reports, permission posture views, and evidence exports — forcing operators to mentally assemble a posture picture themselves. A productized security posture layer is the difference between "we collect security data" and "we help you act on the most important risks." This is a strategic differentiator for MSP positioning and enterprise customer conversations where security posture is a recurring review topic.
- **Proposed direction**:
  - **Posture scoring or posture rollups**: Tenant-level and optionally workspace-level security posture summaries that aggregate signals from findings, baselines, drift state, permission posture, and (when available) external posture signals into a structured posture indicator. Not a single arbitrary number — a structured rollup showing posture dimensions (configuration compliance, identity hygiene, protection coverage, exposure risk) with clear drill-down paths. The goal is "where should I focus?" not "what is my score?"
  - **Blast-radius and impact-oriented interpretation**: For high-severity findings, misconfigurations, or risky conditions, show the scope of impact — how many users, devices, or groups are affected? Which policies target broad populations with permissive or risky settings? Impact context helps operators prioritize consequential risks over technically-severe-but-narrow ones. This is interpretation layered on top of existing assignment and scope data, not a separate data collection effort.
  - **High-risk opt-in and guarded enablement surfaces**: Where tenants have intentionally enabled high-risk settings (e.g. broad sharing, disabled MFA for service accounts, permissive conditional access), make these visible as explicit, acknowledged decisions rather than hidden configuration details. Support opt-in acknowledgement patterns where operators confirm that a high-risk condition is intentional versus accidental. This is about operator awareness and explicit decision capture, not about enforcing or blocking configurations.
  - **Security prioritization surfaces**: Operator-facing views that rank and filter posture conditions by severity, blast radius, and recency — helping operators focus on the few conditions that matter most rather than reviewing flat lists. Supports "top 5 risks across my portfolio" and "highest-impact unresolved findings" patterns.
  - **Tenant-scoped and portfolio-aware**: Security posture is evaluated per tenant; portfolio-level aggregation surfaces which tenants are strongest and weakest for MSP operators managing fleets. Supports fleet-level security posture comparisons and trend tracking over time.
- **Explicit non-goals**: Not a SIEM, SOC, or XDR platform — this is posture interpretation for governance operators, not a security operations center tool. Not a vulnerability management system — TenantPilot does not own vulnerability remediation workflows or patch management. Not a generic security analytics platform or BI dashboard. Not a replacement for Security Posture Signals Foundation — this candidate consumes signals; the foundation candidate collects them. Not a compliance certification engine (Compliance Readiness handles audit-ready reporting). Not a threat detection or incident response system. Not a catch-all security backlog bucket — scope is bounded to posture aggregation, interpretation, prioritization, and guarded-visibility patterns. Not a broad platform hardening initiative — infrastructure, delivery, and application-level hardening are separate candidates.
- **Boundary with Security Posture Signals Foundation**: Security Posture Signals Foundation = signal ingestion, historization, correlation, and evidence-layer representation of security-relevant data (Defender exposure, backup health, etc.). Security Suite Layer = aggregation, interpretation, prioritization, and operator-facing posture value built on top of those signals (and other existing governance data like findings, baselines, and drift). Foundation is the substrate; Suite Layer is the product interpretation. Foundation answers "what signals exist?" Suite Layer answers "what do they mean, and what should I act on first?"
- **Boundary with Compliance Readiness & Executive Review Packs**: Compliance Readiness = framework-oriented, stakeholder-facing reporting and evidence assembly for audit conversations. Security Suite Layer = operator-facing, action-oriented posture interpretation for day-to-day security prioritization. Compliance readiness produces reports; security suite layer guides operational focus. Posture data may feed into compliance readiness outputs, but the two serve different audiences and decision patterns.
- **Boundary with Script & Secrets Governance**: Script & Secrets Governance = lifecycle controls, diff, review, and scanning for high-risk content (scripts, secrets). Security Suite Layer may consume secrets governance findings as posture inputs, but does not own the scanning, diffing, or lifecycle management of scripts and secrets.
- **Boundary with Findings and Baselines**: Findings (Spec 111+) and baselines (Specs 116–119) produce governance data points. Security Suite Layer aggregates and reinterprets those data points through a security-prioritization lens. Findings workflow owns the individual finding lifecycle; security suite layer owns the cross-finding posture picture.
- **Dependencies**: Security Posture Signals Foundation (primary signal source), findings workflow (Spec 111+), baseline/drift engine (Specs 116–119), permission posture (Specs 104/105), RBAC/capability system (066+), audit log foundation (Spec 134)
- **Priority**: medium (high strategic value for MSP positioning and enterprise security conversations, but realistically sequenced after signal foundations and current governance hardening work are stable)

### Recovery Confidence — Automated Restore Testing & Readiness Reporting
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming ("Killer Feature"), product positioning for enterprise trust and MSP differentiation
- **Problem**: TenantPilot has a mature backup and restore pipeline — including restore preview, dry-run, risk checking, and audit logging — but there is no product-level capability that answers the question "how confident are we that restores will actually succeed when needed?" Backup existence proves data is captured; restore execution proves the mechanism works when manually triggered. Neither proves ongoing recoverability. Operators cannot answer: when was recoverability last validated for a given tenant or policy family? Which restore paths have never been exercised? Which tenants have backup coverage but zero restore confidence? What is the overall recovery posture across the portfolio? The gap is not restore capability — it is the absence of a confidence and readiness layer that continuously proves, measures, and reports on recoverability.
- **Why it matters**: Backup without proven recoverability is a false safety net. Enterprise customers, auditors, and MSP account managers increasingly ask not "do you have backups?" but "can you prove you can recover?" Recovery confidence is the difference between a backup tool and a trusted governance platform. It directly strengthens audit conversations (proving restore paths work), MSP differentiation (recovery readiness as a reportable SLA dimension), and operator trust (visibility into which restore paths are validated vs. assumed). This was identified as a "killer feature" in product brainstorming because it shifts TenantPilot from reactive restore capability to proactive recovery assurance — a category few competitors occupy.
- **Proposed direction**:
  - **Automated restore confidence checks**: scheduled or operator-triggered restore validation runs that exercise restore paths without modifying the production tenant — leveraging existing dry-run/preview infrastructure, targeted at proving that backed-up configurations can be successfully restored. Confidence checks produce structured results (pass/fail/partial, coverage, blockers) rather than just logs.
  - **Recoverability tracking model**: per-tenant, per-policy-family tracking of when each restore path was last validated, what the result was, and which paths remain unexercised. This is the persistent readiness state, not a one-time report. Tracks coverage (which policy families have been validated), freshness (how recently), and result quality (clean pass vs. partial vs. failed).
  - **Restore readiness summaries and reporting**: tenant-level and workspace-level views that show recovery posture — coverage gaps, stale validations, unexercised restore paths, confidence scores or readiness indicators. Exportable for audit evidence, customer reviews, and management reporting. Integrates with the evidence/reporting direction as a high-value signal source.
  - **Preflight scoring**: before a real restore is needed, operators can see a structured readiness assessment — which policy families are covered by recent successful validation, which have known blockers, which have never been tested. This turns restore from a "hope it works" moment into a predictable, pre-validated operation.
  - **Validation evidence trail**: each confidence check produces an immutable evidence artifact — what was tested, when, by whom, what the result was, what blockers were found. This evidence feeds into review packs, audit conversations, and compliance readiness outputs. The validation run itself is an auditable governance event.
  - **Tenant-scoped and portfolio-aware**: recovery confidence is evaluated per tenant; portfolio-level aggregation surfaces which tenants have strong vs. weak recovery posture for MSP operators managing fleets.
- **Explicit non-goals**: Not a rewrite or replacement of the restore engine (Spec 011 and related specs handle restore execution; this handles confidence measurement and readiness reporting on top of that foundation). Not a full disaster-recovery orchestration platform or automated failover system. Not a synthetic test lab that provisions isolated test tenants and deploys configurations into them — confidence checks leverage existing dry-run/preview/validation infrastructure, not a separate execution environment. Not a generic backup-health dashboard — backup health (coverage, freshness, size) is a prerequisite signal, not the same problem as restore confidence (proven recoverability). Not a vague "resilience" umbrella — this is specifically about proving and reporting on restore path readiness. Not a replacement for the Evidence Domain Foundation (which owns artifact curation) or Compliance Readiness (which owns presentation assembly) — recovery confidence produces evidence artifacts that those layers consume.
- **Boundary with restore execution (Spec 011, restore pipeline)**: Restore execution = the mechanism to restore configurations from backup to a tenant. Recovery confidence = the layer that exercises, measures, tracks, and reports on whether those mechanisms are ready and reliable. Execution is the tool; confidence is the proof.
- **Boundary with Security Posture Signals Foundation**: Security Posture Signals = ingestion and historization of external posture data (Defender, backup success/failure signals) as evidence inputs. Recovery Confidence = active validation of restore paths and structured readiness reporting. Posture signals may include backup-health inputs; recovery confidence actively exercises restore paths and produces readiness-specific evidence. Backup health signals are passive; restore confidence checks are active. They are complementary: posture signals feed portfolio health views; recovery confidence proves operational readiness.
- **Boundary with Evidence Domain Foundation**: Evidence Foundation = curation, completeness tracking, immutable artifact storage. Recovery Confidence = produces validation evidence artifacts (confidence check results) that Evidence Foundation may curate and bundle. Recovery confidence is a producer; evidence foundation is a curator/consumer.
- **Boundary with MSP Portfolio Dashboard**: Portfolio Dashboard = fleet-level health aggregation and SLA reporting. Recovery confidence signals (per-tenant readiness posture) are a high-value input to the portfolio dashboard, not a replacement for it. The dashboard consumes; this candidate produces the recovery-specific signal.
- **Dependencies**: Restore pipeline stable (Spec 011 and follow-ups), backup infrastructure mature, dry-run/preview infrastructure (restore preview), audit log foundation (Spec 134), RBAC/capability system (066+), evidence/reporting direction for downstream consumption
- **Priority**: medium (high strategic value and strong product differentiation potential, but depends on restore pipeline maturity and is realistically sequenced after current hardening work)

### MSP Multi-Tenant Portfolio Dashboard & SLA Reporting
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming (pillar #1 — MSP Portfolio & Operations), product positioning for MSP portfolio owners
- **Problem**: TenantPilot provides strong per-tenant governance, monitoring, and operational surfaces, but MSP operators and portfolio owners managing 10–100+ tenants across workspaces have no fleet-level view that answers "how is my portfolio doing?" There is no cross-tenant health summary, no SLA/compliance risk overview, no portfolio-level operational monitoring, and no structured reporting surface that supports recurring customer portfolio reviews. Operators must navigate tenant by tenant to assemble a portfolio picture, which does not scale and prevents proactive governance.
- **Why it matters**: MSP portfolio visibility is the #1 brainstorming priority and a core product differentiator. Without it, TenantPilot serves individual tenant management well but cannot position itself as the operational cockpit for MSP businesses. Portfolio-level health, SLA tracking, compliance risk summaries, and cross-tenant operational monitoring are the capabilities that justify platform-level pricing and recurring MSP engagement. This is the difference between a per-tenant tool and an MSP operations platform.
- **Proposed direction**:
  - Workspace-level portfolio dashboard: aggregated health, governance, and operational status across all managed tenants in a workspace
  - Key portfolio signals: backup health (last successful backup age, coverage), sync health (last successful sync, staleness), drift/findings posture (open findings count, severity distribution, trend), operational health (recent failures, stuck runs, throttling indicators), provider connection status (consent/verification posture across fleet)
  - SLA/compliance risk summary views: which tenants are below operational health thresholds, which tenants have governance gaps, which tenants need attention — sortable, filterable, visually prioritized
  - Cross-tenant operational monitoring: portfolio-level view of recent operation runs, failure clustering, and common error patterns across tenants
  - Structured portfolio reporting: exportable portfolio health summaries for MSP-internal use, customer-facing SLA reports, and recurring review preparation
  - Workspace-scoped, RBAC-gated: portfolio views respect workspace membership and capability authorization
- **Explicit non-goals**: Not a replacement for per-tenant dashboards or detail views (those remain the primary tenant-level surfaces). Not a generic BI/data warehouse initiative or a drag-and-drop report builder. Not a customer-facing analytics suite — this is an operator/MSP-internal tool. Not a cross-tenant compare/diff/promotion surface (that is the Cross-Tenant Compare & Promotion candidate). Not a system-console-level platform triage view (that is the System Console Multi-Workspace Operator UX candidate). Not a replacement for alerting (Specs 099/100 handle event-driven notifications; this is a review/monitoring surface).
- **Boundary with Cross-Tenant Compare & Promotion**: Portfolio Dashboard = fleet-level monitoring, health aggregation, SLA reporting, operational overview. Cross-Tenant Compare = policy-level diff, staging-to-production promotion, configuration comparison. They share the multi-tenant dimension but solve fundamentally different problems.
- **Boundary with System Console Multi-Workspace Operator UX**: Portfolio Dashboard = workspace-scoped MSP operator view, health/SLA/governance focus. System Console = platform-level triage, cross-workspace operator tooling, infrastructure focus. Different audiences, different panels.
- **Dependencies**: Per-tenant operational health signals (backup, sync, drift, findings, provider connection status), workspace model, tenant inventory, alerting foundations (Specs 099/100), RBAC/capability system (066+)
- **Priority**: medium (high strategic value, significant data aggregation effort; depends on per-tenant signal maturity)

### Policy Lifecycle / Ghost Policies (Spec 900 refresh)
- **Type**: feature
- **Source**: Spec 900 draft (2025-12-22), HANDOVER risk #9
- **Problem**: Policies deleted in Intune remain in TenantAtlas indefinitely. No deletion indicators. Backup items reference "ghost" policies.
- **Why it matters**: Data integrity, user confusion, backup reliability
- **Proposed direction**: Soft delete detection during sync, auto-restore on reappear, "Deleted" badge, restore from backup. Draft in Spec 900.
- **Dependencies**: Inventory sync stable
- **Priority**: medium

### Standardization & Policy Quality — Linting, Company Standards, Hygiene
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming (pillar #3 — Standardization & Policy Quality / "Intune Linting")
- **Problem**: TenantPilot captures, versions, and governs Intune policy configurations, but provides no capability to evaluate whether those configurations meet quality, consistency, or organizational standards. Operators cannot answer questions like: "Do all policies follow our naming convention?", "Are there duplicate or near-duplicate policies?", "Which policies have no assignments?", "Are scope tags applied consistently?", "Does this tenant meet our company's minimum configuration standard?" Today, quality and hygiene assessment is manual, tenant-by-tenant, and invisible to governance workflows.
- **Why it matters**: Configuration quality is a distinct governance dimension from baseline drift and compliance findings. Drift detection answers "has something changed?"; standardization answers "is it correct and well-structured?" Enterprise customers and MSPs need both. Policy linting, hygiene checks, and company standards create a repeatable quality layer that reduces configuration debt, catches structural problems early, and supports standardization across managed tenants. This is the #3 brainstorming priority and a natural complement to the existing governance stack.
- **Proposed direction**:
  - **Policy linting / quality checks**: rule-based evaluation of policy configurations against defined quality criteria — naming conventions, scope tag requirements, assignment presence, setting completeness, structural validity. Rules should be composable and extensible per workspace or tenant.
  - **Company standards as reusable reference packs**: operators or MSPs define their own configuration standards ("Company Standard 2026") as reference expectations that policies can be evaluated against. Distinct from Microsoft baselines — these are organization-defined, not vendor-defined. A standard pack is a set of expected configuration postures, not a deployable template.
  - **Hygiene checks**: automated detection of structural problems — duplicate or near-duplicate policies, unassigned policies, orphaned scope tags or filters, policies with no settings or empty payloads, stale policies not updated in extended periods, inconsistent naming patterns across policy families.
  - **Quality findings integration**: hygiene and linting results should produce structured findings or quality signals that integrate with the existing findings workflow, not a separate parallel reporting system.
  - **Tenant-scoped and portfolio-aware**: quality evaluation runs per tenant; portfolio views can aggregate quality posture across tenants for MSP operators.
- **Explicit non-goals**: Not a full compliance framework or certification engine (compliance readiness is a separate candidate). Not a generic recommendation engine or AI assistant. Not a replacement for baseline/drift detection (which answers "has it changed from a known-good state?" — standardization answers "is it well-structured and consistent?"). Not a policy deployment or remediation engine — this is evaluation and visibility, not automated correction. Not a replacement for the existing findings workflow — quality signals should flow into findings, not bypass them.
- **Boundary with baseline/drift engine**: Baselines compare current state against a snapshot of known-good state. Standardization evaluates current state against quality rules and organizational expectations. A policy can be drift-free (unchanged from baseline) but still fail quality checks (bad naming, missing assignments, no scope tags). These are complementary, not overlapping.
- **Boundary with Policy Setting Explorer**: Policy Setting Explorer = reverse lookup ("where is this setting defined?"). Standardization = quality evaluation ("is this policy well-structured and consistent?"). Different questions, different surfaces.
- **Dependencies**: Inventory sync stable, policy versioning, tenant context model, findings workflow (Spec 111) for quality findings integration, RBAC/capability system (066+)
- **Priority**: medium (high strategic value, incremental delivery possible starting with high-value hygiene checks)

### Schema-driven Secret Classification
- **Type**: hardening
- **Source**: Spec 120 deferred follow-up
- **Problem**: Secret redaction currently uses pattern-based detection. A schema-driven approach via `GraphContractRegistry` metadata would be more reliable.
- **Why it matters**: Reduces false negatives in secret redaction
- **Proposed direction**: Central classifier in `GraphContractRegistry`, regression corpus
- **Dependencies**: Secret redaction (120) stable, registry completeness (095)
- **Priority**: medium

### Script & Secrets Governance — Diff, Review, Scanning, and Lifecycle Controls for High-Risk Content
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming (Script & Secrets Governance pillar), platform hardening direction
- **Problem**: TenantPilot governs a wide range of Intune policy configurations, but a subset of these configurations carries disproportionate operational risk: PowerShell remediation scripts, detection scripts, custom compliance scripts, proactive remediations, and policy artifacts that embed or reference secrets (pre-shared keys, certificate data, credentials, API tokens). These artifacts are fundamentally different from declarative policy settings — they contain executable logic or sensitive material where a single change can have outsized blast radius, and where silent or unreviewed modification creates real security and operational exposure. Today, TenantPilot treats script-bearing and secret-sensitive artifacts with the same governance depth as any other policy: they are versioned and backed up, but there is no dedicated diff/review surface for script content, no approval or guarded workflow for high-risk script changes, no scanning or policy checks for obviously unsafe secret-handling patterns, and no structured visibility into which configurations carry elevated risk because they contain executable or secret-sensitive content.
- **Why it matters**: Script and secret governance is a distinct risk dimension that cuts across policy families. A naming convention violation in a device configuration policy is a hygiene problem; an unreviewed script change in a remediation policy is a potential security incident. Enterprise customers and MSP operators need to trust that high-risk content changes are visible, reviewable, and governable — not just captured as another version snapshot. This capability strengthens audit conversations (proving that script changes are reviewed), operator safety (preventing silent high-risk modifications from going unnoticed), and platform credibility (demonstrating that TenantPilot understands which parts of Intune configuration carry elevated risk). Without it, backup and versioning give a false sense of governance completeness — the most dangerous artifacts receive the same governance treatment as the least dangerous ones.
- **Proposed direction**:
  - **Script-aware diff and review surfaces**: dedicated diff views for script-bearing policy artifacts that render script content changes readably — not just JSON diff of the enclosing policy payload, but structured presentation of the script text itself (before/after, syntax-highlighted where practical, change summary). These surfaces make script changes reviewable by operators rather than buried in raw payload diffs.
  - **Risk classification for script/secret-bearing artifacts**: extend the inventory or governance metadata so that policy artifacts containing scripts or secret-sensitive fields are identifiable as elevated-risk items. This classification enables filtering, alerting, and governance workflow differentiation — operators can see "which of my policies are script-bearing?" or "which versions changed script content?" without manually inspecting payloads.
  - **Guarded change workflows for high-risk content**: optional governance gates for script-bearing or secret-sensitive changes — such as requiring explicit acknowledgment, capability-gated approval, or elevated audit logging when a versioned change involves script content or secret-sensitive fields. These are governance-layer controls, not Intune-side mutation blocks (TenantPilot observes configuration, it does not control the Intune mutation path). The gates apply to how TenantPilot classifies and routes detected changes.
  - **Scanning and policy checks for secret-handling patterns**: lightweight rule-based checks that flag obviously unsafe patterns in script or configuration content — hardcoded credentials, plaintext secrets, overly broad credential scopes, known-bad patterns. Not a full SAST engine — focused, high-signal checks that catch the most common and most dangerous mistakes. Results integrate with the findings workflow as governance signals, not a parallel detection system.
  - **Rollback and auditability expectations**: script and secret-sensitive changes should have clear rollback visibility (which version introduced the script change, who triggered restore, what was the before/after state). Audit trail expectations should be elevated for this content class — change, review, approval, and rollback events should be distinctly traceable in audit logs.
  - **Operator visibility into script/secret risk posture**: tenant-level and portfolio-level views that surface which tenants have unreviewed script changes, which script-bearing policies have never been reviewed, and where secret-handling patterns have been flagged. This is the governance visibility layer, not a generic dashboard initiative.
- **Explicit non-goals**: Not a replacement for external secret vault or key management systems (Azure Key Vault, HashiCorp Vault, etc.) — TenantPilot does not store or manage secrets as a vault; it governs configurations that may contain or reference sensitive material. Not a full code-signing or binary-signing platform — governance focus is on reviewability and risk visibility, not cryptographic attestation. Not a SIEM, DLP, or broad security-monitoring system — this is governance of specific high-risk content classes within the existing policy governance architecture, not a generic security operations capability. Not a catch-all bucket for every security topic — this is bounded to script-bearing and secret-sensitive configuration artifacts. Not a replacement for the baseline/drift engine (which detects *any* configuration change) — this adds risk-aware governance specifically for the content classes where changes carry elevated operational risk. Not a policy deployment or remediation engine — this is detection, review, and governance, not automated correction. Not a full static analysis (SAST) engine for arbitrary scripts.
- **Boundary with Schema-driven Secret Classification**: Schema-driven Secret Classification = improving the *redaction mechanism's* reliability by using schema metadata to classify which fields contain secrets (a backend classification improvement for the existing redaction pipeline). Script & Secrets Governance = lifecycle governance around script-bearing and secret-sensitive *artifacts* — diff, review, scanning, approval workflows, risk visibility. Classification makes redaction more accurate; governance adds reviewability and lifecycle controls. Schema-driven classification may inform governance risk tagging (which fields are secret-sensitive), but the problems and deliverables are distinct.
- **Boundary with Standardization & Policy Quality**: Standardization = evaluating whether policies are well-structured, consistently named, properly assigned, and hygienically maintained. Script & Secrets Governance = evaluating whether high-risk content (scripts, secrets) is reviewed, safe, and governable. A policy can pass all quality checks (good naming, proper assignments, scope tags) but still have an unreviewed script change or a hardcoded credential. These are complementary governance dimensions, not overlapping.
- **Boundary with Security Posture Signals Foundation**: Security Posture Signals = ingesting and historizing external posture data (Defender, backup health) as evidence inputs for reporting. Script & Secrets Governance = internal governance of the product's own high-risk configuration content. Different data sources, different governance problems. Posture signals are external evidence; script governance is internal safety.
- **Boundary with baseline/drift engine (Specs 116–119)**: Drift detection = detecting that *something changed*. Script & Secrets Governance = applying differentiated governance treatment *because of what changed* (script content, secret-sensitive fields). Drift is content-agnostic detection; script governance is risk-aware response. They compose: drift detection finds the change, script governance classifies and routes it based on risk.
- **Dependencies**: Inventory sync stable, policy versioning and snapshot infrastructure, secret redaction (Spec 120) stable, findings workflow (Spec 111) for governance signal integration, audit log foundation (Spec 134), RBAC/capability system (066+), GraphContractRegistry maturity for field-level metadata
- **Priority**: medium (high security-governance value and clear product differentiation, but realistically sequenced after current hardening work and dependent on inventory/versioning/findings maturity)

### Cross-Tenant Compare & Promotion
- **Type**: feature
- **Source**: Spec 043 draft, 0800-future-features
- **Problem**: No way to compare policies between tenants or promote configurations from staging to production.
- **Why it matters**: Core MSP/enterprise workflow. Identified as top revenue lever in brainstorming.
- **Proposed direction**: Compare/diff UI, group/scope-tag mapping, promotion plan (preview → dry-run → cutover → verify)
- **Dependencies**: Inventory sync, backup/restore mature
- **Spec 043 relationship**: Spec 043 (`specs/043-cross-tenant-compare-and-promotion/spec.md`) is a lightweight draft (scenarios + FRs, created 2026-01-07, status: Draft) that covers the core compare/promotion contract. This candidate captures the expanded strategic direction and scope refinements accumulated since the draft was written. When this candidate is promoted, it should refresh and supersede the existing Spec 043 draft rather than creating a parallel spec.
- **Priority**: medium (high value, high effort)

### System Console Scope Hardening
- **Type**: hardening
- **Source**: Spec 113/114 follow-up
- **Problem**: The system console (`/system`) needs a clear cross-workspace entitlement model. Current platform capabilities (Spec 114) define per-surface access, but cross-workspace query authorization and scope isolation for platform operators are not yet hardened as a standalone contract.
- **Why it matters**: Platform operators acting across workspaces need tight scope boundaries to prevent accidental cross-workspace data exposure in troubleshooting and monitoring flows.
- **Proposed direction**: Formalize cross-workspace query authorization model, scope isolation rules for platform operator sessions, and regression coverage for wrong-workspace access in system console surfaces.
- **Dependencies**: System console (114) stable, canonical tenant context (Specs 135/136)
- **Priority**: low

### System Console Multi-Workspace Operator UX
- **Type**: feature
- **Source**: Spec 113 deferred
- **Problem**: System console (`/system`) currently can't select/filter across workspaces for platform operators. Triage and monitoring require workspace-by-workspace navigation.
- **Why it matters**: Platform ops need cross-workspace visibility for troubleshooting and monitoring at scale.
- **Proposed direction**: Workspace selector/filter in system console views, cross-workspace run aggregation, unified triage entry point.
- **Dependencies**: System console (114) stable, System Console Scope Hardening
- **Priority**: low

### Operations Naming Harmonization Across Run Types, Catalog, UI, and Audit
- **Type**: hardening
- **Source**: coding discovery, operations UX consistency review
- **Why it matters**: Strategically important for enterprise UX, auditability, and long-term platform consistency. `OperationRun` is becoming a cross-domain execution and monitoring backbone, and the current naming drift will get more expensive as new run types and provider domains are added. This should reduce future naming drift, but it is not a blocker-critical refactor and should not be pulled in as a side quest during small UI changes.
- **Problem**: Naming around operations appears historically grown and not consistent enough across `OperationRunType` values, visible run labels, `OperationCatalog` mappings, notifications, audit events, filters, badges, and related UI copy. Internal type names and operator-facing language are not cleanly separated, domain/object/verb ordering is uneven, and small UX fixes risk reinforcing an already inconsistent scheme. If left as-is, new run types for baseline, review, alerts, and additional provider domains will extend the inconsistency instead of converging it.
- **Desired outcome**: A later spec should define a clear naming standard for `OperationRunType`, establish an explicit distinction between internal type identifiers and operator-facing labels, and align terminology across runs, notifications, audit text, monitoring views, and operations UI. New run types should have documented naming rules so they can be added without re-opening the vocabulary debate.
- **In scope**: Inventory of current operation-related naming surfaces; naming taxonomy for internal identifiers versus visible operator language; conventions for verb/object/domain ordering; alignment rules for `OperationCatalog`, run labels, notifications, audit events, filters, badges, and monitoring UI; forward-looking rules for adding new run types and provider/domain families; a pragmatic migration plan that minimizes churn and preserves audit clarity.
- **Out of scope**: Opportunistic mass-refactors during unrelated feature work; immediate renaming of all historical values without a compatibility plan; using a small UI wording issue such as "Sync from Intune" versus "Sync policies" as justification for broad churn; a full operations-domain rearchitecture unless later analysis proves it necessary.
- **Trigger / Best time to do this**: Best tackled when multiple new run types are about to land, when `OperationCatalog` / monitoring / operations hub work is already active, when new domains such as Entra or Teams are being integrated, or when a broader UI naming constitution is ready to be enforced technically. This is a good candidate for a planned cleanup window, not an ad hoc refactor.
- **Risks if ignored**: Continued terminology drift across UI and audit layers, higher cognitive load for operators, weaker enterprise polish, more brittle label mapping, and more expensive cleanup once additional domains and execution types are established. Audit/event language may diverge further from monitoring language, making cross-surface reasoning harder.
- **Suggested direction**: Define stable internal run-type identifiers separately from visible operator labels. Standardize a single naming grammar for operation concepts, including when to lead with verb, object, or domain, and when provider-specific wording is allowed. Apply changes incrementally with compatibility-minded mapping rather than a brachial rename of every historical string. Prefer a staged migration that first defines rules and mapping layers, then updates high-value operator surfaces, and only later addresses legacy internals where justified.
- **Readiness level**: Qualified and strategically important, but intentionally deferred. This should be specified before substantially more run types and provider domains are introduced, yet it should not become an immediate side-track or be bundled into minor UI wording fixes.
- **Candidate quality**:
	- Clearly identified cross-cutting problem with architectural and UX impact
	- Strong future-facing trigger conditions instead of vague "sometime later"
	- Explicit boundaries to prevent opportunistic churn
	- Concrete desired outcome without overdesigning the solution
	- Easy to promote into a full spec once operations-domain work is prioritized

### OperationRun Humanization & Diagnostics Boundary
- **Type**: hardening
- **Source**: operator surface standards adoption v1, operations UX consistency review, cross-link monitoring/alerts/dashboard review
- **Problem**: `OperationRun` is one of TenantPilot's highest-leverage operator surfaces, but its current UX risks exposing implementation semantics instead of operator-facing clarity. The default surface can blur execution outcome, blocked reason, technical diagnostics, object and scope identity, and next-action guidance into one undifferentiated detail stack. Because `OperationRun` is the destination for monitoring links, alert deep links, dashboard drill-ins, and troubleshooting flows, weak clarity here propagates system-wide. The current risk pattern includes raw reason codes, internal IDs and hashes, raw payload context, ambiguous state labels, and insufficient separation between operator summary and diagnostic truth.
- **Why it matters**: This is the best pilot surface for the operator UX standard because it is highly visible, cross-cutting, and already carries the product's richest execution truth. If the default run detail page does not quickly answer "What happened?", "Did it succeed, fail, or get blocked?", "What scope did it affect?", "Is action required?", and "What should I do next?", then monitoring, alerting, dashboards, and support flows all inherit the same ambiguity. A low-clarity run surface reduces trust far beyond the operations page itself.
- **Desired outcome**: The default `OperationRun` list and detail experience should be operator-first: identity, status, scope, interpreted summary, and next action lead; diagnostics remain available but clearly secondary. Senior engineers must still be able to reach raw reason codes, IDs, payload context, and technical details without those details polluting the primary operator surface.
- **Proposed direction**:
  - **Canonical detail-page hierarchy**: make run identity, status, top-level summary, explicit scope, and primary actions the first content block on the detail page. Raw JSON, hashes, internal IDs, and technical payload fragments move below a clearly labeled diagnostics boundary.
  - **Operator-first state interpretation**: translate blocked and failed states into human-readable labels and summaries. Distinguish execution outcome from completeness/downstream effect where relevant so operators can tell the difference between "execution succeeded" and "the intended effect is incomplete or limited."
  - **Diagnostics boundary pattern**: establish a reusable convention where diagnostic truth is available through progressive disclosure, not mixed into the primary reading path. The boundary should explicitly contain raw reason code, raw identifiers, payload context, low-level exception detail, and similar engineering-facing artifacts.
  - **Next-step guidance contract**: whenever a run is blocked or failed, the primary surface must show what the operator should do next. Next-step content should be visible without requiring expansion into raw diagnostics.
  - **Explicit scope communication**: run details and list rows should make the affected object, domain, and workspace/tenant context obvious so an operator can immediately understand impact and blast radius.
  - **Action hierarchy on run details**: establish a safe, obvious action order for follow-up paths such as retry, inspect source object, view related monitoring context, or open diagnostics. Diagnostic actions must not visually compete with the primary operator path.
  - **Reference implementation role**: use `OperationRun` as the reference implementation for future surfaces that need the same pattern: operator-first summary plus secondary diagnostics.
- **In scope**:
  - `OperationRun` list and detail surfaces
  - operator-facing labels and summaries
  - blocked / failed state translation on these surfaces
  - diagnostics boundary and progressive disclosure pattern
  - top-level summary cards / interpreted content
  - explicit scope communication and workspace / tenant context
  - action hierarchy on run details
  - mapping technical reasons into operator-facing blocked reason and next-step guidance
  - monitoring / alert / dashboard deep-link landing clarity insofar as those links land on `OperationRun`
- **Out of scope**:
  - broad redesign of the entire admin UI
  - full monitoring information-architecture rewrite
  - full alerts redesign
  - product-wide adoption of the standard in one pass
  - backend execution model changes that are not needed for `OperationRun` operator-surface clarity
  - broad operation naming refactors beyond what this surface strictly needs to be understandable
- **Acceptance characteristics**:
  - default-visible labels do not expose raw internal field names
  - blocked reasons are human-readable
  - next steps are visible when the run is blocked or failed
  - diagnostics are present but clearly secondary
  - page hierarchy starts with identity, status, summary, and actions
  - raw JSON, internal hashes, and internal IDs are not primary content
  - monitoring and alert deep links land on a page that is understandable to operators without diagnostic context
- **Why now vs later**:
  - **Why now**: high leverage; immediate trust improvement for monitoring and alert flows; first concrete adoption of the operator UX standard; creates a reusable pattern for future detail surfaces
  - **Why not later**: unresolved ambiguity on run surfaces keeps leaking into dashboards, alerts, and troubleshooting entry points; later surfaces will otherwise copy the current weak pattern
- **Cross-cutting impact**: monitoring, alerts, dashboards, diagnostics conventions, status-taxonomy adoption, future detail-page standards, and operator-language normalization
- **Likely follow-on candidates**: `PolicyResource` operator language and metadata isolation, baseline compare / snapshot completeness clarity, restore-run language and safe-execution standard alignment, canonical degraded / prerequisite state pattern across surfaces
- **Dependencies**: Operator Outcome Taxonomy and Cross-Domain State Separation (shared vocabulary), Operator Reason Code Translation and Humanization Contract (blocked/failure labels and next steps), canonical `OperationRun` context work already explored in Specs 054, 114, and 144
- **Boundary with Operations Naming Harmonization**: Naming harmonization owns the cross-product vocabulary for operation types, labels, and catalog mappings. This candidate owns the operator readability and diagnostics separation of the `OperationRun` surface itself. Naming alignment may be consumed here, but this candidate should not expand into a repo-wide naming refactor.
- **Boundary with Operator Presentation & Lifecycle Action Hardening**: Presentation hardening owns shared rendering and action-visibility conventions across many surfaces. This candidate is narrower and deeper: it defines the canonical operator-versus-diagnostics hierarchy on the highest-value run detail surface and uses it as the reference implementation for future adoption.
- **Boundary with Operator Reason Code Translation**: Reason code translation defines how internal codes become human-readable labels and next-step envelopes. This candidate consumes that translation on the `OperationRun` surface and defines where translated content stops and raw diagnostics begin.
- **Strategic sequencing**: Best tackled after the outcome taxonomy and in parallel with or immediately after reason-code translation. It is a strong pilot implementation candidate before broader operator-surface rollout because it validates the standards on the most cross-linked execution surface first.
- **Priority**: high

### Operator Presentation & Lifecycle Action Hardening
- **Type**: hardening
- **Source**: Evidence Snapshot / Ops-UX review 2026-03-19
- **Problem**: TenantPilot has strong shared presentation abstractions — `OperationCatalog` for operation labels, `BadgeRenderer` / `BadgeCatalog` for status/outcome badges, and some lifecycle-aware action gating patterns in selected resources — but these conventions are not consistently enforced across all operator-facing surfaces. Individual surfaces can bypass the shared sources of truth without triggering any architectural or CI feedback. This produces a repeatable class of operator-UX degradation:
  - **Operation label bypass**: surfaces that render operation names directly from internal type keys instead of going through the shared operation catalog, leaking technical identifiers like `inventory_sync` or `compliance.snapshot` into operator-visible UI.
  - **Status/outcome presentation bypass**: surfaces that render raw enum values (e.g. `queued`, `running`, `pending`, `succeeded`) directly from model attributes instead of using `BadgeRenderer`, producing unstyled debug-quality output where operators expect consistent badge rendering.
  - **Missing lifecycle-aware action gating**: mutation and destructive actions (e.g. "Expire snapshot", "Refresh snapshot") that remain visible and invocable on records in terminal lifecycle states (Expired, Failed), because no shared convention requires actions to derive visibility from valid lifecycle transitions. Backend idempotency guards prevent data corruption but do not prevent operator confusion.
  - **Unscoped global widget polling**: global widgets (e.g. `BulkOperationProgress`) that poll on every page including non-operational pages where no active runs are expected, creating unnecessary network noise and giving operators the impression that background activity is occurring when none is relevant.
- **Why it matters**: In enterprise SaaS, operator trust depends on consistent, predictable UI behavior across every surface. A single widget rendering raw `queued` instead of a styled badge, or a single page showing an "Expire" action on an already-expired record, undermines confidence in the product's governance capabilities. These are not cosmetic issues — they are operator-trust issues that compound as the product adds more lifecycle-driven surfaces (Findings, Review Packs, Baselines, Exceptions, Alerts, Drift governance). Without shared enforceable conventions, every new surface risks re-introducing the same failure modes.
- **Proposed direction**:
  - **Operation label convention**: codify the rule that all operator-visible operation names must resolve through `OperationCatalog::label()` (or the equivalent shared source of truth). Add a lightweight enforcement mechanism (CI check, architectural test, or documented anti-pattern) that catches direct usage of raw operation type strings in Blade templates and widget renders.
  - **Status/outcome badge convention**: codify the rule that all operator-visible status and outcome rendering must go through `BadgeRenderer` (or equivalent shared badge helpers). Enumerate the known surfaces that currently comply and identify any that bypass the convention. Add a regression mechanism to prevent new surfaces from bypassing.
  - **Lifecycle-aware action visibility convention**: define a shared contract or trait that mutation/destructive actions must consult to determine visibility based on the record's current lifecycle state. Terminal-state records must not expose invalid lifecycle transitions as available actions. Suggest introducing `isTerminal(): bool` (or equivalent) on lifecycle enums (`EvidenceSnapshotStatus`, `ReviewPackStatus`, `OperationRunStatus`, etc.) so action visibility can be derived from lifecycle semantics rather than ad hoc per-resource `->hidden()` conditions.
  - **Polling ownership convention**: codify the rule that global widgets must declare their polling scope — which pages or contexts justify active polling vs. idle/suppressed behavior. Ensure idle discovery polling intervals are intentional and documented, and that non-operational pages are not subjected to unnecessary polling overhead.
- **Scope boundaries**:
  - **In scope**: shared convention definitions, enforcement mechanisms, anti-pattern catalog, lifecycle enum enrichment (`isTerminal()` or equivalent), regression coverage for badge/label/action consistency
  - **Out of scope**: local Evidence Snapshot fixes (those belong in the active Evidence-related spec), operations naming vocabulary redesign (tracked separately as "Operations Naming Harmonization"), visual language canon / design-system codification (tracked separately as "Admin Visual Language Canon"), BulkOperationProgress architectural redesign, new badge domains or new operation types
- **Examples of failure modes this should prevent**:
  - A widget rendering `{{ $run->status }}` directly instead of using `BadgeRenderer::render(BadgeDomain::OperationRunStatus, $run->status)`
  - A card showing raw `outcome: pending` text instead of a styled outcome badge
  - An "Expire snapshot" action visible on a record with status `Expired`
  - A "Refresh snapshot" action visible on a record with status `Failed`
  - A global progress widget polling every 30 seconds on the Evidence detail page where no active operation runs are relevant
  - A new governance surface (e.g. Baseline review, Alert detail) shipping without badge rendering because no convention required it
- **Why this is a follow-up candidate, not part of current local fixes**: The active Evidence-related spec should fix the specific Evidence Snapshot bugs (raw status in `RecentOperationsSummary`, missing `->hidden()` on expire/refresh actions). This candidate addresses the **shared convention layer** that prevents the same class of bugs from recurring on every future lifecycle-driven surface. The local fixes prove the bugs exist; this candidate prevents their recurrence.
- **Dependencies**: BadgeRenderer / BadgeCatalog system (already stable), OperationCatalog (already stable), lifecycle enums (already defined, need `isTerminal()` enrichment), RBAC/capability system (066+) for action gating patterns
- **Related candidates**: Operations Naming Harmonization (naming vocabulary — complementary but distinct), Admin Visual Language Canon (visual conventions — broader scope), Action Surface Contract v1.1 (interaction-level action rules — complementary)
- **Priority**: medium

### Operations Presence & Non-Blocking Status UX
- **Type**: hardening
- **Source**: UI/UX audit — operations presence and background activity patterns
- **Problem**: `BulkOperationProgress` is a fixed bottom-right overlay (`z-[999999]`) with adaptive polling, mounted globally via render hooks in both panels. This creates several operator-UX problems: (1) completed and stale operations remain visible without a dismiss or minimize affordance, occupying screen real estate on every page; (2) the widget polls on all pages including those with no operational relevance, creating unnecessary network activity and visual noise; (3) there is no transition from "active progress" to "completed notification" — the overlay persists until polling naturally decays, with no intermediate state that acknowledges completion; (4) there is no semantic distinction between "operations are actively running" (progress feedback) and "operations recently finished" (notification/history feedback) — both are served by the same fixed overlay; (5) operators have no way to acknowledge, dismiss, or minimize operation progress once seen, meaning batch operations can dominate the viewport throughout execution.
- **Why it matters**: Background operations (sync, backup, restore, compliance snapshot, inventory) are a core product mechanic. How they surface to operators — during and after execution — directly affects perceived responsiveness, trust in operation completion, and cognitive load during multi-step governance workflows. An overlay that cannot be dismissed, polls everywhere, and makes no distinction between "in progress" and "recently completed" scales poorly as operation types multiply and concurrent operations become normal. Enterprise operators performing audit reviews, findings triage, or policy inspection should not be distracted by persistent progress overlays for unrelated background operations.
- **Proposed direction**:
  - **Dismiss and minimize semantics**: operators can dismiss completed operations from the progress overlay, and optionally minimize the overlay to a compact indicator during active operations. Dismissed state is session-scoped (not persisted across page loads).
  - **Page-scoped vs global polling context**: distinguish pages where operations are contextually relevant (operations list, tenant detail, monitoring hub) from pages where they are not (findings detail, policy inspector, RBAC settings). Non-relevant pages receive either suppressed polling or a minimal "N operations running" indicator instead of the full overlay.
  - **Completion transition pattern**: define a clear transition from "progress" to "notification" when operations complete — e.g. transient toast notification on completion + overlay removal, compact "completed" badge that auto-dismisses after a timeout, or handoff to the notification panel. Indefinite overlay persistence after completion is the anti-pattern to resolve.
  - **Stale operation visibility rules**: define when a completed or failed operation is too old to merit overlay presence. Completed operations older than a configurable threshold should not appear in the progress overlay — they belong in the operations list/history, not in a persistent viewport overlay.
  - **Non-blocking pattern formalization**: establish the product-level convention for how background operations communicate status without blocking or dominating the operator's current context. This convention applies to `BulkOperationProgress` and should be extensible to future background activities (scheduled checks, async exports, evidence generation).
- **In scope**: `BulkOperationProgress` widget behavior redesign, dismiss/minimize UX, polling scope refinement, completion transition pattern, stale visibility rules, non-blocking convention documentation
- **Out of scope**: Operation label vocabulary (tracked as "Operations Naming Harmonization"), badge/status rendering conventions (tracked as "Operator Presentation & Lifecycle Action Hardening"), operations domain architecture changes, new operation types, notification panel infrastructure, monitoring hub redesign, BulkOperationProgress internal data model or domain-layer changes beyond the UX behavior layer
- **Boundary with Operator Presentation & Lifecycle Action Hardening**: That candidate owns shared conventions for how operation labels, status badges, and lifecycle-aware actions render consistently across surfaces. This candidate owns the widget-level UX behavior of how background operations surface, persist, dismiss, and transition in the operator's viewport. Presentation conventions define *how it looks*; operations presence defines *when and where it appears*.
- **Boundary with Operations Naming Harmonization**: Naming harmonization owns the vocabulary (internal type identifiers vs operator-facing labels). This candidate owns the UX behavior layer that consumes those labels.
- **Dependencies**: BulkOperationProgress current implementation, render hook registration, Filament v5 panel infrastructure, operations domain model
- **Related candidates**: Operator Presentation & Lifecycle Action Hardening (complementary — rendering conventions), Operations Naming Harmonization (complementary — terminology), Admin Visual Language Canon (visual weight rules may inform overlay styling)
- **Priority**: medium

### Provider Connection Resolution Normalization
- **Type**: hardening
- **Source**: architecture audit – provider connection resolution analysis
- **Problem**: The codebase has a dual-resolution model for provider connections. Gen 2 jobs (`ProviderInventorySyncJob`, `ProviderConnectionHealthCheckJob`, `ProviderComplianceSnapshotJob`) receive an explicit `providerConnectionId` and pass it through the `ProviderOperationStartGate`. Gen 1 jobs (`ExecuteRestoreRunJob`, `EntraGroupSyncJob`, `SyncRoleDefinitionsJob`, policy sync jobs, etc.) do NOT — their called services resolve the default connection at runtime via `MicrosoftGraphOptionsResolver::resolveForTenant()` or internal `resolveProviderConnection()` methods. This creates non-deterministic execution: a job dispatched against one connection may silently execute against a different one if the default changes between dispatch and execution. ~20 services use the Gen 1 implicit resolution pattern.
- **Why it matters**: Non-deterministic credential binding is a correctness and audit gap. Enterprise customers need to know exactly which connection identity was used for every Graph API call. The implicit pattern also prevents connection-scoped rate limiting, error attribution, and consent-scope validation. This is the foundational refactor that unblocks all other provider connection improvements.
- **Proposed direction**:
  - Refactor all Gen 1 services to accept an explicit `ProviderConnection` (or `providerConnectionId`) parameter instead of resolving default internally
  - Update all Gen 1 jobs to accept `providerConnectionId` at dispatch time (resolved at the UI/controller layer via `ProviderOperationStartGate` or equivalent)
  - Deprecate `MicrosoftGraphOptionsResolver` — callers should use `ProviderGateway::graphOptions($connection)` directly
  - Ensure `provider_connection_id` is recorded in every `OperationRun` context and audit event
  - Standardize error handling: all resolution failures produce `ProviderConnectionResolution::blocked()` with structured `ProviderReasonCodes`, not mixed exceptions (`ProviderConfigurationRequiredException`, `RuntimeException`, `InvalidArgumentException`)
- **Known affected services** (Gen 1 / implicit resolution): `RestoreService` (line 2913 internal `resolveProviderConnection()`), `PolicySyncService` (lines 58, 450), `PolicySnapshotService` (line 752), `RbacHealthService` (line 192), `InventorySyncService` (line 730 internal `resolveProviderConnection()`), `EntraGroupSyncService`, `RoleDefinitionsSyncService`, `EntraAdminRolesReportService`, `AssignmentBackupService`, `AssignmentRestoreService`, `ScopeTagResolver`, `TenantPermissionService`, `VersionService`, `ConfigurationPolicyTemplateResolver`, `FoundationSnapshotService`, `FoundationMappingService`, `RestoreRiskChecker`, `PolicyCaptureOrchestrator`, `AssignmentFilterResolver`, `RbacOnboardingService`, `TenantConfigService`
- **Known affected jobs** (Gen 1 / no explicit connectionId): `ExecuteRestoreRunJob`, `EntraGroupSyncJob`, `SyncRoleDefinitionsJob`, `SyncEntraAdminRolesJob`, plus any job that calls a Gen 1 service
- **Gen 2 reference implementations** (correct pattern): `ProviderInventorySyncJob`, `ProviderConnectionHealthCheckJob`, `ProviderComplianceSnapshotJob` — all receive `providerConnectionId`, pass through `ProviderOperationStartGate`, lock row, create `OperationRun` with connection in context
- **Key architecture components**:
  - `ProviderConnectionResolver` — correct, keep as-is. `resolveDefault()` returns `ProviderConnectionResolution` value object
  - `ProviderOperationStartGate` — canonical dispatch-time gate, correct Gen 2 pattern. Handles 3 operation types: `provider.connection.check`, `inventory_sync`, `compliance.snapshot`
  - `MicrosoftGraphOptionsResolver` — legacy bridge (32 lines), target for deprecation. Calls `resolveDefault()` internally, hides connection identity
  - `ProviderGateway` — lower-level primitive, builds graph options from explicit connection. Correct, keep as-is
  - `ProviderIdentityResolver` — resolves identity (platform vs dedicated) from connection. Correct, keep as-is
  - Partial unique index on `provider_connections`: `(tenant_id, provider) WHERE is_default = true`
- **Out of scope**: UX label changes, UI banners, legacy credential field removal (those are separate candidates below)
- **Dependencies**: None — this is the foundational refactor
- **Related specs**: Spec 081 (Tenant credential migration CI guardrails), Spec 088 (provider connection model), Spec 089 (provider gateway), Spec 137 (data-layer provider prep)
- **Priority**: high

### Provider Connection UX Clarity
- **Type**: polish
- **Source**: architecture audit – provider connection resolution analysis
- **Problem**: The operator-facing language and information architecture around provider connections creates confusion about why a "default" connection is required, what happens when it's missing, and when actions are tenant-wide vs connection-scoped. Specific issues: (1) "Set as Default" is misleading — it implies preference, but the connection is actually the canonical operational identity; (2) missing-default errors surface as blocked `OperationRun` records or exceptions, but there is no proactive banner/hint on the tenant or connection pages; (3) action labels don't distinguish tenant-wide operations (verify, sync) from connection-scoped operations (health check, test); (4) the singleton auto-promotion (first connection becomes default automatically) is invisible — operators don't understand why their first connection was special.
- **Why it matters**: Reduces support friction and operator confusion. Enterprise operators managing multiple tenants need clear, predictable language about connection lifecycle. The current UX makes the correct architecture feel like a bug ("why do I need a default?").
- **Proposed direction**:
  - Rename "Set as Default" → "Promote to Primary" (or "Set as Primary Connection") across all surfaces
  - Add a missing-primary-connection banner on tenant detail / connection list when no default exists — with a direct "Promote" action
  - Distinguish action labels: tenant-wide actions ("Sync Tenant", "Verify Tenant") vs connection-scoped actions ("Check Connection Health", "Test Connection")
  - Improve blocked-notification copy: instead of generic "provider connection required", show "No primary connection configured for [Provider]. Promote a connection to continue."
  - Show a transient success notification when auto-promotion happens on first connection creation ("This connection was automatically set as primary because it's the first for this provider")
  - Consider an info tooltip or help text explaining the primary connection concept on the connection resource pages
- **Key surfaces to update**: `ProviderConnectionResource` (row actions, header actions, table empty state), `TenantResource` (verify action, connection tab), onboarding wizard consent step, `ProviderNextStepsRegistry` remediation links, notification templates for blocked operations
- **Auto-default creation locations** (4 places, need UX feedback): `CreateProviderConnection` action, `TenantOnboardingController`, `AdminConsentCallbackController`, `ManagedTenantOnboardingWizard`
- **Out of scope**: Backend resolution refactoring (that's the normalization candidate above), legacy field removal
- **Dependencies**: Soft dependency on "Provider Connection Resolution Normalization" — UX improvements are more coherent when the backend consistently uses explicit connections, but many label/banner changes can proceed independently
- **Related specs**: Spec 061 (provider connection UX), Spec 088 (provider connection model)
- **Priority**: medium

### Provider Connection Legacy Cleanup
- **Type**: hardening
- **Source**: architecture audit – provider connection resolution analysis
- **Problem**: After normalization is complete, several legacy artifacts remain: (1) `MicrosoftGraphOptionsResolver` — a 32-line convenience bridge that exists only because ~20 services haven't been updated to use explicit connections; (2) service-internal `resolveProviderConnection()` methods in `RestoreService` (line 2913), `InventorySyncService` (line 730), and similar — these are local resolution logic that should not exist once services receive explicit connections; (3) `Tenant` model legacy credential accessors (`app_client_id`, `app_client_secret` fields) — `graphOptions()` already throws `BadMethodCallException`, but the fields and accessors remain; (4) `migration_review_required` flag on `ProviderConnection` — used during the credential migration from tenant-level to connection-level, should be retired once all tenants are migrated.
- **Why it matters**: Dead code increases cognitive load and creates false affordances. New developers may use `MicrosoftGraphOptionsResolver` or internal resolution methods thinking they're the correct pattern. Legacy credential fields on `Tenant` suggest credentials still live there. Cleaning up after normalization makes the correct architecture self-documenting.
- **Proposed direction**:
  - Remove `MicrosoftGraphOptionsResolver` class entirely (after normalization ensures zero callers)
  - Remove all service-internal `resolveProviderConnection()` / `resolveDefault()` methods
  - Remove legacy credential fields from `Tenant` model (migration to drop columns, update factory, update tests)
  - Evaluate `migration_review_required` — if all tenants have migrated, remove the flag and related UI (banner, filter)
  - Update CI guardrails: `NoLegacyTenantGraphOptionsTest` and `NoTenantCredentialRuntimeReadsSpec081Test` can be simplified or removed once the code they guard against is gone
  - Verify no seeders, factories, or test helpers reference legacy patterns
- **Out of scope**: Any new features — this is pure cleanup
- **Dependencies**: Hard dependency on "Provider Connection Resolution Normalization" — cleanup cannot proceed until all callers are migrated
- **Related specs**: Spec 081 (credential migration guardrails), Spec 088 (provider connection model), Spec 137 (data-layer provider prep)
- **Priority**: medium (deferred until normalization is complete)

### Tenant App Status False-Truth Removal
- **Type**: hardening
- **Source**: legacy / orphaned truth audit 2026-03-16
- **Classification**: quick removal
- **Problem**: `Tenant.app_status` is displayed in tenant UI as current operational truth even though production code no longer writes it. Operators can see a frozen "OK" or other stale badge that does not reflect the real provider connection state.
- **Why it matters**: This is misleading operator-facing truth, not just dead schema. It creates false confidence on a tier-1 admin surface.
- **Target model**: `Tenant`
- **Canonical source of truth**: `ProviderConnection.consent_status` and `ProviderConnection.verification_status`
- **Must stop being read**: `Tenant.app_status` in `TenantResource` table columns, infolist/details, filters, and badge-domain mapping.
- **Can be removed immediately**:
  - TenantResource reads of `app_status`
  - tenant app-status badge domain / badge mapping usage
  - factory defaults that seed `app_status`
- **Remove only after cutover**:
  - the `tenants.app_status` column itself, once all UI/report/export reads are confirmed gone
- **Migration / backfill**: No backfill. One cleanup migration to drop `app_status`. `app_notes` may be dropped in the same migration only if it does not broaden the spec beyond tenant stale app fields.
- **UI / resource / policy / test impact**:
  - UI/resources: remove misleading badge and filter from tenant surfaces
  - Policy: none
  - Tests: update `TenantFactory`, remove assertions that treat `app_status` as live truth
- **Scope boundaries**:
  - In scope: remove stale tenant app-status reads and schema field
  - Out of scope: provider connection UX redesign, credential migration, broader tenant health redesign
- **Dependencies**: None required if the immediate operator-facing action is removal rather than replacement with a new tenant-level derived badge.
- **Risks**: Low rollout risk. Main risk is short-term operator confusion about where to view connection health after removal.
- **Why it should be its own spec**: This is the cleanest high-severity operator-trust fix in the repo. It is bounded, low-coupling, and should not wait for the larger provider cutover work.
- **Priority**: high

### Provider Connection Status Vocabulary Cutover
- **Type**: hardening
- **Source**: legacy / orphaned truth audit 2026-03-16
- **Classification**: bounded cutover
- **Problem**: `ProviderConnection` currently exposes overlapping status vocabularies across `status`, `health_status`, `consent_status`, and `verification_status`. Resources, badges, and filters can read both projected legacy state and canonical enum state, creating drift and operator ambiguity.
- **Why it matters**: This is duplicate status truth on an operator-facing surface. It also leaves the system vulnerable to projector drift if legacy projected fields stop matching the enum source of truth.
- **Target model**: `ProviderConnection`
- **Canonical source of truth**: `ProviderConnection.consent_status` and `ProviderConnection.verification_status`
- **Must stop being read**: `ProviderConnection.status` and `ProviderConnection.health_status` in resources, filters, badges, and any operator-facing status summaries.
- **Can be removed immediately**:
  - new operator-facing reads of legacy varchar status fields
  - new badge/filter logic that depends on normalized legacy values
- **Remove only after cutover**:
  - `status` and `health_status` columns
  - projector persistence of those fields, if still retained for compatibility
  - legacy badge normalization paths
- **Migration / backfill**: No data backfill if enum columns are already complete. Requires a later schema cleanup migration to drop legacy varchar columns after all reads are migrated.
- **UI / resource / policy / test impact**:
  - UI/resources: `ProviderConnectionResource` and related badges/filters move to one coherent operator vocabulary
  - Policy: none directly
  - Tests: add exhaustive projection and badge mapping coverage during the transition; update resource/filter assertions to enum-driven behavior
- **Scope boundaries**:
  - In scope: provider connection status fields, display semantics, badge/filter vocabulary, deprecation path for projected columns
  - Out of scope: tenant credential migration, provider onboarding flow redesign, unrelated badge cleanup elsewhere
- **Dependencies**: Confirm all hidden read paths outside the main resource and define the operator-facing enum presentation.
- **Risks**: Medium rollout risk. Filters, badges, and operator language change together, and hidden reads may exist outside the primary resource.
- **Why it should be its own spec**: This is a self-contained source-of-truth cutover on one model. It is too important and too operationally visible to bury inside a generic provider cleanup spec.
- **Priority**: high

### Tenant Legacy Credential Source Decommission
- **Type**: hardening
- **Source**: legacy / orphaned truth audit 2026-03-16
- **Classification**: staged migration
- **Problem**: Tenant-level credential fields remain in the data model after ProviderCredential became the canonical identity store. They are still used for migration classification and are kept artificially alive by factory defaults, which obscures the real architecture and prolongs the cutover.
- **Why it matters**: This is an incomplete architectural cutover around sensitive identity data. The system needs an explicit end-state where runtime credential resolution no longer depends on tenant legacy fields.
- **Target model**: `Tenant`, with `ProviderCredential` as the destination canonical model
- **Canonical source of truth**: `ProviderCredential.client_id` and `ProviderCredential.client_secret`
- **Must stop being read**: tenant legacy credential fields in normal runtime credential resolution. Transitional reads remain allowed only inside migration-classification paths until exit criteria are met.
- **Can be removed immediately**:
  - factory defaults that populate legacy tenant credentials by default
  - any non-classification runtime reads if discovered during spec work
  - UI affordances that imply tenant-stored credentials are active
- **Remove only after cutover**:
  - `Tenant.app_client_id`, `Tenant.app_client_secret`, `Tenant.app_certificate_thumbprint`
  - migration-classification reads and related transitional guardrails
- **Migration / backfill**: Requires explicit completion criteria for the tenant-to-provider credential migration. No blind backfill; removal should follow confirmed migration review state for all affected tenants.
- **UI / resource / policy / test impact**:
  - UI/resources: remove any residual legacy credential messaging once the cutover is complete
  - Policy: none directly
  - Tests: `TenantFactory` must stop creating legacy credentials by default; transition-only tests should use explicit legacy states
- **Scope boundaries**:
  - In scope: tenant legacy credential fields, classification-only transition reads, factory/test cleanup tied to the cutover
  - Out of scope: provider connection status vocabulary, unrelated tenant stale fields, onboarding UX redesign
- **Dependencies**: Hard dependency on the provider credential migration/review lifecycle being complete enough to identify all remaining transitional tenants safely.
- **Risks**: Higher rollout risk than simple cleanup because this touches credential-path architecture and transitional data needed for migration review.
- **Why it should be its own spec**: This has distinct exit criteria, migration gating, and rollback concerns. It is not the same problem as stale operator-facing badges or provider status vocabulary cleanup.
- **Priority**: high

### Entra Group Authorization Capability Alignment
- **Type**: hardening
- **Source**: legacy / orphaned truth audit 2026-03-16
- **Classification**: bounded cutover
- **Problem**: `EntraGroupPolicy` currently grants read access based on tenant access alone and bypasses the capability layer used by the rest of the repo's authorization model.
- **Why it matters**: This is a security- and RBAC-relevant inconsistency. Even if currently read-only, it weakens the capability-first architecture and increases the chance of future authorization drift.
- **Target model**: `EntraGroupPolicy` and the Entra group read-access surface
- **Canonical source of truth**: capability-based authorization decisions layered on top of tenant-access checks
- **Must stop being read**: implicit "tenant access alone is sufficient" as the effective rule for Entra group read access.
- **Can be removed immediately**:
  - the direct bypass if the correct capability already exists and seeded roles already carry it
- **Remove only after cutover**:
  - any compatibility allowances needed while role-capability mappings are updated and verified
- **Migration / backfill**: Usually no schema migration. May require role-capability seeding updates or RBAC backfill so intended operators retain access.
- **UI / resource / policy / test impact**:
  - UI/resources: some users may lose access if role mapping is incomplete; tenant-facing Entra group screens need regression verification
  - Policy: this spec is the policy change
  - Tests: add authorization matrix coverage proving tenant access alone no longer grants read access
- **Scope boundaries**:
  - In scope: read authorization semantics for Entra group surfaces and the required capability mapping
  - Out of scope: new CRUD semantics, role mapping product UI, unrelated policy tidy-up
- **Dependencies**: Choose the correct capability and verify seeded/default roles include it where intended.
- **Risks**: Medium rollout risk because authorization mistakes become access regressions for legitimate operators.
- **Why it should be its own spec**: This is a targeted RBAC hardening change with its own stakeholders, rollout checks, and regression matrix. It should not be hidden inside data or UI cleanup work.
- **Priority**: high

### Support Intake with Context (MVP)
- **Type**: feature
- **Source**: Product design, operator feedback
- **Problem**: Nutzer haben keinen strukturierten Weg, Probleme direkt aus dem Produkt zu melden. Bei technischen Fehlern fehlen Run-/Tenant-/Provider-Details; bei Access-/UX-Problemen fehlen Route-/RBAC-Kontext. Folge: ineffiziente Support-Schleifen und Rückfragen. Ein vollwertiges Ticketsystem ist falsch priorisiert.
- **Why it matters**: Reduziert Support-Reibung, erhöht Erfassungsqualität, steigert wahrgenommene Produktreife. Schafft typed intake layer für spätere Webhook-/PSA-/Ticketing-Erweiterungen, ohne jetzt ein Helpdesk einzuführen.
- **Proposed direction**: Neues `SupportRequest`-Modell (kein Ticket/Case) mit `source_type` (operation_run, provider_connection, access_denied, generic) und `issue_kind` (technical_problem, access_problem, ux_feedback, other). Drei Entry Paths: (1) Context-bound aus failed OperationRun, (2) Access-Denied/403-Kontext, (3) generischer Feedback-Einstieg (User-Menü). Automatischer Context-Snapshot per `SupportRequestContextBuilder` je source_type. Persistierung vor Delivery. E-Mail-Delivery an konfigurierte Support-Adresse. Fingerprint-basierter Spam-Guard. Audit-Events. RBAC via `support.request.create` Capability. Scope-Isolation. Secret-Redaction in context_jsonb.
- **Dependencies**: OperationRun-Domain stabil, RBAC/Capability-System (066+), Workspace-/Tenant-Scoping
- **Priority**: medium

### Policy Setting Explorer — Reverse Lookup for Tenant Configuration
- **Type**: feature
- **Source**: recurring enterprise pain point, governance/troubleshooting gap
- **Problem**: In medium-to-large Intune tenants with dozens of policy types and hundreds of policies, admins routinely face the question: "Where is this setting actually defined?" Examples: "Which policy configures BitLocker?", "Where is `EnableTPM` set to `true`?", "Why does this tenant enforce a specific firewall rule, and which policy is the source?" Today, answering this requires manually opening policies one by one across device configuration, compliance, endpoint security, admin templates, settings catalog, and more. TenantPilot inventories and versions these policies but provides no reverse-lookup surface that maps a setting name, key, or value back to the policies that explicitly define it.
- **Why it matters**: This is a governance, troubleshooting, and explainability gap — not a search convenience. Enterprise admins, auditors, and reviewers need authoritative answers to "where is X defined?" for incident triage, change review, compliance evidence, and duplicate detection. Without it, TenantPilot has deep policy data but cannot surface it from the operator's natural entry point (the setting, not the policy). This capability directly increases the product's value proposition for security reviews, audit preparation, and day-to-day configuration governance.
- **V1 scope**:
  - Tenant-scoped only. User queries settings within the active tenant's indexed policies. No cross-tenant or portfolio-wide search in V1.
  - Dedicated working surface: a tenant-level "Policy Explorer" or "Setting Search" page with query input, filters, and structured result inspection. Not a global header search widget.
  - Query modes: search by setting name/label, by raw key/path, or by value-oriented query (e.g. `EnableTPM = true`).
  - Results display: policy name, policy type/family, setting label/path/key, configured value, version/snapshot context, deep link to the policy detail or version inspector.
  - Supported policy families: start with a curated subset of high-value indexed families (settings catalog, device configuration, compliance, endpoint security baselines, admin templates). Not every Microsoft policy type from day one.
  - Search projection model: a lightweight extracted-setting-facts table per supported policy family. Preserves policy-family-local structure, retains raw path/key, stores search-friendly displayable rows. PostgreSQL-first (GIN indexes on JSONB or dedicated columns as appropriate). Not a universal canonical key normalization engine — a pragmatic, product-oriented search projection.
  - Trust boundary: results reflect settings explicitly present in supported indexed policies. UI must clearly communicate this scope. No-result does NOT imply the setting is absent from effective tenant configuration — only that it was not found in currently supported indexed policy families. This distinction must be visible in the UX (scope indicator, help text, empty-state copy).
  - "Defined in" only: V1 answers "where is this setting explicitly defined?" — it does NOT answer "is this setting effectively applied to devices/users?" The difference between explicit definition and effective state must be preserved and communicated.
- **Explicit non-goals (V1)**:
  - No universal cross-provider canonical setting ontology. Avoid a large fragile semantic mapping project. Setting identity stays policy-family-local in V1.
  - No effective-state guarantees. V1 does not resolve assignment targeting, conflict resolution, or platform-side precedence.
  - No portfolio / cross-tenant / workspace-wide scope.
  - No dependency on external search infrastructure (Elasticsearch, Meilisearch, etc.) if PostgreSQL-first is sufficient.
  - No naive raw JSON full-text search as the product surface. The projection model must provide structured, rankable, explainable results — not grep output.
  - No requirement to support every Microsoft policy family from day one.
- **Architectural direction**:
  - Search projection layer: when policies are synced/versioned, extract setting facts into a dedicated search-friendly projection (e.g. `policy_setting_facts` table or JSONB-indexed structure). Each row captures: `tenant_id`, `policy_id`, `policy_version_id` (nullable), `policy_type`/`family`, `setting_key`/`path`, `setting_label` (display name where available), `configured_value`, `raw_payload_path`. Extraction logic is per-family, not a universal parser.
  - PostgreSQL-first: use GIN indexes on JSONB or trigram indexes on text columns for efficient search. Evaluate `pg_trgm` for fuzzy matching.
  - Extraction is append/rebuild on sync — not real-time transformation. Can be a post-sync projection step integrated into the existing inventory sync pipeline.
  - Provider boundary stays explicit: the projection is populated by each policy family's extraction logic. No abstraction that pretends all policy families share the same schema.
  - RBAC: tenant-scoped, gated by a capability (e.g. `policy.settings.search`). Results respect existing policy-level visibility rules.
  - Audit: queries are loggable but do not require per-query audit entries in V1. The feature is read-only.
- **UX direction**:
  - Primary surface: dedicated page under the tenant context (e.g. tenant → Policy Explorer or tenant → Setting Search). Full working surface with query input, optional filters (policy type, policy family, value match mode), and a results table.
  - Result rows: policy name (linked), policy type badge, setting path/key, configured value, version indicator. Expandable detail or click-through to policy inspector.
  - Empty state: clearly explains scope limitations ("No matching settings found in supported indexed policies. This does not mean the setting is absent from your tenant's effective configuration.").
  - Scope indicator: persistent badge or label showing the search scope (e.g. "Searching N supported policy families in [tenant name]").
  - Future quick-access entry point (e.g. command palette, header search shortcut) is a natural extension but not V1 scope.
- **Future expansion space** (not V1):
  - Semantic aliases / display-name normalization across families
  - Duplicate / conflict detection hints ("this setting is defined in 3 policies")
  - Assignment-aware enrichment ("this policy targets group X")
  - Setting history / change timeline ("this value changed from false to true in version 4")
  - Baseline / drift linkage ("this setting deviates from the CIS baseline")
  - Workspace-wide / portfolio search across tenants
  - Quick-access command palette entry point
- **Risks / notes**:
  - Extraction logic per policy family is the main incremental effort. Each new family supported requires a family-specific extractor. Start with the highest-value families and expand.
  - Settings catalog policies have structured setting definitions that are relatively easy to extract. OMA-URI / admin template policies are less structured. The V1 family selection should favor extractability.
  - The "no-result ≠ not configured" trust boundary is critical for enterprise credibility. Overcommitting search completeness erodes trust.
  - Projection freshness depends on sync frequency. Stale projections must be visually flagged if the tenant hasn't been synced recently.
- **Dependencies**: Inventory sync stable, policy versioning (snapshots), tenant context model, RBAC capability system (066+)
- **Priority**: high

### Help Center / Documentation Surface
- **Type**: feature
- **Source**: product planning, operator support friction analysis
- **Problem**: TenantPilot lacks a central, searchable, in-product knowledge surface for operators. Product documentation, glossary content, workflow walkthroughs, and conceptual explanations are fragmented across specs, internal docs, and implicit operator expectations. Operators who need to understand a concept, look up a term, or read a walkthrough must leave the admin experience entirely.
- **Why it matters**: A canonical in-product documentation surface reduces support friction, enables self-service resolution, and makes advanced governance features more understandable and adoptable. This is the product's central knowledge layer — distinct from contextual inline help (separate candidate), page-level instructional panels (separate candidate), and onboarding next-step guidance (separate candidate). It is also distinct from audit/evidence/reporting artifacts. This is a product maturity and support-efficiency capability, not a content management system.
- **Proposed direction**:
  - Markdown-based documentation stored in-repo, rendered inside the Filament admin panel as a dedicated help center surface
  - Global documentation search across all help articles
  - Structured article hierarchy: conceptual docs, walkthroughs, glossary, role/capability explanations, domain-specific governance guidance
  - Clear separation between product help/knowledge and audit/report/evidence exports
  - Workspace/tenant context awareness only where helpful for navigation, not to turn docs into tenant data
  - Native first-party rendering approach — no external CMS dependency, no third-party documentation platform required
- **Explicit non-goals**: Not a customer support ticket system. Not an audit pack feature. Not a generic CMS. Not a replacement for external knowledge bases if those exist separately. Not the delivery mechanism for contextual inline help or page-level guidance panels — those are separate capabilities that may link into this surface but are independently spec-able. Not a video-first help strategy. Not a forced guided tour infrastructure. v1 does not include a `/system` help-management UI. Content authoring, editing, and lifecycle remain code/repo-driven. Any future `/system` surface is limited to governance/observability concerns, not CMS behavior.
- **Dependencies**: Filament panel infrastructure, existing navigation/information architecture
- **Related candidates**: Contextual Help and Inline Guidance Framework, Page-Level Guidance Patterns, Onboarding Guidance and Next-Step Surfaces, Documentation Generation Pipeline and Editorial Workflow
- **Priority**: medium

### Contextual Help and Inline Guidance Framework
- **Type**: feature
- **Source**: product planning, operator support friction analysis, governance UX complexity
- **Problem**: As TenantPilot's governance surface area grows — findings workflows, RBAC capabilities, provider connection lifecycle, restore risk assessment, compliance baselines — operators encounter complex concepts and multi-step workflows where the purpose, consequences, or next steps are not self-evident from the UI alone. There is no standard mechanism for surfacing short, targeted, inline explanations at the point of need. Operators must either already know the domain or leave the product to find help.
- **Why it matters**: Contextual help reduces cognitive load on high-complexity governance surfaces, decreases support escalations, and makes advanced features accessible to operators who are not domain experts. This is distinct from the central documentation surface (which is a browsable knowledge base) and from page-level instructional panels (which provide section-level orientation). Contextual help is the layer that answers "what does this mean?" and "what happens if I do this?" at the point of interaction.
- **Proposed direction**:
  - Standardized inline help entry points (e.g. `?` icon actions, help affordances on action buttons, info popovers on complex form fields) integrated with Filament's action and component patterns
  - Short-form help content rendered in slideover or modal surfaces — not tooltips, not a tooltip explosion
  - Help content is text-first: concise explanation of what the feature does, why it matters, and what happens next
  - Content sourced from markdown or structured help definitions stored in-repo, maintainable alongside code
  - Optional deep-link from contextual help into the central Help Center for extended reading
  - Clean integration with Filament v5 actions, render hooks, and CSS hook classes — no internal view publishing
  - First-party, native approach — no third-party guided-tour or walkthrough library dependency
- **Explicit non-goals**: Not a tooltip explosion across every field. Not a video-first help strategy. Not a forced guided tour or product walkthrough system. Not a replacement for the central Help Center documentation surface. Not intercom-style chat or conversational help. Not an onboarding checklist (separate candidate). Not a generic CMS feature. v1 does not include a `/system` help-management UI. Content authoring, editing, and lifecycle remain code/repo-driven. Any future `/system` surface is limited to governance/observability concerns, not CMS behavior.
- **Dependencies**: Filament panel infrastructure, action system (Filament v5 actions), Help Center / Documentation Surface (for deep-link target, but functionally independent)
- **Related candidates**: Help Center / Documentation Surface, Page-Level Guidance Patterns, Admin Visual Language Canon
- **Priority**: medium

### Page-Level Guidance Patterns
- **Type**: feature
- **Source**: product planning, governance UX complexity analysis
- **Problem**: Several TenantPilot admin pages serve governance-heavy, interpretation-heavy, or consequence-heavy functions — findings review, RBAC capability management, provider connection lifecycle, restore dry-run results, compliance baseline comparison, drift analysis. These pages present data and actions that require domain context to interpret correctly, but operators arrive without orientation. There is no standard pattern for providing page-level introductory guidance, "learn more" affordances, or instructional panels that help operators understand what a page shows, why it matters, and how to use it effectively.
- **Why it matters**: Page-level guidance reduces operator confusion on the product's most complex and highest-stakes surfaces. It bridges the gap between contextual inline help (which explains individual concepts) and the central documentation surface (which is a browsable reference). It provides section-level orientation without requiring operators to leave the page or consult external resources. For governance and compliance surfaces, clear page-level framing increases operator confidence and reduces misinterpretation of presented data.
- **Proposed direction**:
  - Standardized page-level instructional panel pattern: optional intro/help section at the top of qualifying pages, rendered via Filament render hooks or section components
  - "Learn more" affordances linking from the page context into the central Help Center for extended documentation
  - Pattern supports dismissibility and operator preference (e.g. collapsible, "don't show again" per-page or per-user)
  - Content stored as markdown or structured definitions in-repo, not hardcoded in Blade templates
  - Visual pattern consistent with the Admin Visual Language Canon direction — does not introduce a new visual system
  - Qualifying page criteria: governance-heavy pages, consequence-heavy action pages, interpretation-heavy data review pages. Not every list page or simple CRUD form.
- **Explicit non-goals**: Not a banner/notification system. Not contextual inline help for individual fields or actions (separate candidate). Not onboarding step-by-step flow (separate candidate). Not a forced walkthrough or modal tutorial. Not applied universally to every admin page — only where governance complexity warrants it. v1 does not include a `/system` help-management UI. Content definitions remain code/repo-driven. Any future `/system` surface is limited to governance/observability concerns, not CMS behavior.
- **Dependencies**: Filament panel infrastructure, render hooks, Admin Visual Language Canon (for visual consistency), Help Center / Documentation Surface (for "learn more" link targets)
- **Related candidates**: Help Center / Documentation Surface, Contextual Help and Inline Guidance Framework, Admin Visual Language Canon
- **Priority**: low

### Onboarding Guidance and Next-Step Surfaces
- **Type**: feature
- **Source**: product planning, operator time-to-value analysis
- **Problem**: New operators and new tenants arrive in TenantPilot without structured product-level guidance about what to do next. The managed-tenant onboarding wizard handles the technical setup flow (consent, connection, initial sync), but after onboarding completes — or for operators exploring governance features for the first time — there is no product-level guidance surface that helps operators understand what is available, what to configure next, or how to reach productive use of governance workflows. Empty states, action labels, and page descriptions do not consistently communicate next steps or paths to value.
- **Why it matters**: Reduces time-to-value for new operators without introducing a forced product tour. Improves discoverability of governance features (findings, baselines, RBAC, drift, reporting) by surfacing actionable next steps rather than relying on operators to discover capabilities through sidebar exploration. Improves the quality of empty states and first-use experiences across the product. This is a product adoption and operator efficiency capability, not a marketing or onboarding conversion feature.
- **Proposed direction**:
  - Smart empty states with actionable next-step guidance on high-value surfaces (e.g. findings list with no findings yet, backup history with no backups, dashboard with no synced tenants)
  - Optional post-onboarding next-step surface or checklist-style orientation (not a forced wizard — an opt-in guidance panel or dedicated page)
  - Descriptive action labels and page descriptions that reduce confusion about what features do, especially on first encounter
  - Progress-aware guidance: surfaces that adapt based on what the operator has already configured (e.g. "sync complete — next: review your compliance baseline" vs. "no sync yet — start here")
  - Lightweight, maintainable: guidance content stored as structured definitions in-repo, not hardcoded across scattered Blade templates
  - Native Filament integration via empty states, info sections, and render hooks
- **Explicit non-goals**: Not a forced guided tour or product walkthrough. Not a video-first onboarding strategy. Not a step-by-step wizard for every product feature. Not a tooltip explosion. Not a replacement for the managed-tenant onboarding wizard (which handles technical setup). Not a marketing/conversion funnel. Not a third-party onboarding library integration (e.g. no Appcues, no Intercom tours). Not the same as contextual inline help (separate candidate) or page-level instructional panels (separate candidate). v1 does not include a `/system` help-management UI. Guidance definitions remain code/repo-driven. Any future `/system` surface is limited to governance/observability concerns, not CMS behavior.
- **Dependencies**: Filament panel infrastructure, empty-state patterns, Admin Visual Language Canon (for visual consistency), managed-tenant onboarding wizard (Spec 001 and follow-ups — this candidate covers life after technical onboarding)
- **Related candidates**: Help Center / Documentation Surface, Contextual Help and Inline Guidance Framework, Page-Level Guidance Patterns
- **Priority**: medium

### Documentation Generation Pipeline and Editorial Workflow
- **Type**: feature
- **Source**: product planning, documentation sustainability analysis
- **Problem**: Even with a markdown-based knowledge layer, documentation quality and coverage will degrade without a lightweight authoring pipeline. The product needs a structured way to generate document skeletons/templates, support repeatable documentation workflows, and optionally use AI-assisted drafting without treating generated text as authoritative by default.
- **Why it matters**: Without a documentation pipeline, docs become inconsistent, coverage drifts as features grow, teams fall back to ad hoc writing, the help layer becomes expensive to maintain, and future AI-assisted documentation lacks guardrails.
- **Proposed direction**:
  - Document skeleton or template generation (e.g. command/tooling such as `docs:generate`)
  - Structured frontmatter / metadata expectations where useful
  - Editorial states such as draft / needs review / published
  - Explicit "AI draft needs review" semantics to distinguish generated drafts from canonical reviewed documentation
  - Repo-native markdown workflow as the source of truth
- **Explicit non-goals**: Not a replacement for careful documentation authorship. Not a public marketing content engine. Not a promise of autonomous documentation generation. This is an internal/product documentation pipeline and editorial guardrail layer.
- **Dependencies**: Help Center / Documentation Surface (this candidate builds on the rendering/delivery surface)
- **Priority**: low

### Drift Notifications Settings Surface
- **Type**: feature
- **Source**: product planning, governance alerting direction
- **Problem**: TenantPilot has governance/alerting direction, but operators still lack a clear product surface to configure drift-related notification behavior in a predictable way. Without a dedicated settings experience, alert routing feels infrastructural rather than operator-manageable.
- **Why it matters**: Operators need tenant/workspace-level control over how governance signals reach them — email, Microsoft Teams, severity-aware routing, notification fatigue reduction, and confidence that important drift events will not be silently missed. Especially relevant for MSP-style operations and ongoing tenant reviews.
- **Proposed direction**:
  - Dedicated settings-level drift notification management surface
  - Delivery targets such as email and Teams
  - Routing preferences by severity / event type where appropriately bounded
  - Sensible defaults with cooldown / dedup / quiet-hours framing if those concepts already exist in the broader alerting direction
  - Clear alignment with broader Alerts v1 direction, focused on the operator settings UX and configuration model
- **Explicit non-goals**: Not a reinvention of the whole alerts engine. Not a generic notification center for every product event. This is the operator-facing configuration surface for drift/governance notifications.
- **Dependencies**: Alerting v1 direction, drift detection foundation (Spec 044), tenant/workspace context model
- **Priority**: medium

### Drift Change Governance — Approval Workflows, Freeze Windows, Tamper Detection
- **Type**: feature
- **Source**: roadmap-to-spec coverage audit 2026-03-18, 0800-future-features brainstorming (pillar #2 — Drift & Change Governance / "Zahlhebel #1")
- **Problem**: TenantPilot's drift/baseline engine (Specs 116–119) detects configuration changes and surfaces them as findings. But detection alone does not govern _when_ and _how_ changes are allowed. There is no approval workflow for high-risk configuration changes, no protected time windows during which changes are blocked or escalated, and no tamper detection that distinguishes authorized changes from suspicious or unauthorized modifications. The drift engine answers "what changed?"; this capability answers "was the change allowed, and should it have happened now?"
- **Why it matters**: Change governance is the #2 revenue lever identified in product brainstorming. Enterprise customers and MSPs managing production tenants need controlled change processes — especially for high-risk policy families (endpoint security, compliance, conditional access). Without approval workflows and freeze windows, every detected drift is reactive: something already happened, the only question is whether to accept or revert it. Adding a governance layer turns drift from a detection feature into a change-control platform — the core value proposition for regulated environments, MSP SLA enforcement, and enterprise change management.
- **Proposed direction**:
  - **Change approval workflows**: define which policy families, change types, or severity levels require explicit approval before being accepted in the governance record. Approval can be gated by capability (e.g. `drift.change.approve`), with structured approval/rejection, justification, actor, and timestamp. Approval workflows are governance-layer constructs — they do not block changes in Intune (TenantPilot does not control the mutation path in the source tenant), but they govern how TenantPilot treats detected changes: approved (accepted into baseline), rejected (escalated as governance violation), pending (awaiting review).
  - **Protected / frozen windows**: workspace- or tenant-level configuration of time periods during which detected changes are automatically escalated or flagged (e.g. "no high-risk changes accepted during weekend maintenance windows" or "freeze all baseline-covered policy families during audit preparation"). Freeze windows do not prevent changes in Intune — they elevate the governance response when changes are detected during protected periods.
  - **Tamper / suspicious change detection**: heuristic or rule-based identification of changes that look unauthorized or anomalous — changes outside business hours, changes by unexpected actors, bulk changes across multiple policy families, changes to policies that haven't been modified in extended periods. These produce elevated findings or alerts, not automated blocks.
  - **Integration with existing drift/findings pipeline**: change governance operates on top of the drift detection pipeline. It consumes drift findings and applies governance rules (approval requirements, freeze window evaluation, tamper heuristics) to classify and route them. It does not replace the detection engine.
- **Explicit non-goals**: Not a rewrite or replacement of the drift/baseline engine (Specs 116–119 handle detection; this handles governance response). Not a DevOps CI/CD pipeline or deployment system — TenantPilot does not deploy to Intune tenants. Not a mutation-path control mechanism — TenantPilot cannot prevent changes in the source tenant; it can only govern how detected changes are classified and acted upon. Not a generic security hardening bucket. Not a real-time blocking proxy between operators and Intune.
- **Boundary with drift/baseline engine (Specs 116–119)**: Drift engine = detect changes, capture content, produce findings. Change governance = classify detected changes against approval/freeze/tamper rules, route them through governance workflows. The engine feeds this layer; this layer does not modify detection behavior.
- **Boundary with Drift Notifications Settings Surface**: Drift notifications = operator-facing configuration of alert delivery for drift events. Change governance = approval workflows, freeze windows, tamper classification. Notifications deliver signals; governance adds workflow, classification, and control semantics.
- **Boundary with Exception / Risk-Acceptance Workflow for Findings**: Risk acceptance = post-hoc acknowledgment that a known finding is intentionally accepted. Change governance = pre/peri-change classification of whether a detected change was authorized and occurred under acceptable conditions. Different lifecycle positions, complementary capabilities.
- **Dependencies**: Drift/baseline engine (Specs 116–119) fully shipped, findings workflow (Spec 111), alerting foundations (Specs 099/100), audit log foundation (Spec 134), RBAC/capability system (066+)
- **Priority**: medium (high strategic and revenue value, but depends on drift engine and findings workflow maturity)

### User Invitations and Directory-based User Selection
- **Type**: feature
- **Source**: product planning, access-management UX analysis
- **Problem**: Workspace and tenant membership flows currently lack a polished enterprise-grade invitation and directory-assisted user selection experience. Operators should not need brittle manual steps to add the right person to the right workspace/tenant context.
- **Why it matters**: Improves onboarding speed, operator/admin efficiency, correctness of membership assignment, enterprise credibility of the access-management UX, and future scalability of workspace/tenant administration.
- **Proposed direction**:
  - Directory-based user lookup / selection where supported
  - Invitation flows initiated directly from membership management surfaces
  - Invitation link / invitation lifecycle support
  - Clear distinction between selecting an existing directory identity vs inviting a not-yet-active participant
  - Alignment with existing RBAC / membership / workspace-first context model
- **Explicit non-goals**: Not a full identity-provider redesign. Not a replacement for the Entra auth architecture. Not a generic address-book feature. This is a bounded access-administration workflow improvement.
- **Dependencies**: RBAC/capability system (066+), workspace membership model, Entra identity integration
- **Priority**: medium

<!-- Row Interaction / Action Surface follow-up cluster (2026-03-16) -->

> **Action Surface follow-up direction** — The action-surface contract foundation (Specs 082, 090) and the follow-up taxonomy/viewer specs (143–146) are all fully implemented. The remaining gaps are not architectural redesign — they are incomplete adoption, missing decision criteria, and scope boundaries that haven't expanded to cover all product surfaces. The correct shape is: one foundation amendment to codify the missing rules and extend contract scope (v1.1), two compliance rollout specs to enroll currently-exempted surface families, and one targeted correction to fix the clearest remaining anti-pattern on a high-signal surface. This avoids reinventing the architecture, avoids umbrella "consistency" specs, and produces bounded, independently shippable work. TenantResource lifecycle-conditional actions and PolicyResource More-menu ordering are addressed by the updated foundation rules, not by standalone specs. Widgets, choosers, and pickers remain deferred/exempt.

### Action Surface Contract v1.1 — Decision Criteria, Ordering Rules, and System Scope Extension
- **Type**: foundation/spec amendment
- **Source**: row interaction / action surface architecture analysis 2026-03-16
- **Problem**: The action-surface contract (Spec 082) establishes profiles, slots, affordances, validator tests, and guard tests — but does not codify three things: (1) formal decision criteria for when a surface should use ClickableRow vs ViewAction vs PrimaryLinkColumn as its inspect affordance; (2) ordering rules for actions inside the More menu (destructive-last, lifecycle position, stable grouping); (3) system-panel table surfaces are explicitly excluded from contract scope, meaning ~6 operational surfaces have no declaration and no CI coverage. The architecture is correct; it just cannot prevent inconsistent choices on new surfaces or catch drift on existing ones.
- **Why this is its own spec**: This is a foundation amendment — it changes the rules that all other surfaces must follow. Rollout specs (system panel enrollment, relation manager enrollment) depend on this spec's updated rules existing first. Merging rollout work into a foundation amendment blurs the boundary between "what the rules are" and "who must comply."
- **In scope**:
  - Codify inspect-affordance decision tree (ClickableRow default, ViewAction exception criteria, PrimaryLinkColumn criteria) in `docs/ui/action-surface-contract.md`
  - Define the "lone ViewAction" anti-pattern formally and add it to validator detection
  - Codify More-menu action ordering rules (lifecycle actions, severity ordering, destructive-last)
  - Extend contract scope so system-panel table surfaces are enrollable (not exempt by default)
  - Add guidance that cross-panel surface taxonomy should converge where semantically equivalent
  - Update `ActionSurfaceValidator` to enforce new criteria
  - Update guard/contract tests to cover new rules
- **Non-goals**:
  - Retrofitting all existing system-panel pages (separate rollout spec)
  - Retrofitting all relation managers (separate rollout spec)
  - One-off resource-level fixes (those are tasks within rollout or correction specs)
  - TenantResource or PolicyResource redesign (addressed by applying the updated rules, not by dedicated specs)
  - Chooser/picker/widget contracts (remain deferred/exempt)
- **Depends on**: Spec 082, Spec 090 (both fully complete — this extends their foundation)
- **Suggested order**: First. All other candidates in this cluster depend on the updated rules.
- **Risk**: Low. This adds rules and extends scope — it does not change existing compliant declarations.
- **Why this boundary is right**: Foundation rules must be codified before rollout enforcement. Mixing rule definition with compliance rollout makes it impossible to review the rules independently and creates circular dependencies.
- **Priority**: high

### System Panel Action Surface Contract Enrollment
- **Type**: compliance rollout
- **Source**: row interaction / action surface architecture analysis 2026-03-16
- **Problem**: System-panel table surfaces (Ops/Runs, Ops/Failures, Ops/Stuck, Directory/Tenants, Directory/Workspaces, Security/AccessLogs) use `recordUrl()` consistently but have no `ActionSurfaceDeclaration`, no CI coverage, and are exempt from the contract by default. They are the largest family of undeclared table surfaces in the product.
- **Why this is its own spec**: System-panel surfaces belong to a different panel with different operator audiences and potentially different profile requirements. Enrolling them is a distinct compliance effort from tenant-panel relation managers or targeted resource corrections. The scope is bounded and independently shippable.
- **In scope**:
  - Declare `ActionSurfaceDeclaration` for each system-panel table surface (~6 pages)
  - Map to existing profiles where semantically correct (e.g., `ListOnlyReadOnly` for access logs, `RunLog` for ops run tables)
  - Introduce new system-specific profiles only if existing profiles truly do not fit
  - Remove enrolled system-panel pages from `ActionSurfaceExemptions` baseline
  - Add guard test coverage for enrolled system surfaces
- **Non-goals**:
  - Tenant-panel resource declarations (already covered by Spec 090)
  - Relation manager enrollment (separate candidate)
  - Non-table system pages (dashboards, diagnostics, choosers)
  - System-panel RBAC redesign
  - Cross-workspace query authorization (tracked as "System Console Scope Hardening" candidate)
- **Depends on**: Action Surface Contract v1.1 (must extend scope to system panel first)
- **Suggested order**: Second, in parallel with "Run Log Inspect Affordance Alignment" after v1.1 is complete.
- **Risk**: Low. These surfaces already behave consistently; this work adds formal declarations and CI coverage.
- **Why this boundary is right**: System-panel enrollment is self-contained — it doesn't touch tenant-panel resources or relation managers. Completing it independently gives CI coverage over a currently-invisible surface family.
- **Priority**: medium

### Relation Manager Action Surface Contract Enrollment
- **Type**: compliance rollout
- **Source**: row interaction / action surface architecture analysis 2026-03-16
- **Problem**: Three relation managers (`BackupItemsRelationManager`, `TenantMembershipsRelationManager`, `WorkspaceMembershipsRelationManager`) are in the `ActionSurfaceExemptions` baseline with no declaration. They were exempted during initial rollout (Spec 090) because relation-manager-specific profile semantics were not yet settled. Three other relation managers already have declarations. The exemption should be reduced, not permanent.
- **Why this is its own spec**: Relation managers have different interaction expectations than standalone list resources (context is always nested under a parent record, pagination/empty-state semantics differ, attach/detach may replace create/delete in some cases). Enrollment requires relation-manager-specific review of profile fit, not just copying resource-level declarations.
- **In scope**:
  - Declare `ActionSurfaceDeclaration` for each currently-exempted relation manager (3 components)
  - Validate profile fit (`RelationManager` profile vs a more specific variant)
  - Reduce `ActionSurfaceExemptions` baseline by removing enrolled relation managers
  - Add guard test coverage
- **Non-goals**:
  - Redesigning backup item management UX
  - Redesigning membership management UX
  - Parent resource changes (TenantResource, WorkspaceResource)
  - Full restore/backup domain redesign
  - Introducing new relation managers
- **Depends on**: Action Surface Contract v1.1 (for any updated profile guidance or relation-manager-specific ordering rules)
- **Suggested order**: Third, after both v1.1 and System Panel Enrollment are complete. Lowest urgency because these surfaces are low-traffic and already functionally correct.
- **Risk**: Low. These relation managers already work correctly. This adds formal compliance, not behavioral change.
- **Why this boundary is right**: Relation manager enrollment is a distinct surface family with its own profile semantics. Mixing it with system-panel enrollment or targeted resource corrections would create an unfocused rollout spec.
- **Priority**: low

### Run Log Inspect Affordance Alignment
- **Type**: targeted surface correction
- **Source**: row interaction / action surface architecture analysis 2026-03-16
- **Problem**: `OperationRunResource` declares the `RunLog` profile with `ViewAction` as its inspect affordance. In practice, it renders a lone `ViewAction` in the actions column — the "lone ViewAction" anti-pattern identified in `docs/ui/action-surface-contract.md`. The row-click-first direction means this surface should use `ClickableRow` drill-down to the canonical tenantless viewer (`OperationRunLinks::tenantlessView()`), not a standalone View button. This surface is also inherited by the `Monitoring/Operations` page (which delegates to `OperationRunResource::table()`), so the fix propagates to both surfaces.
- **Why this is its own spec**: This is the single highest-signal concrete violation of the action-surface contract direction. It is bounded to one resource declaration + one inherited page. It does not require rewriting the canonical viewer, redesigning the operations domain, or touching other monitoring surfaces. Keeping it separate from foundation amendments ensures it can ship quickly after v1.1 codifies the anti-pattern rule.
- **In scope**:
  - Change `OperationRunResource` inspect affordance from `ViewAction` to `ClickableRow`
  - Verify `recordUrl()` points to the canonical tenantless viewer
  - Remove the lone `ViewAction` from the actions column
  - Confirm the change propagates correctly to `Monitoring/Operations` (which delegates to `OperationRunResource::table()`)
  - Update/add guard test assertion for the corrected declaration
- **Non-goals**:
  - Rewriting the canonical operation viewer (Spec 144 already complete)
  - Broad operations UX redesign
  - All monitoring pages (Alerts, Stuck, Failures are separate surfaces with distinct interaction models)
  - RestoreRunResource alignment (currently exempted — separate concern)
  - Action hierarchy / More-menu changes on this surface (belong to a general rollout, not this correction)
- **Depends on**: Action Surface Contract v1.1 (for codified anti-pattern rule and ClickableRow-default guidance)
- **Suggested order**: Second, in parallel with "System Panel Enrollment" after v1.1 is complete. Quickest win and highest signal correction.
- **Risk**: Low. Single resource, no behavioral regression, no data model change.
- **Why this boundary is right**: One resource, one anti-pattern, one fix. Expanding scope to "all run-log surfaces" or "all operation views" would turn a quick correction into a rollout spec and delay the most visible improvement.
- **Priority**: medium

### Admin Visual Language Canon — First-Party UI Convention Codification and Drift Prevention
- **Type**: foundation
- **Source**: admin UI consistency analysis 2026-03-17
- **Problem**: TenantPilot has accumulated a strong set of first-party visual conventions across Filament resources, widgets, detail pages, badges, status indicators, action hierarchies, and operational surfaces. These conventions are emerging organically and are already broadly consistent — but they remain implicit. No canonical reference defines when to use native Filament patterns vs custom enterprise-detail compositions, which badge/status semantics apply to which domain states, how timestamps should render (`since()` vs absolute datetime vs contextual format), what the card/section/surface hierarchy rules are, which widget composition strategies are canonical, or where cross-panel visual divergence is intentional vs accidental. As the product's surface area grows — new policy families, new governance domains, new operational pages, new evidence/reporting surfaces — the risk is not current visual chaos but future drift caused by missing written selection criteria and decision rules.
- **Why it matters**: Without a codified visual language reference, each new surface is a local design decision made without canonical guidance. This produces slow, cumulative inconsistency that becomes expensive to correct retroactively and degrades enterprise UX credibility. The problem is amplified by multi-agent development: multiple contributors (human and AI) cannot converge on implicit conventions they haven't seen documented. The value is not aesthetic — it is architectural: a canonical reference prevents divergent local choices, reduces review friction, accelerates new surface development, and establishes a stable foundation for the product's long-term visual identity without introducing third-party theme dependencies.
- **Proposed direction**:
  - Codify the existing first-party admin visual conventions as a canonical reference document (e.g. `docs/ui/admin-visual-language.md` or similar), covering:
    - Badge/status semantics: color mapping rules, icon usage criteria, domain-specific badge extraction patterns, when to use Filament native badge vs custom status composition
    - Timestamp rendering: decision rules for `since()` (relative) vs absolute datetime vs contextual format, with domain-specific overrides where justified
    - Action hierarchy: primary action vs header actions vs row actions vs bulk actions presentation conventions (complementing the Action Surface Contract's interaction-level rules with visual-level guidance)
    - Widget composition: selection criteria for stat cards, chart widgets, list widgets, and custom compositions; density and grouping rules
    - Surface/card/section hierarchy: when to use native Filament sections vs custom detail cards vs grouped infoblocks; nesting and visual weight rules
    - Enterprise-detail page composition: canonical structure for entity detail/view pages (header, metadata, status, content sections, related data)
    - Cross-panel visual divergence: explicit rules for where admin-panel and system-panel styling may diverge and where they must converge
    - Typography and spacing: canonical use of Filament's built-in text scales and spacing tokens; rules against ad hoc inline styles
  - Establish guardrails against ad hoc local visual overrides (documented anti-patterns, PR review checklist items, or lightweight CI checks where practical)
  - Explicitly state that native Filament v5 configuration and CSS hook classes remain the primary styling foundation; a thin first-party theme layer is only justified if native configuration proves insufficient for a documented, bounded set of requirements
  - Explicitly reject third-party theme packages (e.g. Filament theme marketplace packages) as an architectural baseline unless separately justified by a dedicated evaluation spec with clear acceptance criteria
  - Where existing conventions have already diverged, define the canonical choice and flag surfaces that need alignment (as future cleanup tasks, not as part of this spec's implementation scope)
- **In scope**:
  - Inventory of existing visual conventions across tier-1 admin surfaces (resources, detail pages, dashboards, operational views)
  - Canonical reference document with decision rules and examples
  - Anti-pattern catalog (known visual drift patterns to avoid)
  - Lightweight enforcement strategy (review checklist, optional CI, or validator approach)
  - Explicit architectural position on theme dependencies
- **Out of scope**:
  - Visual redesign of any existing surface (this is codification, not redesign)
  - Aesthetic refresh or "make it look nicer" polish work
  - Third-party theme evaluation, selection, or integration
  - Broad Filament view publishing or deep customization layer
  - Marketing/branding/identity work (this is internal admin UX, not external brand)
  - Color palette redesign or new design-system creation
  - Retrofitting all existing surfaces to strict compliance (alignment cleanup is tracked separately per surface)
- **Key architectural positions**:
  - Native Filament v5 remains the primary visual foundation. The product's visual identity is expressed through intentional use of native Filament configuration, not through override layers.
  - CSS hook classes are the canonical customization mechanism where native configuration is insufficient. No publishing of Filament internal views for styling purposes.
  - The main gap is missing canonical reference and decision rules, not missing components or missing technology.
  - The value proposition is preventing future UI drift as more surfaces are added, not correcting a current visual crisis.
- **Dependencies**: Action Surface Contract (Spec 082 / v1.1 candidate) for interaction-level conventions that this visual-level reference complements but does not duplicate. Operations Naming Harmonization candidate for operator-facing terminology alignment that is a distinct concern from visual conventions.
- **Related candidates**: Action Surface Contract v1.1, Operations Naming Harmonization, Help Center / Documentation Surface (the visual language reference could eventually link from contextual help)
- **Trigger / best time to do this**: Before the next wave of new governance domain surfaces (Entra Role Governance, Enterprise App Governance, SharePoint Sharing Governance, Evidence Domain) and before the Policy Setting Explorer UX, so those surfaces are built against documented canonical conventions rather than best-effort pattern matching.
- **Risks if ignored**: Slow visual drift across surfaces, increasing review friction for new surfaces, divergent local conventions that become expensive to reconcile, weakened enterprise UX credibility as surface count grows, and higher cost of eventual systematic alignment.
- **Priority**: medium

### Surface Signal-to-Noise Optimization — Metadata Hierarchy and Information Density
- **Type**: hardening
- **Source**: UI/UX audit — consistency and noise reduction analysis
- **Problem**: Across TenantPilot's operator-facing list pages, detail views, and table surfaces, secondary metadata (timestamps, technical identifiers, raw provider keys, policy family labels, scope tag counts) often renders with the same visual prominence as primary content (policy name, status, outcome, tenant name). This creates a "wall of equal-weight information" where operators must mentally parse every row to find the signal that matters. Specific patterns: (1) date/time format inconsistency — some surfaces use `since()` (relative time), others use absolute datetime, with no clear rule for when each is appropriate; (2) technical identifiers (Graph API entity IDs, internal run IDs, provider-specific keys) surface in columns or info entries where they add no operator value; (3) badge/indicator density — some table rows have 3–4 badges (status, outcome, type, provider) where a simpler hierarchy would communicate the same information with less cognitive load; (4) column label and truncation inconsistency — overlong policy names, setting paths, or assignment descriptions push column layouts into horizontal scroll or wrap awkwardly without consistent truncation conventions; (5) metadata-to-action ratio — some detail/view pages dedicate more viewport space to metadata fields than to the actionable governance information the page exists to serve.
- **Why it matters**: Enterprise governance UX credibility depends on perceived information quality, not just data completeness. A surface that shows everything with equal visual weight communicates "we don't know what's important" to operators processing dozens of policies, hundreds of operation runs, or fleet-level tenant summaries daily. Noise reduction is not aesthetics — it is usability: faster scanning, fewer misreadings, lower cognitive fatigue, and higher confidence that the visible information is the information that matters. This is particularly important as TenantPilot adds more governance domains (Entra roles, enterprise apps, compliance baselines, evidence surfaces) — each new domain adds columns, badges, and metadata fields, and without a noise-reduction pass, information density will compound rather than degrade gracefully.
- **Proposed direction**:
  - **Date/time format decision rules**: codify when to use relative time (`since()`, "2 hours ago"), when to use absolute datetime, and when to use contextual format (date only for old entries, time only for today). Apply consistently across all list and detail surfaces. Relative time is appropriate for recency-sensitive contexts (last sync, last backup, operation age); absolute datetime is appropriate for audit/evidence contexts (created_at, snapshot timestamp). Both should render with appropriate visual weight (secondary text style for timestamps in list columns, not primary text weight).
  - **Technical identifier suppression**: audit list and detail surfaces for raw IDs, Graph API entity IDs, and internal identifiers that serve no operator purpose. Suppress or move to expandable/copyable detail panels. Operators should see human-readable labels, not internal keys, unless they explicitly request technical detail.
  - **Badge density reduction**: establish a per-row badge budget or hierarchy rule — primary status badge, optional outcome badge, context labels where needed, but not every possible dimension as a visible badge. Secondary indicators can be tooltips, expandable detail, or column values instead of badges.
  - **Truncation and column conventions**: define consistent truncation rules for long text fields in table columns (policy names, setting paths, assignment descriptions). Prefer tooltip-on-truncation over horizontal scroll. Define maximum comfortable column count for primary list surfaces.
  - **Metadata visual weight hierarchy**: establish a 3-tier visual weight system for metadata: primary (name, status — full weight), secondary (type, updated_at, tenant — reduced weight, secondary text color), tertiary (ID, raw key, scope tag count — hidden by default, available on demand). Apply across list and detail surfaces.
- **In scope**: metadata visual weight hierarchy rules, date/time format conventions, technical identifier suppression audit, badge density guidelines, truncation conventions, affected surface inventory, implementation of conventions on highest-traffic surfaces
- **Out of scope**: visual redesign or aesthetic refresh (this is hierarchy and noise reduction, not a design overhaul), Admin Visual Language Canon codification (which writes down the full visual convention set — this candidate solves one specific problem within that space), empty states (covered by Spec 122), action hierarchy (covered by Action Surface Contract), new component development, third-party theme integration
- **Boundary with Admin Visual Language Canon**: The Canon is a codification and drift-prevention effort — it documents all visual conventions to prevent future divergence. This candidate identifies and resolves a specific, measurable UX problem (excess metadata noise) that exists today. The solutions from this candidate should feed into the Canon's documented conventions, but this candidate produces concrete UX improvements, not just documentation. The Canon defines the rules; this candidate fixes the violations that currently hurt operator experience.
- **Boundary with Operator Presentation & Lifecycle Action Hardening**: That candidate owns shared rendering conventions for operation labels and status badges via centralized abstractions (OperationCatalog, BadgeRenderer). This candidate owns the broader question of how much metadata should be visible and at what visual weight — a problem that extends beyond operations to all governance surfaces.
- **Boundary with Spec 122 (Empty State Consistency)**: Empty states address surfaces with no data. This candidate addresses surfaces with data that presents too much secondary information with too little hierarchy. Complementary problems at opposite ends of the information-density spectrum.
- **Dependencies**: Admin Visual Language Canon (soft dependency — conventions established here should align with or feed into the Canon), existing Filament table/infolist infrastructure, BadgeRenderer/BadgeCatalog (for badge rendering conventions)
- **Related candidates**: Admin Visual Language Canon (complementary — visual convention codification), Operator Presentation & Lifecycle Action Hardening (complementary — rendering conventions), Spec 122 (complementary — empty state consistency)
- **Priority**: medium

### Infrastructure & Platform Debt — CI, Static Analysis, Test Parity, Release Process
- **Type**: hardening
- **Source**: roadmap-to-spec coverage audit 2026-03-18, Infrastructure & Platform Debt table in `docs/product/roadmap.md`
- **Problem**: TenantPilot's product architecture and governance domain have matured significantly, but the surrounding delivery infrastructure has not kept pace. The roadmap acknowledges six open infrastructure debt items — no CI pipeline, no static analysis (PHPStan/Larastan), SQLite-for-tests vs. PostgreSQL-in-production schema drift risk, no `.env.example`, no formal release process, and Dokploy configuration external to the repo — but none of these has a planning home or a specifiable path to resolution. Individually, each is a small-to-medium task. Collectively, they represent a real delivery confidence and maintainability gap: regressions are caught manually, schema drift between test and runtime is a known risk, deploys are manual, there is no static analysis baseline, and developer onboarding has unnecessary friction. As surface area and contributor count grow, this gap becomes more expensive and more dangerous.
- **Why it matters**: Delivery infrastructure is the foundation that makes product-level correctness sustainable. Without CI, regressions that product architecture hardening work has eliminated can silently return. Without static analysis, type-safety gains from PHP 8.4 and strict Filament/Livewire patterns are unenforced. Test/runtime environment parity gaps mean that passing tests do not prove production correctness — a particularly dangerous problem for a product that governs enterprise tenant configurations. No formal release process means deploy confidence depends on human discipline, which degrades as velocity increases. These are not individually urgent, but they are collectively a prerequisite for scaling the product safely. A platform that governs enterprise Intune tenants should have its own delivery governance in order.
- **Proposed direction**:
  - **CI pipeline**: establish a CI configuration (compatible with Gitea runners or external CI) that runs the test suite, Pint formatting checks, and (once added) static analysis on every push/PR. Start with a minimal pipeline that provides a pass/fail quality gate rather than a complex multi-stage build system. The goal is "every merge request is automatically validated" — not a full platform engineering initiative.
  - **Static analysis baseline**: introduce PHPStan or Larastan at a pragmatic starting level (e.g. level 5–6), baselined against the current codebase. Focus on catching type errors, undefined method calls, and incorrect return types. Do not aim for level-max compliance as a first step — establish the tool, baseline the noise, and raise the level incrementally.
  - **Test/runtime environment parity**: resolve the SQLite-for-tests vs. PostgreSQL-in-production gap. The existing `phpunit.pgsql.xml` suggests this work is partially started. The goal is that the default test suite runs against the same database engine used in production, so that schema-level and query-level differences do not create silent correctness gaps. This is particularly important for JSONB-dependent domains (policy snapshots, backup payloads, operation context).
  - **Developer onboarding hygiene**: add `.env.example` with documented defaults. Small but persistent friction item that affects new contributor experience and reduces setup-related support burden.
  - **Release process formalization**: define a lightweight, documented release process covering version tagging, migration verification, asset compilation (`filament:assets`, `npm run build`), and staging-to-production promotion checks. Not a full release engineering overhaul — a minimal repeatable process that replaces purely manual deploys with a documented, verifiable workflow.
  - **Deployment configuration traceability**: evaluate bringing essential Dokploy/deploy configuration into the repo (or at minimum documenting the external configuration surface) so that environment drift between staging and production is detectable rather than discovered after deployment.
- **Explicit non-goals**: Not a full platform engineering or DevOps transformation initiative. Not a rewrite of deployment architecture or infrastructure provisioning. Not a generic "clean up the repo" bucket for unrelated code quality tasks. Not a replacement for product-level architecture hardening work (queued execution reauthorization, Livewire context locking, etc. are distinct product-safety concerns). Not a mandate to achieve maximum static analysis strictness immediately. Not a CI/CD feature-flag or canary-deployment system. Not an internal developer tooling platform with custom CLIs, dashboards, or abstraction layers. The scope is bounded to the six concrete items identified in the roadmap's Infrastructure & Platform Debt table, plus the minimal CI/release process that connects them into an actionable delivery improvement.
- **Boundary with product architecture hardening (Queued Execution Reauthorization, Livewire Context Locking, etc.)**: Product hardening candidates address trust, authorization, and isolation correctness in the running application. Infrastructure debt addresses delivery confidence — the tooling and process that ensures correctness is verified continuously and shipped reliably. These are complementary layers: product hardening fixes what the code does; infrastructure maturity ensures the fixes stay fixed.
- **Boundary with Operations Naming Harmonization**: Operations naming is about operator-facing terminology consistency across product surfaces. Infrastructure debt is about developer-facing delivery tooling and process. Different audiences, different concerns.
- **Boundary with Admin Visual Language Canon**: The visual language canon mentions lightweight CI enforcement as a possible delivery mechanism for visual convention compliance. If this infrastructure candidate delivers CI, the visual canon can use it — but the CI pipeline itself is infrastructure scope, not visual-canon scope.
- **Dependencies**: None — this is foundational work that other candidates can build on. CI pipeline benefits every future spec by providing automated regression coverage. Static analysis benefits every future hardening spec by enforcing type-safety contractually.
- **Priority**: medium (high cumulative value for delivery confidence and maintainability, but individual items are execution-level tasks rather than product-architecture blockers; should be prioritized pragmatically alongside product work rather than treated as urgent or deferred indefinitely)

---

## Covered / Absorbed

> Candidates that were previously qualified but are now substantially covered by existing specs, or were umbrella labels whose children have been promoted individually.

### Governance Architecture Hardening Wave (umbrella — dissolved)
- **Original source**: architecture audit 2026-03-15
- **Status**: Dissolved into individual candidates. The four children are now tracked separately in Qualified: Queued Execution Reauthorization, Tenant-Owned Query Canon, Livewire Context Locking. The fourth child (Findings Workflow Enforcement) is absorbed below.
- **Reference**: [../audits/tenantpilot-architecture-audit-constitution.md](../audits/tenantpilot-architecture-audit-constitution.md), [../audits/2026-03-15-audit-spec-candidates.md](../audits/2026-03-15-audit-spec-candidates.md)

### Evidence Completeness Reclassification
- **Original source**: semantic clarity & operator-language audit 2026-03-21
- **Status**: Do not promote as a separate candidate. This follow-up is absorbed into existing Spec 153 (Evidence Domain Foundation), which should carry the semantic split between coverage, freshness, valid-empty states, and operator-facing completeness language.

### Operation Outcome & Notification Language
- **Original source**: semantic clarity & operator-language audit 2026-03-21
- **Status**: Prefer extending existing Spec 055 (Ops-UX Constitution Rollout) rather than creating a standalone semantic candidate, as long as Spec 055 is still the active vehicle for operation outcome presentation, partial-success messaging, blocked-cause guidance, and terminal notification language.

### Tenant Review & Publication Readiness Semantics
- **Original source**: semantic clarity & operator-language audit 2026-03-21
- **Status**: Do not create a standalone candidate. This follow-up is absorbed into existing Spec 155 (Tenant Review Layer), which should own review completeness vocabulary, publication-readiness blocker wording, freshness semantics, and review-layer next-action language.

### Findings Workflow Enforcement and Audit Backstop
- **Original source**: architecture audit 2026-03-15, candidate C
- **Status**: Largely absorbed by Spec 111 (findings workflow v2) which defines transition enforcement, timestamp tracking, reason validation, and audit logging. The remaining architectural enforcement gap (model-level bypass prevention) is a hardening follow-up to Spec 111, not a standalone spec-sized problem. Re-qualify only if enforcement softness surfaces as a concrete regression or audit finding.

### Workspace Chooser v2
- **Original source**: Spec 107 deferred backlog
- **Status**: Workspace chooser v1 is covered by Spec 107 + semantic fix in Spec 121. The v2 polish items (search, sort, favorites, pins, environment badges) remain tracked as an Inbox entry. Not qualified as a standalone spec candidate at current priority.

### Dashboard Polish (Enterprise-grade)
- **Original source**: Product review 2026-03-08
- **Status**: Core tenant dashboard is covered by Spec 058 (drift-first KPIs, needs attention, recent lists). Workspace-level landing is in progress via Spec 129. The remaining polish items (sparklines, compliance gauge, progressive disclosure) are tracked in Inbox. This was demoted because the candidate lacked a bounded spec scope — it read as a wish list rather than a specifiable problem.

### Scope & Navigation Semantics (UI/UX Audit)
- **Original source**: UI/UX audit — scope and navigation semantics analysis
- **Status**: Comprehensively covered by existing spec constellation. Spec 077 (implemented) established workspace-first navigation, monitoring hub IA, header context bar, and tenant-context default filters. Spec 103 (draft) addresses IA scope-vs-filter-vs-targeting semantics on monitoring pages. Spec 121 (draft) fixes workspace switch routing semantics. Spec 106 (draft) corrects sidebar navigation context visibility. Spec 107 (draft) covers workspace chooser v1. Spec 129 (draft) addresses workspace home and admin landing pages. Spec 143 (draft) covers tenant lifecycle, operability, and context semantics. Spec 144 (draft) addresses canonical operation viewer context decoupling. Spec 131 (draft) covers cross-resource navigation and drill-down cohesion. The audit's navigation/scope concerns are distributed across these specs as precisely bounded, spec-level problems — no new umbrella candidate is needed.
- **Reference specs**: 077, 103, 106, 107, 121, 129, 131, 143, 144

### Detail Page Hierarchy & Progressive Disclosure (UI/UX Audit)
- **Original source**: UI/UX audit — detail page hierarchy and progressive disclosure analysis
- **Status**: Directly covered by Spec 133 (View Page Template Standard for Enterprise Detail Screens). Spec 133 defines the shared enterprise detail-page composition standard including summary-first header, main-and-supporting layout, dedicated related-context section, secondary technical detail separation, optional section support, and degraded-state resilience. Spec.md, plan.md, research.md, data-model.md, and tasks.md (all tasks complete) exist for 4 initial target pages (BaselineSnapshot, BackupSet, EntraGroup, OperationRun). If additional pages require alignment beyond the initial 4 targets, that is a Spec 133 follow-up scope extension, not a new candidate.
- **Reference specs**: 133

---

## Planned

> Ready for spec creation. Waiting for slot in active work.

*(empty — move items here when prioritized for next sprint)*

---

## Template

```md
### Title
- **Type**: feature | polish | hardening | bug | research
- **Source**: chat | audit | coding discovery | customer feedback | spec N follow-up
- **Problem**:
- **Why it matters**:
- **Proposed direction**:
- **Dependencies**:
- **Priority**: low | medium | high
```
