baldart 4.69.1 → 4.71.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.71.0] - 2026-06-25
+
+**Responsive-awareness in UI review — catch a viewport-scoped edit that regresses the *other* viewport.** When an agent works on one viewport (fix the mobile header, tweak the desktop table), nothing today catches it silently shifting the viewport it was *not* editing. The obvious fix — cloning the i18n ESLint gate into a `responsive-gate` that bans raw `matchMedia`/breakpoint literals — was **refuted** by an adversarial pass: that gate is blind to where responsiveness actually lives (Tailwind `md:` classes, CSS, CSS-in-JS — not `window.matchMedia`), so it is mayo-specific opinion, not a distributable mechanism. The real driver is served by **reactivating machinery that already exists and was inert**: `visual-fidelity-verifier` has had a `responsiveness-break` finding all along, but `/e2e-review` only ever screenshotted **one** viewport (1440px), so it could never fire.
+
+**MINOR** — adds review capability; **no new config key** (rides on `features.has_e2e_review` + `features.has_design_system`), no schema-change propagation. The mobile viewport is fixed at 375px (the canonical small-screen audit width). Degrades to no-op on consumers without e2e-review. The per-route cost was **measured** on a real verifier run before shipping default-on: ~one extra verifier call per renderable route (~0.3% of a card run — the 375px screenshot is lighter than the 1440px one, and only renderable routes incur it).
+
+### Changed
+
+- **`/e2e-review` captures both viewports + runs a mobile responsive-integrity pass** (`framework/.claude/skills/e2e-review/SKILL.md`). Phase 3 now captures `<route-slug>.png` (desktop 1440×900, **unchanged path** — all existing consumers intact) AND `<route-slug>@mobile.png` (375×812), setting the viewport before navigating so SSR/responsive hooks render for that width. Phase 4 adds a second verifier invocation per route with `viewport_role: "mobile"` (step 2b), and the `skip`-level pre-filter no longer suppresses it (the mobile pass needs no mockup). Findings aggregate with `viewport_role` in the dedup key so a mobile `responsiveness-break` stays distinct and the Phase 5 gate / self-heal report show which viewport broke.
+- **`visual-fidelity-verifier` gains a `viewport_role: "mobile"` responsive-integrity mode** (`framework/.claude/agents/visual-fidelity-verifier.md`). When set, it does NOT diff against the (desktop) mockup — the mobile layout reflows by design — and emits ONLY genuine breakage findings (`responsiveness-break`, `unreachable-action`, `layout-break`), conservatively. Reuses the existing taxonomy + output schema; no new finding codes.
+- **`design-system-protocol.md` adds a "Responsive Scope Discipline" section** — the textual SSOT: (1) a viewport-scoped edit MUST NOT alter the other viewport's branch; (2) a structural/heavy component MUST NOT be swapped across viewports via `display:none`/`visibility`/`hidden`/`@media` CSS hiding (mounts both branches, runs both effect/query sets, ships dead DOM). Stated abstractly — concrete primitive names / breakpoints / any project-local gate live in the consumer's own files, never in the framework. Enforced as a **review check** (the CSS-hidden case is invisible to a JS AST rule), not a lint.
+- **`code-reviewer` enforces it** (rule 9) — structural `display:none` swap = HIGH; viewport-scoped edit that mutates the other branch = MEDIUM. **`design-review.md`** checklist points to the same section. This is the surviving, generalized slice of the responsive work; everything stack-specific (a project's `eslint.responsive.config.mjs`, primitive names) stays a consumer-side project file, never in `.framework/`.
+
+## [4.70.0] - 2026-06-25
+
+**`/ds-edit` — the deliberate-edit twin of `/ds-new`, completing the single-element lifecycle.** `/ds-new` creates (its reuse-first step STOPS if the element exists); there was no symmetric guided entry to *change* an existing canonical element. "Update a component" decomposes into three cases — two were already covered: the **mechanical doc-resync** after a code change is automatic (serializer regenerates the HEAD from source, preserving agentic + prose; the BLOCKING `DS_COMPONENT_STALE` gate enforces it), and **agentic re-curation** is `doc-reviewer`'s domain. The gap was the **deliberate change with a decision** — add a variant/prop, a breaking change, or re-governing a closed-set role.
+
+**MINOR** — adds a skill; no new config key (rides on `features.has_design_system`). A pure orchestrator over the same scripts as `/ds-new` — zero rule duplication, and the SAME canonical template (`framework/templates/component-spec.template.md`).
+
+### Added
+
+- **`/ds-edit` skill** (`framework/.claude/skills/ds-edit/SKILL.md`) — update ONE existing canonical component or token. Pre-flight locates the element (refuses + suggests `/ds-new` if it doesn't exist), then classifies the change via the edit decision tree: **resync** (spec catches up to changed source) / **extend** (new variant/prop — within the role contract, else it's a NEW role = `/ds-new`) / **breaking** (removed/renamed variant or prop → migration + spec Changelog) / **re-govern** (the edit changes `canonical_for`/`use_when`/closure). Delegates the source change to `ui-expert`, the agentic re-verify to `doc-reviewer`, and regenerates the spec via the serializer — which **preserves the existing prose + non-empty agentic fields** (`source_sha` anchor) and fills the canonical template only when a spec is missing, so an edited spec keeps the SAME standardized shape as a created one. Verifies via `ds-gate` + `DS_COMPONENT_STALE`. Codex-portable (deterministic spine zero-subagent; agentic/scaffold steps degrade to TODO). Token edits follow the Token Cascade (rename/removal is breaking — migrate the affected `token_bindings`).
+
+### Changed
+
+- **`/prd` routes a REUSE+VARIANT extension to `/ds-edit`** (`ui-design-phase.md`, new step 7b) — when the reconciliation gate finds a region maps to an existing component but needs a variant/prop not yet in its spec and the user confirms extending, route to `/ds-edit` (create-now) or a "modify Component X" card (defer) — symmetric to the NEW→`/ds-new` routing. A "variant" that is really a new role is a `NEW (governed)` case, not an extend.
+- **`/new` (ui-expert Post-Intervention) follows the `/ds-edit` discipline for a MODIFIED primitive** (`implement.md`) — re-run the serializer to regenerate the HEAD from the new source (preserving agentic + prose), never hand-edit; a breaking change adds a spec Changelog entry. Registered in `design-system-protocol.md` (Consumers), `component-manifest-schema.md` (Producers), and `agents/index.md` routing. Propagates to `new2` (shared reference modules).
+
 ## [4.69.1] - 2026-06-24
 
 **`/prd` and `/new` now actually USE `/ds-new` when a new STANDARDIZED component is detected** (v4.69.0 only wired it as an opt-in arm + left `/new`'s spec production unspecified). A new canonical element should be materialized through the one discipline, not hand-rolled per surface.

package/README.md

@@ -211,14 +211,14 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (36 portable skills)
+### Skills (37 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
 - **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
-- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`)
+- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`

package/VERSION

@@ -1 +1 @@
-4.69.1
+4.71.0

package/framework/.claude/agents/code-reviewer.md

@@ -115,6 +115,15 @@ Concrete enforcement contract for the review pass:
    HEAD is NOT `DS_COMPONENT_STALE` merely for that; empty deterministic HEAD
    fields (non-TS stack, unresolved prop) are advisory, never blocking. The HEAD
    is an upgrade target — see `component-manifest-schema.md` § Transition leniency.
+9. **Responsive Scope Discipline** — per [`design-system-protocol.md`](../../agents/design-system-protocol.md)
+   § "Responsive Scope Discipline": (a) a structural/heavy component swapped
+   across viewports via `display:none` / `visibility:hidden` / `hidden` / `@media`
+   CSS hiding (mounts both branches, runs both effect/query sets, ships dead DOM)
+   is **HIGH**; (b) a viewport-scoped edit that also mutates the *other* viewport's
+   branch (e.g. a "mobile only" change that shifts the desktop layout) is
+   **MEDIUM**. Token-level per-breakpoint restyling of a single element is fine —
+   only whole-tree `display:none` swaps trip (a). This is a review judgement, not a
+   lint (the CSS-hidden case is invisible to a JS AST rule).
 
 When `features.has_design_system: false`, the registry reads are skipped but
 the review still flags hardcoded values and inconsistencies against

package/framework/.claude/agents/visual-fidelity-verifier.md

@@ -63,6 +63,7 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
   "card_id": "FEAT-XXXX",
   "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
+  "viewport_role": "desktop" | "mobile",          // optional, default "desktop"
   "implementation_screenshot_path": "/abs/path/to/impl.png",
   "mockup_source": {
     "level": "figma" | "local" | "compliance-only" | "skip",
@@ -81,7 +82,22 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
 ```
 
 If `mockup_source.level == "skip"`, return immediately with
-`{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }`.
+`{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }` —
+**unless** `viewport_role == "mobile"`, in which case run the responsive-integrity
+pass below (it needs no mockup).
+
+**`viewport_role: "mobile"` — responsive-integrity pass.** When set, you are
+looking at the **mobile render** (a narrow viewport, typically 375px). Mobile
+mockups are rarely provided, and the mobile layout *correctly* reflows away from
+any desktop mockup — so in this mode you **do NOT diff against a mockup** and you
+do **NOT** emit fidelity findings (`element-order`, `spacing-off-scale`,
+`typography-*`, `color-*` relative to a desktop design). Evaluate the mobile
+screenshot on its own and flag **only genuine viewport breakage**:
+`responsiveness-break` (horizontal scroll past the viewport, content cut off,
+elements overlapping/unreadable), `unreachable-action` (primary CTA off-screen or
+behind a fixed overlay), and `layout-break` (a container that genuinely collapsed,
+not an intended stack). Be conservative: a dense-but-legible layout is **not** a
+break — flag only hard failures a user would hit. Return the same output schema.
 
 **`resolved_orphans` carve-out (Functional Traceability Gate).** The mockup is a
 fidelity target, not a requirements oracle: it may contain interactive chrome that

package/framework/.claude/skills/ds-edit/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: ds-edit
+effort: medium
+description: >
+  Update ONE existing canonical design-system element correctly — the deliberate
+  edit twin of /ds-new. Classifies the change (resync the spec to changed source /
+  extend with a new variant or prop / breaking change with migration / re-govern
+  the closed-set role) and runs it end to end: apply the source change (delegated
+  to ui-expert), regenerate the spec via the serializer (HEAD from source, agentic
+  + prose PRESERVED, the canonical template
+  framework/templates/component-spec.template.md filled if a spec is missing),
+  re-govern if needed, verify. A THIN orchestrator — delegates every rule to the
+  existing SSOTs, never hand-writes a spec HEAD. Use when the user says /ds-edit,
+  "aggiorna un componente", "modifica una primitive", "aggiungi una variante",
+  "estendi il componente", "resync dello spec", "breaking change su un
+  componente", or when `/prd` confirms a REUSE+VARIANT extension. The pure
+  mechanical doc-resync after a code change is ALREADY automatic (serializer +
+  `DS_COMPONENT_STALE` gate) — this skill is for the DELIBERATE change. Gated on
+  features.has_design_system.
+---
+
+# DS Edit — update one existing canonical element
+
+The deliberate-edit twin of `/ds-new`. `/ds-new` creates (its reuse-first step
+STOPS if the element exists); this skill takes an element that **already exists**
+and changes it with the right discipline. It is a conductor: each step DELEGATES
+to an existing module and cross-pointers to it — **no schema/closed-set/token rule
+is re-described here**, and the spec is always **serializer-emitted, never
+hand-written**.
+
+**What this skill is NOT for.** The *mechanical doc-resync* after a code change
+(props/variants changed, no decision) is already automatic: the serializer
+regenerates the deterministic HEAD from the new source (preserving agentic +
+prose) and the BLOCKING `DS_COMPONENT_STALE` gate (Post-Intervention Coherence
+Check) enforces it. Use this skill for a **deliberate** change with a decision.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`,
+`paths.components_primitives`, `paths.components_root`, `paths.design_tokens`,
+`design_tokens.outputs`, `paths.ui_guidelines`, `identity.brand_name`,
+`git.trunk_branch`.
+
+**Writes:** the changed source (via `ui-expert`), the regenerated
+`${paths.design_system}/components/<Name>.md` + INDEX + Selection Policy, and —
+when tokens change — the DTCG source + regenerated outputs. Source-read-only by
+default; source edits are delegated to `ui-expert`.
+
+**Schema + template:** the frontmatter HEAD is defined in
+`framework/agents/component-manifest-schema.md` and is **emitted by the
+serializer, never hand-written**. The standardized prose body is the canonical
+template `framework/templates/component-spec.template.md` — the SAME template
+`/ds-new` uses. On regeneration the serializer **preserves existing prose +
+non-empty agentic fields** (`source_sha` anchor) and only fills the template when
+a component has no prose body yet. The edit rules are the SSOT in
+`framework/agents/design-system-protocol.md` (Post-Intervention Coherence Check,
+§ Closed-Set Selection Policy, § Token Contract).
+
+**Gated by features:** `features.has_design_system` (BLOCKING). When `false`,
+REFUSE.
+
+**Overlay:** loads `.baldart/overlays/ds-edit.md` if present.
+
+**On missing 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. Mapping +
+parsing contract: `framework/agents/effort-protocol.md`.
+
+## Invocation
+
+`/ds-edit <Name>` (component) · `/ds-edit token <id>` (token) · `/ds-edit` (ask).
+Optionally state the change (e.g. "add variant `compact`", "remove `size=xl`",
+"resync"). When called by `/prd` (the reconciliation gate's REUSE+VARIANT branch),
+the target component + intended variant are pre-resolved.
+
+## Pre-flight
+
+- **P0 — gate.** `features.has_design_system: false` → REFUSE.
+- **P1 — locate.** Resolve the existing component (`${paths.design_system}/components/<Name>.md`
+  + its `source`). If it does NOT exist → STOP and suggest `/ds-new` (this skill
+  edits; it does not create).
+- **P2 — classify the change** (the edit decision tree; ask the user when unclear):
+  - **resync** — the source already changed (props/variants/a11y); only the spec
+    needs to catch up. (Often you don't even need this skill — see "What this skill
+    is NOT for".)
+  - **extend** — add a variant / prop / slot. Decide: does it stay WITHIN the
+    component's role contract (→ extend in place), or is it really a NEW role (→
+    that is `/ds-new` + a governance/closed-set decision, not an in-place edit)?
+  - **breaking** — remove/rename a variant or prop, or change a default. Requires a
+    migration plan + a spec Changelog entry (DELEGATE `templates/breaking-change-checklist.md`).
+  - **re-govern** — the change alters `canonical_for` / `use_when` / closure.
+
+---
+
+## Component edit path
+
+Each step is a delegation. Read the cited SSOT; do not paraphrase it.
+
+1. **Read the current spec + source.** Read the component HEAD (agentic fields to
+   PRESERVE) + prose body + its `source`. Establish the baseline before changing.
+2. **Apply the source change (conditional).** *extend / breaking* → DELEGATE
+   `ui-expert` (Task tool) to modify the source under
+   `${paths.components_primitives}/<Name>` (tokens-compliant; its Token Contract +
+   Functional Traceability pre-work apply). *resync* → the source already changed;
+   skip. The skill itself NEVER writes component source. Codex (no subagents) →
+   describe the required source change as a TODO and require the user to apply it.
+3. **Re-extract the deterministic HEAD.**
+   `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
+   → the updated `props` / `variants` / `composes` / `source_sha` from the new source.
+4. **Re-verify the agentic fields.** DELEGATE `doc-reviewer` to update ONLY what the
+   change affects (`must_rules` / `a11y` / `token_bindings` / `purpose`) and keep the
+   rest. Existing values are preserved by the serializer; never blank a field you
+   did not deliberately change. Codex → carry the existing values forward + TODO.
+5. **Re-govern (conditional).** When the edit changes the role: update
+   `canonical_for` / `use_when` / `selection_closed` per `design-system-protocol.md`
+   § Closed-Set Selection Policy + § Governance. **A variant added to a `closed`
+   family member is fine IF it stays within the role; a change that creates a NEW
+   role/standard is a governance decision** — flag it, don't self-approve.
+   For a **breaking** change, add a spec Changelog entry + a migration note.
+6. **Regenerate the spec (standardized, agentic preserved).** Build a 1-component
+   bundle with the updated fields, merged with the HEADs of ALL existing components
+   (so the regenerated `--index` + Selection Policy stay complete), and run:
+   ```
+   node .framework/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs \
+     --bundle <bundle.json> --out-dir ${paths.design_system}/components \
+     --index ${paths.design_system}/INDEX.md --brand "${identity.brand_name}" \
+     --tokens ${paths.design_tokens} --verify-usage
+   ```
+   The serializer regenerates the valid-YAML HEAD from the new fields, **preserves
+   the existing prose body verbatim** (no clobber), and fills the canonical template
+   `framework/templates/component-spec.template.md` ONLY if this component had no
+   prose yet — the SAME standardized shape as `/ds-new`. Self-validates, fails closed.
+   Review `droppedBindings` / `unverifiedBindings`.
+7. **Verify.** Serializer exit 0. Run `npx baldart ds-gate --json` — a closed-set
+   edit that introduced a new canonical must NOT trip `DS_CLOSED_SET_VIOLATION`. The
+   change + the regenerated spec ship in the SAME commit (the `DS_COMPONENT_STALE`
+   gate is satisfied by the resync). If a closure changed, the INDEX (with the
+   updated Selection Policy) must be committed for `ds-gate` to enforce it.
+8. **Coherence report (never silent).** Emit the protocol's "Registry coherence
+   check: N findings" block: spec updated (incl. HEAD), INDEX/policy reconciled,
+   tokens reconciled, breaking change documented + migration noted.
+
+## Token edit path
+
+Edit the DTCG node in `${paths.design_tokens}` → `npx baldart tokens build` →
+round-trip diff surfaced (never auto-accepted) → if a token's id/semantics
+changed, update affected components' `token_bindings` and re-serialize → coherence
+report. A token **rename/removal** is breaking (consumers reference the id) — list
+the affected component bindings + migrate them. DELEGATE `design-system-protocol.md`
+§ Token Cascade + Token Contract; never hand-edit generated output.
+
+## Inline fallbacks (portability + fail-safe)
+
+- No `Workflow` tool needed (prose-orchestrated).
+- Codex (no subagents): the deterministic spine (`extract-one` → `serialize-spec` →
+  `tokens build` → `ds-gate`) runs unchanged; the `ui-expert` source edit + agentic
+  re-verify degrade to TODO + a clear note.
+- Older CLI: `baldart ds-gate` / `baldart tokens build` absent → SKIP-with-reason,
+  never block. Surface the SKIP.
+
+## /prd integration
+
+`/prd`'s reconciliation gate (`prd/references/ui-design-phase.md`) classifies a
+region as **REUSE+VARIANT** when an existing component covers it but the mockup
+needs a prop/variant not yet in its spec. On user confirmation, `/prd` routes that
+to **`/ds-edit`** (create-now extend) or a "modify Component X" card (defer) —
+symmetric to how a `NEW (governed)` standard routes to `/ds-new`. `/prd` owns the
+*decision* (reuse-as-is vs extend vs new role); `/ds-edit` executes the *edit*.
+
+## See Also
+
+- `framework/.claude/skills/ds-new/SKILL.md` — the create twin (shared scripts +
+  the SAME canonical template).
+- `framework/templates/component-spec.template.md` — the canonical prose template
+  the serializer fills/preserves (the standardized doc shape).
+- `framework/agents/design-system-protocol.md` — Post-Intervention Coherence Check,
+  Closed-Set Selection Policy, Token Contract.
+- `framework/agents/component-manifest-schema.md` — the HEAD schema + the
+  regeneration contract (preserve agentic, regenerate deterministic).
+- `framework/templates/breaking-change-checklist.md` — for breaking edits.

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -273,14 +273,27 @@ capture the result + screenshots per route.
    - Use `page.getByRole()`, `page.getByText()`, `page.getByTestId()` —
      never CSS selectors that depend on Tailwind class strings.
    - Use `expect(locator)` with auto-waiting.
-   - For each route in the scenario, call:
+   - For each route in the scenario, capture BOTH viewports (set the viewport
+     BEFORE navigating so SSR / responsive hooks render for that width):
+       // Desktop — existing path, consumed by Phase 4 / 4b. DO NOT change it.
+       await page.setViewportSize({ width: 1440, height: 900 });
        await page.goto(route);
        await page.waitForLoadState("networkidle");
        await page.screenshot({
          path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.png",
          fullPage: true
        });
-     The screenshot path is consumed by the visual-fidelity-verifier in Phase 4 — do not change it.
+       // Mobile — additive, enables the responsiveness-break check (Phase 4).
+       await page.setViewportSize({ width: 375, height: 812 });
+       await page.goto(route);
+       await page.waitForLoadState("networkidle");
+       await page.screenshot({
+         path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>@mobile.png",
+         fullPage: true
+       });
+     Both screenshot paths are consumed by the visual-fidelity-verifier in
+     Phase 4 — do not change them. 375px is the canonical small-screen audit
+     width (design-system-protocol Reference Tables); it is fixed, not a config key.
    - For OTP-driven personas (test_plan.test_credentials.auth_method == "otp"),
      use `await page.pause()` between phone-entry and code-entry. Document
      the manual step in a test.step block.
@@ -309,7 +322,8 @@ capture the result + screenshots per route.
    - `status`: `passed` | `failed` | `flaky` | `skipped`
    - `duration_ms`
    - `failure_reason` (when failed, the first assertion error + stack hint)
-   - `screenshot_paths[]` (one per route in the scenario)
+   - `screenshot_paths[]` (per route: the desktop `<route-slug>.png` AND the
+     mobile `<route-slug>@mobile.png`)
 5. **Functional findings**: every `failed` or `flaky` scenario becomes a
    functional finding in the aggregate report (Phase 5). Severity:
    - Auth / payments / data-mutation scenario failed → `critical`
@@ -336,7 +350,11 @@ For each `route` in `plan.routes[]`:
      latency / cost saver — most routes pass pixel diff cleanly.
    - When `mockup_source.level == "compliance-only"`, skip pre-filter (no
      image to compare against) and proceed directly to step 2.
-   - When `mockup_source.level == "skip"`, skip this route entirely.
+   - When `mockup_source.level == "skip"`, skip the **desktop fidelity diff**
+     (steps 2) for this route — but still run the **mobile responsive pass**
+     (step 2b) if a `<route-slug>@mobile.png` screenshot was captured, since it
+     needs no mockup. Skip the route entirely only when no screenshot exists
+     (route unrenderable).
 2. **Invoke `visual-fidelity-verifier`** with the input contract documented
    in [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md):
 
@@ -365,12 +383,46 @@ For each `route` in `plan.routes[]`:
    verifier from flagging a deliberately-removed orphan affordance as
    `component-missing`. Omit the field (or pass `[]`) when the inventory has no
    resolved orphans.
+2b. **Mobile responsive-integrity pass.** Invoke the verifier a **second** time
+   for the same route with the mobile screenshot, so its `responsiveness-break`
+   check (which never fires on a desktop-only screenshot) can run. This is what
+   catches a viewport-scoped edit that regresses the *other* viewport:
+
+   ```
+   subagent_type: "visual-fidelity-verifier"
+   prompt: |
+     Compare the implementation against the mockup and return JSON per your
+     output schema.
+
+     Input payload:
+     {
+       "card_id": "FEAT-XXXX",
+       "route": "/dashboard",
+       "viewport": { "width": 375, "height": 812 },
+       "viewport_role": "mobile",
+       "implementation_screenshot_path": ".baldart/e2e-review/FEAT-XXXX/screenshots/<route-slug>@mobile.png",
+       "mockup_source": { "level": "skip" },
+       "tolerance": "<from config>"
+     }
+   ```
+   `viewport_role: "mobile"` puts the verifier in responsive-integrity mode: it
+   does NOT diff against the desktop mockup (the mobile layout reflows by design)
+   and emits ONLY genuine breakage findings (`responsiveness-break`,
+   `unreachable-action`, `layout-break`). Run this pass on every renderable route
+   (a desktop screenshot exists); skip it only when the route is explicitly marked
+   desktop-only in the plan. Cost is ~one extra verifier call per route — measured
+   marginal (~0.3% of a card run) because the 375px screenshot is lighter than the
+   1440px one and only renderable routes incur it.
 3. **Parse the agent's JSON response** strictly. If the response is malformed
    or contains prose outside the JSON, log
    `verifier_protocol_violation` in `gaps[]` and treat the route's findings
    as empty (do not invent findings from prose).
-4. **Aggregate** visual findings across all routes into a single
-   `visual_findings[]` array, deduplicating by `(route, category, region)`.
+4. **Aggregate** visual findings from BOTH passes across all routes into a single
+   `visual_findings[]` array, deduplicating by `(route, viewport_role, category,
+   region)` — `viewport_role` keeps a mobile `responsiveness-break` distinct from
+   any desktop finding on the same route. Tag each mobile-pass finding with
+   `viewport_role: "mobile"` so the Phase 5 gate and self-heal report show which
+   viewport broke.
 
 ---
 

package/framework/.claude/skills/new/references/implement.md

@@ -209,7 +209,12 @@
      `use_when` / `selection_closed` per `design-system-protocol.md § Closed-Set
      Selection Policy` (a closure is a governance decision — flag it, don't self-approve).
      A genuinely surface-specific one-off (`scope: local`) may use a lighter spec, but
-     still tokens-compliant + INDEX-registered.
+     still tokens-compliant + INDEX-registered. **A MODIFIED existing primitive (you
+     changed its props/variants/visual) follows the `/ds-edit` discipline**
+     (`framework/.claude/skills/ds-edit/SKILL.md`): re-run the serializer to regenerate
+     the HEAD from the new source — it **preserves the existing agentic fields + prose**
+     and only fills the template when a spec is missing — never hand-edit the HEAD. A
+     breaking change (removed/renamed variant or prop) adds a spec Changelog entry.
    - `${paths.design_system}/tokens-reference.md` — add / update token entries
      when introducing new semantic tokens. Drift code: `DS_TOKENS_DRIFT`.
 

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -206,6 +206,17 @@ Before invoking `ui-design`:
    the *creation* — no rule is duplicated. (Offline / non-interactive `/prd`: record
    the `/ds-new` create-now intent for the standard so it is not silently deferred.)
 
+7b. **Extend an existing element — `REUSE+VARIANT`.** When the mockup maps to an
+   existing component but needs a prop/variant not yet in its spec, and the user
+   confirmed extending it (rather than reuse-as-is or a new role): route to
+   **`/ds-edit`** (create-now extend) with the target + intended variant, OR a
+   "modify Component X: add variant Y" card (bind-and-defer) — symmetric to 7's
+   NEW→`/ds-new` routing. `/ds-edit` applies the source change (via `ui-expert`) +
+   regenerates the standardized spec (serializer, agentic preserved) + re-governs if
+   the role changes. If the "variant" is really a NEW role, it is a `NEW (governed)`
+   case (step 7), not an extend. A pure doc-resync (source already changed, no
+   decision) needs no skill — the `DS_COMPONENT_STALE` gate + serializer handle it.
+
 Pass the resolved inventory to `ui-design`:
 
 ```

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

@@ -196,6 +196,9 @@ This keeps consumers that have not yet upgraded (and non-TS stacks) from becomin
 - **Single-element create**: `/ds-new` (one component or token, on-the-fly or
   called by `/prd`; same scripts — `extract-one`/`serialize-spec` — as the bulk
   skill, so the HEAD it writes is identical).
+- **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
   Post-Intervention Coherence Check — a new/modified primitive regenerates its
   HEAD in the same change.

package/framework/agents/design-review.md

@@ -73,6 +73,9 @@ recommend `/design-system-init`.
 - [ ] No horizontal scroll on mobile
 - [ ] Touch targets minimum 44x44px
 - [ ] Content hierarchy clear
+- [ ] Responsive Scope Discipline (design-system-protocol.md § "Responsive Scope
+      Discipline"): no structural component swapped via `display:none`; a
+      viewport-scoped change does not regress the other viewport
 
 ### Interaction Design
 

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

@@ -545,6 +545,37 @@ implemented (or is about to be) without a traceable function. HIGH severity:
 it ships dead code and erodes the minimalism contract. The fix is always one of
 the three outcomes above, never "leave it, it matches the mockup".
 
+## Responsive Scope Discipline
+
+A UI surface usually renders across viewports (mobile / tablet / desktop). Two
+rules keep responsive work from regressing the viewport you are *not* editing —
+the framework states them abstractly; the concrete primitive names, breakpoint
+values and any project-specific gate live in the consumer's own files (CLAUDE.md,
+overlays, a project-local linter), never here.
+
+1. **Viewport-scoped edits stay scoped.** When a change targets one viewport
+   (e.g. "fix the mobile header"), it MUST NOT alter the other viewport's branch.
+   Editing the mobile path and silently shifting the desktop layout — or vice
+   versa — is a regression even when the targeted viewport looks correct. Verify
+   both viewports before declaring the task done (`/e2e-review` renders at 1440px
+   and 375px and runs the `responsiveness-break` check at each).
+
+2. **No structural component swapped via `display:none`.** A DOM-structural or
+   heavy component (one that mounts a non-trivial subtree, fetches data, or has
+   expensive children) MUST NOT be shown/hidden across viewports via
+   `display:none` / `visibility:hidden` / a `hidden` attribute / `@media` CSS
+   hiding. Mounting both branches and hiding one ships dead DOM, runs *both*
+   components' effects and queries, and doubles the work on every render. Render
+   only the active branch (a viewport hook / conditional render) instead.
+   Token-level responsive styling — a single element restyled per breakpoint
+   (padding, font-size, direction) — is fine; it is *swapping whole component
+   trees* via `display:none` that this rule rejects.
+
+Enforcement is a **review check** (`code-reviewer`, `/design-review`), not a lint:
+the most damaging case (a CSS-hidden heavy subtree) is invisible to a JS AST rule.
+Rule 2 violations are HIGH; a viewport-scoped edit that mutates the other branch
+(rule 1) is MEDIUM.
+
 ## Post-Intervention Coherence Check (BLOCKING completion gate)
 
 The BLOCKING pre-work above enforces *reads* before any UI change. This
@@ -658,6 +689,7 @@ The following files reference this module instead of duplicating its rules:
 - `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)
 - `framework/.claude/commands/design-review.md`
 - `framework/agents/design-review.md`
 

package/framework/agents/index.md

@@ -22,6 +22,7 @@ Route agents to the right module with minimal reading.
 - 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 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.
 - If CREATING, UPDATING, or READING a per-component spec (`${paths.design_system}/components/<Name>.md`) -> read `agents/component-manifest-schema.md` for the machine-readable frontmatter HEAD (deterministic-from-TS + agentic fields) and the on-demand read contract (INDEX router → frontmatter-first, prose only when modifying). The drift codes + gate stay in `design-system-protocol.md`.
 - If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
 - If touching architecture, auth, or tech stack -> read `agents/architecture.md`.

package/package.json

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