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.

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

• 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.
• T004 [P] Normalize the baseline amendment-target, vocabulary, anti-pattern, exception, and state-ownership definitions in specs/200-filament-surface-rules/data-model.md.
• 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.

• 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.
• T007 [US1] Amend .specify/memory/constitution.md in UI-EX-001 to define bounded legitimate custom-surface and nativity-exception rules.
• 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.
• 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.

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

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

• T018 [P] Align any remaining wording drift between .specify/memory/constitution.md and docs/ui/operator-ux-surface-standards.md.
• T019 [P] Refresh specs/200-filament-surface-rules/research.md with any final amendment-target or rejected-alternative adjustments discovered during implementation.
• 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.
• 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

# 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

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