# Tasks: UI/UX Constitution Extension: Filament Nativity & Custom Surface Rules **Input**: Design documents from `/specs/200-filament-surface-rules/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/constitution-governance-contract.md **Tests**: N/A. This is a docs-only governance feature; no runtime or test-surface changes are planned in Spec 200. ## Test Governance Checklist N/A for this docs-only governance feature. Keep the feature bounded to documentation and constitution artifacts only. ## Phase 1: Setup (Shared Context) **Purpose**: Lock the implementation scope, amendment targets, and supporting source material before editing the constitution. - [x] T001 Review `specs/200-filament-surface-rules/spec.md`, `specs/200-filament-surface-rules/plan.md`, and `specs/200-filament-surface-rules/research.md` to lock the amendment scope and Spec 201 deferrals. - [x] T002 [P] Inspect `.specify/memory/constitution.md` and `docs/ui/operator-ux-surface-standards.md` to confirm the exact insertion points for `UI-FIL-001`, `UI-SURF-001`, `ACTSURF-001`, `HDR-001`, `UI-HARD-001`, `UI-EX-001`, `UI-REVIEW-001`, `Filament UI — Action Surface Contract`, and `UX-001`. --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Prepare the shared governance artifacts and validation scaffolding that all story work depends on. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [x] T003 Align `specs/200-filament-surface-rules/contracts/constitution-governance-contract.md` with the agreed amendment targets, acceptance contract, and explicit no-runtime boundary before constitution edits begin. - [x] T004 [P] Normalize the baseline amendment-target, vocabulary, anti-pattern, exception, and state-ownership definitions in `specs/200-filament-surface-rules/data-model.md`. - [x] T005 [P] Expand `specs/200-filament-surface-rules/quickstart.md` with the baseline representative validation flow for Specs 196 through 199 and the explicit Spec 201 handoff. **Checkpoint**: Amendment scope, supporting vocabulary, and deferred enforcement boundary are locked. --- ## Phase 3: User Story 1 - Classify Nativity And Exceptions Consistently (Priority: P1) 🎯 MVP **Goal**: Make native-by-default, fake-native drift, and legitimate custom-surface exceptions reviewable through the constitution alone. **Independent Test**: A reviewer can classify a fake-native dependency surface and a legitimate custom visualization using only the amended constitution and the representative cases from Spec 196. - [x] T006 [US1] Amend `.specify/memory/constitution.md` in `UI-FIL-001` and `UI-HARD-001` to add explicit native-by-default language and fake-native prohibitions. - [x] T007 [US1] Amend `.specify/memory/constitution.md` in `UI-EX-001` to define bounded legitimate custom-surface and nativity-exception rules. - [x] T008 [US1] Add `Native Surface`, `Fake-Native Surface`, `Custom Surface`, `Legitimate Exception`, plus the `Filament Costume`, `Blade Request UI`, `Hand-Rolled Simple Overview`, and `Hidden Exception` catalog entries in `.specify/memory/constitution.md`. - [x] T009 [US1] Amend `.specify/memory/constitution.md` in `UI-REVIEW-001` to add reviewer-facing nativity and exception-classification questions, then validate the amended language against `specs/196-hard-filament-nativity-cleanup/spec.md` and record any wording refinements in `specs/200-filament-surface-rules/quickstart.md`. **Checkpoint**: Native and exception cases are classifiable without local review vocabulary. --- ## Phase 4: User Story 2 - Cut Shared Detail Families And State Layers Correctly (Priority: P1) **Goal**: Make shared detail micro-UI families, host variation, and shell/page/detail state ownership explicit in the constitution. **Independent Test**: A reviewer can classify shared-family drift and shell/page/detail state confusion using only the amended constitution and the representative cases from Specs 197 through 199. - [x] T010 [US2] Amend `.specify/memory/constitution.md` in `UI-SURF-001`, `ACTSURF-001`, `HDR-001`, and `Filament UI — Action Surface Contract` to define shared detail micro-UI families, one-primary-interaction-model guidance, shared core zones, bounded host variation, and any related header-discipline clarifications. - [x] T011 [US2] Amend `.specify/memory/constitution.md` in `UX-001` and adjacent UI sections to define shell/page/detail ownership plus requested, active, draft, inspect, and restorable state roles. - [x] T012 [US2] Add `Shared Detail Micro-UI`, `Host`, `Global Context State`, `Page State`, `Detail State`, `Host Drift`, `State Layer Collapse`, and `Parallel Inspect Worlds` entries in `.specify/memory/constitution.md`. - [x] T013 [US2] Amend `.specify/memory/constitution.md` in `UI-REVIEW-001`, `ACTSURF-001`, `HDR-001`, and `UI-HARD-001` review gates to add reviewer-facing shared-family and state-layer questions, then validate the amended language against `specs/197-shared-detail-contract/spec.md`, `specs/198-monitoring-page-state/spec.md`, and `specs/199-global-context-shell-contract/spec.md`, and record any refinements in `specs/200-filament-surface-rules/quickstart.md`. **Checkpoint**: Shared-family and state-layer cases are classifiable without inventing a second taxonomy. --- ## Phase 5: User Story 3 - Prepare Enforcement Without Re-Inventing Rules (Priority: P2) **Goal**: Leave a clean cross-spec mapping and enforcement handoff so Spec 201 can operationalize the rules directly. **Independent Test**: A maintainer can derive Spec 201 enforcement targets from the amended constitution and feature artifacts without introducing new rule categories. - [x] T014 [US3] Update `specs/200-filament-surface-rules/contracts/constitution-governance-contract.md` with the finalized cross-spec mapping and the deferred enforcement boundary for Spec 201. - [x] T015 [P] [US3] Update `specs/200-filament-surface-rules/data-model.md` with the finalized `CrossSpecMapping` and exception-type relationships produced by the amended constitution. - [x] T016 [P] [US3] Add the close-out summary of new clauses, tightened clauses, and intentionally deferred enforcement work to `specs/200-filament-surface-rules/quickstart.md`. - [x] T017 [US3] Review `.specify/memory/constitution.md`, `specs/200-filament-surface-rules/contracts/constitution-governance-contract.md`, and `specs/200-filament-surface-rules/quickstart.md` together to verify that Spec 201 can consume the final vocabulary directly. **Checkpoint**: The constitution amendment and Spec 201 handoff are aligned and explicit. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final alignment, wording cleanup, and end-to-end validation across all stories. - [x] T018 [P] Align any remaining wording drift between `.specify/memory/constitution.md` and `docs/ui/operator-ux-surface-standards.md`. - [x] T019 [P] Refresh `specs/200-filament-surface-rules/research.md` with any final amendment-target or rejected-alternative adjustments discovered during implementation. - [x] T020 Run the representative-case walkthrough in `specs/200-filament-surface-rules/quickstart.md` against `.specify/memory/constitution.md` plus `specs/196-hard-filament-nativity-cleanup/spec.md`, `specs/197-shared-detail-contract/spec.md`, `specs/198-monitoring-page-state/spec.md`, and `specs/199-global-context-shell-contract/spec.md`. - [x] T021 Clean up and cross-check `specs/200-filament-surface-rules/plan.md`, `specs/200-filament-surface-rules/contracts/constitution-governance-contract.md`, and `specs/200-filament-surface-rules/quickstart.md` so the final artifact set tells one consistent story. --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies. - **Foundational (Phase 2)**: Depends on Setup completion and blocks all story work. - **User Story 1 (Phase 3)**: Depends on Foundational completion. - **User Story 2 (Phase 4)**: Depends on Foundational completion. - **User Story 3 (Phase 5)**: Depends on User Stories 1 and 2 because the enforcement handoff must reflect the final amended rule language. - **Polish (Phase 6)**: Depends on all user stories being complete. ### User Story Dependencies - **US1 (P1)**: Can start immediately after Foundational and serves as the MVP slice. - **US2 (P1)**: Can start after Foundational, but it edits the same constitution file as US1, so one implementer should do the core `.specify/memory/constitution.md` edits sequentially or split them by section ownership deliberately. - **US3 (P2)**: Starts after US1 and US2 stabilize because it documents the final mapping and Spec 201 handoff. ### Within Each User Story - Core `.specify/memory/constitution.md` edits should be completed before validation tasks for that story. - Story validation tasks should feed any refinement updates into `specs/200-filament-surface-rules/quickstart.md`. - Close-out and handoff tasks should only run after the governing constitution language is stable. ### Parallel Opportunities - `T002` can run in parallel with `T001` after the feature scope is understood. - `T004` and `T005` can run in parallel after `T003` establishes the final contract boundary. - `T015` and `T016` can run in parallel once the final constitution wording from US1 and US2 is stable. - `T018` and `T019` can run in parallel during Polish because they touch different files. --- ## Parallel Example: Foundational Work ```bash # After T003 locks the final contract boundary: Task: "Normalize the amendment-target, vocabulary, anti-pattern, exception, and state-ownership definitions in specs/200-filament-surface-rules/data-model.md" Task: "Expand specs/200-filament-surface-rules/quickstart.md with the representative validation flow for Specs 196 through 199 and the explicit Spec 201 handoff" ``` --- ## Parallel Example: User Story 3 ```bash # After US1 and US2 stabilize the final constitution wording: Task: "Update specs/200-filament-surface-rules/data-model.md with the finalized CrossSpecMapping and exception-type relationships" Task: "Add the close-out summary of new clauses, tightened clauses, and intentionally deferred enforcement work to specs/200-filament-surface-rules/quickstart.md" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup. 2. Complete Phase 2: Foundational. 3. Complete Phase 3: User Story 1. 4. **STOP and VALIDATE**: Confirm a reviewer can classify a fake-native case and a legitimate custom case from the amended constitution alone. ### Incremental Delivery 1. Complete Setup + Foundational. 2. Add User Story 1 and validate nativity/exception classification. 3. Add User Story 2 and validate shared-family/state-layer classification. 4. Add User Story 3 and validate the Spec 201 handoff. 5. Finish with Polish and representative-case walkthrough. ### Parallel Team Strategy With multiple contributors: 1. One contributor completes the contract-boundary task `T003`. 2. A second contributor can prepare `T004` while another prepares `T005`. 3. Once the constitution wording stabilizes, one contributor can finalize the contract note while another finalizes the close-out summary and data-model mapping. --- ## Notes - `[P]` tasks are parallelizable because they touch different files and do not depend on unfinished work in the same artifact. - User-story phases remain independently valuable, but US1 and US2 share `.specify/memory/constitution.md`, so section-level coordination matters. - No runtime tests, CI rules, or lint/grep enforcement should be added under this task list; those remain reserved for Spec 201.