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

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.