baldart 4.69.1 → 4.70.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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.70.0

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/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-system-protocol.md

@@ -658,6 +658,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.70.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"