TenantAtlas/specs/200-filament-surface-rules/tasks.md

# 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.