baldart 4.68.1 → 4.69.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.69.0] - 2026-06-24
+
+**`/ds-new` — the fifth corner of the design-system discipline: guided creation of ONE canonical element + a canonical, ENFORCED doc template.** Discovery/reuse, prevention (`/prd`), enforcement (`ds-gate`), and bulk bootstrap (`/design-system-init`) all existed — but there was no user-invocable entry point to create a single new component or token *correctly* on-the-fly (research → create → document → register → govern → verify); `ui-expert` does it inside tasks, `/design-system-init` is bulk-only. Second gap the user named: the docs were **not standardized** — the rich prose template existed but was buried in `scripts/` and (critically) **not wired into the serializer** (`emitSpec` stubbed a one-liner on empty prose), so freshly-created specs were untemplated.
+
+**MINOR** — adds a skill + a thin script wrapper; no new config key (rides on `features.has_design_system`). A pure orchestrator: every rule stays in its existing SSOT.
+
+### Added
+
+- **`/ds-new` skill** (`framework/.claude/skills/ds-new/SKILL.md`) — single-element guided creation, the on-the-fly twin of `/design-system-init`, also callable by `/prd` at its reconciliation gate's "NEW (governed)" branch. THIN orchestrator: reuse-first (Component Discovery Cascade + Selection-Policy-by-role + `signatureDuplicates`) → optional scaffold (delegated to `ui-expert`, opt-in; default documents an existing source) → extract HEAD (`extract-one.mjs`) → enrich agentic fields (`doc-reviewer`) → govern closures → document+register (serializer) → verify (`ds-gate`) → coherence report. Token path: DTCG node → `baldart tokens build` → bind. Gated on `features.has_design_system` (refuse + suggest `/design-system-init` when false). Codex-portable (deterministic spine zero-subagent; agentic steps degrade to TODO). No rule re-described — cross-pointers to `design-system-protocol.md` + `component-manifest-schema.md`.
+- **`extract-one.mjs`** — single-component wrapper around `extract-manifest.mjs`'s now-exported `extractFile` (the bulk extractor was `--roots <dir>` only). One extraction implementation, zero-dep, Codex-portable; verified to produce byte-identical output to the bulk path.
+
+### Changed
+
+- **Canonical doc template promoted + ENFORCED.** Moved `component-spec.template.md` from `design-system-init/scripts/` to the visible **`framework/templates/component-spec.template.md`** (single SSOT, framework-internal, excluded from the consumer-copy loop) and enhanced it to explicitly encode the structural-retrieval contract (HEAD-first discovery, token IDs not values, tables>prose, cross-ref-over-repetition, one-owner-per-fact — cross-pointing `doc-writing-for-rag` + `component-manifest-schema.md` § Read contract). **Wired into the serializer**: `serialize-spec.mjs`'s `emitSpec()` now FILLS the template on empty prose (placeholders from `props`/`variants`/`token_bindings`, unfillable ones keep `<!-- TODO -->`), via a new `--prose-template` flag (default resolves to the promoted path). Non-empty prose is still preserved verbatim. One change → three beneficiaries: `/ds-new`, `/design-system-init` greenfield, `ui-expert` Post-Intervention regen — every newly-created spec now follows the standardized shape.
+- **`extract-manifest.mjs`** — per-file extraction factored into exported `extractFile`; CLI guarded with `import.meta` so importing has no side effects.
+- **`/prd` reconciliation** (`ui-design-phase.md`) gains an OPT-IN "create now" arm at the NEW-governed branch (invoke `/ds-new`); default stays bind-and-defer. `/ds-new` registered as the single-element create path in `design-system-protocol.md` (§ When a primitive is missing + Consumers), `component-manifest-schema.md` (Producers & consumers), and `agents/index.md` routing.
+
+## [4.68.2] - 2026-06-24
+
+**A change's OWN documentation now closes before merge — no more "post-merge, non-blocking" doc follow-ups for what the change itself touched.** Observed on a real `mayo` FEAT-0055 run that merged with two deferred doc items: a full-sync of the `/products` screen doc (the exact route it changed, beyond a stub) and a `must_rule` clarification on `PageLayout.md` (the component it modified). Both are *own-docs* — documenting what you just shipped — yet `/new` permitted deferring them (the DS Decision Matrix routed "needs judgement" to a follow-up, and Phase 6b force-marks cards DONE regardless). Leaving the doc of the thing you just changed stale at merge is the drift entry door the Post-Intervention philosophy exists to close.
+
+**PATCH** — tightens the deferral classification of an existing gate; no new config key, no new agent/skill. Deliberately NOT a blanket "all docs block merge" (that regresses the follow-up mechanism by coupling ready code to genuinely-separate design decisions) — only *own-docs* block; adjacent/cross-cutting docs still defer to a tracked follow-up.
+
+### Changed
+
+- **New SSOT § "Documentation Closure"** in `agents/workflows.md` (twin of the AC Scope Closure Discipline, STRICTER) — a change's OWN docs must be SYNCED in the same PR before merge, no follow-up escape, a stub is not synced. "Own-docs" is **deterministic** (not the agent's discretion to relabel as adjacent): (1) the spec of any modified primitive, (2) the screen/route doc for a touched route, (3) the card's declared `documentation_impact`/`canonical_docs`. Anything outside those three is adjacent and still deferrable.
+- **`design-system-protocol.md` Decision Matrix tightened** — a spec update that DOCUMENTS the behaviour THIS change introduced (a new/changed `must_rule`/prop/variant/slot/a11y hook) is **inline-BLOCKING, not deferrable**; only a genuinely SEPARATE design decision (a new variant's full semantics, breaking-change migration design, an unresolved a11y trade-off) remains the deferrable case.
+- **`doc-reviewer` Own-Documentation Closure gate** — own-doc obligations are `synced` or a **BLOCKER** (`DOC_OWN_STUB` for a stub-only own-route doc, `DS_COMPONENT_STALE` for a modified-primitive spec), emitted as `BLOCKER` (never a `LOW`/`MED` note, never a silent "deferred"). Flows through the existing pre-merge severity gate (an unresolved BLOCKER blocks the merge — `final-review.md`) and the `doc` domain-override (never inline-bypassed). Shared agent + shared `new-final-review.js` → enforced in BOTH `/new` and `new2` with no separate wiring.
+
 ## [4.68.1] - 2026-06-24
 
 **`/design-system-init` now actually ACTIVATES the closed-set gate it just populated — found on the first real `mayo` upgrade run.** The v4.68.0 upgrade correctly derived + confirmed the closed-set data (the two-header `page-header` family + a `range-slider` pair landed in the component HEADs with `canonical_for`/`selection_closed: true`), but `baldart ds-gate` stayed `no-policy` and never enforced. Root cause: step 6's serializer bundle merged "deterministic (step 3) + agentic (step 4)" but NOT the step-4b/4c selection-policy fields, so `emitSelectionPolicy` ran over components without `canonical_for` and generated an EMPTY `INDEX.md § "Selection Policy"` block (the HEADs got the fields via a side path; the gate reads the INDEX block). Data present, gate dormant.

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 (35 portable skills)
+### Skills (36 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)
+- **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`)
 - **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.68.1
+4.69.0

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

@@ -246,7 +246,33 @@ Run this before any general audit:
 7. Write missing docs directly. Prefer extending existing reference docs over creating new files unless the feature is large enough to justify a standalone document. For type-specific checklists, read `.claude/skills/doc-reviewer-support/references/doc-checklists.md` **if it exists**; otherwise apply the doc-type rules and invariant table above and the `doc-writing-for-rag` skill's templates.
 8. Update indexes when new docs are added.
 9. Assess Obsidian/wiki sync need (section H) — **OPTIONAL, only when `features.has_wiki_overlay: true` in `baldart.config.yml`**. If the flag is absent or false, skip section H with a one-line "no wiki overlay" note. When the flag is true, read `.claude/skills/doc-reviewer-support/references/obsidian-integration.md` for trigger conditions **if it exists**; otherwise assess on first principles (new cross-cutting concept, renamed canonical, deprecated doc) and note the need without dispatching any sync agent here.
-10. Report what was checked, added, fixed, and deferred.
+10. Report what was checked, added, fixed, and deferred — but see the Own-Documentation Closure gate below: an own-doc may NOT appear in the "deferred" bucket.
+
+### Own-Documentation Closure (BLOCKING — own-docs close in this PR, no defer)
+
+Per `agents/workflows.md § Documentation Closure`, the documentation of **what
+this change itself touched** must be SYNCED in this diff before merge — it is NOT
+deferrable to a follow-up, and a STUB is not synced. Build the own-doc obligation
+list deterministically from the diff + card (do not relabel an own-doc as
+"adjacent" to defer it):
+
+1. **Modified-primitive spec** — every component whose source changed → its
+   `components/<Name>.md` reflects the shipped behaviour (the `must_rules` / props /
+   slots the change introduced). A stale/stub spec is `DS_COMPONENT_STALE`.
+2. **Touched route/screen doc** — the diff changed a route/page → the screen/route
+   doc for THAT route is synced (not just stubbed). A stub-only doc for a route you
+   changed is `DOC_OWN_STUB` (the screens/README "stub but full-sync deferred"
+   pattern — not allowed for an own-route).
+3. **Declared `documentation_impact` / `canonical_docs`** — every doc the card named
+   as in-scope is synced.
+
+Each obligation is `synced` or it is a **BLOCKER** finding (`DOC_OWN_STUB` /
+`DS_COMPONENT_STALE`) — emit it as `BLOCKER` in section F/G, never as a `LOW`/`MED`
+note and never silently in a "deferred" list. In WRITE mode you fix it yourself
+(you are fully responsible for feature docs — `## Constraints`); you do NOT defer
+an own-doc to another agent or a later card. Only **adjacent** docs (a broader
+rewrite, a genuinely separate design decision, areas the change only grazed) may be
+reported as a tracked follow-up.
 
 ## Audit Process (general documentation review)
 1. **Map**: Build tree of all docs with purpose annotations.

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -371,8 +371,9 @@ hardcode literals that duplicate these tokens.
 - `framework/agents/project-context.md` — config + overlay contract.
 - `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
   the registry BLOCKING).
-- `scripts/component-spec.template.md` — prose-body reference (HEAD is serializer-owned).
-- `scripts/extract-manifest.mjs` — deterministic, zero-dep HEAD extractor (Codex-portable).
-- `scripts/serialize-spec.mjs` — deterministic HEAD serializer (valid-YAML, fail-closed) + INDEX router emitter.
+- `framework/templates/component-spec.template.md` — the CANONICAL prose-body template (SSOT for the spec shape; the serializer fills it on creation, HEAD is serializer-owned). The `--prose-template` default resolves here; no flag needed.
+- `scripts/extract-manifest.mjs` — deterministic, zero-dep HEAD extractor (`extractFile` shared with `extract-one.mjs`; Codex-portable).
+- `scripts/extract-one.mjs` — single-component wrapper around `extractFile` (used by `/ds-new`).
+- `scripts/serialize-spec.mjs` — deterministic HEAD serializer (valid-YAML, fail-closed) + INDEX router + Selection Policy + canonical prose-body fill.
 - `framework/agents/component-manifest-schema.md` — the frontmatter HEAD schema.
 - `framework/docs/COMPONENT-MANIFEST-LAYER.md` — layer design + lifecycle.

package/framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs

@@ -25,9 +25,6 @@ function arg(name, def = '') {
   return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
 }
 
-const roots = arg('--roots').split(',').map((s) => s.trim()).filter(Boolean);
-const asJson = process.argv.includes('--json');
-
 /** Recursively collect .tsx/.ts files (skip tests, stories, node_modules, index barrels). */
 function walk(dir, out = []) {
   let entries;
@@ -120,32 +117,48 @@ function extractComposes(src) {
   return [...out];
 }
 
-const components = [];
-for (const root of roots) {
-  for (const file of walk(root)) {
-    let src;
-    try { src = fs.readFileSync(file, 'utf8'); } catch (_) { continue; }
-    const name = exportedName(src, file);
-    if (!name) continue;
-    const props = extractProps(src, name);
-    components.push({
-      name,
-      source: path.relative(process.cwd(), file),
-      source_sha: gitSha(file),
-      status: 'stable',
-      category: 'primitive',
-      props,
-      variants: extractVariants(props),
-      composes: extractComposes(src).filter((c) => c !== name),
-    });
-  }
+/**
+ * Extract ONE component's deterministic manifest fields from a source file.
+ * Returns null when the file is unreadable or exports no PascalCase component.
+ * This is the SINGLE extraction implementation — shared by the bulk extractor
+ * (CLI below) and `extract-one.mjs` (the single-component wrapper /ds-new uses),
+ * so the two never fork.
+ */
+export function extractFile(file) {
+  let src;
+  try { src = fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
+  const name = exportedName(src, file);
+  if (!name) return null;
+  const props = extractProps(src, name);
+  return {
+    name,
+    source: path.relative(process.cwd(), file),
+    source_sha: gitSha(file),
+    status: 'stable',
+    category: 'primitive',
+    props,
+    variants: extractVariants(props),
+    composes: extractComposes(src).filter((c) => c !== name),
+  };
 }
 
-const result = { schema: 'baldart.component-manifest-extract/1', count: components.length, components };
-if (asJson) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-else {
-  for (const c of components) {
-    process.stdout.write(`${c.name}  (${c.source})  props:${Object.keys(c.props).length} variants:${c.variants.length} composes:${c.composes.length}\n`);
+// CLI — guarded so importing `extractFile` (from extract-one.mjs) has NO side effects.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const roots = arg('--roots').split(',').map((s) => s.trim()).filter(Boolean);
+  const asJson = process.argv.includes('--json');
+  const components = [];
+  for (const root of roots) {
+    for (const file of walk(root)) {
+      const c = extractFile(file);
+      if (c) components.push(c);
+    }
+  }
+  const result = { schema: 'baldart.component-manifest-extract/1', count: components.length, components };
+  if (asJson) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  else {
+    for (const c of components) {
+      process.stdout.write(`${c.name}  (${c.source})  props:${Object.keys(c.props).length} variants:${c.variants.length} composes:${c.composes.length}\n`);
+    }
+    process.stdout.write(`\n${components.length} components.\n`);
   }
-  process.stdout.write(`\n${components.length} components.\n`);
 }

package/framework/.claude/skills/design-system-init/scripts/extract-one.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Single-component deterministic manifest extractor (since v4.69.0).
+//
+// The thin single-element wrapper around `extract-manifest.mjs`'s `extractFile`
+// (the bulk extractor is `--roots <dir>` only). Used by `/ds-new` to extract one
+// component's deterministic HEAD fields (name, source, source_sha, props,
+// variants, composes) WITHOUT a subagent — the Codex-portable spine. ZERO
+// dependencies; imports the ONE shared extraction implementation so it can never
+// drift from the bulk path.
+//
+// Usage:
+//   node extract-one.mjs --source <path.tsx> [--json]
+
+import { extractFile } from './extract-manifest.mjs';
+
+function arg(name, def = '') {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+}
+
+const source = arg('--source');
+const asJson = process.argv.includes('--json');
+
+if (!source) {
+  console.error('usage: extract-one.mjs --source <path.tsx> [--json]');
+  process.exit(2);
+}
+
+const component = extractFile(source);
+if (!component) {
+  console.error(`extract-one: no exported PascalCase component found in ${source} (or file unreadable)`);
+  process.exit(1);
+}
+
+if (asJson) {
+  process.stdout.write(JSON.stringify({ schema: 'baldart.component-manifest-extract-one/1', component }, null, 2) + '\n');
+} else {
+  process.stdout.write(`${component.name}  (${component.source})  props:${Object.keys(component.props).length} variants:${component.variants.length} composes:${component.composes.length}\n`);
+}

package/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs

@@ -91,9 +91,44 @@ export function emitHead(c) {
 // Date is fine in a CLI script (this is not a resumable workflow).
 const TODAY = new Date().toISOString().slice(0, 10);
 
-/** Full spec file = HEAD fences + preserved prose body. */
-export function emitSpec(c) {
-  const prose = (c.prose && c.prose.trim()) ? c.prose.replace(/^\s+/, '') : `# ${c.name}\n\n> Per-component spec. The HEAD above is the machine-readable contract.\n`;
+/**
+ * Fill the canonical prose-body template (framework/templates/component-spec.template.md)
+ * for a freshly-created component. Takes the template TEXT, strips its leading
+ * comment + documented `---…---` HEAD block (the serializer owns the real HEAD),
+ * and substitutes the deterministically-fillable `{{…}}` placeholders. Unfillable
+ * ones keep the template's `<!-- TODO -->` so a human/doc-reviewer finishes them.
+ * Zero-dep, pure string ops. This is the wiring that makes EVERY newly-created
+ * spec follow the standardized shape (the gap: emitSpec used to stub a one-liner).
+ */
+export function fillProseTemplate(c, templateText) {
+  // Body = everything after the second `---` fence (drop the leading comment + HEAD doc block).
+  const body = templateText.replace(/^[\s\S]*?\n---\n[\s\S]*?\n---\n/, '');
+  const propsTable = (c.props && Object.keys(c.props).length)
+    ? Object.entries(c.props).map(([k, p]) => `| ${k} | ${String((p && p.type) || '').replace(/\|/g, '\\|')} | ${(p && p.default !== undefined && p.default !== '') ? p.default : '—'} | ${(p && p.required) ? 'required' : '—'} |`).join('\n')
+    : '';
+  const variants = (c.variants && c.variants.length) ? c.variants.map((v) => `- \`${v}\``).join('\n') : '';
+  const tokens = (c.token_bindings && c.token_bindings.length) ? c.token_bindings.map((t) => `- \`${t}\``).join('\n') : '';
+  return body
+    .replace(/\{\{ComponentName\}\}/g, c.name || '')
+    .replace(/\{\{exported_name\}\}/g, c.name || '')
+    .replace(/\{\{file_path\}\}/g, c.source || '')
+    .replace(/\{\{today\}\}/g, c.last_verified || TODAY)
+    .replace(/\{\{props_table\}\}/g, propsTable)
+    .replace(/\{\{variants_section\}\}/g, variants)
+    .replace(/\{\{tokens_section\}\}/g, tokens);
+}
+
+/**
+ * Full spec file = HEAD fences + prose body. Prose resolution:
+ *   1. existing `c.prose` → preserved verbatim (never clobbered on regeneration);
+ *   2. else, when `proseTemplate` text is provided → the filled canonical template;
+ *   3. else → a minimal one-line stub (fallback when no template is resolvable).
+ */
+export function emitSpec(c, proseTemplate) {
+  let prose;
+  if (c.prose && c.prose.trim()) prose = c.prose.replace(/^\s+/, '');
+  else if (proseTemplate) prose = fillProseTemplate(c, proseTemplate).replace(/^\s+/, '');
+  else prose = `# ${c.name}\n\n> Per-component spec. The HEAD above is the machine-readable contract.\n`;
   return `---\n${emitHead(c)}\n---\n\n${prose.replace(/\s*$/, '')}\n`;
 }
 
@@ -286,8 +321,14 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   const tokensPath = arg('--tokens'); // optional DTCG .tokens.json → binding vocab guard
   const verifyUsage = process.argv.includes('--verify-usage'); // advisory source-usage check
   const cwd = arg('--cwd', process.cwd());
+  // Canonical prose-body template (framework/templates/component-spec.template.md).
+  // Default resolves relative to this script; callers may override with --prose-template.
+  const proseTemplatePath = arg('--prose-template', new URL('../../../../templates/component-spec.template.md', import.meta.url).pathname);
+  let proseTemplate = '';
+  try { proseTemplate = fs.readFileSync(proseTemplatePath, 'utf8'); }
+  catch (_) { /* template unresolvable → emitSpec falls back to the one-line stub */ }
   if (!bundlePath || !outDir) {
-    console.error('usage: serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>] [--tokens <.tokens.json>] [--verify-usage] [--cwd <dir>]');
+    console.error('usage: serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>] [--tokens <.tokens.json>] [--verify-usage] [--prose-template <path>] [--cwd <dir>]');
     process.exit(2);
   }
   const bundle = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
@@ -325,7 +366,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   fs.mkdirSync(outDir, { recursive: true });
   let invalid = 0;
   for (const c of components) {
-    const spec = emitSpec(c);
+    const spec = emitSpec(c, proseTemplate);
     fs.writeFileSync(path.join(outDir, `${c.name}.md`), spec, 'utf8');
     const head = spec.match(/^---\n([\s\S]*?)\n---/)[1];
     const v = tryValidate(head);

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

@@ -0,0 +1,199 @@
+---
+name: ds-new
+effort: medium
+description: >
+  Create ONE canonical design-system element — a component OR a token — end to
+  end with the full discipline: reuse-first research, (optional) scaffold, then
+  document + register + govern + verify. The single-element, on-the-fly twin of
+  the bulk `/design-system-init`: usable standalone by you, and callable by `/prd`
+  when its reconciliation gate confirms a NEW component. A THIN orchestrator — it
+  delegates every rule to the existing SSOTs (Component Discovery Cascade, the
+  manifest HEAD schema, the closed-set Selection Policy, the token cascade) and
+  produces STANDARDIZED docs by filling the canonical template
+  (framework/templates/component-spec.template.md) via the deterministic
+  serializer — it never hand-writes a spec HEAD. Use when the user says /ds-new,
+  "nuovo componente design system", "aggiungi un token", "crea un componente
+  canonico", "rendi canonico questo componente", "registra una primitive",
+  "documenta un componente nel design system". Gated on features.has_design_system.
+---
+
+# DS New — create one canonical design-system element
+
+The fifth corner of the design-system discipline: discovery/reuse, prevention
+(`/prd`), enforcement (`baldart ds-gate`), and bulk bootstrap
+(`/design-system-init`) already exist — this is the **guided creation of ONE
+element** done correctly. It is a conductor: each step DELEGATES to an existing
+module and cross-pointers to it; **no cascade/schema/closed-set/token rule is
+re-described here** (re-describing it is how it drifts from the SSOT).
+
+## 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`, `paths.global_styles`,
+`identity.brand_name`, `git.trunk_branch`.
+
+**Writes:** files under `${paths.design_system}` (the spec, the regenerated INDEX
++ Selection Policy), the component HEAD fields, and — for tokens — the DTCG
+`${paths.design_tokens}` + the regenerated outputs. Like `/design-system-init`,
+it is **source-read-only by default** (it does not author component source);
+scaffolding a `.tsx` is opt-in and delegated to `ui-expert`.
+
+**Schema:** 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 serializer fills
+it). The creation/governance rules are the SSOT in
+`framework/agents/design-system-protocol.md` (Component Discovery Cascade, §
+Closed-Set Selection Policy, § Token Cascade, Post-Intervention Coherence Check).
+
+**Gated by features:** `features.has_design_system` (BLOCKING). When `false`,
+REFUSE and recommend `/design-system-init` (you need a registry to add to). See
+`design-system-protocol.md` § Gating.
+
+**Overlay:** loads `.baldart/overlays/ds-new.md` if present (e.g. mandated stack
+for scaffolds, brand-voice for the prose, a project token-naming convention).
+
+**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 to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Mapping + parsing contract:
+`framework/agents/effort-protocol.md`.
+
+## Invocation
+
+`/ds-new <Name>` (component) · `/ds-new token <id>` (token) · `/ds-new` (ask).
+Optional: `scaffold` (also generate the source), a mockup/figma ref, a one-line
+intent. When called by `/prd` (the reconciliation gate's "NEW (governed)"
+branch), the role/closure are pre-resolved — skip the reuse step (P1/step 1).
+
+## Pre-flight
+
+- **P0 — gate.** `features.has_design_system: false` → REFUSE + suggest
+  `/design-system-init`. (DELEGATE `design-system-protocol.md` § Gating.)
+- **P1 — kind.** component | token (from the arg, else ask one question).
+- **P2 — source mode (component only).** Does the source already exist, or should
+  the skill scaffold it? Ask once; **default = document an existing file.**
+
+---
+
+## Component path
+
+Each step is a delegation. Read the cited SSOT; do not paraphrase it.
+
+1. **Reuse-first (BLOCKING).** Walk the Component Discovery Cascade AND query the
+   Selection Policy **by role** (`INDEX.md` § Selection Policy), per
+   `design-system-protocol.md`. Surface duplicates with the gate's own detector —
+   `node -e` over `src/utils/ds-reuse-gate.js → signatureDuplicates` (or `baldart
+   ds-gate` once a spec exists). Ask the user **only** on a real fork (a
+   suspected-duplicate, or a closed-family hit) — one consolidated
+   `AskUserQuestion`. On a clean match → **STOP and reuse the existing component**
+   (creating it anyway is the exact failure this skill prevents).
+2. **Create (conditional).** *Scaffold mode* → DELEGATE `ui-expert` (Task tool):
+   it runs its own BLOCKING Functional Traceability + Token Contract pre-work and
+   writes a tokens-compliant source under `${paths.components_primitives}/<Name>`.
+   *Document mode* → take the existing path. Under Codex (no subagents), scaffold
+   degrades to a tokens-compliant-skeleton TODO and requires you to supply the
+   path. The skill itself NEVER writes component source.
+3. **Extract the deterministic HEAD.**
+   `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
+   → `name`/`source`/`source_sha`/`props`/`variants`/`composes` (zero-dep,
+   Codex-portable, no subagent).
+4. **Enrich the agentic fields AS DATA.** DELEGATE `doc-reviewer` (Task tool) to
+   produce `purpose` / `token_bindings` (picked from the REAL ids in
+   `${paths.design_tokens}`) / `a11y` / `related` / `must_rules` as JSON values —
+   NEVER typed into YAML. Codex → leave empty + TODO. (Schema:
+   `component-manifest-schema.md`.)
+5. **Govern (conditional).** Set `canonical_for` / `use_when` / `selection_closed`
+   ONLY when a closure is confirmed by the user (or pre-resolved by `/prd`);
+   propose-only when unattended. DELEGATE `design-system-protocol.md` § Closed-Set
+   Selection Policy + § Governance. An agent never flips closure on its own.
+6. **Document + register (the standardized doc).** Build a 1-component bundle
+   (`{ brand, components: [<the merged deterministic+agentic+policy fields>] }`)
+   **merged with the HEADs of ALL existing components** (read each
+   `${paths.design_system}/components/*.md` HEAD) so the regenerated `--index`
+   router + Selection Policy block stay complete (the same caveat as
+   `/design-system-init` step 6 — an INDEX from a partial bundle drops rows). 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
+   ```
+   It emits the valid-YAML HEAD + the **standardized prose body** (it fills
+   `framework/templates/component-spec.template.md` — the `--prose-template`
+   default; you never hand-write the spec) + the regenerated thin INDEX, then
+   self-validates and **fails closed**. Review `droppedBindings` /
+   `unverifiedBindings` per step 4.
+7. **Verify.** Serializer exit 0. If a closure was written: confirm
+   `grep -q '## Selection Policy' ${paths.design_system}/INDEX.md` AND
+   `npx baldart ds-gate --json` does NOT report `"reason":"no-policy"`. The gate
+   reads the **committed** baseline → the INDEX (with the policy block) must be
+   committed for enforcement; surface that so the user commits it. (This is
+   `/design-system-init` step 6b reused.)
+8. **Coherence report (never silent).** Emit the protocol's "Registry coherence
+   check: N findings" block (per § Post-Intervention Coherence Check): new spec
+   shipped, INDEX entry added, tokens reconciled, closed-set respected.
+
+---
+
+## Token path
+
+1. **Reuse-first.** Check the token already exists (in `${paths.design_tokens}` /
+   `tokens-reference.md`); ask **primitive vs semantic vs component** layer.
+   DELEGATE `design-system-protocol.md` § Token Cascade (components consume
+   semantic, never primitive; prefer OKLCH for palette generation).
+2. **Edit the DTCG SSOT.** Add the node to `${paths.design_tokens}` (`.tokens.json`,
+   `$type` + `$value`, hierarchical id). NEVER hand-edit the generated output.
+3. **Regenerate.** `npx baldart tokens build` (reads `.tokens.json`, regenerates
+   `design_tokens.outputs[]` + `tokens-reference.md`). DELEGATE — never reimplement.
+4. **Round-trip verify.** A non-empty semantic diff between the generated output
+   and the prior is surfaced, **never auto-accepted** — the user ratifies.
+5. **Bind (optional).** When a component should consume the new token, add its
+   **id** (not value) to that component's `token_bindings` and re-serialize (the
+   component path's step 6). The `--tokens` guard confirms the id resolves.
+6. **Coherence report.** Per § Post-Intervention Coherence Check (check 3): a
+   dangling `token_bindings` id is `DS_TOKENS_DRIFT`.
+
+**Token-doc standard (NOT a per-token file).** A token's one-owner home is its
+DTCG node + its row in the generated `tokens-reference.md` + its id in component
+`token_bindings`. Do NOT create a per-token `.md` (it would be a 4th source of
+truth — violates `doc-writing-for-rag` one-owner-per-fact). Token *rationale*, if
+any, goes in an existing `${paths.design_system}/patterns/*.md`.
+
+---
+
+## Inline fallbacks (portability + fail-safe)
+
+- **No `Workflow` tool needed** — this skill is prose-orchestrated.
+- **Codex (no subagents):** the deterministic spine (`extract-one` → `serialize-spec`
+  → `tokens build` → `ds-gate`) is zero-subagent and runs unchanged; the agentic
+  enrichment (step 4) and `ui-expert` scaffold degrade to TODO + a clear note.
+- **Older CLI:** `baldart ds-gate` / `baldart tokens build` absent →
+  SKIP-with-reason, never block (every BALDART gate's fail-safe contract). Surface
+  the SKIP; do not claim a gate ran when it did not.
+
+## /prd integration
+
+`/prd`'s reconciliation gate (`prd/references/ui-design-phase.md`, the "NEW
+(governed) — confirmed with user" branch) OWNS the decision *whether* a new
+element is needed; `/ds-new` EXECUTES the creation. When `/prd` invokes it with a
+resolved `region → NewComponent — role: family@context — standard:y/n — closed:y/n`,
+skip P1/P2/step 1 (already reconciled) and run from step 2. No rule is duplicated
+across the two.
+
+## See Also
+
+- `framework/agents/design-system-protocol.md` — the cascade, closed-set, token
+  cascade, governance, and Post-Intervention rules this skill delegates to.
+- `framework/agents/component-manifest-schema.md` — the HEAD schema.
+- `framework/templates/component-spec.template.md` — the canonical prose template
+  the serializer fills (the standardized doc shape).
+- `framework/.claude/skills/design-system-init/SKILL.md` — the bulk twin; shares
+  the same scripts (`extract-manifest`/`extract-one`/`serialize-spec`).
+- `framework/docs/COMPONENT-MANIFEST-LAYER.md` — the layer overview.

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

@@ -186,6 +186,16 @@ Before invoking `ui-design`:
      it from then on. A new standard for *all* views also opens a **migration
      follow-up card** for the existing views (never migrate them in this PRD).
 
+7. **Create now (OPT-IN) vs bind-and-defer (default).** For each `NEW (governed)`
+   element, the default is **bind-and-defer**: persist the binding (step 6) and let
+   `ui-expert` create the component at `/new` implement time. When the user wants it
+   materialized **now** (the canonical element + its standardized spec + INDEX entry
+   + governance, before any card runs), invoke **`/ds-new`** with the resolved tuple
+   (`NewComponent — role: family@context — standard:y/n — closed:y/n`); it skips its
+   own reuse step (already reconciled here) and runs from its create step. `/prd`
+   owns the *decision*; `/ds-new` executes the *creation* — no rule is duplicated.
+   This is additive: omit it and the default bind-and-defer path is unchanged.
+
 Pass the resolved inventory to `ui-design`:
 
 ```

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

@@ -192,7 +192,10 @@ This keeps consumers that have not yet upgraded (and non-TS stacks) from becomin
 ## Producers & consumers
 
 - **Bootstrap / upgrade**: `/design-system-init` (deterministic extract + agentic
-  enrich; greenfield and upgrade modes).
+  enrich; greenfield and upgrade modes; bulk).
+- **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).
 - **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

@@ -360,7 +360,10 @@ agent has two choices:
 - **Add to the registry** — preferred when the primitive is broadly useful.
   Create the per-component spec, the implementation under
   `${paths.components_primitives}/<Name>`, and an INDEX.md entry in the same
-  change.
+  change. The guided single-element path is the **`/ds-new`** skill (reuse-first →
+  optional scaffold → document + register + govern + verify); it produces the
+  standardized spec by filling the canonical template via the serializer. The bulk
+  analogue (whole registry at once) is `/design-system-init`.
 - **Local one-off** — only when the use case is genuinely surface-specific
   (e.g. a marketing-page hero illustration). Even then, prefer composing
   existing primitives over hand-rolling a new one. Justify the local choice
@@ -600,7 +603,8 @@ For each item in the diff that touched a visual surface, run these 4 checks:
 | Situation | Action |
 |---|---|
 | Spec / token update is trivial (variant added, prop renamed, token value tweaked) | Apply inline — same commit as the code change |
-| Spec / token update requires design judgement (new variant semantics, breaking change, accessibility decision) | Open a follow-up card; **document the gap explicitly** in the change description; flag for `code-reviewer` |
+| Spec update DOCUMENTS the behaviour THIS change introduced (a new/changed `must_rule`, prop, variant, slot, a11y hook the diff added) | **Apply inline — BLOCKING, not deferrable.** This is an *own-doc* (`agents/workflows.md § Documentation Closure`): documenting what you just shipped is part of the change, never a follow-up. A stub is not synced. |
+| Spec / token update requires a genuinely SEPARATE design decision (a new variant's full semantics needing its own design pass, a breaking change needing migration design, an unresolved accessibility trade-off) — beyond documenting this change | Open a follow-up card; **document the gap explicitly** in the change description; flag for `code-reviewer`. This is the ONLY deferrable case. |
 | Reused undocumented primitive that is broadly useful | Add INDEX entry inline; if a full spec needs design work, scaffold a stub spec marked `status: needs-review` |
 | Reused undocumented primitive that is surface-specific | Add INDEX entry with `scope: local` and a 2-line note explaining why no full spec is needed |
 | Introduced a primitive that **duplicates** an existing registry entry | **Stop**. This is the failure mode the cascade exists to prevent. Revert and reuse the existing primitive, or escalate to refactor the existing primitive if the new requirement is legitimately broader |
@@ -652,7 +656,8 @@ The following files reference this module instead of duplicating its rules:
   intrinsic-quality critic consumed by `/e2e-review` Phase 4b)
 - `framework/.claude/skills/ui-design/SKILL.md`
 - `framework/.claude/skills/frontend-design/SKILL.md`
-- `framework/.claude/skills/design-system-init/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/commands/design-review.md`
 - `framework/agents/design-review.md`
 

package/framework/agents/index.md

@@ -21,6 +21,7 @@ Route agents to the right module with minimal reading.
 - 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 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 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/framework/agents/workflows.md

@@ -61,6 +61,38 @@ When a card's `acceptance_criteria` cannot be fully implemented as written, the
 
 Any deferral travels through an explicit `AskUserQuestion` with the AC text quoted verbatim, one question per AC. For orchestrator skills (`/new`, `/prd`) this discipline is enforced in the per-card AC-closure gate before commit. Auto Mode's "bias toward proceeding" applies to routine decisions, NOT to scope reduction — silent deferral of a numbered AC is a violation even in Auto Mode.
 
+### Documentation Closure (own-docs close before merge — no defer)
+
+The same discipline applies to the **documentation of what the change itself
+touched** — and is STRICTER than ACs: a change's OWN docs must be reconciled
+**in the same PR, before merge**. They may NOT be deferred to a post-merge
+follow-up, and a STUB is not "synced". Leaving the doc of the thing you just
+changed stale at merge is the drift entry door the Post-Intervention philosophy
+exists to close ("reconcile at source, not next Monday").
+
+**"Own docs" is deterministic** (derivable from the diff + card — not the agent's
+discretion to relabel as "adjacent"):
+
+1. **Modified-primitive spec** — any component whose source changed in the diff →
+   its `${paths.design_system}/components/<Name>.md` (incl. the `must_rules` /
+   behaviour the change introduced). This is `DS_COMPONENT_STALE` and is already
+   blocking; it is **not** deferrable as "needs design judgement" when it merely
+   documents what this change did (see `agents/design-system-protocol.md`
+   Decision Matrix).
+2. **Touched route/screen doc** — if the diff changes a route/page, the screen/route
+   doc for THAT route (`${paths.references_dir}/ui/…` / `docs/design/screens/…`).
+3. **Declared `documentation_impact` / `canonical_docs`** — the docs the card itself
+   named as in-scope.
+
+Each own-doc obligation is `synced` (the doc reflects the shipped change, in this
+diff) or it BLOCKS the merge. There is no `deferred` state for an own-doc and no
+follow-up-card escape — the only resolutions are *sync it now* or an explicit
+`[USER-APPROVED DEFERRAL]` recorded via `AskUserQuestion` (interactive) / surfaced
+as a blocker (autonomous). **Adjacent / cross-cutting docs** — a broader rewrite, a
+genuinely separate design decision, docs for areas the change only grazed — are
+NOT own-docs: those legitimately defer to a tracked follow-up card. The boundary is
+the three deterministic categories above; anything outside them is adjacent.
+
 ### Coder authority (no defer)
 
 Coder agents report `done | failed` at card level. Per-requirement signals (`done | not_implemented`) are inputs to the orchestrator's AC-Closure Gate, never terminal verdicts. Coders have NO authority to declare an AC `deferred`, `out of scope`, `covered by X`, `partial`, `blocked`, or any equivalent. Only the user, via the gate's `AskUserQuestion`, can approve a deferral. Inventing constraints — `time budget`, `context budget`, `context pressure as override`, or any phrase not enumerated in a phase's documented Gate table — to skip phases or defer ACs is a protocol violation. The same rule applies to orchestrator agents (sequential and team-mode L0/L1/L2/L3): they relay coder signals into the gate; they do not aggregate, summarize, or pre-filter deferrals.

package/framework/docs/COMPONENT-MANIFEST-LAYER.md

@@ -40,8 +40,8 @@ BALDART wraps the **standard** (DTCG) and owns only a thin generator — the sam
 |---|---|---|
 | HEAD schema | `framework/agents/component-manifest-schema.md` | SSOT for the frontmatter fields + read/regeneration/leniency contract |
 | Gate + cascade | `framework/agents/design-system-protocol.md` | BLOCKING reads, drift codes, token SSOT inversion, Authority Matrix |
-| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` | zero-dep Node; name/source/source_sha/props/variants/composes (Codex-portable) |
-| Spec template | `…/design-system-init/scripts/component-spec.template.md` | HEAD + prose scaffold |
+| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (`extractFile`) + `extract-one.mjs` (single-component wrapper) | zero-dep Node; name/source/source_sha/props/variants/composes (Codex-portable) |
+| Spec template | `framework/templates/component-spec.template.md` | CANONICAL prose-body template (SSOT); serializer fills it on creation via `--prose-template` (default) |
 | Bootstrap/upgrade | `framework/.claude/skills/design-system-init/SKILL.md` | greenfield + upgrade modes |
 | Token emitters | `src/utils/token-emitters/{index,ts,css}.js` | DTCG → stack-native output (REGISTRY pattern) |
 | Token generator | `src/utils/tokens-generator.js` | parse `.tokens.json`, resolve `{aliases}`, build/isStale |

package/framework/{.claude/skills/design-system-init/scripts → templates}/component-spec.template.md

@@ -1,8 +1,21 @@
-<!-- NOTE: the frontmatter HEAD below is EMITTED DETERMINISTICALLY by
-     scripts/serialize-spec.mjs (field data in, valid YAML out). Do NOT hand-write
-     or hand-fill it — invalid YAML (e.g. `props:{}` without a space, unquoted
-     multiline strings) is exactly the bug the serializer prevents. This template
-     documents the SHAPE + is the reference for the PROSE BODY below the fences. -->
+<!-- CANONICAL per-component spec template (since v4.69.0). SSOT for the SHAPE of
+     every `${paths.design_system}/components/<Name>.md`. Consumed by
+     scripts/serialize-spec.mjs (it fills the PROSE BODY below the fences on
+     creation) and cited by /ds-new, /design-system-init, ui-expert, doc-reviewer.
+     This is framework-internal (machinery), not a hand-edit copy.
+
+     The frontmatter HEAD is EMITTED DETERMINISTICALLY by serialize-spec.mjs
+     (field data in, valid YAML out) — NEVER hand-write or hand-fill it (invalid
+     YAML, e.g. `props:{}` without a space, is exactly the bug the serializer
+     prevents). The block below documents the HEAD shape; the serializer owns it.
+
+     RETRIEVAL CONTRACT (why this shape — see `doc-writing-for-rag` SKILL.md +
+     `agents/component-manifest-schema.md` § "Read contract"): agents discover a
+     component by reading the thin INDEX router → then ONLY this HEAD frontmatter
+     (never this prose body, never the source) — the prose is read solely when
+     MODIFYING the component. So: keep the body scan-able (tables > prose), one
+     fact per owner (visual values live in tokens-reference.md, not here),
+     cross-ref instead of repeating, and store token IDs (not values). -->
 ---
 # Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md
 # DETERMINISTIC fields (regenerated from source — do not hand-curate):
@@ -20,6 +33,10 @@ token_bindings: {{token_bindings_yaml}}   # DTCG token IDs (not values)
 a11y: "{{a11y}}"
 related: {{related_yaml}}
 must_rules: {{must_rules_yaml}}
+# Selection policy (closed-set — see design-system-protocol.md § Closed-Set Selection Policy):
+canonical_for: {{canonical_for_yaml}}   # ["<family>@<context>"] roles this is THE canonical answer for ([] = none)
+use_when: "{{use_when}}"                 # one-line predicate: pick this over its siblings when…
+selection_closed: {{selection_closed}}   # true ⇒ the role family is a CLOSED set (new member = governance, not code)
 last_verified: {{today}}
 owner: doc-reviewer
 ---
@@ -27,10 +44,12 @@ owner: doc-reviewer
 # {{ComponentName}}
 
 > Per-component spec. The HEAD above is the machine-readable contract (read it
-> first for discovery); this prose body is the human long-form rationale.
-> Authoritative for props, variants, accessibility, and anti-patterns. Visual
-> authority (color/shadow/radius/spacing) belongs to the DTCG token SSOT
-> (`${paths.design_tokens}`), surfaced via [`../tokens-reference.md`](../tokens-reference.md).
+> first for discovery); this prose body is the human long-form rationale, read
+> only when MODIFYING this component. Authoritative for props, variants,
+> accessibility, and anti-patterns. Visual authority (color/shadow/radius/spacing)
+> belongs to the DTCG token SSOT (`${paths.design_tokens}`), surfaced via
+> [`../tokens-reference.md`](../tokens-reference.md) — never duplicate token
+> values here.
 
 ## Source
 
@@ -67,9 +86,10 @@ when to use it. Example:
 
 {{tokens_section}}
 
-<!-- TODO: list the tokens this component reads from tokens-reference.md.
-Color, spacing, shadow, radius, motion. If you find hardcoded literals in
-the source, that's a registry violation — fix at the source. -->
+<!-- TODO: these are DTCG token IDs (not values) — one read of tokens-reference.md
+resolves every value. List the color / spacing / shadow / radius / motion tokens
+this component reads. A hardcoded literal in the source is a registry violation —
+fix it at the source, add a token if one is missing. -->
 
 ## Accessibility
 
@@ -104,4 +124,4 @@ Cross-link to patterns/ docs when applicable. -->
 <!-- Track breaking changes to the spec. Bump version when removing a variant
 or changing a default. -->
 
-- {{today}} — Spec scaffolded by `/design-system-init`.
+- {{today}} — Spec scaffolded by BALDART (`/ds-new` / `/design-system-init`).

package/package.json

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

package/src/utils/symlinks.js

@@ -785,6 +785,7 @@ class SymlinkUtils {
     const FRAMEWORK_INTERNAL = new Set([
       'baldart.config.template.yml',
       'skill-project-context.snippet.md',
+      'component-spec.template.md', // canonical prose-body template — consumed by serialize-spec.mjs, not hand-edited
       'overlays', // example overlays directory — consumers reference, don't copy wholesale
     ]);