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

# Implementation Plan: Spec 370 - Global Surface Information Architecture Contract v1

**Branch**: `feat/370-global-surface-information-architecture-contract` | **Date**: 2026-06-10 | **Spec**: `specs/370-global-surface-information-architecture-contract/spec.md`
**Input**: Feature specification from `specs/370-global-surface-information-architecture-contract/spec.md`

## Summary

Prepare a docs-only Global Surface Information Architecture Contract v1 under the Spec 370 package. The work formalizes the Spec 368 audit lessons into reusable review artifacts for future UI productization specs: decision-first hierarchy, surface/audience/scope classification, zero-metric suppression, evidence-vs-diagnostics separation, metadata placement, copy rules, and follow-up mapping. No application implementation is part of this plan.

The contract is subordinate to `.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`, and the runtime `ActionSurfaceType` enum. Spec 370 IA review classes are not runtime Action Surface values and do not publish a new canonical product standard in this slice.

## Technical Context

**Language/Version**: Markdown governance artifacts in a PHP 8.4 / Laravel 12 / Filament v5 / Livewire v4 repository.
**Primary Dependencies**: Spec Kit templates and existing repo documentation. No package or runtime dependency changes.
**Storage**: Markdown files under `specs/370-global-surface-information-architecture-contract/`.
**Testing**: Manual artifact review and `git diff --check`. No Pest or browser test required because there is no runtime behavior change.
**Validation Lanes**: docs-only/manual review.
**Target Platform**: TenantPilot repo workflow.
**Project Type**: Laravel monolith plus Spec Kit docs.
**Performance Goals**: N/A.
**Constraints**: No runtime code, migrations, assets, routes, policies, jobs, services, tests, or UI changes.
**Scale/Scope**: One spec package and spec-local artifacts.

## Candidate Selection Gate

- **Selected candidate exists in source material**: yes, from the user-provided Spec 370 draft and Spec 368 Candidate A.
- **Not already covered by active/completed spec**: yes. Spec 369 intentionally deferred the global contract, and no `specs/370-*` package existed before this run.
- **Completed-spec guardrail**: Spec 368 is an audit/source artifact. Spec 369 is completed/validated and not modified. Existing completed specs are context only.
- **Roadmap fit**: yes, aligned with the roadmap's UI and product maturity polish lane and decision-centered operating model.
- **Smallest viable slice**: docs-only contract and checklist artifacts.
- **Deferred adjacent work**: page runtime refactors, diagnostic fixture work, browser screenshot updates, target mock/examples per archetype, automation/static guards, and docs/product publication.
- **Gate result**: PASS.

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change; docs-only guardrail package.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
- **No-impact class**: docs-only.
- **Native vs custom classification summary**: N/A for runtime. Future specs must prefer native Filament/shared primitives.
- **Shared-family relevance**: status messaging, evidence/report viewers, diagnostics disclosure, dashboard signals, action hierarchy as review guidance only.
- **State layers in scope**: none at runtime.
- **Audience modes in scope**: defined for future review: operator, customer, auditor, platform_admin, support, developer, mixed, unknown.
- **Decision/diagnostic/raw hierarchy plan**: decision-first, diagnostics-second, evidence-third, technical metadata on demand, with explicit evidence/diagnostics separation.
- **Raw/support gating plan**: future customer/auditor surfaces must collapse or capability-gate raw/support detail by default.
- **One-primary-action / duplicate-truth control**: future surfaces should expose one dominant next action and avoid duplicated first-viewport status/reason/impact.
- **Handling modes by drift class or surface**: report-only in this spec; future deviations are `document-in-feature` or `follow-up-spec`.
- **Repository-signal treatment**: report-only for this docs package.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: manual artifact review only.
- **Exception path and spread control**: no runtime exceptions; any future exception must name the surface, audience, rule, reason, and containment path.
- **Active feature PR close-out entry**: N/A.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none for this prep; future UI-changing specs update `docs/ui-ux-enterprise-audit/` as required.
- **No-impact rationale**: only files in `specs/370-global-surface-information-architecture-contract/` are created/updated.
- **Navigation / Filament provider-panel handling**: no provider or navigation changes.
- **Screenshot or page-report need**: no new screenshots. Existing Spec 368 screenshots are source evidence.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, docs-only.
- **Systems touched**: no runtime systems. Context references include Spec 368 audit artifacts, Spec 336 baseline compare, Spec 344 customer review, Spec 369 Baseline Profile decision view, UI-COV-001, and existing shared interaction helpers.
- **Shared abstractions reused**: no runtime abstraction. Future specs should reuse existing `BadgeCatalog`, `BadgeRenderer`, `ActionSurfaceDeclaration`, `OperationUxPresenter`, `OperationRunLinks`, `UiEnforcement`, and `WorkspaceUiEnforcement` where applicable.
- **New abstraction introduced? why?**: no runtime abstraction. The documentation contract is necessary because the repeated issue is cross-surface review consistency, not missing code infrastructure.
- **Why the existing abstraction was sufficient or insufficient**: Existing code helpers are sufficient for runtime semantics; they do not give future specs one product-information hierarchy to review against.
- **Bounded deviation / spread control**: contract remains spec-local until a later approval decides whether to publish it under `docs/product/`. It must not be treated as an `ActionSurfaceType` extension or a replacement for existing standards.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: docs guidance only.
- **Provider-owned seams**: provider payloads, provider IDs, permission internals, portal/API terminology, and Graph-specific diagnostics remain provider-owned/support detail.
- **Platform-core seams**: workspace, managed environment, provider connection, governed subject, operation, evidence, diagnostics, customer-safe, support/raw.
- **Neutral platform terms / contracts preserved**: yes.
- **Retained provider-specific semantics and why**: Microsoft/Intune examples remain as source evidence because they are current implementation reality, but default contract language is provider-neutral.
- **Bounded extraction or follow-up path**: future runtime provider-boundary exceptions are `document-in-feature` or `follow-up-spec`.

## Constitution Check

- Inventory-first: PASS / N/A. No inventory or snapshot truth changes.
- Read/write separation: PASS. No write/change behavior is introduced.
- Graph contract path: PASS / N/A. No Graph calls.
- Deterministic capabilities: PASS / N/A. No capability derivation changes.
- RBAC-UX and isolation: PASS. Future specs are required to preserve RBAC and deny-as-not-found semantics; this spec changes none.
- Run observability and OperationRun: PASS / N/A. No OperationRun behavior.
- Test governance: PASS. Docs-only lane is stated with no runtime test requirement.
- Proportionality: PASS with explicit review because the spec creates documentation vocabulary and artifacts.
- No premature abstraction: PASS. No runtime framework, component, presenter, registry, or guard is introduced.
- Persisted truth: PASS. Spec-local Markdown artifacts only; no database truth.
- Behavioral state: PASS. No runtime state/status/reason code family.
- UI semantics: PASS with risk control. The contract stays as review guidance and avoids mandatory code architecture.
- Shared pattern first: PASS. Future specs are instructed to reuse existing shared paths first.
- Provider boundary: PASS. Provider-specific detail is kept out of platform-core default language.
- UI/Productization coverage: PASS. Checked no-impact with rationale.
- Filament v5 / Livewire v4: PASS. No runtime Filament/Livewire changes; future guidance references native/shared primitives.

## Project Structure

```text
specs/370-global-surface-information-architecture-contract/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── artifacts/
    ├── 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
    └── validation-report.md
```

No `data-model.md`, `contracts/`, `research.md`, or `quickstart.md` is required for this docs-only package unless a later reviewer asks for a separate publication decision.

## Implementation Phases

### Phase 0 - Source Evidence And Scope Lock

- Confirm Spec 368 source artifacts exist and mark missing inputs as `not available`.
- Confirm no existing Spec 370 package or branch was present before creation.
- Lock the no-runtime-change boundary.

### Phase 1 - Contract Artifacts

- Draft the surface IA contract.
- Document the canonical standards boundary and the fact that Spec 370 IA review classes are not runtime `ActionSurfaceType` values.
- Draft the surface type, audience, and scope matrix.
- Draft the UI bloat pattern registry.
- Draft the page assessment checklist.
- Draft copy and terminology rules.
- Draft the follow-up spec map.
- Explicitly defer Spec 368 Candidate A target mock/example artifacts from this slice.

### Phase 2 - Consistency And Readiness

- Ensure `spec.md`, `plan.md`, `tasks.md`, checklist, and artifacts agree.
- Run Spec Kit prerequisite check with tasks.
- Run read-only preparation analysis guidance.
- Fix only Spec Kit artifacts if analysis finds bounded issues.
- Run `git diff --check`.

## Data Model

N/A. No database tables, models, migrations, JSONB columns, indexes, or persisted runtime artifacts.

## API / Contracts

N/A. No HTTP API, OpenAPI contract, JSON schema, Graph contract, queue contract, or external integration changes.

## UI / Filament Implications

No current Filament resource/page/provider/panel changes.

Future UI-changing specs should:

- keep Filament v5 / Livewire v4 compatibility;
- register panel providers only in `apps/platform/bootstrap/providers.php` when panel code changes;
- keep global search disabled unless View/Edit page and scoping rules are safe;
- keep destructive/high-impact actions on `->action(...)`, `->requiresConfirmation()`, server-side authorization, audit, and tests;
- use native Filament/shared primitives first;
- continue filling the repo's UI/UX Surface Classification and UI Action Matrix with canonical Action Surface classes, not Spec 370 IA review labels;
- update `docs/ui-ux-enterprise-audit/` only when reachable UI surfaces change.

## Test Strategy

- No Pest, PHPUnit, browser, PostgreSQL, or frontend test lane is required for this docs-only preparation package.
- Required validation:
  - `./.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks`
  - read-only preparation analysis across `spec.md`, `plan.md`, and `tasks.md`
  - `git diff --check`
- Future runtime specs that consume this contract must add focused Filament/Livewire/browser coverage only for the changed surface.

## Rollout Considerations

- No deploy impact.
- No env var, migration, queue, scheduler, storage, cache, Graph, asset, or worker impact.
- No `php artisan filament:assets` requirement because no Filament assets are registered.
- A later docs/product publication step may be considered only after review.

## Risk Controls

- Keep contract artifacts spec-local.
- Keep canonical standards and runtime Action Surface terminology authoritative.
- Keep automation/static guard work out of scope.
- Keep target mock/example artifacts out of scope unless a later spec approves them.
- Label source evidence by verification class.
- Require future deviations to be recorded in the active feature instead of silently forking UI language.
- Do not edit completed Spec 368/369 artifacts.

## Spec Readiness Gate

- `spec.md`, `plan.md`, `tasks.md`: required.
- `checklists/requirements.md`: required.
- Contract artifacts: required.
- Blocking open questions: none.
- Runtime implementation risk: none in this package.
- Later implementation scope: bounded docs-only finalization and optional review publication decision.