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

Implementation Plan: UI/UX Constitution Extension: Filament Nativity & Custom Surface Rules

Branch: 200-filament-surface-rules | Date: 2026-04-18 | Spec: specs/200-filament-surface-rules/spec.md Input: Feature specification from specs/200-filament-surface-rules/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Extend the existing UI constitution so Filament-native defaults, fake-native drift, legitimate custom surfaces, shared detail micro-UI families, and shell/page/detail state ownership are all reviewable through one integrated rule set. The implementation approach is docs-only: amend existing constitution sections rather than create a parallel UI rulebook, add the shared vocabulary and anti-pattern catalog grounded in Specs 196 through 199, define the exception model boundaries, and record a clean handoff to Spec 201 for enforcement.

Technical Context

Language/Version: Markdown governance artifacts in a PHP 8.4.15 / Laravel 12 / Filament v5 / Livewire v4 repository
Primary Dependencies: .specify/memory/constitution.md, docs/ui/operator-ux-surface-standards.md, adjacent Specs 196 through 199, existing UI rule IDs UI-SURF-001, ACTSURF-001, HDR-001, UI-HARD-001, UI-EX-001, UI-REVIEW-001, UI-FIL-001, DECIDE-001, and UX-001
Storage: N/A
Testing: Document review, representative-case validation, and checklist verification only
Validation Lanes: N/A (docs-only governance change)
Target Platform: Repository governance for the Laravel web application and its Filament admin/operator surfaces
Project Type: Laravel monolith with docs-only planning artifacts
Performance Goals: N/A; the success target is review clarity, constitution precision, and explicit scope boundaries rather than runtime performance
Constraints: No parallel rulebook; no runtime routes or API contracts; no CI/grep/lint/test enforcement in this spec; legitimate custom surfaces must remain possible; Spec 201 remains the enforcement boundary
Scale/Scope: One constitution amendment path, one supporting operator-UX standards reference, one spec artifact set, and cross-spec mapping across Specs 196 through 199 plus Spec 201

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: N/A (docs-only governance feature; no inventory or snapshot behavior changes)
• Read/write separation: PASS (no product write path is introduced)
• Graph contract path: PASS (no Graph calls or contract registry changes)
• Deterministic capabilities: PASS (no capability derivation changes)
• RBAC-UX: PASS (no authorization behavior changes; planned rules only reinforce existing boundaries)
• Workspace isolation: PASS (no new workspace context path; shell/page/detail layering rules must preserve established workspace truth)
• Tenant isolation: PASS (no new tenant access path; future rules explicitly forbid silent scope broadening)
• Run observability: PASS (no OperationRun creation or lifecycle changes)
• Ops-UX 3-surface feedback: N/A (no run feedback surfaces)
• Ops-UX lifecycle + summary counts + guards: N/A (no run lifecycle change)
• Ops-UX system runs: N/A
• Automation: N/A (no queued/scheduled flow)
• Data minimization: PASS (no runtime or persistence impact)
• Test governance (TEST-GOV-001): PASS (N/A lanes and no runtime impact are explicit; enforcement-oriented follow-up is deferred to Spec 201)
• Proportionality (PROP-001): PASS but triggered; the new vocabulary and taxonomy are bounded to already proven repo problem classes and do not create runtime architecture
• No premature abstraction (ABSTR-001): PASS (no new runtime factory, registry, resolver, or service layer is introduced)
• Persisted truth (PERSIST-001): PASS (repository docs only; no product truth added)
• Behavioral state (STATE-001): PASS (state-layer terms are governance vocabulary, not new persisted or executable state families)
• UI semantics (UI-SEM-001): PASS (the plan strengthens direct, reviewable domain-to-UI rules and rejects local semantic frameworks)
• V1 explicitness / few layers (V1-EXP-001, LAYER-001): PASS (existing constitution sections are amended in place rather than layered with a second framework)
• Spec discipline / bloat check (SPEC-DISC-001, BLOAT-001): PASS (all related semantic additions stay in one rule spec; enforcement stays separate in Spec 201)
• Badge semantics (BADGE-001): PASS (no new badge taxonomy; the plan only clarifies when local status language is forbidden)
• Filament-native UI (UI-FIL-001): PASS (this feature extends the rule instead of introducing alternative UI semantics)
• UI/UX surface taxonomy (UI-CONST-001 / UI-SURF-001): PASS (the plan tightens existing taxonomy and exception logic)
• Decision-first operating model (DECIDE-001): PASS (no new primary surface; the plan strengthens review vocabulary for future surfaces)
• UI/UX inspect model and hard rules (UI-HARD-001): PASS (the plan adds fake-native and state-layer clarity without changing runtime inspect models)
• Action-surface discipline (ACTSURF-001 / HDR-001 / UI-EX-001): PASS (the plan extends existing action and exception rules in place)

Gate status before Phase 0 research: PASS

Test Governance Check

Fill for any runtime-changing or test-affecting feature. Docs-only or template-only work may state concise N/A or none.

• Test purpose / classification by changed surface: N/A
• Affected validation lanes: N/A
• Why this lane mix is the narrowest sufficient proof: This feature is a docs-only governance and planning slice. Validation is review-oriented and does not require runtime or test-lane execution.
• Narrowest proving command(s): N/A
• Fixture / helper / factory / seed / context cost risks: none
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Closing validation and reviewer handoff: Reviewers should verify the amended constitution against the representative cases from Specs 196 through 199, confirm that no runtime enforcement is claimed prematurely, and ensure the handoff to Spec 201 is explicit.
• Budget / baseline / trend follow-up: none
• Review-stop questions: Does any rule create a parallel rulebook? Does any clause imply runtime enforcement that belongs to Spec 201? Does the taxonomy overreach beyond proven repo cases? Does the docs-only contract remain clearly bounded?
• Escalation path: none
• Why no dedicated follow-up spec is needed: A dedicated follow-up already exists as Spec 201; this plan only prepares the vocabulary and constitution amendments that Spec 201 will later operationalize.

Project Structure

Documentation (this feature)

specs/200-filament-surface-rules/
├── plan.md
├── checklists/
│   └── requirements.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── constitution-governance-contract.md
└── tasks.md

Source Code (repository root)

.specify/
├── memory/
│   └── constitution.md
└── templates/
    └── checklist-template.md          # referenced only; enforcement edits remain deferred to Spec 201

docs/
└── ui/
    └── operator-ux-surface-standards.md

specs/
├── 196-hard-filament-nativity-cleanup/
├── 197-shared-detail-contract/
├── 198-monitoring-page-state/
├── 199-global-context-shell-contract/
└── 200-filament-surface-rules/

Structure Decision: This is a docs-only governance feature. The implementation centers on .specify/memory/constitution.md plus the feature artifacts in specs/200-filament-surface-rules/. docs/ui/operator-ux-surface-standards.md is a reference alignment target only if wording drift is discovered during implementation. Checklist or CI operationalization remains explicitly deferred to Spec 201.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	N/A	N/A

Proportionality Review

• Current operator problem: Reviewers lack one stable language for classifying fake-native drift, bounded custom surfaces, shared-family host drift, and shell/page/detail state ownership. That makes future UI work inconsistent even when local specs identify specific defects.
• Existing structure is insufficient because: The existing constitution has strong surface and action rules, but it does not yet state native-by-default, fake-native, shared-family, and explicit state-layer ownership as one integrated set grounded in the proven repo cases from Specs 196 through 199.
• Narrowest correct implementation: Amend the existing constitution sections in place, add the minimal new vocabulary and anti-pattern catalog, define the exception boundary, and leave template/checklist/grep/test operationalization to Spec 201.
• Ownership cost created: The repo gains a tighter review vocabulary and more precise constitutional language that maintainers must preserve in future UI specs and PRs.
• Alternative intentionally rejected: A separate standalone UI constitution document, broad template enforcement in this spec, or a generic design-system framework detached from the existing constitution.
• Release truth: current-release review truth and governance clarity

Phase 0 — Outline & Research (Complete)

Outputs:

• specs/200-filament-surface-rules/research.md

Unknowns resolved:

• Which existing constitution sections should absorb the new rules so the repo avoids a parallel rulebook.
• Which parts of Spec 200 are genuinely new versus clarifications or extensions of existing rule IDs.
• How to model a contracts artifact for a docs-only governance slice without inventing runtime API endpoints.
• Which adjacent documentation artifacts should be referenced for operator-language and progressive-disclosure alignment.
• Which parts of review/checklist operationalization must stay deferred to Spec 201 to honor scope.

Phase 1 — Design & Contracts (Complete)

Outputs:

• specs/200-filament-surface-rules/data-model.md
• specs/200-filament-surface-rules/contracts/constitution-governance-contract.md
• specs/200-filament-surface-rules/quickstart.md

Design highlights:

• The feature uses a conceptual data model only: amendment targets, vocabulary terms, anti-patterns, exception types, state-ownership rules, and cross-spec mappings.
• No runtime API contract is introduced; the contract artifact explicitly records the docs-only governance scope, amendment targets, acceptance conditions, and deferred enforcement boundary.
• The quickstart centers on amending existing constitution sections, validating representative cases, and leaving automation to Spec 201.

Constitution Re-check (Post-Design)

Result: PASS

• The design remains docs-only and introduces no Graph calls, authorization changes, runtime state, or OperationRun behavior.
• The proportionality trigger stays justified because the new taxonomy is bounded to proven repo problem classes and integrated into existing rule IDs.
• No template, checklist, grep, lint, or runtime enforcement is pulled into this spec; those concerns remain explicitly deferred to Spec 201.
• Legitimate custom surfaces remain available through the documented exception path; the design does not collapse all operator-facing UI into one Filament-only rule.

Implementation Sequencing

1. Amend .specify/memory/constitution.md in place, targeting the existing sections 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 with the native-by-default, fake-native, shared-family, state-layer, reviewer-guidance, and exception rules.
2. Add the glossary and anti-pattern catalog inside the amended constitution language so the new vocabulary is reviewable without creating a second rule source.
3. Add the cross-spec mapping and close-out note in the Spec 200 artifact set, showing how Specs 196 through 199 feed the rules and what remains reserved for Spec 201.
4. Validate the amended constitution against the representative cases from Specs 196 through 199 to confirm that each case can be classified through the new rule language alone.
5. If wording drift is discovered, align docs/ui/operator-ux-surface-standards.md with the amended constitution without creating a competing standard or adding enforcement mechanics.
6. Record explicit deferrals to Spec 201 for review checklist changes, grep/lint guards, test enforcement, or CI automation.