TenantAtlas/specs/370-global-surface-information-architecture-contract/spec.md

Feature Specification: Spec 370 - Global Surface Information Architecture Contract v1

Feature Branch: feat/370-global-surface-information-architecture-contract Created: 2026-06-10 Status: Draft Input: User-provided Spec 370 draft, Spec 368 Platform-wide UI Signal-to-Noise Browser Audit, and Spec 368 Candidate A.

Candidate Selection Summary

• Selected candidate: Global Surface Information Architecture Contract v1.
• Source: User-provided Spec 370 draft and specs/368-platform-ui-signal-to-noise-browser-audit/spec-candidates.md Candidate A.
• Why selected: Spec 368 found recurring signal-to-noise issues across operations, backup, baseline, provider, diagnostic, and customer/auditor surfaces. The same pattern appears repeatedly: pages expose available data before the current decision, reason, impact, next action, and evidence basis. A docs-only contract is the smallest low-runtime-risk way to align later UI productization specs before more page-local refactors diverge.
• Roadmap relationship: Supports the roadmap's UI and product maturity polish lane, especially the decision-centered operating model and surface/IA classification direction in docs/product/roadmap.md.
• Smallest viable slice: Create a repo-anchored, docs-only contract under this spec package. It defines surface types, audience disclosure rules, header/main/sidebar/technical-details hierarchy, zero-metric suppression, verification classes, page assessment checklist, UI bloat patterns, and follow-up mapping. It does not change runtime UI.
• Canonical standards relationship: Spec 370 is a spec-local IA review artifact, not a replacement for .specify/memory/constitution.md, docs/product/standards/, docs/ui/operator-ux-surface-standards.md, docs/ui/tenantpilot-enterprise-ui-standards.md, docs/ui/action-surface-contract.md, or the runtime ActionSurfaceType enum.
• Deferred close alternatives:
  • Core Operator View Surfaces Productization Pass: page-level runtime refactors remain follow-up specs.
  • Customer/Auditor Surface Safety Pass: valuable, but should consume the global contract instead of defining a competing one.
  • Diagnostic Surface Separation: valuable, but should consume the global contract and handle fixture/auth gaps separately.
  • UI Bloat Regression Guard: deferred until the docs contract proves stable enough to automate safely.
  • Target mock/example per archetype from Spec 368 Candidate A: deferred; this slice uses existing Spec 368 before-state evidence and does not create target imagery or mockups.
  • Spec 369 Baseline Profile Decision View: already prepared and implemented/validated; not a prep target.
• Completed-spec guardrail: No specs/370-* package existed before this run. Spec 368 is an audit/source artifact and is not modified. Spec 369 is completed/validated context and is not modified. Existing UI, action-surface, scope, and OperationRun specs are treated as historical context only.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Operators, customer reviewers, auditors, and support users see inconsistent first-viewport hierarchy across TenantPilot surfaces. Several pages make users parse metadata, lifecycle fields, raw identifiers, repeated zero metrics, or technical diagnostics before understanding the decision.
• Today's failure: New UI productization specs can solve the same problem differently page by page, creating parallel status language, inconsistent diagnostics disclosure, and duplicated decision summaries. A page may appear busy even when no action is needed, or technical truth may compete with the current operator decision.
• User-visible improvement: Future surface work starts from one documented decision-first hierarchy: status, reason, impact, primary next action, affected objects, evidence availability, then diagnostics and technical metadata on demand.
• Smallest enterprise-capable version: A docs-only contract and assessment checklist scoped to existing audit evidence. No runtime UI refactor, no new component library, no automated guard, no migration, and no broad design-system rebuild.
• Explicit non-goals: No Filament page refactors, no new navigation, no CSS/theme work, no new Livewire components, no new persisted entities, no new policies/RBAC, no OperationRun behavior changes, no browser fixture fixes, and no broad static guard implementation.
• Permanent complexity imported: One spec-local contract artifact set and a small vocabulary for verification class, surface type, audience type, and disclosure hierarchy. These are review rules, not runtime classes.
• Why now: Spec 368 produced browser-verified cross-surface evidence, and Spec 369 intentionally deferred the global rule pack because a page-local fix was safer first. After the first page-local productization slice, the next small foundation is the shared contract that future slices can consume.
• Why not local: The problem is repeated across multiple domains. Continuing page-local fixes without a shared contract risks five slightly different interpretations of decision-first UI and metadata disclosure.
• Approval class: Workflow Compression.
• Red flags triggered: New taxonomy/rule language and "foundation" risk. Defense: this spec is docs-only, uses existing audit evidence, does not create code abstractions, and explicitly defers automation until a separate approval.
• 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: workspace/platform documentation and governance artifact.
• Primary Routes: N/A. No reachable route, page, panel, action, modal, drawer, wizard, table, or form changes in this spec.
• Data Ownership: No application data ownership changes. Spec-local artifacts are provisional documentation truth for future UI review only, subordinate to the canonical standards listed above until a later docs/product publication decision is approved.
• RBAC: No runtime authorization changes. The contract must still require future specs to preserve workspace/tenant isolation, capability checks, and deny-as-not-found semantics where UI changes expose scoped data.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

N/A - no reachable UI surface impact.

• No-impact rationale: This spec creates documentation and review artifacts only under specs/370-global-surface-information-architecture-contract/. It does not edit runtime files, routes, navigation, Filament providers, resources, pages, views, CSS, JavaScript, tests, or screenshot coverage artifacts.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes, documentation-only.
• Interaction class(es): status messaging, header information hierarchy, dashboard signals, evidence/report viewers, diagnostics disclosure, zero-state metrics, operator next-action copy.
• Systems touched: Spec-local artifacts only. Existing systems such as BadgeCatalog, BadgeRenderer, OperationUxPresenter, OperationRunLinks, ActionSurfaceDeclaration, and UI audit registries are referenced as context for future specs but not changed.
• Existing pattern(s) to extend: Spec 368 recommendations, Spec 336 baseline compare decision-first pattern, Spec 344 customer review disclosure pattern, Spec 369 page-local decision summary pattern, and UI-COV-001 artifact discipline.
• Shared contract / presenter / builder / renderer to reuse: N/A for this docs-only prep. Future runtime specs must reuse existing shared paths before inventing local UI semantics.
• Why the existing shared path is sufficient or insufficient: Existing code paths already cover many page-local semantics. The missing piece is a reviewable documentation contract that says where decision, evidence, diagnostics, and metadata belong by surface type.
• Allowed deviation and why: No runtime deviation. The contract may document Spec 370 IA review classes as review language only; these classes are not runtime ActionSurfaceType values and must not override canonical UI standards.
• Consistency impact: Future specs should use one hierarchy for status/reason/impact/next-action and one rule set for technical metadata demotion.
• Review focus: Confirm the contract remains a guardrail and does not become a mandated runtime framework.

OperationRun UX Impact

N/A - no OperationRun start or link semantics touched.

This spec does not create, queue, deduplicate, resume, block, complete, or deep-link to an OperationRun. It only states that future OperationRun-facing surfaces must separate execution outcome, data completeness, governance result, lifecycle/readiness, evidence, diagnostics, and technical metadata.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: documentation only.
• Boundary classification: platform-core review language with provider-owned examples.
• Seams affected: Future vocabulary guidance for provider connections, diagnostics, evidence, and technical details.
• Neutral platform terms preserved or introduced: workspace, managed environment, provider connection, governed subject, operation, evidence, diagnostics, customer-safe, support/raw.
• Provider-specific semantics retained and why: Microsoft/Intune examples may remain in source evidence because TenantPilot's current implementation is Microsoft-first, but the contract must not make Microsoft terms the default platform-core vocabulary.
• Why this does not deepen provider coupling accidentally: The contract explicitly treats provider payloads, provider IDs, portal terms, raw API fields, and permission internals as technical/support detail unless the surface is intentionally diagnostic.
• Follow-up path: Future provider-specific exceptions must be document-in-feature or follow-up-spec.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Spec-local IA contract artifacts	no	N/A	status messaging, evidence/report viewers, diagnostics disclosure as documentation	none	no	Docs-only preparation package
Future UI specs consuming the contract	future only	native/shared first	all relevant shared families	future surface-specific	future exceptions only	Out of scope for this spec

Decision-First Surface Role

N/A - no operator-facing surface is changed.

The contract defines future review vocabulary for Primary Decision, Secondary Context, and Tertiary Evidence/Diagnostics surfaces, but does not reclassify or edit any live page.

Audience-Aware Disclosure

N/A - no live detail or status surface is changed.

The contract artifact must define disclosure expectations for operator, customer, auditor, platform admin, support, developer, mixed, and unknown audiences.

UI/UX Surface Classification

N/A - no reachable operator-facing list, detail, queue, audit, config, or report surface is changed.

The contract artifact must include the surface type matrix for future classification work.

Operator Surface Contract

N/A - no new or materially refactored operator-facing page is introduced.

The contract artifact itself defines the minimum fields future operator-surface contracts must answer.

Proportionality Review

• New source of truth?: yes, but only provisional spec-local documentation truth for future UI review expectations. Canonical standards remain authoritative unless a later approved docs/product publication reconciles this package into them.
• New persisted entity/table/artifact?: yes, Markdown artifacts under the spec package; no database or runtime persistence.
• New abstraction?: no runtime abstraction, interface, service, resolver, presenter, or registry.
• New enum/state/reason family?: no runtime enum/state/reason family.
• New cross-domain UI framework/taxonomy?: a documentation taxonomy for surface/audience/scope review language, not a runtime framework and not the runtime ActionSurfaceType taxonomy.
• Current operator problem: Operators and customer/auditor users lose time and trust when page-local UI shows technical metadata, zero metrics, and repeated statuses before the current decision and evidence basis.
• Existing structure is insufficient because: Spec 368 and Spec 369 prove page-level work can improve one surface, but the same rule decisions recur across backup, operations, baseline, provider, diagnostics, evidence, and customer review. Existing specs do not provide one shared review artifact for later productization slices.
• Narrowest correct implementation: Keep the contract as Markdown under this spec, anchored to audit evidence and examples. Do not add code, CI guards, shared components, target mockups, or docs/product publication unless separately reviewed.
• Ownership cost: Future specs may reference the contract as a review artifact, but must still follow canonical standards and runtime Action Surface rules. Reviewers must prevent it from becoming a mandatory presenter/component framework or competing standards layer.
• Alternative intentionally rejected: Direct runtime refactors across all affected pages, a new UI component library, static guard implementation, or global presenter layer. All are broader than the current need.
• Release truth: current-release productization guardrail.

Compatibility posture

This is a docs-only preparation package. Backward compatibility, migration shims, legacy aliases, data backfills, and fixture migrations are not applicable.

Testing / Lane / Runtime Impact

• Test purpose / classification: N/A for application tests. Artifact review and git diff --check are sufficient for this preparation package.
• Validation lane(s): docs-only/manual review, no Pest lane required.
• Why this classification and these lanes are sufficient: No runtime behavior, database schema, queue, route, Filament resource, Livewire component, policy, or asset changes are planned.
• New or expanded test families: none.
• Fixture / helper cost impact: none.
• Heavy-family visibility / justification: none.
• Special surface test profile: N/A.
• Standard-native relief or required special coverage: N/A. The contract may require future specs to use browser/manual smoke only when they change reachable UI.
• Reviewer handoff: Reviewers should confirm the package is docs-only, the contract remains narrow, the artifact examples are traceable to Spec 368, and follow-up specs are not hidden in the primary scope.
• Budget / baseline / trend impact: none.
• Escalation needed: document-in-feature if a future spec needs to deviate from the contract; follow-up-spec if repeated drift justifies automation.
• Active feature PR close-out entry: N/A - preparation package only.
• Planned validation commands:
  • ./.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
  • git diff --check
  • Manual review of spec.md, plan.md, tasks.md, and artifacts/*.md.
• Runtime impact: none. No env vars, migrations, queues, scheduler, storage, Graph calls, or Filament assets.

User Scenarios & Testing

User Story 1 - Review future UI specs against one IA contract (Priority: P1)

As a product/engineering reviewer, I want future UI productization specs to use one repo-anchored surface information architecture contract, so I can detect bloat, duplicated status, and misplaced metadata before implementation.

Independent Test: Review a future UI spec and confirm it declares surface type, audience, first-viewport decision content, evidence placement, diagnostics placement, metadata placement, and any contract deviation.

Acceptance Scenarios:

1. Given a future spec changes an operator detail page, When reviewers inspect its plan, Then the spec can be checked against the contract's header/main/sidebar/technical-details hierarchy.
2. Given a future spec needs to show technical metadata early, When it is reviewed, Then it must document the surface type and why that exception is justified.
3. Given a future UI spec repeats status/impact/next-action in multiple first-viewport cards, When it is reviewed, Then the contract gives reviewers a concrete basis to request consolidation.

User Story 2 - Preserve customer/auditor safety by default (Priority: P1)

As a customer-facing reviewer or auditor, I want customer/auditor surfaces to default to outcome, evidence, limitation, and next action instead of internal diagnostics, so handoff artifacts are trustworthy and readable.

Independent Test: Use the page assessment checklist to classify a customer/auditor surface and confirm raw IDs, provider payloads, internal reason ownership, debug labels, and operation internals are not default-visible unless explicitly justified.

Acceptance Scenarios:

1. Given a customer review or report surface is changed later, When the checklist is applied, Then customer-safe decision content is first and raw/support detail is collapsed or capability-gated.
2. Given evidence is available, When the surface is assessed, Then evidence readiness, captured-at timing, limitations, and export/handoff action are separated from diagnostics.
3. Given evidence is unavailable or blocked, When the surface is assessed, Then the limitation is stated without pretending the evidence is verified.

User Story 3 - Keep diagnostics useful without overwhelming decision surfaces (Priority: P2)

As an operator or support user, I want diagnostic surfaces to lead with failure, likely cause, next check, and related evidence/operation, while regular decision surfaces keep raw diagnostics on demand.

Independent Test: Apply the surface type matrix to a diagnostic page and a decision page and confirm the diagnostic page is allowed to show technical depth while the decision page demotes raw detail.

Acceptance Scenarios:

1. Given a diagnostic surface is changed later, When reviewers apply the contract, Then the first viewport must explain what failed, why it likely failed, what to check next, and where supporting evidence or operations live.
2. Given a non-diagnostic detail page contains raw IDs or payload lineage, When it is assessed, Then that detail belongs in sidebar or collapsed technical details.
3. Given a page has no current issues, When it renders, Then zero/error/no-attention metrics should not crowd out the current good state unless they are meaningful proof.

Functional Requirements

• FR-001: The spec package MUST define a Global Surface Information Architecture Contract that is explicitly docs-only for this slice.
• FR-002: The contract MUST define the first-viewport decision hierarchy as status, reason, impact, primary next action, affected objects, evidence availability, then diagnostics/technical metadata on demand.
• FR-003: The contract MUST define header, main content, sidebar/aside, technical details, and evidence-area placement rules.
• FR-004: The contract MUST define zero-metric suppression rules for healthy/no-action states.
• FR-005: The contract MUST define at least these surface types: decision_surface, operator_surface, workflow_surface, customer_surface, auditor_surface, evidence_surface, diagnostic_surface, configuration_surface, system_surface, portfolio_surface, support_surface, and unknown.
• FR-006: The contract MUST define at least these audiences: operator, customer, auditor, platform_admin, support, developer, mixed, and unknown.
• FR-007: The contract MUST define at least these scope types: workspace_scoped, environment_scoped, tenant_scoped, customer_scoped, system_scoped, mixed, and unknown.
• FR-008: The contract MUST define verification classes: repo-verified, browser-verified, derived from existing implementation, foundation-real, plausible, not verified, not available, and deferred.
• FR-009: The package MUST include a page assessment checklist that future UI specs can use before implementation.
• FR-010: The package MUST include a UI bloat pattern registry based on Spec 368 findings.
• FR-011: The package MUST include copy and terminology rules that preserve provider-neutral platform language and customer-safe disclosure.
• FR-012: The package MUST include a follow-up spec map that keeps page-specific refactors, diagnostic fixture fixes, and automation guardrails out of this scope.
• FR-013: The package MUST include a source audit summary that identifies which Spec 368 inputs are available, missing, browser-verified, or not available.
• FR-014: The package MUST include a validation report covering branch, HEAD, dirty/untracked files, source artifact availability, and preparation analysis result.
• FR-015: The spec MUST NOT modify runtime application code, tests, migrations, routes, resources, views, policies, jobs, services, config, or assets.
• FR-016: The contract MUST avoid creating a mandatory runtime presenter, badge system, UI framework, component library, or static guard in this slice.

Non-Functional Requirements

• NFR-001: The contract must be concise enough to be applied during spec review without requiring a separate design governance process.
• NFR-002: Every rule must be traceable to Spec 368 evidence, existing repo patterns, or an explicit plausible/deferred label.
• NFR-003: The contract must preserve Filament v5 / Livewire v4 compatibility by referring future runtime work back to native Filament/shared primitives instead of custom UI systems.
• NFR-004: The contract must preserve RBAC and tenant/workspace isolation expectations for future UI specs without changing authorization in this slice.
• NFR-005: The contract must distinguish evidence from diagnostics and must not treat OperationRun internals as customer-safe proof by default.
• NFR-006: The contract must keep provider-specific implementation detail out of platform-core default language unless the surface is explicitly provider-owned or diagnostic.

Out Of Scope

• Runtime UI changes to any page.
• Refactoring Baseline Profile, Backup Set, OperationRun, Restore Run, Operations Hub, Customer Review Workspace, Provider Connections, Diagnostics, Evidence Snapshot, Required Permissions, or System panel pages.
• Browser screenshot updates for individual pages.
• Target mockups or one target example per archetype.
• System/auth fixture repair.
• New Filament components, Blade views, CSS, JavaScript, assets, or design tokens.
• New application tests, browser tests, static guards, CI checks, or lint rules.
• New database tables, migrations, models, services, jobs, policies, routes, config, or OperationRun types.
• Updating completed specs or removing close-out history.
• Publishing the contract to docs/product/ unless a later implementation review explicitly approves that repo-wide documentation location.
• Replacing or renaming existing canonical UI standards, Action Surface classifications, or runtime ActionSurfaceType values.

Acceptance Criteria

• AC-001: spec.md, plan.md, tasks.md, and checklists/requirements.md exist for Spec 370.
• AC-002: The artifact set includes source-audit-summary.md, surface-contract.md, surface-type-matrix.md, ui-bloat-patterns.md, page-assessment-checklist.md, copy-and-terminology-rules.md, follow-up-spec-map.md, and validation-report.md.
• AC-003: The contract explicitly states "Decision first. Diagnostics second. Evidence third. Technical metadata only on demand" and clarifies that evidence availability may appear in the decision layer while full evidence/proof remains distinct from diagnostics.
• AC-004: The contract defines the required surface, audience, scope, verification, and layout/disclosure rules.
• AC-005: The follow-up map excludes page-level runtime refactors and automation guardrails from this spec.
• AC-006: Preparation analysis finds no blocking inconsistency across spec.md, plan.md, and tasks.md, or any finding is fixed only in Spec Kit artifacts.
• AC-007: git diff --check passes for the prepared artifacts.
• AC-008: No application/runtime files are modified.
• AC-009: The package explicitly distinguishes Spec 370 IA review classes from existing product standards and runtime ActionSurfaceType values, and explicitly defers target mock/example artifacts.

Success Criteria

• A future UI productization spec can cite this package and classify a changed page without inventing a new first-viewport hierarchy.
• Reviewers can identify whether a surface is decision, workflow, evidence, diagnostic, customer/auditor, configuration, system, portfolio, support, or unknown.
• Follow-up UI specs remain smaller because they can reuse this contract instead of redefining zero metrics, metadata demotion, evidence placement, and diagnostics disclosure.
• The contract reduces overproduction risk by explicitly deferring code, guards, and broad page refactors.

Risks

• The contract could be interpreted as a runtime framework instead of a documentation guardrail.
• The surface taxonomy could grow beyond current evidence if future contributors add speculative categories.
• Publishing a separate docs/product copy too early could create two sources of truth.
• Future page specs may over-apply the contract to tiny UI changes where no material surface impact exists.

Assumptions

• Spec 368 audit artifacts are the authoritative source evidence for this package.
• Spec 369's page-local Baseline Profile work is completed/validated and should not be reopened by this prep.
• The repo's current Spec Kit scripts provide branch/spec and plan setup; tasks and analysis are artifact-driven rather than shell-command-driven.
• A docs-only spec package is sufficient for the first version of this contract.

Open Questions

• None blocking preparation.
• Non-blocking follow-up: whether a later implementation step should publish a stable copy under docs/product/ or keep the contract spec-local until a second consuming UI productization spec validates it.

Follow-up Spec Candidates

• Backup Set View decision-first productization.
• OperationRun View metadata/proof separation polish.
• Customer/Auditor Surface Safety Pass.
• Diagnostic Surface Separation and browser fixture reachability for Required Permissions/System/Evidence Snapshot.
• UI Bloat Regression Guard v1, only after this contract is validated by at least one additional runtime UI spec.
• Docs/product publication or standards integration for the contract if repeated references prove the spec-local artifact is too hidden.