feat(aidd-ui): govern UI systems and experience contracts

[blafourcade]

Problem

aidd-ui was a loader smoke test, not an architectural concern. UI decisions were either implicit or mixed into implementation planning, with no stable contract for design-system evolution or feature experience.

Architecture

Ownership is now explicit:

• aidd-pm owns product intent and requirements.
• aidd-context owns durable project memory.
• aidd-ui owns shared UI-system contracts, feature experience contracts, and experience review.
• aidd-dev owns implementation and technical correctness.
• orchestrators own cross-concern sequencing.

The authority model is:

• code = current implementation truth
• project memory = compact stable pointers
• UI-system contracts = shared design decisions
• task-local ui.md = feature experience decisions

Memory remains read-only to aidd-ui. Repository evidence wins on drift, which is reported for a separate Context-owned refresh.

Design-system contract

01-system makes the design system a governed capability rather than an asset bundle. It discovers existing conventions, maps ownership scopes, establishes the minimum viable system when absent, and manages explicit deltas through draft, approval, verification, promotion, reconciliation, and retirement.

All decisions follow existing -> reuse -> extend -> create. Higher-level page and composite patterns are considered before primitives and tokens. Concurrent scopes use explicit locks; replacement and nested-scope rules avoid parallel systems and ambiguous ownership.

The plugin contracts asset roles, sources, constraints, and acceptance criteria. It does not generate binary assets or production components; those remain implementation work.

Skills

Five domains survived the responsibility review:

• 01-system: versioned shared UI-system authority and lifecycle
• 02-design: versioned feature-local experience contract, including structure, expression, assets, refinement, and implementation handoff
• 03-review: evidence-pinned, nonnormative experience findings
• 04-accessibility: reusable accessibility requirements and review fragments
• 05-adapt: reusable viewport, input, content-pressure, and motion adaptation fragments

Separate handoff and polish skills were removed because they duplicated the design lifecycle. Accessibility and adaptation remain separate providers because each has an independently invocable validation domain.

Compared with Impeccable, which directly shapes and edits frontend implementation, aidd-ui produces versioned AIDD decision artifacts and provider fragments. It does not copy Impeccable's command ecosystem, browser tooling, or implementation ownership.

Dev integration

Frontend planning discovers and consumes a ready ui.md contract by reference. The legacy wireframe path remains a bounded fallback while the provider is optional. UI-system and contract revisions are revalidated before implementation; drift stops execution and requests replanning.

The net change to aidd-dev:01-plan is five lines versus next; the lifecycle detail lives in the owning aidd-ui skills.

Validation

• pnpm exec lefthook run pre-commit => passed
• pnpm exec lefthook run pre-push => passed; CLI suites skipped because no matching push files
• node --test \"scripts/__tests__/*.test.js\" => 8/8 passed
• claude plugin validate plugins/aidd-ui --strict => passed
• claude plugin validate plugins/aidd-dev --strict => passed
• node scripts/check-skill-argument-hints.mjs => passed
• node scripts/check-markdown-links.js => 0 broken links across 734 links
• UI headless scenario matrix => 32/32 passed after targeted reruns
• Dev integration scenario matrix => 9/9 passed after targeted reruns
• final functional adversarial review => 100/100, ship
• final skill-authoring review against 04-skill-generate R1-R19 => ship, no defects
• final anti-slop review => 96/100, ship, no blocker or important finding

The evaluator now stages specialist providers, creates deterministic Git fixtures, snapshots files and directories, rejects unexpected mutations, and fails on any nonzero or signaled Claude CLI exit. Four UI cases and two Dev cases hit CLI exit 143 during parallel runs; each passed in an isolated rerun. One fallback defect and one brittle assertion were corrected before the final results above.

Known limitations

• aidd-ui remains alpha and recommended: false.
• No Figma integration, image generation, browser automation, visual regression, or automatic memory writes.
• Contracts are Markdown artifacts; no machine schema enforcement is introduced in this increment.
• The legacy Dev wireframe fallback remains until UI capability availability can be assumed or orchestrated.
• Rich rendered-browser experience review and orchestrator sequencing remain follow-up work.

Certification

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.