ahmido
edf7646a18
Some checks failed
Main Confidence / confidence (push) Failing after 43s
## Summary - add Spec 200 for the Filament nativity and custom-surface constitution slice - amend the shared constitution with native-by-default, fake-native, shared-family, state-layer, reviewer-guidance, and exception language - add the full Spec 200 artifact set: spec, plan, research, data model, quickstart, tasks, contract, and requirements checklist - align the operator UX standards doc to the new constitution vocabulary - remove superseded `001-*` spec artifacts that were replaced by the new feature work ## Validation - completed consistency analysis across spec, plan, tasks, and contract artifacts - completed integrated-browser smoke check on the current TenantPilot dashboard - no runtime tests executed because this is a docs-only governance change ## Notes - runtime application behavior is intentionally unchanged - enforcement automation, grep/lint guards, and regression test operationalization remain deferred to Spec 201 Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #248
90 lines
6.2 KiB
Markdown
90 lines
6.2 KiB
Markdown
# 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
|