TenantAtlas/specs/200-filament-surface-rules/quickstart.md

Quickstart: Implementing Spec 200

Purpose

Use this sequence when turning Spec 200 into the actual constitution amendment.

This is a docs-only governance feature. Do not add runtime behavior, transport contracts, CI rules, or enforcement automation here.

Inputs

• specs/200-filament-surface-rules/spec.md
• specs/200-filament-surface-rules/research.md
• specs/200-filament-surface-rules/data-model.md
• .specify/memory/constitution.md
• docs/ui/operator-ux-surface-standards.md
• specs/196-hard-filament-nativity-cleanup/spec.md
• specs/197-shared-detail-contract/spec.md
• specs/198-monitoring-page-state/spec.md
• specs/199-global-context-shell-contract/spec.md

Steps

1. Start in .specify/memory/constitution.md and locate the existing sections targeted by the plan: UI-SURF-001, ACTSURF-001, UI-HARD-001, UI-EX-001, Filament UI — Action Surface Contract, UX-001, and UI-FIL-001.
2. Add the minimum rule language needed to make native-by-default, fake-native, legitimate custom surfaces, shared detail families, and shell/page/detail state ownership explicit.
3. Add the required vocabulary terms and anti-pattern names inside the amended constitution language instead of in a separate standalone document.
4. Extend the exception model so legitimate deviations are named, bounded, and forced to state what remains standardized.
5. Validate the amendment against the representative cases from Specs 196 through 199. Each case must be classifiable from the constitution text alone.
6. Write the close-out note for Spec 200, clearly separating:
   • newly added or tightened constitution rules
   • clarifications to existing rules
   • items intentionally deferred to Spec 201
7. Only if wording drift is discovered, align docs/ui/operator-ux-surface-standards.md with the amended constitution. Do not create a competing standards document.

Representative Walkthrough

Use this exact walkthrough to validate that the amendment classifies the already proven repo cases without inventing new rule families during review.

Source spec	Case to walk through	Constitution language that must classify it	Expected result
Spec 196	Dependency edges, required-permissions filters, and evidence overview nativity cleanup	UI-FIL-001, UI-HARD-001, UI-EX-001, UI-REVIEW-001	Fake-native and simple-overview drift are rejected unless a bounded custom or nativity exception is explicit
Spec 197	Verification report and normalized diff/settings hosts	UI-SURF-001, ACTSURF-001, HDR-001, Filament UI — Action Surface Contract, UI-REVIEW-001	Shared-family core and host-owned variation are distinguishable; host drift is rejectable
Spec 198	Monitoring and compare state ownership	UI-HARD-001, UX-001, UI-REVIEW-001	Requested, active, draft, inspect, and restorable state roles are classifiable without treating them as one blur
Spec 199	Global context bar, tenantless shell, fallback behavior	ACTSURF-001, UX-001, UI-REVIEW-001	Global context state is clearly shell-owned and not silently re-owned by a page or partial

Walkthrough output checklist

1. Name the surface class and decide whether the surface is Native Surface, Custom Surface, or a Shared Detail Micro-UI.
2. Decide whether any named anti-pattern appears: Filament Costume, Blade Request UI, Hand-Rolled Simple Overview, Hidden Exception, Host Drift, State Layer Collapse, or Parallel Inspect Worlds.
3. If the case is still allowed, identify the exact exception type and the standardized parts that remain intact.
4. Name which layer owns the relevant truth: Global Context State, Page State, or Detail State.
5. Name which state roles matter: Requested, Active, Draft, Inspect, or Restorable.
6. Stop if the review needs a new term. Spec 200 is only complete when the constitution text already contains the needed category.

Cross-Spec Mapping

Input spec	What Spec 200 absorbs	What remains outside Spec 200
196-hard-filament-nativity-cleanup	native-by-default language, fake-native prohibitions, simple-overview default-to-native rule	runtime cleanup work and regression tests
197-shared-detail-contract	shared detail micro-UI and host/core vocabulary, host-drift review gates	runtime host consolidation and regression tests
198-monitoring-page-state	shell/page/detail ownership vocabulary and explicit state-role language	runtime page-state contract implementation and regression tests
199-global-context-shell-contract	workspace-first shell ownership vocabulary and shell/page separation	runtime shell resolution and fallback behavior
201-*	no new concepts; only enforcement consumers	checklist, grep, lint, CI, and regression operationalization

Validation Checklist

• The constitution is still the single source of truth.
• No new runtime route, API, database, or enforcement code has been introduced.
• Legitimate custom surfaces are still possible through the exception model.
• Fake-native drift is named clearly enough that reviewers can identify it quickly.
• Shared detail family and state-layer rules are grounded in the already proven cases from Specs 197, 198, and 199.
• The handoff to Spec 201 is explicit and does not require new conceptual categories.

Close-out Summary

When the amendment is finished, leave one concise close-out note that separates:

• New clauses and vocabulary: native/custom/fake-native classification, shared detail micro-UI and host language, state-layer ownership terms, and the named anti-pattern catalog.
• Tightened existing clauses: native-by-default expectations, one-primary-interaction-model discipline, shared-family host ownership, record-header discipline for embedded families, and explicit review questions.
• Deferred enforcement: checklist operationalization, grep/lint guards, CI checks, and runtime or test-backed regression enforcement in Spec 201.

Not In Scope Here

• changing .specify/templates/checklist-template.md for enforcement behavior
• adding grep or lint guards
• adding CI checks
• inventing sample runtime endpoints or implementation code snippets to simulate enforcement