baldart 4.73.0 → 4.74.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.74.0] - 2026-06-25
+
+**Update in autonomy: a standing `git.on_divergence` policy so `npx baldart update` stops asking every release.** A consumer that keeps local commits on `.framework/` which the updater cannot auto-classify as overlays — the canonical case being a project-specific edit to a `framework/agents/*.md` **protocol module** (e.g. a design-system review rule naming the project's own files), which unlike `.claude/{agents,skills,commands}/` has **no overlay channel** — was stopped on EVERY update with "Custom commits touch non-overlayable paths … cannot be auto-resolved", forcing a manual `--on-divergence pull` each time. The non-interactive escape hatch existed only as a per-run CLI flag; there was no way to persist the choice. Now `git.on_divergence` in `baldart.config.yml` records a standing policy the interactive `update` honours, so a consumer opts in once and never passes the flag again. The `--on-divergence` CLI flag still wins for a single run, and the default (unset/null) preserves the current "stop once and ask" behaviour exactly.
+
+**MINOR** — adds capability via a new config key. The **schema-change propagation rule applies** and is satisfied end-to-end: template (`git.on_divergence`) + configure prompt + update detector (already diffs all `git.*` keys, so the new key auto-surfaces on existing configs) + the gating code in `update` + CHANGELOG. Backward compatible: an existing config without the key resolves to null → no policy → unchanged behaviour; a config typo fails loud up-front (validated against the same `DIVERGENCE_STRATEGIES` set as the flag).
+
+### Added
+
+- **`git.on_divergence` standing divergence policy** (`framework/templates/baldart.config.template.yml` § `git:`). Values: `null`/unset (DEFAULT — stop once and ask), `pull` (keep the local commits and merge upstream over them; non-destructive, the autonomy choice), `scaffold-overlays` (auto-scaffold the overlay-able subset, then stop). Read by `update` via a new `readDivergencePolicy()` helper; surfaced interactively (`Applying persisted divergence policy …`) so an auto-merge is never a surprise. The `configure` git section now prompts for it (`src/commands/configure.js`), writing the key explicitly (as null when unset) so the schema-drift detector does not re-offer it every release.
+
+### Changed
+
+- **`update` resolves the divergence strategy as flag-or-config** (`src/commands/update.js`). `--on-divergence` (explicit per-run override) wins; absent a flag, the resolver falls back to `git.on_divergence`. Up-front validation now reports the correct source (`--on-divergence` vs ``git.on_divergence`` in baldart.config.yml) on a typo. The stale-CLI self-relaunch needs no change — the newer child re-reads the same config and resolves the policy itself.
+
+### Fixed
+
+- **`links.design` now resolves to a path that EXISTS — making the v4.73.0 image-load fire in the mockup-only case.** v4.73.0 made the `/new` implementer `Read` the mockup image when `links.design` is a `.png`, but the card field was still hardcoded to `design.html` (`framework/.claude/agents/prd-card-writer.md`, `framework/.claude/skills/prd/assets/card-template.yml`). In **mockup-only** runs — exactly the "I hand `/prd` Claude Design / Figma mockups" flow — no `design.html` is generated (`ui-design-phase.md` sets `design.html_path: n/a (mockup-only)`), so the card pointed at a **non-existent** file: the implementer got a dead path AND the image branch never fired (extension was `.html`). `prd-card-writer` now resolves `links.design` to an on-disk path — design.html when generated, ELSE the screen's canonical mockup PNG from `mockup_analysis.screens[].mockup_ref` / `prerender_png` under `mockups/` (chat-only `chat://image-N` images are never persisted, so such a card is flagged visually-unreferenced rather than pointed at a path that won't resolve). The `/new` briefing (`framework/.claude/skills/new/references/implement.md` § "Design Reference") also falls back to the sibling `mockups/` PNG when a legacy card's `.html` path is absent. No behaviour change for generated-design runs.
+
 ## [4.73.0] - 2026-06-25
 
 **Mockup→code fidelity: let the implementer actually SEE the mockup, and carry the intent a flat list loses.** A recurring complaint: a detailed mockup (Claude Design / Figma) is handed to `/prd`, then `/new` ships something that is not 1:1 with the design. The obvious diagnosis — "the PRD's visual mapping is too weak, add a mockup-understanding agent" — was **refuted** by an adversarial pass: the visual data largely already exists (`mockup_analysis` captures affordances + traceability + states + DS violations; `component_bindings` propagates region→component to the implementer), and a parallel machine-readable `design-spec` artifact would be a second SSOT that drifts from the mockup and would feed the verifier a textual proxy instead of the pixels (a bias `visual-fidelity-verifier` explicitly forbids). The **actual driver**: the `/new` UI briefing passes the mockup as a *path* and says "Read the design.html file" — but for a binary PNG/Figma mockup nothing ever instructs the (multimodal) `ui-expert` to **load the image into its context**. The implementer was building from text, never looking at the design.

package/VERSION

@@ -1 +1 @@
-4.73.0
+4.74.0

package/framework/.claude/agents/prd-card-writer.md

@@ -468,7 +468,19 @@ Every card MUST include ALL fields from the template:
 - `review_profile` (`skip`|`light`|`balanced`|`deep` — computed via Rule C, or honored if pre-set)
 - `files_likely_touched` (exact paths with NEW/MODIFY)
 - `links.prd` (path to PRD)
-- `links.design` (path to design.html — REQUIRED for any card with UI scope)
+- `links.design` (REQUIRED for any card with UI scope) — the card's screen design
+  reference, resolved to a path **that exists on disk in the worktree**:
+  - **design.html when one was generated** for this screen (Step 3 produced it).
+  - **ELSE the screen's canonical mockup PNG** under `${paths.prd_dir}/<slug>/mockups/`
+    — read it from the screen's `mockup_analysis.screens[].mockup_ref` (or
+    `prerender_png`). A **mockup-only** run (user-provided Claude Design / Figma
+    mockups, no design generated) sets `design.html_path: n/a (mockup-only)` — in
+    that case design.html does NOT exist, so pointing at it gives the `/new`
+    implementer a dead path and no visual reference. Use the PNG.
+  - A **chat-only image** (`mockup_ref: chat://image-N`, never persisted to disk —
+    see `discovery-phase.md` 1.6.4 step 3) cannot be referenced: it is unreachable
+    from `/new`. Flag the card as visually-unreferenced rather than writing a path
+    that won't resolve in the worktree.
 - `canonical_docs` — REQUIRED for all cards generated from a PRD:
   - `ssot_registry_entry`: scan `${paths.references_dir}/ssot-registry.md` and copy the exact row name (column 1, bold) matching this card's macro feature. If the feature is new and has no entry yet, use the PRD slug.
   - `data_model_refs`: list of `${paths.references_dir}/collections/*.md` paths for collections touched by this card — REQUIRED whenever the card has `data_fields`; derive from the collection names in `data_fields`.
@@ -605,7 +617,9 @@ Rules:
 
 Rules:
 - Every UI element MUST map to at least one card
-- Every card with UI scope MUST include `links.design`
+- Every card with UI scope MUST include `links.design`, resolved to an on-disk
+  path per the `links.design` rule above (design.html when generated, else the
+  screen's canonical mockup PNG — never a non-existent design.html)
 - Every UI requirement MUST reference the specific element number
 
 ## Parallel Group Computation (MANDATORY)

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

@@ -123,7 +123,11 @@
      actually load and look at the image. (On a non-multimodal tool the `Read`
      degrades to no-op text; fall back to the structured fields below.)
    - If `links.design` is an `.html` file: **Read the design.html file** and use
-     it as the visual reference.
+     it as the visual reference. **If that file does not exist** (a legacy
+     mockup-only card that points at a `design.html` which was never generated),
+     fall back: look under the PRD's `mockups/` dir (sibling of the `links.design`
+     path) for the screen's PNG/JPG and `Read` that image instead — do not proceed
+     with no visual reference.
 
    Use it as the **visual reference** for your implementation (layout, spacing,
    hierarchy, copy). The design was approved by the user — your implementation

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -130,7 +130,13 @@ files_likely_touched:
 
 links:
   prd: "${paths.prd_dir}/{{slug}}/PRD.md"
-  design: "${paths.prd_dir}/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
+  # REQUIRED for UI cards (omit for API-only). Point at the card's screen design
+  # reference THAT EXISTS ON DISK: the generated design.html when one was produced,
+  # ELSE the screen's canonical mockup PNG under mockups/ (mockup-only runs have NO
+  # design.html). Never point at a design.html that was not generated — the /new
+  # implementer loads this path; a chat-only image (chat://image-N, never persisted)
+  # cannot be referenced.
+  design: "${paths.prd_dir}/{{slug}}/design.html"  # OR ${paths.prd_dir}/{{slug}}/mockups/<screen>.png
 
 # --- Canonical Docs (REQUIRED for cards generated from a PRD) ---
 # Traces which SSOT documents informed this card's requirements.

package/framework/templates/baldart.config.template.yml

@@ -443,6 +443,25 @@ git:
   # the production-readiness gate, e.g. ["supabase-db-push", "vercel-prod"].
   auto_deploy: []
 
+  # Standing divergence policy (since v4.74.0). When THIS consumer has local
+  # commits on `.framework/` that `npx baldart update` cannot auto-classify as
+  # overlays — e.g. a project-specific edit to a `framework/agents/*.md` protocol
+  # module, which (unlike `.claude/{agents,skills,commands}/`) has NO overlay
+  # channel — the interactive update STOPS once and asks. Set a standing policy
+  # here to let `update` self-resolve without passing `--on-divergence` every
+  # release (the "update in autonomy" knob):
+  #
+  #   null / unset  — DEFAULT. Stop once and ask (current behaviour).
+  #   pull          — keep the local commits and merge upstream over them.
+  #                   Non-destructive: a merge commit is created; resolve any
+  #                   conflicts that surface. This is the autonomy choice.
+  #   scaffold-overlays — auto-scaffold overlay skeletons for the overlay-able
+  #                   subset, then stop (only helps `.claude/{agents,skills,
+  #                   commands}/` edits — useless for protocol-module drift).
+  #
+  # The `--on-divergence` CLI flag always overrides this key for a single run.
+  on_divergence: null
+
 # ─── TOOLS ───────────────────────────────────────────────────────────────
 # Which AI CLI tools should the framework target on this machine?
 # Each enabled tool gets its own per-item skill symlinks pointing at the

package/package.json

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

package/src/commands/configure.js

@@ -694,6 +694,23 @@ async function interactivePrompts(merged, detected) {
     ? autoDeployAnswer.split(',').map((s) => s.trim()).filter(Boolean)
     : [];
 
+  // ---- Standing divergence policy (since v4.74.0) -----------------------
+  // Lets `npx baldart update` self-resolve `.framework/` divergence without a
+  // manual `--on-divergence` flag every release. Default (blank) = stop & ask.
+  const currentDiv = (typeof merged.git.on_divergence === 'string' && merged.git.on_divergence.trim())
+    ? merged.git.on_divergence.trim() : '';
+  const chosenDiv = await UI.select(
+    `Standing divergence policy for \`npx baldart update\` (current: ${currentDiv || 'ask each time'})`,
+    [
+      { name: 'ask each time — stop & ask when .framework/ has unclassifiable local commits (default)', value: '' },
+      { name: 'pull — auto-merge upstream over the local commits (non-destructive; the autonomy choice)', value: 'pull' },
+      { name: 'scaffold-overlays — auto-scaffold overlays for the overlay-able subset, then stop', value: 'scaffold-overlays' },
+    ]
+  );
+  // Write the key even when unset (as null) so the schema-drift detector does
+  // not re-offer it on every future update.
+  merged.git.on_divergence = chosenDiv || null;
+
   UI.section('Features (explicit yes/no — option A: always ask)');
   for (const flag of [
     ['has_design_system', 'Project has a documented design system?'],

package/src/commands/update.js

@@ -29,6 +29,27 @@ function readEnabledTools(cwd = process.cwd()) {
 // agent-overlay feedback that prompted this).
 const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
 
+// Persisted divergence policy (since v4.74.0). When a consumer has local commits
+// on `.framework/` that the interactive flow would otherwise STOP on (e.g. a
+// project-specific edit to a `framework/agents/*.md` protocol module, which has
+// no overlay channel), `git.on_divergence` in baldart.config.yml lets `update`
+// self-resolve without a manual `--on-divergence` flag every release. The CLI
+// flag still wins (explicit per-run override). Returns the raw string (validated
+// by the caller, so a config typo fails loud) or null when no policy is set.
+function readDivergencePolicy(cwd = process.cwd()) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (!fs.existsSync(cfgPath)) return null;
+    const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+    const v = cfg && cfg.git && cfg.git.on_divergence;
+    if (typeof v === 'string' && v.trim()) return v.trim();
+  } catch (_) { /* fall through — no policy */ }
+  return null;
+}
+
 // Machine-readable result channel (v3.32.0+). When --json is active, STDOUT
 // must carry exactly ONE JSON object and nothing else — UI.setJsonMode() has
 // already redirected every human line to STDERR. Every terminal point in the
@@ -749,15 +770,25 @@ async function update(options = {}, unknownArgs = []) {
     }
   }
 
-  // Non-interactive divergence strategy (since v3.29.0). Validated up-front so
-  // a typo fails fast instead of mid-flow after the network fetch.
-  const divStrategy = options.onDivergence;
+  // Divergence strategy resolution (flag since v3.29.0; persisted policy since
+  // v4.74.0). The `--on-divergence` CLI flag is the explicit per-run override;
+  // absent a flag, fall back to the standing `git.on_divergence` policy in
+  // baldart.config.yml so a consumer that opted in never has to pass the flag.
+  // Validated up-front so a typo (in EITHER source) fails fast instead of
+  // mid-flow after the network fetch.
+  const divFlag = options.onDivergence;
+  const divFromConfig = divFlag === undefined ? readDivergencePolicy() : null;
+  const divStrategy = divFlag !== undefined ? divFlag : (divFromConfig || undefined);
+  const divStrategySource = divFlag !== undefined ? 'flag' : (divFromConfig ? 'config' : null);
   if (divStrategy !== undefined && !DIVERGENCE_STRATEGIES.includes(divStrategy)) {
+    const where = divStrategySource === 'config'
+      ? '`git.on_divergence` in baldart.config.yml'
+      : '--on-divergence';
     if (JSON_MODE) {
       emitUpdateJson({ ok: false, action: 'usage-error',
-        reason: `Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.` }, 1);
+        reason: `Invalid ${where} "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.` }, 1);
     }
-    UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
+    UI.error(`Invalid ${where} "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
     process.exit(1);
   }
 
@@ -875,6 +906,11 @@ async function update(options = {}, unknownArgs = []) {
     // a framework file → suggest /overlay. real-custom = prompt 3-way.
     if (status.hasDivergence) {
       UI.newline();
+      // Surface the persisted policy so an interactive user isn't surprised that
+      // `update` auto-resolved (e.g. auto-merged) instead of stopping to ask.
+      if (divStrategySource === 'config') {
+        UI.info(`Applying persisted divergence policy git.on_divergence: "${divStrategy}" (from baldart.config.yml). Pass --on-divergence to override for one run.`);
+      }
       if (status.divergenceClass === 'all-noise') {
         UI.info(`Detected ${status.divergenceCommits.length} subtree-merge / chore commit(s) (git plumbing noise — no real content drift). Auto-resolving…`);
       } else if (status.divergenceClass === 'overlay-able') {