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

.claude-plugin/marketplace.json

@@ -52,7 +52,7 @@
     {
       "name": "aidd-ui",
       "source": "./plugins/aidd-ui",
-      "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.",
+      "description": "ALPHA. Shared UI systems, feature experience contracts, UX review, accessibility, and interface adaptation.",
       "strict": true,
       "recommended": false
     }

README.md

@@ -11,7 +11,7 @@ _(Already tested on `Legacy` codebases)_
 [![Made in France](https://img.shields.io/badge/made%20in-France-0055A4?labelColor=EF4135)](https://www.ai-driven-dev.fr/)
 
 <p>
-  <!--counts:start--><kbd>7 plugins</kbd> · <kbd>47 skills</kbd> · <kbd>2 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
+  <!--counts:start--><kbd>7 plugins</kbd> · <kbd>51 skills</kbd> · <kbd>2 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
 </p>
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -277,9 +277,9 @@ Synchronous feature flow, async issue-to-PR automation, and product backlog.
 
 ### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧
 
-`1 skill` · **alpha**
+`5 skills` · **alpha**
 
-UI / UX design — smoke-test only, not ready for use.
+Versioned UI system contracts, feature experience decisions, specialist verdicts, and evidence-pinned review.
 
 </td>
 <td width="33%" valign="top"></td>

docs/ARCHITECTURE.md

@@ -55,10 +55,11 @@ Every capability lives in exactly one plugin, chosen by **concern**. This taxono
 | `aidd-orchestrator` | Orchestration        | Coordination |
 | `aidd-ui` 🚧        | UI/UX design         | Execution    |
 
-`aidd-ui` is alpha: smoke-test only, off the curated install path.
+`aidd-ui` is alpha: it owns interface experience decisions and remains off the curated install path.
 
 - **Knowledge vs execution is a firewall.** Knowledge plugins produce artifacts you *read* and never write or run application source. `aidd-context`'s bootstrap deliberately creates no `package.json`. Real code belongs to `aidd-dev` or an orchestrator's own setup actions.
 - **Concern decides placement, not existence.** A missing capability goes in the plugin whose concern owns it, then the caller delegates. Never reimplement it in the calling plugin because the right home lacks it today.
+- **The UI seam is an experience contract, not application code.** Product intent and durable project knowledge feed UI decisions; code transformation consumes those decisions for implementation. Current code wins when project memory drifts, and only the knowledge concern updates memory.
 - **Orchestration = sequencing across concerns** with little domain logic. Delegating a sub-step once does not make a skill an orchestrator. The orchestrator owns only glue and hands off through a seam artifact, for example an `INSTALL.md` one plugin produces and another consumes.
 - `aidd-orchestrator:02-backlog` owns the cross-artifact flow. Each artifact's contract stays in its `aidd-pm` skill, so a direct PM call follows the same rules as an orchestrated one.
 

docs/CATALOG.md

@@ -8,7 +8,7 @@ The exhaustive list of AIDD plugins, skills, and actions. Skills are invoked thr
 - [aidd-refine](#-aidd-refine) - meta-cognition
 - [aidd-vcs](#-aidd-vcs) - version control workflows
 - [aidd-orchestrator](#-aidd-orchestrator) - async orchestration (optional)
-- [aidd-ui](#-aidd-ui) - UI / UX (🚧 alpha, not ready)
+- [aidd-ui](#-aidd-ui) - UI / UX decisions (🚧 alpha)
 
 ---
 
@@ -38,10 +38,10 @@ Code transformation: plan, implement, assert, audit, review, test, refactor, deb
 
 | Skill           | Role                                                                       | Actions                                                                         |
 | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `01-plan`       | Turn a request, ticket, or file into a phased implementation plan: gather, explore, wireframe, plan | `01-gather`, `02-explore`, `03-wireframe`, `04-plan`          |
+| `01-plan`       | Turn a request, ticket, or file into a phased implementation plan and resolve ready UI decisions | `01-gather`, `02-explore`, `03-experience`, `04-plan`          |
 | `02-implement`  | Execute a plan phase by phase until 100% complete                          | `01-implement`                                                                   |
 | `03-assert`     | Assert features work - general, architecture, frontend UI                  | `01-assert`, `02-assert-architecture`, `03-assert-frontend`                      |
-| `04-audit`      | Read-only codebase audit across quality pillars                            | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` |
+| `04-audit`      | Read-only codebase audit; UI experience is delegated to its owning concern | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` |
 | `05-review`     | Read-only review of a diff - code quality and feature behavior             | `01-review-code`, `02-review-functional`                                         |
 | `06-test`       | Write and iterate tests, validate user journeys in the browser             | `01-test`, `02-test-journey`                                                     |
 | `07-refactor`   | Improve code without changing behavior across four axes                    | `01-performance`, `02-security`, `03-cleanup`, `04-architecture`                 |
@@ -102,8 +102,12 @@ Runs synchronous feature delivery, optional async issue automation, and the prod
 
 ## 🎨 aidd-ui
 
-🚧 **Alpha — not ready for use.** UI / UX: design, review, and improve frontend interfaces. Currently a smoke-test only.
+🚧 **Alpha.** Shared UI systems and feature experience decisions. Off the curated install path.
 
-| Skill      | Role                                      | Actions    |
-| ---------- | ----------------------------------------- | ---------- |
-| `01-hello` | Smoke-test that confirms the plugin loads | `01-greet` |
+| Skill | Role | Actions |
+| --- | --- | --- |
+| `01-system` | Manage shared UI system contracts and deltas | `inspect`, `map`, `specialize`, `adopt`, `establish`, `extend`, `retire`, `reconcile`, `promote` |
+| `02-design` | Create or revise a feature UI contract | `frame`, `inspect`, `specialize`, `structure`, `compose`, `write`, `verify` |
+| `03-review` | Diagnose and prioritize experience defects | `inspect`, `specialize`, `assess`, `write` |
+| `04-accessibility` | Own accessibility requirements and verdicts | `inspect`, `specify`, `evaluate` |
+| `05-adapt` | Own space, input, and platform transformations | `inspect`, `specify`, `evaluate` |

plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md

@@ -1,25 +1,23 @@
 # Design
 
-The visual language: the design system, tokens, and UI conventions. What it looks like, not how it is coded.
+Compact pointers to stable UI knowledge. Current code remains implementation truth; an active UI system contract remains decision authority.
 
-## System
+## UI System Authority
 
-- <Design-system approach (tokens, library, ad hoc) and where it lives>
-- <Styling method (CSS-in-JS, utility classes, modules)>
+- <Active contract path, id, and scope; or "none">
 
-## Tokens
+## Current Implementation
 
-- <Where colors, spacing, and typography are defined. Point to the file>
+- <UI system maturity and styling method>
+- <Canonical token, theme, component, layout, and asset source paths>
 
-## Components
+## Stable Context
 
-- <The shared component patterns and their states>
-
-## Accessibility
-
-- <The a11y bar (contrast, focus, ARIA) and how it is met>
+- <Stable convention not already normative in the active contract>
+- <Known contract, implementation, or external-document drift>
 
 <!--
-Capture: the design system, where tokens live, the a11y bar.
-Skip: per-component CSS. Point to the theme file. Remove this comment when filled.
+When an active UI system contract exists, point to it instead of copying its token, component, adaptation, or accessibility decisions.
+When none exists, summarize only stable implemented conventions and their source paths.
+Skip feature-local decisions and per-component values. Remove this comment when filled.
 -->

plugins/aidd-context/skills/02-project-memory/references/reading-sources.md

@@ -10,6 +10,7 @@ opening it again.
 | -------------------------------------------- | -------------------------------------------- |
 | the manifest, and a lockfile beside it        | the stack, the workspaces, the published name |
 | the root README, then any `docs/`             | what it does, for whom, its domain words      |
+| current contracts under `aidd_docs/ui/systems/` | accepted shared UI authority, ids, and scopes |
 | the top-level directories                     | the shape, and which areas own what           |
 | the entry points the manifest declares        | where execution starts                        |
 | every file under the VCS platform's own directory | how it ships, and what runs on its own schedule |
@@ -38,6 +39,8 @@ wrote stays whatever the verdicts below say.
 | a work item, a live value, a technical id                     | drop    |
 | a plan, a wish, a thing not shipped                           | drop    |
 
+For a current UI system contract, keep only its path, immutable id, and normalized scope. The path resolves the current revision; do not copy its decisions or retain the revision number in memory.
+
 ## Depth
 
 - Every workspace of a monorepo, never the root manifest alone.

plugins/aidd-dev/CATALOG.md

@@ -44,7 +44,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |-------|------|---|
 | `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - |
 | `actions` | [02-explore.md](skills/01-plan/actions/02-explore.md) | - |
-| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - |
+| `actions` | [03-experience.md](skills/01-plan/actions/03-experience.md) | - |
 | `actions` | [04-plan.md](skills/01-plan/actions/04-plan.md) | - |
 | `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | - |
 | `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | - |
@@ -84,7 +84,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - |
 | `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - |
 | `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` |
-| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Audit a codebase read-only across seven quality pillars into one ranked report. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works.` |
+| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Audit a codebase read-only across six engineering pillars plus delegated UI experience review. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works.` |
 
 #### `skills/05-review`
 

plugins/aidd-dev/README.md

@@ -14,7 +14,7 @@ Covers code transformation: planning, implementation, assertions, audits, code r
 
 | Bracket ID | Skill | Description |
 |---|---|---|
-| [2.1] | [plan](skills/01-plan/SKILL.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. |
+| [2.1] | [plan](skills/01-plan/SKILL.md) | Turn a request, ticket, or file into a phased implementation plan, resolving a ready UI contract for frontend work with a bounded compatibility fallback while the UI provider is optional. |
 | [2.2] | [implement](skills/02-implement/SKILL.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. |
 | [2.3] | [assert](skills/03-assert/SKILL.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. |
 | [2.4] | [audit](skills/04-audit/SKILL.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. |

plugins/aidd-dev/skills/01-plan/SKILL.md

@@ -10,19 +10,19 @@ Turn a gathered source into an implementation plan and its phase files. Never wr
 
 ## Actions
 
-| #   | Action      | Role                                                 | Input                      |
-| --- | ----------- | ---------------------------------------------------- | -------------------------- |
-| 01  | `gather`    | Collect and restate the source                       | user request               |
-| 02  | `explore`   | Read the codebase for projection, rules, feasibility | gathered source            |
-| 03  | `wireframe` | Sketch a screen at low fidelity, frontend only       | source + explore context   |
-| 04  | `plan`      | Break into phases, write the plan and phase files    | explore output + wireframe |
+| #   | Action       | Role                                                 | Input                        |
+| --- | ------------ | ---------------------------------------------------- | ---------------------------- |
+| 01  | `gather`     | Collect and restate the source                       | user request                 |
+| 02  | `explore`    | Read the codebase for projection, rules, feasibility | gathered source              |
+| 03  | `experience` | Resolve UI decisions, frontend only                  | source + explore context     |
+| 04  | `plan`       | Break into phases, write the plan and phase files    | explore output + UI contract |
 
 Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI.
 Before running an action, read its file in `actions/`, not only the table or assets.
 
 ## References
 
-- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs.
+- `references/wireframe-conventions.md`: bounded compatibility fallback while the UI provider remains optional.
 - `references/plan-status.md`: the plan lifecycle `status` values and who writes each.
 
 ## Assets

plugins/aidd-dev/skills/01-plan/actions/03-experience.md

@@ -0,0 +1,29 @@
+# 03 - Experience
+
+Resolve implementation-ready UI decisions for frontend work. Skip when the feature has no interface.
+
+## Input
+
+The gathered source, explore context, and optional feature `ui.md`.
+
+## Output
+
+Prefer one verified current `ui.md` reference with revision, pinned systems, and required deltas. When the alpha UI provider is unavailable, return a compatibility-only low-fidelity wireframe.
+
+## Process
+
+1. **Find.** Inspect the feature's current `ui.md` and reject it while `.ui.lock` exists.
+2. **Discover.** Resolve a provider from runtime capability metadata without naming a sibling.
+3. **Resolve.** Invoke `create` or `revise` when available, then accept only a current ready contract whose systems and approved or verified deltas resolve at their current bases.
+   - Route satisfied approved deltas to system reconciliation and promoted deltas to UI revision.
+4. **Fallback.** Draw a structure-only wireframe from [wireframe-conventions.md](../references/wireframe-conventions.md) only when no contract and no provider exist.
+   - Stop with `UI revision needed` when a contract exists but no provider can revise it.
+5. **Return.** Reference a resolved contract and dependencies without copying decisions, or return the bounded fallback wireframe.
+
+## Test
+
+- Non-UI work skips this action.
+- UI work yields one current ready contract with resolvable dependencies.
+- A draft, stale, or promoted graph routes to its owning UI operation.
+- Provider absence preserves only the compatibility wireframe and creates no UI artifact.
+- Provider absence never bypasses an existing draft or stale contract.

plugins/aidd-dev/skills/01-plan/actions/04-plan.md

@@ -4,7 +4,7 @@ Turn the explored source into a plan and its phases, save them, then review the
 
 ## Input
 
-The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`.
+The explore output from `02-explore` (projection, rules, feasibility, risks), plus the verified UI contract reference or compatibility wireframe from `03-experience` for frontend work.
 
 ## Output
 
@@ -14,15 +14,21 @@ A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slu
 
 1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many.
 2. **Folder.** Reuse the feature folder the source already lives in, or create one.
-3. **Fill.** Fill the plan and each phase from their templates, following the inline contracts. Slice the projection across the phases.
-4. **Show.** Display the written paths.
-5. **Review.** Score the complete plan and its phases from 0 to 10, with ✓ reasons and ✗ risks. In interactive mode, show them and revise until approved. Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source. The score is never written to the plan.
+3. **Fill.** Fill the plan and phases from their templates.
+   - Slice the architecture projection across phases.
+   - For UI work, reference either the contract or fallback without copying it.
+   - Assign each approved delta to one phase and treat verified deltas as dependencies.
+4. **Validate.** Read back every phase and require `UI Contract` and `Wireframe` to be mutually exclusive and absent from non-UI phases.
+5. **Show.** Display the written paths.
+6. **Review.** Score the complete plan and its phases from 0 to 10, with ✓ reasons and ✗ risks. In interactive mode, show them and revise until approved. Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source. The score is never written to the plan.
 
 ## Test
 
 - `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/plan.md` exists with one `phase-<n>.md` per phase next to it.
 - Every written file satisfies its template's inline contract.
 - No `{...}` placeholder is left in any written file.
 - The phase projection slices together cover the modify, create, and delete lists.
+- Every UI phase references the ready contract or compatibility wireframe, never both.
+- Every approved delta has exactly one implementation owner; verified deltas have none.
 - A confidence score was reported and written to no file.
 - An autonomous run waits only for a product decision that the source cannot resolve.

plugins/aidd-dev/skills/01-plan/assets/phase-template.md

@@ -46,12 +46,22 @@ journey
     {cleanup or reset action} => {baseline restored}: 5: {channel}
 ```
 
-## Wireframe
+## UI Contract
 
 <!-- UI phase only. No UI => omit the section, don't invent one. -->
 
+- Contract: `{project-relative ui.md path}@{revision}`
+- Systems: {system ids and revisions}
+- Implement deltas: {approved delta paths owned by this phase or none}
+- Consume deltas: {verified delta paths and approved delta paths owned by an earlier phase, or none}
+- Depends on phases: {owners of consumed approved deltas or none}
+
+## Wireframe
+
+<!-- Compatibility fallback only when no UI provider is installed. Omit when UI Contract is present. -->
+
 ```txt
-{the confirmed wireframe}
+{structure-only wireframe}
 ```
 
 ## Tasks to do