104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# 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
|