baldart 4.81.0 → 4.82.0

package/framework/.claude/skills/skill-creator/scripts/quick_validate.py

@@ -39,7 +39,10 @@ def validate_skill(skill_path):
         return False, f"Invalid YAML in frontmatter: {e}"
 
     # Define allowed properties
-    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}
+    # BALDART additions: `effort` (per-skill reasoning baseline — effort-protocol.md)
+    # and `version` (per-skill SemVer — canonical structure, see references/skill-structure.md).
+    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata',
+                          'effort', 'version'}
 
     # Check for unexpected properties (excluding nested keys under metadata)
     unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
@@ -83,6 +86,19 @@ def validate_skill(skill_path):
         if len(description) > 1024:
             return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
 
+    # BALDART canonical-structure warnings (non-fatal — see references/skill-structure.md).
+    # `version` + a per-skill CHANGELOG.md are REQUIRED for new skills but WARNED (not
+    # hard-failed) here for backwards-compat with skills authored before the convention.
+    warnings = []
+    if 'version' not in frontmatter:
+        warnings.append("missing `version:` in frontmatter (add `version: 1.0.0`)")
+    if 'effort' not in frontmatter:
+        warnings.append("missing `effort:` in frontmatter (see effort-protocol.md)")
+    if not (skill_path / 'CHANGELOG.md').exists():
+        warnings.append("missing CHANGELOG.md (per-skill changelog — keeps version history out of SKILL.md context)")
+    if warnings:
+        return True, "Skill is valid! Warnings:\n  - " + "\n  - ".join(warnings)
+
     return True, "Skill is valid!"
 
 if __name__ == "__main__":

package/framework/.claude/skills/toolchain-bootstrap/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — toolchain-bootstrap
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/toolchain-bootstrap/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: toolchain-bootstrap
 effort: medium
+version: 1.0.0
 description: >
   Install, verify, and wire the curated dev toolchain for this project. Detects
   the JS/TS stack, installs the best-in-class tools as devDependencies (Biome for

package/framework/.claude/skills/ui-design/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — ui-design
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/ui-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ui-design
 effort: medium
+version: 1.0.0
 description: "UI design workflow. Generates context-aware mockups with GAN-inspired generator/evaluator separation, visual verification via Playwright, and structured sprint contracts. Use when: (1) designing new pages or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning existing pages, (4) creating design options for user review, (5) any task involving 'design UI', 'mockup', 'opzioni di design', 'progetta interfaccia', '3 opzioni', 'design page', 'UI design'. Not for: bug fixes, small tweaks, copy-only changes, or implementing an already-chosen design."
 ---
 

package/framework/.claude/skills/ui-implement/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog — ui-implement
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Skill introdotta (framework v4.82.0). Estrae da `/new` il playbook mockup→code
+  (claude-design-link / build-from-code / load-image / read-html) e la self-verifica di
+  fidelity, come skill dedicata richiamabile da `/new` e in forma indipendente.
+- Orchestratore thin: cita `design-system-protocol.md`, `ui-expert.md`,
+  `/e2e-review` e la verifier-trio; nessun rule duplicato (no dual-SSOT).
+- Scope = **solo fidelity**: code-quality/doc/QA/ownership restano a `/new`.

package/framework/.claude/skills/ui-implement/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: ui-implement
+effort: medium
+version: 1.0.0
+description: >
+  Implement an ALREADY-APPROVED mockup into the codebase end-to-end and
+  self-verify its fidelity. Takes a mockup in any channel — a Claude Design
+  handoff link (pulled to source via DesignSync), finished source code
+  (mockups/_src/), a rendered image (PNG/JPG/WEBP/PDF), or an HTML file — picks
+  the matching build workflow (the playbook),
+  builds reuse-first via the ui-expert agent, then auto-verifies fidelity
+  (structural + visual + design-quality) via /e2e-review. The single SSOT of the
+  mockup→code implement+verify playbook: /new delegates a UI card's
+  implement+fidelity here; usable standalone on a mockup path or a CARD-ID. A THIN
+  orchestrator that cites design-system-protocol.md, ui-expert.md and /e2e-review,
+  never duplicating them — NOT /ui-design (which generates mockup options) and NOT
+  the ui-expert agent (which builds). Use when the user says /ui-implement,
+  "implementa il mockup", "costruisci lo schermo dal design", "build from mockup",
+  "porta il mockup a codice". Gated on features.has_design_system.
+---
+
+# UI Implement — mockup → code, built and verified
+
+The fix for the recurring "the build isn't 1:1 with the mockup" failure, lifted
+out of `/new` into one specialized, self-verifying skill. A mockup is not one
+thing: a **Claude Design link** resolves to **finished code speaking the
+project's own tokens**, an image is pixels, an HTML file is markup, an archived
+source tree is code already on disk. Each demands a **different build workflow**,
+and choosing the wrong one is
+the #1 fidelity failure. This skill dispatches on the input, builds reuse-first,
+and proves the result before declaring done.
+
+It is a conductor: every rule (the registry cascade, the token contract, the
+build-from-code behaviour, the fidelity taxonomy, the coherence check) lives in
+an existing SSOT and is CITED here, never re-described — re-describing it is how
+it drifts.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`,
+`paths.components_primitives`, `paths.app_dir`, `paths.ui_guidelines`,
+`paths.prd_dir`, `stack.framework`, `stack.animation`, `identity.*`,
+`features.has_design_system`, `features.has_e2e_review`, `features.has_i18n`,
+`features.e2e_review.*`.
+
+**Writes:** UI source under `${paths.app_dir}` / `${paths.components_primitives}`
+(via the `ui-expert` agent) + the design-system reconciliation those changes
+require (INDEX / component spec / tokens — delegated to `/ds-new` / `/ds-edit`).
+The self-verify artifacts land under `.baldart/e2e-review/<id>/`.
+
+**Gated by features:** `features.has_design_system` (BLOCKING — the registry
+cascade + reconciliation need a registry; when `false`, REFUSE and recommend
+`/design-system-init`). `features.has_e2e_review` gates the self-verify step —
+when `false`, the fidelity verify DEGRADES to a compliance-only check (log the
+gap), it does not abort.
+
+**Overlay:** loads `.baldart/overlays/ui-implement.md` if present (brand build
+conventions, mandated component-mapping rules, project fidelity tolerances).
+
+**On missing/empty keys:** ask the user; do not assume defaults. See
+`framework/agents/project-context.md` § 3.
+
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+## Invocation
+
+`/ui-implement <mockup-path-or-CARD-ID>` (standalone) · `/ui-implement` (ask for
+the mockup). When called by `/new` for a UI card, the caller passes the
+**programmatic** context (card path + `worktree_path` + `mode: "programmatic"`) —
+see [references/integration.md](references/integration.md). The mode only changes
+where the mockup + scope come from (Step 1); Steps 2–8 are identical.
+
+## Pre-flight
+
+- **P0 — gate.** `features.has_design_system: false` → REFUSE + suggest
+  `/design-system-init`. (DELEGATE `design-system-protocol.md` § Gating.)
+- **P1 — mode.** *Programmatic* (a `/new` card + worktree path was passed) vs
+  *standalone* (`/ui-implement <args>`). Programmatic returns COMPACT JSON;
+  standalone narrates + returns the same verdict inline.
+- **P2 — resolve the mockup + scope.** *Programmatic* → read the card's
+  `links.design` / `links.design_src` / `component_bindings` and its
+  `files_likely_touched` (do NOT re-derive). *Standalone* → the arg is usually a
+  **Claude Design handoff link** (channel 1 — resolve it per the playbook), else a
+  local mockup path or a `CARD-ID`; on ambiguity, ONE `AskUserQuestion`. **No
+  mockup resolvable → REFUSE** (this skill implements a GIVEN design; generating
+  one is `/ui-design`).
+
+---
+
+## Workflow
+
+Each step is a delegation. Read the cited SSOT; do not paraphrase it.
+
+1. **Detect input type & pick the build workflow.** DELEGATE →
+   [references/playbook.md](references/playbook.md): the dispatch table maps the
+   mockup channel (Claude Design link / finished code / image / HTML) to its build workflow
+   and its verifier lane. Record the chosen workflow in the tracker — it drives
+   Steps 4–7.
+
+2. **Registry-first BLOCKING pre-work.** Before any UI code, complete the
+   registry-first cascade — CITE `framework/agents/design-system-protocol.md`
+   § "Authoritative Style Reference / Registry-First Protocol" and
+   `ui-expert.md` (read INDEX + Authority Matrix, `ui_guidelines`,
+   `tokens-reference.md`, per-primitive specs in scope, per-pattern docs, and the
+   Selection Policy closed families). Do NOT re-describe the 6 steps — they are
+   the agent's SSOT and are reproduced in the briefing (Step 4).
+
+3. **Component reconciliation.** When the card carries `component_bindings` (the
+   `/prd` Component Reconciliation map — `agents/card-schema.md`), THAT map is
+   authoritative over *which component each region is*; honor it over any contrary
+   reading of the mockup. No bindings (standalone / bindings absent) → run the
+   reuse-first cascade as your own reconciliation (CITE `design-system-protocol.md`
+   § Component Discovery Cascade + Closed-Set Selection Policy). A genuinely-new
+   member of a closed family is a governance decision — STOP and surface it, don't
+   self-approve.
+
+4. **Implement — spawn `ui-expert`.** Build via the `ui-expert` agent with a
+   briefing that carries: the chosen build workflow (Step 1), the mockup path(s),
+   the registry-first cascade declaration requirement, the design-source
+   declaration requirement (when code-src exists), the `component_bindings`, and
+   the i18n / states-taxonomy / token-cascade constraints. All of these are
+   `ui-expert.md`'s own contracts — the briefing points at them; it does not
+   re-teach them. (Codex / no-subagents → the skill performs the build inline
+   following the same `ui-expert.md` contracts.)
+
+5. **Ground the design-source declaration** *(only when the card has
+   `links.design_src` / `mockups/_src/` exists)*. After the agent's first
+   response, verify every cited source symbol/class exists in `mockups/_src/`
+   (`grep -rF`) and every cited registry primitive exists in the registry
+   (`INDEX.md` / `components/`). A hollow or fabricated declaration → REJECT +
+   re-spawn. Log `design-source: grounded` | `rejected (<reason>)`. (This is the
+   Step 7b grounding lifted out of `/new`.)
+
+6. **Post-Intervention Coherence Check (BLOCKING).** Reconcile the design-system
+   sources in the SAME change — CITE `design-system-protocol.md`
+   § "Post-Intervention Coherence Check": INDEX (`DS_INDEX_DRIFT`), component spec
+   (`DS_COMPONENT_STALE` — a NEW primitive follows `/ds-new`, a MODIFIED one
+   follows `/ds-edit`, never a hand-written HEAD), tokens (`DS_TOKENS_DRIFT`), and
+   the `DS_MIRROR_STALE` advisory when a Claude Design satellite is bound. Emit the
+   `design_system_coherence:` block in the completion report.
+
+7. **Self-verify fidelity — invoke `/e2e-review`.** With `features.has_e2e_review:
+   true`, invoke `/e2e-review` in **programmatic mode** (payload +
+   contract: [references/integration.md](references/integration.md)). It runs the
+   fidelity trio — structural (`markup-fidelity-verifier`, route-free) + visual
+   (`visual-fidelity-verifier`) + design-quality (`ui-quality-critic`) — plus the
+   functional E2E lane when routes exist, aggregates under the severity gate, and
+   runs its OWN bounded self-heal loop (routing UI-presentation fixes to
+   `ui-expert`, functional to `coder`). The gate, tolerance and self-heal all live
+   INSIDE `/e2e-review` — this skill never re-implements them. It reuses
+   `features.e2e_review.*` from config (do NOT pass `tolerance` /
+   `max_self_heal_iterations` in the payload). **Standalone with no card**, or
+   `has_e2e_review: false`: DEGRADE — spawn the verifier trio directly per
+   `design-system-protocol.md` § "Route-Independent Fidelity & Coverage
+   Obligation" against the built files + the mockup, and gate on the same canonical
+   severity taxonomy.
+
+8. **Return the verdict.** COMPACT (see Return Contract). *Programmatic* → return
+   the JSON contract to `/new`. *Standalone* → narrate the verdict + findings +
+   report path; on `blocked`, surface the gating findings and stop (do not
+   silently ship a non-faithful build).
+
+---
+
+## Scope boundary — fidelity only
+
+This skill OWNS implement + **fidelity** verification (structural + visual +
+design-quality). It does **NOT** own code-quality review (Simplify / Codex),
+doc-review, QA (`qa-sentinel`), or ownership-gated AC closure — those remain the
+caller's (`/new`'s) responsibility for a mixed UI+logic card. For a **pure-graphics**
+card `/new` already skips Simplify/Codex/QA (the fidelity trio IS the review), so
+this skill owns that card's whole implement+verify. See
+[references/integration.md](references/integration.md) § "What /new keeps".
+
+## Inline fallbacks (portability + fail-safe)
+
+- **No `has_e2e_review`:** Step 7 DEGRADE branch (verifier trio direct) — never
+  abort.
+- **Codex (no subagents):** Step 4 builds inline; Step 7 degrades to the direct
+  verifier path or a compliance-only check. Runs end-to-end.
+- **Claude Design link but no DesignSync MCP / not authed:** channel 1 degrades —
+  ask the user to `/design-login`, or to hand over a download-as-`.zip` (→ channel
+  2) or the offline HTML export (→ channel 3). Never guess the design from the URL.
+- **Image-only mockup on a non-multimodal tool:** the `Read` of the image degrades
+  to a no-op; fall back to the card's structured fields (`component_bindings`,
+  responsive ACs) + compliance-only fidelity. Log the degradation.
+- **No mockup at all:** REFUSE (standalone) — this skill implements a GIVEN design.
+
+## /new integration
+
+`/new` OWNS the batch (worktree, ordering, code-quality/doc/QA/ownership); this
+skill OWNS a UI card's mockup→code implement + fidelity verify. `/new` delegates a
+UI card (with `links.design` / `links.design_src`) here in programmatic mode and
+consumes the COMPACT JSON — replacing its inline Design-Reference build + Phase 2.6
+e2e-review for that card. If this skill is unavailable (Codex without it linked / an
+older install), `/new` falls back to an inline **coarse** build brief + a direct
+`/e2e-review` invocation and says so — the prose stays SSOT, delegate-or-else-inline
+(the same opt-in contract as `/prd` → `/ds-handoff`). Full contract:
+[references/integration.md](references/integration.md).
+
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message is bounded — verdict
+(`passed | blocked | overridden | skipped | error`) + the chosen build workflow +
+key findings as `path:line` + `Report: <path>`. Persist the long form (the
+`/e2e-review` report + tracker), return the short form. FULL narrative only when the
+user invoked you directly. Schema + persist-then-summarize rule:
+`framework/agents/return-contract-protocol.md`.
+
+## See Also
+
+- `framework/agents/design-system-protocol.md` — the registry cascade, token
+  contract, Post-Intervention Coherence Check, Closed-Set Selection Policy,
+  Route-Independent Fidelity & Coverage Obligation, and the canonical fidelity
+  severity taxonomy this skill gates on.
+- `framework/.claude/agents/ui-expert.md` — the implementer this skill spawns;
+  § "Design Reference — When the mockup is finished CODE" is the build-from-code
+  SSOT the playbook points at.
+- `framework/.claude/skills/e2e-review/SKILL.md` — the self-verify orchestrator
+  (Phase 2.7 structural, Phase 4 visual, Phase 4b quality, Phase 5 gate, Phase 5b
+  self-heal).
+- `framework/.claude/agents/visual-fidelity-verifier.md` /
+  `markup-fidelity-verifier.md` / `ui-quality-critic.md` — the verifier trio.
+- `framework/.claude/skills/prd/references/discovery-phase.md` § 1.6.4 — the Claude
+  Design handoff pull (DesignSync MCP → `mockups/_src/`) the channel-1 build reuses.
+- `framework/scripts/extract-mockup-design.mjs` — the offline Claude Design bundle
+  decoder the HTML branch of the playbook uses.
+- `framework/.claude/skills/ds-new/SKILL.md` / `ds-edit` — canonical create/edit
+  for a genuinely-new or modified primitive surfaced during the build.

package/framework/.claude/skills/ui-implement/references/integration.md

@@ -0,0 +1,92 @@
+# Integration — how `/ui-implement` is called
+
+This skill has two call sites: a human (standalone) and `/new` (programmatic
+delegation for a UI card). The workflow (Steps 1–8 of `SKILL.md`) is identical;
+only the input source and the return shape differ.
+
+## Invocation contract (programmatic mode)
+
+`/new` invokes the skill with the same payload SHAPE it already uses for
+`/e2e-review`, so the delegation drops into the existing orchestration:
+
+```json
+{
+  "card_id": "<CARD-ID>",
+  "worktree_path": "<absolute worktree path>",
+  "mockup_path": "<optional — standalone override when there is no card>",
+  "mode": "programmatic"
+}
+```
+
+- `card_id` present → the skill reads the card YAML for `links.design`,
+  `links.design_src`, `component_bindings`, `files_likely_touched`, responsive ACs.
+- `mockup_path` (no card) → standalone-ish programmatic run: the skill resolves the
+  mockup from the path and derives scope from the built/changed files.
+- Do NOT pass `tolerance` / `max_self_heal_iterations` — the internal `/e2e-review`
+  call reads those from `features.e2e_review.*` itself (dead keys otherwise).
+
+## Return contract (COMPACT JSON)
+
+```json
+{
+  "status": "passed" | "blocked" | "overridden" | "skipped" | "error",
+  "build_workflow": "build-from-code" | "read-html" | "load-image" | "compliance-only",
+  "findings": [ /* gating findings, canonical severity taxonomy */ ],
+  "ds_drift_codes": [ "DS_INDEX_DRIFT" | "DS_COMPONENT_STALE" | "DS_TOKENS_DRIFT" ],
+  "design_system_coherence": { /* INDEX / components / tokens / mirror reconciled */ },
+  "report_path": ".baldart/e2e-review/<id>/report.json"
+}
+```
+
+`status` semantics mirror `/e2e-review` exactly (`review-cycle.md` § Phase 2.6
+gating table), so `/new`'s existing gating logic consumes them unchanged:
+`passed`/`skipped`/`overridden` → proceed; `blocked` → STOP the card (AUTONOMOUS:
+follow-up card); `error` → capped retry.
+
+## Where `/new` delegates
+
+For a UI card with `links.design` / `links.design_src`, the delegation **replaces
+two inline `/new` steps for that card**:
+
+1. **Phase 2 Design-Reference build** (`implement.md` — the mockup-specific brief +
+   design-source declaration + Step 7b grounding). The `ui-implement` skill now
+   owns this; `implement.md` keeps only a thin pointer + a coarse fallback.
+2. **Phase 2.6 `/e2e-review`** (`review-cycle.md`). Folded into Step 7 of this
+   skill — `/new` does NOT invoke `/e2e-review` separately for a delegated card
+   (the skill already ran it; re-invoking would double the fidelity pass).
+
+## What `/new` KEEPS (fidelity-only scope)
+
+The skill's self-verify covers **fidelity only**. `/new` retains, for a **mixed
+UI+logic** card, everything else in its per-card cluster:
+
+- Phase 2.55 **Simplify** (code quality) · Phase 3.5 **QA** (`qa-sentinel`) ·
+  Phase 3.7 **Codex** review · Phase 3 **doc-review** · Phase 2.5b **AC-Closure** /
+  ownership-gated deferrals.
+
+For a **pure-graphics** card (`owner_agent: ui-expert` + `review_profile: light` +
+`areas == [ui]` + zero high-risk triggers), `/new` already SKIPS Simplify/Codex/QA
+(the fidelity trio IS the review — `review-cycle.md:119`). So for that card the
+skill owns the whole implement+verify, and `/new` only adds doc-review + commit.
+
+This is the answer to "does self-verify make `/new`'s review redundant?": it
+short-circuits the **fidelity** pass only; it never removes code-quality / doc / QA
+/ ownership for a mixed card — no review hole.
+
+## Coarse inline fallback (portability)
+
+When the skill is unavailable (Codex without it linked, an older install, no
+`Workflow`/skill routing), `/new` falls back to its inline **coarse** path: the
+`ui-expert` briefing reproduces the Design-Reference + registry cascade prose, and
+`/new` invokes `/e2e-review` directly at Phase 2.6. The `implement.md` /
+`review-cycle.md` prose remains the SSOT fallback — delegate-or-else-inline, the
+same opt-in contract as `/prd` → `/ds-handoff`.
+
+## `new2` (workflow) note
+
+`new2.js` hosts the batch in a background workflow and reads `implement.md` /
+`review-cycle.md` for the per-card semantics. In this release `new2` keeps its
+**inline** implement+verify path (the fallback prose stays valid), so no `new2.js`
+change is required. Full `new2` parity — delegating the UI card's implement+verify
+off-context via `workflow()` — is a follow-up, to be taken after the context-economy
+measurement (`SKILL.md` scope note + the plan's measure-first gate).

package/framework/.claude/skills/ui-implement/references/playbook.md

@@ -0,0 +1,71 @@
+# Playbook — input type → build workflow
+
+The SSOT of *which build strategy to take*. Detect the mockup channel FIRST
+(Step 1 of `SKILL.md`), then follow the matching row. A card may present more than
+one channel (e.g. `links.design_src` **and** a PNG preview) — the priority order
+below resolves it: **finished code wins**, the image is then a secondary
+cross-check, never the source of truth.
+
+## Detection order (highest-priority match wins)
+
+1. **Claude Design link** (the primary standalone channel) — the arg is a Claude
+   Design handoff URL. Resolve it via the **DesignSync MCP** (interactive auth —
+   `/design-login`): pull the screen's finished source (`.jsx` / `.css` / tokens)
+   READ-ONLY into `mockups/_src/`, then treat it as channel 2 (build-from-code).
+   The pull mechanism is the SAME one `/prd`'s Mockup Intake uses
+   (`prd/references/discovery-phase.md` § 1.6.4) — cite it, do not reinvent it.
+   MCP unreachable / not authed → DEGRADE: ask the user for a download-as-`.zip`
+   (raw `.jsx`/`.css` → channel 2) or the offline single-file HTML export (→
+   channel 3). This is the channel to expect for standalone runs.
+2. **Finished source code already on disk** — the card has `links.design_src`, OR
+   `mockups/_src/` holds `.jsx` / `.tsx` / `.css` / token files (a Claude Design
+   handoff or `.zip` already pulled at `/prd` time). This is what a `/new`-delegated
+   card sees — the `/prd` pull already ran, so no MCP round-trip here.
+3. **HTML file** — `links.design` (or the resolved arg) is an `.html` file.
+4. **Image** — `links.design` resolves to `.png` / `.jpg` / `.jpeg` / `.webp` /
+   `.pdf`, or a `mockups/*.png` canonical path.
+5. **None** — no mockup resolvable → REFUSE (standalone) / DEGRADE to
+   compliance-only (programmatic, no `links.design`).
+
+> **No Figma.** This project never uses Figma — there is deliberately no Figma
+> channel. A design arrives as a **Claude Design link** (channel 1, the usual
+> case), or as the code/HTML/image it was exported to.
+
+## Dispatch table
+
+| Channel (priority) | Build workflow | Fidelity target | Verifier lane | Cited SSOT |
+|---|---|---|---|---|
+| **1. Claude Design link** (handoff URL) | **resolve → build-from-code**: pull the screen's finished `.jsx`/`.css`/tokens via the DesignSync MCP (`/design-login`) READ-ONLY into `mockups/_src/`, then build from that source exactly as channel 2. The export speaks the project's own token language → near-1:1 reuse, not a redesign. MCP unavailable → degrade to a download-as-`.zip` (→ ch.2) or the offline HTML export (→ ch.3). | The **pulled source code** | **structural** (`markup-fidelity-verifier`, route-free) + design-quality | `prd/references/discovery-phase.md` § 1.6.4 (the pull); `ui-expert.md` § "finished CODE" |
+| **2. Finished code on disk** (`links.design_src` / `mockups/_src/`) | **build-from-code** (v4.75). `Read` the source. **Reuse-first**: map the source's token refs / classes (`--space-lg`, `.m-card`) to the registry primitives — the source speaks the project's token language, so the mapping is near-1:1, not a redesign. Copy structure / nesting / spacing / radii / `@keyframes` / `@media` **exactly**. A genuinely-new component → port faithfully via `/ds-new` (never a one-off duplicate). **Declare** files read + symbols reused + primitives mapped (grounded at Step 5). | The **source code** (exact written values), not re-interpreted pixels | **structural** (`markup-fidelity-verifier`, route-free) + design-quality | `ui-expert.md` § "finished CODE"; `design-system-protocol.md` § Route-Independent Fidelity |
+| **3. HTML file** (`.html`) | **read-html**: `Read` the file as the visual+structural reference. **If it is a Claude Design offline single-file bundle** (`<script type="__bundler/template">`), decode it first with `node framework/scripts/extract-mockup-design.mjs <file>` → writes readable HTML+CSS to `mockups/_src/`, THEN fall through to channel 2 (build-from-code). A plain `.html` with no bundle → build from its markup/CSS structure directly. | The **markup/CSS structure** | **structural** (`markup-fidelity-verifier`) + visual + design-quality | `implement.md:139-144`; `extract-mockup-design.mjs` |
+| **4. Image** (`.png`/`.jpg`/`.webp`/`.pdf`) | **load-image** (v4.73/74): you are multimodal — **`Read` the image path directly** so it renders into context. The **pixels** are the fidelity target: study layout, spacing, hierarchy, density, color, and every region's relative position. Do NOT build from the filename or a textual guess. (Non-multimodal tool → the `Read` degrades to a no-op; fall back to the card's structured fields.) | The **pixels** | **visual** (`visual-fidelity-verifier`) + design-quality | `implement.md:129-138` |
+| **5. None** | REFUSE (standalone) — generating a design is `/ui-design`. Programmatic with no `links.design` → DEGRADE to compliance-only (registry + tokens, no pixel/structural diff). | — | design-quality only (compliance-only) | `e2e-review` cascade lvl (c/d) |
+
+## Cross-cutting rules (every channel)
+
+- **`component_bindings` override the mockup.** Whatever the pixels/markup suggest,
+  a region bound `action: reuse → <Component>` MUST reuse that component. The
+  binding is authoritative (Step 3 of `SKILL.md`). Only `action: new` (confirmed at
+  `/prd` time) may introduce a component.
+- **Registry-first cascade is BLOCKING for every channel** — the build strategy
+  chooses *how* to reproduce a region; the cascade chooses *which registry
+  primitive* it maps to. Never skip it (Step 2).
+- **Responsive + states come from code, not the still frame.** A single image shows
+  one viewport and one state. `@media` breakpoints and `@keyframes` live in the
+  source CSS (channels 1/3); the card's responsive ACs and `states[]` cover what a
+  flat image cannot (channel 4). Implement them as testable behaviour, not optional
+  polish.
+- **Token-clean always.** Map every source value to a semantic token; a hardcoded
+  hex/shadow/radius/spacing that bypasses the token contract is drift, even if it
+  matches the mockup pixel-for-pixel (`design-system-protocol.md` § Token Contract).
+
+## Verifier lane → what it catches (reference)
+
+| Lane | Agent | Catches | Runs when |
+|---|---|---|---|
+| structural | `markup-fidelity-verifier` | `layout-break` (2-col→1-col), `element-order`, `component-missing/-duplicated`, `token-bypass`, `responsiveness-break` — route-free, before any browser | code-form mockup (channels 1/2/3) |
+| visual | `visual-fidelity-verifier` | perceptual: `color-mismatch`, `typography-*`, `spacing-off-scale`, `shadow/radius-off`, `data-state-mismatch`, `coverage-gap` | image (channel 4), or the rendered build (channels 1/2/3 after render) |
+| design-quality | `ui-quality-critic` | intrinsic quality (10-dimension rubric): hierarchy, rhythm, contrast, density, composition, states, motion, polish, brand | ALWAYS (including no-mockup compliance-only) |
+
+The taxonomy above is CITED from `design-system-protocol.md` / the verifier agents —
+never redefine severities here.

package/framework/.claude/skills/webapp-testing/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — webapp-testing
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/webapp-testing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: webapp-testing
 effort: medium
+version: 1.0.0
 description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
 license: Complete terms in LICENSE.txt
 ---

package/framework/.claude/skills/worktree-manager/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — worktree-manager
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: worktree-manager
 effort: medium
+version: 1.0.0
 description: >
   Manage fully independent git worktrees for parallel coding agents.
   Commands: /nw (new worktree) creates an isolated workspace with its own

package/framework/agents/skills-mapping.md

@@ -191,6 +191,25 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > standalone invocable BALDART skill. Route UI work through `ui-design` /
 > `ui-expert`, not to `ui-ux-pro-max` directly.
 
+### ui-implement
+
+**When to use**:
+
+- Implementing an ALREADY-APPROVED mockup into code + self-verifying its fidelity
+- Any mockup channel: a Claude Design link (pulled to source), finished source code (`mockups/_src/`), image, HTML — no Figma
+- The implementation twin of `ui-design` (which GENERATES the mockup); the SSOT of
+  the mockup→code build playbook that `/new` delegates a UI card to
+
+**Triggers**:
+
+- "/ui-implement"
+- "implementa il mockup" / "costruisci lo schermo dal design" / "build from mockup"
+
+> `ui-implement` OWNS a UI card's implement + **fidelity** verify (it spawns
+> `ui-expert` and folds in `/e2e-review`). It does NOT own code-quality / doc / QA —
+> those stay with `/new` for a mixed card. NOT `/ui-design` (generates) and NOT the
+> `ui-expert` agent (builds). Gated on `features.has_design_system`.
+
 ### motion-design
 
 **When to use**:
@@ -689,3 +708,13 @@ Document how to create custom skills:
 2. Follow skill template format
 3. Document when to use
 4. Add to this mapping file
+
+## Skill Versioning & Canonical Structure
+
+Every BALDART skill is **versioned** (`version:` SemVer in frontmatter, starting at
+`1.0.0`) and ships a per-skill **`CHANGELOG.md`** (a SEPARATE file, so version
+history never burns context when `SKILL.md` loads). The canonical layout is
+`SKILL.md` + `CHANGELOG.md` (required) plus `references/` / `assets/` / `scripts/`
+only when the skill needs them. Bump `version` + add a `CHANGELOG.md` entry in the
+same edit whenever a skill changes. Full convention:
+`framework/.claude/skills/skill-creator/references/skill-structure.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.81.0",
+  "version": "4.82.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"