6.2 KiB
6.2 KiB
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.mdspecs/200-filament-surface-rules/research.mdspecs/200-filament-surface-rules/data-model.md.specify/memory/constitution.mddocs/ui/operator-ux-surface-standards.mdspecs/196-hard-filament-nativity-cleanup/spec.mdspecs/197-shared-detail-contract/spec.mdspecs/198-monitoring-page-state/spec.mdspecs/199-global-context-shell-contract/spec.md
Steps
- Start in
.specify/memory/constitution.mdand 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, andUI-FIL-001. - 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.
- Add the required vocabulary terms and anti-pattern names inside the amended constitution language instead of in a separate standalone document.
- Extend the exception model so legitimate deviations are named, bounded, and forced to state what remains standardized.
- Validate the amendment against the representative cases from Specs 196 through 199. Each case must be classifiable from the constitution text alone.
- 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
- Only if wording drift is discovered, align
docs/ui/operator-ux-surface-standards.mdwith 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
- Name the surface class and decide whether the surface is
Native Surface,Custom Surface, or aShared Detail Micro-UI. - Decide whether any named anti-pattern appears:
Filament Costume,Blade Request UI,Hand-Rolled Simple Overview,Hidden Exception,Host Drift,State Layer Collapse, orParallel Inspect Worlds. - If the case is still allowed, identify the exact exception type and the standardized parts that remain intact.
- Name which layer owns the relevant truth:
Global Context State,Page State, orDetail State. - Name which state roles matter:
Requested,Active,Draft,Inspect, orRestorable. - 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.mdfor enforcement behavior - adding grep or lint guards
- adding CI checks
- inventing sample runtime endpoints or implementation code snippets to simulate enforcement