baldart 5.1.0 → 5.2.0

package/framework/.claude/skills/ui-design/scripts/craft-check.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * craft-check.mjs — deterministic anti-slop / craft gate for ui-design mockups.
+ *
+ * Scans self-contained mockup HTML for the mechanically-checkable subset of
+ * references/anti-slop.md + references/craft-standards.md. Runs identically on
+ * Claude Code and Codex (zero deps, Node >= 18) — it is Gate 0 of Step D.
+ *
+ * Usage:
+ *   node craft-check.mjs <file.html> [more.html ...] [--json] [--strict-palette]
+ *
+ *   --strict-palette  escalate palette-reflex findings (AI-indigo, beige
+ *                     battery, trust gradient) from warn to block. Use in
+ *                     exploration regime; leave off in-context (the project's
+ *                     own brand may legitimately use these families).
+ *
+ * Exit codes: 0 = PASS (no blockers), 1 = FAIL (>=1 blocker), 2 = usage error.
+ *
+ * Rule provenance: distilled from impeccable (Apache-2.0, © Paul Bakaus),
+ * taste-skill (MIT, © Leonxlnx), open-design (Apache-2.0, nexu-io).
+ * Heuristics are conservative: binary rules block, judgment-adjacent rules warn.
+ */
+
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const strictPalette = args.includes('--strict-palette');
+const files = args.filter((a) => !a.startsWith('--'));
+
+if (files.length === 0) {
+  console.error('usage: node craft-check.mjs <file.html> [...] [--json] [--strict-palette]');
+  process.exit(2);
+}
+
+const INDIGO_HEXES = ['#6366f1', '#4f46e5', '#4338ca', '#3730a3', '#8b5cf6', '#7c3aed', '#a855f7'];
+const BEIGE_BG_HEXES = ['#f5f1ea', '#f7f5f1', '#fbf8f1', '#efeae0', '#ece6db', '#faf7f1', '#e8dfcb'];
+const BEIGE_ACCENT_HEXES = ['#b08947', '#b6553a', '#9a2436', '#9c6e2a', '#bc7c3a', '#7d5621'];
+const EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/u;
+
+function lineOf(src, index) {
+  return src.slice(0, index).split('\n').length;
+}
+
+function excerptAt(src, index, len = 80) {
+  const start = Math.max(0, src.lastIndexOf('\n', index) + 1);
+  const end = src.indexOf('\n', index);
+  return src.slice(start, end === -1 ? start + len : Math.min(end, start + len)).trim();
+}
+
+/** Collect matches of a regex as {line, excerpt} evidence (capped). */
+function findAll(src, re, cap = 5) {
+  const out = [];
+  let m;
+  const rex = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+  while ((m = rex.exec(src)) !== null && out.length < cap) {
+    out.push({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) });
+    if (m.index === rex.lastIndex) rex.lastIndex++;
+  }
+  return out;
+}
+
+/** Strip script/style/comments, then tags → visible text (index-preserving via spaces). */
+function visibleText(src) {
+  const blank = (s) => s.replace(/[^\n]/g, ' ');
+  return src
+    .replace(/<script[\s\S]*?<\/script>/gi, blank)
+    .replace(/<style[\s\S]*?<\/style>/gi, blank)
+    .replace(/<!--[\s\S]*?-->/g, blank)
+    .replace(/<[^>]+>/g, blank);
+}
+
+function checkFile(path) {
+  const src = readFileSync(path, 'utf8');
+  const text = visibleText(src);
+  const findings = [];
+  const add = (rule, severity, message, evidence) => {
+    if (evidence.length > 0) findings.push({ rule, severity, message, count: evidence.length, evidence });
+  };
+  const palSev = strictPalette ? 'block' : 'warn';
+
+  // ---- Absolute bans (binary) ------------------------------------------
+  add('em-dash', 'block',
+    'Em-dash (or en-dash separator) in visible copy — zero tolerance (anti-slop.md).',
+    findAll(text, /—|\s–\s/));
+
+  add('filler-copy', 'block',
+    'Filler copy (lorem ipsum / "Feature One") — an empty section is a composition problem.',
+    findAll(text, /lorem ipsum|\bfeature (one|two|three)\b/i));
+
+  add('gradient-text', 'block',
+    'Gradient text (background-clip: text) — decorative, never meaningful.',
+    findAll(src, /background-clip:\s*text|bg-clip-text/i));
+
+  add('scroll-cue', 'block',
+    '"Scroll to explore" cue — they know what scroll is.',
+    findAll(text, /scroll (down )?to (explore|discover|see)/i));
+
+  add('scroll-listener', 'block',
+    'window scroll listener in script — use IntersectionObserver / animation-library scroll values.',
+    findAll(src, /addEventListener\(\s*['"]scroll['"]/));
+
+  if (!/<meta[^>]+name=["']viewport["']/i.test(src)) {
+    findings.push({ rule: 'missing-viewport', severity: 'block', message: 'Missing <meta name="viewport"> — the mockup cannot be judged responsively.', count: 1, evidence: [{ line: 1, excerpt: '<head>' }] });
+  }
+  if (!/<html[^>]+lang=/i.test(src)) {
+    findings.push({ rule: 'missing-lang', severity: 'block', message: 'Missing lang attribute on <html> (identity.language).', count: 1, evidence: [{ line: 1, excerpt: '<html>' }] });
+  }
+
+  // Emoji as icons inside headings/buttons
+  {
+    const ev = [];
+    const rex = /<(h[1-6]|button)\b[^>]*>([\s\S]*?)<\/\1>/gi;
+    let m;
+    while ((m = rex.exec(src)) !== null && ev.length < 5) {
+      const inner = m[2].replace(/<[^>]+>/g, '');
+      if (EMOJI_RE.test(inner)) ev.push({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) });
+    }
+    add('emoji-icons', 'block',
+      'Emoji as feature icons in headings/buttons — use monoline SVG with currentColor.', ev);
+  }
+
+  // ---- Rationed patterns (count-bounded) --------------------------------
+  {
+    const sections = (src.match(/<section\b/gi) || []).length || 1;
+    const eyebrows = findAll(src, /class=["'][^"']*\buppercase\b[^"']*\btracking-/g, 50);
+    const cap = Math.ceil(sections / 3);
+    if (eyebrows.length > cap) {
+      findings.push({
+        rule: 'eyebrow-overuse', severity: 'block',
+        message: `Eyebrow kickers: ${eyebrows.length} for ${sections} section(s) — cap is ceil(sections/3) = ${cap}. Drop them; the headline alone is enough.`,
+        count: eyebrows.length, evidence: eyebrows.slice(0, 5),
+      });
+    }
+  }
+
+  add('numbered-markers', 'warn',
+    'Numbered section markers (01 / 02 · Label) — the eyebrow trope one tier deeper.',
+    findAll(text, /\b0\d\s*[\/·]\s*\S/));
+
+  add('status-dots', 'warn',
+    'Pulsing decorative status dots — zero by default.',
+    findAll(src, /class=["'][^"']*animate-pulse[^"']*["']/));
+
+  add('marquee-overuse', 'warn',
+    'More than one marquee/auto-scroll strip per page.',
+    findAll(src, /marquee|animate-\[?scroll/gi).slice(1));
+
+  // ---- Palette reflexes (warn; block with --strict-palette) -------------
+  add('ai-indigo', palSev,
+    'Default-Tailwind indigo/violet accent — the textbook AI tell (LILA rule).',
+    findAll(src, new RegExp(INDIGO_HEXES.join('|'), 'i')));
+
+  add('beige-battery', palSev,
+    'Premium-consumer beige/brass battery — banned as a default; rotate palette families (design-directions.md).',
+    findAll(src, new RegExp([...BEIGE_BG_HEXES, ...BEIGE_ACCENT_HEXES].join('|'), 'i')));
+
+  add('trust-gradient', palSev,
+    'Two-stop purple→blue/cyan/pink "trust" gradient — a flat surface + intentional type beats it.',
+    findAll(src, /from-(purple|indigo|violet)-\d+[^"']*to-(blue|cyan|pink|fuchsia)-\d+/i));
+
+  // ---- Craft warnings ----------------------------------------------------
+  add('side-stripe', 'warn',
+    'Colored side-stripe accent (border-left/right > 1px) — the canonical AI dashboard tile.',
+    findAll(src, /border-l-[2-8]\b|border-r-[2-8]\b|border-left:\s*[2-9]px\s+solid\s+(?!transparent)/i));
+
+  add('h-screen', 'warn',
+    'h-screen used — prefer min-h-[100dvh] (iOS Safari).',
+    findAll(src, /\bh-screen\b/));
+
+  add('transition-all', 'warn',
+    '`transition: all` — animate transform/opacity explicitly.',
+    findAll(src, /transition:\s*all|\btransition-all\b/i));
+
+  add('br-in-heading', 'warn',
+    '<br> inside a heading — plan font scale with the copy instead of breaking lines manually.',
+    findAll(src, /<h[1-3][^>]*>(?:(?!<\/h[1-3]>)[\s\S])*?<br\s*\/?>/gi));
+
+  add('caps-no-tracking', 'warn',
+    'ALL-CAPS element without letter-spacing — uppercase requires +0.06–0.1em tracking.',
+    findAll(src, /class=["'](?![^"']*tracking-)[^"']*\buppercase\b[^"']*["']/g));
+
+  add('justify-text', 'warn',
+    'Justified text — never text-align: justify in UI.',
+    findAll(src, /text-align:\s*justify|\btext-justify\b/i));
+
+  add('fake-metrics', 'warn',
+    'Fake-perfect metric (99.9%, 10×) — real source, labelled mock, or absent (Jane Doe rule).',
+    findAll(text, /\b99\.9+\s*%|\b10×|\b100\s*%\s+(faster|better)/i));
+
+  // First <img> lazy / dimensionless images (CLS)
+  {
+    const imgs = [...src.matchAll(/<img\b[^>]*>/gi)];
+    if (imgs.length > 0 && /loading=["']lazy["']/i.test(imgs[0][0])) {
+      findings.push({ rule: 'lcp-lazy', severity: 'warn', message: 'First image is loading="lazy" — never lazy-load the LCP candidate.', count: 1, evidence: [{ line: lineOf(src, imgs[0].index), excerpt: excerptAt(src, imgs[0].index) }] });
+    }
+    const dimless = imgs.filter((m) => !/\bwidth=|\baspect-ratio|aspect-\[/i.test(m[0]));
+    add('img-no-dimensions', 'warn',
+      '<img> without width/height or aspect-ratio — reserves no space (CLS).',
+      dimless.slice(0, 5).map((m) => ({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) })));
+  }
+
+  // Token discipline: distinct raw hexes + off-scale arbitrary values
+  {
+    const hexes = new Set((src.match(/#[0-9a-fA-F]{6}\b/g) || []).map((h) => h.toLowerCase()));
+    if (hexes.size > 12) {
+      findings.push({ rule: 'hex-sprawl', severity: 'warn', message: `${hexes.size} distinct raw hex colors — an incomplete palette; consolidate to CSS custom properties.`, count: hexes.size, evidence: [] });
+    }
+    const offScale = [...src.matchAll(/\b(?:[mp][trblxy]?|gap|space-[xy])-\[(\d+)px\]/g)]
+      .filter((m) => Number(m[1]) % 4 !== 0);
+    add('off-scale-spacing', 'warn',
+      'Arbitrary spacing off the base-4 scale (e.g. p-[13px]) — token violation.',
+      offScale.slice(0, 5).map((m) => ({ line: lineOf(src, m.index), excerpt: m[0] })));
+    const sizes = new Set([
+      ...[...src.matchAll(/text-\[(\d+)px\]/g)].map((m) => m[1]),
+      ...[...src.matchAll(/font-size:\s*(\d+)px/gi)].map((m) => m[1]),
+    ]);
+    if (sizes.size > 9) {
+      findings.push({ rule: 'type-scale-sprawl', severity: 'warn', message: `${sizes.size} distinct px font sizes — one scale, 6–9 deliberate steps.`, count: sizes.size, evidence: [] });
+    }
+  }
+
+  const blockers = findings.filter((f) => f.severity === 'block');
+  return { file: path, verdict: blockers.length === 0 ? 'PASS' : 'FAIL', blockers: blockers.length, warnings: findings.length - blockers.length, findings };
+}
+
+const results = files.map((f) => {
+  try {
+    return checkFile(f);
+  } catch (e) {
+    return { file: f, verdict: 'ERROR', error: e.message, findings: [] };
+  }
+});
+
+if (asJson) {
+  console.log(JSON.stringify({ strictPalette, results }, null, 2));
+} else {
+  for (const r of results) {
+    console.log(`\n${r.verdict === 'PASS' ? '✓' : '✗'} ${r.file} — ${r.verdict}` + (r.error ? ` (${r.error})` : ''));
+    for (const f of r.findings || []) {
+      console.log(`  [${f.severity.toUpperCase()}] ${f.rule} ×${f.count}: ${f.message}`);
+      for (const ev of f.evidence.slice(0, 3)) console.log(`      L${ev.line}: ${ev.excerpt}`);
+    }
+  }
+  console.log('');
+}
+
+process.exit(results.some((r) => r.verdict === 'FAIL' || r.verdict === 'ERROR') ? 1 : 0);

package/framework/agents/component-manifest-schema.md

@@ -220,7 +220,7 @@ This keeps consumers that have not yet upgraded (and non-TS stacks) from becomin
 - **Single-element edit**: `/ds-edit` (update one existing component/token —
   resync / extend / breaking / re-govern; regenerates the HEAD from the new source
   via the same scripts, **preserving non-empty agentic fields + prose**).
-- **Per-task write**: `ui-expert` / `ui-design` / `frontend-design` in the
+- **Per-task write**: `ui-expert` / `ui-design` / `ui-implement` in the
   Post-Intervention Coherence Check — a new/modified primitive regenerates its
   HEAD in the same change.
 - **Curation owner**: `doc-reviewer` (agentic fields).

package/framework/agents/design-system-protocol.md

@@ -12,7 +12,7 @@ twofold:
    implementation, so existing primitives are reused instead of duplicated.
 
 This is the textual SSOT for the registry-first protocol. Skills (`ui-design`,
-`frontend-design`, `design-system-init`), agents (`ui-expert`, `code-reviewer`),
+`ui-implement`, `design-system-init`), agents (`ui-expert`, `code-reviewer`),
 and the `/design-review` command all reference this module instead of
 duplicating the BLOCKING-read cascade.
 
@@ -468,7 +468,7 @@ its own — it **proposes, a human confirms**:
 ## Functional Traceability Gate (BLOCKING — unconditional)
 
 A mockup is a fidelity target, **not** a requirements oracle. Design tools
-(Claude Design, Figma, the `ui-design`/`frontend-design` generators) routinely
+(Claude Design, Figma, the `ui-design` generator) routinely
 add interactive-looking chrome — buttons, icons, menu entries, toggles, badges —
 that no requirement asked for. Implementing a mockup **1:1 for fidelity**
 materialises that chrome into real markup + dead handlers + unused icon imports,
@@ -524,7 +524,7 @@ For every **orphan**, never decide silently (consistent with the framework's
 
 ### Where it runs
 
-1. **Design / generation time** (`ui-design`, `frontend-design`, `ui-expert`
+1. **Design / generation time** (`ui-design`, `ui-expert`
    designing) — when producing a mockup, do not invent interactive chrome with
    no backing requirement; mark genuinely decorative elements as such in the
    inventory so the downstream gate is deterministic, not a guess.
@@ -698,7 +698,7 @@ complete** when `features.has_design_system: true` until the registry has
 been verified against the change that was just made.
 
 The check runs at end-of-task by the agent that performed the work (`ui-expert`,
-`ui-design`, `frontend-design`, `code-reviewer`). It is **not** delegated to
+`ui-design`, `code-reviewer`). It is **not** delegated to
 the weekly `ds-drift` routine — that routine is a safety net, not the primary
 mechanism. Drift introduced today must be reconciled today, not next Monday.
 
@@ -820,9 +820,9 @@ The following files reference this module instead of duplicating its rules:
 - `framework/.claude/agents/ui-expert.md`
 - `framework/.claude/agents/code-reviewer.md`
 - `framework/.claude/agents/ui-quality-critic.md` (Design Quality Rubric — the
-  intrinsic-quality critic consumed by `/e2e-review` Phase 4b)
+  intrinsic-quality critic consumed by `/e2e-review` Phase 4b and `/ui-design`
+  Step D)
 - `framework/.claude/skills/ui-design/SKILL.md`
-- `framework/.claude/skills/frontend-design/SKILL.md`
 - `framework/.claude/skills/design-system-init/SKILL.md` (bulk registry bootstrap/upgrade)
 - `framework/.claude/skills/ds-new/SKILL.md` (single-element guided creation)
 - `framework/.claude/skills/ds-edit/SKILL.md` (single-element guided edit — resync / extend / breaking / re-govern)

package/framework/agents/index.md

@@ -20,6 +20,7 @@ Route agents to the right module with minimal reading.
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
 - If touching ANY visual surface (component, page, mockup, design review) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` and treat the BLOCKING cascade (`${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md`) as mandatory pre-work. When the flag is `false`, recommend `/design-system-init` to scaffold a registry.
+- If the task is a DESIGN DECISION (new page/screen/component to design, redesign/restyle, design options to explore, a local prototype/mockup) -> route to the `/ui-design` skill (the local design studio: Design Read & direction lock, deterministic craft gate, dual-lens evaluation). An ALREADY-APPROVED mockup to implement routes to `/ui-implement`; a direct in-code UI change with no design decision delegates to the `ui-expert` agent (`AGENTS.md` § delegation). NEVER route design work to `frontend-design` (a router since v5.2.0) or `ui-ux-pro-max` (superseded by `ui-design/references/`).
 - If a UI change might INTRODUCE a component (designing from a mockup, building a new primitive) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` § "Closed-Set Selection Policy": query the registry by ROLE (`INDEX.md` § Selection Policy), reuse the canonical member of any `closed` family, honor the card's `component_bindings`, and run `baldart ds-gate` (a `DS_CLOSED_SET_VIOLATION` — a new canonical in a closed family, the "third header" failure mode — BLOCKS). A new member of a closed family is a governance decision (`/prd` reconciliation + ADR), never an implementation act.
 - If creating ONE new canonical design-system element on-the-fly (a component or a token) and `features.has_design_system: true` -> use the `/ds-new` skill (reuse-first → optional scaffold via `ui-expert` → document + register + govern + verify); it produces the standardized spec by filling `framework/templates/component-spec.template.md` via the serializer, never hand-writing a HEAD. The bulk analogue (whole registry) is `/design-system-init`.
 - If EDITING one existing design-system element (add a variant/prop, breaking change, re-govern, or resync the spec) and `features.has_design_system: true` -> use the `/ds-edit` skill (classify the change → apply source via `ui-expert` → regenerate the spec via the serializer, PRESERVING agentic fields + prose, same canonical template as `/ds-new` → verify). The pure mechanical doc-resync after a code change is already automatic (serializer + `DS_COMPONENT_STALE` gate); `/ds-edit` is for the deliberate change.

package/framework/agents/skills-mapping.md

@@ -191,38 +191,38 @@ competing methodology — it detects the task type and passes the matching
 
 ## UI/UX Skills
 
-### frontend-design
-
-**When to use**:
-
-- Building UI components
-- Creating pages
-- Styling work
-
-**Triggers**:
-
-- "Create [page]"
-- "Build [component]"
-- "Design [interface]"
+> **UI routing rule (since v5.2.0).** ALL design-decision work routes to
+> `ui-design` (the local design studio). `frontend-design` is a RETIRED
+> generator kept as a router: its broad triggers still land there, but its
+> body immediately reroutes (design → `/ui-design`, approved mockup → code →
+> `/ui-implement`, direct in-code UI → `ui-expert` agent per `AGENTS.md`
+> § delegation). Never follow pre-v5.2.0 `frontend-design` design guidance.
+> `ui-ux-pro-max` is superseded by `ui-design/references/`
+> (design-directions / craft-standards / anti-slop) — never route to it.
 
 ### ui-design
 
 **When to use**:
 
-- Designing new pages or components (context-aware mockups)
-- The `/prd` skill reaches its UI design phase
-- Redesigning existing pages / creating design options for review
+- Designing, prototyping or restyling ANY page/screen/component locally —
+  the internal twin of the Claude Design handoff
+- The `/prd` skill reaches its UI design phase (Step 3)
+- Redesigning existing pages / exploring design options or aesthetic
+  directions for review
 
 **Triggers**:
 
 - "/ui-design"
-- "Design UI" / "mockup" / "opzioni di design"
-- Design-heavy features, visual refinement, design-system work
+- "Design UI" / "mockup" / "prototipo" / "opzioni di design" / "restyle" /
+  "rifai la UI" / "migliora il design" / "progetta interfaccia"
+- Design-heavy features, visual refinement, greenfield landing/dashboard work
+
+### frontend-design (router — retired generator)
 
-> `ui-ux-pro-max` is a **tool used inside** the `ui-expert` agent / `ui-design`
-> skill (see REGISTRY.md — listed as a Key Tool of `ui-expert`), not a
-> standalone invocable BALDART skill. Route UI work through `ui-design` /
-> `ui-expert`, not to `ui-ux-pro-max` directly.
+**When to use**: never follow it as a workflow. If a trigger lands here
+("create/build/style [page/component/UI]"), apply its routing table:
+design work → `ui-design` · approved mockup → `ui-implement` · in-code UI
+change → `ui-expert` agent · motion → `motion-design`.
 
 ### ui-implement
 
@@ -674,7 +674,9 @@ Is it a bug fix?
   |
   v
 Is it UI/visual work?
-  |-- YES --> /ui-design (mockups/options) or frontend-design;
+  |-- YES --> design decision (new/redesign/restyle/options) → /ui-design;
+  |           approved mockup → code → /ui-implement;
+  |           direct in-code UI change → ui-expert agent (AGENTS.md § delegation);
   |           motion → /motion-design
   |
   v

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -94,8 +94,8 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 
 | Key | Typical value | Used by |
 |---|---|---|
-| `design_system` | `docs/design-system` | ui-design, frontend-design, prd, bug, kie-ai, simplify, playwright-skill, webapp-testing, gamification-design |
-| `ui_guidelines` | `docs/references/ui-guidelines.md` | ui-design, frontend-design, copywriting, gamification-design |
+| `design_system` | `docs/design-system` | ui-design, ui-implement, prd, bug, kie-ai, simplify, playwright-skill, webapp-testing, gamification-design |
+| `ui_guidelines` | `docs/references/ui-guidelines.md` | ui-design, copywriting, gamification-design |
 | `api_index` | `docs/references/api/index.md` | doc-writing-for-rag |
 | `api_schemas` | `docs/references/api/schemas.md` | doc-writing-for-rag |
 | `api_errors` | `docs/references/errors.md` | doc-writing-for-rag |
@@ -157,7 +157,7 @@ Lifecycle:
 | Key | Type | Notes |
 |---|---|---|
 | `brand_name` | string | Public product name |
-| `design_philosophy` | string | Free-form, one line. Examples: `"Neo-Brutalism"`, `"Glassmorphism"`, `"Minimalist"`, `"Material 3"`, `""` (no opinion). Drives aesthetic decisions in `ui-design`, `frontend-design`, `kie-ai`, `motion-design`. |
+| `design_philosophy` | string | Free-form, one line. Examples: `"Neo-Brutalism"`, `"Glassmorphism"`, `"Minimalist"`, `"Material 3"`, `""` (no opinion). Drives aesthetic decisions in `ui-design`, `kie-ai`, `motion-design`. |
 | `language` | BCP-47 tag | `"en"`, `"it"`, etc. Drives copy register in `copywriting`, error-message language in `ui-design`. |
 | `audience_segments` | array of strings | Domain split, e.g. `["merchant","customer"]` or `["b2b","b2c"]`. Empty `[]` = no segmentation. Drives prompts in `copywriting`, evaluation in `ui-design`. |
 
@@ -257,7 +257,7 @@ Every flag MUST be present as `true` or `false` once `baldart configure` has run
 
 | Flag | Meaning |
 |---|---|
-| `has_design_system` | The project has docs rooted at `paths.design_system`. When `true`, `ui-design`, `bug`, `frontend-design`, `simplify`, `playwright-skill` etc. treat the INDEX as BLOCKING. |
+| `has_design_system` | The project has docs rooted at `paths.design_system`. When `true`, `ui-design`, `ui-implement`, `bug`, `simplify`, `playwright-skill` etc. treat the INDEX as BLOCKING. |
 | `multi_tenant_theming` | The project supports per-tenant theme overrides. Activates themed-surface text/bg pairing rules in `ui-design`, `playwright-skill`, `webapp-testing`. |
 | `has_api_docs` | Canonical API docs at `paths.api_index`. Gates `doc-writing-for-rag` schemas/errors workflow. |
 | `has_backlog` | Card-driven workflow (`paths.backlog_dir` + AGENTS.md card protocol). `new` skill refuses to run without it. |
@@ -337,7 +337,7 @@ These skills had heavy hard-coding before v3.0.0; if your project has opinions i
 |---|---|
 | `ui-design` | Design philosophy mandates, theming pairing rules, charting wrappers, browser open command, evaluation thresholds |
 | `copywriting` | Brand voice pillars, audience register matrix, forbidden vocabulary, language-only rules |
-| `frontend-design` | Aesthetic mandates, illustration-motion contract |
+| `frontend-design` | (retired to a router since v5.2.0 — port aesthetic mandates / illustration-motion contract to the `ui-design` overlay) |
 | `prd` / `prd-add` | Project terminology, mandatory review gates, design-system reads for UI PRDs |
 | `kie-ai` | Illustration character library, video-prompt motion vocabulary, forbidden aesthetics |
 | `bug` | Project debug entry points (env summary helper, cache debug switch, error-code module) |

package/package.json

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

package/src/commands/configure.js

@@ -790,7 +790,7 @@ async function interactivePrompts(merged, detected) {
       '  /design-system-init  (or invoke the skill)\n' +
       'to scaffold INDEX.md + tokens-reference.md + per-component specs at\n' +
       'docs/design-system/. The registry-first protocol (ui-expert, ui-design,\n' +
-      'frontend-design, /design-review) needs these files to enforce coherence.'
+      'ui-implement, /design-review) needs these files to enforce coherence.'
     );
   } else if (merged.features.has_design_system === false) {
     UI.info(

package/src/utils/__tests__/classify-divergence.test.js

@@ -290,5 +290,47 @@ console.log('\n─── overlayCoversTouched (fs-backed) ───');
   fsMod.rmSync(tmp, { recursive: true, force: true });
 }
 
+// absorbablePayloadSubset(touched) — pure. The subset whose byte-content must
+// match upstream for a commit to be "absorbed". Consumer files (outside
+// `.framework/`) and subtree bookkeeping (VERSION/CHANGELOG/README) are
+// EXCLUDED. Fixtures reproduce the exact mayo v5.0.1→v5.1.0 divergence that
+// falsely blocked the update pre-v5.1.1 (mixed FEAT commits + add-then-revert
+// pairs touching VERSION/CHANGELOG).
+console.log('\n─── absorbablePayloadSubset (pure) ───');
+{
+  const cases = [
+    { name: 'mixed FEAT commit: framework doc + app files → only the doc survives',
+      touched: ['.framework/framework/agents/design-system-protocol.md',
+                'backlog/FEAT-0054-03-enforcement.yml',
+                'docs/references/ssot-registry.md'],
+      expected: ['.framework/framework/agents/design-system-protocol.md'] },
+    { name: 'mixed FEAT commit: framework doc + CLAUDE.md + eslint config → only the doc',
+      touched: ['.framework/framework/agents/design-system-protocol.md',
+                'CLAUDE.md', 'eslint.responsive.config.mjs'],
+      expected: ['.framework/framework/agents/design-system-protocol.md'] },
+    { name: 'bookkeeping-only touch (VERSION/CHANGELOG/README) → empty subset',
+      touched: ['.framework/VERSION', '.framework/CHANGELOG.md', '.framework/README.md'],
+      expected: [] },
+    { name: 'revert commit: bookkeeping + payload scripts → only the scripts survive',
+      touched: ['.framework/CHANGELOG.md', '.framework/README.md', '.framework/VERSION',
+                '.framework/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs',
+                '.framework/framework/agents/component-manifest-schema.md'],
+      expected: ['.framework/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs',
+                 '.framework/framework/agents/component-manifest-schema.md'] },
+    { name: 'consumer-only files → empty subset',
+      touched: ['src/app/page.tsx', 'README.md'], expected: [] },
+    { name: 'empty touched → empty subset',
+      touched: [], expected: [] },
+    { name: 'null touched → empty subset (no throw)',
+      touched: null, expected: [] },
+  ];
+  for (const c of cases) {
+    const actual = GitUtils.absorbablePayloadSubset(c.touched);
+    const ok = JSON.stringify(actual) === JSON.stringify(c.expected);
+    if (ok) { pass++; console.log(`  ✓ ${c.name}`); }
+    else { fail++; console.log(`  ✗ ${c.name} → ${JSON.stringify(actual)} (expected ${JSON.stringify(c.expected)})`); }
+  }
+}
+
 console.log(`\nResult: ${pass} pass, ${fail} fail`);
 process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -209,10 +209,13 @@ class GitUtils {
   //   - subtree-merge:  `git subtree pull --squash` merge commits
   //   - subtree-squash: the squash payload commits themselves
   //   - chore-wrapper:  CLI-generated [CHORE]/chore(baldart): commits
-  //   - absorbed:       a would-be custom commit whose touched .framework/ files
-  //                     are now byte-identical to upstream (FETCH_HEAD) — the edit
-  //                     has been absorbed into upstream (or reset away), so a
-  //                     re-sync loses nothing. Pure history, not live drift → noise.
+  //   - absorbed:       a would-be custom commit whose touched .framework/ PAYLOAD
+  //                     files are now byte-identical to upstream (FETCH_HEAD) — the
+  //                     edit has been absorbed into upstream (or reset away), so a
+  //                     re-sync loses nothing. Consumer files (outside .framework/)
+  //                     and subtree bookkeeping (VERSION/CHANGELOG/README) are not
+  //                     counted (see absorbablePayloadSubset). Pure history, not
+  //                     live drift → noise.
   //   - custom-overlay-able: user edited a framework agent/skill/command
   //                          → should migrate to .baldart/overlays/
   //   - custom-other:   anything else (src/, CHANGELOG, ad-hoc fixes)
@@ -297,18 +300,51 @@ class GitUtils {
     });
   }
 
-  // True when EVERY touched `.framework/` file's content at HEAD is already
+  // The subset of a commit's touched paths whose byte-content must match
+  // upstream for the commit to count as "absorbed". Two classes of path are
+  // EXCLUDED because they can never conflict in a `.framework/` subtree sync:
+  //   1. Anything outside `.framework/` — the consumer's OWN files. A mixed
+  //      commit that edits both a framework doc and app code (e.g. a FEAT that
+  //      also tweaks a protocol module) is common; the subtree merge never
+  //      touches the app files, so they are irrelevant to whether the commit's
+  //      framework portion is absorbed. (Pre-v5.1.1 the check bailed to
+  //      not-absorbed on the FIRST such path → mixed commits falsely blocked
+  //      the update even when their `.framework/` payload matched upstream.)
+  //   2. Subtree bookkeeping (`.framework/{VERSION,CHANGELOG.md,README.md}`) —
+  //      framework-owned metadata the merge reconciles wholesale, which ALWAYS
+  //      differs across versions (VERSION bumps, CHANGELOG grows). Counting it
+  //      meant any commit touching it (e.g. an add-then-revert pair) could
+  //      never be absorbed. It is never consumer content, so dropping it is
+  //      safe: a hand-edit to it SHOULD be overwritten by upstream anyway.
+  // Pure (no fs / no git) so it stays unit-testable.
+  static absorbablePayloadSubset(touched) {
+    const prefix = `${FRAMEWORK_DIR}/`;
+    const META = new Set([
+      `${prefix}VERSION`,
+      `${prefix}CHANGELOG.md`,
+      `${prefix}README.md`,
+    ]);
+    return (touched || []).filter((p) => p.startsWith(prefix) && !META.has(p));
+  }
+
+  // True when EVERY `.framework/` PAYLOAD file touched by the commit is already
   // byte-identical to the upstream (FETCH_HEAD) blob — i.e. the commit's edit
   // has been fully absorbed into upstream (or reset away) and a re-sync would
   // lose nothing. Compares blob SHAs (cheap, exact). The subtree prefix
   // `.framework/` is stripped to reach the upstream path (FETCH_HEAD has no
-  // `.framework/` prefix). Conservative: any file outside `.framework/`, missing
-  // upstream, or whose SHA differs → not absorbed (real drift, keep flagging).
+  // `.framework/` prefix). The comparison runs over `absorbablePayloadSubset`
+  // ONLY (consumer files + subtree bookkeeping excluded — see there). A commit
+  // whose payload subset is EMPTY (it touched `.framework/` only via bookkeeping
+  // and/or only touched consumer files) carries no subtree drift → absorbed.
+  // Conservative on the payload itself: a file missing at HEAD (deleted) or
+  // missing upstream (net-new), or whose SHA differs → not absorbed (real
+  // drift, keep flagging).
   async isAbsorbedAgainstUpstream(touched) {
     if (!touched || !touched.length) return false;
     const prefix = `${FRAMEWORK_DIR}/`;
-    for (const p of touched) {
-      if (!p.startsWith(prefix)) return false;
+    const payload = GitUtils.absorbablePayloadSubset(touched);
+    if (!payload.length) return true;
+    for (const p of payload) {
       const upstreamPath = p.slice(prefix.length);
       let headSha;
       let upSha;