TenantAtlas/specs/200-filament-surface-rules/contracts/constitution-governance-contract.md

Constitution Governance Contract

Contract Type

Docs-only governance contract. This feature introduces no runtime HTTP, GraphQL, CLI, or queue API surface.

Governing Scope

Spec 200 must amend the existing UI constitution so the following rule families become explicit, reviewable, and bounded:

• Filament-native by default
• fake-native prohibitions
• legitimate custom-surface allowance
• shared detail micro-UI family rules
• shell/page/detail state ownership rules
• reviewer-facing guidance and classification questions
• explicit exception handling
• named anti-pattern catalog

Required Amendment Targets

The implementation must update the existing constitution in .specify/memory/constitution.md rather than create a separate rulebook.

Expected amendment targets:

• UI-SURF-001
• ACTSURF-001
• HDR-001
• UI-HARD-001
• UI-EX-001
• UI-REVIEW-001
• Filament UI — Action Surface Contract
• UX-001
• UI-FIL-001 where native-first wording needs sharpening

Final Amendment Mapping

Source spec	Problem class absorbed by Spec 200	Final constitution targets
Spec 196	Native-by-default clarity, fake-native drift, request-driven body-state misuse, simple-overview drift	UI-FIL-001, UI-HARD-001, UI-EX-001, UI-REVIEW-001
Spec 197	Shared detail micro-UI families, host/core boundaries, bounded host variation	UI-SURF-001, ACTSURF-001, HDR-001, Filament UI — Action Surface Contract, UI-REVIEW-001
Spec 198	Requested vs active vs draft vs inspect vs restorable page-state ownership	UI-HARD-001, UX-001, UI-REVIEW-001
Spec 199	Workspace-first shell truth, tenantless state, shell/page separation, fallback clarity	ACTSURF-001, UX-001, UI-REVIEW-001
Spec 201	Enforcement follow-up only	deferred consumer; no constitution wording invented there

Final Exception Boundary

Spec 200 leaves four bounded exception families available inside UI-EX-001:

• Legitimate Custom Surface Exception
• Nativity Exception
• Shared Detail Host Variation Exception
• State-Layer Special-case Exception

Each exception must stay inside the existing exception model and must state:

1. the product reason
2. the smallest custom behavior required
3. what remains standardized
4. which layer owns the relevant state
5. what Spec 201 may later enforce

Acceptance Contract

The finished constitution amendment must satisfy all of the following:

1. A reviewer can classify the representative cases from Specs 196, 197, 198, and 199 using the amended constitution alone.
2. The amendment does not create a parallel top-level UI rulebook.
3. Legitimate custom surfaces remain possible through an explicit exception path.
4. The anti-pattern catalog names at least the recurring drift classes identified in the feature spec.
5. Reviewer-facing guidance and classification questions are explicit enough to classify the representative cases from Specs 196 through 199.
6. The cross-spec mapping to Specs 196 through 199 and the deferral to Spec 201 are explicit.

The acceptance contract is not satisfied unless the constitution now names all of the following review classes directly: Native Surface, Fake-Native Surface, Custom Surface, Shared Detail Micro-UI, Host, Global Context State, Page State, Detail State, Legitimate Exception, Host Drift, State Layer Collapse, and Parallel Inspect Worlds.

Out of Scope

This contract explicitly excludes:

• app/ runtime code changes
• route, controller, or Livewire behavior changes
• CI/grep/lint/test enforcement
• checklist-template operationalization beyond optional wording-only references
• fabricated REST or GraphQL endpoints

Deferred Enforcement Boundary

Spec 201 is responsible for operationalization work such as:

• review checklist changes
• grep/lint guards
• CI enforcement
• runtime or test-backed regression guards for the anti-pattern catalog

Spec 200 must define the rule language cleanly enough that Spec 201 can consume it without inventing a new vocabulary.

Close-out Contract

The final artifact set must leave one explicit close-out note that separates:

• newly added clauses and vocabulary
• tightened existing clauses
• enforcement work intentionally deferred to Spec 201