baldart 4.72.0 → 4.74.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.
+
+**MINOR** — adds capability; **no new `baldart.config.yml` key** (rides on the existing `features.has_design_system`), so the schema-change propagation rule does NOT apply. The new `component_bindings[].props` is an **optional** sub-field — legacy cards omit it and the validator (which keys on the `C`-profile top-level field) is unaffected. On a non-multimodal tool (Codex) the image-load instruction degrades to a harmless no-op and the structured fields carry the intent.
+
+### Changed
+
+- **The `/new` UI briefing loads the mockup IMAGE multimodally** (`framework/.claude/skills/new/references/implement.md` § "Design Reference"). The instruction now branches on the file type of `links.design`: an IMAGE (`.png`/`.jpg`/`.jpeg`/`.webp`/`.pdf`, or a `mockups/*.png` canonical path) is **`Read` directly** so it renders into the agent's context (pixels = fidelity target); an `.html` keeps the existing read-as-text behaviour. The briefing also now surfaces `component_bindings[].props`/`variant` (exact variant intent) and the card's responsive ACs (breakpoint behaviour a single-viewport image cannot show) as the structured complement to the image.
+- **`mockup_analysis` schema enriched in-place with the four dimensions a flat affordance list + a single static image lose** (`framework/.claude/skills/prd/references/discovery-phase.md` § "Mockup analysis schema"). Each `screens[]` entry gains four OPTIONAL fields: `layout` (compact nesting sketch — the hierarchy), `component_props` (key props/variant legible per component — the reuse-vs-`reuse-variant` signal), `states` (richer `states_visible` mapping each state→the AC that mandates it; an untraced state is a Discovery gap by the same rule as an untraced affordance), and `responsive` (breakpoint behaviour). "Omit rather than guess" discipline extended to all four.
+- **Component Reconciliation consumes the enrichment and persists it** (`framework/.claude/skills/prd/references/ui-design-phase.md` § "Component Reconciliation"). `REUSE+VARIANT` detection now compares `mockup_analysis.component_props` against the component's spec HEAD (props the spec doesn't cover ⇒ variant), and the persist step carries resolved props into `component_bindings[].props` and lifts `responsive` notes into the UI card's `acceptance_criteria` as testable ACs.
+
+### Added
+
+- **`component_bindings[].props` card sub-field** (`framework/agents/card-schema.md` § `component_bindings`) — the optional resolved props/variant each region must use, the exact-variant intent a static image leaves ambiguous; `ui-expert` implements it verbatim. Sub-field of the existing `C`-profile `component_bindings`, so no validator/matrix change.
+
 ## [4.72.0] - 2026-06-25
 
 **Session-id provenance on PRDs and cards — trace an implementation bug back to the chat history that produced it.** When `/new` ships a card that turns out wrong, there was no link from the card back to *which Claude Code session* planned it (`/prd`) or implemented it (`/new`/`/new2`) — so you couldn't reopen the transcript to see the steps the session took (or skipped). Now every card carries an optional `provenance` block recording the session UUID for each lifecycle stage, and the PRD frontmatter records its authoring session. Resolve the chat history at `~/.claude/projects/*/<session-id>.jsonl` (the UUID is globally unique — no project slug needed). This turns "this feature is broken, why?" into a concrete pointer at the planning/implementation conversation, for improving the framework from real runs.

package/VERSION

@@ -1 +1 @@
-4.72.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

@@ -111,9 +111,36 @@
 
    ### Design Reference (UI cards only — include if card has links.design)
    Design file: [path from card's links.design field]
-   Read the design.html file and use it as the **visual reference** for your
-   implementation (layout, spacing, hierarchy, copy). The design was approved by
-   the user — your implementation MUST match its appearance.
+
+   **Load the mockup into your context — branch on the file type:**
+   - If `links.design` resolves to an IMAGE (`.png` / `.jpg` / `.jpeg` /
+     `.webp` / `.pdf`, or the card points at a `mockups/*.png` canonical path):
+     you are multimodal — **`Read` the mockup image file path directly**. `Read`
+     renders the image visually into your context (the native multimodal
+     mechanism). The mockup's PIXELS are the fidelity target: study layout,
+     spacing, hierarchy, density, color, and the relative position of every
+     region. Do NOT implement from the filename or a textual guess — you MUST
+     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. **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
+   MUST match its appearance.
+
+   **Structured design intent (when present on the card).** The image shows the
+   static look at one viewport; these fields cover what a single image cannot:
+   - `component_bindings[].props` / `variant` — the exact props/variant each
+     region must use (e.g. `SectionHeader {depth: 0}`, `DataTable {density:
+     comfortable}`). Implement them verbatim; do not eyeball a variant.
+   - the card's responsive acceptance criteria — breakpoint behaviour the
+     single-viewport mockup does not show (e.g. "≤640px: table collapses to
+     card-list"). These are testable ACs, not optional polish.
 
    **The mockup is a visual reference, NOT a license to re-create components.**
    When the card carries `component_bindings` (the `/prd` Component Reconciliation

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/.claude/skills/prd/references/discovery-phase.md

@@ -1122,11 +1122,24 @@ mockup_analysis:
       purpose: <one line — what this screen lets the user do>
       components:
         - <component name from ${paths.design_system}/INDEX.md if matched, else free-form>
+      layout:        # OPTIONAL — compact nesting sketch (the hierarchy a flat list loses)
+        - region: <e.g. "page-header">
+          component: <component or free-form for this region>
+          contains: [<child region/component>, …]   # omit for leaf regions
+      component_props:   # OPTIONAL — key props/variants legible from the mockup, per component
+        - component: <e.g. "SectionHeader">
+          props: {<prop>: <value>}    # e.g. {depth: 0} · {density: comfortable, selectable: true}
       affordances:   # interactive + iconographic artifacts visible in the mockup
         - label: <e.g. "Export CSV button", "bell icon", "Filters tab">
           traces_to: <US-id / AC-id / discovery dimension this artifact serves — or "" if none yet>
           classification: backed | decorative | orphan
       states_visible: [empty, loading, error, success, default]
+      states:        # OPTIONAL — richer form: map each visible state to the AC that mandates it
+        - state: <loading | empty | error | success | default>
+          traces_to: <AC-id — or "" if no AC mandates it yet (a Discovery gap, see below)>
+          representation: <one line, e.g. "skeleton rows ×5", "EmptyState, copy 'Nessun ordine'">
+      responsive:    # OPTIONAL — breakpoint behaviour a single-viewport mockup cannot show
+        - <e.g. "≤640px: DataTable collapses to card-list; header shows back button">
       copy_excerpts:
         - <verbatim text visible in the mockup, max ~10 strings per screen>
       gaps:
@@ -1148,11 +1161,21 @@ mockup_analysis:
 - Omit `copy_excerpts` for screens that have no readable text (icon-only).
 - Omit `states_visible` for screens that show only the default state — do not
   invent states the mockup doesn't show.
+- `layout`, `component_props`, `states`, and `responsive` are OPTIONAL
+  enrichments. Fill them when the mockup makes them legible — they carry exactly
+  the intent a flat affordance list and a single static image lose (nesting
+  hierarchy, the exact component variant, state→AC mapping, breakpoint
+  behaviour). Omit a field rather than guess; never invent a breakpoint,
+  prop, or nesting the mockup doesn't actually show (same rule as `states_visible`).
+  These feed the Component Reconciliation (reuse vs `reuse-variant`) and the
+  `/new` implementer briefing — they are how visual intent survives to code.
 
 **Gap discipline:** every entry in `gaps[]` MUST become either a Discovery question
 or an explicit non-question (recorded in Discovery Log as "skipped — outside
 mockup scope"). Gaps that remain unresolved by the end of Discovery block PRD
-writing in Step 4.
+writing in Step 4. A `states[]` entry with `traces_to: ""` is a gap by the same
+rule — a visible state no AC mandates must be resolved in Discovery (gain an AC,
+or be confirmed cosmetic), exactly like an untraced affordance.
 
 **Affordance discipline (Functional Traceability):** classify every interactive
 or iconographic artifact the mockup shows. The mockup is a fidelity target, not

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

@@ -158,7 +158,10 @@ Before invoking `ui-design`:
    - **REUSE** — an existing component (or a closed-family canonical member) covers
      it. Record the exact component. *No question asked — this is the silent path.*
    - **REUSE+VARIANT** — an existing component covers it but the mockup needs a
-     prop/variant not yet in its spec.
+     prop/variant not yet in its spec. The `mockup_analysis.component_props` for
+     this component is the signal: compare the legible props against the
+     component's spec HEAD — props the spec doesn't cover ⇒ this is a VARIANT,
+     not a plain REUSE.
    - **NEW** — genuinely no match.
 5. **Ask ONLY on ambiguity** (`REUSE+VARIANT` and `NEW` — never on plain REUSE).
    One consolidated `AskUserQuestion` per ambiguous element, in the
@@ -179,7 +182,12 @@ Before invoking `ui-design`:
    - Into each affected card → the `component_bindings` block (see
      `agents/card-schema.md`): `region → component (reuse | new) [+ variant]`. This
      is the authority `ui-expert` implements against (the mockup becomes a visual
-     reference, not a license to re-create).
+     reference, not a license to re-create). **Carry the resolved props** from
+     `mockup_analysis.component_props` into `component_bindings[].props` so the
+     exact-variant intent reaches the implementer (a single static image leaves it
+     ambiguous). Likewise, lift any `mockup_analysis.screens[].responsive` notes
+     into the UI card's `acceptance_criteria` as testable responsive ACs — the
+     mockup cannot show breakpoint behaviour at one viewport.
    - Into the manifest → when the user confirms a new standard / closure, the
      component's `canonical_for` / `use_when` / `selection_closed` are written (via
      `/design-system-init` enrich or `doc-reviewer`), so `baldart ds-gate` enforces
@@ -222,7 +230,7 @@ Pass the resolved inventory to `ui-design`:
 ```
 ### Component Reconciliation (resolved)
 REUSE — bind region → existing component:
-- [region] → [Component] — [path] — [variant if any]
+- [region] → [Component] — [path] — [variant if any] — [props if any]
 
 NEW (governed) — confirmed with user:
 - [region] → [NewComponent] — role: [family@context] — standard: [yes/no] — closed: [yes/no]

package/framework/agents/card-schema.md

@@ -148,6 +148,7 @@ component_bindings:
     action: reuse                     # reuse | reuse-variant | new
     variant: ""                       # when action: reuse-variant
     role: "page-header@depth-0"       # when it maps a Selection-Policy role
+    props: {depth: 0}                 # optional — exact props the region must use (from mockup_props)
   - region: "row actions"
     component: IconButton
     action: reuse
@@ -159,6 +160,14 @@ that finds a `component_bindings` entry MUST honor it over any contrary reading
 the mockup; a UI card that went through `/prd` with `features.has_design_system:
 true` but lacks this field is under-specified (the reconciliation did not run).
 
+`props` is **optional** — the resolved key props/variant the region must use,
+lifted from the mockup analysis `component_props` during reconciliation (e.g.
+`{depth: 0}`, `{density: comfortable}`). It carries the exact-variant intent a
+single static image leaves ambiguous; `ui-expert` implements it verbatim. Omit it
+when the mockup exposes no distinguishing props (the component's defaults apply).
+Breakpoint behaviour the mockup cannot show at a single viewport lives in the
+card's `acceptance_criteria` as testable responsive ACs, not here.
+
 ### `provenance` (session-id traceability — optional, skill-written)
 
 A small block that records **which Claude Code session produced the card**, so a card

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.72.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') {