baldart 3.8.2 → 3.9.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [3.9.0] - 2026-05-22
+
+`worktree-manager` (`/mw`) gains a configurable merge strategy. The previous flow forced every consumer through `gh pr create` + `gh pr merge`; in repos where `develop` is not protected on GitHub, that roundtrip is unnecessary and was observed to stall (PR opened, never merged). The new `git.merge_strategy` key lets each project pick its lane.
+
+### Added
+
+- **`baldart.config.yml` → `git.merge_strategy`** — new top-level config section with one key (default `pr`):
+  - `pr` (default, backwards-compatible) — push feature branch, open PR via `gh pr create`, merge via `gh pr merge`. Required if `develop` is protected on origin.
+  - `local-push` — after the rebase in `/mw` step 4b, fast-forward push the feature branch directly to `origin/develop` (`git push origin <feat>:develop`). No PR, no `gh` dependency. Fails hard with a clear hint if `develop` is protected on origin.
+- **`framework/.claude/skills/worktree-manager/SKILL.md` step 4c** — fully rewritten into two clearly labelled strategies (A: `pr`, B: `local-push`) plus a shared local-develop-sync block. Both strategies remain strictly worktree-isolated — neither runs `git checkout` / `git switch` / `git branch` on the main repo.
+- **Programmatic API output** — `/mw` now returns `strategy: "pr"|"local-push"`. `prNumber` is `null` in `local-push` mode.
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — Phase 6 description and fail-safe rules reference the configured strategy instead of hard-coding `gh pr merge`.
+- **`worktree-manager` Project Context header** — added at the top of the skill, citing `git.merge_strategy` + `paths.backlog_dir` per the always-ask-never-assume contract in `framework/agents/project-context.md`.
+- **`src/commands/configure.js`** — gained autodetection + interactive prompt for `git.merge_strategy`. The probe runs `gh api repos/:o/:r/branches/develop/protection` to recommend `pr` (when develop is protected) or `local-push` (when not). Falls back to `pr` safely when `gh` is missing or the remote is unreachable. The detection reason is surfaced inline so the user knows *why* a strategy is recommended.
+- **`src/commands/update.js`** — schema-drift detection now also covers new top-level sections (currently `git.*`). When new keys are detected, `update` proactively offers to run `configure` instead of just warning. This means an existing consumer running `npx baldart update` will be **asked** about the new `git.merge_strategy` key, not silently defaulted.
+
+### Notes
+
+- No migration is required for existing consumers. `git.merge_strategy` defaults to `pr` when the key is absent, preserving the v3.4.0+ behaviour exactly.
+- On `npx baldart update`, existing consumers are **prompted** to run `configure`, where the merge-strategy autodetection probes their repo and recommends `pr` or `local-push` with a one-line reason. The user picks; nothing is auto-applied.
+- `develop` remains the only supported integration branch; configurable `base_branch` is out of scope for this release.
+
 ## [3.8.2] - 2026-05-22
 
 `baldart` (smart doctor) no longer double-confirms safe actions. Previously, running `baldart` with a remote-ahead state would ask *"Run: Pull N commit(s)?"* and then the `update` command would ask *"Proceed with update?"* immediately after — two prompts for the same intent.

package/VERSION

@@ -1 +1 @@
-3.8.2
+3.9.0

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

@@ -1176,7 +1176,7 @@ After the final review passes AND all cards are committed in the worktree, deleg
    - The worktree path and branch from the tracker
    - `checksAlreadyPassed: true` (final review + QA already validated the build)
    - All card IDs for the commit message
-3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto latest develop (step 4b — auto-resolves doc conflicts, stops on code conflicts), remote merge to develop via `gh pr merge` (step 4c — NEVER `git checkout develop` on the main repo; this respects the absolute terminal-isolation rule that many consumer projects declare in CLAUDE.md), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
+3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto latest develop (step 4b — auto-resolves doc conflicts, stops on code conflicts), merging into develop via the configured `git.merge_strategy` (step 4c — `pr` uses `gh pr merge`, `local-push` does a direct FF push to `origin/develop`; NEITHER runs `git checkout develop` on the main repo, respecting the absolute terminal-isolation rule), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
 4. **If code merge conflicts** → the skill STOPs and reports. Doc-only conflicts (ssot-registry.md, project-status.md, etc.) are auto-resolved by keeping both sides.
 5. **If post-merge build fails** → the skill STOPs and keeps the worktree intact for investigation.
 6. Record the merge commit hash and result in the tracker.
@@ -1245,8 +1245,8 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
 **Why this exists**: Agents frequently skip the DONE marking in Phase 4 (step 27) due to context compaction, commit failures that interrupt the flow, or team mode where Step D.6 gets lost. This gate is the safety net that catches ALL of these cases.
 
 ### Fail-safe rules (enforced by worktree-manager skill)
-- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use `gh pr merge` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
-- Never merge to `main` — only to `develop`, and only via `gh pr merge` (NOT local checkout).
+- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use the configured `git.merge_strategy` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
+- Never merge to `main` — only to `develop`, via the configured `git.merge_strategy` (NOT local checkout).
 - Never force push to `main` or `develop`. `--force-with-lease` on feature branches after rebase is allowed.
 - Never delete a branch before successful merge verification.
 - Never remove a worktree before confirming develop is stable post-merge.

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -14,6 +14,11 @@ description: >
 
 # Worktree Manager
 
+**Project Context (resolved from `baldart.config.yml`)**:
+- `git.merge_strategy` — `pr` (default, GitHub PR via `gh`) or `local-push` (direct fast-forward to `origin/develop`). Drives `/mw` step 4c.
+- `paths.backlog_dir` — used for syncing untracked backlog cards (`/nw` step 3b).
+- Protocol reference: `framework/agents/project-context.md`. Skills must ASK when a needed key is missing — never assume.
+
 **IMMEDIATE EXECUTION**: When invoked via `/nw`, `/mw`, `/lw`, or `/cw`, do NOT explain the process. Start executing the matching command flow immediately:
 
 - `/nw` → Ask for **slug** (required) and optionally a **card ID**, then execute all steps (pre-flight → create → install → build → report). If the user provided args, skip questions and use them directly. Supports three forms:
@@ -38,9 +43,13 @@ Output: `{ path: string, branch: string, port: number }`
 ### /mw programmatic
 
 Input: `{ worktreePath: string, checksAlreadyPassed?: boolean }`
-Output: `{ merged: boolean, developVerified: boolean, prNumber: number, mergeCommit: string }`
+Output: `{ merged: boolean, developVerified: boolean, prNumber: number|null, mergeCommit: string, strategy: "pr"|"local-push" }`
+
+The merge path depends on `git.merge_strategy` in `baldart.config.yml`:
+- `pr` (default, since v3.4.0): merge via `gh pr create` + `gh pr merge`. `prNumber` is the PR number, `mergeCommit` is the SHA returned by the GitHub merge API.
+- `local-push` (since v3.9.0): direct fast-forward push of the rebased feature branch to `origin/develop` — no PR, no `gh`. `prNumber` is `null`, `mergeCommit` is the local SHA of the feature branch tip.
 
-Note: since v3.4.0 the merge happens via `gh pr merge` against GitHub (NOT a local `git checkout develop` + `git merge`). `mergeCommit` is the SHA returned by the GitHub merge API. The orchestrator can use `prNumber` for follow-up (linking, deploy webhooks, etc.).
+Neither path runs `git checkout` / `git switch` / `git branch` on the main repo. The orchestrator can branch on `strategy` if it needs PR linking (only meaningful in `pr` mode).
 
 ### /cw programmatic
 
@@ -435,16 +444,32 @@ npm run build
 
 If build fails after rebase → STOP and report. The rebase introduced incompatibilities.
 
-### 4c. Remote merge via GitHub PR (NO main-repo checkout)
+### 4c. Land the feature branch onto develop (strategy-branched)
 
-**IMPORTANT — Remote merge only, NO local checkout/switch/branch on the main repo.** Consumer projects often share the main repo as a parallel resource across multiple terminals; running `git checkout develop` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. We therefore do the merge via the GitHub API (`gh pr create` + `gh pr merge`) — the main repo's `HEAD` is never touched.
+**IMPORTANT — NO local checkout/switch/branch on the main repo, regardless of strategy.** Consumer projects share the main repo as a parallel resource across multiple terminals; running `git checkout develop` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. Both strategies below operate from the worktree and the main repo's `HEAD` is never touched.
 
-The previous local-merge flow caused: (a) classifier-blocked `git checkout develop` in projects with terminal-isolation rules in CLAUDE.md, (b) silent failure of the orchestrator's merge phase.
+Read `git.merge_strategy` from `baldart.config.yml` (default: `pr`):
 
 ```bash
 MAIN=$(git -C "$WORKTREE_PATH" rev-parse --git-common-dir)/..
 MAIN=$(cd "$MAIN" && pwd)
 
+# Resolve strategy from baldart.config.yml (default: pr)
+STRATEGY=$(grep -A1 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
+  | grep 'merge_strategy:' | head -1 \
+  | sed -E 's/.*merge_strategy:[[:space:]]*([a-z-]+).*/\1/' || echo "pr")
+STRATEGY=${STRATEGY:-pr}
+```
+
+If neither `pr` nor `local-push` resolves, ASK the user once which to use and suggest persisting the choice (per the always-ask, never-assume contract in `framework/agents/project-context.md`).
+
+---
+
+#### Strategy A — `pr` (default, GitHub PR via `gh`)
+
+Use this when `develop` is protected on origin (required status checks, reviews, merge queue) — a direct push would be rejected.
+
+```bash
 # 1. Push the feature branch to origin (force-with-lease in case of rebase in 4b).
 git -C "$WORKTREE_PATH" push --force-with-lease origin "$BRANCH"
 
@@ -464,10 +489,6 @@ fi
 echo "PR #$PR_NUMBER ready to merge."
 
 # 3. Merge via gh CLI. --delete-branch removes the remote branch on success.
-#    The CLI may print a non-fatal warning if the LOCAL branch can't be deleted
-#    (e.g. "fatal: 'develop' is already used by worktree at ..." when develop is
-#    checked out in another worktree). The REMOTE merge happens regardless — we
-#    swallow the local-cleanup warning.
 MERGE_OUTPUT=$(gh pr merge "$PR_NUMBER" --merge --delete-branch 2>&1) || MERGE_RC=$?
 echo "$MERGE_OUTPUT"
 
@@ -488,11 +509,63 @@ if [ "$PR_STATE" != "MERGED" ]; then
   exit 1
 fi
 echo "✅ PR #$PR_NUMBER merged to develop."
+```
+
+If `gh` is not installed in the project, STOP and ask the user to install GitHub CLI (`brew install gh` or equivalent) and run `gh auth login`. Do NOT fall back to a local checkout — it violates terminal isolation.
+
+If both gh CLI and REST API merge fail → STOP and report. Suggest switching to `merge_strategy: local-push` only if `develop` is NOT protected on origin.
+
+---
+
+#### Strategy B — `local-push` (direct FF push, no PR)
+
+Use this when `develop` is NOT protected on origin and the user wants to skip the GitHub PR roundtrip. After step 4b the feature branch is rebased onto `origin/develop`, so it can fast-forward `develop` on origin in a single push.
+
+```bash
+# 1. Sanity: confirm the feature branch is strictly ahead of origin/develop
+#    (i.e. the rebase in step 4b succeeded and we can FF develop on origin).
+git -C "$WORKTREE_PATH" fetch origin develop --quiet
+AHEAD=$(git -C "$WORKTREE_PATH" rev-list --count "origin/develop..$BRANCH")
+BEHIND=$(git -C "$WORKTREE_PATH" rev-list --count "$BRANCH..origin/develop")
+if [ "$BEHIND" -ne 0 ]; then
+  echo "❌ local-push aborted: $BRANCH is $BEHIND commit(s) behind origin/develop." >&2
+  echo "   Re-run step 4b (rebase onto origin/develop), then retry." >&2
+  exit 1
+fi
+if [ "$AHEAD" -eq 0 ]; then
+  echo "ℹ️ Nothing to push — $BRANCH is identical to origin/develop. Skipping."
+else
+  echo "Fast-forwarding origin/develop by $AHEAD commit(s) via local-push…"
+fi
+
+# 2. Direct fast-forward push to develop on origin. No PR.
+#    If develop is protected on origin, this fails — surface the hint and stop.
+if ! PUSH_OUTPUT=$(git -C "$WORKTREE_PATH" push origin "$BRANCH:develop" 2>&1); then
+  echo "$PUSH_OUTPUT"
+  if echo "$PUSH_OUTPUT" | grep -qiE "protected branch|required status|review required"; then
+    echo "❌ local-push rejected: 'develop' is protected on origin." >&2
+    echo "   Switch baldart.config.yml → git.merge_strategy: pr, or remove the protection." >&2
+  fi
+  exit 1
+fi
+echo "✅ $BRANCH merged into develop on origin (fast-forward, no PR)."
 
-# 4. Sync local develop ONLY if the main repo's HEAD is already develop.
-#    NEVER `git checkout develop` here — that's the regression we're fixing.
-#    If the user (or another terminal) had develop checked out, ff-only updates
-#    it cleanly. Otherwise we leave their HEAD alone and they'll pull next time.
+# 3. Delete the remote feature branch (best-effort — never fatal).
+git -C "$WORKTREE_PATH" push origin --delete "$BRANCH" 2>/dev/null || true
+
+MERGE_SHA=$(git -C "$WORKTREE_PATH" rev-parse HEAD)
+PR_NUMBER=""
+```
+
+---
+
+#### Common — sync local develop ref (both strategies)
+
+```bash
+# Sync local develop ONLY if the main repo's HEAD is already develop.
+# NEVER `git checkout develop` here. If the user (or another terminal) had
+# develop checked out, ff-only updates it cleanly. Otherwise we leave their
+# HEAD alone and they'll pull next time.
 CURRENT_BRANCH=$(git -C "$MAIN" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
 if [ "$CURRENT_BRANCH" = "develop" ]; then
   git -C "$MAIN" pull --ff-only origin develop || \
@@ -503,10 +576,6 @@ else
 fi
 ```
 
-If `gh` is not installed in the project, STOP and ask the user to install GitHub CLI (`brew install gh` or equivalent) and run `gh auth login`. Do NOT fall back to the legacy local-checkout flow — it violates terminal isolation in worktree-driven projects.
-
-If both gh CLI and REST API merge fail → STOP and report. Do NOT attempt a local checkout as fallback.
-
 ### 5. Post-merge verification
 
 ```bash
@@ -554,7 +623,9 @@ Remove the entry from `.worktrees/registry.json`.
 Merge complete:
   Card:     <CARD-ID>
   Branch:   <BRANCH> (deleted on remote; local-cleanup may have skipped if checked out elsewhere)
-  PR:       #<PR_NUMBER> merged via `gh pr merge`
+  Strategy: <pr | local-push>
+  PR:       #<PR_NUMBER> merged via `gh pr merge`    ← only in `pr` strategy
+  Push:     fast-forward to origin/develop           ← only in `local-push` strategy
   Worktree: <WORKTREE_PATH> (removed)
   develop:  remote up to date; local main-repo synced only if HEAD was already develop
 ```
@@ -665,8 +736,8 @@ Cleanup complete:
 
 ## Safety Rules
 
-- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects (e.g. mayo) declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use `gh pr create` + `gh pr merge` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
-- NEVER merge to `main` — only to `develop`, and only via `gh pr merge` (NOT local checkout).
+- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use the configured `git.merge_strategy` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
+- NEVER merge to `main` — only to `develop`, via the configured `git.merge_strategy` (`pr` → `gh pr merge`; `local-push` → `git push origin <feat>:develop`). NEVER via local checkout.
 - NEVER force push from a worktree (`--force-with-lease` on the feature branch after rebase is the only allowed force variant).
 - NEVER `git add .` or `git add -A` — always explicit file names.
 - NEVER remove a worktree with uncommitted changes without explicit user confirmation.

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

@@ -112,6 +112,26 @@ features:
   # LLM-wiki overlay (paths.wiki_dir + capture/wiki-curator loop).
   has_wiki_overlay: false
 
+# ─── GIT ─────────────────────────────────────────────────────────────────
+# Controls how worktree-manager (`/mw`) integrates a worktree's feature
+# branch back into `develop`.
+git:
+  # How `/mw` lands the feature branch onto develop:
+  #
+  #   pr          (default) — push feature branch, open a PR via `gh pr create`,
+  #                 merge via `gh pr merge`. Required if `develop` is protected
+  #                 on origin (status checks, required reviews, merge queue).
+  #
+  #   local-push  — after rebasing the feature branch onto `origin/develop`,
+  #                 fast-forward push the feature branch directly to
+  #                 `origin/develop` (`git push origin <feat>:develop`).
+  #                 No PR, no `gh` dependency. FAILS hard if `develop` is
+  #                 protected on origin — switch back to `pr` in that case.
+  #
+  # Neither strategy ever touches the main repo's HEAD — both flows are
+  # worktree-isolated and respect the terminal-isolation rule.
+  merge_strategy: pr
+
 # ─── 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": "3.8.2",
+  "version": "3.9.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

@@ -26,6 +26,48 @@ const IGNORED_DIRS = new Set([
   '.expo', '.parcel-cache', 'tmp', '.idea', '.vscode', '.DS_Store'
 ]);
 
+/**
+ * Probe origin/develop branch protection to recommend a merge strategy.
+ * Returns: { value, protected, reason }
+ *   - 'pr'         when develop is protected (PR is the only viable path)
+ *   - 'local-push' when develop is NOT protected (FF push is faster, no gh needed)
+ *   - 'pr' as a safe default if we can't tell (gh missing, network down, no remote)
+ *
+ * Non-fatal: any failure returns `{ value: 'pr', protected: null }` so configure
+ * keeps moving. The user can override in the interactive prompt.
+ */
+function detectMergeStrategy(cwd = process.cwd()) {
+  try {
+    const { execSync } = require('child_process');
+    const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
+    // Need both git + gh. If either is absent or unauthenticated, default 'pr'.
+    try { execSync('gh --version', opts); } catch (_) {
+      return { value: 'pr', protected: null, reason: 'gh CLI not installed — defaulting to pr.' };
+    }
+    let nameWithOwner = '';
+    try {
+      nameWithOwner = execSync('gh repo view --json nameWithOwner -q .nameWithOwner', opts).trim();
+    } catch (_) {
+      return { value: 'pr', protected: null, reason: 'no GitHub remote detected — defaulting to pr.' };
+    }
+    // Probe branch protection. 404 means "not protected" → local-push viable.
+    try {
+      execSync(`gh api repos/${nameWithOwner}/branches/develop/protection`, opts);
+      return { value: 'pr', protected: true, reason: 'develop is protected on origin — PR strategy required.' };
+    } catch (_) {
+      // Could be 404 (not protected) OR branch doesn't exist. Check existence:
+      try {
+        execSync(`gh api repos/${nameWithOwner}/branches/develop -q .name`, opts);
+        return { value: 'local-push', protected: false, reason: 'develop exists on origin and is not protected — local-push viable.' };
+      } catch (_) {
+        return { value: 'pr', protected: null, reason: 'develop branch not found on origin — defaulting to pr.' };
+      }
+    }
+  } catch (_) {
+    return { value: 'pr', protected: null, reason: 'probe failed — defaulting to pr.' };
+  }
+}
+
 function detect(cwd = process.cwd()) {
   const exists = (p) => fs.existsSync(path.join(cwd, p));
   const findFirst = (...candidates) => candidates.find(exists) || '';
@@ -238,6 +280,8 @@ function detect(cwd = process.cwd()) {
     : (exists('cypress.config.ts') || exists('cypress.config.js') || hasDep('cypress')) ? 'cypress'
     : '';
 
+  const mergeStrategyProbe = detectMergeStrategy(cwd);
+
   const detected = {
     paths: {
       design_system: designSystemPath,
@@ -302,6 +346,16 @@ function detect(cwd = process.cwd()) {
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
     },
+    git: {
+      // Set to a plain string — the structured probe details (`protected`,
+      // `reason`) are kept on a sibling key so mergePreserving stays type-safe.
+      merge_strategy: mergeStrategyProbe.value,
+    },
+    _probes: {
+      // Internal scratchpad — never serialized to YAML. Used by
+      // interactivePrompts to surface the autodetection reasoning.
+      merge_strategy: mergeStrategyProbe,
+    },
   };
 
   // Reference walkFirst once so the dead-code linter is happy and the helper
@@ -424,6 +478,25 @@ async function interactivePrompts(merged, detected) {
   }
   merged.tools.enabled = currentEnabled;
 
+  // ---- Git merge strategy (since v3.9.0) --------------------------------
+  UI.section('Git merge strategy (how `/mw` lands feature branches onto develop)');
+  merged.git = merged.git || {};
+  const probe = (detected._probes && detected._probes.merge_strategy)
+    || { value: 'pr', protected: null };
+  if (probe.reason) UI.info(probe.reason);
+  const currentMerge = merged.git.merge_strategy || probe.value || 'pr';
+  const chosenMerge = await UI.select(
+    `Choose merge strategy (current: ${currentMerge})`,
+    [
+      { name: 'pr — open a GitHub PR, merge via `gh pr merge` (required if develop is protected)', value: 'pr' },
+      { name: 'local-push — direct FF push to origin/develop (no PR, no `gh` dependency)', value: 'local-push' },
+    ]
+  );
+  merged.git.merge_strategy = chosenMerge;
+  if (chosenMerge === 'local-push' && probe.protected === true) {
+    UI.warning('You picked `local-push` but develop appears protected on origin — pushes will be rejected. Switch back to `pr` if it fails.');
+  }
+
   UI.section('Features (explicit yes/no — option A: always ask)');
   for (const flag of [
     ['has_design_system', 'Project has a documented design system?'],
@@ -535,7 +608,9 @@ function serialize(config) {
 # NOTE: features.* flags MUST be explicit (true | false). Any flag absent
 # from this file will prompt the user on first skill invocation.
 `;
-  return header + yaml.dump(stripNullFeatures(config), { lineWidth: 100, noRefs: true });
+  const clean = stripNullFeatures(config);
+  if (clean && clean._probes) delete clean._probes;
+  return header + yaml.dump(clean, { lineWidth: 100, noRefs: true });
 }
 
 async function configure(opts = {}) {

package/src/commands/update.js

@@ -413,12 +413,21 @@ async function update(options = {}) {
               .filter((k) => !(k in (cur2.features || {})));
             const missingPaths = Object.keys(tpl.paths || {})
               .filter((k) => !(k in (cur2.paths || {})));
-            if (missingFeatures.length || missingPaths.length) {
+            const missingGit = Object.keys(tpl.git || {})
+              .filter((k) => !(k in (cur2.git || {})));
+            const allMissing = [...missingPaths, ...missingFeatures, ...missingGit.map((k) => `git.${k}`)];
+            if (allMissing.length) {
               UI.newline();
-              UI.warning(
-                `New config keys in this version: ${[...missingPaths, ...missingFeatures].join(', ')}. ` +
-                'Re-run `npx baldart configure` to populate them (existing values are preserved).'
-              );
+              UI.warning(`New config keys in this version: ${allMissing.join(', ')}.`);
+              // Auto-offer configure so the user actually answers, instead of
+              // silently falling back to template defaults on first use.
+              const runConfigure = await UI.confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
+              if (runConfigure) {
+                const configureCmd = require('./configure');
+                await configureCmd();
+              } else {
+                UI.info('Skipped. Skills will prompt for the missing keys on first use.');
+              }
             }
           } catch (_) {
             // Non-fatal — schema drift detection is best-effort.