# Feature Specification: Shared Detail Micro-UI Contract

**Feature Branch**: `197-shared-detail-contract`  
**Created**: 2026-04-15  
**Status**: Proposed  
**Input**: User description: "Spec 197 — Shared Detail Micro-UI Contract"

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

- **Problem**: Wiederverwendete Detail-Micro-UIs für dieselben fachlichen Objekte leben heute als leicht unterschiedliche Host-Varianten, sodass Operatoren dieselbe Surface je nach Host neu lesen und neu erlernen müssen.
- **Today's failure**: Dieselbe fachliche Surface zeigt je nach Host andere Tabs, anders platzierte Next Steps, anders platzierte technische Details oder lokale Zusatzlogik. Dadurch entstehen inkonsistente Operator-Erwartungen, Drift bei Weiterentwicklungen und unnötiger Test- sowie Pflegeaufwand.
- **User-visible improvement**: Operatoren erleben dieselbe Verification-Report- oder Diff-/Settings-Surface hostübergreifend als dieselbe fachliche Surface mit denselben Kernzonen, denselben erwartbaren Interaktionsmustern und klar begrenzten Host-Unterschieden.
- **Smallest enterprise-capable version**: Nur zwei bereits real belegte Shared-Familien werden standardisiert: die Verification-Report-Familie sowie die Normalized Diff / Normalized Settings-Familie. Der Spec führt keinen generischen UI-Baukasten ein und modelliert keine weiteren Custom-Surfaces ohne nachgewiesene Familienwiederholung.
- **Explicit non-goals**: Kein Shell- oder Monitoring-Page-State-Refactor, keine Vereinheitlichung aller Custom-Detailansichten, kein generisches internes Komponenten-Framework, keine Table-/CRUD-/Badge-Konsistenzkampagne außerhalb der belegten Shared-Familien.
- **Permanent complexity imported**: Zwei explizite Shared-Family-Verträge, dokumentierte Pflicht-/Optional-/Host-Zonen, begrenzte Host-Variationsregeln, family-orientierte Regressionsabdeckung, eine kleine Abschlussdokumentation zu migrierten Hosts und erlaubten Restvarianten.
- **Why now**: Beide Familien sind bereits in mehreren Hosts sichtbar und zeigen belegte Drift. Jeder weitere Host erhöht die Wahrscheinlichkeit, dass dieselbe Surface erneut als lokale Mini-App eingebaut wird.
- **Why not local**: Lokale Bereinigungen pro Host beseitigen die Wiederholung nicht. Das Problem liegt in fehlendem gemeinsamen Vertrag für dieselbe Surface-Familie, nicht in einem einzelnen Host.
- **Approval class**: Cleanup
- **Red flags triggered**: Eine rote Flagge: Shared-Cross-Surface-Contract kann in ein zu breites UI-Framework kippen, wenn der Scope über die zwei belegten Familien hinaus wächst.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - Monitoring- beziehungsweise Operations-Detailflächen, die Verification Reports als eingebettete Detail-Surface zeigen
  - Tenant-onboarding- und tenantbezogene Verifikationsflächen, die denselben Verification Report in Wizard-, Widget- oder Inline-Kontext rendern
  - Tenantbezogene Policy-, Policy-Version- und Finding-Detailflächen, die Normalized Settings oder Normalized Diff als Detail-Surface zeigen
- **Data Ownership**:
  - Tenant-owned: verifikationsbezogene Detaildaten, Policy-, Policy-Version- und Finding-Daten, die innerhalb der Shared-Familien dargestellt werden
  - Workspace-context / canonical-view owned: die hostseitige Einbettung in kanonische Monitoring- oder Operations-Detailflächen
  - Dieser Spec führt keine neue persistierte UI- oder Vertrags-Entität ein; die Shared-Family-Verträge bleiben rein darstellungs- und verhaltensbezogen
- **RBAC**:
  - Bestehende Workspace-Mitgliedschaft und Tenant-Entitlement bleiben die Zugangsvoraussetzung für alle Hosts, die diese Shared-Familien rendern
  - Bestehende View-/Inspect-Berechtigungen der Hosts bleiben maßgeblich; der Spec führt keine neue Capability und keinen neuen Autorisierungsweg ein
  - Host-spezifische Aktionen innerhalb oder neben der Shared-Family bleiben weiter an die bereits vorhandenen Capability-Regeln des Hosts gebunden

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Wenn Tenant-Kontext aktiv ist, rendern Shared-Familien ausschließlich Daten aus dem aktuell aktiven Tenant-Kontext des Hosts. Ein Host darf keine Shared-Family tenantübergreifend oder tenantlos auf tenant-owned Daten erweitern.
- **Explicit entitlement checks preventing cross-tenant leakage**: Jeder Host bleibt dafür verantwortlich, nur bereits autorisierte Records oder Reports an die Shared-Family zu übergeben. Tenantlose kanonische Hosts dürfen tenant-owned Inhalte nur nach bestehender Entitlement-Prüfung sichtbar machen; Nicht-Mitglieder bleiben deny-as-not-found.

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

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Verification Report family | Secondary Context Surface | Operator prüft, warum ein Verify- oder Onboarding-Schritt bereit, blockiert oder nacharbeitspflichtig ist | Ergebnisstatus, Blocker oder Warnungen, zentrale Next Steps, klarer Host-Kontext | Technische Details, Run-Identität, tiefere Diagnose, Host-spezifische Assist-Einstiege | Nicht primär, weil die eigentliche Entscheidung im Host-Workflow liegt; diese Surface liefert die entscheidungsrelevante Begründung | Unterstützt Verify-, Onboarding- und Tenant-Follow-up-Workflows, ohne selbst eine separate Prozessfläche zu werden | Gleiche Grundstruktur in mehreren Hosts reduziert erneutes Uminterpretieren derselben Report-Aussage |
| Normalized Diff / Settings family | Tertiary Evidence / Diagnostics Surface | Operator prüft, was sich fachlich geändert hat oder welche Settings inhaltlich gelten | Klar gegliederte Abschnitte, aktiver View-Modus, wichtigste Diff- oder Settings-Inhalte | Zusätzliche Abschnitte, tiefere technische Darstellung, volle Detailtiefe, optionale Expand-/Fullscreen-Zonen | Nicht primär, weil die Entscheidung meist von einer übergeordneten Policy-, Version- oder Finding-Detailfläche ausgelöst wird | Unterstützt Review-, Diagnose- und Vergleichsarbeit innerhalb bestehender Detail-Workflows | Konsistente View-Zonen und Zustände reduzieren Vergleichsaufwand zwischen Policy-, Version- und Finding-Hosts |

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

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Verification Report family | Detail / Embedded Review | Shared detail micro-UI | Read blockers, follow next step, open related operation or assist path | Host-owned embedded detail surface | forbidden | Innerhalb der gemeinsamen Action-/Assist-Zone oder hostseitig unmittelbar angrenzend, klar getrennt von Kernstatus und Diagnose | Keine destruktiven Aktionen im Shared Core; hostseitige Mutationen bleiben außerhalb des Core-Vertrags und confirmation-gated | Host-owned verification entry surfaces | Host-owned verification detail contexts in operations, onboarding, or tenant review flows | Aktiver Tenant- oder Workspace-Kontext des Hosts, Report-Status, Ergebnis-/Readiness-Signale | Verification report | Readiness, blockers or warnings, and next action intent | Embedded shared family; kein eigenständiges list-first oder standalone resource detail |
| Normalized Diff / Settings family | Detail / Evidence | Shared detail micro-UI | Inspect sections, switch view mode, expand detail, compare meaningfully | Host-owned embedded detail surface | forbidden | Innerhalb der gemeinsamen View-/Action-Zone der Surface; hostseitige Navigation bleibt außerhalb der Kern-Interaktion | Keine destruktiven Aktionen innerhalb der Shared-Family | Host-owned policy, policy version, or finding detail entries | Host-owned policy, version, and finding detail contexts | Aktiver Tenant-Kontext des Hosts, Inhaltstyp, verfügbarer Detailmodus, Empty/Unavailable-Signale | Normalized settings / Normalized diff | Die aktuell relevante fachliche Detailaussage des Settings- oder Diff-Inhalts | Embedded evidence family; kein eigenständiges CRUD- oder queue-first surface |

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

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Verification Report family | Tenant operator, workspace operator, onboarding operator | Verstehen, ob ein Verify- oder Onboarding-Schritt bereit ist, was blockiert, und was als Nächstes zu tun ist | Embedded report detail | Why is this verification ready, blocked, or cautionary, and what should I do next? | Summary oder header zone, outcome or readiness status, issues or passes overview, next-step or assist entry points | Technical details, operation identity, deeper diagnostics, host-specific helper content | readiness, outcome, severity of issues, data completeness | Shared core is read-only; host-owned acknowledge or assist mutations remain explicitly bounded | Review issues, switch view zone, follow next step, open technical detail or related run | None in shared core |
| Normalized Diff / Settings family | Tenant operator, reviewer, diagnostician | Verstehen, welche Inhalte gelten oder was sich fachlich geändert hat | Embedded evidence detail | What changed or what settings are in force, and where should I inspect next? | Shared section structure, active view or tab, visible content blocks, empty or unavailable explanation | Secondary sections, deeper technical content, larger expansions, raw or diagnostic follow-up hosted elsewhere | content availability, comparison completeness, section context | Read-only | Switch view or tab, expand relevant detail, inspect targeted sections | None |

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

- **New source of truth?**: No
- **New persisted entity/table/artifact?**: No
- **New abstraction?**: Yes
- **New enum/state/reason family?**: No
- **New cross-domain UI framework/taxonomy?**: No
- **Current operator problem**: Dieselbe fachliche Detail-Surface wirkt in verschiedenen Hosts wie verschiedene kleine Anwendungen. Das erschwert sichere Wiedererkennung, verlangsamt Folgeschritte und erhöht die Wahrscheinlichkeit, dass Weiterentwicklungen inkonsistent erfolgen.
- **Existing structure is insufficient because**: Reines Fragment-Sharing auf View-Ebene verhindert keine Drift bei Tabs, Assist-Zonen, Diagnostics-Zonen, lokalen Zuständen oder Action-Platzierung. Ohne expliziten Familienvertrag bleibt jeder Host faktisch Mitbesitzer der Surface-Logik.
- **Narrowest correct implementation**: Definiere nur für die zwei bereits belegten Shared-Familien einen gemeinsamen Detailvertrag mit expliziten Pflicht-, Optional- und Host-Variationszonen; keine generische Plattform, kein globales UI-System, keine neue Persistenz.
- **Ownership cost**: Dauerhaft entstehen begrenzte zusätzliche Vertragsdokumentation, cross-host Regressionstests und ein klarer Review-Maßstab für künftige Host-Einbindungen. Im Gegenzug sinken parallele View-Logik, Drift-Risiko und Teststreuung.
- **Alternative intentionally rejected**: Einzelne Hosts lokal aufzuräumen oder weitere Blade-Sharing-Fixes einzubauen wurde verworfen, weil das die gemeinsame Kernlogik nicht schützt. Ein generisches internes UI-Framework wurde ebenfalls verworfen, weil nur zwei reale Familien standardisiert werden müssen.
- **Release truth**: Current-release truth

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Recognize the same verification surface everywhere (Priority: P1)

As an operator, I want verification results to use the same recognizable structure in operation detail, onboarding, and tenant verification hosts, so that I can immediately see the same core meaning, next steps, and diagnostics without relearning the surface.

**Why this priority**: The most visible current drift is inside the Verification Report family, where the same report meaning is rendered with host-specific structure and local state.

**Independent Test**: Can be fully tested by rendering each covered verification host with equivalent verification data and confirming that the same core zones, same status meaning, and same next-step intent are visible in each host while allowed host variations remain bounded.

**Acceptance Scenarios**:

1. **Given** the same verification outcome is rendered in an operations detail host and an onboarding host, **When** the operator opens each host, **Then** the same core summary, issue/pass structure, and diagnostics contract are recognizable.
2. **Given** a verification host offers host-specific assist or acknowledge behavior, **When** the operator uses that host, **Then** the host-specific behavior appears as an explicit variation of the same shared verification contract rather than as a different report UI.
3. **Given** a verification report has no technical detail payload available, **When** it is rendered in any covered host, **Then** the absence is communicated through the same contractually defined unavailable or optional zone behavior rather than host-specific omission rules.

---

### User Story 2 - Inspect normalized settings and diffs consistently (Priority: P1)

As an operator reviewing policy, version, or finding detail, I want normalized settings and normalized diff surfaces to behave like one family, so that tabs, view modes, sections, and unavailable states do not feel reinvented per host.

**Why this priority**: The diff/settings family already appears across multiple detail hosts and contains subtle host-specific drift around visibility, context handling, and section behavior.

**Independent Test**: Can be fully tested by rendering representative policy, policy-version, and finding hosts and verifying that the same family-level structure, same core view behavior, and same empty or unavailable semantics apply wherever the same content concept is shown.

**Acceptance Scenarios**:

1. **Given** a normalized diff is available in more than one covered host, **When** the operator opens each host, **Then** the same family-level view structure and section logic are recognizable.
2. **Given** a normalized settings surface renders different content subtypes, **When** those subtypes are shown in covered hosts, **Then** subtype differences remain explicit and do not appear as ad hoc host forks.
3. **Given** a host cannot show a diff or settings payload, **When** the operator reaches that area, **Then** the surface shows a family-consistent unavailable or partial state rather than a host-specific gap.

---

### User Story 3 - Add or update a host without re-forking the family (Priority: P2)

As a developer or reviewer, I want a clear shared-family contract for repeated detail surfaces, so that a new host or host change can extend the family through known variation points instead of quietly re-forking the whole micro-UI.

**Why this priority**: The product gain only lasts if later host work cannot easily recreate drift.

**Independent Test**: Can be fully tested by reviewing a changed or newly added host against the family contract and verifying that only allowed host-driven inputs, zones, and actions differ.

**Acceptance Scenarios**:

1. **Given** a developer introduces a new host for an existing shared family, **When** the host is reviewed and tested, **Then** the host declares or uses only the family's allowed variation points.
2. **Given** an existing host needs a unique action or assist entry, **When** that difference is added, **Then** the difference remains visibly host-scoped and does not redefine the family core structure.
3. **Given** a future host tries to introduce a different tab or view contract for the same family without domain justification, **When** the change is reviewed, **Then** it is rejected as out of contract.

### Edge Cases

- A covered host lacks one optional zone, such as technical details, but still must preserve the same family-level structure and optional-state behavior.
- A host needs an assist or acknowledge action that no other host needs; the action must remain an explicit host variation and not become a hidden structural fork.
- The same family appears in both tenant-context and workspace-context hosts; tenant scope must stay explicit and inaccessible data must remain not found.
- A diff or settings payload is partially available, unavailable, or subtype-specific; the surface must communicate this consistently without silently dropping the zone.
- A family contains local state, such as view selection or expansion state; that state must be owned once at the family level rather than recreated differently in each host.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph calls, no new long-running or queued work, and no new write workflow. It standardizes repeated operator-facing detail surfaces that already exist and must remain derived from the host's current domain truth.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature introduces one narrow kind of abstraction: an explicit shared detail-family contract for two already proven families. It does not introduce new persistence, new state families, or a cross-domain UI framework. The purpose is to replace duplicate cross-host ownership, not to layer a new semantic system on top of existing truth.

**Constitution alignment (OPS-UX):** No new `OperationRun` type or execution path is introduced. Existing links to operations remain navigation only and continue to rely on the current operations contract.

**Constitution alignment (RBAC-UX):** The feature does not change authorization behavior. Existing workspace and tenant entitlement rules continue to govern every host. Non-members remain deny-as-not-found, members without capability remain forbidden where host-owned actions already enforce capability, and no shared family may bypass host authorization.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable.

**Constitution alignment (BADGE-001):** Existing centralized status, severity, readiness, and availability semantics remain the source of truth. This feature must not create host-local badge or tone vocabularies for the same shared family.

**Constitution alignment (UI-FIL-001):** Existing native detail containers, shared status primitives, and current custom viewer bodies remain the basis. The work must consolidate contract ownership and avoid new host-local replacement markup for status, assist, or action zones. Exception: the core bodies of the two shared families remain domain-specific rich viewers rather than being flattened into generic primitives.

**Constitution alignment (UI-NAMING-001):** Shared family vocabulary must stay stable across hosts. Operators should continue to see the same canonical nouns, such as verification report, technical details, next steps, normalized settings, and diff, instead of host-specific synonyms for the same concept.

**Constitution alignment (DECIDE-001):** Verification Report surfaces remain secondary context surfaces, and Normalized Diff / Settings surfaces remain tertiary evidence surfaces. Each host must still make the first decision possible without forcing the operator to decode different family structures for the same concept.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** The feature standardizes embedded detail and evidence surfaces. Each family keeps exactly one primary inspect model per host: the host opens the record, and the family provides the repeated inner surface. Pure navigation remains host-owned or within the family's secondary action zone. Destructive behavior is outside the shared core and remains governed by host rules.

**Constitution alignment (ACTSURF-001 - action hierarchy):** Shared-family actions are limited to navigation, inspection, view switching, assist entry, and other low-risk context actions. Any mutating or destructive host action remains clearly separated from the shared-family core and may not compete with the family's primary evidence or review function.

**Constitution alignment (OPSURF-001):** Default-visible content stays operator-first. Shared-family surfaces must show the core meaning, next step, or relevant content first, while deeper diagnostics remain secondary and intentionally revealed. Host context remains visible so operators understand scope.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** Direct host-by-host mapping is currently insufficient because it has already produced duplicate ownership and drift. This feature must replace that duplicate ownership with one shared contract per family rather than adding extra presenter layers. Regression tests must assert the business-visible consequences of sameness across hosts.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied. These are embedded read-heavy detail families, not new standalone CRUD resources. Each host continues to own its one primary inspect/open model, no redundant View action is introduced by the family work, and destructive actions stay outside the shared core. UI-FIL-001 is satisfied with the documented exception that family-specific detail viewers remain custom where the domain requires it.

**Constitution alignment (UX-001 — Layout & Information Architecture):** The feature does not add create or edit screens. Existing detail hosts must continue to use appropriate detail layouts, clear sectioning, explicit empty or unavailable states, and operator-first information ordering. Where a host already uses a view-style detail surface, the shared family must strengthen rather than weaken that clarity.

### Functional Requirements

- **FR-197-001**: The system MUST define a shared detail contract for the Verification Report family that covers every currently in-scope host where the same verification surface appears.
- **FR-197-002**: The Verification Report contract MUST identify which zones are mandatory, optional, host-extendable, and host-governed, including summary or header, outcome or readiness, view or tab zone, next-step or assist zone, technical-details or diagnostics zone, and empty or unavailable state handling.
- **FR-197-003**: Covered Verification Report hosts MUST use the same family-level core structure and MUST NOT redefine the family through incompatible local tab, view, or zone contracts.
- **FR-197-004**: Host-specific Verification Report differences MAY vary action availability, host placement, or assist entry behavior, but MUST NOT change the family's core structure, diagnostics contract, or next-step contract without explicit domain justification.
- **FR-197-005**: The Verification Report family MUST remain at least functionally equivalent to the pre-standardized state, preserving current information value, current operator usefulness, and current diagnosis depth.
- **FR-197-006**: The system MUST define a shared detail contract for the Normalized Diff / Normalized Settings family across every currently in-scope host that presents the same content concept.
- **FR-197-007**: The Normalized Diff / Settings contract MUST standardize family-level view zones, section behavior, empty or unavailable states, partial states, and any supported expand or fullscreen semantics where those behaviors are part of the family.
- **FR-197-008**: If the Normalized Diff / Settings family contains meaningful subtypes, those subtypes MUST be explicit variations of the same family contract and MUST NOT exist only as accidental host forks.
- **FR-197-009**: Covered hosts for the Normalized Diff / Settings family MAY vary host framing or surrounding context, but MUST preserve recognizable family-level interaction patterns for view switching, section reading, and detail inspection.
- **FR-197-010**: For each in-scope shared family, the required inputs, supported states, and render expectations MUST be explicit enough that a host does not need hidden local assumptions to render the family correctly.
- **FR-197-011**: If a shared family requires local UI state, that state MUST be owned once at the family level and MUST NOT be recreated differently in each host.
- **FR-197-012**: New or updated hosts using an in-scope shared family MUST extend the family only through the contract's documented variation points and MUST NOT introduce new ad hoc Blade-level main variants for the same surface.
- **FR-197-013**: Domain-specific viewers that are similar in shape but intentionally separate from the two in-scope families MAY remain outside this spec, but they MUST stay explicitly out of scope rather than becoming accidental exceptions inside the standardized families.
- **FR-197-014**: Regression coverage MUST prove that multiple hosts for each in-scope shared family use the same family-level contract and that any remaining differences are explicit, bounded host variations.
- **FR-197-015**: Release acceptance for this spec MUST include a closing inventory of migrated hosts, intentionally allowed remaining variations, and follow-up topics that were found to be shell, monitoring-state, or other out-of-scope concerns.

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

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Verification Report family | Embedded inside operations detail, onboarding verification, and tenant verification hosts | Host-owned header actions; shared family may expose low-risk report actions such as open related operation, open technical details, or follow next step | Host-owned detail inspection; not a list/table surface | None at family level; any host-specific per-item action stays explicitly host-scoped | None | Family-consistent empty, unavailable, or assist CTA where relevant | N/A | N/A | No new audit path introduced | Action Surface Contract satisfied. Shared core is read-heavy; host-owned acknowledge or assist mutations remain outside the core contract and retain existing authorization and confirmation rules. |
| Normalized Diff / Settings family | Embedded inside policy, policy version, and finding detail hosts | Host-owned detail header actions only | Host-owned detail inspection; not a list/table surface | None | None | Family-consistent unavailable or partial-state explanation; CTA only if the host already owns a follow-up path | N/A | N/A | No | Action Surface Contract satisfied. Read-only evidence family; no new mutation or destructive affordance is introduced. |

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

- **Shared detail family**: A repeated domain detail surface that appears in more than one host and should read as the same surface wherever it appears.
- **Family contract**: The explicit definition of a shared family's inputs, supported states, mandatory zones, optional zones, and allowed host variations.
- **Host variation**: A deliberately bounded host-specific difference, such as action availability, placement, or assist entry, that does not redefine the family core.
- **Verification report detail**: The domain report surface that communicates verification readiness, blockers, passes, next steps, and deeper diagnostics.
- **Normalized detail surface**: The domain evidence surface that communicates structured settings content or structured diff content through one recognizable family.

## Deliverables

- **D-197-001**: A standardized Verification Report shared-family contract covering the currently in-scope hosts.
- **D-197-002**: A standardized Normalized Diff / Normalized Settings shared-family contract covering the currently in-scope hosts.
- **D-197-003**: Documented variation rules per family that state what is shared core, what hosts may extend, and what hosts must not re-invent.
- **D-197-004**: A closing migration note listing migrated hosts, consciously allowed remaining differences, and related topics that were intentionally left out of scope.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-197-001**: In regression coverage, every currently in-scope host for the Verification Report family passes the shared-family contract assertions with zero unexplained core-structure differences.
- **SC-197-002**: In regression coverage, every currently in-scope host for the Normalized Diff / Settings family passes the shared-family contract assertions with zero unexplained view-structure differences.
- **SC-197-003**: In operator smoke review, a reviewer can identify summary, next-step or assist placement, and diagnostics placement within 10 seconds on each covered Verification Report host.
- **SC-197-004**: In operator smoke review, covered diff/settings hosts are recognized as the same family for view modes, section behavior, and unavailable-state behavior in 100% of reviewed scenarios.
- **SC-197-005**: The release contains no remaining unbounded host-only main variant for either in-scope shared family.

## Assumptions

- The current repository already contains the two in-scope shared families in enough hosts to justify a family-level contract now.
- Existing host authorization, route structure, and domain truth remain correct; this spec changes shared UI contract ownership, not host entitlement logic.
- Rich domain-specific detail rendering remains necessary; only the family contract is being standardized, not the domain detail richness itself.

## Non-Goals

- Standardizing every custom detail surface in the repository
- Refactoring the global shell, workspace context bar, or monitoring page-state behavior
- Reworking Evidence Overview, baseline compare matrix, or generic table surfaces
- Eliminating every custom view body in favor of a generic component system
- Pulling unrelated domain-specific diff viewers into scope without proving that they are the same shared family

## Dependencies

- Existing operations detail hosts, tenant verification hosts, and onboarding verification hosts that already render Verification Report content
- Existing policy, policy version, and finding detail hosts that already render Normalized Settings or Normalized Diff content
- Existing host-level authorization, detail routing, and status semantics that the shared-family contracts must preserve rather than replace

## Definition of Done

Spec 197 is complete when:

- both confirmed in-scope shared families use explicit family contracts,
- the main hosts for each family no longer behave like loosely drifted mini-app variants of the same surface,
- remaining host differences are explicitly documented as bounded variations,
- regression and smoke verification prove operator sameness and preserved usefulness,
- and no shell-, monitoring-state-, or other out-of-scope topic has been silently absorbed into this work.