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
175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# 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.
|